randolf.ca  1.00
Randolf Richardson's C++ classes
Loading...
Searching...
No Matches
randolf::rtools Class Reference

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 <rtools>

+ Collaboration diagram for randolf::rtools:

Static Public Member Functions

static std::vector< std::string > * atomize (const char *str, size_t len=0)
 Split string into an std::vector that's perfectly-sized to store all the elements separated by whitespace, but not whitespace that's enclosed within quotation marks (literal quotation marks - " - will not be intrepreted, and will be treated as literal/non-functional non-whitespace characters).
 
static std::vector< std::string > * atomize (std::string str, size_t len=0)
 Split string into an std::vector that's perfectly-sized to store all the elements separated by whitespace, but not whitespace that's enclosed within quotation marks (literal quotation marks - " - will not be intrepreted, and will be treated as literal/non-functional non-whitespace characters).
 
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 delimiter, const char *str, const size_t len=-1)
 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, std::string str, const size_t len=-1)
 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::string to_hex (const int i) noexcept
 Convert a 32-bit integer 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, size_t len=1, const char *delimiter=nullptr) noexcept
 Convert an array of octets (8-bit bytes) to hexadecimal.
 
static std::string to_hex (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_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 (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 (char *data, size_t 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 (std::string &str, 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
Version
1.00
Author
Randolf Richardson

Member Function Documentation

◆ atomize() [1/2]

static std::vector< std::string > * randolf::rtools::atomize ( const char * str,
size_t len = 0 )
inlinestatic

Split string into an std::vector that's perfectly-sized to store all the elements separated by whitespace, but not whitespace that's enclosed within quotation marks (literal quotation marks - " - will not be intrepreted, and will be treated as literal/non-functional non-whitespace characters).

Any leading and/or trailing whitespace characters will be ignored.

Multiple whitespace delimiters will be treated as a single delimiter.

Whitespace characters:

  • 0: NULL
  • 9: Tab
  • 10: Linefeed
  • 13: Carriage Return
  • 32: Space
Returns
Pointer to an array of "atoms" stored in an std::vector object
Parameters
strSource string (to be split into atoms)
lenLength of string (in bytes), or 0 if str is an ASCIIZ string (NULL-terminated)

◆ atomize() [2/2]

static std::vector< std::string > * randolf::rtools::atomize ( std::string str,
size_t len = 0 )
inlinestatic

Split string into an std::vector that's perfectly-sized to store all the elements separated by whitespace, but not whitespace that's enclosed within quotation marks (literal quotation marks - " - will not be intrepreted, and will be treated as literal/non-functional non-whitespace characters).

Any leading and/or trailing whitespace characters will be ignored.

Multiple whitespace delimiters will be treated as a single delimiter.

Whitespace characters:

  • 0: NULL
  • 9: Tab
  • 10: Linefeed
  • 13: Carriage Return
  • 32: Space
Returns
Pointer to an array of "atoms" stored in an std::vector object
Parameters
strSource string (to be split into atoms)
lenLength of string (in bytes), or 0 if str is an ASCIIZ string (NULL-terminated)
Parameters
strSource string (to be split into atoms)
lenLength of string (in bytes), or 0 if str is an ASCIIZ string (NULL-terminated)

◆ 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
inASCIIZ string to decode
bBase64 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
inString to decode
bBase64 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
inString to encode
bBase64 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
inString to encode
bBase64 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
valuePointer to ASCII representation of numeric value
lenLength of value (in bytes), or 0 to auto-detect length if value string is an ASCIIZ string
skip_dotDon't insert any commas after the last period (or whatever string is set as the dot character)
digitsNumber of digits between commas
commaPointer to ASCIIZ comma character string (nullptr = disabled)
spacePointer to ASCIIZ space character string (nullptr = disabled) used instead of commas for non-digit fill-ins where commas would normally be inserted
dotPeriod 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_errorIf 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
saslUnparsed SASL exchange string (must not be Base64-encoded)
add_missing_keysEnsure the following keys exist, each with one empty string: nonce, nc, cnonce, qop, realm, username, digest-uri, authzid

◆ split() [1/2]

static std::vector< std::string > randolf::rtools::split ( const char delimiter,
std::string str,
const size_t len = -1 )
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.

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 (this behaviour might change in the future, so don't rely on it).
Returns
Pointer to an array of "atoms" (strings) stored in an std::vector object
Parameters
delimiterCharacter to use for the delimiter
strSource string (to be split)
lenLength of string (in bytes), or -1 if str is an ASCIIZ string (NULL-terminated)
Parameters
delimiterCharacter to use for the delimiter
strSource string (to be split into atoms)
lenLength of string (in bytes), or 0 if using the full length of the string

◆ split() [2/2]

static std::vector< std::string > randolf::rtools::split ( const char delimiter,
const char * str,
const size_t len = -1 )
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.

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 (this behaviour might change in the future, so don't rely on it).
Returns
Pointer to an array of "atoms" (strings) stored in an std::vector object
Parameters
delimiterCharacter to use for the delimiter
strSource string (to be split)
lenLength of string (in bytes), or -1 if str is an ASCIIZ string (NULL-terminated)

◆ to_hex() [1/4]

static std::string randolf::rtools::to_hex ( const void * data,
size_t 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
dataBinary data to convert to hexadecimal
lenLength 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
delimiterDelimiter 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 ( 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
dataBinary data to convert to hexadecimal
delimiterDelimiter 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
iInteger 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
iInteger 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
strSource string
in_place_conversionPerform in-place conversion (default is FALSE / non-destructive)
beginBegin conversion from this position (0 = first character)
Negative positions are caculated backward from the end of the string
lenNumber 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
strSource string
in_place_conversionPerform in-place conversion (default is FALSE / non-destructive)
beginBegin conversion from this position (0 = first character)
Negative positions are caculated backward from the end of the string
lenNumber 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 ( 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
strSource string

◆ wipe() [1/2]

static void randolf::rtools::wipe ( std::string & str,
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
strString to wipe
passesNumber of passes (default is 1)

◆ wipe() [2/2]

static void randolf::rtools::wipe ( char * data,
size_t 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
dataString to wipe
lenLength of string (-1 = ASCIIZ string)
passesNumber 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: