rline

#pragma once
 
#include <cstring>
 
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
  @version 1.00
  @author Randolf Richardson
  *///=========================================================================
  class rline {
    private:
      char        __eol_sequence[3] = {'\0', '\0', '\0'}; // EoL sequence (default = none)
      int         __eol_size = 0; // Size of EoL sequence (default = 0)
      bool        __eol_LFCR = false; // Only TRUE if EoL is broken <LFCR> sequence
      std::string __line; // Text data without EoL sequence
 
      /*======================================================================*//**
      @brief
      Internal line-of-text intake method used by constructors and other methods.
      *///=========================================================================
      void __rline(
      /// Line of text to embrace
      const char* line,
      /// Length of data (-1 = ASCIIZ string)
      size_t len = -1
      ) noexcept {
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
        if (line == nullptr) { // A null string was provided, so just do a clear() to prevent a Null Pointer Exception
          __eol_sequence[0] = '\0';
          __eol_sequence[1] = '\0';
          __eol_size = 0;
          __eol_LFCR = false;
          __line.clear();
          return;
        } // -x- if !line -x-
 
        // --------------------------------------------------------------------------
        // Measure size of line if an ASCIIZ string was indicated.
        // --------------------------------------------------------------------------
        if (len == -1) len = std::strlen(line);
        if (len == 0) return; // Empty line provided, so our class-defaults will be correct
        
        // --------------------------------------------------------------------------
        // Locate single-character EoL sequence.
        // --------------------------------------------------------------------------
        char ch1 = line[len - 1];
        if ((ch1 == 10) || (ch1 == 13)) {
          __eol_sequence[0] = ch1;
          __eol_size++;
        } // -x- if ch1 -x-
        if (len == 1) return; // Total string length is 1 character, so we only needed to check for CR or LF
 
        // --------------------------------------------------------------------------
        // Locate double-character of EoL sequence (ch1 is actually the last/second
        // character, which means that ch0 is the penultimate character, but only if
        // ch0 is CR or LF).
        // --------------------------------------------------------------------------
        char ch0 = line[len - 2];
        if (((ch0 == 10) && (ch1 == 13)) || ((ch0 == 13) && (ch1 == 10))) {
          __eol_sequence[0] = ch0;
          __eol_sequence[1] = ch1;
          __eol_size++;
          if (ch0 == 10) __eol_LFCR = true;
        } // -x- if ch0 -x-
 
        // --------------------------------------------------------------------------
        // Assign line of text, without EoL sequence (if any) to the internal string.
        // --------------------------------------------------------------------------
        __line.assign(line, len - __eol_size);
 
      }; // -x- void __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.  Multiple lines
      embedded in the supplied string will be treated as a single line, and ignored
      therefore.
      @note
      If @c line is a @c nullptr then it will be treated as an empty string without
      any 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 is_null
      *///=========================================================================
      rline(
      /// Line of text to embrace
      char* line,
      /// Length of line (-1 == ASCIIZ string)
      size_t len = -1
      ) noexcept { __rline(line, len); }; // -x- constructor rline -x-
 
      /*======================================================================*//**
      @brief
      Instantiate a new rline based on the supplied line of text.  Multiple lines
      embedded in the supplied string will be treated as a single line, and ignored
      therefore.
      *///=========================================================================
      rline(
      /// Line of text to embrace
      std::string line
      ) noexcept { __rline(line.c_str(), line.length()); }; // -x- constructor rline -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 std::string str) {
        __line.append(str);
        return this;
      }; // -x- rline* append -x-
 
      /*======================================================================*//**
      @brief
      Assign a new line of text, the same way the constructor assigns it.
      @note
      If @c line is a @c nullptr then it will be treated as an empty string without
      any 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 insert
      *///=========================================================================
      rline* assign(
      /// Line of text to embrace
      char* line,
      /// Length of line (-1 == ASCIIZ string)
      size_t len = -1
      ) noexcept {
 
        // --------------------------------------------------------------------------
        // Reset internal variables.
        // --------------------------------------------------------------------------
        __eol_sequence[0] = '\0';
        __eol_sequence[1] = '\0';
        __eol_size = 0;
        __eol_LFCR = false;
 
        // --------------------------------------------------------------------------
        // Replace line of text.
        // --------------------------------------------------------------------------
        __rline(line, len);
 
        return this;
      }; // -x- rline* assign -x-
 
      /*======================================================================*//**
      @brief
      Assign a new line of text, the same way the constructor assigns it.
      @returns The same rline object so as to facilitate stacking
      @see append
      @see insert
      *///=========================================================================
      rline* assign(
      /// Line of text to embrace
      std::string line
      ) noexcept {
 
        // --------------------------------------------------------------------------
        // Reset internal variables.
        // --------------------------------------------------------------------------
        __eol_sequence[0] = '\0';
        __eol_sequence[1] = '\0';
        __eol_size = 0;
        __eol_LFCR = false;
 
        // --------------------------------------------------------------------------
        // Replace line of text.
        // --------------------------------------------------------------------------
        __rline(line.c_str(), line.length());
 
        return this;
      }; // -x- rline* assign -x-
 
      /*======================================================================*//**
      @brief
      Reset all data and internal flags to the original state of the constructor
      that has no parameters.
      @returns The same rline object so as to facilitate stacking
      *///=========================================================================
      rline* clear() noexcept {
 
        // --------------------------------------------------------------------------
        // Reset internal variables.
        // --------------------------------------------------------------------------
        __eol_sequence[0] = '\0';
        __eol_sequence[1] = '\0';
        __eol_size = 0;
        __eol_LFCR = false;
        __line.clear();
 
        return this;
      }; // -x- rline* clear -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@nFALSE = 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.
      @returns The EoL sequence as a string
      @see get
      *///=========================================================================
      const std::string eol() noexcept { return __eol_sequence; }; // -x- std::string eol -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
      *///=========================================================================
      const std::string get(
      /// Whether to include the EoL sequence (default = FALSE)
      const bool include_eol = false
      ) noexcept { return include_eol ? __line + __eol_sequence : __line; }; // -x- std::string get -x-
 
      /*======================================================================*//**
      @brief
      Indicate whether an EoL sequence was detected.
      @returns TRUE = EoL sequence is present@nFALSE = No EoL sequence
      @see empty
      *///=========================================================================
      bool has_eol() noexcept { return __eol_size != 0; }; // -x- bool has_eol -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)
      int position, // Must be "int" and not "size_t" because we size_t is unsigned
      /// The string to insert
      const std::string str) {
        __line.insert(position >= 0 ? position : (__line.size() + position), str);
        return this;
      }; // -x- rline* insert -x-
 
      /*======================================================================*//**
      @brief
      Indicate whether this line is non-existent, which means there is no text and
      no 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@nFALSE = not null (has text and/or an EoL
      sequence)
      @see empty
      *///=========================================================================
      bool is_null() noexcept { return (__line.size() + __eol_size) == 0; }; // -x- bool is_null -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_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
      *///=========================================================================
      size_t size(
      /// Whether to include the EoL sequence (default = FALSE)
      const bool include_eol = false
      ) noexcept { return include_eol ? __line.size() + __eol_size : __line.size(); }; // -x- size_t size -x-
 
      /*======================================================================*//**
      @brief
      Provides the length of the EoL sequence.
      @returns Number of bytes (0 = no EoL string)
      *///=========================================================================
      size_t size_eol() noexcept { return __eol_size; }; // -x- size_t size_eol -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
      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 << (char*)c.__line.c_str(); }; // -x- std::ostream& operator<< -x-
 
  }; // -x- class rline -x-
 
}; // -x- namespace randolf -x-