randolf.ca  1.00
Randolf's C++ classes
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...

+ 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). More...
 
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). More...
 
static std::string base64_decode (const std::string &in, const std::string b=base64_plus_slash)
 Decode a Base64-encoded std::string. More...
 
static std::string base64_encode (const std::string &in, const std::string b=base64_plus_slash)
 Encode an std::string into Base64 format. More...
 
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 occur before that (this is also configurable). More...
 
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. More...
 
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. More...
 
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. More...
 
static std::string to_hex (const int i) noexcept
 Convert a 32-bit integer to hexadecimal. More...
 
static std::string to_hex (const unsigned int i) noexcept
 Convert a 32-bit unsigned integer to hexadecimal. More...
 
static std::string to_hex (const void *data, size_t len=1) noexcept
 Convert an array of octets (8-bit bytes) to hexadecimal. More...
 
static std::string to_hex (std::string data) noexcept
 Convert an std::string's internal array of octets (8-bit bytes) to hexadecimal. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 

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 rtools v1.00 by 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)

◆ base64_decode()

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

Decode a Base64-encoded std::string.

All invalid characters are simply ignored.

Returns
Decoded string
See also
base64_encode
Parameters
inString to decode
bBase64 character set to use

◆ base64_encode()

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

Encode an std::string into Base64 format.

All invalid characters are simply ignored.

Returns
Base64-encoded string
See also
base64_decode
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 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)
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 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 
)
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

◆ to_hex() [2/4]

static std::string randolf::rtools::to_hex ( std::string  data)
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

◆ 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)
lenNumber of characters to convert (-1 = maximum number of characters)

◆ 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)
lenNumber of characters to convert (-1 = maximum number of characters)

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

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