rline

#pragma once
 
#include <cstring>
#include <vector>
 
namespace randolf {
 
  /*======================================================================*//**
  @brief
  One line of text is stored in this class, with additional metadata to track
  whether the text was terminated by an EoL (End of Line) sequence, and, if so,
  what the EoL sequence was.
 
  This is particularly useful for reading lines of text from a file or a socket
  without having to go to additional efforts to track whether the final line is
  terminated with an EoL sequence (since this class takes care of this detail).
 
  By default, the EoL sequence may be &lt;CR&gt;, &lt;LF&gt;, &lt;CRLF&gt;, or
  &lt;LFCR&gt;.
 
  @par Use case
  One of the challenges with the @c std::string class is that it doesn't
  provide a way to differentiate between a empty line and @c NULL, unless one
  uses pointers to @c std::string objects and sets thoes pointers to @c nullptr
  which entails having to test for that, resulting in more code in various
  places to test for multiple conditions, thus providing opportunities for more
  unintended situations (a.k.a., bugs) ... and then there's the matter of how
  to handle the variety of EoL sequences that persist due to the diversity of
  Operating System standards, which complicates matters even more.
 
  This class handles all of these details gracefully, and provides a thorough
  variety of clearly-documented methods that ensure consistency whilst handling
  the complexity of EoL sequences that may be 1 or 2 characters long and also
  differentiating between blank and NULL lines, all without causing significant
  increases in complexity in code.
 
  @par History
    - 2024-Nov-16 v1.00 Initial version
    - 2025-Jan-05 v1.00 Added c_str(), data(), and append(char*, int) methods,
                        and the rline(std::string, std::string) constructor
    - 2025-Jan-09 v1.00 Added @ref eol(char, char) and @ref eol(std::string)
                        methods for configuring a specific EoL sequence
    - 2025-Jan-12 v1.00 Changed std::length_error to std::invalid_argument in
                        response to length being specified as a negative value
                        so this can more easily be handled with seperate code;
                        added the @c at() method, and [], ==, and != operators
    - 2025-Jan-13 v1.00 Improved internal support for EoL flag indication
    - 2025-Feb-03 v1.00 Increased use of references and pointers
    - 2025-Feb-09 v1.00 Added a constructor, and @ref append(), @ref assign(),
                        and @ref to_vector(), methods, and, finally, also an
                        `operator std::vector<char>` method, all of which make
                        easy to work with data in `std::vector<char>` arrays
    - 2025-Feb-10 v1.00 Added @ref clear_all() method (which complements the
                        @ref clear() method)
    - 2025-Feb-13 v1.00 Added @ref append(const char) method, and @ref first()
                        and @ref last() methods
  @version 1.00
  @author Randolf Richardson
  *///=========================================================================
  class rline {
    private:
      std::string __line; // Text data without EoL sequence
      char        __eol_detected[3]   = {'\0', '\0', '\0'}; // EoL sequence detected (default = none)
      int         __eol_detected_size = 0;                  // EoL sequence detected size (default = 0)
      char        __eol_standard[3]   = {'\0', '\0', '\0'}; // EoL sequence standard (default = none/autodetect)
      int         __eol_standard_size = 0;                  // EoL sequence standard size (default = 0)
 
      /*======================================================================*//**
      @brief
      Internal line-of-text intake method used by constructors and other methods.
      @returns TRUE = EoL sequence was encountered@n
               FALSE = EoL sequence is not present
      *///=========================================================================
      bool __rline(
      /// Line of text to embrace
      const char* line,
      /// Length of data (-1 = ASCIIZ string)
      int len = -1) noexcept {
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
        if (line == nullptr) return false; // A null string was provided, so we can avoid a lot of processing
 
//std::cout << "__rline len=" << __line.size() << " data=[" << data << "]" << std::endl;
        // --------------------------------------------------------------------------
        // Measure size of line if an ASCIIZ string was indicated.
        // --------------------------------------------------------------------------
        if (len == -1) len = std::strlen(line);
        if (len ==  0) return false; // Empty line provided, so this is an easy finish
 
        // --------------------------------------------------------------------------
        // Pre-allocate memory in std::string so that we can write directly to the
        // underlying array, which is the most efficient (fastest) way.
        // --------------------------------------------------------------------------
        int offset = __line.size();
        __line.resize(offset + len); // In case of a dymamic realloc(), this must be done before calling __line.data()
        char* __line_data = __line.data();
 
//std::cout << "__rline len=" << len << " offset=" << offset << " line=[" << line << "]" << std::endl;
//std::cout << "__rline len=" << len << " offset=" << offset << std::endl;
        // --------------------------------------------------------------------------
        // Detect existing (as in already-defined) EoL sequence while copying data.
        // --------------------------------------------------------------------------
        if (__eol_standard_size != 0) {
//std::cout << "__eol_sequence_size != 0" << std::endl;
 
          // --------------------------------------------------------------------------
          // Internal variables.
          // --------------------------------------------------------------------------
          char c;
          char e = __eol_standard[0];
          int  i;
 
          // --------------------------------------------------------------------------
          // Check for edge case with 2-character EoL sequence carries over from
          // existing line data.
          // --------------------------------------------------------------------------
          if (offset > 0 && __eol_standard_size == 2) {
            if (__line[offset - 1] == e && line[0] == __eol_standard[1]) {
              __line.resize(__line.size() - 1); // Crop previous character
              __eol_detected[0]   = e;
              __eol_detected[1]   = line[0];
              __eol_detected_size = __eol_standard_size;
              return true;
            } // -x- if e -x-
          } // -x- if !offset -x-
 
//std::cout << "__rline len=" << len << " offset=" << offset << " line=[" << line << "]" << std::endl;
          // --------------------------------------------------------------------------
          // Copy data.
          // --------------------------------------------------------------------------
          for (i = 0; i < len; i++) {
 
            // --------------------------------------------------------------------------
            // Obtain next character to absorb.
            // --------------------------------------------------------------------------
            c = line[i];
 
            // --------------------------------------------------------------------------
            // EoL sequence detected.  If this is a one-character EoL sequence, then it
            // matches and we're done; or if this is a two-character EoL sequence, then
            // it also must match; otherwise the sequence will be ignored and treated as
            // a normal part of the text.
            // --------------------------------------------------------------------------
            if (c == e) {
              if (__eol_standard_size == 1) {
                __eol_detected[0]   = e;//__eol_standard[0];
                __eol_detected[1]   = 0;//__eol_standard[1];
                __eol_detected_size = 1;
                break;
              } // -x- if 1 -x-
              if ((i + 1) < len && line[i + 1] == __eol_standard[1]) {
                __eol_detected[0]   = e;
                __eol_detected[1]   = __eol_standard[1];
                __eol_detected_size = 2;
                break;
              } // -x- if 2 -x-
 
            } // -x- if c -x-
 
            // --------------------------------------------------------------------------
            // Append character to internal __line by writing directly to the underlying
            // array (which is the most efficienty way to store it), then advance the
            // offset index.
            // --------------------------------------------------------------------------
            __line_data[offset++] = c;
 
          } // -x- for i -x-
 
        // --------------------------------------------------------------------------
        // Automatic EoL sequence detection while copying data.
        // --------------------------------------------------------------------------
        } else { // This "else" statement is effectively the same as:  if (eol_standard_size == 0)
//std::cout << "__eol_sequence_size == 0" << std::endl;
 
          // --------------------------------------------------------------------------
          // Internal variables.
          // --------------------------------------------------------------------------
          char c;
          int  i;
 
//std::cout << "__rline len=" << len << " offset=" << offset << " line=[" << line << "]" << std::endl;
          // --------------------------------------------------------------------------
          // Copy data.
          // --------------------------------------------------------------------------
          for (i = 0; i < len; i++) {
 
            // --------------------------------------------------------------------------
            // Obtain next character to absorb.
            // --------------------------------------------------------------------------
            c = line[i];
 
            // --------------------------------------------------------------------------
            // LF detected, so save it and exit the loop, while also advancing
            // __eol_sequence_size (in two places if this is a broken LFCR sequence).  We
            // do need to compare "i" against "len" to prevent a 1-byte index overflow.
            // --------------------------------------------------------------------------
            if (c == 10) { // LF detected
              __eol_detected_size = __eol_standard_size;
              __eol_detected[__eol_detected_size++] = c;
              __eol_standard[__eol_standard_size++] = c;
              if ((i + 1) < len && line[i + 1] == 13) { // CR detected, so save it too
                __eol_detected[__eol_detected_size++] = 13;
                __eol_standard[__eol_standard_size++] = 13;
              } // -x- if CR -x-
//std::cout << "__eol_detected_size<LF>=" << __eol_detected_size << std::endl;
              break;
 
            // --------------------------------------------------------------------------
            // CR detected, so save it and exit the loop, while also advancing
            // __eol_sequence_size (in two places if this is a valid CRLF sequence).  We
            // do need to compare "i" against "len" to prevent a 1-byte index overflow.
            // --------------------------------------------------------------------------
            } else if (c == 13) { // CR detected
              __eol_detected_size = __eol_standard_size;
              __eol_detected[__eol_detected_size++] = c;
              __eol_standard[__eol_standard_size++] = c;
              if ((i + 1) < len && line[i + 1] == 10) { // LF detected, so save it too
                __eol_detected[__eol_detected_size++] = 10; // LF detected, so save it too
                __eol_standard[__eol_standard_size++] = 10; // LF detected, so save it too
              } // -x- if LF -x-
//std::cout << "__eol_detected_size<CR>=" << __eol_detected_size << std::endl;
              break;
 
            } // -x- if CR/LF -x-
 
            // --------------------------------------------------------------------------
            // Append character to internal __line by writing directly to the underlying
            // array (which is the most efficienty way to store it), then advance the
            // offset index.
            // --------------------------------------------------------------------------
            __line_data[offset++] = c;
//std::cout << "c=" << c << " offset=" << offset << std::endl;
 
          } // -x- for i -x-
 
        } // -x- if !__eol_standar_size -x-
 
        // --------------------------------------------------------------------------
        // The "offset" variable was updated by the loop to ensure it holds the
        // accurate length of __line internally.  The "i" variable was loop-local.
        // --------------------------------------------------------------------------
        __line.resize(offset);
//std::cout << "offset=" << offset << " __line=[" << get() << "]" << std::endl;
 
        return __eol_standard_size > 0; // TRUE = EoL sequence was encountered
      } // -x- bool __rline -x-
 
    public:
      /*======================================================================*//**
      @brief
      Instantiate an empty rline, with no EoL sequences present.
      *///=========================================================================
      rline() noexcept {} // -x- constructor rline -x-
 
      /*======================================================================*//**
      @brief
      Instantiate a new rline based on the supplied line of text, ending early upon
      encountering the first EoL sequence (use either the @ref size(bool) or the
      @ref size_with_eol() method to obtain the total quantity of characters that
      were absorbed, including the EoL sequence {if present}).
 
      If no EoL sequence was encountered, the @ref has_eol() method will return
      `false` even though the contents of the supplied line were copied (and are
      still accessible) -- this is useful in loops reading lines of text that are
      too long to store in memory with a single allocation (and either interpreting
      the absorbed data somehow, or using a simple loop to skip through to the end
      of the line before issuing an error that indicates the total line length).
      @note
      If @c line is a @c nullptr then it will be treated as an empty string without
      an EoL sequence, instead of throwing a Null Pointer Exception.  This provides
      an opportunity to write simpler code (see the @ref is_null method for the way
      to check for this condition, which also happens to be the result of using the
      default constructor or calling @ref clear).
      @see assign
      @see clear
      @see has_eol
      @see is_null
      @see size
      @see size_with_eol
      *///=========================================================================
      rline(
      /// Line of text to embrace
      const char* line,
      /// Length of line (-1 == ASCIIZ string)
      const size_t len = -1) noexcept {
        __rline(line, len);
      } // -x- constructor rline -x-
 
      /*======================================================================*//**
      @brief
      Instantiate a new rline based on the supplied line of text, ending early upon
      encountering the first EoL sequence (use either the `size(true)` or the
      `size_full()` method to obtain the total quantity of characters that were
      absorbed, including the EoL sequence {if present}).
 
      If no EoL sequence was encountered, the @ref has_eol() method will return
      `false` even though the contents of the supplied line were copied (and are
      still accessible) -- this is useful in loops reading lines of text that are
      too long to store in memory with a single allocation (and either interpreting
      the absorbed data somehow, or using a simple loop to skip through to the end
      of the line before issuing an error that indicates the total line length).
      @see assign
      @see has_eol
      @see is_null
      @see size
      @see size_with_eol
      *///=========================================================================
      rline(
      /// Line of text to embrace
      const std::string& line,
      /// Length of line (-1 == defer to length of line provided)
      const size_t len = -1) noexcept {
        __rline(line.data(), len == -1 ? line.length() : len);
      } // -x- constructor rline -x-
 
      /*======================================================================*//**
      @brief
      Instantiate a new rline based on the supplied line of text, ending early upon
      encountering the first EoL sequence (the `size(true)` and `size_full()`
      methods obtain the total quantity of characters that were absorbed, including
      the EoL sequence {if present}).
 
      If no EoL sequence was encountered, the @ref has_eol() method will return
      `false` even though the contents of the supplied line were copied (and are
      still accessible) -- this is useful in loops reading lines of text that are
      too long to store in memory with a single allocation (and either interpreting
      the absorbed data somehow, or using a simple loop to skip through to the end
      of the line before issuing an error that indicates the total line length).
      @throws std::length_error if the EoL sequence is longer than 2 characters
      @see assign
      @see has_eol
      @see is_null
      @see size
      @see size_with_eol
      *///=========================================================================
      rline(
      /// Line of text to embrace, without the EoL sequence characters
      const std::string& line,
      /// The EoL sequence to impose as if it had been detected (may be only 1 or 2
      /// characters long)
      const std::string& eol_sequence) {
 
          // --------------------------------------------------------------------------
          // Save EoL sequence while also performing a simple syntax check.
          // --------------------------------------------------------------------------
          switch (eol_sequence.size()) {
            case 2:
              __eol_detected[0]   = __eol_standard[0]   = eol_sequence[0];
              __eol_detected[1]   = __eol_standard[1]   = eol_sequence[1];
              __eol_detected_size = __eol_standard_size = 2;
              break;
            case 1:
              __eol_detected[0]   = __eol_standard[0]   = eol_sequence[0];
              __eol_detected[1]   = __eol_standard[1]   = '\0';
              __eol_detected_size = __eol_standard_size = 1;
              break;
            case 0:
              __eol_detected[0]   = __eol_standard[0]   = '\0';
              __eol_detected[1]   = __eol_standard[1]   = '\0';
              __eol_detected_size = __eol_standard_size = 0;
              break;
            deafult: // Any other length is invalid
              throw std::length_error("eol_sequence is too long (maximum length is 2 characters)");
          } // -x- switch eol_sequence.size -x-
 
        // --------------------------------------------------------------------------
        // Set line of text.
        // --------------------------------------------------------------------------
        __rline(line.data(), line.length());
 
      } // -x- constructor rline -x-
 
      /*======================================================================*//**
      @brief
      Instantiate a new rline based on the supplied line of text, ending early upon
      encountering the first EoL sequence (use either the `size(true)` or the
      `size_full()` method to obtain the total quantity of characters that were
      absorbed, including the EoL sequence {if present}).
 
      If no EoL sequence was encountered, the @ref has_eol() method will return
      `false` even though the contents of the supplied line were copied (and are
      still accessible) -- this is useful in loops reading lines of text that are
      too long to store in memory with a single allocation (and either interpreting
      the absorbed data somehow, or using a simple loop to skip through to the end
      of the line before issuing an error that indicates the total line length).
      @see assign
      @see has_eol
      @see is_null
      @see size
      @see size_with_eol
      *///=========================================================================
      rline(
      /// Line of text to embrace
      const std::vector<char>& line,
      /// Length of line (-1 == defer to length of line provided)
      const size_t len = -1) noexcept {
        __rline(line.data(), len == -1 ? line.size() : len);
      } // -x- constructor rline -x-
 
      /*======================================================================*//**
      @brief
      Add the specified character (without checking whether it's part of an EoL
      character sequence) onto the line of text (before the EoL sequence).
      @returns The same rline object so as to facilitate stacking
      @see assign
      @see insert
      *///=========================================================================
      rline& append(
      /// The string to insert
      const char character) {
        char ch[] = { character, 0 };
        __rline(ch, 1);
        return *this;
      } // -x- rline& append -x-
 
      /*======================================================================*//**
      @brief
      Add the specified string (without checking whether it contains any EoL
      character sequences) onto the line of text (before the EoL sequence).
      @returns The same rline object so as to facilitate stacking
      @see assign
      @see insert
      *///=========================================================================
      rline& append(
      /// The string to insert
      const char* line,
      /// Length of line (-1 == ASCIIZ string)
      const size_t len = -1) {
        __rline(line, len);
        return *this;
      } // -x- rline& append -x-
 
      /*======================================================================*//**
      @brief
      Add the specified std::string (without checking whether it contains any EoL
      character sequences) onto the line of text (before the EoL sequence).
      @returns The same rline object so as to facilitate stacking
      @see assign
      @see insert
      *///=========================================================================
      rline& append(
      /// The string to insert
      const std::string& line,
      /// Length of line (-1 == defer to length of line provided)
      const size_t len = -1) {
        __rline(line.data(), len == -1 ? line.length() : len);
        return *this;
      } // -x- rline& append -x-
 
      /*======================================================================*//**
      @brief
      Add the specified std::vector<char> (without checking whether it contains any
      EoL character sequences) onto the line of text (before the EoL sequence).
      @returns The same rline object so as to facilitate stacking
      @see assign
      @see insert
      *///=========================================================================
      rline& append(
      /// The data to insert
      const std::vector<char>& line,
      /// Length of line (-1 == defer to length of line provided)
      const size_t len = -1) {
        __rline(line.data(), len == -1 ? line.size() : len);
        return *this;
      } // -x- rline& append -x-
 
      /*======================================================================*//**
      @brief
      Assign a new rline based on the supplied line of text, ending early upon
      encountering the first EoL sequence (use either the @ref size(bool) or the
      @ref size_with_eol() method to obtain the total quantity of characters that
      were absorbed, including the EoL sequence {if present}).
 
      If no EoL sequence was encountered, the @ref has_eol() method will return
      `false` even though the contents of the supplied line were copied (and are
      still accessible) -- this is useful in loops reading lines of text that are
      too long to store in memory with a single allocation (and either interpreting
      the absorbed data somehow, or using a simple loop to skip through to the end
      of the line before issuing an error that indicates the total line length).
      @note
      If @c line is a @c nullptr then it will be treated as an empty string without
      an EoL sequence, instead of throwing a Null Pointer Exception.  This provides
      an opportunity to write simpler code (see the @ref is_null method for the way
      to check for this condition, which also happens to be the result of using the
      default constructor or calling @ref clear).
      @returns The same rline object so as to facilitate stacking
      @see append
      @see clear
      @see has_eol
      @see insert
      @see is_null
      @see size
      @see size_with_eol
      *///=========================================================================
      rline& assign(
      /// Line of text to embrace
      const char* line,
      /// Length of line (-1 == ASCIIZ string)
      const size_t len = -1) noexcept {
 
        // --------------------------------------------------------------------------
        // Reset internal variables.
        // --------------------------------------------------------------------------
        __line.clear();
 
        // --------------------------------------------------------------------------
        // Replace line of text.
        // --------------------------------------------------------------------------
        __rline(line, len);
 
        return *this;
      } // -x- rline& assign -x-
 
      /*======================================================================*//**
      @brief
      Assign a new rline based on the supplied line of text, ending early upon
      encountering the first EoL sequence (use either the @ref size(bool) or the
      @ref size_with_eol() method to obtain the total quantity of characters that
      were absorbed, including the EoL sequence {if present}).
 
      If no EoL sequence was encountered, the @ref has_eol() method will return
      `false` even though the contents of the supplied line were copied (and are
      still accessible) -- this is useful in loops reading lines of text that are
      too long to store in memory with a single allocation (and either interpreting
      the absorbed data somehow, or using a simple loop to skip through to the end
      of the line before issuing an error that indicates the total line length).
      @returns The same rline object so as to facilitate stacking
      @see append
      @see has_eol
      @see insert
      @see is_null
      @see size
      @see size_with_eol
      *///=========================================================================
      rline& assign(
      /// Line of text to embrace
      const std::string& line,
      /// Length of line (-1 == defer to length of line provided)
      const size_t len = -1) noexcept {
 
        // --------------------------------------------------------------------------
        // Reset internal variables.
        // --------------------------------------------------------------------------
        __line.clear();
 
        // --------------------------------------------------------------------------
        // Replace line of text.
        // --------------------------------------------------------------------------
        __rline(line.data(), len == -1 ? line.length() : len);
 
        return *this;
      } // -x- rline& assign -x-
 
      /*======================================================================*//**
      @brief
      Assign a new rline based on the supplied line of text, ending early upon
      encountering the first EoL sequence (use either the @ref size(bool) or the
      @ref size_with_eol() method to obtain the total quantity of characters that
      were absorbed, including the EoL sequence {if present}).
 
      If no EoL sequence was encountered, the @ref has_eol() method will return
      `false` even though the contents of the supplied line were copied (and are
      still accessible) -- this is useful in loops reading lines of text that are
      too long to store in memory with a single allocation (and either interpreting
      the absorbed data somehow, or using a simple loop to skip through to the end
      of the line before issuing an error that indicates the total line length).
      @returns The same rline object so as to facilitate stacking
      @see append
      @see has_eol
      @see insert
      @see is_null
      @see size
      @see size_with_eol
      *///=========================================================================
      rline& assign(
      /// Line of text to embrace
      const std::vector<char>& line,
      /// Length of line (-1 == defer to length of line provided)
      const size_t len = -1) noexcept {
 
        // --------------------------------------------------------------------------
        // Reset internal variables.
        // --------------------------------------------------------------------------
        __line.clear();
 
        // --------------------------------------------------------------------------
        // Replace line of text.
        // --------------------------------------------------------------------------
        __rline(line.data(), len == -1 ? line.size() : len);
 
        return *this;
      } // -x- rline& assign -x-
 
      /*======================================================================*//**
      @brief
      Array-style access to the underlying std::string (without the EoL sequence).
 
      The first element is at index 0.
      @throws std::out_of_range if the index is out-of-range
      @returns char
      @see first
      @see last
      @see operator[]
      *///=========================================================================
      char at(
      /// Index of character to access (0 = first element; negative index values
      /// are calculated in reverse, starting with -1 as the final position)
      const int index) {
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        int MAX = __line.length();
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
        if (index >= MAX || 0 - index > MAX) throw std::out_of_range("index (position=" + std::to_string(index) + ") falls outside of the underlying string (length=" + std::to_string(MAX) + ")");
 
        return __line[index >= 0 ? index : MAX - index];
      } // -x- char at -x-
 
      /*======================================================================*//**
      @brief
      Reset all data (including the detected EoL sequence) while preserving
      internal flags (including the established EoL standard).
      @returns The same rline object so as to facilitate stacking
      *///=========================================================================
      rline& clear() noexcept {
 
        // --------------------------------------------------------------------------
        // Reset internal variables.
        // --------------------------------------------------------------------------
        __eol_detected[0]   = '\0';
        __eol_detected[1]   = '\0';
        __eol_detected_size = 0;
        __line.clear();
 
        return *this;
      } // -x- rline& clear -x-
 
      /*======================================================================*//**
      @brief
      Reset all data (including the detected EoL sequence) and reset internal flags
      (including the established EoL standard) to be like the original state of the
      constructor that has no parameters.
      @returns The same rline object so as to facilitate stacking
      *///=========================================================================
      rline& clear_all() noexcept {
 
        // --------------------------------------------------------------------------
        // Reset internal variables.
        // --------------------------------------------------------------------------
        __eol_detected[0]   = __eol_standard[0] = '\0';
        __eol_detected[1]   = __eol_standard[1] = '\0';
        __eol_detected_size = __eol_standard_size = 0;
        __line.clear();
 
        return *this;
      } // -x- rline& clear_all -x-
 
      /*======================================================================*//**
      @brief
      Returns a pointer to the underlying string array, without the EoL sequence.
      @returns Pointer to buffer (null terminated)
      @see data
      *///=========================================================================
      const char* c_str() noexcept {
        return __line.c_str();
      } // -x- char* c_str -x-
 
      /*======================================================================*//**
      @brief
      Returns a pointer to the underlying string array, without the EoL sequence.
      @returns Pointer to buffer (not null terminated)
      @see c_str
      *///=========================================================================
      char* data() noexcept {
        return __line.data();
      } // -x- char* data -x-
 
      /*======================================================================*//**
      @brief
      Obtain a copy of the EoL sequence that was detected.
      @returns A pointer to the EoL sequence as a @c char[] array
      @see eol
      @see get
      *///=========================================================================
      const char* data_eol(
      /// TRUE = return the detected EoL sequence (default) @n
      /// FALSE = return the EoL sequence to use when detecting an EoL sequence
      const bool detected = true) noexcept {
        return detected ? __eol_detected : __eol_standard;
      } // -x- char* data_eol -x-
 
      /*======================================================================*//**
      @brief
      Returns a pointer to the underlying std::string object, without the EoL
      sequence.
      @returns Pointer to buffer (not null terminated)
      @see c_str
      @see to_vector
      *///=========================================================================
      std::string* data_string() noexcept {
        return &__line;
      } // -x- std::string* data -x-
 
      /*======================================================================*//**
      @brief
      Indicate whether the line of text is empty.  Whether an EoL sequence is
      present is incidental since this only measures the size of the line of text
      without regard for the presence of an EoL sequence.
      @returns TRUE = Line of text is empty@n
               FALSE = Line of text is not empty
      @see has_eol()
      @see is_null()
      *///=========================================================================
      bool empty() noexcept {
        return __line.empty();
      } // -x- bool empty -x-
 
      /*======================================================================*//**
      @brief
      Obtain a copy of the EoL sequence that was detected.
      @returns The EoL sequence as a string
      @see data_eol
      @see get
      *///=========================================================================
      const std::string eol(
      /// TRUE = return the detected EoL sequence (default) @n
      /// FALSE = return the EoL sequence to use when detecting an EoL sequence
      const bool detected = true) noexcept {
        return std::string(detected ? __eol_detected : __eol_standard);
      } // -x- std::string& eol -x-
 
      /*======================================================================*//**
      @brief
      Define the EoL sequence to use when detecting an EoL sequence (also clears
      the detected EoL sequence, if present).
      @note
      This method is the most efficient @c eol method to use for defining the
      specific EoL sequence to use.
      @returns The same rline object so as to facilitate stacking
      @see eol
      *///=========================================================================
      rline& eol(
      /// The first character of the EoL sequence (typically 10 or 13)@c
      /// 10 = LF (Line Feed) @n
      /// 13 = CR (Carriage Return) @n
      /// 0 = enable EoL sequence auto-detection (this is the default in all
      /// constructors, and is also set by the @ref clear method)
      const char c1,
      /// The second character of the EoL sequence (typically 10 or 13)@c
      /// 10 = LF (Line Feed) @n
      /// 13 = CR (Carriage Return) @n
      /// 0 = indicate that this is not a two-character EoL sequence
      const char c2 = 0) noexcept {
 
        // --------------------------------------------------------------------------
        // Save EoL sequence.
        // --------------------------------------------------------------------------
        __eol_detected[0] = __eol_detected[1] = 0;
        __eol_standard[0] = c1;
        __eol_standard[1] = c1 == 0 ? 0 : c2;
 
        // --------------------------------------------------------------------------
        // Calculate the size of the EoL sequence.
        // --------------------------------------------------------------------------
        __eol_detected_size = 0;
        __eol_standard_size = 2;
        if (c2 == 0) __eol_standard_size = 1;
        if (c1 == 0) __eol_standard_size = 0;
 
        return *this;
      } // -x- rline& eol -x-
 
      /*======================================================================*//**
      @brief
      Define the EoL sequence to use when detecting an EoL sequence (also clears
      the detected EoL sequence, if present).
      @throws std::length_error if the EoL sequence is longer than 2 characters
      @returns The same rline object so as to facilitate stacking
      @see eol
      *///=========================================================================
      rline& eol(
      /// The EoL sequence (may be only 1 or 2 characters long; or 0 characters to
      /// enable EoL auto-detection, which is also the default in all constructors)
      const std::string& eol_sequence) {
 
        // --------------------------------------------------------------------------
        // Save EoL sequence while also performing a simple syntax check.
        // --------------------------------------------------------------------------
        switch (eol_sequence.size()) {
          case 2:
            __eol_detected[0]   = __eol_detected[1] = 0;
            __eol_standard[0]   = eol_sequence[0];
            __eol_standard[1]   = eol_sequence[1];
            __eol_detected_size = 0;
            __eol_standard_size = 2;
            break;
          case 1:
            __eol_detected[0]   = __eol_detected[1] = 0;
            __eol_standard[0]   = eol_sequence[0];
            __eol_standard[1]   = '\0';
            __eol_detected_size = 0;
            __eol_standard_size = 1;
            break;
          case 0:
            __eol_detected[0]   = __eol_detected[1] = 0;
            __eol_standard[0]   = '\0';
            __eol_standard[1]   = '\0';
            __eol_detected_size = 0;
            __eol_standard_size = 0;
            break;
          deafult: // Any other length is invalid
            throw std::length_error("eol_sequence is too long (maximum length is 2 characters)");
        } // -x- switch eol_sequence.size -x-
 
        return *this;
      } // -x- rline& eol -x-
 
      /*======================================================================*//**
      @brief
      Return the first character from the underlying std::string (not including the
      EoL sequence).
      @throws std::out_of_range if the underlying string is empty
      @returns char
      @see at
      @see last
      @see operator[]
      *///=========================================================================
      char first() {
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
        if (__line.empty()) throw std::out_of_range("first() is out of range because rline is empty");
 
        return __line.front();
      } // -x- char first -x-
 
      /*======================================================================*//**
      @brief
      Obtain a copy of the entire line of text, without the EoL sequence (albeit by
      default, this can also be included by setting the @c include_eol flag).
      @returns The line of text as a string
      @see eol
      @see data_eol
      *///=========================================================================
      const std::string get(
      /// Whether to include the EoL detected (default = FALSE)
      const bool include_eol = false) noexcept {
        return std::string(include_eol ? __line + __eol_detected : __line);
      } // -x- std::string get -x-
 
      /*======================================================================*//**
      @brief
      Indicate whether an EoL sequence was detected.
      @returns TRUE = EoL sequence is present@n
               FALSE = No EoL sequence
      @see empty
      *///=========================================================================
      bool has_eol() noexcept {
        return __eol_detected_size != 0;
      } // -x- bool has_eol -x-
 
      /*======================================================================*//**
      @brief
      Indicate whether a broken EoL sequence detected of `<LFCR>` is being used as
      the EoL sequence.
      @returns TRUE = Broken EoL sequence is present@n
               FALSE = No broken EoL sequence
      @see empty
      *///=========================================================================
      bool has_LFCR(
      /// TRUE = report on whether a broken EoL sequence was detected (default) @n
      /// FALSE = report on whether a broken EoL sequence was specifically defined
      ///         as the EoL sequence to detect
      const bool detected = true) noexcept {
        if (true) return __eol_detected_size == 2 && __eol_detected[0] == 10 && __eol_detected[1] == 13;
        else      return __eol_standard_size == 2 && __eol_standard[0] == 10 && __eol_standard[1] == 13;
      } // -x- bool has_LFCR -x-
 
      /*======================================================================*//**
      @brief
      Insert the specified string (without checking whether it contains any EoL
      character sequences) into the line of text at the specified position.
      @exception std::out_of_range When the position (@c pos) provided is out of
                                   range (e.g., position is larger than the entire
                                   size of the string)
      @returns The same rline object so as to facilitate stacking
      @see append
      @see assign
      *///=========================================================================
      rline& insert(
      /// Where to insert the supplied string (0 = insert before first character;
      /// and use a negative number to set the position relative to the end of the
      /// line of text)
      const int position, // Must be "int" and not "size_t" because size_t is unsigned
      /// The string to insert
      const std::string& str,
      /// Length of string (-1 == defer to length of string provided)
      const size_t len = -1) {
//std::cout << "str=[" << str << "] position=" << (position >= 0 ? position : __line.size() + position) << std::endl;
        __line.insert((position >= 0 ? position : __line.size() + position),
                      str,
                      0,
                      len == -1 ? str.size() : len);
//std::cout << "__line=[" << __line << "]" << std::endl;
        return *this;
      } // -x- rline& insert -x-
 
      /*======================================================================*//**
      @brief
      Indicate whether this line is non-existent, which means there is no text and
      no detected EoL sequence.  This is less than an an @ref empty() string when
      it confirms that there literally are no characters at all.
      @returns TRUE = null string@n
               FALSE = not null (has text and/or an EoL
      sequence)
      @see empty
      *///=========================================================================
      bool is_null() noexcept {
        return (__line.size() + __eol_detected_size) == 0;
      } // -x- bool is_null -x-
 
      /*======================================================================*//**
      @brief
      Return the last character from the underlying std::string (not including the
      EoL sequence).
      @throws std::out_of_range if the underlying string is empty
      @returns char
      @see at
      @see first
      @see operator[]
      *///=========================================================================
      char last() {
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
        if (__line.empty()) throw std::out_of_range("last() is out of range because rline is empty");
 
        return __line.back();
      } // -x- char last -x-
 
      /*======================================================================*//**
      @brief
      Provides the length of the line of text without the EoL sequence.
 
      This method is identital to the @ref size method.
      @returns Number of bytes
      @see size
      *///=========================================================================
      size_t length(
      /// Whether to include the EoL sequence (default = FALSE)
      const bool include_eol = false) noexcept {
        return include_eol ? __line.size() + __eol_detected_size : __line.size();
      } // -x- size_t length -x-
 
      /*======================================================================*//**
      @brief
      Provides the length of the line of text without the EoL sequence.
 
      This method is identital to the @ref length method.
      @returns Number of bytes
      @see length
      @see size_eol
      @see size_with_eol
      *///=========================================================================
      size_t size(
      /// Whether to include the EoL sequence (default = FALSE)
      const bool include_eol = false) noexcept {
        return include_eol ? __line.size() + __eol_detected_size : __line.size();
      } // -x- size_t size -x-
 
      /*======================================================================*//**
      @brief
      Provides the length of the detected EoL sequence.
      @returns Number of bytes (0 = no EoL string)
      @see size
      *///=========================================================================
      size_t size_eol(
      /// TRUE = report on the size of the detected EoL sequence (default) @n
      /// FALSE = report on the size of the EoL sequence to use when detecting an
      ///         EoL sequence
      const bool detected = true) noexcept {
        return detected ? __eol_detected_size : __eol_standard_size;
      } // -x- size_t size_eol -x-
 
      /*======================================================================*//**
      @brief
      Provides the length of the line of text, including the EoL sequence (if one
      is present).
      @returns Number of bytes
      @see length
      @see size
      *///=========================================================================
      size_t size_with_eol() noexcept {
        return __line.size() + __eol_detected_size;
      } // -x- size_t size_with_eol -x-
 
      /*======================================================================*//**
      @brief
      Converts the underlying std::string object to `std::vector<char>`  without
      the EoL sequence, and returns it.
      @returns std::vector<char> (not null terminated)
      @see c_str
      @see to_vector
      *///=========================================================================
      std::vector<char> to_vector() noexcept {
        return std::vector<char>(__line.data(), __line.data() + __line.size());
      } // -x- std::vector<char> to_vector -x-
 
      /*======================================================================*//**
      @brief
      Convert this @c rline to an @c std::string without the EoL sequence.
 
      @code{.cpp}
        #include <iostream>      // std::cout, std::cerr, std::endl, etc.
        #include <string>        // std::string
        #include <randolf/rline>
 
        int main(int argc, char *argv[]) {
          randolf::rline rl("This is an example.\n");
          std::string s = rl;
          std::cout << "\"" << s << "\"" << std::endl;
          return EXIT_SUCCESS;
        } // -x- int main -x-
      @endcode
 
      @returns The line of text as an std::string object
      @see get
      *///=========================================================================
      operator std::string() const noexcept {
        return __line;
      } // -x- operator std::string -x-
 
      /*======================================================================*//**
      @brief
      Convert this @c rline to an `std::vector<char>` without the EoL sequence.
 
      @code{.cpp}
        #include <iostream>      // std::cout, std::cerr, std::endl, etc.
        #include <string>        // std::string
        #include <randolf/rline>
 
        int main(int argc, char *argv[]) {
          randolf::rline rl("This is an example.\n");
          std::vector<char> v = rl;
          std::cout << "\"" << v[0] << "\"" << std::endl;
          return EXIT_SUCCESS;
        } // -x- int main -x-
      @endcode
 
      @returns The line of text as an std::vector<char> object
      @see get
      *///=========================================================================
      operator std::vector<char>() const noexcept {
        return std::vector<char>(__line.data(), __line.data() + __line.size());
      } // -x- operator std::vector<char> -x-
 
      /*======================================================================*//**
      @brief
      Compare with the underlying std::string (without the EoL sequence).
      @returns TRUE = doesn't match@n
               FALSE = match
      *///=========================================================================
      bool operator!=(
      /// String to compare with
      const std::string& s) {
        return __line != s;
      } // -x- bool operator== -x-
 
      /*======================================================================*//**
      @brief
      Compare with the underlying std::string (without the EoL sequence).
      @returns TRUE = match@n
               FALSE = doesn't match
      *///=========================================================================
      bool operator==(
      /// String to compare with
      const std::string& s) {
        return __line == s;
      } // -x- bool operator== -x-
 
      /*======================================================================*//**
      @brief
      Array-style access to the underlying std::string (without the EoL sequence).
 
      The first element is at index 0.
      @throws std::out_of_range if the index is out-of-range
      @returns char
      @see at
      @see first
      @see last
      *///=========================================================================
      char operator[](
      /// Index of character to access (0 = first element; negative index values
      /// are calculated in reverse, starting with -1 as the final position)
      int index) {
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        int MAX = __line.length();
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
        if (index >= MAX || 0 - index > MAX) throw std::out_of_range("index (position=" + std::to_string(index) + ") falls outside of the underlying string (length=" + std::to_string(MAX) + ")");
 
        return __line[index >= 0 ? index : MAX - index];
      } // -x- char operator[] -x-
 
      /*======================================================================*//**
      @brief
      Support convenient streaming usage with std::cout, std::cerr, and friends.
 
      @code{.cpp}
        #include <iostream>      // std::cout, std::cerr, std::endl, etc.
        #include <string>        // std::string
        #include <randolf/rline>
 
        int main(int argc, char *argv[]) {
          randolf::rline rl("This is an example.\n");
          std::cout << "\"" << rl << "\"" << std::endl;
          return EXIT_SUCCESS;
        } // -x- int main -x-
      @endcode
 
      @returns Line of text, without EoL sequence
      *///=========================================================================
      friend std::ostream& operator<< (
      /// Output stream (provided automatically by std::cout and std::cerr)
      std::ostream& o,
      /// Object class (matched by compiler)
      rline const& c) {
        return o << &c.__line;
      } // -x- std::ostream& operator<< -x-
 
  }; // -x- class rline -x-
 
}; // -x- namespace randolf -x-