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  iconhash
 Store a 128 bit icon hash (profile picture, server icon etc) as a 128 bit binary value made of two uint64_t. Has a constructor to build one from a string, and a method to fetch the value back in string form. More...
 
struct  uptime
 A class used to represent an uptime in hours, minutes, seconds and days, with helper functions to convert from time_t and display as a string. More...
 

Typedefs

typedef std::function< void(const std::string &output)> cmd_result_t
 Callback for the results of a command executed via dpp::utility::exec. More...
 

Enumerations

enum  time_format : uint8_t {
  tf_long_date = 'D' , tf_long_datetime = 'F' , tf_relative_time = 'R' , tf_long_time = 'T' ,
  tf_short_date = 'd' , tf_short_datetime = 'f' , tf_short_time = 't'
}
 Timestamp formats for dpp::utility::timestamp() More...
 

Functions

std::function< void(const dpp::log_t &)> DPP_EXPORT cout_logger ()
 Get a default logger that outputs to std::cout. e.g. More...
 
std::function< void(const dpp::confirmation_callback_t &detail)> DPP_EXPORT log_error ()
 The default callback handler for API calls. on error, sends the error to the logger. More...
 
void DPP_EXPORT exec (const std::string &cmd, std::vector< std::string > parameters={}, cmd_result_t callback={})
 Run a commandline program asynchronously. The command line program is spawned in a separate std::thread, and when complete, its output from stdout is passed to the callback function in its string parameter. For example. More...
 
std::string DPP_EXPORT timestamp (time_t ts, time_format tf)
 Return a mentionable timestamp (used in a discord embed). These timestamps will display the given timestamp in the user's timezone and locale. More...
 
std::string DPP_EXPORT current_date_time ()
 Returns current date and time. More...
 
std::string DPP_EXPORT loglevel (dpp::loglevel in)
 Convert a dpp::loglevel enum value to a string. More...
 
double DPP_EXPORT time_f ()
 Return the current time with fractions of seconds. This is a unix epoch time with the fractional seconds part after the decimal place. More...
 
bool DPP_EXPORT has_voice ()
 Returns true if D++ was built with voice support. More...
 
std::string DPP_EXPORT bytes (uint64_t c)
 Convert a byte count to display value. More...
 
uint32_t DPP_EXPORT rgb (float red, float green, float blue)
 Convert floats 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 debug_dump (uint8_t *data, size_t length)
 Output hex values of a section of memory for debugging. More...
 
size_t DPP_EXPORT utf8len (const std::string &str)
 Returns the length of a UTF-8 string in codepoints. More...
 
std::string DPP_EXPORT utf8substr (const std::string &str, std::string::size_type start, std::string::size_type length)
 Return substring of a UTF-8 encoded string in codepoints. More...
 
std::string DPP_EXPORT read_file (const std::string &filename)
 Read a whole file into a std::string. Be sure you have enough memory to read the file, if you are reading a large file. More...
 
std::string DPP_EXPORT validate (const std::string &value, size_t _min, size_t _max, const std::string &exception_message)
 Validate a string value In the event the length of the string is less than _min, then an exception of type dpp:length_exception will be thrown. If the string is longer than _max UTF8 codepoints it will be truncated to fit. More...
 
std::string DPP_EXPORT avatar_size (uint32_t size)
 Return the url parameter for an avatar size, or empty if the size is 0. 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 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 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...
 

Variables

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

Detailed Description

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

Typedef Documentation

◆ cmd_result_t

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

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

Enumeration Type Documentation

◆ time_format

enum dpp::utility::time_format : uint8_t

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

Note
These values are the actual character values specified by the Discord API and should not be changed unless the Discord API changes the specification! They have been sorted into numerical order of their ASCII value to keep C++ happy.
Enumerator
tf_long_date 

"20 April 2021" - Long Date

tf_long_datetime 

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

tf_relative_time 

"2 months ago" - Relative Time

tf_long_time 

"16:20:30" - Long Time

tf_short_date 

"20/04/2021" - Short Date

tf_short_datetime 

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

tf_short_time 

"16:20" - Short Time

Function Documentation

◆ avatar_size()

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

Return the url parameter for an avatar size, or empty if the size is 0.

Parameters
sizesize to generate url parameter for
Returns
std::string url parameter

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

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

std::function< void(const dpp::log_t &)> DPP_EXPORT cout_logger()
Get a default logger that outputs to std::cout. e.g.
Returns
A logger for attaching to on_log

◆ current_date_time()

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

Returns current date and time.

Returns
std::string Current date and time

◆ 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

◆ 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";
});
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...
Parameters
cmdThe command to run.
parametersCommand line parameters. Each will be escaped using std::quoted.
callbackThe callback to call on completion.

◆ has_voice()

bool DPP_EXPORT dpp::utility::has_voice ( )

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

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

◆ log_error()

std::function< void(const dpp::confirmation_callback_t &detail)> DPP_EXPORT dpp::utility::log_error ( )

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

Returns
A lambda for attaching to an API callback

◆ loglevel()

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

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

Parameters
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 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 escaped text

◆ read_file()

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

Read a whole file into a std::string. Be sure you have enough memory to read the file, if you are reading a large file.

Note
Be aware this function can block! If you are regularly reading large files, consider caching them.
Parameters
filenameThe path to the file to read
Returns
std::string The file contents
Exceptions
dpp::exceptionon failure to read the entire file

◆ rgb() [1/2]

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

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

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

Return a mentionable timestamp (used in a discord embed). 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

◆ utf8len()

size_t DPP_EXPORT dpp::utility::utf8len ( const std::string &  str)

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

Parameters
strstring to count length of
Returns
size_t length of string (0 for invalid utf8)

◆ utf8substr()

std::string DPP_EXPORT dpp::utility::utf8substr ( const std::string &  str,
std::string::size_type  start,
std::string::size_type  length 
)

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

Parameters
strstring to return substring from
startstart codepoint offset
lengthlength in codepoints
Returns
std::string Substring in UTF-8 or empty string if invalid UTF-8 passed in

◆ validate()

std::string DPP_EXPORT dpp::utility::validate ( const std::string &  value,
size_t  _min,
size_t  _max,
const std::string &  exception_message 
)

Validate a string value In the event the length of the string is less than _min, then an exception of type dpp:length_exception will be thrown. If the string is longer than _max UTF8 codepoints it will be truncated to fit.

Parameters
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

Variable Documentation

◆ cdn_host

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

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

D++ Library version 10.0.21D++ Library version 10.0.20D++ Library version 10.0.19D++ Library version 10.0.18D++ Library version 10.0.17D++ Library version 10.0.16D++ Library version 10.0.15D++ Library version 10.0.14D++ Library version 10.0.13D++ Library version 10.0.12D++ Library version 10.0.11D++ Library version 10.0.10D++ Library version 10.0.9D++ Library version 10.0.8D++ Library version 10.0.7D++ Library version 10.0.6D++ Library version 10.0.5D++ Library version 10.0.4D++ Library version 10.0.3D++ Library version 10.0.2D++ Library version 10.0.1D++ Library version 10.0.0D++ Library version 9.0.19D++ Library version 9.0.18D++ Library version 9.0.17D++ Library version 9.0.16D++ Library version 9.0.15D++ Library version 9.0.14D++ 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