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::function< void(const dpp::log_t &)> DPP_EXPORT	cout_logger ()
	Get a default logger that outputs to std::cout. e.g. 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...

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...

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::string DPP_EXPORT	current_date_time ()
	Returns current date and time. More...

std::string DPP_EXPORT	loglevel (dpp::loglevel in)
	Convert a dpp::loglevel enum value to a string. 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...

bool DPP_EXPORT	has_voice ()
	Returns true if D++ was built with voice support. More...

std::string DPP_EXPORT	bytes (uint64_t c)
	Convert a byte count to display value. More...

uint32_t DPP_EXPORT	rgb (double red, double green, double blue)
	Convert doubles 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...

uint32_t DPP_EXPORT	cmyk (double c, double m, double y, double k)
	Convert doubles to CMYK for sending in embeds. More...

uint32_t DPP_EXPORT	cmyk (int c, int m, int y, int k)
	Convert ints to CMYK for sending in embeds. More...

std::string DPP_EXPORT	debug_dump (uint8_t *data, size_t length)
	Output hex values of a section of memory for debugging. 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	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...

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	avatar_size (uint32_t size)
	Get the url query parameter for the cdn endpoint. Internally used to build url getters. 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	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	markdown_escape (const std::string &text, bool escape_code_blocks=false)
	Escapes Discord's markdown sequences in a string. More...

std::string DPP_EXPORT	url_encode (const std::string &value)
	Encodes a url parameter similar to php urlencode() 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...

std::string DPP_EXPORT	user_mention (const snowflake &id)
	Create a mentionable user. More...

std::string DPP_EXPORT	channel_mention (const snowflake &id)
	Create a mentionable channel. More...

std::string DPP_EXPORT	emoji_mention (const std::string &name, const snowflake &id, bool is_animated=false)
	Create a mentionable emoji. More...

std::string DPP_EXPORT	role_mention (const snowflake &id)
	Create a mentionable role. More...

std::string DPP_EXPORT	version ()
	Returns the library's version 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...

void DPP_EXPORT	set_thread_name (const std::string &name)
	Set the name of the current thread for debugging and statistical reporting. 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 )

Get the url query parameter for the cdn endpoint. Internally used to build url getters.

Parameters

size	size to generate url parameter for. Must be any power of two between 16 and 4096 (inclusive) or it'll return an empty string.

Returns: std::string url query parameter e.g. ?size=128, or an empty string

◆ 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

◆ channel_mention()

std::string DPP_EXPORT dpp::utility::channel_mention ( const snowflake & id )

Create a mentionable channel.

Parameters

id	The ID of the channel.

Returns: std::string The formatted mention of the channel.

◆ cmyk() [1/2]

uint32_t DPP_EXPORT dpp::utility::cmyk	(	double	c,
		double	m,
		double	y,
		double	k
	)

Convert doubles to CMYK for sending in embeds.

Parameters

c	cyan value, between 0 and 1 inclusive
m	magenta value, between 0 and 1 inclusive
y	yellow value, between 0 and 1 inclusive
k	key (black) value, between 0 and 1 inclusive

Returns: uint32_t returned integer colour value

◆ cmyk() [2/2]

uint32_t DPP_EXPORT dpp::utility::cmyk	(	int	c,
		int	m,
		int	y,
		int	k
	)

Convert ints to CMYK for sending in embeds.

Parameters

c	cyan value, between 0 and 255 inclusive
m	magenta value, between 0 and 255 inclusive
y	yellow value, between 0 and 255 inclusive
k	key (black) value, between 0 and 255 inclusive

Returns: uint32_t returned integer colour value

◆ 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());

dpp::utility::cout_logger

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

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

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

◆ emoji_mention()

std::string DPP_EXPORT dpp::utility::emoji_mention	(	const std::string &	name,
		const snowflake &	id,
		bool	is_animated = `false`
	)

Create a mentionable emoji.

Parameters

name	The name of the emoji.
id	The ID of the emoji.
is_animated	is emoji animated.

Returns: std::string The formatted mention of the emoji.

◆ 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	(	double	red,
		double	green,
		double	blue
	)

Convert doubles 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

◆ role_mention()

std::string DPP_EXPORT dpp::utility::role_mention ( const snowflake & id )

Create a mentionable role.

Parameters

id	The ID of the role.

Returns: std::string The formatted mention of the role.

◆ 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

◆ user_mention()

std::string DPP_EXPORT dpp::utility::user_mention ( const snowflake & id )

Create a mentionable user.

Parameters

id	The ID of the user.

Returns: std::string The formatted mention of the user.

◆ 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.

Classes

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ cmd_result_t

Enumeration Type Documentation

◆ time_format

Function Documentation

◆ avatar_size()

◆ bot_invite_url()

◆ bytes()

◆ channel_mention()

◆ cmyk() [1/2]

◆ cmyk() [2/2]

◆ cout_logger()

◆ current_date_time()

◆ debug_dump()

◆ emoji_mention()

◆ exec()

◆ has_voice()

◆ log_error()

◆ loglevel()

◆ make_url_parameters() [1/2]

◆ make_url_parameters() [2/2]

◆ markdown_escape()

◆ read_file()

◆ rgb() [1/2]

◆ rgb() [2/2]

◆ role_mention()

◆ set_thread_name()

◆ slashcommand_mention() [1/2]

◆ slashcommand_mention() [2/2]

◆ time_f()

◆ timestamp()

◆ tokenize()

◆ url_encode()

◆ user_mention()

◆ utf8len()

◆ utf8substr()

◆ validate()

◆ version()

Variable Documentation

◆ cdn_host