dpp::utility
dpp::utility::dummy
dpp::utility::icon
dpp::utility::iconhash
dpp::utility::image_data
dpp::utility::primaryguild
dpp::utility::uptime
uint8_t avx_type_t dpp::utility::avx_type_t avx_none

No AVX Support.

avx_1

AVX support.

avx_2

AVX2 support.

avx_512

AVX512 support.

Supported AVX instruction set type for audio mixing.

guild_navigation_type
dpp::utility::guild_navigation_type
gnt_customize

Customize tab with the server's dpp::onboarding_prompt

gnt_browse

"16:20" Browse Channels tab

gnt_guide

Server Guide.

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

uint8_t time_format dpp::utility::time_format tf_long_date = 'D'

"20 April 2021" - Long Date

tf_long_datetime
= 'F'

"Tuesday, 20 April 2021 16:20" - Long Date/Time

tf_relative_time
= 'R'

"2 months ago" - Relative Time

tf_long_time
= 'T'

"16:20:30" - Long Time

tf_short_date
= 'd'

"20/04/2021" - Short Date

tf_short_datetime
= 'f'

"20 April 2021 16:20" - Short Date/Time

tf_short_time
= 't'

"16:20" - Short Time

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

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.

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

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

typename F
typename R
typename... Args Args
bool bool dpp::utility::callable_returns_v callable_returns_v dpp::utility::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.

F

Callable object

R

Return type to check for convertibility to

Args...

Arguments to use to resolve the overload

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

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

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

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

The base URL for message/user/channel links.

std::string DPP_EXPORT std::string DPP_EXPORT dpp::utility::avatar_size (uint32_t size) avatar_size dpp::utility::avatar_size uint32_t size

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

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.

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

std::string DPP_EXPORT 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"}) bot_invite_url 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.

bot_id

Bot ID

permissions

Permission bitmask of the bot to invite

scopes

Scopes to use

Invite URL

std::string DPP_EXPORT std::string DPP_EXPORT dpp::utility::bytes (uint64_t c) bytes dpp::utility::bytes uint64_t c

Convert a byte count to display value.

c

number of bytes

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

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

For internal use only!

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

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

std::string endpoint url or empty string

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

For internal use only!

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

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

std::string endpoint url or empty string

std::string DPP_EXPORT std::string DPP_EXPORT dpp::utility::cdn_endpoint_url_sticker (snowflake sticker_id, sticker_format format) cdn_endpoint_url_sticker 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).

For internal use only!

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

sticker_id

The sticker ID. Returns empty string if 0

format

The format type

std::string endpoint url or empty string

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

Create a mentionable channel.

id

The ID of the channel.

std::string The formatted mention of the channel.

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

Create a URL for message.

guild_id

The ID of the guild where channel is located.

channel_id

The ID of the channel.

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

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

Convert doubles to CMYK for sending in embeds.

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

uint32_t returned integer colour value

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

Convert ints to CMYK for sending in embeds.

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

uint32_t returned integer colour value

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

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

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

A logger for attaching to on_log

std::string DPP_EXPORT std::string DPP_EXPORT dpp::utility::current_date_time () current_date_time dpp::utility::current_date_time

Returns current date and time.

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

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

Output hex values of a section of memory for debugging.

data

The start of the data to display

length

The length of data to display

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

Create a mentionable emoji.

name

The name of the emoji.

id

The ID of the emoji.

is_animated

is emoji animated.

std::string The formatted mention of the emoji.

void DPP_EXPORT void DPP_EXPORT dpp::utility::exec (const std::string &cmd, std::vector< std::string > parameters={}, cmd_result_t callback={}) exec 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"},[](conststd::string&output){
    std::cout<<"Outputof'ls-al':"<<output<<"\n";
    });

cmd

The command to run.

parameters

Command line parameters. Each will be escaped using `std::quoted`.

callback

The callback to call on completion.

std::string DPP_EXPORT std::string DPP_EXPORT dpp::utility::file_extension (image_type type) file_extension dpp::utility::file_extension image_type type

Get the file extension for an image type.

type

Image type

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

std::string DPP_EXPORT std::string DPP_EXPORT dpp::utility::file_extension (sticker_format format) file_extension dpp::utility::file_extension sticker_format format

Get the file extension for a sticker format.

format

Sticker format

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

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

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

guild_id

The guild ID

gnt

Guild navigation type using dpp::utility::guild_navigation_type

std::string The formatted timestamp

bool DPP_EXPORT bool DPP_EXPORT dpp::utility::has_voice () has_voice dpp::utility::has_voice

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

bool True if voice support is compiled in (libopus)

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

Convert doubles to HSL for sending in embeds.

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

uint32_t returned integer colour value

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

Convert ints to HSL for sending in embeds.

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

uint32_t returned integer colour value

bool DPP_EXPORT bool DPP_EXPORT dpp::utility::is_coro_enabled () is_coro_enabled dpp::utility::is_coro_enabled

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

bool True if coroutines are supported

command_completion_event_t DPP_EXPORT command_completion_event_t DPP_EXPORT dpp::utility::log_error () log_error dpp::utility::log_error

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

A lambda for attaching to an API callback

std::string DPP_EXPORT std::string DPP_EXPORT dpp::utility::loglevel (dpp::loglevel in) loglevel dpp::utility::loglevel dpp::loglevel in

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

in

log level to convert

std::string string form of log level

std::string DPP_EXPORT std::string DPP_EXPORT dpp::utility::make_url_parameters (const std::map< std::string, std::string > &parameters) make_url_parameters 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 to create a url query string for

std::string A correctly encoded url query string

std::string DPP_EXPORT std::string DPP_EXPORT dpp::utility::make_url_parameters (const std::map< std::string, uint64_t > &parameters) make_url_parameters 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 to create a url query string for

std::string A correctly encoded url query string

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

Create a URL for message.

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.

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

std::string DPP_EXPORT std::string DPP_EXPORT dpp::utility::mime_type (image_type type) mime_type dpp::utility::mime_type image_type type

Get the mime type for an image type.

type

Image type

std::string The mime type for this image type

std::string DPP_EXPORT std::string DPP_EXPORT dpp::utility::mime_type (sticker_format format) mime_type dpp::utility::mime_type sticker_format format

Get the mime type for a sticker format.

format

Sticker format

std::string The mime type for this sticker format

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

Read a whole file into a std::string.

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.

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

filename

The path to the file to read

std::string The file contents

dpp::file_exception

on failure to read the entire file

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

Convert doubles to RGB for sending in embeds.

red

red value, between 0 and 1 inclusive

green

green value, between 0 and 1 inclusive

blue

blue value, between 0 and 1 inclusive

uint32_t returned integer colour value

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

Convert ints to RGB for sending in embeds.

red

red value, between 0 and 255 inclusive

green

green value, between 0 and 255 inclusive

blue

blue value, between 0 and 255 inclusive

uint32_t returned integer colour value

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

Create a mentionable role.

id

The ID of the role.

std::string The formatted mention of the role.

void DPP_EXPORT void DPP_EXPORT dpp::utility::set_thread_name (const std::string &name) set_thread_name dpp::utility::set_thread_name const std::string & name

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

name

New name to set

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

Create a mentionable slashcommand (used in a message).

command_id

The ID of the slashcommand

command_name

The command name

subcommand

Optional: The subcommand name (for mentioning a subcommand)

std::string The formatted mention

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

command_id

The ID of the slashcommand

command_name

The command name

subcommand_group

The subcommand group name

subcommand

The subcommand name

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

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

Create a URL for message.

guild_id

The ID of the guild where thread is located.

thread_id

The ID of the thread.

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

double DPP_EXPORT double DPP_EXPORT dpp::utility::time_f () time_f 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.

double time with fractional seconds

std::string DPP_EXPORT std::string DPP_EXPORT dpp::utility::timestamp (time_t ts, time_format tf=tf_short_datetime) timestamp 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.

ts

Time stamp to convert

tf

Format of timestamp using dpp::utility::time_format

std::string The formatted timestamp

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

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

in

Input string

sep

Separator characters

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

std::string DPP_EXPORT std::string DPP_EXPORT dpp::utility::url_encode (const std::string &value) url_encode dpp::utility::url_encode const std::string & value

Escapes Discord's markdown sequences in a string.

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.

std::string The text with the markdown special characters escaped with a backslash */ std::string DPP_EXPORT markdown_escape(const std::string& text, bool escape_code_blocks = false);

/**

Encodes a url parameter similar to php urlencode()

value

String to encode

std::string URL encoded string

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

Create a mentionable user.

id

The ID of the user.

std::string The formatted mention of the user.

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

Create a URL for message.

user_id

The ID of the guild where thread is located.

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

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

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

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

str

string to count length of

size_t Length of string

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

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

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

str

string to return substring from

start

start codepoint offset

length

length in codepoints

std::string The requested substring

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

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

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.

str

string to return substring from

start

start codepoint offset

length

length in codepoints

std::string_view The requested subview

std::string DPP_EXPORT std::string DPP_EXPORT dpp::utility::validate (const std::string &value, size_t _min, size_t _max, const std::string &exception_message) validate 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.

value

The value to validate

_min

Minimum length

_max

Maximum length

exception_message

Exception message to throw if value length < _min

std::string Validated string, truncated if necessary.

dpp::length_exception

if value UTF8 length < _min

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

Returns the library's version string.

std::string version

avx_type_t DPP_EXPORT avx_type_t DPP_EXPORT dpp::utility::voice_avx () voice_avx dpp::utility::voice_avx

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

avx_type_t AVX type

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