rtools

#pragma once
 
#include <algorithm>          // std::max and std::min
#include <array>              // std::array
#include <cstring>            // std::strlen
#include <ctime>              // std::time
#include <exception>          // std::exception::runtime_error
#include <iostream>           // std::cout
#include <stdexcept>          // std::runtime_error
#include <string>             // std::string
#include <unordered_map>      // std::unordered_map
#include <vector>             // std::vector
 
namespace randolf {
 
  /*======================================================================*//**
  @brief
  This @ref 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.
  @par 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&nbsp;strings
                        for inputs, and made various minor improvements to the
                        documentation since the previous update
    - 2024-Nov-24 v1.00 Added @c delimiter parameter to two @ref to_hex methods
    - 2024-Nov-25 v1.00 Added support for negative positions in @ref to_lower
                        and @ref 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 @ref randolf::Atomize
  @version 1.00
  @author Randolf Richardson
  *///=========================================================================
  class rtools {
 
    public:
      /*======================================================================*//**
      @brief
      This character set is suggested by RFC4648 (see page 8) as "safe" for use in
      URLs and filenames.
      @see base64_decode
      @see base64_encode
      *///=========================================================================
      inline static const char base64_set_minus_underscore[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
 
      /*======================================================================*//**
      @brief
      This character set is normally used to encode IMAP4 mailbox names.
      @see base64_decode
      @see base64_encode
      *///=========================================================================
      inline static const char base64_set_plus_comma[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+,";
 
      /*======================================================================*//**
      @brief
      This character set is the default in every @c 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 base64_decode
      @see base64_encode
      *///=========================================================================
      inline static const char base64_set_plus_slash[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
 
      /*======================================================================*//**
      @brief
      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 base64_decode
      @see base64_encode
      *///=========================================================================
      inline static const char base64_set_plus_tilde[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+~";
 
      /*======================================================================*//**
      @brief
      Decode a Base64-encoded @c ASCIIZ&nbsp;string.
 
      All invalid characters are simply ignored.
      @returns Decoded string
      @see base64_encode
      @see base64_set_plus_slash
      *///=========================================================================
      static std::string base64_decode(
      /// ASCIIZ string to decode
      const char *in,
      /// Base64 character set to use
      const std::string b = base64_set_plus_slash) {
        std::string out;
        std::vector<int> T(256, -1);
        int val  = 0;
        int valb = -8;
        for (int i = 0; i < 64; i++) T[b[i]] = i;
 
        unsigned char c;
        while ((c = (unsigned char)*in++) != 0) {
          if (T[c] == -1) break;
          val = (val << 6) + T[c];
          valb += 6;
          if (valb >= 0) {
            out.push_back(char((val >> valb) & 0xFF));
            valb -= 8;
          } // -x- if valb -x-
        } // -x- while c -x-
        return out;
      } // -x- std::string base64_decode -x-
 
      /*======================================================================*//**
      @brief
      Decode a Base64-encoded @c std::string.
 
      All invalid characters are simply ignored.
      @returns Decoded string
      @see base64_encode
      @see base64_set_plus_slash
      *///=========================================================================
      static std::string base64_decode(
      /// String to decode
      const std::string &in,
      /// Base64 character set to use
      const std::string b = base64_set_plus_slash) {
        std::string out;
        std::vector<int> T(256, -1);
        int val  = 0;
        int valb = -8;
        for (int i = 0; i < 64; i++) T[b[i]] = i;
 
        for (unsigned char c: in) {
          if (T[c] == -1) break;
          val = (val << 6) + T[c];
          valb += 6;
          if (valb >= 0) {
            out.push_back(char((val >> valb) & 0xFF));
            valb -= 8;
          } // -x- if valb -x-
        } // -x- for c -x-
        return out;
      } // -x- std::string base64_decode -x-
 
      /*======================================================================*//**
      @brief
      Encode an @c ASCIIZ&nbsp;string into Base64 format.
 
      All invalid characters are simply ignored.
      @returns Base64-encoded string
      @see base64_decode
      @see base64_set_plus_slash
      *///=========================================================================
      static std::string base64_encode(
      /// String to encode
      const char *in,
      /// Base64 character set to use
      const std::string b = base64_set_plus_slash) {
        std::string out;
        int val  = 0;
        int valb =- 6;
 
        unsigned char c;
        while ((c = (unsigned char)*in++) != 0) {
          val = (val << 8) + c;
          valb += 8;
          while (valb >= 0) {
            out.push_back(b[(val >> valb) & 0x3F]);
            valb -= 6;
          } // -x- while valb -x-
        } // -x- for c -x-
        if (valb >- 6) out.push_back(b[((val << 8) >> (valb + 8)) & 0x3F]);
        while (out.size() % 4) out.push_back('=');
        return out;
      } // -x- std::string base64_encode -x-
 
      /*======================================================================*//**
      @brief
      Encode an @c std::string into Base64 format.
 
      All invalid characters are simply ignored.
      @returns Base64-encoded string
      @see base64_decode
      @see base64_set_plus_slash
      *///=========================================================================
      static std::string base64_encode(
      /// String to encode
      const std::string &in,
      /// Base64 character set to use
      const std::string b = base64_set_plus_slash) {
        std::string out;
        int val  = 0;
        int valb =- 6;
 
        for (unsigned char c: in) {
          val = (val << 8) + c;
          valb += 8;
          while (valb >= 0) {
            out.push_back(b[(val >> valb) & 0x3F]);
            valb -= 6;
          } // -x- while valb -x-
        } // -x- for c -x-
        if (valb >- 6) out.push_back(b[((val << 8) >> (valb + 8)) & 0x3F]);
        while (out.size() % 4) out.push_back('=');
        return out;
      } // -x- std::string base64_encode -x-
 
      /*======================================================================*//**
      @brief
      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
      *///=========================================================================
      static std::string insert_commas(
      /// Pointer to ASCII representation of numeric value
      const char* value,
      /// Length of value (in bytes), or 0 to auto-detect length if value string is an ASCIIZ string
      size_t len = 0,
      /// Don't insert any commas after the last period (or whatever string is set as the @c dot character)
      bool skip_dot = true,
      /// Number of digits between commas
      const int digits = 3,
      /// Pointer to ASCIIZ comma character string (nullptr = disabled)
      const char* comma = ",",
      /// Pointer to ASCIIZ space character string (nullptr = disabled) used instead of commas for non-digit fill-ins where commas would normally be inserted
      const char* space = " ",
      /// Period character used when @c skip_dot is enabled
      const char dot = '.') noexcept {
 
        // --------------------------------------------------------------------------
        // Measure size of format string if an ASCIIZ string was indicated.
        // --------------------------------------------------------------------------
        if (len == 0) len = std::strlen(value);
 
        // --------------------------------------------------------------------------
        // Find the dot, and adjust len accordingly.
        // --------------------------------------------------------------------------
        for (int i = len - 1; i > 0; i--) {
          if (value[i] == dot) {
            len = i;
            break;
          } // -x- if dot -x-
        } // -x- for i -x-
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        std::string v(value, len);
        const int   m     = len % digits; // Modulus for every 3rd character
        bool        blank = false; // Add blank space instead of comma
 
        // --------------------------------------------------------------------------
        // Insert commas as long as there are digits.
        // --------------------------------------------------------------------------
        for (int i = len - 1; i > 0; i--) {
          if (v[i] < '0' || v[i] > '9') blank = true; // Not a digit, so we're switching from commas to blanks (spaces)
          if ((i % digits) == m) { // This is where a separator belongs
            if     (!blank && comma != nullptr) v.insert(i, comma); // Insert comma, if one is defined
            else if (blank && space != nullptr) v.insert(i, space); // Insert space, if one is defined
          } // -x- if m -x-
        } // -x- for i -x-
 
        return v;
      } // -x- std::string insert_commas -x-
 
      /*======================================================================*//**
      @brief
      Parses a SASL exchange, returning an @c std::unordered_map of the key-value
      pairs that were encountered.
      @throws 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
      *///=========================================================================
      static std::unordered_map<std::string, std::vector<std::string>> parse_sasl_exchange(
      /// Unparsed SASL exchange string (must not be Base64-encoded)
      const std::string sasl,
      /// Ensure the following keys exist, each with one empty string:  nonce, nc, cnonce, qop, realm, username, digest-uri, authzid
      const bool add_missing_keys = false) {
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        std::unordered_map<std::string, std::vector<std::string>> map;
        char                     ch; // Used in string parsing
        std::string              temp; // Used to build current element
        std::string              key; // Key name
        bool                     keyMode   = true; // TRUE = parsing key name; FALSE = parsing value
        bool                     quoteMode = false; // Used for tracking "quote mode" with quotation mark usage
        int                      offset    = -1; // Offset within the unparsed string of the character currently being processed
        const int                MAX       = sasl.size();
 
        // --------------------------------------------------------------------------
        // Parse the string, one character at a time.
        // --------------------------------------------------------------------------
        for (int offset = 0; offset < MAX; offset++) {
          switch (ch = sasl[offset]) {
            case '"': // Quotation mark
              if (keyMode) throw std::runtime_error("Key names can't contain quotation marks at offset " + std::to_string(offset));
              if (!quoteMode && temp.length() > 0) throw std::runtime_error("Malformed quoted value at offset " + std::to_string(offset));
              quoteMode = !quoteMode; // Toggle "quote mode"
              temp.push_back(ch); // Save quotation mark
              break;
            case '\\': // Back-slash
              if (keyMode) throw std::runtime_error("Key names can't contain escaped literal characters at offset " + std::to_string(offset));
              ch = sasl[++offset]; // Get next character after incrementing offset
              if (offset >= MAX) throw std::runtime_error("Literal character is missing at offset " + std::to_string(offset));
              if (ch < ' ' || ch == 127) throw std::runtime_error("Invalid charater at offset " + std::to_string(offset)); // Any characters except CTLs and separators
              temp.push_back('\\'); // Save backslash
              temp.push_back(ch); // Save literal character
              break;
            case ' ': // Space
              if (!quoteMode) throw std::runtime_error("White space characters not permitted at offset " + std::to_string(offset));
              temp.push_back(ch);
              break;
            case '=': // Equal sign (signifies end of key, and beginning of value)
              if (quoteMode) {
                temp.push_back(ch);
                break;
              }
              if (!keyMode) throw std::runtime_error("Invalid character at offset " + std::to_string(offset));
              keyMode = !keyMode; // Toggle flag
              if (temp.length() == 0) throw std::runtime_error("Missing key name at offset " + std::to_string(offset));
              key = temp; // Save string for later
              temp = ""; // Clear temporary string
              break;
            case ',': // Comma delimiter (signifies end of value)
              if (quoteMode) {
                temp.push_back(ch);
                break;
              }
              if (keyMode) throw std::runtime_error("Invalid character at offset " + std::to_string(offset));
              keyMode = !keyMode; // Toggle flag
              if (temp[0] == '"' && temp[temp.length() - 1] != '"') throw std::runtime_error("Malformed quoted value at offset " + std::to_string(offset));
              map[key].push_back(temp);
              temp = "";
              break;
            default: // Everything else is a literal character
              if (ch < ' ' || ch == 127) throw std::runtime_error("Invalid character at offset " + std::to_string(offset)); // Any characters except CTLs and separators
              if (keyMode && (std::string("()<>@,;:\\\"/[]?={} ").find_first_of(ch) != std::string::npos)) throw std::runtime_error("Invalid character at offset " + std::to_string(offset));
              temp.push_back(ch);
              break;
          } // -x- switch ch -x-
        } // -x- for ch -x-
 
        // --------------------------------------------------------------------------
        // Syntax checks.  There is no need to check for additional data because we
        // added a comma to the unparsed_string -- if the original unparsed_string
        // had a trailing comma, then an exception would have been thrown already.
        // --------------------------------------------------------------------------
        if (quoteMode) throw std::runtime_error("Incomplete value at offset " + std::to_string(offset));
 
        // --------------------------------------------------------------------------
        // Save last key-value pair if we're not in keyMode.
        // --------------------------------------------------------------------------
        if (!keyMode) map[key].push_back(temp);
 
        // --------------------------------------------------------------------------
        // Add missing keys, each with one empty string.
        // --------------------------------------------------------------------------
        if (add_missing_keys) {
          if (map.try_emplace("nonce",      std::vector<std::string>()).second) { map["nonce"     ].push_back(""); };
          if (map.try_emplace("nc",         std::vector<std::string>()).second) { map["nc"        ].push_back(""); };
          if (map.try_emplace("cnonce",     std::vector<std::string>()).second) { map["cnonce"    ].push_back(""); };
          if (map.try_emplace("qop",        std::vector<std::string>()).second) { map["qop"       ].push_back(""); };
          if (map.try_emplace("realm",      std::vector<std::string>()).second) { map["realm"     ].push_back(""); };
          if (map.try_emplace("username",   std::vector<std::string>()).second) { map["username"  ].push_back(""); };
          if (map.try_emplace("digest-uri", std::vector<std::string>()).second) { map["digest-uri"].push_back(""); };
          if (map.try_emplace("authzid",    std::vector<std::string>()).second) { map["authzid"   ].push_back(""); };
        } // -x- if add_missing_keys -x-
 
        // --------------------------------------------------------------------------
        // Return the newly-created unordered_map.
        // --------------------------------------------------------------------------
        return map;
 
      } // -x- std::unordered_map<std::string, std::vector<std::string>> parse_sasl_exchange -x-
 
      /*======================================================================*//**
      @copydoc split(const char, const char*, const size_t)
      *///=========================================================================
      static std::vector<std::string> split(
      /// Character to use for the delimiter
      const char delimiter,
      /// Source string (to be split into atoms)
      std::string str,
      /// Length of string (in bytes), or 0 if using the full length of the string
      const size_t len = -1) {
        return split(delimiter, str.data(), len >= -1 ? str.size() : len);
      } // -x- std::vector<std::string> split -x-
 
      /*======================================================================*//**
      @brief
      Split string into an @c 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.
 
      @pre
      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 @c std::vector
      object
      *///=========================================================================
      static std::vector<std::string> split(
      /// Character to use for the delimiter
      const char   delimiter,
      /// Source string (to be split)
      const char*  str,
      /// Length of string (in bytes), or -1 if @c str is an ASCIIZ string (NULL-terminated)
      const size_t len = -1) { // TODO:  Add support for a "maximum_elements" parameter
 
        // --------------------------------------------------------------------------
        // Internal variables.
        //
        // Includes not measuring size of string if an ASCIIZ string was indicated
        // because "if (len == -1) len = std::strlen(str);" is less optimal than what
        // the main loop already does in this regard.
        // --------------------------------------------------------------------------
        const char*   MAX = len == -1 ? (char*)-1 : str + len; // Loop pre-optimization
        std::string* atom = new std::string();
 
        // --------------------------------------------------------------------------
        // Pre-allocate std::vector with a size that's half the length of the string,
        // because this is the maximum number of atoms there could be if each atom is
        // 1 byte long and each delimiting whitespace character is also 1 byte long.
        // --------------------------------------------------------------------------
        std::vector<std::string> ary;
        if (len > 0) ary.reserve(len >> (1 + 1)); // Ensure array-like efficiency
 
        // --------------------------------------------------------------------------
        // Main loops.
        //
        // Optimization:  By using separate loops for a non-NULL delimiter from the
        //                NULL delimiter, both loops are faster and less complicated.
        // --------------------------------------------------------------------------
        if (delimiter != (char)0) { // Process using non-NULL delimiter
          do {
            if (*str == delimiter) { // Delimiter character
              ary.push_back(*atom);    // Save current atom to vector
              atom = new std::string(); // Create new atom (string)
            } else {
              atom->append(str, 1);     // Add this character to the atom
            } // -x- if delimiter -x-
          } while (*str != (char)0 && ++str < MAX); // -x- while str -x-
 
          // --------------------------------------------------------------------------
          // If we're not in delimited mode, and the current string is not empty, then
          // add it to the vector as the final atom.
          //
          // Memory leak prevention (we don't need any free radicals taking up memory!
          // {yes, I had fun writing this, and whether or not you like it, you can't
          // deny the cleverness of this pun}):  Because of the way the loop (above) is
          // structured, there will never be a memory leak here resulting from trailing
          // non-delimiter characters because a new atom is created only when a first
          // delimiter character is encountered.
          // --------------------------------------------------------------------------
          ary.push_back(*atom);
 
        // --------------------------------------------------------------------------
        // Process NULL delimiter.
        // --------------------------------------------------------------------------
        } else { // Process using NULL delimiter
          do {
            if (*str == (char)0) { // NULL delimiter
              if (len == 0) break;
              ary.push_back(*atom);    // Save current atom to vector
              atom = new std::string(); // Create new atom (string)
            } else { // -x- if *str -x-
              atom->append(str, 1);     // Add this character to the atom
            } // -x- if (char)0 -x-
          } while (str++ < MAX); // -x- while str -x-
        } // -x- if delimiter -x-
 
        // --------------------------------------------------------------------------
        // Shrink the array before returning it so sizing can be considered properly
        // and unneeded memory can be freed.
        // --------------------------------------------------------------------------
        ary.shrink_to_fit(); // TODO:  Make this optional with a flag called RTOOLS_SHRINK
 
        return ary;
      } // -x- std::vector<std::string> split -x-
 
      /*======================================================================*//**
      @brief
      Convert an array of octets (8-bit bytes) to hexadecimal.
 
      @returns std::string of hexadecimal characters (in lower case)
      *///=========================================================================
      static std::string to_hex(
      /// Binary data to convert to hexadecimal
      const void* data,
      /// 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
      size_t len = 1,
      /// Delimiter character sequence (ASCIIZ string) to insert between multiple
      /// pairs of nybbles@n
      /// @c nullptr = no delimiter (default)
      const char* delimiter = nullptr) noexcept {
        std::string h; // Target string
        char buf[3]; // Temporary buffer for use by snprintf()
        if (len == -1) len = std::strlen((const char*)data); // Measure as if ASCIIZ string if length is 0
        for(int i = 0; i < len; i++) {
          if (delimiter != nullptr && i > 0) h.append(delimiter);
          snprintf(buf, (size_t)3, "%02x", ((const unsigned char*)data)[i]);
          h.append(buf);
        } // -x- for i -x-
        return h;
      } // -x- std::string to_hex -x-
 
      /*======================================================================*//**
      @brief
      Convert an std::string's internal array of octets (8-bit bytes) to
      hexadecimal.
 
      @returns std::string of hexadecimal characters (in lower case)
      *///=========================================================================
      static std::string to_hex(
      /// Binary data to convert to hexadecimal
      std::string data,
      /// Delimiter character sequence (ASCIIZ string) to insert between multiple
      /// pairs of nybbles@n
      /// @c nullptr = no delimiter (default)
      const char* delimiter = nullptr) noexcept { return to_hex(data.data(), data.size(), delimiter); } // -x- std::string to_hex -x-
 
      /*======================================================================*//**
      @brief
      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
      *///=========================================================================
      static std::string to_hex(
      /// Integer to convert to hexadecimal
      const int i) noexcept {
        std::string h;
        h.resize(9); // 32-bit integer needs 8 nybbles to be represented in hexadecimal plus a NULL terminator
        h.resize(snprintf(h.data(), h.size(), "%x", i)); // Convert to hexadecimal, and truncate NULL terminator
        return h;
      } // -x- std::string to_hex -x-
 
      /*======================================================================*//**
      @brief
      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
      *///=========================================================================
      static std::string to_hex(
      /// Integer to convert to hexadecimal
      const unsigned int i) noexcept {
        std::string h;
        h.resize(9); // 32-bit integer needs 8 nybbles to be represented in hexadecimal plus a NULL terminator
        h.resize(snprintf(h.data(), h.size(), "%x", i)); // Convert to hexadecimal, and truncate NULL terminator
        return h;
      } // -x- std::string to_hex -x-
 
      /*======================================================================*//**
      @brief
      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 to_upper
      *///=========================================================================
      static std::string to_lower(
      /// Source string
      std::string& str,
      /// Perform in-place conversion (default is FALSE / non-destructive)
      bool in_place_conversion = false,
      /// Begin conversion from this position (0 = first character)@n
      /// Negative positions are caculated backward from the end of the string
      const int begin = 0,
      /// Number of characters to convert (values exceeding string length will not
      /// cause any exceptions as the excess will be effectively ignored)@n
      /// -1 = maximum number of characters (a.k.a., until end of string)
      const int len = -1) noexcept {
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        const int BEGIN = begin >=  0 ? begin : str.length() + begin; // Calculate negative values from end of string
        const int MAX   = len   == -1 ? str.length() : std::min(str.length(), (size_t)(begin + len)); // Optimization:  For faster loop operations
 
        // --------------------------------------------------------------------------
        // Perform in-place conversion.
        // --------------------------------------------------------------------------
        if (in_place_conversion) {
          for (int i = BEGIN; i < MAX; i++) {
            char ch = str.at(i);
            if (ch >= 'A' && ch <= 'Z') str.at(i) = ch += 32; // Convert to lower-case
          } // -x- for i -x-
          return str; // Return updated string
        } // -x- if in_place_conversion -x-
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        std::string new_string = str; // Copy string (this allocates additional memory)
 
        // --------------------------------------------------------------------------
        // Perform isolated conversion.
        // --------------------------------------------------------------------------
        for (int i = BEGIN; i < MAX; i++) {
          char ch = str.at(i);
          if (ch >= 'A' && ch <= 'Z') new_string.at(i) = ch += 32; // Convert to lower-case
        } // -x- for i -x-
        return new_string; // Return new string
 
      } // -x- std::string to_lower -x-
 
      /*======================================================================*//**
      @brief
      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 to_lower
      *///=========================================================================
      static std::string to_upper(
      /// Source string
      std::string& str,
      /// Perform in-place conversion (default is FALSE / non-destructive)
      bool in_place_conversion = false,
      /// Begin conversion from this position (0 = first character)@n
      /// Negative positions are caculated backward from the end of the string
      const int begin = 0,
      /// Number of characters to convert (values exceeding string length will not
      /// cause any exceptions as the excess will be effectively ignored)@n
      /// -1 = maximum number of characters (a.k.a., until end of string)
      const int len = -1) noexcept {
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        const int BEGIN = begin >=  0 ? begin : str.length() + begin; // Calculate negative values from end of string
        const int MAX   = len   == -1 ? str.length() : std::min(str.length(), (size_t)(begin + len)); // Optimization:  For faster loop operations
 
        // --------------------------------------------------------------------------
        // Perform in-place conversion.
        // --------------------------------------------------------------------------
        if (in_place_conversion) {
          for (int i = BEGIN; i < MAX; i++) {
            char ch = str.at(i);
            if (ch >= 'a' && ch <= 'z') str.at(i) = ch -= 32; // Convert to upper-case
          } // -x- for i -x-
          return str; // Return updated string
        } // -x- if in_place_conversion -x-
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        std::string new_string = str; // Copy string (this allocates additional memory)
 
        // --------------------------------------------------------------------------
        // Perform isolated conversion.
        // --------------------------------------------------------------------------
        for (int i = BEGIN; i < MAX; i++) {
          char ch = str.at(i);
          if (ch >= 'a' && ch <= 'z') new_string.at(i) = ch -= 32; // Convert to upper-case
        } // -x- for i -x-
        return new_string; // Return new string
 
      } // -x- std::string to_upper -x-
 
      /*======================================================================*//**
      @brief
      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)
      *///=========================================================================
      static std::string trim_quotes(
      /// Source string
      std::string str) noexcept {
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        const int LAST = str.length() - 1; // Optimization:  For faster loop operations
        if (LAST < 2) return str; // Less than two characters, so return
 
        // --------------------------------------------------------------------------
        // Process string.
        // --------------------------------------------------------------------------
        std::string new_string = (str[0] == '"' && str[LAST] == '"') ? str.substr(1, LAST - 1) : str; // This allocates additional memory
        return new_string; // Return new string
 
      } // -x- std::string trim_quotes -x-
 
      /*======================================================================*//**
      @brief
      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 @c srand() with high resolution time once before starting
      the loop that calls the @c std::rand() function.  (Only the first 8 bits
      returned by @c std::rand() are used; the remaining higher bits are not used.)
      *///=========================================================================
      static void wipe(
      /// String to wipe
      std::string& str,
      /// Number of passes (default is 1)
      unsigned int passes = 1) { wipe(str.data(), str.capacity(), passes); } // -x- void wipe -x-
 
      /*======================================================================*//**
      @brief
      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 @c srand() with high resolution time once before starting
      the loop that calls the @c std::rand() function.  (Only the first 8 bits
      returned by @c std::rand() are used; the remaining higher bits are not used.)
      *///=========================================================================
      static void wipe(
      /// String to wipe
      char* data,
      /// Length of string (-1 = ASCIIZ string)
      size_t len = -1,
      /// Number of passes (default is 1)
      unsigned int passes = 1) {
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        if (len == -1) len = std::strlen(data);
        std::timespec ts;
        std::timespec_get(&ts, TIME_UTC);
 
        // --------------------------------------------------------------------------
        // Seed random number generator with high-resolution time data.
        // --------------------------------------------------------------------------
        std::srand(ts.tv_sec * ts.tv_nsec);
 
        // --------------------------------------------------------------------------
        // Data wipe loop.
        // --------------------------------------------------------------------------
        while (passes-- > 0) {
          for (int i = len; i >= 0; i--)
            ((unsigned char*)data)[i] ^= (unsigned char)std::rand();
        } // -x- while passes -x-
 
      } // -x- void wipe -x-
 
  }; // -x- class rtools -x-
  
} // -x- namespace randolf -x-