rring

#pragma once
 
#include <algorithm> // std::min and std::max
#include <cstring>
#include <mutex>
#include <new>
#include <tuple>
#include <vector>
 
#include <randolf/rline>
#include <randolf/rring_bam>
 
namespace randolf {
 
  /*======================================================================*//**
  @brief
  Ring buffer implementation for 8-bit bytes that's threadsafe and resizeable,
  and the methods are designed to be efficient in various ways, including by
  supporting the transfer of multiple bytes in variable quantities.
 
  Data is stored internally as a @c char* array, but a few methods are provided
  to also support easy interoperability with @c std::vector objects since there
  are many scenarios where this can be helpful (and from the perspective of
  optimization, this eliminates the cumbersome need to utilize conversions
  between @c std::string and @c std::vector objects since, internally, we use
  direct access to/from @c std::vector objects where needed).
 
  @par Use case
  Occasionally, ring buffers (a.k.a., circular buffers) are useful in specific
  situations because they provide better performance compared to other types of
  buffers, which either results in frequent allocations and deallocations of
  memory for transient-but-ordered portions of data or tracking sections of
  transient-but-ordered portions of data.  A ring buffer relies on a single
  allocation of memory, along with a few variables for tracking top and bottom
  positions plus a few other internals to ensure smooth and accurate usage.
 
  Expanding and reducing ring buffer memory automatically (which is disabled by
  default) is a feature that's particularly useful for server daemons that
  process small amounts of data most of the time.  For example, an SMTP, IMAP4,
  POP3, MEOW, FTP, HTTP, FINGER, or WHOIS server that is rqeuired to minimize
  per-connection memory requirements can have a line buffer that begins with 80
  characters, and be configured to increase to millions on-demand that will
  automatically shrink back down to the minimal 80 character buffer size, hence
  most of the time the buffer will only utilize 80 characters, with occasional
  longer lines that can be rejected efficiently or handled in some other way by
  the daemon without the complexity of memory management and, most importantly,
  without having to pre-allocate larger amounts of memory "just in case" a few
  connections start sending long lines (such as corrupt data, buffer overflow
  attempts that could be part of fuzzing tests or hacking efforts, etc.).
 
  @par Conventions
  Lower-case letters "rb" are regularly used in partial example code to
  represent an instantiated rring object.
 
  An ASCIIZ string is a C-string (char* array) that includes a terminating null
  (0) character at the end.
 
  @par History
    - 2024-Nov-25 v1.00 Initial version
    - 2024-Dec-03 v1.00 Added @ref rring_bam structure integration
    - 2024-Dec-03 v1.00 Added @ref data_bam and related methods
    - 2024-Dec-23 v1.00 Added @ref defragment and @ref reverse methods
    - 2024-Dec-23 v1.00 Renamed @c peek_ methods to @c peek_to_ and @c remove_
                        methods to @c remove_to, so that the intention of these
                        methods is more easily understood
    - 2024-Dec-23 v1.00 Added internal methods to support ring buffer resizing
    - 2024-Dec-24 v1.00 Added constructor that includes automatic expansion
                        policy parameters
    - 2024-Dec-25 v1.00 Implemented automatic buffer size expansion policies
    - 2024-Dec-27 v1.00 Automatic buffer size expansion, reduction, and block
                        resizing implementations are complete, and tested
    - 2024-Jan-07 v1.00 Added @ref copy_to_rline method
    - 2024-Jan-09 v1.00 Added optional @c len parameter to various constructor,
                        assign, and append methods for greater flexibility
    - 2024-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
  @version 1.00
  @author Randolf Richardson
  *///=========================================================================
  class rring {
    private:
      char*      __buffer;          // Pointer to buffer
      size_t     __size;            // Size of buffer // TODO:  Add a base_size to ease later calculations with xp
      size_t     __head        = 0; // Head (beginning)
      size_t     __tail        = 0; // Tail (end)
      std::mutex __mutex;           // Used to add support for multiple threads
 
      // --------------------------------------------------------------------------
      // Dynamic expansion variables.
      // --------------------------------------------------------------------------
      uint       __xp_block_size;   // Expansion increment/decrement block size (default == __size)
      uint       __xp_max      = 0; // Maximum possible number of expansion blocks
      uint       __xp_play     = 2; // Number of available blocks must be present before attempting reduction
      uint       __xp_used     = 0; // Number of expansion increments used
 
      // --------------------------------------------------------------------------
      // Policy flags.
      // --------------------------------------------------------------------------
      bool       __wipe_policy = true; // Destructor memory wipe-out policy
 
    public:
      /*======================================================================*//**
      @brief
      Instantiate an empty ring buffer (without automatic resizing-expansions).
      @exception std::bad_alloc If @c malloc() fails to allocate memory
      *///=========================================================================
      rring(
      /// Size of buffer
      const size_t buffer_size) {
        __buffer        = (char*)malloc(buffer_size);
        if (__buffer   == nullptr) throw std::bad_alloc(); // Throw exception if __buffer wasn't allocated by malloc
        __size          = buffer_size;
        __xp_block_size = buffer_size;
      }; // -x- constructor rring -x-
 
      /*======================================================================*//**
      @brief
      Instantiate an empty ring buffer (with automatic resizing-expansion policies
      set so the internal buffer will be re-sized to adapt to unexpected allocation
      needs behind-the-scenes automatically).
      @exception std::bad_alloc If @c malloc() fails to allocate memory
      *///=========================================================================
      rring(
      /// Size of buffer
      const size_t buffer_size,
      /// Maximum possible number of expansion blocks@n
      /// 0 = no expansions / effectively disabling expansion (default)
      const uint   xp_max,
      /// Minimum number of available blocks before a reduction can occur
      const uint   xp_play = 2,
      /// Size of expansion blocks @n
      /// 0 = use @c buffer_size (default) @n
      const uint   xp_block_size = 0
      ) {
        __buffer        = (char*)malloc(buffer_size);
        if (__buffer   == nullptr) throw std::bad_alloc(); // Throw exception if __buffer wasn't allocated by malloc
        __size          = buffer_size;
 
        // --------------------------------------------------------------------------
        // Dynamic expansion variables.
        // --------------------------------------------------------------------------
        __xp_max        = xp_max;
        __xp_play       = xp_play;
        __xp_block_size = xp_block_size == 0 ? __size : xp_block_size;
 
      }; // -x- constructor rring -x-
 
      /*======================================================================*//**
      @brief
      Free internal memory resources, after clearing buffer's memory (if the policy
      indicates that it needs to be cleared).
      *///=========================================================================
      ~rring() noexcept {
        if (__buffer != nullptr) {
 
          // --------------------------------------------------------------------------
          // Overwrite buffer's memory with NULL if policy indicates it.
          // --------------------------------------------------------------------------
          if (__wipe_policy) while (__size > 0) __buffer[--__size] = '\0';
 
          // --------------------------------------------------------------------------
          // Free buffer's memory resource.
          // --------------------------------------------------------------------------
          free(__buffer);
 
        } // -x- if __buffer -x-
      }; // -x- destructor ~rring -x-
 
    private:
      // @returns Quantity of entries added (if positive) or removed (if negative)
      //          if ring buffer memory was increased/decreased respectively@n
      //          0 = there was no change in ring buffer memory
      /*======================================================================*//**
      @brief
      Calculate the number of available entries in the ring buffer, and expand or
      contract the size of the buffer memory if needed quantity calls for it.
      @exception std::overflow_error If the quantity of needed entries exceeds the
                                     available free space in the ring buffer
      @returns If `need > 0`, number of entries available, same as __available() @n
               If `need <= 0`, number of entries removed (0 == none removed)
      *///=========================================================================
      uint __adjust_xp(
      /// Number of additional entries to attempt to make available@n
      /// 0 = attempt to reduce ring buffer memory (with no intention to expand it)
      uint need = 0
      ) {
 
        // --------------------------------------------------------------------------
        // Easy checks first.
        // --------------------------------------------------------------------------
        if (__xp_max == 0) return 0; // Expandable memory is effectively disabled, so nothing can change
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        size_t available = (__head < __tail) ? __tail - __head
                                   : __size - (__head - __tail);
 
        // --------------------------------------------------------------------------
        // Reduce memory (as per policies) if there's no need to increase memory.
        // --------------------------------------------------------------------------
        if (need == 0) {
 
          // --------------------------------------------------------------------------
          // Internal variables.
          // --------------------------------------------------------------------------
          uint play = __xp_play == 0 ? __xp_block_size : __xp_play * __xp_block_size;
 
//std::cout << "play=" << play << " available=" << available << " __xp_used=" << __xp_used << " __xp_play=" << __xp_play << std::endl;
          // --------------------------------------------------------------------------
          // If there isn't enough "play," then we don't need to reduce buffer memory.
          //
          // The reason we don't throw an exception is that reducing ring buffer memory
          // here is a passive background function, so it's not actually an error when
          // the conditions for reduction are not satisfied.
          // --------------------------------------------------------------------------
          if (available < play /* && __xp_used < __xp_play */) return 0; // No need to reduce buffer memory (because __xp_play is less than what's available)
          if (available < __xp_used * __xp_block_size) return 0; // No need to reduce buffer memory (because some/all of it is still in use)
 
          // --------------------------------------------------------------------------
          // Allocate less memory and move buffer into it using __defragment (which
          // takes care of re-allocating the new memory).
          //
          // Note:  Utilized memory is calculated using "__size - available" and then
          //        we add "play" to maintain the minimal amount of available memory
          // --------------------------------------------------------------------------
          uint old_size = __size;
          uint r_blocks = std::min((uint)(available / __xp_block_size), __xp_used);
          uint new_size = __size - r_blocks * __xp_block_size;
          __defragment(true, new_size);
          __xp_used -= r_blocks;
 
//std::cout << "old_size=" << old_size << " new_size=" << new_size << std::endl;
          // --------------------------------------------------------------------------
          // Return quantity of entries removed since the original need specified 0.
          // --------------------------------------------------------------------------
          return old_size - new_size;
 
        } // -x- if need -x-
 
        // --------------------------------------------------------------------------
        // If there's already enough memory, then simply return the quantity that's
        // already available.
        // --------------------------------------------------------------------------
        if (need <= available) return available; // Return already-calculated quantity of available entries
 
        // --------------------------------------------------------------------------
        // Calculate number of blocks needed, then check that it's possible to
        // accomodate what's needed or throw an exception if there isn't enough.
        // --------------------------------------------------------------------------
        uint xp_blocks_needed = need / __xp_block_size + (need % __xp_block_size != 0); // Total number of blocks needed, mathematically rounded up
//std::cout << "__size=" << __size << " xp_blocks_needed=" << xp_blocks_needed << " need=" << need << " __xp_max=" << __xp_max << " __xp_used=" << __xp_used << std::endl;
        if (xp_blocks_needed > __xp_max - __xp_used) throw std::overflow_error("Amount of needed data (quantity=" + std::to_string(need) + ") exceeds expansion limits");
 
        // --------------------------------------------------------------------------
        // Allocate new memory and move buffer into it using __defragment (which
        // takes care of re-allocating the new memory).
        // --------------------------------------------------------------------------
        __defragment(true, __size + __xp_block_size * xp_blocks_needed);
 
        // --------------------------------------------------------------------------
        // If __defragment()'s memory allocation was successful, then it means that
        // the resizing was successful, and so now it's okay to update any important
        // variables.
        // --------------------------------------------------------------------------
        __xp_used = xp_blocks_needed; // Not += (as of 2024-Dec-27)
//std::cout << "__size=" << __size << " xp_blocks_needed=" << xp_blocks_needed << " need=" << need << " __xp_max=" << __xp_max << " __xp_used=" << __xp_used << std::endl;
 
        return __available(); // Return re-calculated quantity of available entries because __defragment probably changed them
 
      } // -x- int __adjust_xp -x-
 
      /*======================================================================*//**
      @brief
      Calculate the number of available entries in the ring buffer.
      @returns Number of entries available
      @see get_available
      *///=========================================================================
      size_t __available() noexcept {
        return (__head < __tail) ? __tail - __head
                       : __size - (__head - __tail);
      } // -x- size_t __available -x-
 
      /*======================================================================*//**
      @brief
      Calculate the number of utilized entries in the ring buffer.
      @returns Number of entries utilized
      @see get_utilized
      *///=========================================================================
      size_t __utilized() noexcept {
        return (__head >= __tail) ? __head - __tail
                        : __size - (__tail - __head);
      } // -x- size_t __utilized -x-
 
    public:
      /*======================================================================*//**
      @brief
      Add one character to the unused portion of the internal ring buffer.
      @exception std::overflow_error If the amount of data exceeds the available
                                     free space in the ring buffer
      @returns The same rring object so as to facilitate stacking
      @see peek
      @see remove
      *///=========================================================================
      rring* append(
      /// Data to add
      const char data) {
 
        // --------------------------------------------------------------------------
        // Add data to ring buffer.  If no data is needed, then skip all the mutex
        // locking overhead, etc., and return the empty string.
        // --------------------------------------------------------------------------
        { std::lock_guard<std::mutex> guard(__mutex);
          if (__adjust_xp(1) == 0) throw std::overflow_error("Ring buffer is full");
          if (__head >= __size) __head = 0; // Wrap-around
          __buffer[__head] = data;          // Copy entry
          __head++;                         // Advance to next entry
        } // -x- mutex guard -x-
 
        return this;
      } // -x- rring* append -x-
 
      /*======================================================================*//**
      @brief
      Add any number of characters that fit within the unused portion of the
      internal ring buffer.
      @exception std::invalid_argument If data length is -2 or below
      @exception std::overflow_error If the amount of data exceeds the available
                                     free space in the ring buffer
      @returns The same rring object so as to facilitate stacking
      @see c_str
      @see peek_to_array
      @see remove_to_array
      *///=========================================================================
      rring* append(
      /// Data to add
      const char* data,
      /// Length of data (-1 = treat @c data as an ASCIIZ string)
      int len = -1) {
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
             if (len == -1) len = std::strlen(data);
        else if (len  < -1) throw std::invalid_argument("Unrealistic data length of " + std::to_string(len));
 
        // --------------------------------------------------------------------------
        // Add data to ring buffer.  If no data is needed, then skip all the mutex
        // locking overhead, etc., and return the empty string.
        // --------------------------------------------------------------------------
        if (len > 0) {
          std::lock_guard<std::mutex> guard(__mutex);
          if (__adjust_xp(len) < len) throw std::overflow_error("Amount of data (len=" + std::to_string(len) + ") exceeds available free space in ring buffer");
          for (int i = 0; i < len; i++) {
            if (__head >= __size) __head = 0; // Wrap-around
            __buffer[__head] = data[i];       // Copy entry
            __head++;                         // Advance to next entry
          } // -x- for i -x-
        } // -x- if len -x-
 
        return this;
      } // -x- rring* append -x-
 
      /*======================================================================*//**
      @brief
      Add any number of characters that fit within the unused portion of the
      internal ring buffer.
      @exception std::invalid_argument If data length is -2 or below
      @exception std::length_error If data length is too long
      @exception std::overflow_error If the amount of data exceeds the available
                                     free space in the ring buffer
      @returns The same rring object so as to facilitate stacking
      @see c_str
      @see peek_to_string
      @see remove_to_string
      *///=========================================================================
      rring* append(
      /// Data to add
      const std::string data,
      /// Length of data (-1 = rely on data.length())
      int len = -1) {
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
             if (len == -1           ) len = data.length();
        else if (len  < -1           ) throw std::invalid_argument("Unrealistic data length of " + std::to_string(len));
        else if (len  > data.length()) throw std::length_error("Unrealistic data length of " + std::to_string(len));
 
        // --------------------------------------------------------------------------
        // Add data to ring buffer.  If no data is needed, then skip all the mutex
        // locking overhead, etc., and return the empty string.
        // --------------------------------------------------------------------------
        if (len > 0) {
          std::lock_guard<std::mutex> guard(__mutex);
          if (__adjust_xp(len) < len) throw std::overflow_error("Amount of data (len=" + std::to_string(len) + ") exceeds available free space in ring buffer");
          for (int i = 0; i < len; i++) {
            if (__head >= __size) __head = 0; // Wrap-around
            __buffer[__head] = data[i];       // Copy entry
            __head++;                         // Advance to next entry
          } // -x- for i -x-
        } // -x- if len -x-
 
        return this;
      } // -x- rring* append -x-
 
      /*======================================================================*//**
      @brief
      Add any number of characters that fit within the unused portion of the
      internal ring buffer.
      @exception std::invalid_argument If data length is -2 or below
      @exception std::overflow_error If the amount of data exceeds the available
                                     free space in the ring buffer
      @returns The same rring object so as to facilitate stacking
      @see c_str
      @see peek_to_vector
      @see remove_to_vector
      *///=========================================================================
      rring* append(
      /// Data to add
      const std::vector<char> data,
      /// Length of data (-1 = treat @c data as an ASCIIZ string)
      int len = -1) {
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
             if (len == -1) len = data.size();
        else if (len  < -1) throw std::invalid_argument("Unrealistic data length of " + std::to_string(len));
 
        // --------------------------------------------------------------------------
        // Add data to ring buffer.  If no data is needed, then skip all the mutex
        // locking overhead, etc., and return the empty string.
        // --------------------------------------------------------------------------
        if (len > 0) {
          std::lock_guard<std::mutex> guard(__mutex);
          if (__adjust_xp(len) < len) throw std::overflow_error("Amount of data (len=" + std::to_string(len) + ") exceeds available free space in ring buffer");
          for (int i = 0; i < len; i++) {
            if (__head >= __size) __head = 0; // Wrap-around
            __buffer[__head] = data[i];       // Copy entry
            __head++;                         // Advance to next entry
          } // -x- for i -x-
        } // -x- if len -x-
 
        return this;
      } // -x- rring* append -x-
 
      /*======================================================================*//**
      @brief
      Add any number of characters that fit within the unused portion of the
      internal ring buffer.
      @exception std::invalid_argument If data length is -2 or below
      @exception std::overflow_error If the amount of data exceeds the available
                                     free space in the ring buffer
      @returns The same rring object so as to facilitate stacking
      @see c_str
      @see peek_to_vector
      @see remove_to_vector
      *///=========================================================================
      rring* append(
      /// Data to add
      const std::vector<unsigned char> data,
      /// Length of data (-1 = treat @c data as an ASCIIZ string)
      int len = -1) {
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
             if (len == -1) len = data.size();
        else if (len  < -1) throw std::invalid_argument("Unrealistic data length of " + std::to_string(len));
 
        // --------------------------------------------------------------------------
        // Add data to ring buffer.  If no data is needed, then skip all the mutex
        // locking overhead, etc., and return the empty string.
        // --------------------------------------------------------------------------
        if (len > 0) {
          std::lock_guard<std::mutex> guard(__mutex);
          if (__adjust_xp(len) < len) throw std::overflow_error("Amount of data (len=" + std::to_string(len) + ") exceeds available free space in ring buffer");
          for (int i = 0; i < len; i++) {
            if (__head >= __size) __head = 0; // Wrap-around
            __buffer[__head] = data[i];       // Copy entry
            __head++;                         // Advance to next entry
          } // -x- for i -x-
        } // -x- if len -x-
 
        return this;
      } // -x- rring* append -x-
 
      /*======================================================================*//**
      @brief
      Array-style access to the utilized portion of the ring buffer's contents,
      which yields the same result as that of the @ref at() method.
 
      The first element is at index 0.
      @throws std::out_of_range if the index is out-of-range
      @returns char
      @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)
      int index) {
        std::lock_guard<std::mutex> guard(__mutex);
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        int MAX = __utilized();
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
        if (index >= MAX || 0 - index > MAX) throw std::out_of_range("index (position=" + std::to_string(index) + ") falls outside of the utilized portion (length=" + std::to_string(MAX) + ") of the buffer");
 
        // --------------------------------------------------------------------------
        // Calculate character's position.
        // --------------------------------------------------------------------------
        index = index >= 0 ? __tail + index : __head + index;
        if (index >= __size) index -= __size;
 
        return __buffer[index];
      } // -x- char at -x-
 
      /*======================================================================*//**
      @brief
      Return the contents of the ring buffer as an ASCIIZ string.
      @post
      The string returned will need to be `free()`'d after it's no longer needed.
 
      @code{.cpp}
        #include <iostream>      // std::cout, std::cerr, std::endl, etc.
        #include <randolf/rring>
 
        int main(int argc, char *argv[]) {
          randolf::rring rb(1024);
          rb.append("This is an example.");
          char* c = rb.c_str();
          std::cout << "\"" << c << "\"" << std::endl;
          free(c);
          return EXIT_SUCCESS;
        } // -x- int main -x-
      @endcode
 
      @warning
      When using the @ref data parameter in a multi-threaded scenario, the amount
      of the memory needed should be set to the maximum size of this ring buffer to
      prevent unintended under-allocation resulting from a simultaneous increase
      in utilized ring buffer memory (caused by @ref set_size).
      @exception std::bad_alloc If @c malloc() fails to allocate memory
      @returns ASCIIZ string
      @see append(const char*, int)
      @see append(const std::string, int)
      @see peek_to_array
      @see peek_to_string
      *///=========================================================================
      char* c_str(
      /// Where to store the ASCIIZ string (including terminating zero, so it is
      /// imperative that `utilized() + 1` bytes be pre-allocated)@n
      /// @c nullptr = allocate the needed memory using @c malloc()
      char* data = nullptr) noexcept {
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        size_t len;
 
        // --------------------------------------------------------------------------
        // Generate ASCIIZ string.
        // --------------------------------------------------------------------------
        { std::lock_guard<std::mutex> guard(__mutex);
          len = __utilized();
          if (data == nullptr) {
            data = (char*)malloc(len + 1);
            if (data == nullptr) throw std::bad_alloc(); // Throw exception if data wasn't allocated by malloc
          } // -x- if !data -x-
          size_t t = __tail;
          for (int i = 0; i < len; i++) {
            if (t >= __size) t = 0; // Wrap-around
            data[i] = __buffer[t];  // Copy entry
            t++;                    // Advance to next entry
          } // -x- for i -x-
        } // -x- mutex guard -x-
        data[len] = '\0'; // Not "len - 1" because we already allocated "len + 1"
 
        return data;
      } // -x- char* c_str -x-
 
      /*======================================================================*//**
      @brief
      Copy a line of text into a randolf::rline object.  If an EoL sequence is not
      detected, the data will still fill the randolf::rline object.
      @note
      If providing a pre-existing randolf::rline object, data will be appended to
      any existing data that's already present.
      @throws std::invalid_argument If @c len is less than -1
      @returns Data from ring buffer
      @see append(const std::string, int)
      @see c_str
      @see peek
      @see peek_to_array
      @see peek_to_string
      @see peek_to_vector
      *///=========================================================================
      randolf::rline* copy_to_rline(
      /// Maximum quantity of data to duplicate@n
      /// -1 = all data
      int len = -1,
      /// Pointer to an already-instantiated @ref randolf::rline object to use@n
      /// nullptr = instantiate a new @ref randolf::rline object (this will need to
      ///           be `delete`'d when it's no longer needed)
      randolf::rline* data = nullptr) {
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
        if (len < -1) throw std::invalid_argument("Unrealistic data length of " + std::to_string(len));
        if (data == nullptr) data = new randolf::rline();
 
        // --------------------------------------------------------------------------
        // Duplicate data from ring buffer, quickly (in one or two moves).
        // --------------------------------------------------------------------------
        { std::lock_guard<std::mutex> guard(__mutex);
          switch (len) {
            case -1: // Copy everything
              if (__head >= __tail) { // Not wrapped
                data->append(__buffer + __tail, __utilized());
              } else {
                int n = __size - __tail;
                data->append(__buffer + __tail, std::min(len, n));
                if (n < len) data->append(__buffer, len - n);
              } // -x- if not_wrapped -x-
            case 0: // Copy nothing at all
              break;
            default: // Copy specified quantity
              int utilized = __utilized();
              if (utilized < len) len = utilized; // throw std::overflow_error("Amount of data (len=" + std::to_string(len) + ") exceeds utilized space in ring buffer");
              if (__head >= __tail) { // Not wrapped
                data->append(__buffer + __tail, std::min(len, utilized));
              } else {
                int n = __size - __tail;
                data->append(__buffer + __tail, std::min(len, n));
                if (n < len) data->append(__buffer, len - n);
              } // -x- if not_wrapped -x-
          } // -x- switch len -x-
        } // -x- mutex guard -x-
 
        return data;
      } // -x- randolf::rline* copy_to_rline -x-
 
      /*======================================================================*//**
      @brief
      Returns a pointer to the underlying ring buffer's array.  If the "defragment"
      flag is cleared then the beginning of the array may not be the same as where
      the data actually begins (and ends) within the buffer (see the @c warning
      hereunder).
 
      @warning
      This is the live data, which should not be accessed or modified directly; use
      the @ref data_bam() and @ref data_bam_adjust() methods instead when there is
      a need to access or modify the backing array directly.
      @exception std::bad_alloc If @c malloc() fails to allocate memory (this can
                                only occur when the "defragment" flag is set)
      @returns Pointer to buffer (not null terminated)
      @see data_bam
      @see data_bam_adjust
      @see defragment
      @see get_available
      @see get_utilized
      @see set_size
      @qualifier ADVANCED
      *///=========================================================================
      char* data(
      /// Whether to defragment the data first@n
      /// @c TRUE = fuly defragment so that data begins at position 0 (default) @n
      /// @c FALSE = don't defragment the data (this is an advanced feature that
      ///            will require knowing how to use the @ref data_bam method, and
      ///            also the @ref data_bam method if adding or removing data)
      bool defragment_flag = true) noexcept {
        std::lock_guard<std::mutex> guard(__mutex);
        if (defragment_flag) defragment(true);
        return __buffer;
      } // -x- char* data -x-
 
      /*======================================================================*//**
      @brief
      Returns the lengths and addresses of available memory.  There may be only one
      block of memory, or two, depending on whether the available memory straddles
      the boundary of the ring buffer.
 
      This is the nearest equivalent of the @ref data() methods provided in classes
      such as @c std::string and @c std::vector, but with the nuance of supporting
      the underpinnings of this ring buffer wherein the utilized portions may be
      stored at both the end and beginning of the buffer memory.
      @note
      The intention of this method is to provide an opportunity to directly update
      the contents of the ring buffer's data section in an efficient manner (e.g.,
      such as by reading file or socket data directly into memory without having to
      perform separate data copying operations, etc.).
      @warning
      Upon updating a portion of the available-data block, the @c head will also
      need to be updated accordingly, for which the @ref data_bam_adjust method is
      provided.
      @exception std::bad_alloc If @c malloc() fails to allocate memory
      @returns Pointer to @ref rring_bam structure
      @see data
      @see data_bam_adjust
      @see empty
      @see get_available
      @see get_head
      @see get_tail
      @see get_utilized
      @see rring_bam
      @qualifier ADVANCED
      *///=========================================================================
      rring_bam* data_bam(
      /// Pointer to @ref rring_bam structure (that's already been allocated)@n
      /// @c nullptr (default) = allocate memory for this structure with @c malloc
      /// (which will need to be `free`'d when it's no longer needed)
      rring_bam* bam = nullptr) noexcept {
        std::lock_guard<std::mutex> guard(__mutex);
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        if (bam == nullptr) {
          bam = (rring_bam*)malloc(__size);
          if (bam == nullptr) throw std::bad_alloc(); // Throw exception if bam wasn't allocated by malloc
        } // -x- if !bam -x-
 
        // --------------------------------------------------------------------------
        // Configure utilized data block pointer(s) and length(s).
        // --------------------------------------------------------------------------
        bam->block1        = __buffer + __tail;
        if (__head        >= __tail) { // Not wrapped
          bam->block1_size = __head - __tail;
          bam->block2      = nullptr;
          bam->block2_size = 0;
        } else { // Wrapped
          bam->block1_size = __size - __tail;
          bam->block2      = __size - __tail == 0 ? nullptr : __buffer;
          bam->block2_size = __head;
        } // -x- if __head -x-
 
        // --------------------------------------------------------------------------
        // Configure available data block pointer(s) and length(s).
        // --------------------------------------------------------------------------
        bam->avail1        = __buffer + __head;
        if (__head         < __tail) { // Not wrapped
          bam->avail1_size = __tail - __head;
          bam->avail2      = nullptr;
          bam->avail2_size = 0;
        } else { // Wrapped
          bam->avail1_size = __size - __head;
          bam->avail2      = __tail == 0 ? nullptr : __buffer;
          bam->avail2_size = __tail;
        } // -x- if __head -x-
 
        return bam;
      } // -x- rring_bam* data_bam -x-
 
      /*======================================================================*//**
      @brief
      Arbitrarily change the head and tail positions in the ring buffer.  This is
      intended for use in conjunction with appending data directly to the ring
      buffer after the @ref data_bam method.
      @exception std::overflow_error If either adjustment would result in causing
                                     an overflow
      @returns The same rring object so as to facilitate stacking
      @see data
      @see data_bam
      @see set_head
      @see set_tail
      @qualifier ADVANCED
      *///=========================================================================
      rring* data_bam_adjust(
      /// New internal head position
      size_t head,
      /// New internal tail position
      size_t tail = 0) {
 
        // --------------------------------------------------------------------------
        // Set new head and tail positions.
        // --------------------------------------------------------------------------
        { std::lock_guard<std::mutex> guard(__mutex);
          __head = head;
          __tail = tail;
        } // -x- mutex guard -x-
 
        return this;
      } // -x- rring* data_bam_adjust -x-
 
    private:
      /*======================================================================*//**
      @brief
      Internal method used primarily by the defragment() and resize() methods.
 
      A full defragmentation always results in the tail changing to position 0.
      
      TO DO:  Return to code in _archive/2024-Dec-22/ which is nearly finished, and
              attempt to get the algorithm working for the last few bytes so that
              the memory allocation approach we use now won't be needed (and also
              therefore eliminates the wipe_policy implementation step).
      @exception std::length_error If the new @c buffer_size is less than the total
                                   quantity of utilized entries (which would result
                                   in the truncation of data)
      @exception std::bad_alloc If @c malloc() fails to allocate memory
      @see defragment
      @see set_size
      *///=========================================================================
      void __defragment(
      /// Whether to defrag when the utilized block isn't straddling the internal
      /// memory buffer boundary@n
      /// TRUE = always fully defragment (default) @n
      /// FALSE = only defragment if utilized block straddles memory boundary
      const bool full,
      /// Total size of new memory buffer to be allocated (used in resizing so that
      /// we only allocate the new buffer once {here} rather than twice {here, and
      /// in any of the methods that @ref resize the internal buffer})
      const size_t buffer_size) {
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        const size_t utilized = __utilized();
 
        // --------------------------------------------------------------------------
        // Perform quick checks if size isn't increasing.
        // --------------------------------------------------------------------------
        if (buffer_size == __size) {
 
          // --------------------------------------------------------------------------
          // Already fully optimized, so don't even start.
          // --------------------------------------------------------------------------
          if (__tail == 0) return;
 
          // --------------------------------------------------------------------------
          // If not wrapped around ring buffer (and not resizing), optimization is a
          // fast-and-easy matter of shifting all the elements without re-allocating
          // the ring buffer memory.
          // --------------------------------------------------------------------------
          if (__tail <= __head) {
            if (!full) return; // No work to be done
            for (size_t i = 0; i < utilized; i++) // Move data
              __buffer[i] = __buffer[__tail++];
            __head = utilized;
            __tail = 0;
            return;
          } // -x- if __tail -x-
 
        // --------------------------------------------------------------------------
        // Size reduction sanity check.
        // --------------------------------------------------------------------------
        } else if (buffer_size < utilized) {
 
          // --------------------------------------------------------------------------
          // Prevent truncation by throwing a length_error exception.
          // --------------------------------------------------------------------------
          throw std::length_error("Unrealistic buffer size reduction to " + std::to_string(buffer_size));
 
        } // -x- if buffer_size -x-
 
        // --------------------------------------------------------------------------
        // Allocate new internal buffer.
        // --------------------------------------------------------------------------
        void* data = (char*)malloc(buffer_size);     // Allocate new buffer to the same as as the current one
        if (data == nullptr) throw std::bad_alloc(); // Throw exception if data wasn't allocated by malloc
 
        // --------------------------------------------------------------------------
        // Copy data to new buffer that is the same size as the current one.
        // --------------------------------------------------------------------------
        for (int i = 0; i < utilized; i++) {
          if (__tail >= __size) __tail = 0;    // Wrap-around
          ((char*)data)[i] = __buffer[__tail]; // Copy entry
          __tail++;                            // Advance to next entry
        } // -x- for i -x-
 
        // --------------------------------------------------------------------------
        // De-allocate old internal buffer, and wipe old data before de-allocation if
        // the policy warrants it.
        // --------------------------------------------------------------------------
        if (__wipe_policy)
          for (int i = 0; i < __size; i++)
            __buffer[i] = 0;
        free(__buffer);
 
        // --------------------------------------------------------------------------
        // Set new buffer pointer and internal variables.
        // --------------------------------------------------------------------------
        __buffer = (char*)data; // Update pointer to internal buffer
        __head = utilized;
        __tail = 0;
        __size = buffer_size;
 
        return;
      } // -x- void __defragment -x-
 
    public:
      /*======================================================================*//**
      @brief
      Reorganizes the utilized memory in the ring buffer memory by moving the tail
      to the beginning.  Defragmentation is completed in the most efficient manner,
      depending on what needs to be done.  If data wraps around the buffer memory,
      then new memory will be allocated and data will be moved to it (old memory
      will also be cleared if the wipe policy is in effect).
 
      A full defragmentation always results in the tail changing to position 0.
      @exception std::length_error If the new @c buffer_size is less than the total
                                   quantity of utilized entries (which would result
                                   in the truncation of data)
      @exception std::bad_alloc If @c malloc() fails to allocate memory
      @returns The same rring object so as to facilitate stacking
      @see data
      @see data_bam
      @see get_ascii_map
      @see get_wipe_policy
      @see set_size
      *///=========================================================================
      rring* defragment(
      /// Whether to defrag when the utilized block isn't straddling the internal
      /// memory buffer boundary@n
      /// TRUE = always fully defragment (default) @n
      /// FALSE = only defragment if utilized block straddles memory boundary (this
      ///         favours reducing processor overhead if all that's wanted is to
      ///         have one block of memory to contend with in the BAM, hence it's
      ///         also what the @ref set_size() method uses for better performance
      ///         overall because resizing most likely occurs when the need for CPU
      ///         cycles are more critical, so we're doing our part by reducing our
      ///         CPU load)
      const bool full = true) {
        { std::lock_guard<std::mutex> guard(__mutex);
          __defragment(full, __size);
        } // -x- mutex guard -x-
        return this;
      } // -x- rring* defragment -x-
 
      /*======================================================================*//**
      @brief
      Discard data from the ring buffer.
      @throws std::invalid_argument If @c len is less than -1
      @returns Number of entries that were discarded
      @see remove
      *///=========================================================================
      size_t discard(
      /// Number of bytes to discard@n
      /// -1 = all utilized data that remains will be discarded (default)
      int len = -1) noexcept {
        if (len == 0) return 0; // Do nothing
        size_t discarded;
        { std::lock_guard<std::mutex> guard(__mutex);
               if (len == -1) len = __size;
          else if (len  < -1) throw std::invalid_argument("Unrealistic data length of " + std::to_string(len));
          discarded = __utilized();
 
          // --------------------------------------------------------------------------
          // Discard everything because len is greater than or equal to the amount of
          // data in the ring buffer.
          // --------------------------------------------------------------------------
          if (len >= discarded) { // Discard everything if len is too large
            __head = 0;
            __tail = 0;
            __adjust_xp(); // Ring buffer memory allocation maintenance
            return len; // Return quantity that was actually discarded
          } // -x- if len -x-
 
          // --------------------------------------------------------------------------
          // Adjust __tail according to amount of data to discard.  Calculating this is
          // enormously faster than looping through the buffer.
          // --------------------------------------------------------------------------
          if (__head >= __tail || __size - __tail < len) { // Not wrapping, so adjustment is easy
            __tail += len;
          } else { // Wrapping, so change tail to discard size minus what's discarded from the end
            __tail = len - (__size - __tail);
          } // -x- if __head -x-
 
          // --------------------------------------------------------------------------
          // Ring buffer memory allocation maintenance.
          // --------------------------------------------------------------------------
          __adjust_xp();
 
        } // -x- mutex guard -x-
 
        return discarded - len; // Return quantity that was actually discarded
      } // -x- int discard -x-
 
      /*======================================================================*//**
      @brief
      Indicates whether the ring buffer is empty.
      @returns TRUE = empty@n
               FALSE = not empty
      @see data_bam
      @see get_available
      @see get_utilized
      @see get_size
      *///=========================================================================
      bool empty() noexcept {
        std::lock_guard<std::mutex> guard(__mutex);
        return __head == __tail;
      } // -x- bool empty -x-
 
      /*======================================================================*//**
      @brief
      Obtains a one-line ASCII art depiction of a map of the ring buffer's memory
      usage, wherein the utilized and available portions are represented by the `|`
      (pipe) and `.` (period) characters, respectively.  These characters are
      configurable and may each contain more than one character, which is
      particularly useful for text-mode console output in a typical Linux shell in
      which @c ANSI or @c AVATAR codes may be used to present these characters or
      sequences in different colours, although there may be other uses for this
      too.
      @exception std::invalid_argument If length is -2 or below
      @returns One-line ASCII depiction of ring buffer's memory map
      @see get_available
      @see get_head
      @see get_tail
      @see get_utilized
      *///=========================================================================
      std::string get_ascii_map(
      /// Desired size of ASCII map@n
      /// -1 = Use size of entire ring buffer
      int len = 65,
      /// Character(s) representing utilized entries
      const std::string u = "|",
      /// Character(s) representing available entries
      const std::string a = ".") noexcept {
 
        // --------------------------------------------------------------------------
        // Internal variables, which will be copied .
        // --------------------------------------------------------------------------
        double head;
        double tail;
        double size;
        { std::lock_guard<std::mutex> guard(__mutex);
          head = __head;
          tail = __tail;
          size = __size;
        } // -x- mutex guard -x-
        std::string map;
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
        if (len == -1) len = size;
        if (len ==  0) return map;
        if (len <= -1) throw std::invalid_argument("Unrealistic data length of " + std::to_string(len));
 
        // --------------------------------------------------------------------------
        // Generate output.
        // --------------------------------------------------------------------------
        if (len >= size) {
          head = head * (len / size);
          tail = tail * (len / size);
        } else {        
          head = head / (size / len);
          tail = tail / (size / len);
        } // -x- if len -x-
        map.reserve(len); // Pre-allocate the exact amount of underlying memory needed
        if (head >= tail) for (int i = 0; i < len; i++) map.append(i < tail || i >= head ? a : u); // "a" or "u" could be longer than one character
        else              for (int i = 0; i < len; i++) map.append(i < head || i >= tail ? u : a); // "a" or "u" could be longer than one character
 
        return map;
      } // -x- std::string get_ascii_map -x-
 
      /*======================================================================*//**
      @brief
      Calculate the number of available entries in the ring buffer.
      @returns Number of entries available
      @see data_bam
      @see get_utilized
      @see get_xp_blocks_available
      *///=========================================================================
      size_t get_available() noexcept {
        std::lock_guard<std::mutex> guard(__mutex);
        return __available();
      } // -x- size_t get_available -x-
 
      /*======================================================================*//**
      @brief
      Obtains the base size of the ring buffer, regardless of how much is utilized
      or available, and without any of the expansion policy limits.
      @returns Maximum potential size of ring buffer
      @see empty
      @see get_available
      @see get_max_size
      @see get_size
      @see get_utilized
      @see set_size
      @qualifier ADVANCED
      *///=========================================================================
      size_t get_base_size() noexcept {
        std::lock_guard<std::mutex> guard(__mutex);
        return __size - (__xp_used * __xp_block_size);
      } // -x- size_t get_base_size -x-
 
      /*======================================================================*//**
      @brief
      Obtains the position of the head in the ring buffer.
      @returns Position of head in ring buffer
      @see data_bam
      @see get_available
      @see get_tail
      @see get_utilized
      @see set_head
      @see set_tail
      @qualifier ADVANCED
      *///=========================================================================
      size_t get_head() noexcept {
        std::lock_guard<std::mutex> guard(__mutex);
        return __head;
      } // -x- size_t get_head -x-
 
      /*======================================================================*//**
      @brief
      Obtains the potential total size of the ring buffer, including both its
      utilized and available portions, including the maximum limit of what the
      expansion policies can extend the internal ring buffer's size to.
      @returns Maximum potential size of ring buffer
      @see empty
      @see get_available
      @see get_base_size
      @see get_max_size
      @see get_size
      @see get_utilized
      @see set_size
      @qualifier ADVANCED
      *///=========================================================================
      size_t get_max_size() noexcept {
        std::lock_guard<std::mutex> guard(__mutex);
        return __size + ((__xp_max - __xp_used) * __xp_block_size);
      } // -x- size_t get_max_size -x-
 
      /*======================================================================*//**
      @brief
      Obtains the total size of the current ring buffer, including both its
      utilized and available portions.
      @returns Total current size of ring buffer
      @see empty
      @see get_available
      @see get_base_size
      @see get_max_size
      @see get_utilized
      @see set_size
      @qualifier ADVANCED
      *///=========================================================================
      size_t get_size() noexcept {
        std::lock_guard<std::mutex> guard(__mutex);
        return __size;
      } // -x- size_t get_size -x-
 
      /*======================================================================*//**
      @brief
      Obtains the position of the tail in the ring buffer.
      @returns Position of tail in ring buffer
      @see data_bam
      @see get_available
      @see get_head
      @see get_utilized
      @see set_head
      @see set_tail
      @qualifier ADVANCED
      *///=========================================================================
      size_t get_tail() noexcept {
        std::lock_guard<std::mutex> guard(__mutex);
        return __tail;
      } // -x- size_t get_tail -x-
 
      /*======================================================================*//**
      @brief
      Calculate the number of utilized entries in the ring buffer.
      @returns Number of entries utilized
      @see data_bam
      @see get_available
      @see get_xp_blocks_utilized
      *///=========================================================================
      size_t get_utilized() noexcept {
        std::lock_guard<std::mutex> guard(__mutex);
        return __utilized();
      } // -x- size_t get_utilized -x-
 
      /*======================================================================*//**
      @brief
      Indicate whether internal buffer's memory will be cleared by the destructor
      before de-allocating it (default is @c true upon instantiation).
 
      @note
      This is an important security feature for when the ring buffer may have been
      storing private data because it prevents the leaking of private data to other
      process that coincidentally gain access to the same memory area (e.g., by way
      of future calls to `malloc()`).
      @returns Post-wipe policy (TRUE = clear / FALSE = don't clear)
      @see set_wipe_policy
      @qualifier ADVANCED
      *///=========================================================================
      bool get_wipe_policy() noexcept {
        std::lock_guard<std::mutex> guard(__mutex);
        return __wipe_policy;
      } // -x- bool get_wipe_policy -x-
 
      /*======================================================================*//**
      @brief
      Obtain block size in expansion policy.
      @returns Expansion policy's block size
      @see get_xp_max
      @see get_xp_play
      @see set_xp_block_size
      @qualifier ADVANCED
      *///=========================================================================
      size_t get_xp_block_size() noexcept {
        std::lock_guard<std::mutex> guard(__mutex);
        return __xp_block_size;
      } // -x- size_t get_xp_block_size -x-
 
      /*======================================================================*//**
      @brief
      Obtain quantity of blocks available for use in buffer ring memory expansions.
      @returns Quantity of expansion blocks available
      @see get_available
      @see get_xp_block_size
      @see get_xp_blocks_utilized
      @see get_xp_max
      @see get_xp_play
      @qualifier ADVANCED
      *///=========================================================================
      size_t get_xp_blocks_available() noexcept {
        std::lock_guard<std::mutex> guard(__mutex);
        return __xp_max - __xp_used;
      } // -x- size_t get_xp_blocks_available -x-
 
      /*======================================================================*//**
      @brief
      Obtain quantity of blocks utilized utilized for buffer ring memory expansion.
      @returns Quantity of expansion blocks utilized
      @see get_utilized
      @see get_xp_block_size
      @see get_xp_blocks_available
      @see get_xp_max
      @see get_xp_play
      @qualifier ADVANCED
      *///=========================================================================
      size_t get_xp_blocks_utilized() noexcept {
        std::lock_guard<std::mutex> guard(__mutex);
        return __xp_used;
      } // -x- size_t get_xp_blocks_utilized -x-
 
      /*======================================================================*//**
      @brief
      Obtain maximum block quantity in expansion policy.
      @returns Expansion policy's maximum block quantity
      @see get_xp_block_size
      @see get_xp_blocks_available
      @see get_xp_blocks_utilized
      @see get_xp_play
      @see set_xp_max
      @qualifier ADVANCED
      *///=========================================================================
      size_t get_xp_max() noexcept {
        std::lock_guard<std::mutex> guard(__mutex);
        return __xp_max;
      } // -x- size_t get_xp_max -x-
 
      /*======================================================================*//**
      @brief
      Obtain minimum quantity of blocks available before automatic expansion block
      reduction policy.
      @returns Expansion policy's play setting
      @see get_xp_block_size
      @see get_xp_blocks_available
      @see get_xp_blocks_utilized
      @see get_xp_max
      @see set_xp_play
      @qualifier ADVANCED
      *///=========================================================================
      size_t get_xp_play() noexcept {
        std::lock_guard<std::mutex> guard(__mutex);
        return __xp_play;
      } // -x- size_t get_xp_play -x-
 
      /*======================================================================*//**
      @brief
      Duplicate a single character from the utilized portion of the internal ring
      buffer, and return it as an @c char primitive.
      @exception std::overflow_error If the amount of data exceeds the amount of
                                     data in the ring buffer
      @returns Data from ring buffer
      @see append(const char)
      @see c_str
      @see peek_to_array
      @see peek_to_string
      @see peek_to_vector
      @see remove
      *///=========================================================================
      char peek() {
        std::lock_guard<std::mutex> guard(__mutex);
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
        if (__utilized() == 0) throw std::overflow_error("Ring buffer is empty");
 
        // --------------------------------------------------------------------------
        // Duplicate the last byte of data from the ring buffer.
        // --------------------------------------------------------------------------
        return __buffer[__tail]; // Copy entry
 
      } // -x- char peek -x-
 
      /*======================================================================*//**
      @brief
      Duplicate the specified number of characters from the utilized portion of the
      internal ring buffer, and return them as a @c char* array.
      @post
      The string returned will need to be `free()`'d after it's no longer needed.
      @exception std::bad_alloc If @c malloc() fails to allocate memory
      @exception std::overflow_error If the amount of data exceeds the amount of
                                     data in the ring buffer
      @returns Data from ring buffer
      @see append(const char*, int)
      @see c_str
      @see peek
      @see peek_to_string
      @see peek_to_vector
      @see remove_to_array
      *///=========================================================================
      char* peek_to_array(
      /// Amount of data to duplicate
      size_t len,
      /// Where to store the data@n
      /// @c nullptr = allocate the needed memory using @c malloc()
      char* data = nullptr) {
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        if (data == nullptr) {
          data = (char*)malloc(len);
          if (data == nullptr) throw std::bad_alloc(); // Throw exception if data wasn't allocated by malloc
        } // -x- if !data -x-
 
        // --------------------------------------------------------------------------
        // Remove data from ring buffer.
        // --------------------------------------------------------------------------
        { std::lock_guard<std::mutex> guard(__mutex);
          size_t t = __tail;
          for (int i = 0; i < len; i++) {
            if (t >= __size) t = 0; // Wrap-around
            data[i] = __buffer[t];  // Copy entry
            t++;                    // Advance to next entry
          } // -x- for i -x-
        } // -x- mutex guard -x-
 
        return data;
      } // -x- char* peek_to_array -x-
 
      /*======================================================================*//**
      @brief
      Duplicate the specified number of characters from the utilized portion of the
      internal ring buffer, and return it as an @c std::string object.
      @exception std::invalid_argument If data length is -2 or below
      @exception std::overflow_error If the amount of data exceeds the amount of
                                     data in the ring buffer
      @returns Data from ring buffer
      @see append(const std::string, int)
      @see c_str
      @see peek
      @see peek_to_array
      @see peek_to_vector
      @see remove_to_string
      *///=========================================================================
      std::string peek_to_string(
      /// Amount of data to duplicate@n
      /// -1 = all data
      int len = -1,
      /// The previously instantiated std::string object to use (the default is to
      /// instantiate a new instance of std::string).
      std::string data = std::string()) {
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
        if (len < -1) throw std::invalid_argument("Unrealistic data length of " + std::to_string(len));
 
        // --------------------------------------------------------------------------
        // Duplicate data from ring buffer.  If no data is needed, then skip all the
        // mutex locking overhead, etc., and return the empty string.
        // --------------------------------------------------------------------------
        if (len != 0) {
          std::lock_guard<std::mutex> guard(__mutex);
          if (len == -1) len = __utilized();
          if (__utilized() < len) throw std::overflow_error("Amount of data (len=" + std::to_string(len) + ") exceeds utilized space in ring buffer");
          data.resize(len); // Pre-allocate needed memory
          size_t t = __tail;
          for (int i = 0; i < len; i++) {
            if (t >= __size) t = 0; // Wrap-around
            data[i] = __buffer[t];  // Copy entry
            t++;                    // Advance to next entry
          } // -x- for i -x-
        } // -x- if len -x-
 
        return data;
      } // -x- std::string peek_to_string -x-
 
      /*======================================================================*//**
      @brief
      Duplicate the specified number of characters from the utilized portion of the
      internal ring buffer, and return it as an @c std::string object.
      @exception std::invalid_argument If data length is -2 or below
      @exception std::overflow_error If the amount of data exceeds the amount of
                                     data in the ring buffer
      @returns Data from ring buffer
      @see append(const std::vector<char>, int)
      @see append(const std::vector<unsigned char>, int)
      @see c_str
      @see peek
      @see peek_to_array
      @see peek_to_string
      @see remove_to_vector
      *///=========================================================================
      std::vector<char> peek_to_vector(
      /// Amount of data to duplicate@n
      /// -1 = all data
      int len = -1,
      /// The previously instantiated std::string object to use (the default is to
      /// instantiate a new instance of std::string).
      std::vector<char> data = std::vector<char>()) {
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
        if (len < -1) throw std::invalid_argument("Unrealistic data length of " + std::to_string(len));
 
        // --------------------------------------------------------------------------
        // Duplicate data from ring buffer.  If no data is needed, then skip all the
        // mutex locking overhead, etc., and return the empty string.
        // --------------------------------------------------------------------------
        if (len != 0) {
          std::lock_guard<std::mutex> guard(__mutex);
          if (len == -1) len = __utilized();
          if (__utilized() < len) throw std::overflow_error("Amount of data (len=" + std::to_string(len) + ") exceeds utilized space in ring buffer");
          data.resize(len); // Pre-allocate needed memory
          size_t t = __tail;
          for (int i = 0; i < len; i++) {
            if (t >= __size) t = 0; // Wrap-around
            data[i] = __buffer[t];  // Copy entry
            t++;                    // Advance to next entry
          } // -x- for i -x-
        } // -x- if len -x-
 
        return data;
      } // -x- std::vector<char> peek_to_vector -x-
 
      /*======================================================================*//**
      @brief
      Remove one character from the utilized portion of the internal ring buffer,
      and return it .
      @exception std::overflow_error If the amount of data exceeds the amount of
                                     data in the ring buffer
      @returns Data from ring buffer
      @see append(const char)
      @see c_str
      @see peek
      @see remove_to_array
      @see remove_to_string
      @see remove_to_vector
      *///=========================================================================
      char remove() {
 
        // --------------------------------------------------------------------------
        // Remove data from ring buffer.  If no data is needed, then skip all the
        // mutex locking overhead, etc., and return the empty string.
        // --------------------------------------------------------------------------
        char ch;
        { std::lock_guard<std::mutex> guard(__mutex);
          if (__utilized() == 0) throw std::overflow_error("Ring buffer is empty");
          if (__tail >= __size) __tail = 0; // Wrap-around
          ch = __buffer[__tail];            // Copy entry
          __tail++;                         // Advance to next entry
        } // -x- mutex guard -x-
 
        // --------------------------------------------------------------------------
        // Ring buffer memory allocation maintenance.
        // --------------------------------------------------------------------------
        __adjust_xp();
 
        return ch;
      } // -x- char remove -x-
 
      /*======================================================================*//**
      @brief
      Remove the specified number of characters from the utilized portion of the
      internal ring buffer, and return them as a @c char* array.
      @post
      The string returned will need to be `free()`'d after it's no longer needed.
      @exception std::bad_alloc If @c malloc() fails to allocate memory
      @exception std::overflow_error If the amount of data exceeds the amount of
                                     data in the ring buffer
      @returns Data from ring buffer
      @see append(const char*, int)
      @see c_str
      @see peek_to_array
      @see remove
      @see remove_to_string
      @see remove_to_vector
      *///=========================================================================
      char* remove_to_array(
      /// Maximum quantity of data to move@n
      size_t len,
      /// Where to store the data@n
      /// @c nullptr = allocate the needed memory using @c malloc()
      char* data = nullptr) {
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        if (data == nullptr) {
          data = (char*)malloc(len);
          if (data == nullptr) throw std::bad_alloc(); // Throw exception if data wasn't allocated by malloc
        } // -x- if !data -x-
 
        // --------------------------------------------------------------------------
        // Remove data from ring buffer.  If no data is needed, then skip all the
        // mutex locking overhead, etc., and return the empty string.
        // --------------------------------------------------------------------------
        { std::lock_guard<std::mutex> guard(__mutex);
          for (int i = 0; i < len; i++) {
            if (__tail >= __size) __tail = 0; // Wrap-around
            data[i] = __buffer[__tail];       // Copy entry
            __tail++;                         // Advance to next entry
          } // -x- for i -x-
        } // -x- mutex guard -x-
 
        // --------------------------------------------------------------------------
        // Ring buffer memory allocation maintenance.
        // --------------------------------------------------------------------------
        __adjust_xp();
 
        return data;
      } // -x- char* remove_to_array -x-
 
      /*======================================================================*//**
      @brief
      Remove the specified number of characters from the utilized portion of the
      internal ring buffer, and return it as an @c std::string object.
      @exception std::invalid_argument If data length is -2 or below
      @exception std::overflow_error If the amount of data exceeds the amount of
                                     data in the ring buffer
      @returns Data from ring buffer
      @see append(const std::string, int)
      @see c_str
      @see peek_to_string
      @see remove
      @see remove_to_array
      @see remove_to_vector
      *///=========================================================================
      std::string remove_to_string(
      /// Amount of data to remove@n
      /// -1 = all data
      int len = -1,
      /// The previously instantiated std::string object to use (the default is to
      /// instantiate a new instance of std::string).
      std::string data = std::string()) {
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
        if (len < -1) throw std::invalid_argument("Unrealistic data length of " + std::to_string(len));
 
        // --------------------------------------------------------------------------
        // Remove data from ring buffer.  If no data is needed, then skip all the
        // mutex locking overhead, etc., and return the empty string.
        // --------------------------------------------------------------------------
        if (len > 0) {
          std::lock_guard<std::mutex> guard(__mutex);
          if (len == -1) len = __utilized();
          if (__utilized() < len) throw std::overflow_error("Amount of data (len=" + std::to_string(len) + ") exceeds utilized space in ring buffer");
          data.resize(len); // Pre-allocate needed memory
          for (int i = 0; i < len; i++) {
            if (__tail >= __size) __tail = 0; // Wrap-around
            data[i] = __buffer[__tail];       // Copy entry
            __tail++;                         // Advance to next entry
          } // -x- for i -x-
        } // -x- if len -x-
 
        // --------------------------------------------------------------------------
        // Ring buffer memory allocation maintenance.
        // --------------------------------------------------------------------------
        __adjust_xp();
 
        return data;
      } // -x- std::string remove_to_string -x-
 
      /*======================================================================*//**
      @brief
      Remove the specified number of characters from the utilized portion of the
      internal ring buffer, and return it as an @c std::string object.
      @exception std::invalid_argument If data length is -2 or below
      @exception std::overflow_error If the amount of data exceeds the amount of
                                     data in the ring buffer
      @returns Data from ring buffer
      @see append(const std::vector<char>, int)
      @see append(const std::vector<unsigned char>, int)
      @see c_str
      @see peek_to_vector
      @see remove
      @see remove_to_array
      @see remove_to_string
      *///=========================================================================
      std::vector<char> remove_to_vector(
      /// Amount of data to remove@n
      /// -1 = all data
      int len = -1,
      /// The previously instantiated std::string object to use (the default is to
      /// instantiate a new instance of std::string).
      std::vector<char> data = std::vector<char>()) {
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
        if (len < -1) throw std::invalid_argument("Unrealistic data length of " + std::to_string(len));
 
        // --------------------------------------------------------------------------
        // Remove data from ring buffer.  If no data is needed, then skip all the
        // mutex locking overhead, etc., and return the empty string.
        // --------------------------------------------------------------------------
        if (len > 0) {
          std::lock_guard<std::mutex> guard(__mutex);
          if (len == -1) len = __utilized();
          if (__utilized() < len) throw std::overflow_error("Amount of data (len=" + std::to_string(len) + ") exceeds utilized space in ring buffer");
          data.resize(len); // Pre-allocate needed memory
          for (int i = 0; i < len; i++) {
            if (__tail >= __size) __tail = 0; // Wrap-around
            data[i] = __buffer[__tail];       // Copy entry
            __tail++;                         // Advance to next entry
          } // -x- for i -x-
        } // -x- if len -x-
 
        // --------------------------------------------------------------------------
        // Ring buffer memory allocation maintenance.
        // --------------------------------------------------------------------------
        __adjust_xp();
 
        return data;
      } // -x- std::vector<char> remove_to_vector -x-
 
      /*======================================================================*//**
      @brief
      Flip the order of all entries in the ring buffer.
      @returns The same rring object so as to facilitate stacking
      *///=========================================================================
      rring* reverse() {
        char carry;
        { std::lock_guard<std::mutex> guard(__mutex);
          int h = __head;
          int t = __tail;
          for (int i = __utilized() / 2; i > 0; i--) {
            if (--h < 0) h = __size - 1; // Wrap-around
            if (t >= __size) t = 0;      // Wrap-around
                  carry = __buffer[h];
            __buffer[h] = __buffer[t];
            __buffer[t] = carry;
            t++;                         // Advance to next entry
          } // -x- for i -x-
        } // -x- mutex guard -x-
        return this;
      } // -x- rring* reverse -x-
 
      /*======================================================================*//**
      @brief
      Alter the position of the internal head position, without changing any of the
      the pre-existing data in the underlying ring buffer.
      @exception std::overflow_error If the new position falls beyond the internal
                                     tail position (or, in other words, it exceeds
                                     the available free space in the ring buffer)
      @returns The same rring object so as to facilitate stacking
      @see get_available
      @see get_head
      @see get_tail
      @see get_utilized
      @see set_tail
      @qualifier ADVANCED
      *///=========================================================================
      rring* set_head(
      /// Position adjustment (may also be negative, but only for relative @c type)
      int offset,
      /// Type of adjustment@n
      /// TRUE = absolute (default)@n
      /// FALSE = relative (@c offset may also be negative)
      bool type = true) {
 
        // --------------------------------------------------------------------------
        // Absolute position.
        // --------------------------------------------------------------------------
        if (type) {
          if (offset <             0) throw std::overflow_error("Head position adjustment of " + std::to_string(offset) + " cannot be negative");
          std::lock_guard<std::mutex> guard(__mutex);
          if (offset > __available()) throw std::overflow_error("Head position adjustment of " + std::to_string(offset) + " exceeds available space in ring buffer");
          __head = (__head + offset) % __size;
 
        // --------------------------------------------------------------------------
        // Relative position.
        // --------------------------------------------------------------------------
        } else {
          if (offset > 0) { // Positive adjustment
            std::lock_guard<std::mutex> guard(__mutex);
            if (    offset > __available()) throw std::overflow_error("Head position adjustment of " + std::to_string(offset) + " exceeds available space in ring buffer");
            __head = (__head + offset) % __size;
          } else if (offset < 0) { // Negative adjustment
            std::lock_guard<std::mutex> guard(__mutex);
            if (0 - offset > __utilized() ) throw std::overflow_error("Head position adjustment of " + std::to_string(offset) + " exceeds utilized space in ring buffer");
            __head += offset;
            if (__head >= __size) __head += __size;
          } // -x- if offset -x-
        } // -x- if type -x-
 
        return this;
      } // -x- rring* set_head -x-
 
      /*======================================================================*//**
      @brief
      Configure the total size of the ring buffer.  The new size cannot be smaller
      than the amount of data that's already present in the ring buffer (see the
      @ref get_utilized method to find out how much data is present).
      @exception std::overflow_error If the new size exceeds the amount of data
                                     that's already present in the ring buffer
      @returns The same rring object so as to facilitate stacking
      @see get_available
      @see get_size
      @see get_utilized
      *///=========================================================================
      rring* set_size(
      /// New size of ring buffer
      const size_t len) {
        { std::lock_guard<std::mutex> guard(__mutex);
          if (__utilized() < len) throw std::overflow_error("New size of ring buffer (len=" + std::to_string(len) + ") exceeds utilized amount");
          // TODO:  Change (increase or decrease) total size of ring buffer, if possible,
          //        which will entail moving data around if it wraps, and also throwing
          //        an exception if the reduction is less than the utilized portion.
          __size = len;
        } // -x- mutex guard -x-
 
        return this;
      } // -x- rring* set_size -x-
 
      /*======================================================================*//**
      @brief
      Alter the position of the internal tail position, without changing any of the
      the pre-existing data in the underlying ring buffer.
      @exception std::overflow_error If the new position falls beyond the internal
                                     head position (or, in other words, it exceeds
                                     the available free space in the ring buffer)
      @returns The same rring object so as to facilitate stacking
      @see get_available
      @see get_head
      @see get_tail
      @see get_utilized
      @see set_head
      @qualifier ADVANCED
      *///=========================================================================
      rring* set_tail(
      /// Position adjustment (may also be negative, but only for relative @c type)
      int offset,
      /// Type of adjustment@n
      /// TRUE = absolute (default)@n
      /// FALSE = relative (@c offset may also be negative)
      bool type = true) {
 
        // --------------------------------------------------------------------------
        // Absolute position.
        // --------------------------------------------------------------------------
        if (type) {
          if (offset <            0) throw std::overflow_error("Tail position adjustment of " + std::to_string(offset) + " cannot be negative");
          std::lock_guard<std::mutex> guard(__mutex);
          if (offset > __utilized()) throw std::overflow_error("Tail position adjustment of " + std::to_string(offset) + " exceeds utilized space in ring buffer");
          __tail = (__tail + offset) % __size;
 
        // --------------------------------------------------------------------------
        // Relative position.
        // --------------------------------------------------------------------------
        } else {
          if (offset > 0) { // Positive position
            std::lock_guard<std::mutex> guard(__mutex);
            if (    offset > __utilized() ) throw std::overflow_error("Tail position adjustment of " + std::to_string(offset) + " exceeds utilized space in ring buffer");
            __tail = (__tail + offset) % __size;
          } else if (offset < 0) { // Negative adjustment
            std::lock_guard<std::mutex> guard(__mutex);
            if (0 - offset > __available()) throw std::overflow_error("Tail position adjustment of " + std::to_string(offset) + " exceeds available space in ring buffer");
            __tail += offset;
            if (__tail >= __size) __tail += __size;
          } // -x- if offset -x-
        } // -x- if type -x-
 
        return this;
      } // -x- rring* set_tail -x-
 
      /*======================================================================*//**
      @brief
      Specify whether the internal buffer's memory will be cleared by the
      destructor before de-allocating it (default is @c true upon instantiation).
 
      @note
      This is an important security feature for when the ring buffer may have been
      storing private data because it prevents the leaking of private data to other
      process that coincidentally gain access to the same memory area (e.g., by way
      of future calls to `malloc()`).
      @returns The same rring object so as to facilitate stacking
      @see get_wipe_policy
      @qualifier ADVANCED
      *///=========================================================================
      rring* set_wipe_policy(
      /// TRUE = clear buffer memory in destructor@n
      /// FALSE = don't clear buffer memory in destructor
      const bool policy_flag) noexcept {
        { std::lock_guard<std::mutex> guard(__mutex);
          __wipe_policy = policy_flag;
        } // -x- mutex guard -x-
 
        return this;
      } // -x- rring* set_wipe_policy -x-
 
      /*======================================================================*//**
      @brief
      Configure the automatic expansion policy's incremental block size.
      @exception std::overflow_error If the new setting, which reduces the maximum
                                     quantity of blocks, exceeds the available
                                     memory and would otherwise result in losing
                                     some of the utilized entries
      @returns The same rring object so as to facilitate stacking
      @see get_xp_block_size
      @see set_xp_max
      @see set_xp_play
      @qualifier ADVANCED
      *///=========================================================================
      rring* set_xp_block_size(
      /// Maximum possible number of expansion blocks@n
      /// 0 = disable expansion policy
      const uint xp_block_size) {
        { std::lock_guard<std::mutex> guard(__mutex);
          if (xp_block_size == __xp_block_size) return this; // It's pointless to change to the same thing
 
          // --------------------------------------------------------------------------
          // Internal variables.
          // --------------------------------------------------------------------------
          uint old_xp_used_entries = __xp_used * __xp_block_size;
          uint new_xp_used_entries = __xp_used * xp_block_size;
          size_t base_size = __size - old_xp_used_entries;
          size_t utilized = __utilized();
//std::cout << "__size=" << __size << " base_size=" << base_size << " old_xp_used_entries=" << old_xp_used_entries << " new_xp_used_entries=" << new_xp_used_entries << " utilized=" << utilized << std::endl;
 
          // --------------------------------------------------------------------------
          // Check if size is too small, and throw an exception if it is.
          // --------------------------------------------------------------------------
          if (utilized > base_size + new_xp_used_entries) throw std::overflow_error("Reducing block size to " + std::to_string(xp_block_size) + " exceeds available memory in ring buffer");
 
          // --------------------------------------------------------------------------
          // Update __xp_block_size and then call __adjust_xp to optimize memory block
          // re-allocation.
          // --------------------------------------------------------------------------
          __xp_block_size = xp_block_size;
          __adjust_xp(base_size + new_xp_used_entries);
 
        } // -x- mutex guard -x-
 
        return this;
      } // -x- rring* set_xp_block_size -x-
 
      /*======================================================================*//**
      @brief
      Configure the automatic expansion policy's maximum number of blocks.
      @exception std::overflow_error If the new setting, which reduces the maximum
                                     quantity of blocks, exceeds the available
                                     memory and would otherwise result in losing
                                     some of the utilized entries
      @returns The same rring object so as to facilitate stacking
      @see get_xp_max
      @see set_xp_block_size
      @see set_xp_play
      @qualifier ADVANCED
      *///=========================================================================
      rring* set_xp_max(
      /// Maximum possible number of expansion blocks@n
      /// 0 = disable expansion policy
      const uint xp_max) {
        { std::lock_guard<std::mutex> guard(__mutex);
 
          // --------------------------------------------------------------------------
          // Increasing the maximum, or keeping the maximum the same, is easy, because
          // there's no risk of losing any utilized data.
          // --------------------------------------------------------------------------
          if (xp_max >= __xp_max) {
            __xp_max = xp_max;
 
          // --------------------------------------------------------------------------
          // Decreasing the maximum requires making sure we don't lose data.
          // --------------------------------------------------------------------------
          } else {
            size_t utilized = __utilized();
            uint entries = __size + ((__xp_max - __xp_used) * __xp_block_size) - utilized;// + (utilized % __xp_block_size != 0);
std::cout << "__xp_max=" << __xp_max << " xp_max=" << xp_max << "*" << xp_max * __xp_block_size << " entries=" << entries << std::endl;
            if (entries > xp_max * __xp_block_size) throw std::overflow_error("Reducing maximum blocks to " + std::to_string(xp_max) + " exceeds available blocks in ring buffer");
            __xp_max = xp_max;
          } // -x- if xp_max -x-
        } // -x- mutex guard -x-
 
        return this;
      } // -x- rring* set_xp_max -x-
 
      /*======================================================================*//**
      @brief
      Configure the automatic expansion policy's quantity of available blocks that
      must be present before attempting a reduction of ring buffer memory.
      @returns The same rring object so as to facilitate stacking
      @see get_xp_play
      @see set_xp_block_size
      @see set_xp_max
      @qualifier ADVANCED
      *///=========================================================================
      rring* set_xp_play(
      /// Number of available blocks must be present before attempting reduction
      const uint xp_play) noexcept {
        { std::lock_guard<std::mutex> guard(__mutex);
          __xp_play = xp_play; // Changing this setting doesn't directly impact any data, so just save it
        } // -x- mutex guard -x-
 
        return this;
      } // -x- rring* set_xp_play -x-
 
      /*======================================================================*//**
      @brief
      Convert the entire contents of this ring buffer to an ASCIIZ string in the
      form of a @c char* array.
      @post
      The string returned will need to be `free()`'d after it's no longer needed.
 
      @code{.cpp}
        #include <iostream>      // std::cout, std::cerr, std::endl, etc.
        #include <randolf/rring>
 
        int main(int argc, char *argv[]) {
          randolf::rring rb(1024);
          rb.append("This is an example.");
          char* c = rb;
          std::cout << "\"" << c << "\"" << std::endl;
          free(c);
          return EXIT_SUCCESS;
        } // -x- int main -x-
      @endcode
 
      @exception std::bad_alloc If @c malloc() fails to allocate memory
      @returns Contents of this ring buffer as an ASCII string as a @c char* array.
      @see c_str
      *///=========================================================================
      operator char*() noexcept { return c_str(); } // -x- operator char*() -x-
 
      /*======================================================================*//**
      @brief
      Convert the entire contents of this ring buffer to an @c std::string object.
 
      @code{.cpp}
        #include <iostream>      // std::cout, std::cerr, std::endl, etc.
        #include <string>        // std::string
        #include <randolf/rring>
 
        int main(int argc, char *argv[]) {
          randolf::rring rb(1024);
          rb.append("This is an example.");
          std::string s = rb;
          std::cout << "\"" << s << "\"" << std::endl;
          return EXIT_SUCCESS;
        } // -x- int main -x-
      @endcode
 
      @returns Contents of this ring buffer as an std::string object
      @see peek_to_string
      *///=========================================================================
      operator std::string() noexcept { return peek_to_string(); } // -x- operator std::string -x-
 
      /*======================================================================*//**
      @brief
      Convert the entire contents of this ring buffer to an @c std::vector<char>
      object.
 
      @code{.cpp}
        #include <iostream>      // std::cout, std::cerr, std::endl, etc.
        #include <string>        // std::string
        #include <vector>        // std::vector
        #include <randolf/rring>
 
        int main(int argc, char *argv[]) {
          randolf::rring rb(1024);
          rb.append("This is an example.");
          std::vector<char> v = rb;
          std::cout << "\"" << std::string(v.begin(), v.end()) << "\"" << std::endl;
          return EXIT_SUCCESS;
        } // -x- int main -x-
      @endcode
 
      @returns Contents of this ring buffer as an std::vector<char> object
      @see peek_to_vector
      *///=========================================================================
      operator std::vector<char>() noexcept { return peek_to_vector(); } // -x- operator std::vector<char> -x-
 
      /*======================================================================*//**
      @brief
      Array-style access to the utilized portion of the ring buffer's contents,
      which yields the same result as that of the @ref at() method.
 
      The first element is at index 0.
      @throws std::out_of_range if the index is out-of-range
      @returns char
      @see at
      *///=========================================================================
      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) {
        std::lock_guard<std::mutex> guard(__mutex);
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        int MAX = __utilized();
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
        if (index >= MAX || 0 - index > MAX) throw std::out_of_range("index (position=" + std::to_string(index) + ") falls outside of the utilized portion (length=" + std::to_string(MAX) + ") of the buffer");
 
        // --------------------------------------------------------------------------
        // Calculate character's position.
        // --------------------------------------------------------------------------
        index = index >= 0 ? __tail + index : __head + index;
        if (index >= __size) index -= __size;
 
        return __buffer[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/rring>
 
        int main(int argc, char *argv[]) {
          randolf::rring rb(1024);
          rb.append("This is an example.");
          std::cout << "\"" << rb << "\"" << std::endl;
          return EXIT_SUCCESS;
        } // -x- int main -x-
      @endcode
 
      @returns Contents of this ring buffer as an std::string object (which will be
               de-allocated by the std::string object's destructor upon going out
               of scope)
      @see peek_to_string
      *///=========================================================================
      friend std::ostream& operator<< (
      /// Output stream (provided automatically by std::cout and std::cerr)
      std::ostream& o,
      /// Object class (matched by compiler)
      rring& c) noexcept { return o << c.peek_to_string(); } // -x- std::ostream& operator<< -x-
 
  }; // -x- class rring -x-
 
}; // -x- namespace randolf -x-