dpp::utility Namespace Reference

Utility helper functions, generally for logging, running programs, time/date manipulation, etc. More...

Classes
struct	iconhash
	Store a 128 bit icon hash (profile picture, server icon etc) as a 128 bit binary value made of two uint64_t. Has a constructor to build one from a string, and a method to fetch the value back in string form. More...
struct	uptime
	A class used to represent an uptime in hours, minutes, seconds and days, with helper functions to convert from time_t and display as a string. More...

Typedefs
typedef std::function< void(const std::string &output)>	cmd_result_t
	Callback for the results of a command executed via dpp::utility::exec. More...

Enumerations
enum	time_format : uint8_t {   tf_long_date = 'D' , tf_long_datetime = 'F' , tf_relative_time = 'R' , tf_long_time = 'T' ,   tf_short_date = 'd' , tf_short_datetime = 'f' , tf_short_time = 't' }
	Timestamp formats for dpp::utility::timestamp() More...

Functions
std::string DPP_EXPORT	avatar_size (uint32_t size)
	Return the url parameter for an avatar size, or empty if the size is 0. More...
std::string DPP_EXPORT	bot_invite_url (const snowflake bot_id, const uint64_t permissions=0, const std::vector< std::string > &scopes={"bot", "applications.commands"})
	Create a bot invite. More...
std::string DPP_EXPORT	bytes (uint64_t c)
	Convert a byte count to display value. More...
std::function< void(const dpp::log_t &)> DPP_EXPORT	cout_logger ()
	Get a default logger that outputs to std::cout. e.g. More...
std::string DPP_EXPORT	current_date_time ()
	Returns current date and time. More...
std::string DPP_EXPORT	debug_dump (uint8_t *data, size_t length)
	Output hex values of a section of memory for debugging. More...
void DPP_EXPORT	exec (const std::string &cmd, std::vector< std::string > parameters={}, cmd_result_t callback={})
	Run a commandline program asynchronously. The command line program is spawned in a separate std::thread, and when complete, its output from stdout is passed to the callback function in its string parameter. For example. More...
bool DPP_EXPORT	has_voice ()
	Returns true if D++ was built with voice support. More...
std::function< void(const dpp::confirmation_callback_t &detail)> DPP_EXPORT	log_error ()
	The default callback handler for API calls. on error, sends the error to the logger. More...
std::string DPP_EXPORT	loglevel (dpp::loglevel in)
	Convert a dpp::loglevel enum value to a string. More...
std::string DPP_EXPORT	make_url_parameters (const std::map< std::string, std::string > &parameters)
	Build a URL parameter string e.g. "?a=b&c=d&e=f" from a map of key/value pairs. Entries with empty key names or values are omitted. More...
std::string DPP_EXPORT	make_url_parameters (const std::map< std::string, uint64_t > &parameters)
	Build a URL parameter string e.g. "?a=b&c=d&e=f" from a map of key/value pairs. Entries with empty key names or zero values are omitted. More...
std::string DPP_EXPORT	markdown_escape (const std::string &text, bool escape_code_blocks=false)
	Escapes Discord's markdown sequences in a string. More...
std::string DPP_EXPORT	read_file (const std::string &filename)
	Read a whole file into a std::string. Be sure you have enough memory to read the file, if you are reading a large file. More...
uint32_t DPP_EXPORT	rgb (float red, float green, float blue)
	Convert floats to RGB for sending in embeds. More...
uint32_t DPP_EXPORT	rgb (int red, int green, int blue)
	Convert ints to RGB for sending in embeds. More...
void DPP_EXPORT	set_thread_name (const std::string &name)
	Set the name of the current thread for debugging and statistical reporting. More...
std::string DPP_EXPORT	slashcommand_mention (snowflake command_id, const std::string &command_name, const std::string &subcommand="")
	Create a mentionable slashcommand (used in a message). More...
std::string DPP_EXPORT	slashcommand_mention (snowflake command_id, const std::string &command_name, const std::string &subcommand_group, const std::string &subcommand)
	Create a mentionable slashcommand (used in a message). More...
double DPP_EXPORT	time_f ()
	Return the current time with fractions of seconds. This is a unix epoch time with the fractional seconds part after the decimal place. More...
std::string DPP_EXPORT	timestamp (time_t ts, time_format tf=tf_short_datetime)
	Return a mentionable timestamp (used in a message). These timestamps will display the given timestamp in the user's timezone and locale. More...
std::vector< std::string > DPP_EXPORT	tokenize (std::string const &in, const char *sep="\r\n")
	Split (tokenize) a string into a vector, using the given separators. More...
std::string DPP_EXPORT	url_encode (const std::string &value)
	Encodes a url parameter similar to php urlencode() More...
size_t DPP_EXPORT	utf8len (const std::string &str)
	Returns the length of a UTF-8 string in codepoints. More...
std::string DPP_EXPORT	utf8substr (const std::string &str, std::string::size_type start, std::string::size_type length)
	Return substring of a UTF-8 encoded string in codepoints. More...
std::string DPP_EXPORT	validate (const std::string &value, size_t _min, size_t _max, const std::string &exception_message)
	Validate a string value In the event the length of the string is less than _min, then an exception of type dpp:length_exception will be thrown. If the string is longer than _max UTF8 codepoints it will be truncated to fit. More...
std::string DPP_EXPORT	version ()
	Returns the library's version string. More...

Variables
const std::string	cdn_host = "https://cdn.discordapp.com"
	The base URL for CDN content such as profile pictures and guild icons. More...

Detailed Description

Utility helper functions, generally for logging, running programs, time/date manipulation, etc.

Typedef Documentation

cmd_result_t

typedef std::function<void(const std::string& output)> dpp::utility::cmd_result_t

Callback for the results of a command executed via dpp::utility::exec.

Enumeration Type Documentation

time_format

enum dpp::utility::time_format : uint8_t

Timestamp formats for dpp::utility::timestamp()

Note

These values are the actual character values specified by the Discord API and should not be changed unless the Discord API changes the specification! They have been sorted into numerical order of their ASCII value to keep C++ happy.

Enumerator
tf_long_date	"20 April 2021" - Long Date
tf_long_datetime	"Tuesday, 20 April 2021 16:20" - Long Date/Time
tf_relative_time	"2 months ago" - Relative Time
tf_long_time	"16:20:30" - Long Time
tf_short_date	"20/04/2021" - Short Date
tf_short_datetime	"20 April 2021 16:20" - Short Date/Time
tf_short_time	"16:20" - Short Time

Function Documentation

avatar_size()

std::string DPP_EXPORT dpp::utility::avatar_size

(

uint32_t

size

)

Return the url parameter for an avatar size, or empty if the size is 0.

Parameters

size	size to generate url parameter for

Returns

std::string url parameter

bot_invite_url()

std::string DPP_EXPORT dpp::utility::bot_invite_url	(	const snowflake	bot_id,
		const uint64_t	permissions = 0,
		const std::vector< std::string > &	scopes = {"bot", "applications.commands"}
	)

Create a bot invite.

Parameters

bot_id	Bot ID
permissions	Permission bitmask of the bot to invite
scopes	Scopes to use

Returns

Invite URL

bytes()

std::string DPP_EXPORT dpp::utility::bytes

(

uint64_t

c

)

Convert a byte count to display value.

Parameters

c	number of bytes

Returns

std::string display value suffixed with M, G, T where necessary

cout_logger()

std::function< void(const dpp::log_t &)> DPP_EXPORT dpp::utility::cout_logger

(

)

Get a default logger that outputs to std::cout. e.g.

bot.on_log(dpp::utility::cout_logger());

Returns

A logger for attaching to on_log

current_date_time()

std::string DPP_EXPORT dpp::utility::current_date_time

(

)

Returns current date and time.

Returns

std::string Current date and time in "Y-m-d H:M:S" format

debug_dump()

std::string DPP_EXPORT dpp::utility::debug_dump	(	uint8_t *	data,
		size_t	length
	)

Output hex values of a section of memory for debugging.

Parameters

data	The start of the data to display
length	The length of data to display

exec()

void DPP_EXPORT dpp::utility::exec	(	const std::string &	cmd,
		std::vector< std::string >	parameters = {},
		cmd_result_t	callback = {}
	)

Run a commandline program asynchronously. The command line program is spawned in a separate std::thread, and when complete, its output from stdout is passed to the callback function in its string parameter. For example.

dpp::utility::exec("/bin/ls", {"-al"}, [](const std::string& output) {
    std::cout << "Output of 'ls -al': " << output << "\n";
});

Parameters

cmd	The command to run.
parameters	Command line parameters. Each will be escaped using std::quoted.
callback	The callback to call on completion.

has_voice()

bool DPP_EXPORT dpp::utility::has_voice

(

)

Returns true if D++ was built with voice support.

Returns

bool True if voice support is compiled in (libsodium/libopus)

log_error()

std::function< void(const dpp::confirmation_callback_t &detail)> DPP_EXPORT dpp::utility::log_error

(

)

The default callback handler for API calls. on error, sends the error to the logger.

Returns

A lambda for attaching to an API callback

loglevel()

std::string DPP_EXPORT dpp::utility::loglevel

(

dpp::loglevel

in

)

Convert a dpp::loglevel enum value to a string.

Parameters

in	log level to convert

Returns

std::string string form of log level

make_url_parameters() [1/2]

std::string DPP_EXPORT dpp::utility::make_url_parameters

(

const std::map< std::string, std::string > &

parameters

)

Build a URL parameter string e.g. "?a=b&c=d&e=f" from a map of key/value pairs. Entries with empty key names or values are omitted.

Parameters

parameters

parameters to create a url query string for

Returns

std::string A correctly encoded url query string

make_url_parameters() [2/2]

std::string DPP_EXPORT dpp::utility::make_url_parameters

(

const std::map< std::string, uint64_t > &

parameters

)

Build a URL parameter string e.g. "?a=b&c=d&e=f" from a map of key/value pairs. Entries with empty key names or zero values are omitted.

Parameters

parameters

parameters to create a url query string for

Returns

std::string A correctly encoded url query string

markdown_escape()

std::string DPP_EXPORT dpp::utility::markdown_escape	(	const std::string &	text,
		bool	escape_code_blocks = false
	)

Escapes Discord's markdown sequences in a string.

Parameters

text	Text to escape
escape_code_blocks	If set to false, then code blocks are not escaped. This means that you can still use a code block, and the text within will be left as-is. If set to true, code blocks will also be escaped so that ` symbol may be used as a normal character.

Returns

std::string The text with the markdown special characters escaped with a backslash

read_file()

std::string DPP_EXPORT dpp::utility::read_file

(

const std::string &

filename

)

Read a whole file into a std::string. Be sure you have enough memory to read the file, if you are reading a large file.

Note

Be aware this function can block! If you are regularly reading large files, consider caching them.

Parameters

filename

The path to the file to read

Returns

std::string The file contents

Exceptions

dpp::exception

on failure to read the entire file

rgb() [1/2]

uint32_t DPP_EXPORT dpp::utility::rgb	(	float	red,
		float	green,
		float	blue
	)

Convert floats to RGB for sending in embeds.

Parameters

red	red value, between 0 and 1 inclusive
green	green value, between 0 and 1 inclusive
blue	blue value, between 0 and 1 inclusive

Returns

uint32_t returned integer colour value

rgb() [2/2]

uint32_t DPP_EXPORT dpp::utility::rgb	(	int	red,
		int	green,
		int	blue
	)

Convert ints to RGB for sending in embeds.

Parameters

red	red value, between 0 and 255 inclusive
green	green value, between 0 and 255 inclusive
blue	blue value, between 0 and 255 inclusive

Returns

uint32_t returned integer colour value

set_thread_name()

void DPP_EXPORT dpp::utility::set_thread_name

(

const std::string &

name

)

Set the name of the current thread for debugging and statistical reporting.

Parameters

name	New name to set

slashcommand_mention() [1/2]

std::string DPP_EXPORT dpp::utility::slashcommand_mention	(	snowflake	command_id,
		const std::string &	command_name,
		const std::string &	subcommand = ""
	)

Create a mentionable slashcommand (used in a message).

Parameters

command_id	The ID of the slashcommand
command_name	The command name
subcommand	Optional: The subcommand name (for mentioning a subcommand)

Returns

std::string The formatted mention

slashcommand_mention() [2/2]

std::string DPP_EXPORT dpp::utility::slashcommand_mention	(	snowflake	command_id,
		const std::string &	command_name,
		const std::string &	subcommand_group,
		const std::string &	subcommand
	)

Create a mentionable slashcommand (used in a message).

Parameters

command_id	The ID of the slashcommand
command_name	The command name
subcommand_group	The subcommand group name
subcommand	The subcommand name

Returns

std::string The formatted mention of the slashcommand with its subcommand

time_f()

double DPP_EXPORT dpp::utility::time_f

(

)

Return the current time with fractions of seconds. This is a unix epoch time with the fractional seconds part after the decimal place.

Returns

double time with fractional seconds

timestamp()

std::string DPP_EXPORT dpp::utility::timestamp	(	time_t	ts,
		time_format	tf = tf_short_datetime
	)

Return a mentionable timestamp (used in a message). These timestamps will display the given timestamp in the user's timezone and locale.

Parameters

ts	Time stamp to convert
tf	Format of timestamp using dpp::utility::time_format

Returns

std::string The formatted timestamp

tokenize()

std::vector< std::string > DPP_EXPORT dpp::utility::tokenize	(	std::string const &	in,
		const char *	sep = "\r\n"
	)

Split (tokenize) a string into a vector, using the given separators.

Parameters

in	Input string
sep	Separator characters

Returns

std::vector<std::string> Tokenized strings

url_encode()

std::string DPP_EXPORT dpp::utility::url_encode

(

const std::string &

value

)

Encodes a url parameter similar to php urlencode()

Parameters

value

String to encode

Returns

std::string URL encoded string

utf8len()

size_t DPP_EXPORT dpp::utility::utf8len

(

const std::string &

str

)

Returns the length of a UTF-8 string in codepoints.

Parameters

str	string to count length of

Returns

size_t length of string (0 for invalid utf8)

utf8substr()

std::string DPP_EXPORT dpp::utility::utf8substr	(	const std::string &	str,
		std::string::size_type	start,
		std::string::size_type	length
	)

Return substring of a UTF-8 encoded string in codepoints.

Parameters

str	string to return substring from
start	start codepoint offset
length	length in codepoints

Returns

std::string Substring in UTF-8 or empty string if invalid UTF-8 passed in

validate()

std::string DPP_EXPORT dpp::utility::validate	(	const std::string &	value,
		size_t	_min,
		size_t	_max,
		const std::string &	exception_message
	)

Validate a string value In the event the length of the string is less than _min, then an exception of type dpp:length_exception will be thrown. If the string is longer than _max UTF8 codepoints it will be truncated to fit.

Parameters

value	The value to validate
_min	Minimum length
_max	Maximum length
exception_message	Exception message to throw if value length < _min

Returns

std::string Validated string, truncated if necessary.

Exceptions

dpp::length_exception

if value UTF8 length < _min

version()

std::string DPP_EXPORT dpp::utility::version

(

)

Returns the library's version string.

Returns

std::string version

Variable Documentation

cdn_host

const std::string dpp::utility::cdn_host = "https://cdn.discordapp.com"

The base URL for CDN content such as profile pictures and guild icons.