D++ (DPP)
C++ Discord API Bot Library
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  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. Has a constructor to build one from a string, and a method to fetch the value back in string form. 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  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

command_completion_event_t 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)
 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...
 
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...
 
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...
 
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...
 
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...
 
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 (std::string_view str)
 Returns the length of a UTF-8 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 utf8substr (std::string_view str, size_t start, size_t 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. 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 message_url (const snowflake &guild_id, const snowflake &channel_id, const snowflake &message_id)
 Create a URL for message. More...
 
std::string DPP_EXPORT channel_url (const snowflake &guild_id, const snowflake &channel_id)
 Create a URL for message. More...
 
std::string DPP_EXPORT thread_url (const snowflake &guild_id, const snowflake &thread_id)
 Create a URL for message. More...
 
std::string DPP_EXPORT user_url (const snowflake &user_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...
 
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

std::function< void(const dpp::log_t &)> DPP_EXPORT cout_logger ()
 Get a default logger that outputs to std::cout. e.g. More...
 
const std::string cdn_host = "https://cdn.discordapp.com"
 The base URL for CDN content such as profile pictures and guild icons. More...
 
const std::string url_host = "https://discord.com"
 The base URL for message/user/channel links. 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

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

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

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
sizesize 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_idBot ID
permissionsPermission bitmask of the bot to invite
scopesScopes to use
Returns
Invite URL

◆ bytes()

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

Convert a byte count to display value.

Parameters
cnumber 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 
)

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_formatsA vector of supported formats for the endpoint from the discord docs
path_without_extensionThe path for the endpoint (without the extension e.g. .png)
formatthe wished format to return. Must be one of the formats passed in allowed_formats, otherwise it returns an empty string
sizethe 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_animatedWhether 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_animatedWhether 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 
)

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_formatsA vector of supported formats for the endpoint from the discord docs
path_without_extensionThe path for the endpoint (without the extension e.g. .png)
hashThe hash (optional). If not empty, it will be prefixed with a_ for animated images (is_animated=true)
formatthe wished format to return. Must be one of the formats passed in allowed_formats, otherwise it returns an empty string
sizethe 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_animatedWhether 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_animatedWhether 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 
)

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_idThe sticker ID. Returns empty string if 0
formatThe 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
idThe ID of the channel.
Returns
std::string The formatted mention of the channel.

◆ channel_url()

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

Create a URL for message.

Parameters
guild_idThe ID of the guild where channel is located.
channel_idThe ID of the channel.
Returns
std::string The URL to message or empty string if any of ids is 0.

◆ 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
ccyan value, between 0 and 1 inclusive
mmagenta value, between 0 and 1 inclusive
yyellow value, between 0 and 1 inclusive
kkey (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
ccyan value, between 0 and 255 inclusive
mmagenta value, between 0 and 255 inclusive
yyellow value, between 0 and 255 inclusive
kkey (black) value, between 0 and 255 inclusive
Returns
uint32_t returned integer colour value

◆ 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
dataThe start of the data to display
lengthThe 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
nameThe name of the emoji.
idThe ID of the emoji.
is_animatedis 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
cmdThe command to run.
parametersCommand line parameters. Each will be escaped using std::quoted.
callbackThe 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
typeImage 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
formatSticker 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_idThe guild ID
gntGuild 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)

◆ hsl() [1/2]

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

Convert doubles to HSL for sending in embeds.

Parameters
hhue value, between 0 and 1 inclusive
ssaturation value in percentage, between 0 and 1 inclusive
llightness value in percentage, between 0 and 1 inclusive
Returns
uint32_t returned integer colour value

◆ hsl() [2/2]

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

Convert ints to HSL for sending in embeds.

Parameters
hhue value, between 0 and 360 inclusive
ssaturation value in percentage, between 0 and 100 inclusive
llightness value in percentage, between 0 and 100 inclusive
Returns
uint32_t returned integer colour value

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

command_completion_event_t 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
inlog 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
parametersparameters 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
parametersparameters 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
textText to escape
escape_code_blocksIf 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

◆ message_url()

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

Create a URL for message.

Parameters
guild_idThe ID of the guild where message is written.
channel_idThe ID of the channel where message is written.
message_idThe ID of the message.
Returns
std::string The URL to message or empty string if any of ids is 0.

◆ mime_type() [1/2]

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

Get the mime type for an image type.

Parameters
typeImage 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
formatSticker 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.

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
filenameThe path to the file to read
Returns
std::string The file contents
Exceptions
dpp::file_exceptionon 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
redred value, between 0 and 1 inclusive
greengreen value, between 0 and 1 inclusive
blueblue 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
redred value, between 0 and 255 inclusive
greengreen value, between 0 and 255 inclusive
blueblue 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
idThe 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
nameNew 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_idThe ID of the slashcommand
command_nameThe command name
subcommandOptional: 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_idThe ID of the slashcommand
command_nameThe command name
subcommand_groupThe subcommand group name
subcommandThe subcommand name
Returns
std::string The formatted mention of the slashcommand with its subcommand

◆ thread_url()

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

Create a URL for message.

Parameters
guild_idThe ID of the guild where thread is located.
thread_idThe ID of the thread.
Returns
std::string The URL to message or empty string if any of ids is 0.

◆ 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
tsTime stamp to convert
tfFormat 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
inInput string
sepSeparator 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
valueString 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
idThe ID of the user.
Returns
std::string The formatted mention of the user.

◆ user_url()

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

Create a URL for message.

Parameters
user_idThe ID of the guild where thread is located.
Returns
std::string The URL to message or empty string if id is 0.

◆ utf8len()

size_t DPP_EXPORT 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
strstring to count length of
Returns
size_t Length of string

◆ utf8substr()

std::string DPP_EXPORT 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
strstring to return substring from
startstart codepoint offset
lengthlength in codepoints
Returns
std::string The requested substring

◆ utf8subview()

std::string_view DPP_EXPORT 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
strstring to return substring from
startstart codepoint offset
lengthlength in codepoints
Returns
std::string_view The requested subview

◆ 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
valueThe value to validate
_minMinimum length
_maxMaximum length
exception_messageException message to throw if value length < _min
Returns
std::string Validated string, truncated if necessary.
Exceptions
dpp::length_exceptionif value UTF8 length < _min

◆ version()

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

Returns the library's version string.

Returns
std::string version

◆ voice_avx()

avx_type_t DPP_EXPORT 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

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
FCallable object
RReturn 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.

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

Returns
A logger for attaching to on_log

◆ url_host

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

The base URL for message/user/channel links.

dpp::utility::exec
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::thre...
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.
Definition: dispatcher.h:228
D++ Library version 9.0.13D++ Library version 9.0.12D++ Library version 9.0.11D++ Library version 9.0.10D++ Library version 9.0.9D++ Library version 9.0.8D++ Library version 9.0.7D++ Library version 9.0.6D++ Library version 9.0.5D++ Library version 9.0.4D++ Library version 9.0.3D++ Library version 9.0.2D++ Library version 9.0.1D++ Library version 9.0.0D++ Library version 1.0.2D++ Library version 1.0.1D++ Library version 1.0.0