dpp::utility Namespace Reference

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

Classes
struct	dummy
	Utility struct that has the same size and alignment as another but does nothing. Useful for ABI compatibility. More...
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...
enum	guild_navigation_type { gnt_customize , gnt_browse , gnt_guide }
	Guild navigation types for dpp::utility::guild_navigation() 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...
std::string DPP_EXPORT	cdn_endpoint_url (const std::vector< image_type > &allowed_formats, const std::string &path_without_extension, const dpp::image_type format, uint16_t size, bool prefer_animated=false, bool is_animated=false)
std::string DPP_EXPORT	cdn_endpoint_url_hash (const std::vector< image_type > &allowed_formats, const std::string &path_without_extension, const std::string &hash, const dpp::image_type format, uint16_t size, bool prefer_animated=false, bool is_animated=false)
std::string DPP_EXPORT	cdn_endpoint_url_sticker (snowflake sticker_id, sticker_format format)
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	guild_navigation (const snowflake guild_id, guild_navigation_type gnt)
	Create a mentionable guild navigation (used in a message). 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...
bool DPP_EXPORT	is_coro_enabled ()
	Returns true if D++ was built with coroutine 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 (std::string_view name, 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	mime_type (image_type type)
	Get the mime type for an image type. More...
std::string DPP_EXPORT	mime_type (sticker_format format)
	Get the mime type for a sticker format. More...
std::string DPP_EXPORT	file_extension (image_type type)
	Get the file extension for an image type. More...
std::string DPP_EXPORT	file_extension (sticker_format format)
	Get the file extension for a sticker format. 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...
template<typename F , typename R , typename... Args>
constexpr bool	callable_returns_v = std::is_convertible_v<std::invoke_result_t<F, Args...>, R>
	Type trait to check if a callable F can be called using the arguments Args, and that its return value is convertible to R. 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

guild_navigation_type

enum dpp::utility::guild_navigation_type

Guild navigation types for dpp::utility::guild_navigation()

Enumerator
gnt_customize	Customize tab with the server's dpp::onboarding_prompt
gnt_browse	Browse Channels tab
gnt_guide	Server Guide.

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

cdn_endpoint_url()

std::string DPP_EXPORT dpp::utility::cdn_endpoint_url	(	const std::vector< image_type > &	allowed_formats,
		const std::string &	path_without_extension,
		const dpp::image_type	format,
		uint16_t	size,
		bool	prefer_animated = false,
		bool	is_animated = false
	)

For internal use only. Helper function to easily create discord's cdn endpoint urls

See also

https://discord.com/developers/docs/reference#image-formatting-cdn-endpoints

Parameters

allowed_formats	A vector of supported formats for the endpoint from the discord docs
path_without_extension	The path for the endpoint (without the extension e.g. .png)
format	the wished format to return. Must be one of the formats passed in allowed_formats, otherwise it returns an empty string
size	the image size which will be appended as a querystring to the url. It must be any power of two between 16 and 4096, otherwise no querystring will be appended (discord then returns the image as their default size)
prefer_animated	Whether the user prefers gif format. If true, it'll return gif format whenever the image is available as animated. In this case, the format-parameter is only used for non-animated images.
is_animated	Whether the image is actually animated or not

Returns

std::string endpoint url or empty string

cdn_endpoint_url_hash()

std::string DPP_EXPORT dpp::utility::cdn_endpoint_url_hash	(	const std::vector< image_type > &	allowed_formats,
		const std::string &	path_without_extension,
		const std::string &	hash,
		const dpp::image_type	format,
		uint16_t	size,
		bool	prefer_animated = false,
		bool	is_animated = false
	)

For internal use only. Helper function to easily create discord's cdn endpoint urls

See also

https://discord.com/developers/docs/reference#image-formatting-cdn-endpoints

Parameters

allowed_formats	A vector of supported formats for the endpoint from the discord docs
path_without_extension	The path for the endpoint (without the extension e.g. .png)
hash	The hash (optional). If not empty, it will be prefixed with a_ for animated images (is_animated=true)
format	the wished format to return. Must be one of the formats passed in allowed_formats, otherwise it returns an empty string
size	the image size which will be appended as a querystring to the url. It must be any power of two between 16 and 4096, otherwise no querystring will be appended (discord then returns the image as their default size)
prefer_animated	Whether the user prefers gif format. If true, it'll return gif format whenever the image is available as animated. In this case, the format-parameter is only used for non-animated images.
is_animated	Whether the image is actually animated or not

Returns

std::string endpoint url or empty string

cdn_endpoint_url_sticker()

std::string DPP_EXPORT dpp::utility::cdn_endpoint_url_sticker	(	snowflake	sticker_id,
		sticker_format	format
	)

For internal use only. Helper function to easily create discord's cdn endpoint urls (specialised for stickers)

See also

https://discord.com/developers/docs/reference#image-formatting-cdn-endpoints

Parameters

sticker_id	The sticker ID. Returns empty string if 0
format	The format type

Returns

std::string endpoint url or empty string

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

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	(	std::string_view	name,
		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.

file_extension() [1/2]

std::string DPP_EXPORT dpp::utility::file_extension

(

image_type

type

)

Get the file extension for an image type.

Parameters

type	Image type

Returns

std::string The file extension (e.g. ".png") for this image type

file_extension() [2/2]

std::string DPP_EXPORT dpp::utility::file_extension

(

sticker_format

format

)

Get the file extension for a sticker format.

Parameters

format

Sticker format

Returns

std::string The file extension (e.g. ".png") for this sticker format

guild_navigation()

std::string DPP_EXPORT dpp::utility::guild_navigation	(	const snowflake	guild_id,
		guild_navigation_type	gnt
	)

Create a mentionable guild navigation (used in a message).

Parameters

guild_id	The guild ID
gnt	Guild navigation type using dpp::utility::guild_navigation_type

Returns

std::string The formatted timestamp

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)

is_coro_enabled()

bool DPP_EXPORT dpp::utility::is_coro_enabled

(

)

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

Returns

bool True if coroutines are supported

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

mime_type() [1/2]

std::string DPP_EXPORT dpp::utility::mime_type

(

image_type

type

)

Get the mime type for an image type.

Parameters

type	Image type

Returns

std::string The mime type for this image type

mime_type() [2/2]

std::string DPP_EXPORT dpp::utility::mime_type

(

sticker_format

format

)

Get the mime type for a sticker format.

Parameters

format

Sticker format

Returns

std::string The mime type for this sticker format

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::file_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

callable_returns_v

template<typename F , typename R , typename... Args>

constexpr bool dpp::utility::callable_returns_v = std::is_convertible_v<std::invoke_result_t<F, Args...>, R>

inlineconstexpr

Type trait to check if a callable F can be called using the arguments Args, and that its return value is convertible to R.

Template Parameters

F	Callable object
R	Return type to check for convertibility to
Args...	Arguments to use to resolve the overload

Returns

Whether the expression F(Args...) is convertible to R

cdn_host

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

inline

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