| D++ (DPP) C++ Discord API Bot Library

Search
Loading...
Searching...
No Matches
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 | primaryguild
| User's primary guild (server tag). 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.

## 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. Internally used to build url getters.
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.
std::string DPP_EXPORT | bytes (uint64_t c)
| Convert a byte count to display value.
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.
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.
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).
std::string DPP_EXPORT | channel_mention (const snowflake &id)
| Create a mentionable channel.
std::string DPP_EXPORT | channel_url (const snowflake &guild_id, const snowflake &channel_id)
| Create a URL for message.
uint32_t DPP_EXPORT | cmyk (double c, double m, double y, double k)
| Convert doubles to CMYK for sending in embeds.
uint32_t DPP_EXPORT | cmyk (int c, int m, int y, int k)
| Convert ints to CMYK for sending in embeds.
std::function< void(const dpp::log_t &)> DPP_EXPORT | cout_logger ()
| Get a default logger that outputs to std::cout. e.g.
std::string DPP_EXPORT | current_date_time ()
| Returns current date and time.
std::string DPP_EXPORT | debug_dump (const uint8_t *data, size_t length)
| Output hex values of a section of memory for debugging.
std::string DPP_EXPORT | emoji_mention (std::string_view name, snowflake id, bool is_animated=false)
| Create a mentionable emoji.
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:
std::string DPP_EXPORT | file_extension (image_type type)
| Get the file extension for an image type.
std::string DPP_EXPORT | file_extension (sticker_format format)
| Get the file extension for a sticker format.
std::string DPP_EXPORT | guild_navigation (const snowflake guild_id, guild_navigation_type gnt)
| Create a mentionable guild navigation (used in a message).
bool DPP_EXPORT | has_voice ()
| Returns true if D++ was built with voice support.
uint32_t DPP_EXPORT | hsl (double h, double s, double l)
| Convert doubles to HSL for sending in embeds.
uint32_t DPP_EXPORT | hsl (int h, int s, int l)
| Convert ints to HSL for sending in embeds.
bool DPP_EXPORT | is_coro_enabled ()
| Returns true if D++ was built with coroutine support.
command_completion_event_t DPP_EXPORT | log_error ()
| The default callback handler for API calls. on error, sends the error to the logger.
std::string DPP_EXPORT | loglevel (dpp::loglevel in)
| Convert a dpp::loglevel enum value to a string.
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.
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.
std::string DPP_EXPORT | message_url (const snowflake &guild_id, const snowflake &channel_id, const snowflake &message_id)
| Create a URL for message.
std::string DPP_EXPORT | mime_type (image_type type)
| Get the mime type for an image type.
std::string DPP_EXPORT | mime_type (sticker_format format)
| Get the mime type for a sticker format.
std::string DPP_EXPORT | read_file (const std::string &filename)
| Read a whole file into a std::string.
uint32_t DPP_EXPORT | rgb (double red, double green, double blue)
| Convert doubles to RGB for sending in embeds.
uint32_t DPP_EXPORT | rgb (int red, int green, int blue)
| Convert ints to RGB for sending in embeds.
std::string DPP_EXPORT | role_mention (const snowflake &id)
| Create a mentionable role.
void DPP_EXPORT | set_thread_name (const std::string &name)
| Set the name of the current thread for debugging and statistical reporting.
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).
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).
std::string DPP_EXPORT | thread_url (const snowflake &guild_id, const snowflake &thread_id)
| Create a URL for message.
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.
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.
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.
std::string DPP_EXPORT | url_encode (const std::string &value)
| Escapes Discord's markdown sequences in a string.
std::string DPP_EXPORT | user_mention (const snowflake &id)
| Create a mentionable user.
std::string DPP_EXPORT | user_url (const snowflake &user_id)
| Create a URL for message.
size_t DPP_EXPORT | utf8len (std::string_view str)
| Returns the length of a UTF-8 string in codepoints.
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.
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.
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.
std::string DPP_EXPORT | version ()
| Returns the library's version string.
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.

## 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.
const std::string | cdn_host = "https://cdn.discordapp.com"
| The base URL for CDN content such as profile pictures and guild icons.
const std::string | url_host = "https://discord.com"
| The base URL for message/user/channel links.

## 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_EXPORT dpp::utility::avatar_size | ( | uint32_t | size | ) |

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

Parameters

  size | size to generate url parameter for. Must be any power of two between 16 and 4096 (inclusive) or it'll return an empty string.

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

## ◆ bot_invite_url()

std::string DPP_EXPORT dpp::utility::bot_invite_url | ( | const snowflake | bot_id,
|  | const uint64_t | permissions = 0,
|  | const std::vector< std::string > & | scopes = {"bot", "applications.commands"} )

Create a bot invite.

Parameters

  bot_id | Bot ID
  permissions | Permission bitmask of the bot to invite
  scopes | Scopes to use

Returns
  Invite URL

## ◆ bytes()

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

Convert a byte count to display value.

Parameters

  c | number of bytes

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

## ◆ cdn_endpoint_url()

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

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

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

Returns
  std::string endpoint url or empty string

## ◆ cdn_endpoint_url_sticker()

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

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

## ◆ channel_mention()

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

Create a mentionable channel.

Parameters

  id | The ID of the channel.

Returns
  std::string The formatted mention of the channel.

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

## ◆ cmyk() [1/2]

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

Convert doubles to CMYK for sending in embeds.

Parameters

  c | cyan value, between 0 and 1 inclusive
  m | magenta value, between 0 and 1 inclusive
  y | yellow value, between 0 and 1 inclusive
  k | key (black) value, between 0 and 1 inclusive

Returns
  uint32_t returned integer colour value

## ◆ cmyk() [2/2]

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

Convert ints to CMYK for sending in embeds.

Parameters

  c | cyan value, between 0 and 255 inclusive
  m | magenta value, between 0 and 255 inclusive
  y | yellow value, between 0 and 255 inclusive
  k | key (black) value, between 0 and 255 inclusive

Returns
  uint32_t returned integer colour value

## ◆ cout_logger()

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

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

bot.on_log(dpp::utility::cout_logger());
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.

Returns
  A logger for attaching to on_log

## ◆ current_date_time()

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

Returns current date and time.

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

## ◆ debug_dump()

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

Output hex values of a section of memory for debugging.

Parameters

  data | The start of the data to display
  length | The length of data to display

## ◆ emoji_mention()

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

Create a mentionable emoji.

Parameters

  name | The name of the emoji.
  id | The ID of the emoji.
  is_animated | is emoji animated.

Returns
  std::string The formatted mention of the emoji.

## ◆ exec()

void DPP_EXPORT dpp::utility::exec | ( | const std::string & | cmd,
|  | std::vector< std::string > | parameters = {},
|  | cmd_result_t | callback = {} )

Run a commandline program asynchronously. The command line program is spawned in a separate std::thread, and when complete, its output from stdout is passed to the callback function in its string parameter. For example:

dpp::utility::exec("/bin/ls", {"-al"}, [](const std::string& output) {
std::cout << "Output of 'ls -al': " << output << "\n";
});
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...

Parameters

  cmd | The command to run.
  parameters | Command line parameters. Each will be escaped using std::quoted.
  callback | The callback to call on completion.

## ◆ file_extension() [1/2]

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

Get the file extension for an image type.

Parameters

  type | Image type

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

## ◆ file_extension() [2/2]

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

Get the file extension for a sticker format.

Parameters

  format | Sticker format

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

## ◆ guild_navigation()

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

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

Parameters

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

Returns
  std::string The formatted timestamp

## ◆ has_voice()

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

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

Returns
  bool True if voice support is compiled in (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

  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

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

  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

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

  in | log level to convert

Returns
  std::string string form of log level

## ◆ make_url_parameters() [1/2]

std::string DPP_EXPORT dpp::utility::make_url_parameters | ( | const std::map< std::string, std::string > & | parameters | ) |

Build a URL parameter string e.g. "?a=b&c=d&e=f" from a map of key/value pairs. Entries with empty key names or values are omitted.

Parameters

  parameters | parameters to create a url query string for

Returns
  std::string A correctly encoded url query string

## ◆ make_url_parameters() [2/2]

std::string DPP_EXPORT dpp::utility::make_url_parameters | ( | const std::map< std::string, uint64_t > & | parameters | ) |

Build a URL parameter string e.g. "?a=b&c=d&e=f" from a map of key/value pairs. Entries with empty key names or zero values are omitted.

Parameters

  parameters | parameters to create a url query string for

Returns
  std::string A correctly encoded url query string

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

## ◆ mime_type() [1/2]

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

Get the mime type for an image type.

Parameters

  type | Image type

Returns
  std::string The mime type for this image type

## ◆ mime_type() [2/2]

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

Get the mime type for a sticker format.

Parameters

  format | Sticker format

Returns
  std::string The mime type for this sticker format

## ◆ read_file()

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

Read a whole file into a std::string.

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_EXPORT dpp::utility::rgb | ( | double | red,
|  | double | green,
|  | double | blue )

Convert doubles to RGB for sending in embeds.

Parameters

  red | red value, between 0 and 1 inclusive
  green | green value, between 0 and 1 inclusive
  blue | blue value, between 0 and 1 inclusive

Returns
  uint32_t returned integer colour value

## ◆ rgb() [2/2]

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

Convert ints to RGB for sending in embeds.

Parameters

  red | red value, between 0 and 255 inclusive
  green | green value, between 0 and 255 inclusive
  blue | blue value, between 0 and 255 inclusive

Returns
  uint32_t returned integer colour value

## ◆ role_mention()

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

Create a mentionable role.

Parameters

  id | The ID of the role.

Returns
  std::string The formatted mention of the role.

## ◆ set_thread_name()

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

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

Parameters

  name | New name to set

## ◆ slashcommand_mention() [1/2]

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

Create a mentionable slashcommand (used in a message).

Parameters

  command_id | The ID of the slashcommand
  command_name | The command name
  subcommand | Optional: The subcommand name (for mentioning a subcommand)

Returns
  std::string The formatted mention

## ◆ slashcommand_mention() [2/2]

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

Create a mentionable slashcommand (used in a message).

Parameters

  command_id | The ID of the slashcommand
  command_name | The command name
  subcommand_group | The subcommand group name
  subcommand | The subcommand name

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

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

## ◆ time_f()

double DPP_EXPORT dpp::utility::time_f | ( |  | ) |

Return the current time with fractions of seconds. This is a unix epoch time with the fractional seconds part after the decimal place.

Returns
  double time with fractional seconds

## ◆ timestamp()

std::string DPP_EXPORT dpp::utility::timestamp | ( | time_t | ts,
|  | time_format | tf = tf_short_datetime )

Return a mentionable timestamp (used in a message). These timestamps will display the given timestamp in the user's timezone and locale.

Parameters

  ts | Time stamp to convert
  tf | Format of timestamp using dpp::utility::time_format

Returns
  std::string The formatted timestamp

## ◆ tokenize()

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

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

Parameters

  in | Input string
  sep | Separator characters

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

## ◆ url_encode()

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

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 */ std::string DPP_EXPORT markdown_escape(const std::string& text, bool escape_code_blocks = false);

/**

Encodes a url parameter similar to php urlencode()

Parameters

  value | String to encode

Returns
  std::string URL encoded string

## ◆ user_mention()

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

Create a mentionable user.

Parameters

  id | The ID of the user.

Returns
  std::string The formatted mention of the user.

## ◆ user_url()

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

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

  str | string 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

  str | string to return substring from
  start | start codepoint offset
  length | length 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

  str | string to return substring from
  start | start codepoint offset
  length | length 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

  value | The value to validate
  _min | Minimum length
  _max | Maximum length
  exception_message | Exception message to throw if value length < _min

Returns
  std::string Validated string, truncated if necessary.

Exceptions

  dpp::length_exception | if value UTF8 length < _min

## ◆ version()

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

Returns the library's version string.

Returns
  std::string version

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

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

inline constexpr

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.

## ◆ url_host

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

inline

The base URL for message/user/channel links.

D++ Library version 9.0.13 D++ Library version 9.0.12 D++ Library version 9.0.11 D++ Library version 9.0.10 D++ Library version 9.0.9 D++ Library version 9.0.8 D++ Library version 9.0.7 D++ Library version 9.0.6 D++ Library version 9.0.5 D++ Library version 9.0.4 D++ Library version 9.0.3 D++ Library version 9.0.2 D++ Library version 9.0.1 D++ Library version 9.0.0 D++ Library version 1.0.2 D++ Library version 1.0.1 D++ Library version 1.0.0