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
 
  @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
 
    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{}; // Data structure that will keep being replaced
        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) __clear(); //::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
              [[fallthrough]];
            case ' ':  // Whitespace:  Space
              [[fallthrough]];
            case '\t': // Whitespace:  Tab
              [[fallthrough]];
            case '\r': // Whitespace:  Carriage Return
              [[fallthrough]];
            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 '"': //
              goto __assign_default;
            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-
            __assign_default:
              [[fallthrough]];
            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, but not flags or modes.  Called by both the destructor,
      the clear() method, and the various assign() methods.
      *///=========================================================================
      void __clear() {
 
        // --------------------------------------------------------------------------
        // Delete all data entry points.  These need to be deleted separately because
        // the std::vector won't automatically delete structures.
        // --------------------------------------------------------------------------
        for (int i = __data_points.size() - 1; i >= 0; i--)
          delete __data_points.at(i);
        __data_points.clear();
 
        // --------------------------------------------------------------------------
        // Free the original string, if one has been allocated (in most cases, there
        // will be allocated memory here that needs to be freed).
        // --------------------------------------------------------------------------
        if (__origin != nullptr) {
          ::free(__origin); // Memory management
          __origin = nullptr;
        } // -x- if !__origin -x-
 
      } // -x- void __clear -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}.)
      *///=========================================================================
      Atomize(
      /// See @ref ATOMIZE_FLAGS for a list of options
      const int flags = ATOMIZE_DEFAULT,
      /// Set the modes (@c nullptr default means don't set the modes) @n
      /// 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" = is a key-value pair / "" = not a key-value pair@n
      /// 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) __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}.)
      *///=========================================================================
      Atomize(
      /// See @ref ATOMIZE_FLAGS for a list of options
      const int flags,
      /// Set the modes (@c 0 default means don't set the modes) @n
      /// 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" = is a key-value pair / "" = not a key-value pair@n
      /// 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;
        if (mode != 0) {
          char new_mode[]{mode, 0};
          __mode(new_mode, 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.
      *///=========================================================================
      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 ATOMIZE_FLAGS for a list of options
      const int flags = ATOMIZE_DEFAULT,
      /// Set the modes (@c nullptr default means don't set the modes) @n
      /// 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" = is a key-value pair / "" = not a key-value pair@n
      /// 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) __mode(mode);
        __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.
      *///=========================================================================
      Atomize(
      /// The intake ASCIIZ string
      const char* intake,
      /// The length of the intake string@n
      /// -1 = Measure ASCIIZ string
      const int len,
      /// See @ref ATOMIZE_FLAGS for a list of options
      const int flags,
      /// Set the modes (@c 0 default means don't set the modes) @n
      /// 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" = is a key-value pair / "" = not a key-value pair@n
      /// 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;
        if (mode != 0) {
          char new_mode[]{mode, 0};
          __mode(new_mode, 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.
      *///=========================================================================
      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 ATOMIZE_FLAGS for a list of options
      const int flags = ATOMIZE_DEFAULT,
      /// Set the modes (@c nullptr default means don't set the modes) @n
      /// 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" = is a key-value pair / "" = not a key-value pair@n
      /// 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) __mode(mode);
        __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.
      *///=========================================================================
      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 ATOMIZE_FLAGS for a list of options
      const int flags,
      /// Set the modes (@c 0 default means don't set the modes) @n
      /// 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" = is a key-value pair / "" = not a key-value pair@n
      /// 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;
        if (mode != 0) {
          char new_mode[]{mode, 0};
          __mode(new_mode, false);
        } // -x- if mode -x-
        __assign(intake.data(), len >= 0 ? len : intake.size());
      } // -x- constructor Atomize -x-
 
      /*======================================================================*//**
      @brief
      Destructor.
      *///=========================================================================
      ~Atomize() noexcept {
        __clear();
      } // -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
      @returns Entire atom
      @see get
      @see get_key
      @see get_value
      @see operator[]
      *///=========================================================================
      std::string at(
      /// Which atom to obtain (0 = first atom; negative values count backward from
      /// the last atom in the internal array)
      int index,
      /// Temporarily override the current modes (@c nullptr default means don't
      /// change modes) @n
      /// 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" = is a key-value pair / "" = not a key-value pair@n
      /// 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.
        // --------------------------------------------------------------------------
        if (index < 0) index = __data_points.size() + index;
        __atom* atom = __data_points[index];
        std::string previous_mode;
 
        // --------------------------------------------------------------------------
        // Save and change modes.
        // --------------------------------------------------------------------------
        if (mode != nullptr) {
          previous_mode = this->mode(); // Save current mode
          __mode(mode);
        } // -x- if mode -x-
 
        // --------------------------------------------------------------------------
        // Presence of key-value pair (results in ignoring all other modes).
        // --------------------------------------------------------------------------
        if (mode_p) return atom->vpos != 0 ? "1" : "";
 
        // --------------------------------------------------------------------------
        // Key/Value mode.
        // --------------------------------------------------------------------------
        std::string str;
             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 (int 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 (int 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 (int 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 previously saved modes.
        // --------------------------------------------------------------------------
        if (mode != nullptr) this->mode(previous_mode.data());
 
        return str;
      } // -x- std::string at -x-
 
      /*======================================================================*//**
      @brief
      Clear this Atomize's underlying data and reset all states.  This does not
      reset nor alter flags or modes.
      @returns The same Atomize object so as to facilitate stacking
      *///=========================================================================
      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 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 flags(const int)
      @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 flags
      @see mode
      *///=========================================================================
      Atomize* flags(
      /// See @ref ATOMIZE_FLAGS for a list of options
      const int flags) {
        __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 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 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 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 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@n
               FALSE = this atom was not split into a key-value pair
      @see at
      @see get
      @see get_key
      @see get_value
      @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 flags
      @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-
 
  private:
      /*======================================================================*//**
      @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 the base defaults.
      @throws std::invalid_argument if an incorrect value is provided
      @returns The same Atomize object so as to facilitate stacking
      *///=========================================================================
      void __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" = is a key-value pair / "" = not a key-value pair@n
      /// 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,
      /// This is primarily used by the empty constructor@n
      /// TRUE = invalid mode throws an std::invalid_argument exception (default) @n
      /// FALSE = ignore invalid mode
      const bool throw_exception = true) {
 
        // --------------------------------------------------------------------------
        // Clear all settings.
        // --------------------------------------------------------------------------
        mode_k = false;
        mode_v = false;
        mode_p = false;
        mode_c = false;
        mode_f = false;
        mode_l = false;
        mode_u = false;
 
        // --------------------------------------------------------------------------
        // Set modes (duplicates are effectively ignored, and 0 never shows up here
        // because it terminates the string).
        // --------------------------------------------------------------------------
        const size_t len = std::strlen(mode);
        for (int i = 0; i < len; i++) {
          switch (mode[i]) {
            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[i]) + "\"");
          } // -x- switch mode[i] -x-
        } // -x- for i -x-
 
      } // -x- void mode -x-
 
  public:
      /*======================================================================*//**
      @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 the base defaults.
      @throws std::invalid_argument if an incorrect value is provided
      @returns The same Atomize object so as to facilitate stacking
      @see flags
      @see mode
      *///=========================================================================
      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" = is a key-value pair / "" = not a key-value pair@n
      /// 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) {
        __mode(mode);
        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 the base defaults.
      @throws std::invalid_argument if an incorrect value is provided
      @returns The same Atomize object so as to facilitate stacking
      @see flags
      @see mode
      *///=========================================================================
      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" = is a key-value pair / "" = not a key-value pair@n
      /// 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) {
        char new_mode[]{mode, 0};
        __mode(new_mode, false);
        return this;
      } // -x- Atomize* mode -x-
 
      /*======================================================================*//**
      @brief
      Return the total quantity of atoms.
      @returns Quantity of atoms
      @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 (int 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 (int 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 mode
      *///=========================================================================
      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-