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

Namespaces
	anonymous_namespace{utility.cpp}

Classes
struct	dummy
	Utility struct that has the same size and alignment as another but does nothing. More...

struct	icon
	Wrapper class around a variant for either iconhash or image, for API objects that have one or the other (generally iconhash when receiving, image when uploading an image) 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. More...

struct	image_data
	Image to be received or sent to API calls. 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	avx_type_t : uint8_t { avx_none, avx_1, avx_2, avx_512 }
	Supported AVX instruction set type for audio mixing. More...

enum	guild_navigation_type { gnt_customize, gnt_browse, gnt_guide }
	Guild navigation types for dpp::utility::guild_navigation() More...

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)
	Get the url query parameter for the cdn endpoint. 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::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)
	Helper function to easily create discord's cdn endpoint urls. More...

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)
	Helper function to easily create discord's cdn endpoint urls. More...

std::string DPP_EXPORT	cdn_endpoint_url_sticker (snowflake sticker_id, sticker_format format)
	Helper function to easily create discord's cdn endpoint urls (specialised for stickers) More...

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

std::string DPP_EXPORT	channel_url (const snowflake &guild_id, const snowflake &channel_id)
	Create a URL for message. 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	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...

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

void DPP_EXPORT	exec (const std::string &cmd, std::vector< std::string > parameters={}, cmd_result_t callback={})
	Run a commandline program asynchronously. 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...

template<typename T >
std::enable_if_t< std::is_same_v< T, sticker_format >, std::string >	file_extension (T format)

template<typename T >
std::enable_if_t< std::is_same_v< T, image_type >, std::string >	file_extension (T type)

template std::string	file_extension< image_type > (image_type t)

template std::string	file_extension< sticker_format > (sticker_format t)

std::string DPP_EXPORT	guild_navigation (const snowflake guild_id, guild_navigation_type gnt)
	Create a mentionable guild navigation (used in a message). More...

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

uint32_t DPP_EXPORT	hsl (double h, double s, double l)
	Convert doubles to HSL for sending in embeds. More...

uint32_t DPP_EXPORT	hsl (int h, int s, int l)
	Convert ints to HSL for sending in embeds. More...

bool DPP_EXPORT	is_coro_enabled ()
	Returns true if D++ was built with coroutine support. More...

command_completion_event_t DPP_EXPORT	log_error ()
	The default callback handler for API calls. 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. More...

std::string DPP_EXPORT	make_url_parameters (const std::map< std::string, uint64_t > &parameters)
	Build a URL parameter string e.g. 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	message_url (const snowflake &guild_id, const snowflake &channel_id, const snowflake &message_id)
	Create a URL for message. 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...

template<typename T >
std::enable_if_t< std::is_same_v< T, sticker_format >, std::string >	mime_type (T format)

template<typename T >
std::enable_if_t< std::is_same_v< T, image_type >, std::string >	mime_type (T type)

template std::string	mime_type< image_type > (image_type t)

template std::string	mime_type< sticker_format > (sticker_format t)

std::string DPP_EXPORT	read_file (const std::string &filename)
	Read a whole file into a std::string. 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...

std::string DPP_EXPORT	role_mention (const snowflake &id)
	Create a mentionable role. 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...

std::string DPP_EXPORT	thread_url (const snowflake &guild_id, const snowflake &thread_id)
	Create a URL for message. More...

double DPP_EXPORT	time_f ()
	Return the current time with fractions of seconds. More...

std::string DPP_EXPORT	timestamp (time_t ts, time_format tf=tf_short_datetime)
	Return a mentionable timestamp (used in a message). 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...

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

std::string DPP_EXPORT	user_url (const snowflake &user_id)
	Create a URL for message. More...

size_t DPP_EXPORT	utf8len (std::string_view str)
	Returns the length of a UTF-8 string in codepoints. More...

std::string DPP_EXPORT	utf8substr (std::string_view str, size_t start, size_t length)
	Return substring of a UTF-8 encoded string in codepoints. More...

std::string_view DPP_EXPORT	utf8subview (std::string_view str, size_t start, size_t length)
	Return subview 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. More...

std::string DPP_EXPORT	version ()
	Returns the library's version string. More...

avx_type_t DPP_EXPORT	voice_avx ()
	Returns an enum value indicating which AVX instruction set is used for mixing received voice data, if any. More...

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

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

std::function< void(const dpp::log_t &)> DPP_EXPORT	cout_logger ()
	Get a default logger that outputs to std::cout. More...

static const char *	hex = "0123456789ABCDEF"

constexpr int	max_cdn_image_size {4096}

constexpr int	min_cdn_image_size {16}

const std::string	url_host = "https://discord.com"
	The base URL for message/user/channel links. 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

◆ avx_type_t

enum dpp::utility::avx_type_t : uint8_t

Supported AVX instruction set type for audio mixing.

Enumerator
avx_none	No AVX Support.
avx_1	AVX support.
avx_2	AVX2 support.
avx_512	AVX512 support.

◆ 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	"16:20" 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::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

References max_cdn_image_size, and min_cdn_image_size.

Referenced by cdn_endpoint_url_hash().

Here is the caller graph for this function:

◆ bot_invite_url()

std::string 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::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

Referenced by dpp::utility::image_data::set().

Here is the caller graph for this function:

◆ cdn_endpoint_url()

std::string 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`
	)

Helper function to easily create discord's cdn endpoint urls.

Warning: For internal use only!

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

References cdn_endpoint_url_hash().

Referenced by dpp::role::get_members(), and dpp::user_identified::user_identified().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ cdn_endpoint_url_hash()

std::string 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`
	)

Helper function to easily create discord's cdn endpoint urls.

Warning: For internal use only!

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

References avatar_size(), cdn_host, dpp::unicode_emoji::hash, dpp::i_gif, dpp::i_jpg, dpp::i_png, and dpp::i_webp.

Referenced by cdn_endpoint_url(), dpp::guild::connect_member_voice(), and dpp::user::has_animated_icon().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ cdn_endpoint_url_sticker()

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

Helper function to easily create discord's cdn endpoint urls (specialised for stickers)

Warning: For internal use only!

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

References cdn_host, and file_extension().

Here is the call graph for this function:

◆ channel_mention()

std::string 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.

◆ channel_url()

std::string dpp::utility::channel_url	(	const snowflake &	guild_id,
		const snowflake &	channel_id
	)

Create a URL for message.

Parameters

guild_id	The ID of the guild where channel is located.
channel_id	The ID of the channel.

Returns: std::string The URL to message or empty string if any of ids is 0.

References dpp::snowflake::empty(), and url_host.

Referenced by thread_url().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ cmyk() [1/2]

uint32_t 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

References dpp::unicode_emoji::b, dpp::unicode_emoji::m, and rgb().

Referenced by cmyk().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ cmyk() [2/2]

uint32_t 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

References cmyk(), and dpp::unicode_emoji::m.

Here is the call graph for this function:

◆ current_date_time()

std::string 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

References dpp::unicode_emoji::tm, and dpp::trim().

Here is the call graph for this function:

◆ debug_dump()

std::string 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

References dpp::to_hex().

Referenced by dpp::discord_client::handle_frame().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ emoji_mention()

std::string 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.

Referenced by dpp::emoji::load_image().

Here is the caller graph for this function:

◆ exec()

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

References set_thread_name(), and dpp::unicode_emoji::thread.

Here is the call graph for this function:

◆ file_extension() [1/4]

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

Referenced by dpp::utility::image_data::get_file_extension().

Here is the caller graph for this function:

◆ file_extension() [2/4]

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

◆ file_extension() [3/4]

template<typename T >

std::enable_if_t<std::is_same_v<T, sticker_format>, std::string> dpp::utility::file_extension ( T format )

References dpp::sf_apng, dpp::sf_gif, dpp::sf_lottie, and dpp::sf_png.

Referenced by cdn_endpoint_url_sticker().

Here is the caller graph for this function:

◆ file_extension() [4/4]

template<typename T >

std::enable_if_t<std::is_same_v<T, image_type>, std::string> dpp::utility::file_extension ( T type )

References dpp::i_gif, dpp::i_jpg, dpp::i_png, and dpp::i_webp.

◆ file_extension< image_type >()

template std::string dpp::utility::file_extension< image_type > ( image_type t )

◆ file_extension< sticker_format >()

template std::string dpp::utility::file_extension< sticker_format > ( sticker_format t )

◆ guild_navigation()

std::string 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

References gnt_browse, gnt_customize, and gnt_guide.

◆ has_voice()

bool dpp::utility::has_voice ( )

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

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

◆ hsl() [1/2]

uint32_t dpp::utility::hsl	(	double	h,
		double	s,
		double	l
	)

Convert doubles to HSL for sending in embeds.

Parameters

h	hue value, between 0 and 1 inclusive
s	saturation value in percentage, between 0 and 1 inclusive
l	lightness value in percentage, between 0 and 1 inclusive

Returns: uint32_t returned integer colour value

References dpp::unicode_emoji::b, and rgb().

Referenced by hsl().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ hsl() [2/2]

uint32_t dpp::utility::hsl	(	int	h,
		int	s,
		int	l
	)

Convert ints to HSL for sending in embeds.

Parameters

h	hue value, between 0 and 360 inclusive
s	saturation value in percentage, between 0 and 100 inclusive
l	lightness value in percentage, between 0 and 100 inclusive

Returns: uint32_t returned integer colour value

References hsl().

Here is the call graph for this function:

◆ is_coro_enabled()

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

References dpp::error_info::human_readable, and dpp::ll_error.

◆ loglevel()

std::string 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

References dpp::ll_critical, dpp::ll_debug, dpp::ll_error, dpp::ll_info, dpp::ll_trace, and dpp::ll_warning.

◆ make_url_parameters() [1/2]

std::string 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

References url_encode(), and dpp::unicode_emoji::v.

Referenced by dpp::cluster::delete_webhook(), dpp::cluster::edit_webhook_message(), dpp::cluster::guild_delete_integration(), and make_url_parameters().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ make_url_parameters() [2/2]

std::string 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

References make_url_parameters(), and dpp::unicode_emoji::v.

Here is the call graph for this function:

◆ markdown_escape()

std::string 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

Represents the current state of the finite state machine for the markdown_escape function.

Normal text

A paragraph code block, represented by three backticks.

An inline code block, represented by one backtick.

Represents the current state of the finite state machine for the markdown_escape function.

Normal text

A paragraph code block, represented by three backticks.

An inline code block, represented by one backtick.

Referenced by main().

Here is the caller graph for this function:

◆ message_url()

std::string dpp::utility::message_url	(	const snowflake &	guild_id,
		const snowflake &	channel_id,
		const snowflake &	message_id
	)

Create a URL for message.

Parameters

guild_id	The ID of the guild where message is written.
channel_id	The ID of the channel where message is written.
message_id	The ID of the message.

Returns: std::string The URL to message or empty string if any of ids is 0.

References dpp::snowflake::empty(), and url_host.

Here is the call graph for this function:

◆ mime_type() [1/4]

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

Referenced by dpp::utility::image_data::get_mime_type().

Here is the caller graph for this function:

◆ mime_type() [2/4]

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

◆ mime_type() [3/4]

template<typename T >

std::enable_if_t<std::is_same_v<T, sticker_format>, std::string> dpp::utility::mime_type ( T format )

References dpp::sf_apng, dpp::sf_gif, dpp::sf_lottie, and dpp::sf_png.

◆ mime_type() [4/4]

template<typename T >

std::enable_if_t<std::is_same_v<T, image_type>, std::string> dpp::utility::mime_type ( T type )

References dpp::i_gif, dpp::i_jpg, dpp::i_png, and dpp::i_webp.

◆ mime_type< image_type >()

template std::string dpp::utility::mime_type< image_type > ( image_type t )

◆ mime_type< sticker_format >()

template std::string dpp::utility::mime_type< sticker_format > ( sticker_format t )

◆ read_file()

std::string dpp::utility::read_file ( const std::string & filename )

Read a whole file into a std::string.

Note: This function can take a while if this is a large file, causing events to not reply and also taking up a lot of memory. Make sure you have enough memory, and use dpp::interaction_create_t::thinking in events where you call this function on big files.

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

References dpp::colors::blue, dpp::colors::green, and dpp::colors::red.

Referenced by cmyk(), and hsl().

Here is the caller graph for this function:

◆ rgb() [2/2]

uint32_t 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

References dpp::colors::blue, dpp::colors::green, and dpp::colors::red.

◆ role_mention()

std::string 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::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

Referenced by exec().

Here is the caller graph for this function:

◆ slashcommand_mention() [1/2]

std::string 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

Referenced by dpp::interaction::get_channel(), and dpp::interaction::get_context_message().

Here is the caller graph for this function:

◆ slashcommand_mention() [2/2]

std::string 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

◆ thread_url()

std::string dpp::utility::thread_url	(	const snowflake &	guild_id,
		const snowflake &	thread_id
	)

Create a URL for message.

Parameters

guild_id	The ID of the guild where thread is located.
thread_id	The ID of the thread.

Returns: std::string The URL to message or empty string if any of ids is 0.

References channel_url().

Here is the call graph for this function:

◆ time_f()

double 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

Referenced by dpp::connect_with_timeout(), get_time(), dpp::discord_client::handle_frame(), main(), and dpp::discord_client::one_second_timer().

Here is the caller graph for this function:

◆ timestamp()

std::string 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

Referenced by dpp::set_ts_not_null(), and dpp::ts_not_null().

Here is the caller graph for this function:

◆ tokenize()

std::vector< std::string > 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

References dpp::unicode_emoji::b.

Referenced by dpp::https_client::handle_buffer().

Here is the caller graph for this function:

◆ url_encode()

std::string 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

References hex.

Referenced by dpp::cluster::get_channel_webhooks(), dpp::cluster::guild_command_get_permissions(), dpp::cluster::guild_commands_get(), dpp::cluster::interaction_followup_create(), dpp::cluster::interaction_followup_edit_original(), dpp::cluster::interaction_response_create(), dpp::cluster::interaction_response_edit(), dpp::cluster::interaction_response_get_original(), main(), make_url_parameters(), and dpp::cluster::message_delete_own_reaction().

Here is the caller graph for this function:

◆ user_mention()

std::string 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.

◆ user_url()

std::string dpp::utility::user_url ( const snowflake & user_id )

Create a URL for message.

Parameters

user_id The ID of the guild where thread is located.

Returns: std::string The URL to message or empty string if id is 0.

References dpp::snowflake::empty(), and url_host.

Here is the call graph for this function:

◆ utf8len()

size_t dpp::utility::utf8len ( std::string_view str )

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

Note: Result is unspecified for strings that are not valid UTF-8.

Parameters

str	string to count length of

Returns: size_t Length of string

Referenced by dpp::commandhandler::register_commands(), and validate().

Here is the caller graph for this function:

◆ utf8substr()

std::string dpp::utility::utf8substr	(	std::string_view	str,
		size_t	start,
		size_t	length
	)

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

Note: Result is unspecified for strings that are not valid UTF-8.

Parameters

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

Returns: std::string The requested substring

References start, and utf8subview().

Referenced by dpp::select_option::set_animated(), dpp::embed::set_description(), dpp::embed::set_video(), dpp::slashcommand::to_json_impl(), and validate().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ utf8subview()

std::string_view dpp::utility::utf8subview	(	std::string_view	str,
		size_t	start,
		size_t	length
	)

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

Note: You must ensure that the resulting view is not used after the lifetime of the viewed string has ended.; Result is unspecified for strings that are not valid UTF-8.

Parameters

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

Returns: std::string_view The requested subview

References start.

Referenced by dpp::commandhandler::register_commands(), and utf8substr().

Here is the caller graph for this function:

◆ validate()

std::string 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

References utf8len(), and utf8substr().

Referenced by dpp::role::has_view_creator_monetization_analytics(), and dpp::scheduled_event::scheduled_event().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ version()

std::string dpp::utility::version ( )

Returns the library's version string.

Returns: std::string version

References DPP_VERSION_TEXT.

◆ voice_avx()

avx_type_t dpp::utility::voice_avx ( )

Returns an enum value indicating which AVX instruction set is used for mixing received voice data, if any.

Returns: avx_type_t AVX type

References avx_1, avx_2, avx_512, and avx_none.

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.

Referenced by cdn_endpoint_url_hash(), and cdn_endpoint_url_sticker().

◆ cout_logger

std::function< void(const dpp::log_t &)> 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

Referenced by main().

◆ hex

const char* dpp::utility::hex = "0123456789ABCDEF"

static

Referenced by dpp::utility::iconhash::set(), and url_encode().

◆ max_cdn_image_size

constexpr int dpp::utility::max_cdn_image_size {4096}

constexpr

Referenced by avatar_size().

◆ min_cdn_image_size

constexpr int dpp::utility::min_cdn_image_size {16}

constexpr

Referenced by avatar_size().

◆ url_host

const std::string dpp::utility::url_host = "https://discord.com"

inline

The base URL for message/user/channel links.

Referenced by channel_url(), message_url(), and user_url().

Namespaces

Classes

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ cmd_result_t

Enumeration Type Documentation

◆ avx_type_t

◆ guild_navigation_type

◆ time_format

Function Documentation

◆ avatar_size()

◆ bot_invite_url()

◆ bytes()

◆ cdn_endpoint_url()

◆ cdn_endpoint_url_hash()

◆ cdn_endpoint_url_sticker()

◆ channel_mention()

◆ channel_url()

◆ cmyk() [1/2]

◆ cmyk() [2/2]

◆ current_date_time()

◆ debug_dump()

◆ emoji_mention()

◆ exec()

◆ file_extension() [1/4]

◆ file_extension() [2/4]

◆ file_extension() [3/4]

◆ file_extension() [4/4]

◆ file_extension< image_type >()

◆ file_extension< sticker_format >()

◆ guild_navigation()

◆ has_voice()

◆ hsl() [1/2]

◆ hsl() [2/2]

◆ is_coro_enabled()

◆ log_error()

◆ loglevel()

◆ make_url_parameters() [1/2]

◆ make_url_parameters() [2/2]

◆ markdown_escape()

◆ message_url()

◆ mime_type() [1/4]

◆ mime_type() [2/4]

◆ mime_type() [3/4]

◆ mime_type() [4/4]

◆ mime_type< image_type >()

◆ mime_type< sticker_format >()

◆ read_file()

◆ rgb() [1/2]

◆ rgb() [2/2]

◆ role_mention()

◆ set_thread_name()

◆ slashcommand_mention() [1/2]

◆ slashcommand_mention() [2/2]

◆ thread_url()

◆ time_f()

◆ timestamp()

◆ tokenize()

◆ url_encode()

◆ user_mention()

◆ user_url()

◆ utf8len()

◆ utf8substr()

◆ utf8subview()

◆ validate()

◆ version()

◆ voice_avx()

Variable Documentation

◆ callable_returns_v

◆ cdn_host

◆ cout_logger

◆ hex

◆ max_cdn_image_size

◆ min_cdn_image_size

◆ url_host