dpp::utility Namespace Reference

Utility helper functions, generally for logging. 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...

Functions
void DPP_EXPORT	exec (const std::string &cmd, std::vector< std::string > parameters={}, cmd_result_t callback={})
	Run a commandline program asyncronously. 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 prameter. For example. More...
std::string DPP_EXPORT	timestamp (time_t ts, time_format tf)
	Return a mentionable timestamp (used in a discord embed) 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	rgb (float red, float green, float blue)
	Convert floats to RGB for sending in embeds. More...
uint32_t	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	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	avatar_size (uint32_t size)
	Return the url parameter for an avatar size, or empty if the size is 0. 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.

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.

Function Documentation

avatar_size()

std::string dpp::utility::avatar_size

(

uint32_t

size

)

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

Parameters

size	size to generate url parameter for

Returns

std::string url parameter

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

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

data	The start of the data to display
length	The 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 asyncronously. 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 prameter. For example.

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

Parameters

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

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)

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

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

filename

The path to the file to read

Returns

std::string The file contents

Exceptions

dpp::exception

on failure to read the entire file

rgb() [1/2]

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

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

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)

Parameters

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

Returns

std::string

utf8len()

size_t DPP_EXPORT dpp::utility::utf8len

(

const std::string &

str

)

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

Parameters

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

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

Returns

std::string Substring in UTF-8 or empty string if invalid UTF-8 passed in

validate()

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

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

Parameters

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

Returns

std::string Validated string, truncated if necessary.

Exceptions

dpp::length_exception

if value UTF8 length < _min

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.