Atomize

#pragma once
 
#include <algorithm>
#include <atomic>
#include <cstring>
#include <exception>
#include <iostream>
#include <vector>
 
namespace randolf {
 
  /*======================================================================*//**
  @brief
  The @ref Atomize class provides an object-oriented interface with array-style
  access to a string, that was efficiently separated into atoms, and with more
  granularity and functionality through the use of modes (see @ref mode for
  deatils) and certain API methods, hence one could say "Atomize can split your
  atoms safely.".
 
  When parsing a line or block of text, the following is assumed:
 
     - parameters are separated by one or multiple consecutive whitespace
       characters (space, null, tab, linefeed, carriage return)
 
     - values that are enclosed within a set of quotation marks may include
       whitespace characters that will then not be interpreted as delimiters
 
  Data is interpreted in a single pass during instantiation or assignment, and
  the interpretation algorithm is written in an optimized programming style to
  ensure high efficiency.
 
  There are no memory leaks, which, as it turns out, is particularly important
  not only because the specialized parsing involved is often utilized in heavy
  data processing loops where speed and reliability are needed, but also
  because some of the libraries I've tested that provide similar functionality
  leak memory or fail in other ways that were triggered by peculiar or fuzzed
  data, which this class is not impacted by (primarily because I don't trust
  data to always be "as expected").
 
  @par Use case
 
  Parsing command lines or configuration settings can become challenging when
  multiple parameters are provided on a single line, and some of those
  parameters include quoted text that contains spaces. This class handles all
  of these scenarios and makes it easy to access each parameter in the same
  manner that arrays and vectors are accessed.
 
  @par Background
 
  I created this class to make it easier to write internet server daemons.
 
  @par Getting started
 
  @author Randolf Richardson
  @version 1.00
  @par History
    - 2025-Jan-20 v1.00 Initial version
    - 2025-Feb-03 v1.00 Increased use of references and pointers
 
  @par Conventions
  Lower-case letter "h" is regularly used in partial example code to represent
  an instantiated rhostname object.
 
  An ASCIIZ string is a C-string (char* array) that includes a terminating null
  (0) character at the end.
 
  @par Notes
 
  I use the term "ASCIIZ string" to indicate an array of characters that's
  terminated by a 0 (a.k.a., null).  Although this is very much the same as a
  C-string, the difference is that in many API functions a C-string must often
  be accompanied by its length value.  When referring to an ASCIIZ string, I'm
  intentionally indicating that the length of the string is not needed because
  the string is null-terminated.  (This term was also commonly used in assembly
  language programming in the 1970s, 1980s, and 1990s, and as far as I know is
  still used by machine language programmers today.)
 
  @par Examples
 
  @code{.cpp}
    #include <iostream>  // std::cout, std::cerr, std::endl, etc.
 
    #include <randolf/Atomize>
 
    int main(int argc, char *argv[]) {
      randolf::Atomize a("parameters key=value");
      std::cout << "atom0: " << a.at(0)      << std::endl;
      std::cout << "atom1: " << a.at(1)      << std::endl;
      std::cout <<  "key1: " << a.at(1, 'k') << std::endl;
      std::cout <<  "val1: " << a.at(1, 'v') << std::endl;
      return EXIT_SUCCESS;
    } // -x- int main -x-
  @endcode
 
  Parameter stacking is also supported (with methods that return @c Atomize*).
  *///=========================================================================
  class Atomize {
 
    private:
      // --------------------------------------------------------------------------
      // Internal structures.
      // --------------------------------------------------------------------------
      struct __atom {
        uint fpos = 0; // First position/offset (key also begins here)
        uint flen = 0; // Full length
        uint klen = 0; // Key length
        uint vpos = 0; // Value position/offset (0 == not present)
        uint vlen = 0; // Value length (do not use this to test for presence of value)
      }; // -x- struct __atom -x-
 
      // --------------------------------------------------------------------------
      // Internal variables.
      // --------------------------------------------------------------------------
      char*                __origin      = nullptr; // Copy of original string
      std::vector<__atom*> __data_points;
      int                  __flags       = 0;
 
      // --------------------------------------------------------------------------
      // Operator modes (all are disabled by default).
      // --------------------------------------------------------------------------
      bool                 mode_k        = false; // Key
      bool                 mode_v        = false; // Value
      bool                 mode_p        = false; // Presence of key-value pair
      bool                 mode_c        = false; // Camel_Case
      bool                 mode_f        = false; // First letter upper-case
      bool                 mode_l        = false; // All lower-case
      bool                 mode_u        = false; // All upper-case
      #define              ATOMIZE_MAX_MODES 8    // Number of modes + 1 (so include 0 for strnlen())
 
    public:
      /*======================================================================*//**
      @brief
      Optional flags that alter, modify, or enhance the operation of atomization
      intake.
      *///=========================================================================
      enum ATOMIZE_FLAGS: int {
 
        /*----------------------------------------------------------------------*//**
        The ATOMIZE_DEFAULT flag isn't necessary, but it's included here for
        completeness as it accomodates programming styles that prefer to emphasize
        when defaults are being relied upon.
        *///-------------------------------------------------------------------------
        ATOMIZE_DEFAULT = 0,
 
        /*----------------------------------------------------------------------*//**
        Interpret all quotation marks (the default is to only utilize enclosing
        quotation marks).
        *///-------------------------------------------------------------------------
        ATOMIZE_USE_ALL_QUOTES = 1,
 
        /*----------------------------------------------------------------------*//**
        Don't interpret quotation marks as grouping characters.
        *///-------------------------------------------------------------------------
        ATOMIZE_IGNORE_QUOTES = 2,
 
        /*----------------------------------------------------------------------*//**
        Delete quotation marks that function as grouping characters (this flag has no
        effect when @ref ATOMIZE_IGNORE_QUOTES is set).
        *///-------------------------------------------------------------------------
        ATOMIZE_DELETE_QUOTES = 4,
 
      }; // -x- enum ATOMIZE_FLAGS -x-
 
    private:
      /*======================================================================*//**
      @brief
      Assign new string.
      *///=========================================================================
      void __assign(
      /// The intake ASCIIZ string
      const char* intake,
      /// The length of the intake string
      const int len) {
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        __atom* atom = new __atom{}; // Transient data structure
        bool       k = false;        // Key-value pair detection flag
        //bool       q = false;        // Begin in non-quote mode
        bool       w = true;         // Begin in whitespace mode to skip any leading whitespace
 
        // --------------------------------------------------------------------------
        // Allocate internal memory.
        // --------------------------------------------------------------------------
        if (__origin != nullptr) ::free(__origin);     // Memory management
            __origin  =   (char*)::calloc(1, len + 1); // Allocate memory
 
        // --------------------------------------------------------------------------
        // Primary loop.
        // --------------------------------------------------------------------------
        for (int i = 0; i < len; i++) {
 
          // --------------------------------------------------------------------------
          // Extract current charact and copy original string at the same time, which
          // also creates an optimization opportunity for compilers to store "c" in a
          // register, which is faster than accessing a memory location.
          // --------------------------------------------------------------------------
          char c = __origin[i] = intake[i];
 
          // --------------------------------------------------------------------------
          // Process character.
          // --------------------------------------------------------------------------
          switch (c) {
            case '\0': // Whitespace:  NULL
              //if (len == 0) break;    // End of ASCIIZ string
            case ' ':  // Whitespace:  Space
            case '\t': // Whitespace:  Tab
            case '\r': // Whitespace:  Carriage Return
            case '\n': // Whitespace:  Linefeed
              if (!w) { // End of atom
                if (k) atom->vlen = i - atom->vpos;
                  else atom->klen = i - atom->fpos;
                __data_points.push_back(atom);      // Save current atom to vector
                atom = new __atom{.fpos = (uint)i}; // Create new atom
                k = false;                          // Disable key-value pair mode
                w = true;                           // Enable whitespace mode
              } // -x- if !w -x-
              break;
            case '=': // Key-value pair detected
              if (!k) { // Key-value pair mode is not already detected
                k = true; // Enable key-value pair mode
                atom->klen = w ? 0 : i - atom->fpos;
                atom->vpos = i + 1; // Save position of value
              } // -x- if !k -x-
            default: // Non-whitespace characters
              if (w) { // White space mode is enabled
                atom->fpos = i; // Save new starting position
                w = false; // Disable whitespace mode
              } // -x- if w -x-
              if (k) atom->vlen++;
                else atom->klen++;
              atom->flen++;
          } // -x- swtich str -x-
 
        } // -x- for i -x-
 
        // --------------------------------------------------------------------------
        // Save final atom if it's not empty.
        // --------------------------------------------------------------------------
        if (atom->flen != 0) __data_points.push_back(atom);
        else delete atom;
 
      } // -x- void __assign -x-
 
      /*======================================================================*//**
      @brief
      Clear internal data.  Called by destructor and assign() methods.
      *///=========================================================================
      void __clear() {
 
        // --------------------------------------------------------------------------
        // Resources management:  De-allocate all structures since a std::vector of
        // pointers to these structures won't do this automatically when we clear()
        // the entire vector.
        // --------------------------------------------------------------------------
        for (int i = (int)__data_points.size() - 1; i >= 0; i--) delete __data_points.at(i);
        __data_points.clear();
 
        // --------------------------------------------------------------------------
        // Memory management.
        // --------------------------------------------------------------------------
        ::free(__origin);
        __origin = nullptr;
 
      } // -x- void __clear -x-
 
      /*======================================================================*//**
      @brief
      Set a mode.
      *///=========================================================================
      void __mode(const char mode, const bool throw_exception = true) {
        switch (mode) {
          case 'k':
            mode_k = true;
            break;
          case 'v':
            mode_v = true;
            break;
          case 'p':
            mode_p = true;
            break;
          case 'c':
            mode_c = true;
            break;
          case 'f':
            mode_f = true;
            break;
          case 'l':
            mode_l = true;
            break;
          case 'u':
            mode_u = true;
            break;
          default:
            if (throw_exception) throw std::invalid_argument("unrecognized oeprator_mode \"" + std::to_string(mode) + "\"");
        } // -x- switch mode -x-
      } // -x- void __mode -x-
 
    public:
      /*======================================================================*//**
      @brief
      Instantiate an empty Atomize object, which is expected to be used with the
      @ref assign method at some later point.  (This is particularly useful for
      defining a local Atomize object in a header file in a way that won't throw an
      exception, including invalid mode codes {which will just be ignored instead
      of throwing an exception}.)
      @see assign
      @see mode
      *///=========================================================================
      Atomize(
      /// See @ref ATOMIZE_FLAGS for a list of options
      const int flags,
      /// Granulatarity (default is to return the entire atom): @n
      /// @c 0 = don't set any modes (default) @n
      /// @c 'k' = key (same as 0 if no key-value pair was detected) @n
      /// @c 'v' = value (will be empty if no key-value pair was detected) @n
      /// @c 'p' = returns "1" if key-value pair is present, or an empty string if not
      /// Conversion options (default is for no conversion): @n
      /// @c 'c' = Camel_Case @n
      /// @c 'f' = First character in upper-case @n
      /// @c 'l' = all lower case @n
      /// @c 'u' = ALL UPPER CASE
      const char mode) noexcept {
        __flags = flags;
        __mode(mode, false);
      } // -x- constructor Atomize -x-
 
      /*======================================================================*//**
      @brief
      Instantiate an empty Atomize object, which is expected to be used with the
      @ref assign method at some later point.  (This is particularly useful for
      defining a local Atomize object in a header file in a way that won't throw an
      exception, including invalid mode codes {which will just be ignored instead
      of throwing an exception}.)
      @see assign
      @see mode
      *///=========================================================================
      Atomize(
      /// See @ref ATOMIZE_FLAGS for a list of options
      const int flags = ATOMIZE_DEFAULT,
      /// Granulatarity (default is to return the entire atom): @n
      /// @c nullptr = don't set any modes @n
      /// @c "k" = key (same as 0 if no key-value pair was detected) @n
      /// @c "v" = value (will be empty if no key-value pair was detected) @n
      /// @c "p" = returns "1" if key-value pair is present, or an empty string if not
      /// Conversion options (default is for no conversion): @n
      /// @c "c" = Camel_Case @n
      /// @c "f" = First character in upper-case @n
      /// @c "l" = all lower case @n
      /// @c "u" = ALL UPPER CASE
      const char* mode = nullptr) noexcept {
        __flags = flags;
        if (mode != nullptr) {
          const int mode_len = ::strnlen(mode, ATOMIZE_MAX_MODES);
          for (int i = 0; i < mode_len; i++) __mode(mode[i], false);
        } // -x- if mode -x-
      } // -x- constructor Atomize -x-
 
      /*======================================================================*//**
      @brief
      Instantiate an Atomize object using the specified ASCIIZ string for intake.
      @throws std::invalid_argument If the parameters are malformed in some way.
      @see assign
      @see mode
      *///=========================================================================
      Atomize(
      /// The intake ASCIIZ string
      const char* intake,
      /// The length of the intake string@n
      /// -1 = Measure ASCIIZ string
      const int len,
      /// See @ref FLAGS for a list of options
      const int flags,
      /// Granulatarity (default is to return the entire atom): @n
      /// @c 0 = don't set any modes (default) @n
      /// @c 'k' = key (same as 0 if no key-value pair was detected) @n
      /// @c 'v' = value (will be empty if no key-value pair was detected) @n
      /// @c 'p' = returns "1" if key-value pair is present, or an empty string if not
      /// Conversion options (default is for no conversion): @n
      /// @c 'c' = Camel_Case @n
      /// @c 'f' = First character in upper-case @n
      /// @c 'l' = all lower case @n
      /// @c 'u' = ALL UPPER CASE
      const char mode) {
        __flags = flags;
        __mode(mode, false);
        __assign(intake, len >= 0 ? len : std::strlen(intake));
      } // -x- constructor Atomize -x-
 
      /*======================================================================*//**
      @brief
      Instantiate an Atomize object using the specified ASCIIZ string for intake.
      @throws std::invalid_argument If the parameters are malformed in some way.
      @see assign
      @see mode
      *///=========================================================================
      Atomize(
      /// The intake ASCIIZ string
      const char* intake,
      /// The length of the intake string@n
      /// -1 = Measure ASCIIZ string
      const int len = -1,
      /// See @ref FLAGS for a list of options
      const int flags = ATOMIZE_DEFAULT,
      /// Granulatarity (default is to return the entire atom): @n
      /// @c nullptr = don't set any modes @n
      /// @c "k" = key (same as 0 if no key-value pair was detected) @n
      /// @c "v" = value (will be empty if no key-value pair was detected) @n
      /// @c "p" = returns "1" if key-value pair is present, or an empty string if not
      /// Conversion options (default is for no conversion): @n
      /// @c "c" = Camel_Case @n
      /// @c "f" = First character in upper-case @n
      /// @c "l" = all lower case @n
      /// @c "u" = ALL UPPER CASE
      const char* mode = nullptr) {
        __flags = flags;
        if (mode != nullptr) {
          const int mode_len = ::strnlen(mode, ATOMIZE_MAX_MODES);
          for (int i = 0; i < mode_len; i++) __mode(mode[i], false);
        } // -x- if mode -x-
        __assign(intake, len >= 0 ? len : std::strlen(intake));
      } // -x- constructor Atomize -x-
 
      /*======================================================================*//**
      @brief
      Instantiate an Atomize object using the specified string for intake.
      @throws std::invalid_argument If the parameters are malformed in some way.
      @see assign
      @see mode
      *///=========================================================================
      Atomize(
      /// The intake C++ string
      const std::string& intake,
      /// The length of the intake string@n
      /// -1 = Obtain length from @c intake.size() method
      const int len,
      /// See @ref FLAGS for a list of options
      const int flags,
      /// Granulatarity (default is to return the entire atom): @n
      /// @c 0 = don't set any modes (default) @n
      /// @c 'k' = key (same as 0 if no key-value pair was detected) @n
      /// @c 'v' = value (will be empty if no key-value pair was detected) @n
      /// @c 'p' = returns "1" if key-value pair is present, or an empty string if not
      /// Conversion options (default is for no conversion): @n
      /// @c 'c' = Camel_Case @n
      /// @c 'f' = First character in upper-case @n
      /// @c 'l' = all lower case @n
      /// @c 'u' = ALL UPPER CASE
      const char mode) {
        __flags = flags;
        __mode(mode, false);
        __assign(intake.data(), len >= 0 ? len : intake.size());
      } // -x- constructor Atomize -x-
 
      /*======================================================================*//**
      @brief
      Instantiate an Atomize object using the specified string for intake.
      @throws std::invalid_argument If the parameters are malformed in some way.
      @see assign
      @see mode
      *///=========================================================================
      Atomize(
      /// The intake C++ string
      const std::string& intake,
      /// The length of the intake string@n
      /// -1 = Obtain length from @c intake.size() method
      const int len = -1,
      /// See @ref FLAGS for a list of options
      const int flags = ATOMIZE_DEFAULT,
      /// Granulatarity (default is to return the entire atom): @n
      /// @c nullptr = don't set any modes @n
      /// @c "k" = key (same as 0 if no key-value pair was detected) @n
      /// @c "v" = value (will be empty if no key-value pair was detected) @n
      /// @c "p" = returns "1" if key-value pair is present, or an empty string if not
      /// Conversion options (default is for no conversion): @n
      /// @c "c" = Camel_Case @n
      /// @c "f" = First character in upper-case @n
      /// @c "l" = all lower case @n
      /// @c "u" = ALL UPPER CASE
      const char* mode = nullptr) {
        __flags = flags;
        if (mode != nullptr) {
          const int mode_len = ::strnlen(mode, ATOMIZE_MAX_MODES);
          for (int i = 0; i < mode_len; i++) __mode(mode[i], false);
        } // -x- if mode -x-
        __assign(intake.data(), len >= 0 ? len : intake.size());
      } // -x- constructor Atomize -x-
 
      /*======================================================================*//**
      @brief
      Destructor.
      @see clear
      *///=========================================================================
      ~Atomize() noexcept {
        __clear();
        if (__origin != nullptr) ::free(__origin); // Memory management
      } // -x- constructor Atomize -x-
 
      /*======================================================================*//**
      @brief
      Assign (and interpret) a new ASCIIZ string (flags and modes are inherited).
      @throws std::invalid_argument If the parameters are malformed in some way.
      @returns The same Atomize object so as to facilitate stacking
      *///=========================================================================
      Atomize& assign(
      /// The intake ASCIIZ string
      const char* intake,
      /// The length of the intake string@n
      /// -1 = Measure ASCIIZ string
      const int len = -1) {
        __clear();
        __assign(intake, len >= 0 ? len : std::strlen(intake));
        return *this;
      } // -x- Atomize& assign -x-
 
      /*======================================================================*//**
      @brief
      Assign (and interpret) a new string (flags and modes are inherited).
      @throws std::invalid_argument If the parameters are malformed in some way.
      @returns The same Atomize object so as to facilitate stacking
      *///=========================================================================
      Atomize& assign(
      /// The intake C++ string
      const std::string& intake,
      /// The length of the intake string@n
      /// -1 = Obtain length from @c intake.size() method
      const int len = -1) {
        __clear();
        __assign(intake.data(), len >= 0 ? len : intake.size());
        return *this;
      } // -x- Atomize& assign -x-
 
      /*======================================================================*//**
      @brief
      Access to atoms, whilst utilizing the operator mode that was configured using
      the @ref mode method.
      Return an entire atom.
      @throws std::out_of_range if the index is out-of-range
      @see get
      @see get_key
      @see get_value
      @see mode
      @see operator[](int)
      @returns Entire atom, or portion, depending on the mode
      *///=========================================================================
      std::string at(
      /// Which atom to obtain (0 = first atom; negative values count backward from
      /// the last atom in the internal array)
      int index,
      /// Granulatarity (default is to return the entire atom): @n
      /// @c 0 = don't change any modes (default) @n
      /// @c 'k' = key (same as 0 if no key-value pair was detected) @n
      /// @c 'v' = value (will be empty if no key-value pair was detected) @n
      /// @c 'p' = returns "1" if key-value pair is present, or an empty string if not
      /// Conversion options (default is for no conversion): @n
      /// @c 'c' = Camel_Case @n
      /// @c 'f' = First character in upper-case @n
      /// @c 'l' = all lower case @n
      /// @c 'u' = ALL UPPER CASE
      const char mode) {
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        std::string str;
        if (index < 0) index = __data_points.size() + index;
        __atom* atom = __data_points[index];
 
        // --------------------------------------------------------------------------
        // Save mode.
        // --------------------------------------------------------------------------
        std::string old_modes(mode == 0 ? "" : this->mode());
        if (mode != 0) this->mode(mode);
 
        // --------------------------------------------------------------------------
        // Presence of key-value pair (results in ignoring all other modes).
        // --------------------------------------------------------------------------
        if (mode_p) {
          if (atom->vpos != 0) str.assign("1");
          return str;
        } // -x- if mode_p -x-
 
        // --------------------------------------------------------------------------
        // Key/Value mode.
        // --------------------------------------------------------------------------
             if (mode_k) str.assign(__origin, atom->fpos, atom->klen);
        else if (mode_v) str.assign(__origin, atom->vpos, atom->vlen);
        else             str.assign(__origin, atom->fpos, atom->flen);
 
        // --------------------------------------------------------------------------
        // Conversion modes.
        // --------------------------------------------------------------------------
        char* data = str.data();
        if (mode_l) { // All lower-case
          for (size_t i = 0; i < str.size(); i++) {
            char ch = data[i];
            if (ch >= 'A' && ch <= 'Z') data[i] += 32; // Convert to lower-case
          } // -x- for i -x-
        } else if (mode_u) { // All upper-case
          for (size_t i = 0; i < str.size(); i++) {
            char ch = data[i];
            if (ch >= 'a' && ch <= 'z') data[i] -= 32; // Convert to upper-case
          } // -x- for i -x-
        } else if (mode_c) { // Camel_Case
          char pch = 0;
          for (size_t i = 0; i < str.size(); i++) {
            char ch = data[i];
            if (pch < 'A' || (pch > 'Z' && pch < 'a') || pch > 'z') {
              if (ch >= 'a' && ch <= 'z')
                data[i] -= 32; // Convert to upper-case
            } // -x- if pch -x-
            pch = data[i];
          } // -x- for i -x-
        } else if (mode_f) { // First letter
          char ch = data[0];
          if (ch >= 'a' && ch <= 'z') data[0] -= 32; // Convert to upper-case
        } // -x- if mode_c -x-
 
        // --------------------------------------------------------------------------
        // Restore mode.
        // --------------------------------------------------------------------------
        if (mode != 0) this->mode(old_modes.data());
 
        return str;
      } // -x- std::string at -x-
 
      /*======================================================================*//**
      @brief
      Access to atoms, whilst utilizing the operator mode that was configured using
      the @ref mode method.
      Return an entire atom.
      @throws std::out_of_range if the index is out-of-range
      @see get
      @see get_key
      @see get_value
      @see mode
      @see operator[](int)
      @returns Entire atom, or portion, depending on the mode
      *///=========================================================================
      std::string at(
      /// Which atom to obtain (0 = first atom; negative values count backward from
      /// the last atom in the internal array)
      int index,
      /// Granulatarity (default is to return the entire atom): @n
      /// @c nullptr = don't change any modes (default) @n
      /// @c "k" = key (same as 0 if no key-value pair was detected) @n
      /// @c "v" = value (will be empty if no key-value pair was detected) @n
      /// @c "p" = returns "1" if key-value pair is present, or an empty string if not
      /// Conversion options (default is for no conversion): @n
      /// @c "c" = Camel_Case @n
      /// @c "f" = First character in upper-case @n
      /// @c "l" = all lower case @n
      /// @c "u" = ALL UPPER CASE
      const char* mode = nullptr) {
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        std::string str;
        if (index < 0) index = __data_points.size() + index;
        __atom* atom = __data_points[index];
 
        // --------------------------------------------------------------------------
        // Save mode.
        // --------------------------------------------------------------------------
        std::string old_modes(mode == nullptr ? "" : this->mode());
        if (mode != nullptr) this->mode(mode);
 
        // --------------------------------------------------------------------------
        // Presence of key-value pair (results in ignoring all other modes).
        // --------------------------------------------------------------------------
        if (mode_p) {
          if (atom->vpos != 0) str.assign("1");
          return str;
        } // -x- if mode_p -x-
 
        // --------------------------------------------------------------------------
        // Key/Value mode.
        // --------------------------------------------------------------------------
             if (mode_k) str.assign(__origin, atom->fpos, atom->klen);
        else if (mode_v) str.assign(__origin, atom->vpos, atom->vlen);
        else             str.assign(__origin, atom->fpos, atom->flen);
 
        // --------------------------------------------------------------------------
        // Conversion modes.
        // --------------------------------------------------------------------------
        char* data = str.data();
        if (mode_l) { // All lower-case
          for (size_t i = 0; i < str.size(); i++) {
            char ch = data[i];
            if (ch >= 'A' && ch <= 'Z') data[i] += 32; // Convert to lower-case
          } // -x- for i -x-
        } else if (mode_u) { // All upper-case
          for (size_t i = 0; i < str.size(); i++) {
            char ch = data[i];
            if (ch >= 'a' && ch <= 'z') data[i] -= 32; // Convert to upper-case
          } // -x- for i -x-
        } else if (mode_c) { // Camel_Case
          char pch = 0;
          for (size_t i = 0; i < str.size(); i++) {
            char ch = data[i];
            if (pch < 'A' || (pch > 'Z' && pch < 'a') || pch > 'z') {
              if (ch >= 'a' && ch <= 'z')
                data[i] -= 32; // Convert to upper-case
            } // -x- if pch -x-
            pch = data[i];
          } // -x- for i -x-
        } else if (mode_f) { // First letter
          char ch = data[0];
          if (ch >= 'a' && ch <= 'z') data[0] -= 32; // Convert to upper-case
        } // -x- if mode_c -x-
 
        // --------------------------------------------------------------------------
        // Restore mode.
        // --------------------------------------------------------------------------
        if (mode != nullptr) this->mode(old_modes.data());
 
        return str;
      } // -x- std::string at -x-
 
      /*======================================================================*//**
      @brief
      Clear this Atomize's underlying data and reset all states.
      @returns The same Atomize object so as to facilitate stacking
      @see empty
      @see size
      *///=========================================================================
      Atomize& clear() {
        __clear();
        return *this;
      } // -x- Atomize& clear -x-
 
      /*======================================================================*//**
      @brief
      Confirm that there are no atoms.
      @returns TRUE = no atoms@n
               FALSE = at least one atom exists
      @see clear
      @see size
      *///=========================================================================
      bool empty() {
        return __data_points.empty();
      } // -x- bool empty -x-
 
      /*======================================================================*//**
      @brief
      Obtain current set of internal flags.
      @returns Current flags, as defined in @ref ATOMIZE_FLAGS
      @see mode
      *///=========================================================================
      int flags() {
        return __flags;
      } // -x- int flags -x-
 
      /*======================================================================*//**
      @brief
      Obtain current set of internal flags.
      @returns The same Atomize object so as to facilitate stacking
      @see mode
      *///=========================================================================
      Atomize& flags(
      /// See @ref FLAGS for a list of options
      const int flags = ATOMIZE_DEFAULT) {
        __flags = flags;
        return *this;
      } // -x- Atomize& flags -x-
 
      /*======================================================================*//**
      @brief
      Return the entire atom.
      @throws std::out_of_range if the index is out-of-range
      @returns Key portion of atom (or the entire atom if a key-value pair wasn't
               detected)
      @see at
      @see get_key
      @see get_value
      @see has_kv
      @see mode
      @see operator[](int)
      *///=========================================================================
      std::string get(
      /// Which atom to obtain (0 = first atom; negative values count backward from
      /// the last atom in the internal array)
      int index) {
        if (index < 0) index = __data_points.size() + index;
        __atom* atom = __data_points[index];
        return std::string(__origin, atom->fpos, atom->flen);
      } // -x- std::string get -x-
 
      /*======================================================================*//**
      @brief
      Return the key portion of an atom, or the entire atom if a key-vlue pair
      wasn't detected.
      @throws std::out_of_range if the index is out-of-range
      @returns Key portion of atom (or the entire atom if a key-value pair wasn't
               detected)
      @see at
      @see get
      @see get_value
      @see has_kv
      @see mode
      @see operator[](int)
      *///=========================================================================
      std::string get_key(
      /// Which atom to obtain (0 = first atom; negative values count backward from
      /// the last atom in the internal array)
      int index) {
        if (index < 0) index = __data_points.size() + index;
        __atom* atom = __data_points[index];
        return std::string(__origin, atom->fpos, atom->klen);
      } // -x- std::string get_key -x-
 
      /*======================================================================*//**
      @brief
      Return the value portion of an atom, or an empty string if a key-vlue pair
      wasn't detected.
      @throws std::out_of_range if the index is out-of-range
      @returns Value portion of atom (or an empty string if a key-value pair wasn't
               detected)
      @see at
      @see get
      @see get_key
      @see has_kv
      @see mode
      @see operator[](int)
      *///=========================================================================
      std::string get_value(
      /// Which atom to obtain (0 = first atom; negative values count backward from
      /// the last atom in the internal array)
      int index) {
        if (index < 0) index = __data_points.size() + index;
        __atom* atom = __data_points[index];
        return std::string(atom->vpos != 0 ? std::string(__origin, atom->vpos, atom->vlen) : "");
      } // -x- std::string get_value -x-
 
      /*======================================================================*//**
      @brief
      Indicates whether the specified atom was split into a key-value pair (if it
      was, then the @c key and the @c value are delimited by the first instance of
      an equal sign {`=`}).
      @throws std::out_of_range if the index is out-of-range
      @returns TRUE = key-value pair was detected by the parsing algorithm
               FALSE = this atom was not split into a key-value pair
      @see at
      @see get
      @see get_key
      @see get_value
      @see mode
      @see operator[](int)
      *///=========================================================================
      bool has_kv(
      /// Which atom to obtain (0 = first atom; negative values count backward from
      /// the last atom in the internal array)
      int index) {
        if (index < 0) index = __data_points.size() + index;
        __atom* atom = __data_points[index];
        return atom->vpos != 0;
      } // -x- bool has_kv -x-
 
      /*======================================================================*//**
      @brief
      Get the operator modes that are set for the @ref operator[] operator.
      @throws std::invalid_argument if an incorrect value is provided
      @returns The same Atomize object so as to facilitate stacking
      @see at
      @see flags
      @see get
      @see get_key
      @see get_value
      @see has_kv
      @see operator[](int)
      @see mode(const char*)
      *///=========================================================================
      std::string mode() noexcept {
        std::string modes;
        if (mode_k) modes.append("k");
        if (mode_v) modes.append("v");
        if (mode_p) modes.append("p");
        if (mode_c) modes.append("c");
        if (mode_f) modes.append("f");
        if (mode_l) modes.append("l");
        if (mode_u) modes.append("u");
        return modes;
      } // -x- std::string mode -x-
 
      /*======================================================================*//**
      @brief
      Set the operator modes for use with the @ref operator[] operator (modes that
      are not specified will be reset to their defaults).
 
      Calling this method with @c 0 as the parameter will result in resetting all
      operator modes to their defaults.
      @throws std::invalid_argument if an incorrect value is provided
      @returns The same Atomize object so as to facilitate stacking
      @see at
      @see flags
      @see get
      @see get_key
      @see get_value
      @see has_kv
      @see operator[](int)
      *///=========================================================================
      Atomize& mode(
      /// Granulatarity (default is to return the entire atom): @n
      /// @c nullptr = clear all modes (default) @n
      /// @c "k" = key (same as 0 if no key-value pair was detected) @n
      /// @c "v" = value (will be empty if no key-value pair was detected) @n
      /// @c "p" = returns "1" if key-value pair is present, or an empty string if not
      /// Conversion options (default is for no conversion): @n
      /// @c "c" = Camel_Case @n
      /// @c "f" = First character in upper-case @n
      /// @c "l" = all lower case @n
      /// @c "u" = ALL UPPER CASE
      const char* mode) {
 
        // --------------------------------------------------------------------------
        // Clear all settings.
        // --------------------------------------------------------------------------
        mode_k = false;
        mode_v = false;
        mode_p = false;
        mode_c = false;
        mode_f = false;
        mode_l = false;
        mode_u = false;
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
        if (mode == nullptr) return *this;
 
        // --------------------------------------------------------------------------
        // Set modes (duplicates are effectively ignored, and 0 never shows up here
        // because it terminates the string).
        // --------------------------------------------------------------------------
        const int mode_len = ::strnlen(mode, ATOMIZE_MAX_MODES);
        for (int i = 0; i < mode_len; i++) __mode(mode[i]);
 
        return *this;
      } // -x- Atomize& mode -x-
 
      /*======================================================================*//**
      @brief
      Set the operator modes for use with the @ref operator[] operator (modes that
      are not specified will be reset to their defaults).
 
      Calling this method with @c 0 as the parameter will result in resetting all
      operator modes to their defaults.
      @throws std::invalid_argument if an incorrect value is provided
      @returns The same Atomize object so as to facilitate stacking
      @see at
      @see flags
      @see get
      @see get_key
      @see get_value
      @see has_kv
      @see operator[](int)
      *///=========================================================================
      Atomize& mode(
      /// Granulatarity (default is to return the entire atom): @n
      /// @c 0 = entire atom (default) @n
      /// @c 'k' = key (same as 0 if no key-value pair was detected) @n
      /// @c 'v' = value (will be empty if no key-value pair was detected) @n
      /// @c 'p' = returns "1" if key-value pair is present, or an empty string if not
      /// Conversion options (default is for no conversion): @n
      /// @c 'c' = Camel_Case @n
      /// @c 'f' = First character in upper-case @n
      /// @c 'l' = all lower case @n
      /// @c 'u' = ALL UPPER CASE
      const char mode) {
 
        // --------------------------------------------------------------------------
        // Reset all modes.
        // --------------------------------------------------------------------------
        mode_k = false;
        mode_v = false;
        mode_p = false;
        mode_c = false;
        mode_f = false;
        mode_l = false;
        mode_u = false;
 
        // --------------------------------------------------------------------------
        // Set mode.
        // --------------------------------------------------------------------------
        __mode(mode);
 
        return *this;
      } // -x- Atomize& mode -x-
 
      /*======================================================================*//**
      @brief
      Return the total quantity of atoms.
      @returns Quantity of atoms
      @see clear
      @see empty
      *///=========================================================================
      size_t size() {
        return __data_points.size();
      } // -x- size_t size -x-
 
      /*======================================================================*//**
      @brief
      Generate an std::vector<std::string> that contains all atoms.
      @returns std::string
      *///=========================================================================
      std::vector<std::string> to_vector(
      /// FALSE = don't split key-value pairs (default) @n
      /// TRUE = split key-value pairs into separate entries (for key names, the
      ///        equal sign will be included at the end of the string)
      bool split_kv_pairs = false) noexcept {
        std::vector<std::string> v;
 
        // --------------------------------------------------------------------------
        // Splitting key-value pairs is best handled in a separate loop.
        // --------------------------------------------------------------------------
        if (split_kv_pairs) {
          for (size_t i = 0; i < __data_points.size(); i++) {
            __atom* atom = __data_points[i];
            if (atom->vpos != 0) { // Non-zero indicates that a key-value pair was detected
              v.push_back(std::string(__origin, atom->fpos, atom->klen + 1)); // +1 includes equal sign
              v.push_back(std::string(__origin, atom->vpos, atom->vlen));
            } else { // No key-value pair was detected
              v.push_back(std::string(__origin, atom->fpos, atom->flen));
            } // -x- if atom->vpos -x-
          } // -x- for i -x-
          return v;
        } // -x- if split_kv_pairs -x-
 
        // --------------------------------------------------------------------------
        // Full atoms requires is straight-forward.
        // --------------------------------------------------------------------------
        for (size_t i = 0; i < __data_points.size(); i++) {
          __atom* atom = __data_points[i];
          v.push_back(std::string(__origin, atom->fpos, atom->flen));
        } // -x- for i -x-
 
        return v;
      } // -x- std::vector<std::string> to_vector -x-
 
      /*======================================================================*//**
      @brief
      Array-style access to atoms, whilst utilizing the operator mode that was
      configured using the @ref mode method.
      @throws std::out_of_range if the index is out-of-range
      @returns std::string
      @see at
      @see get
      @see get_key
      @see get_value
      @see has_kv
      @see mode
      @see operator[](int)
      *///=========================================================================
      std::string operator[](
      /// Index of character to access (0 = first atom; negative index values are
      /// calculated in reverse, starting with -1 as the final atom)
      int index) {
        return at(index);
      } // -x- std::string operator[] -x-
 
  }; // -x- class Atomize -x-
 
}; // -x- namespace randolf -x-