This rtools class primarily provides a collection of static methods that facilitate a variety of general-purpose computer programming needs. Separate classes may also be added in the future for more sophisticated needs. More...

#include <randolf/rtools>

Collaboration diagram for randolf::rtools:

Static Public Member Functions
static std::string	base64_decode (const char *in, const std::string &b=base64_set_plus_slash)
	Decode a Base64-encoded `ASCIIZ string`.

static std::string	base64_decode (const std::string &in, const std::string &b=base64_set_plus_slash)
	Decode a Base64-encoded `std::string`.

static std::string	base64_encode (const char *in, const std::string &b=base64_set_plus_slash)
	Encode an `ASCIIZ string` into Base64 format.

static std::string	base64_encode (const std::string &in, const std::string &b=base64_set_plus_slash)
	Encode an `std::string` into Base64 format.

static std::string	insert_commas (const char value, size_t len=0, bool skip_dot=true, const int digits=3, const char comma=",", const char *space=" ", const char dot='.') noexcept
	Insert commas into the last numeric sequence of digits in the supplied string and insert spaces before that (commas and spaces are configurable). If a decimal point is found, then comma insertions will only occur before that (this is also configurable).

static std::unordered_map< std::string, std::vector< std::string > >	parse_sasl_exchange (const std::string &sasl, const bool add_missing_keys=false)
	Parses a SASL exchange, returning an `std::unordered_map` of the key-value pairs that were encountered.

static std::vector< std::string >	split (const char *str, const int len=-1, const bool keep_empties=false)
	Split string into an `std::vector` that's perfectly-sized to store all the elements separated by whitespace characters. If no whitespace characters are encountered, the resulting vector will contain the entire string as its only element. If the string is empty, the resulting vector will contain an empty string as its only element.

static std::vector< std::string >	split (const char delimiter, const char *str, const int len=-1, const bool keep_empties=true)
	Split string into an `std::vector` that's perfectly-sized to store all the elements separated by a delimiter character. If no delimiters are encountered, the resulting vector will contain the entire string as its only element. If the string is empty, the resulting vector will contain an empty string as its only element.

static std::vector< std::string >	split (const char delimiter, const std::string &str, const int len=-1, const bool keep_empties=true)
	Split string into an `std::vector` that's perfectly-sized to store all the elements separated by a delimiter character. If no delimiters are encountered, the resulting vector will contain the entire string as its only element. If the string is empty, the resulting vector will contain an empty string as its only element.

static std::vector< std::string >	split (const std::string &str, const int len=-1, const bool keep_empties=false)
	Split string into an `std::vector` that's perfectly-sized to store all the elements separated by whitespace characters. If no whitespace characters are encountered, the resulting vector will contain the entire string as its only element. If the string is empty, the resulting vector will contain an empty string as its only element.

static std::string	to_hex (const int i) noexcept
	Convert a 32-bit integer to hexadecimal.

static std::string	to_hex (const std::string &data, const char *delimiter=nullptr) noexcept
	Convert an std::string's internal array of octets (8-bit bytes) to hexadecimal.

static std::string	to_hex (const unsigned int i) noexcept
	Convert a 32-bit unsigned integer to hexadecimal.

static std::string	to_hex (const void data, int len=1, const char delimiter=nullptr) noexcept
	Convert an array of octets (8-bit bytes) to hexadecimal.

static std::string	to_lower (std::string &str, bool in_place_conversion=false, const int begin=0, const int len=-1) noexcept
	Convert ASCII characters in an std::string to lower case. UTF-8 characters are not converted.

static std::string	to_upper (std::string &str, bool in_place_conversion=false, const int begin=0, const int len=-1) noexcept
	Convert ASCII characters in an std::string to upper case. UTF-8 characters are not converted.

static std::string	trim_quotes (const std::string &str) noexcept
	Removes the outer-most/enclosing set of quotation marks from the beginning and end of the specified String, but only if both are present.

static void	wipe (const char *data, int len=-1, unsigned int passes=1)
	Wipe the contents of the supplied data with random data by XOR'ing random unsigned char values with every character in the string.

static void	wipe (const std::string &str, const unsigned int passes=1)
	Wipe the contents of the supplied string with random data by XOR'ing random unsigned char values with every character in the string. The clear() method is not used because it's a waste of CPU cycles for a string that's just going to be de-allocated anyway.

Static Public Attributes
static const char	base64_set_minus_underscore [] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
	This character set is suggested by RFC4648 (see page 8) as "safe" for use in URLs and filenames.

static const char	base64_set_plus_comma [] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+,"
	This character set is normally used to encode IMAP4 mailbox names.

static const char	base64_set_plus_slash [] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
	This character set is the default in every `base64_` method in this library because it's the most commonly used for base64 encoding.

static const char	base64_set_plus_tilde [] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+~"
	This is an alternate character set that is rarely used, but is mentioned in RFC4648 (see page 7, second paragraph of section 5).

Detailed Description

This rtools class primarily provides a collection of static methods that facilitate a variety of general-purpose computer programming needs. Separate classes may also be added in the future for more sophisticated needs.

History

2023-May-17 v1.00 Initial version
2024-Oct-23 v1.00 Added three more well-known base64 sets, added support for base64 encoding/decoding to use ASCIIZ strings for inputs, and made various minor improvements to the documentation since the previous update
2024-Nov-24 v1.00 Added delimiter parameter to two to_hex methods
2024-Nov-25 v1.00 Added support for negative positions in to_lower and to_upper methods so that they count backward from the end of the string
2025-Jan-20 v1.00 Removed atomize methods after rebuilding these in a separate class called randolf::atomize
2025-Feb-03 v1.00 Increased use of references and pointers
2025-Apr-05 v1.00 Minor improvements to documentation

Version: 1.00

Author: Randolf Richardson

Member Function Documentation

◆ base64_decode() [1/2]

static std::string randolf::rtools::base64_decode	(	const char *	in,
		const std::string &	b = base64_set_plus_slash )

inlinestatic

Decode a Base64-encoded ASCIIZ string.

All invalid characters are simply ignored.

Returns: Decoded string

See also: base64_encode; base64_set_plus_slash

Parameters

in	ASCIIZ string to decode
b	Base64 character set to use

◆ base64_decode() [2/2]

static std::string randolf::rtools::base64_decode	(	const std::string &	in,
		const std::string &	b = base64_set_plus_slash )

inlinestatic

Decode a Base64-encoded std::string.

All invalid characters are simply ignored.

Returns: Decoded string

See also: base64_encode; base64_set_plus_slash

Parameters

in	String to decode
b	Base64 character set to use

◆ base64_encode() [1/2]

static std::string randolf::rtools::base64_encode	(	const char *	in,
		const std::string &	b = base64_set_plus_slash )

inlinestatic

Encode an ASCIIZ string into Base64 format.

All invalid characters are simply ignored.

Returns: Base64-encoded string

See also: base64_decode; base64_set_plus_slash

Parameters

in	String to encode
b	Base64 character set to use

◆ base64_encode() [2/2]

static std::string randolf::rtools::base64_encode	(	const std::string &	in,
		const std::string &	b = base64_set_plus_slash )

inlinestatic

Encode an std::string into Base64 format.

All invalid characters are simply ignored.

Returns: Base64-encoded string

See also: base64_decode; base64_set_plus_slash

Parameters

in	String to encode
b	Base64 character set to use

◆ insert_commas()

static std::string randolf::rtools::insert_commas	(	const char *	value,
		size_t	len = 0,
		bool	skip_dot = true,
		const int	digits = 3,
		const char *	comma = ",",
		const char *	space = " ",
		const char	dot = '.' )

inlinestaticnoexcept

Insert commas into the last numeric sequence of digits in the supplied string and insert spaces before that (commas and spaces are configurable). If a decimal point is found, then comma insertions will only occur before that (this is also configurable).

Returns: Numeric value as a char* array converted to a properly-delimited string as an std::string

Parameters

value	Pointer to ASCII representation of numeric value
len	Length of value (in bytes), or 0 to auto-detect length if value string is an ASCIIZ string
skip_dot	Don't insert any commas after the last period (or whatever string is set as the `dot` character)
digits	Number of digits between commas
comma	Pointer to ASCIIZ comma character string (nullptr = disabled)
space	Pointer to ASCIIZ space character string (nullptr = disabled) used instead of commas for non-digit fill-ins where commas would normally be inserted
dot	Period character used when `skip_dot` is enabled

◆ parse_sasl_exchange()

static std::unordered_map< std::string, std::vector< std::string > > randolf::rtools::parse_sasl_exchange	(	const std::string &	sasl,
		const bool	add_missing_keys = false )

inlinestatic

Parses a SASL exchange, returning an std::unordered_map of the key-value pairs that were encountered.

Exceptions

std::runtime_error If a SASL message is improperly formatted (the error message includes the offset where the format problem occurred)

Returns: Key-value pairs in an unordered map where the key is an std::string object and the value is a vector of std::string objects

Parameters

sasl	Unparsed SASL exchange string (must not be Base64-encoded)
add_missing_keys	Ensure the following keys exist, each with one empty string: nonce, nc, cnonce, qop, realm, username, digest-uri, authzid

◆ split() [1/4]

static std::vector< std::string > randolf::rtools::split	(	const char	delimiter,
		const std::string &	str,
		const int	len = -1,
		const bool	keep_empties = true )

inlinestatic

Split string into an std::vector that's perfectly-sized to store all the elements separated by a delimiter character. If no delimiters are encountered, the resulting vector will contain the entire string as its only element. If the string is empty, the resulting vector will contain an empty string as its only element.

By default, we do keep_empties when a delimiter character is specified because the character may be a comma ("`,`") for use in parsing a simple list of items where position is important (e.g., simple CSV data), or may be a tab (ASCII character 9) for use in parsing where position is also important.

Precondition: Using (char)0 as a delimiter necessitates specifying the length of the source string, otherwise the resulting vector will contain only the first element.

Returns: Pointer to an array of "atoms" (strings) stored in an std::vector object

Parameters

delimiter	Character to use for the delimiter
str	Source string (to be split)
len	Length of string (in bytes), or -1 if `str` is an ASCIIZ string (NULL-terminated)
keep_empties	Whether to include empty entries TRUE = keep empty entries (default) FALSE = exclude empty entries

Parameters

delimiter	Character to use for the delimiter
str	Source string (to be split into atoms)
len	Length of string (in bytes), or 0 if using the full length of the string
keep_empties	Whether to include empty entries TRUE = keep empty entries (default) FALSE = exclude empty entries

◆ split() [2/4]

static std::vector< std::string > randolf::rtools::split	(	const char	delimiter,
		const char *	str,
		const int	len = -1,
		const bool	keep_empties = true )

inlinestatic

Split string into an std::vector that's perfectly-sized to store all the elements separated by a delimiter character. If no delimiters are encountered, the resulting vector will contain the entire string as its only element. If the string is empty, the resulting vector will contain an empty string as its only element.

By default, we do keep_empties when a delimiter character is specified because the character may be a comma ("`,`") for use in parsing a simple list of items where position is important (e.g., simple CSV data), or may be a tab (ASCII character 9) for use in parsing where position is also important.

Precondition: Using (char)0 as a delimiter necessitates specifying the length of the source string, otherwise the resulting vector will contain only the first element.

Returns: Pointer to an array of "atoms" (strings) stored in an std::vector object

Parameters

delimiter	Character to use for the delimiter
str	Source string (to be split)
len	Length of string (in bytes), or -1 if `str` is an ASCIIZ string (NULL-terminated)
keep_empties	Whether to include empty entries TRUE = keep empty entries (default) FALSE = exclude empty entries

◆ split() [3/4]

static std::vector< std::string > randolf::rtools::split	(	const std::string &	str,
		const int	len = -1,
		const bool	keep_empties = false )

inlinestatic

Split string into an std::vector that's perfectly-sized to store all the elements separated by whitespace characters. If no whitespace characters are encountered, the resulting vector will contain the entire string as its only element. If the string is empty, the resulting vector will contain an empty string as its only element.

By default, we don't keep_empties when filtering on hardcoded internal whitespace because the CRLF EoL (End of Line) sequence is common.

Note

The following are whitespace characters, and they are tested for in the order shown here (which is optimized for what is most common):

32 space
10 linefeed
13 carriage return
9 horizontal tab
0 NULL terminator

Returns: Pointer to an array of "atoms" (strings) stored in an std::vector object

Parameters

str	Source string (to be split)
len	Length of string (in bytes), or -1 if `str` is an ASCIIZ string (NULL-terminated)
keep_empties	Whether to include empty entries TRUE = keep empty entries FALSE = exclude empty entries (default)

Parameters

str	Source string (to be split into atoms)
len	Length of string (in bytes), or 0 if using the full length of the string
keep_empties	Whether to include empty entries TRUE = keep empty entries FALSE = exclude empty entries (default)

◆ split() [4/4]

static std::vector< std::string > randolf::rtools::split	(	const char *	str,
		const int	len = -1,
		const bool	keep_empties = false )

inlinestatic

Split string into an std::vector that's perfectly-sized to store all the elements separated by whitespace characters. If no whitespace characters are encountered, the resulting vector will contain the entire string as its only element. If the string is empty, the resulting vector will contain an empty string as its only element.

By default, we don't keep_empties when filtering on hardcoded internal whitespace because the CRLF EoL (End of Line) sequence is common.

Note

The following are whitespace characters, and they are tested for in the order shown here (which is optimized for what is most common):

32 space
10 linefeed
13 carriage return
9 horizontal tab
0 NULL terminator

Returns: Pointer to an array of "atoms" (strings) stored in an std::vector object

Parameters

str	Source string (to be split)
len	Length of string (in bytes), or -1 if `str` is an ASCIIZ string (NULL-terminated)
keep_empties	Whether to include empty entries TRUE = keep empty entries FALSE = exclude empty entries (default)

◆ to_hex() [1/4]

static std::string randolf::rtools::to_hex	(	const void *	data,
		int	len = 1,
		const char *	delimiter = nullptr )

inlinestaticnoexcept

Convert an array of octets (8-bit bytes) to hexadecimal.

Returns: std::string of hexadecimal characters (in lower case)

Parameters

data	Binary data to convert to hexadecimal
len	Length of array (in 8-bit bytes), which can be as short as 0; if -1, then the length of the data will be measured as an ASCIIZ string; default is 1 if not specified since this is the safest option
delimiter	Delimiter character sequence (ASCIIZ string) to insert between multiple pairs of nybbles `nullptr` = no delimiter (default)

◆ to_hex() [2/4]

static std::string randolf::rtools::to_hex	(	const std::string &	data,
		const char *	delimiter = nullptr )

inlinestaticnoexcept

Convert an std::string's internal array of octets (8-bit bytes) to hexadecimal.

Returns: std::string of hexadecimal characters (in lower case)

Parameters

data	Binary data to convert to hexadecimal
delimiter	Delimiter character sequence (ASCIIZ string) to insert between multiple pairs of nybbles `nullptr` = no delimiter (default)

◆ to_hex() [3/4]

static std::string randolf::rtools::to_hex ( const int i )

inlinestaticnoexcept

Convert a 32-bit integer to hexadecimal.

This method is needed because std::to_string() doesn't include an option to specify the radix.

Returns: Up to 8 hexadecimal characters

Parameters

i	Integer to convert to hexadecimal

◆ to_hex() [4/4]

static std::string randolf::rtools::to_hex ( const unsigned int i )

inlinestaticnoexcept

Convert a 32-bit unsigned integer to hexadecimal.

This method is needed because std::to_string() doesn't include an option to specify the radix.

Returns: Up to 8 hexadecimal characters

Parameters

i	Integer to convert to hexadecimal

◆ to_lower()

static std::string randolf::rtools::to_lower	(	std::string &	str,
		bool	in_place_conversion = false,
		const int	begin = 0,
		const int	len = -1 )

inlinestaticnoexcept

Convert ASCII characters in an std::string to lower case. UTF-8 characters are not converted.

Returns: Copy of std::string, in lower-case form

See also: to_upper

Parameters

str	Source string
in_place_conversion	Perform in-place conversion (default is FALSE / non-destructive)
begin	Begin conversion from this position (0 = first character) Negative positions are caculated backward from the end of the string
len	Number of characters to convert (values exceeding string length will not cause any exceptions as the excess will be effectively ignored) -1 = maximum number of characters (a.k.a., until end of string)

◆ to_upper()

static std::string randolf::rtools::to_upper	(	std::string &	str,
		bool	in_place_conversion = false,
		const int	begin = 0,
		const int	len = -1 )

inlinestaticnoexcept

Convert ASCII characters in an std::string to upper case. UTF-8 characters are not converted.

Returns: Copy of std::string, in upper-case form

See also: to_lower

Parameters

str	Source string
in_place_conversion	Perform in-place conversion (default is FALSE / non-destructive)
begin	Begin conversion from this position (0 = first character) Negative positions are caculated backward from the end of the string
len	Number of characters to convert (values exceeding string length will not cause any exceptions as the excess will be effectively ignored) -1 = maximum number of characters (a.k.a., until end of string)

◆ trim_quotes()

static std::string randolf::rtools::trim_quotes ( const std::string & str )

inlinestaticnoexcept

Removes the outer-most/enclosing set of quotation marks from the beginning and end of the specified String, but only if both are present.

Returns: Copy of std::string, with quotation marks removed (if both were present)

Parameters

str	Source string

◆ wipe() [1/2]

static void randolf::rtools::wipe	(	const std::string &	str,
		const unsigned int	passes = 1 )

inlinestatic

Wipe the contents of the supplied string with random data by XOR'ing random unsigned char values with every character in the string. The clear() method is not used because it's a waste of CPU cycles for a string that's just going to be de-allocated anyway.

Warning: This method calls srand() with high resolution time once before starting the loop that calls the std::rand() function. (Only the first 8 bits returned by std::rand() are used; the remaining higher bits are not used.)

Parameters

str	String to wipe
passes	Number of passes (default is 1)

◆ wipe() [2/2]

static void randolf::rtools::wipe	(	const char *	data,
		int	len = -1,
		unsigned int	passes = 1 )

inlinestatic

Wipe the contents of the supplied data with random data by XOR'ing random unsigned char values with every character in the string.

Warning: This method calls srand() with high resolution time once before starting the loop that calls the std::rand() function. (Only the first 8 bits returned by std::rand() are used; the remaining higher bits are not used.)

Parameters

data	String to wipe
len	Length of string (-1 = ASCIIZ string)
passes	Number of passes (default is 1)

Member Data Documentation

◆ base64_set_minus_underscore

const char randolf::rtools::base64_set_minus_underscore[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"

inlinestatic

This character set is suggested by RFC4648 (see page 8) as "safe" for use in URLs and filenames.

See also: base64_decode; base64_encode

◆ base64_set_plus_comma

const char randolf::rtools::base64_set_plus_comma[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+,"

inlinestatic

This character set is normally used to encode IMAP4 mailbox names.

See also: base64_decode; base64_encode

◆ base64_set_plus_slash

const char randolf::rtools::base64_set_plus_slash[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"

inlinestatic

This character set is the default in every base64_ method in this library because it's the most commonly used for base64 encoding.

Note: Although other well-known base64 character sets are included here, or you can create your own, which has a simple format – it must be 64 characters long without a NULL terminator (additional characters will be ignored), and each character can only be specified once (or else encoding or decoding will fail to render consistent results; there's no checking performed beforehand since the software developers providing these customized character sets are trusted to not introduce such problems).

See also: base64_decode; base64_encode

◆ base64_set_plus_tilde

const char randolf::rtools::base64_set_plus_tilde[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+~"

inlinestatic

This is an alternate character set that is rarely used, but is mentioned in RFC4648 (see page 7, second paragraph of section 5).

Note: RFC4648 incorrectly specifies the 63rd character when it's the 64th character (the slash) that's being replaced with a tilde. This error likely came from not counting the zero "value" label when referencing the set in which the 1st character is labeled as having a value of 0.

See also: base64_decode; base64_encode

The documentation for this class was generated from the following file:

randolf/rtools

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Function Documentation

◆ base64_decode() [1/2]

◆ base64_decode() [2/2]

◆ base64_encode() [1/2]

◆ base64_encode() [2/2]

◆ insert_commas()

◆ parse_sasl_exchange()

◆ split() [1/4]

◆ split() [2/4]

◆ split() [3/4]

◆ split() [4/4]

◆ to_hex() [1/4]

◆ to_hex() [2/4]

◆ to_hex() [3/4]

◆ to_hex() [4/4]

◆ to_lower()

◆ to_upper()

◆ trim_quotes()

◆ wipe() [1/2]

◆ wipe() [2/2]

Member Data Documentation

◆ base64_set_minus_underscore

◆ base64_set_plus_comma

◆ base64_set_plus_slash

◆ base64_set_plus_tilde