bitbuffer.inl

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of module \alib_bitbuffer of the \aliblong.
///
/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
/// Published under #"mainpage_license".
//==================================================================================================
ALIB_EXPORT namespace alib {  namespace bitbuffer {
 
//==================================================================================================
/// An array of integral values used for serializing and deserializing data on bit-level.
/// While writing and reading bits is performed with associated classes #"BitWriter"
/// and #"BitReader", this class is responsible for storing the data and transferring
/// it to an <em>integral</em>-arrays, which may, for example, be written and read to and from
/// <c>std::[i/o]stream</c> objects.
/// With this, platform independence is guaranteed (in respect to little/big-endian storage and
/// similar matters).
///
/// This class is abstract (pure virtual), and does not perform the allocation.
/// With #"BitBuffer", #"BitBufferMA" and #"BitBufferLocal",
/// three descendants with different allocation strategies are provided.
/// A customized version may be easily created by implementing pure virtual methods
/// #".Capacity" and #".EnsureCapacity".
///
/// \attention
///   To avoid the use of virtual function calls bit write operations, methods #".Capacity" and
///   #".EnsureCapacity" are <b>not invoked automatically!</b>.
///   In contrast, it is the users' responsibility to invoke these methods (or only
///   #".EnsureCapacity") before performing data insertions.<br>
///   This behavior is a design decision to maximize execution performance, hence rather a feature.
///
/// Own Implementations have to set field #".data" when reallocating the internal buffer.
//==================================================================================================
class BitBufferBase
{
  public:
        /// The storage type of bit buffers. This is chosen as being <c>unsigned int</c>, which
        /// should be the "fasted" integral type for any compiler/platform combination.
        using TStorage= unsigned int;
 
        static_assert( bitsof(TStorage) == 32 || bitsof(TStorage) == 64,
                       "Unsupported size of C++ int type" );
 
    /// Defines a bit position within outer class #"BitBufferBase". A bit position is
    /// determined by the index in the storage array along with the number of the currently
    /// written (or read) bit. Types #"BitWriter" and #"BitReader"
    /// use this type to define their current write (read) position.
    ///
    /// Methods #"Encode32" and #"Encode64" shorten the information, by storing the bit position in
    /// the upper bits of a \e 32, respectively \e 64 bit value. This is useful whenever a
    /// broader number of bit buffer indices are to be stored. The use case to mention here is
    /// "lazy decoding of data", where only the index to the bit buffer is kept in memory.)
    /// positions
    class Index
    {
        #if !DOXYGEN
            friend class BitBufferBase;
            friend class BitReader;
            friend class BitWriter;
        #endif
 
        uinteger          pos= 0;     ///< Index of the current word to read/write.
        lang::ShiftOpRHS  bit= 0;     ///< Current bit index in the current word.
 
      public:
 
        /// Default constructor initializing members #"pos" and #".bit" to zero.
        Index()                                                                            =default;
 
        /// Constructor
        /// @param pPos The initial value for member #"pos".
        /// @param pBit The initial value for member #".bit".
        Index( uinteger pPos, lang::ShiftOpRHS pBit)
        : pos(pPos)
        , bit(pBit)                                                                               {}
 
        /// Returns the index of the actual storage word in the buffer.
        /// @return The index of the current word containing the next bit to read/write.
        uinteger          Pos()                                                const { return pos; }
 
        /// Returns the number of the actual bit in the actual word of the buffer buffer.
        /// @return The number of the next bit to read/write.
        lang::ShiftOpRHS  Bit()                                                const { return bit; }
 
        /// Returns true, if the next bit to read/write is the first of the current storage
        /// word in the buffer. Alignment of buffers may become important when buffers are
        /// serialized (e.g., to mass storage devices). Method
        /// #"BitBufferBase::Terminate;*" may be used to receive an aligned
        /// index.
        ///
        /// @return The result of <c>Bit() == 0</c>.
        bool        IsAligned()                                           const { return bit == 0; }
 
        /// Sets this index to zero, hence pointing to the first bit in the buffer.
        void        Clear()                                                      { pos= 0; bit= 0; }
 
        /// Returns the size of the memory from given \p{startIdx} to this index occupied by
        /// the internal storage words of the buffer.
        ///
        /// @param startIdx The starting index. Defaults to <c>{0,0}</c>.
        /// @return The size of the buffer (part) in bytes.
        integer GetByteOffset( Index startIdx= Index(0, 0)  )                                const {
            ALIB_ASSERT_ERROR(     startIdx.pos < pos
                               || (startIdx.pos == pos && startIdx.bit < bit), "BITBUFFER",
                 "Given buffer start index is greater than this index." )
            return integer((pos - startIdx.Pos()) * sizeof(TStorage) );
        }
 
        /// Sets this index to point to the word and bit given by a byte offset.<br>
        /// This method is useful when bit buffers are deserialized from character streams.
        /// @param byteOffset The position within the buffer in bytes.
        void        SetFromByteOffset( uinteger byteOffset )
        {
            pos=  byteOffset / sizeof( TStorage );
            bit= (byteOffset % sizeof( TStorage )) * 8 ;
        }
 
        /// Returns the number of bits used in respect to this index.
        /// @return The number of bits written or read.
        uinteger    CountBits()                                                                const
        { return uinteger( pos * bitsof(TStorage) + uinteger(bit) ); }
 
        /// Encodes this index information into a 32-bit variable by using the upper 5 (or 6)
        /// bits for the bit index. As a result, the possible value range of index data is
        /// reduced. The reduction depends on the platform's size of type \c int. In case of
        /// 32-bit, five bits are needed to store the bit position. In the case of 64-bit,
        /// six bits are needed.<br>
        /// As the underlying \e TStorage type changes as well, in both cases, the resulting
        /// addressable storage bytes is limited to the same value:
        /// - TStorage 64-bit: <em>2^(32-6) * 8 bytes = 512 megabytes</em>
        /// - TStorage 32-bit: <em>2^(32-5) * 4 bytes = 512 megabytes</em>
        ///
        /// In case bit buffers grow to over half a gigabyte, 64-bit encoding should be performed
        /// by using alternative method #"Encode64".
        ///
        /// @return The encoded index.
        uint32_t    Encode32() {
            ALIB_ASSERT_ERROR(pos < (uinteger(1) << (31 - lang::Log2OfSize<TStorage>() ) ),
                "BITBUFFER",  "32bit too narrow for endcoding BitBuffer::Index." )
            return uint32_t(pos) | (uint32_t(bit) << (31 - lang::Log2OfSize<TStorage>() ));
        }
 
        /// Encodes this index information into a 64-bit value by using the upper five (or six)
        /// bits for the bit index.
        ///
        /// @see For a shorter encoding, limited to bit buffer sizes of 512 megabytes,
        ///      see method #"Encode32".
        ///
        /// @return The encoded index.
        uint64_t    Encode64()
        { return uint64_t(pos) | (uint64_t(bit) << (63L - lang::Log2OfSize<TStorage>() ));     }
 
        /// Static method that decodes an index information, encoded with #"Encode32", to an
        /// instance of this class.
        ///
        /// @param code  The encoded information.
        /// @return The decoded index.
        static
        Index       Decode32(uint32_t code)
        {
            return Index { uinteger  (code & lang::LowerMask<  31  - lang::Log2OfSize<TStorage>() , uint32_t>() ),
                           lang::ShiftOpRHS(code            >>(31  - lang::Log2OfSize<TStorage>() ))              };
        }
 
 
        /// Static method that decodes an index information, encoded with #"Encode64", to an
        /// instance of this class.
        ///
        /// @param code  The encoded information.
        /// @return The decoded index.
        static
        Index       Decode64(uint64_t code) {
            return Index{uinteger(        code & lang::LowerMask<  63L - lang::Log2OfSize<TStorage>() , uint64_t>() ),
                         lang::ShiftOpRHS(code                  >>(63L - lang::Log2OfSize<TStorage>()))};
        }
 
        /// Comparison operator.
        ///
        /// @param rhs The right-hand side argument of the comparison.
        /// @return \c true if this object equals \p{rhs}, \c false otherwise.
        bool operator==(const Index& rhs)   const { return   (pos == rhs.pos) && (bit == rhs.bit); }
 
        /// Comparison operator.
        ///
        /// @param rhs The right-hand side argument of the comparison.
        /// @return \c true if this object does not equal \p{rhs}, \c false otherwise.
        bool operator!=(const Index& rhs)                        const { return   !(*this == rhs); }
 
        /// Comparison operator.
        ///
        /// @param rhs The right-hand side argument of the comparison.
        /// @return \c true if this object is smaller than \p{rhs}, \c false otherwise.
        bool operator<(const Index& rhs)                                                     const {
            return (pos < rhs.pos) || ((pos == rhs.pos)
                                       && (bit <  rhs.bit)  );
        }
 
        /// Comparison operator.
        ///
        /// @param rhs The right-hand side argument of the comparison.
        /// @return \c true if this object is smaller or equal than \p{rhs}, \c false otherwise.
        bool operator<=(const Index& rhs)                                                    const {
            return (pos < rhs.pos) || ((pos == rhs.pos)
                                       && (bit <=  rhs.bit) );
        }
 
        /// Comparison operator.
        ///
        /// @param rhs The right-hand side argument of the comparison.
        /// @return \c true if this object is greater or equal than \p{rhs}, \c false otherwise.
        bool operator>=(const Index& rhs)                           const { return !(*this < rhs); }
 
        /// Comparison operator.
        ///
        /// @param rhs The right-hand side argument of the comparison.
        /// @return \c true if this object is greater than \p{rhs}, \c false otherwise.
        bool operator>(const Index& rhs)                           const { return !(*this <= rhs); }
    }; // inner struct Index
 
  protected:
 
    /// A pointer to the storage. Implementations of this abstract type have to set this field
    /// when reallocating the internal buffer.
    TStorage*   data;
 
  public:
    /// Default Constructor (the only one).
    BitBufferBase()  noexcept : data(nullptr)                                                     {}
 
    /// Virtual destructor (does nothing, needed for abstract virtual class).
    virtual
    ~BitBufferBase()                                                                              {}
 
    /// Virtual function to determine the (currently allocated) capacity.
    /// @return The size of the internal storage in bits.
    ALIB_DLL
    virtual uinteger    Capacity()                                                         const =0;
 
    /// Virtual function to reserve buffer space by optionally increasing the buffer to
    /// enable the writing of the given bits.
    ///
    /// @param bitsRequired The number of bits required.
    /// @param index        The index to which the capacity is currently used.
    /// @return \c true if the space is available or could be made available,
    ///         \c false otherwise.
    ALIB_DLL
    virtual bool        EnsureCapacity( uinteger bitsRequired, BitBufferBase::Index index )      =0;
 
    /// Returns the storage word at the given position
    /// @param index The index to read the word from. Note that the bit number in this value is
    ///              ignored.
    /// @return The word at the given index.
    TStorage            GetWord(const Index& index)                const { return data[index.pos]; }
 
    /// Stores the given \p{value} at the given \p{index}.
    /// @param index The index to read the word at. Note that the bit number in this value is
    ///              ignored.
    /// @param value The value to store
    void                SetWord(const Index& index, TStorage value)      { data[index.pos]= value; }
 
    /// Returns the number of remaining bits in this buffer in relation to a given index.
    /// @param idx  An actual writing/reading position.
    /// @return The number of bits dived remaining in this buffer.
    uinteger            RemainingSize(const Index& idx)                                        const
    { return   Capacity() - idx.CountBits(); }
 
    /// Returns the start of the internal storage.
    /// @return A pointer to the data array provided by the decendent types.
    TStorage*           Data()                                                const { return data; }
 
    /// Returns the memory address of the internal storage word denoted by \p{idx}
    /// reinterpreted to C++ type <c>char*</c>.
    /// @param idx The index of the word to point to. The bit position within this index is
    ///            ignored.
    /// @return A \c char pointer to the internal storage word the given index refers to.
    char* CharStream( Index idx= Index(0, 0) )
    { return reinterpret_cast<char*>( &data[idx.pos] ); }
 
    /// Writes a termination bit of value \c 1 and lets this buffer's index point to the next
    /// buffer word.\n
    /// Termination can be undone using the result index of this method with #Unterminate.
    /// This method should be invoked before serializing a buffer and method
    /// #Unterminate may be used after deserialization to continue writing to the buffer without
    /// creating a gap.
    ///
    /// @param writerIndex The index to the last bit before termination.
    ///
    /// @return The #"BitBufferBase::Index::IsAligned;aligned" index after termination
    ///         which is aligned point to the first bit behind the last used storage word.
    ///         Such index may be later fed into method #Unterminate to undo the termination.
    ALIB_DLL
    Index   Terminate  (Index writerIndex);
 
    /// Removes the termination bit found in the word before given \p{terminationIndex}.
    /// @param terminationIndex The index returned by previous invocation of method #Terminate.
    ///
    /// @return The index of the next bit to write to the now unterminated buffer.
    ALIB_DLL
    Index   Unterminate(Index terminationIndex);
 
    /// Converts the internal storage words into the platform-independent
    /// "Little Endian Encoding", which means it may change the byte order within the storage
    /// words of the buffer.
    ///
    /// This method is recommended to be used before writing buffer contents to a file to
    /// make files system independent.
    ///
    /// \attention The start index needs to be aligned to a storage word. This is asserted
    ///            in debug compilations.
    ///            See method #"Index::IsAligned" for more information.
    ///
    /// \note It is recommended to terminate the buffer before using this method.
    ///       and to pass the index returned by method #Terminate as second parameter
    ///       \p{endIndex}.
    ///
    /// \see Method #FromLittleEndianEncoding.
    ///
    /// @param startIndex The first storage word to convert. (The bit position of the index
    ///                   is ignored).
    /// @param endIndex   The first bit behind the storage to be converted. Hence, if the bit
    ///                   position within this argument is not \c 0, then the whole word that
    ///                   this index points to, will be converted. Otherwise it won't.
    ALIB_DLL
    void    ToLittleEndianEncoding( const Index&   startIndex,
                                    const Index&   endIndex    );
 
    /// The counter-method to #ToLittleEndianEncoding.
    ///
    /// @param startIndex The first storage word to convert. (The bit position of the index
    ///                   is ignored).
    /// @param endIndex   The first bit behind the storage to be converted. Hence, if the bit
    ///                   position within this argument is not \c 0, then the whole word that
    ///                   this index points to, will be converted. Otherwise it won't.
    ALIB_DLL
    void    FromLittleEndianEncoding( const Index& startIndex, const Index& endIndex );
}; // class BitBufferBase
 
//==================================================================================================
/// A bit buffer using dynamic allocation.
/// \see
///   - Two alternatives are provided with #"BitBufferMA", which uses
///     #"alib_mods_contmono;monotonic allocation" and #"BitBufferLocal", which uses
///     local (stack) memory.
///   - For this class, a #"alibtools_debug_helpers_gdb;pretty printer" for the
///     GNU debugger is provided.
//==================================================================================================
class BitBuffer: public BitBufferBase
{
  protected:
    /// The vector that holds the data.
    std::vector<TStorage>   storage;
 
  public:
    /// Constructor.
    /// @param initialCapacity  The requested initial capacity of the buffer in bits.
    BitBuffer( uinteger initialCapacity )              { EnsureCapacity(initialCapacity, Index()); }
 
    /// Returns the (currently allocated) capacity.
    /// @return The size of the internal storage in bits.
    virtual uinteger Capacity()     const override { return storage.capacity() * bitsof(TStorage); }
 
    /// Checks if the given required storage space is internally reserved. If not,
    /// the internal capacity is doubled, or, if more is required, set to the required space.
    ///
    /// @param bitsRequired The number of bits required.
    /// @param idx          The index of current buffer use.
    /// @return \c true if the space is available or could be made available,
    ///         \c false otherwise.
    virtual bool     EnsureCapacity(uinteger bitsRequired, BitBufferBase::Index idx)      override {
        uinteger capacityNeeded= (idx.CountBits() + bitsRequired + (bitsof(TStorage) - 1) )
                                 / bitsof(TStorage);
        if( capacityNeeded > storage.capacity() )
            storage.reserve( (std::max)( capacityNeeded, uinteger(storage.capacity()) * 2 ));
        data= storage.data();
 
        return true;
    }
}; // class BitBuffer
 
//==================================================================================================
/// A bit buffer using #"alib_mods_contmono;monotonic allocation".
/// \see
///   Two alternatives are provided with #"BitBuffer" and #"BitBufferLocal".
//==================================================================================================
class BitBufferMA  : public BitBufferBase
{
  protected:
    /// The monotonic allocator used internally to allocate the storage. This is provided
    /// with construction.
    MonoAllocator&             ma;
 
    /// The vector that holds the data.
    StdVectorMA<TStorage>    storage;
 
  public:
    /// Constructor taking an external monotonic allocator and the initial capacity.
    /// @param monoAllocator    A reference to a monotonic allocator to use to allocate buffer
    ///                         storage data.
    /// @param initialCapacity  The requested initial capacity of the buffer in bits.
    BitBufferMA( MonoAllocator& monoAllocator, uinteger initialCapacity )
    : ma( monoAllocator )
    , storage(ma)                                      { EnsureCapacity(initialCapacity, Index()); }
 
 
    /// Returns the (currently allocated) capacity.
    /// @return The size of the internal storage in bits.
    virtual uinteger Capacity()     const override { return storage.capacity() * bitsof(TStorage); }
 
    /// Checks if the given required storage space is internally reserved. If not,
    /// the internal capacity is doubled, or, if more is required, set to the required space.
    ///
    /// @param bitsRequired The number of bits divided required.
    /// @param idx          The index of current buffer use.
    /// @return \c true if the space is available or could be made available,
    ///         \c false otherwise.
    virtual bool     EnsureCapacity(uinteger bitsRequired, BitBufferBase::Index idx)      override {
        uinteger capacityNeeded= (idx.CountBits() + bitsRequired + (bitsof(TStorage) - 1) )
                                 / bitsof(TStorage);
        if( capacityNeeded > storage.capacity() )
            storage.reserve( (std::max)( capacityNeeded, uinteger(storage.capacity()) * 2 ));
        data= storage.data();
 
        return true;
    }
 
    /// Returns the internal monotonic allocator for external use.
    /// @return The monotonic allocator given on construction.
    MonoAllocator& GetAllocator()                                                     { return ma; }
}; // class BitBufferMA
 
//==================================================================================================
/// A bit buffer using local storage, which means a fixed size internal array.
/// If used as function member, the storage is located on the stack and hence its size has
/// platform-specific limitations.<br>
/// This class is useful to read and write smaller pieces of data, for example, header information
/// of binary data files which furthermore are filled/loaded with bit buffers using of other memory
/// allocations.
/// \see
///   Two alternatives are provided with #"BitBuffer" and #"BitBufferMA".
/// @tparam TCapacity The number of bits to reserve internally
//==================================================================================================
template<uinteger TCapacity>
class BitBufferLocal  : public BitBufferBase
{
  protected:
    /// The array that holds the data.
    TStorage    storage[ (TCapacity + bitsof(TStorage) - 1) / bitsof(TStorage) ];
 
  public:
    /// Constructor.
    BitBufferLocal()                                                     noexcept { data= storage; }
 
    /// Returns the (in this case fixed size!) capacity.
    /// @return The size of the internal storage in bits.
    virtual uinteger Capacity()                                 const override { return TCapacity; }
 
    /// Checks if the given required storage space is internally reserved.
    /// If not, in debug compilations an \alib_assertion is raised because this is a fixed size
    /// buffer.
    ///
    /// @param bitsRequired The number of bits required.
    /// @param idx          The index of current buffer use.
    /// @return \c true if the space is available or could be made available,
    ///         \c false otherwise.
    virtual bool     EnsureCapacity(uinteger bitsRequired, BitBufferBase::Index idx)      override {
        uinteger capacityNeeded= idx.CountBits() + bitsRequired;
        if( capacityNeeded > TCapacity ) {
            ALIB_ERROR("BITBUFFER", "Local bit buffer cannot expand its capacity" )
            return false;
        }
 
        return true;
    }
}; // class BitBufferLocal
 
 
//==================================================================================================
/// Non-instantiatable base class for types #"BitWriter" and #"BitReader".
//==================================================================================================
class BitRWBase
{
  protected:
    BitBufferBase&          bb;    ///< The bit buffer to write into. Provided on construction.
    BitBufferBase::Index    idx;   ///< The current reading/writing index within #bb.
 
    /// Protected constructor, used by derived classes only.
    /// @param buffer The bit buffer to work on.
    explicit BitRWBase( BitBufferBase& buffer )
    : bb  ( buffer )                                                                              {}
 
  public:
    /// Retrieves the internal bit buffer.
    /// @return The buffer the derived reader or writer works with.
    BitBufferBase&              GetBuffer()                                     const { return bb; }
 
    /// Returns a copy of the current index in the bit buffer in respect to writing or
    /// reading progress of derived classes #"BitWriter" #"BitReader".
    /// Such index elements may be passed to methods
    /// #"BitWriter::Reset(const BitBufferBase::Index&)" and
    /// #"BitReader::Reset(const BitBufferBase::Index&)"
    /// @return The index of the next bit to write.
    BitBufferBase::Index        GetIndex()                                     const { return idx; }
 
    /// Invokes #"BitBufferBase::Index::CountBits;*" on the index returned by #GetIndex.
    /// @return The number of bits currently read from or written to the buffer.
    uinteger                    Usage()                            const { return idx.CountBits(); }
 
    /// Invokes #"BitBufferBase::RemainingSize;*" on the internal bit buffer, passing
    /// the result of #GetIndex.
    /// @return The number of bits dived by 8 remaining in this buffer.
    uinteger                    RemainingSize()            const { return   bb.RemainingSize(idx); }
 
};
 
//==================================================================================================
/// Writes bits into a #"BitBufferBase".
//==================================================================================================
class BitWriter : public BitRWBase
{
    /// Local type alias (shortcut)
    using TStorage= BitBufferBase::TStorage;
 
    /// The current word, which is partly written and not stored in buffer, yet.
    BitBufferBase::TStorage     word;
 
  public:
    /// Constructs a bit writer operating on the given bit buffer.
    /// @param buffer The buffer to write to (starting at the beginning).
    explicit BitWriter( BitBufferBase& buffer )
    : BitRWBase( buffer )                                                               { word= 0; }
 
    /// Constructs a bit writer operating on the given bit buffer, starting to write at the
    /// given #"BitBufferBase::Index".
    /// @param buffer The buffer to write to.
    /// @param index  An index providing the postion of the first bit to (over-) write in
    ///               \p{buffer}.
    explicit BitWriter( BitBufferBase& buffer, const BitBufferBase::Index& index )
    : BitRWBase  ( buffer )
    {
        idx= index;
        word= bb.GetWord(idx) & lang::LowerMask<TStorage>( idx.bit );
    }
 
    /// Destructs a bit writer. Invokes #Flush().
    ~BitWriter()                                                                        { Flush(); }
 
    /// Resets the internal index of this writer to the start of the bit buffer.
    void   Reset()                                        { idx = BitBufferBase::Index(); word= 0; }
 
    /// Resets the internal index of this writer to the given one.
    /// @param index The position of the next bit in the buffer to write to.
    void   Reset( const BitBufferBase::Index& index ) {
        idx.pos= index.pos;
        idx.bit= index.bit;
        word= bb.GetWord(idx) & lang::LowerMask<TStorage>(idx.bit );
    }
 
    /// Writes the last word of bits into the underlying buffer.
    /// This method has to be called before writing the buffer to a file or similar.
    /// The method is automatically invoked on destruction.
    void    Flush()                                                       { bb.SetWord(idx, word); }
 
    #if DOXYGEN
        /// Writes the given integral value with the given number of bits to the stream.
        /// \note
        ///   Internally, different template functions selected with keyword \c requires
        ///   for the different integral types exist.
        ///
        /// \see
        ///   This method uses a template parameter for the number of bits to write.
        ///   A slightly slower, non-templated version is available with
        ///   #WriteBits<TValue, TMaskValue>( ShiftOpRHS, TValue)
        ///   which is to be used when the value is determined only at run-time.
        ///
        /// @tparam TWidth     The number of bits in \p{value} to write.
        /// @tparam TValue     The type of \p{value} to write. (Deduced from parameter \p{value}.)
        /// @tparam TMaskValue Determines if bits beyond \p{width} of given \p{value} may be set and
        ///                    have to be masked out.
        ///                    Defaults to \c false.
        /// @param  value      The value to write.
        template<ShiftOpRHS TWidth, typename TIntegral, bool TMaskValue= false>
        void WriteBits( TIntegral value );
    #else
        // Version 1/2: #Bits to write are less or equal to internal buffer width
        template<lang::ShiftOpRHS TWidth, typename TValue, bool TMaskValue= false>
        requires (      std::unsigned_integral<TValue>
                    && !std::same_as          < TValue, bool>
                    && ( TWidth <= bitsof(TStorage) )            )
        void WriteBits(TValue value ) {
            static_assert(bitsof(TValue) >= TWidth, "Fixed size given greater than value type.");
            ALIB_ASSERT_ERROR(idx.pos < bb.Capacity(), "BITBUFFER", "BitBufferBase overflow" )
            ALIB_ASSERT_ERROR(    TMaskValue
                               || TWidth == bitsof(TValue)
                               || value == (value & lang::LowerMask<TValue>(TWidth) ),  "BITBUFFER",
                               "Upper bits dirty while TMaskValue flag not set." )
 
            if constexpr ( (TWidth < bitsof(TValue)) && TMaskValue )
                value&=  lang::LowerMask<TWidth, TValue >();
 
            word|=   TStorage(value) << idx.bit ;
            idx.bit+= TWidth;
            if(idx.bit >= bitsof(TStorage) ) {
                bb.SetWord(idx, word);
                idx.pos++;
                word= 0;
                idx.bit-= bitsof(TStorage);
                if( idx.bit )
                    word|= (TStorage(value) >> (TWidth - idx.bit) );
        }   }
 
        // Version 2/2: #Bits to write is greater than internal buffer width
        template<lang::ShiftOpRHS TWidth, typename TValue, bool TMaskValue= false>
        requires (      std::unsigned_integral<TValue>
                    && !std::same_as          < TValue, bool>
                    && ( TWidth > bitsof(TStorage) )            )
        void WriteBits(TValue value ) {
            static_assert(bitsof(TValue) >= TWidth, "Fixed size given greater than value type.");
            ALIB_ASSERT_ERROR(idx.pos < bb.Capacity(), "BITBUFFER", "BitBufferBase overflow" )
            ALIB_ASSERT_ERROR(    TMaskValue
                               || TWidth == bitsof(TValue)
                               || value == (value & lang::LowerMask<TValue>(TWidth) ),  "BITBUFFER",
                               "Upper bits dirty while TMaskValue not set." )
 
            if constexpr ( (TWidth <  bitsof(TValue)) && TMaskValue )
                value&=  lang::LowerMask<TWidth, TValue>();
 
            word|= (TStorage(value) << idx.bit);
            lang::ShiftOpRHS bitsWritten= bitsof(TStorage) - idx.bit;
            value>>= bitsWritten;
            while(true) { // the loop is at least hit once and bit is 0! (but not written in bit)
                bb.SetWord(idx, word);
                idx.pos++;
                word= TStorage(value);
                bitsWritten+= bitsof(TStorage);
                if(bitsWritten >= TWidth )
                    break;
 
                value>>= bitsof(TStorage);
            }
 
            idx.bit= (idx.bit + TWidth) % bitsof(TStorage);
            if(idx.bit == 0 ) { // next buffer value reached?
                bb.SetWord(idx, word);
                idx.pos++;
                word= 0;
        }   }
 
        // Helper-versions for signed and bool
        template<lang::ShiftOpRHS TWidth, typename TValue, bool TMaskValue= false>
        requires ( std::signed_integral<TValue> && !std::same_as<TValue, bool>  )
        void WriteBits(TValue value) {
            using TUI= typename std::make_unsigned<TValue>::type;
            WriteBits<TWidth, TUI, TMaskValue>( static_cast<TUI>( value ) );
        }
 
        template<typename TValue>
        requires ( std::same_as<TValue, bool>  )
        void WriteBits(TValue value)
        { WriteBits<1, unsigned int, false>( static_cast<unsigned int>( value ) ); }
 
    #endif // doxygen
 
 
// Doxygen (V1.15) would create identical entries in its tag-file, so those are not reachable.
// On the other hand, it complains if the methods are not doxed. So, we hide them from doxygen.
#if DOXYGEN
    /// Writes the given integral value with the given number of bits to the stream.
    /// \note Internally, two versions of this method, selected with keyword \c requires,
    ///       for different integral types exist.
    /// \see
    ///   A method that uses a template parameter for the number of bits to write, is
    ///   available with #WriteBits<TWidth,TIntegral>(TIntegral).
    ///   This might be slightly faster and should be used instead of this method, whenever the
    ///   number of bits to write is known at compilation time.
    ///
    /// @tparam TValue     The integral type of the value to write.
    ///                    (Deduced from parameter \p{value}.)
    /// @tparam TMaskValue Determines if bits beyond \p{width} of given \p{value} may be set and
    ///                    have to be masked out. Defaults to \c false.
    /// @param  width      The number of bits in \p{value}.
    /// @param  value      The value to write.
    template<typename TValue, bool TMaskValue= false>
    requires ( std::integral<TValue>  && ( sizeof(TValue) <= sizeof(TStorage) ) )
    void WriteBits(lang::ShiftOpRHS width, TValue value);
#else
    template<typename TValue, bool TMaskValue= false>
    requires ( std::integral<TValue>  && ( sizeof(TValue) <= sizeof(TStorage) ) )
    void WriteBits(lang::ShiftOpRHS width, TValue value) {
        ALIB_ASSERT_ERROR(idx.pos < bb.Capacity(), "BITBUFFER", "BitBufferBase overflow" )
        ALIB_ASSERT_ERROR( width <= bitsof(TValue),
              "BITBUFFER", "BitBufferBase::Write: Width too high: ", width )
 
        ALIB_ASSERT_ERROR(    TMaskValue
                           || width>=bitsof(TValue)
                           || value == (value & lang::LowerMask<TValue>(width) ),
              "BITBUFFER", "Upper bits dirty while TMaskValue not set.")
 
         if constexpr (TMaskValue)
            if( width < bitsof(TValue) )
                value&= lang::LowerMask<TValue>(width);
 
        word|= TStorage(value) << idx.bit ;
        idx.bit+= width;
        if(idx.bit >= bitsof(TStorage) ) {
            bb.SetWord(idx, word);
            idx.pos++;
            word= 0;
            idx.bit-= bitsof(TStorage);
            if( idx.bit )
                word|= ( TStorage(value) >> (width - idx.bit) );
    }   }
 
    template<typename TValue, bool TMaskValue= false>
    requires ( std::integral<TValue>  && ( sizeof(TValue) > sizeof(TStorage) ) )
    void WriteBits(lang::ShiftOpRHS width, TValue value) {
        ALIB_ASSERT_ERROR( idx.pos < bb.Capacity(), "BITBUFFER", "BitBufferBase overflow" )
        ALIB_ASSERT_ERROR( width <= bitsof(TValue), "BITBUFFER",
                "BitBufferBase::Write: Width too high: ", width )
        ALIB_ASSERT_ERROR(    TMaskValue
                           || width==bitsof(TValue)
                           || value == (value & lang::LowerMask<TValue>(width) ),
                "BITBUFFER", "Upper bits dirty while TMaskValue not set.")
 
        if constexpr (TMaskValue)
            if( width <= bitsof(TValue) )
                value&= lang::LowerMask<TValue>(width);
 
        if( width <= bitsof(TStorage) ) {
            word|= TStorage(value) << idx.bit ;
            idx.bit+= width;
            if(idx.bit >= bitsof(TStorage) ) {
                bb.SetWord(idx, word);
                idx.pos++;
                word= 0;
                idx.bit-= bitsof(TStorage);
                if( idx.bit )
                    word|= ( TStorage(value) >> (width - idx.bit) );
            }
        } else {
            word|= (TStorage(value) << idx.bit);
            lang::ShiftOpRHS bitsWritten= bitsof(TStorage) - idx.bit;
            value>>= bitsWritten;
            while(true) { // the loop is at least hit once and bit is 0! (but not written in bit)
                bb.SetWord(idx, word);
                idx.pos++;
                word= TStorage(value);
                bitsWritten+= bitsof(TStorage);
                if(bitsWritten >= width )
                    break;
                value>>= bitsof(TStorage);
            }
            idx.bit= (idx.bit + width) % bitsof(TStorage);
            if(idx.bit == 0 ) { // next buffer value reached?
                bb.SetWord(idx, word);
                idx.pos++;
                word= 0;
    }   }   }
#endif
    
    /// Writes the given unsigned integral value to the stream by writing lower values
    /// with smaller sizes. The general assumption behind this is that lower values are more frequent
    /// and the average written size is less than the unencode size - despite the overhead needed
    /// to write information about how a value is encoded.
    ///
    /// The encoding for \e unsigned integrals is as follows:
    /// - For byte value types, a single bit <c>'0'</c> is written if the value is below \c 8,
    ///   followed by the three bits containing the value. Otherwise, a single bit <c>'1'</c> is
    ///   written, followed by the full 8 bits.
    /// - For all other value types (16-, 32- and 64-bit) the number of bytes needed is written
    ///   first (one bit in the case of 16-bit values, two bits in the case of 32-bit values
    ///   and three bits in the case of 64 bit values), and then the corresponding amount of
    ///   full bytes are written.
    ///
    /// \e Signed integrals are converted to unsigned integrals using the sometimes called
    /// "zig-zag coding". Here, all numbers are doubled and negative numbers are turned
    /// positive and uneven. This way, the least significant bit becomes the sign bit.
    /// The advantage of this approach is that small numbers, negative or positive,
    /// remain small in respect to their bitwise representation.<p>
    /// The conversion hence is as follows:
    ///      unsigned =  signed >= 0  ?   signed * 2   :  ( (-signed -1 ) * 2 ) | 1
    ///
    /// @tparam TUIntegral  The type of the given unsigned integral.
    /// @param  value       The value to write.
    template<typename TUIntegral>
    requires ( std::unsigned_integral<TUIntegral> && !std::same_as< TUIntegral, bool> )
    void WriteInt( TUIntegral value )
    {
        ALIB_ASSERT_ERROR( idx.pos < bb.Capacity(), "BITBUFFER", "BitBufferBase overflow" )
        writeUIntegral(value);
    }
 
    /// Converts the given \e signed integral to an unsigned one using the so-called
    /// "zig-zag coding". Here, all numbers are doubled and negative numbers are turned
    /// positive and uneven. This way, the least significant bit becomes the sign bit.
    /// The advantage of this approach is that small numbers, negative or positive,
    /// remain small in respect to their bitwise representation.<p>
    /// The conversion hence is as follows:
    ///      unsigned =  signed >= 0  ?   signed * 2   :  ( (-signed -1 ) * 2 ) | 1
    ///
    /// Then calls #"BitWriter::WriteInt(TUIntegral)".
    /// @tparam TSIntegral  The type of the given signed integral.
    /// @param  value       The value to write.
    template<typename TSIntegral>
    requires ( std::signed_integral<TSIntegral> && !std::same_as< TSIntegral, bool> )
    void WriteInt( TSIntegral value ) {
        ALIB_ASSERT_ERROR( idx.pos < bb.Capacity(), "BITBUFFER", "BitBufferBase overflow" )
        using TUnsigned= typename std::make_unsigned<TSIntegral>::type;
        writeUIntegral(  value >= 0 ? TUnsigned( value << 1)
                                    : TUnsigned( (TUnsigned(-(value+ 1)) << 1) | 1 )   );
    }
 
  protected:
 
    /// Internal method that writes a unsigned 8-bit value.
    /// @param value The value to write.
    ALIB_DLL void      writeUIntegral( uint8_t  value );
 
    /// Internal method that writes a unsigned 16-bit value.
    /// @param value The value to write.
    ALIB_DLL void      writeUIntegral( uint16_t value );
 
    /// Internal method that writes a unsigned 32-bit value.
    /// @param value The value to write.
    ALIB_DLL void      writeUIntegral( uint32_t value );
 
    /// Internal method that writes a unsigned 64-bit value.
    /// @param value The value to write.
    ALIB_DLL void      writeUIntegral( uint64_t value );
 
}; // class BitWriter
 
 
//==================================================================================================
/// Reads bits from a #"BitBufferBase".
//==================================================================================================
class BitReader : public BitRWBase
{
  protected:
    /// Local type alias (shortcut)
    using TStorage= BitBufferBase::TStorage;
 
    /// The current word, which is partly read and shifted to start with current bit.
    BitBufferBase::TStorage     word;
 
  public:
    /// Constructs a bit reader using the given bit buffer and starting to read at the beginning.
    /// @param buffer    The buffer to read from.
    explicit BitReader( BitBufferBase& buffer )
    : BitRWBase( buffer )                                                 { word= bb.GetWord(idx); }
 
 
    /// Constructs a bit reader using the given bit buffer, starting to read at the
    /// given #"BitBufferBase::Index".
    /// @param buffer The buffer to read from.
    /// @param index  An index providing the postion of the first bit to read in \p{buffer}.
    explicit BitReader( BitBufferBase& buffer, const  BitBufferBase::Index& index )
    : BitRWBase( buffer ) {
        idx.pos= index.pos;
        idx.bit= index.bit;
        word= bb.GetWord(idx) >> idx.bit;
    }
 
    /// Destructs a bit reader. In debug compilations an \alib_assertion is raised if the
    /// read operation passed the end of the underlying buffer was performed.
    ~BitReader()
    {
        ALIB_ASSERT_ERROR( idx.pos < bb.Capacity(), "BITBUFFER",
              "BitBufferBase overflow detected. Ensure a higher capacity" )
    }
 
    /// Resets this reader to the start of the bit buffer.
    void   Reset() {
        idx.pos= 0;
        idx.bit= 0;
        word= bb.GetWord(idx);
    }
 
    /// Resets this reader to the given index position and calls #Sync().
    /// @param index The next read position.
    void   Reset( const BitBufferBase::Index& index ) {
        idx.pos= index.pos;
        idx.bit= index.bit;
        Sync();
    }
 
    /// Re-reads the currently fetched storage word from the memory.
    /// \note This method is not needed in common use cases and implemented solely for the
    ///       purpose to support unit-tests which write and write in parallel to the same
    ///       bit buffer.
    /// @return A reference to this \c BitReader to allow concatenated operations.
    BitReader&  Sync()                           { word= bb.GetWord(idx) >> idx.bit; return *this; }
 
// Doxygen (V1.15) would create identical entries in its tag-file, so those are not reachable.
// On the other hand, it complains if the methods are not doxed. So, we hide them from doxygen.
#if DOXYGEN
    /// Reads the given number of bits from the stream into the given unsigned integral value.
    /// \note
    ///   Two different template functions (selected by keyword \c requires) for the different
    ///   integral types exist.
    ///   One to read a number of bits that are less or equal to the internal buffer width, and
    ///   one if there is more to read than the internal buffer width.
    /// \see
    ///   This method uses a template parameter for the number of bits to read.
    ///   A slightly slower, non-templated version is available with #ReadBits<TResult>(ShiftOpRHS),
    ///   which is to be used when the number of bits to read is determined only at run-time.
    /// @tparam TWidth    The number of bits in \p{value} to write.
    /// @tparam TResult   The type of the value to return.
    /// @return The value read.
    template<lang::ShiftOpRHS TWidth, typename TResult= int>
    TResult ReadBits();
#else
    template<lang::ShiftOpRHS TWidth, typename TResult= int>
    requires ( std::integral<TResult> &&  ( TWidth <= bitsof(TStorage)) )
    TResult ReadBits() {
        ALIB_ASSERT_ERROR(idx.pos < bb.Capacity(), "BITBUFFER", "BitBufferBase overflow" )
 
        TResult     result;
 
        // the one bit case. Could have been left to the compiler to optimize, but who knows.
        if constexpr ( TWidth == 1 ) {
            result=  word & 1;
            word>>= 1;
            if(++idx.bit == bitsof(TStorage)) {
                idx.pos++;
                word= bb.GetWord(idx);
                idx.bit= 0;
            }
            return result;
        }
 
        static_assert(bitsof(TResult) >= TWidth, "Fixed size to read greater than given result type.");
        if constexpr ( TWidth == bitsof(TStorage)  )
            result= TResult( word );
        else {
            result= TResult( word  & lang::LowerMask<TWidth, TStorage>() );
            word>>= TWidth;
        }
 
        idx.bit+= TWidth;
        if(idx.bit >= bitsof(TStorage)) {
            idx.pos++;
            word= bb.GetWord(idx);
            idx.bit-= bitsof(TStorage);
            if( idx.bit ) {
                lang::ShiftOpRHS bitsRead= TWidth - idx.bit;
                if constexpr ( TWidth < bitsof(TStorage)  )
                    result |= TResult( (   word << bitsRead )
                                         & lang::LowerMask<TWidth, TStorage>() );
                else
                    result |= TResult(   word << bitsRead          );
            }
 
            word>>= idx.bit;
        }
 
        return result;
    }
 
    template<lang::ShiftOpRHS TWidth, typename TResult= int>
    requires ( std::integral<TResult> &&  ( TWidth > bitsof(TStorage)) )
    TResult ReadBits() {
        static_assert(bitsof(TResult) >= TWidth, "Fixed size to read greater than given result type.");
        ALIB_ASSERT_ERROR( idx.pos < bb.Capacity(), "BITBUFFER", "BitBufferBase overflow" )
 
        TResult    result  = word;
        lang::ShiftOpRHS bitsRead= bitsof(TStorage) - idx.bit;
        do { // the loop is at least hit once and bit is 0! (but not written in bit)
            idx.pos++;
            word= bb.GetWord(idx);
            result|= TResult(word) << bitsRead;
            bitsRead+= bitsof(TStorage);
        }
        while( bitsRead < TWidth);
 
        idx.bit= (idx.bit + TWidth) % bitsof(TStorage);
 
        // next buffer value reached?
        if(idx.bit == 0 )
            idx.pos++;
        else
            result= lang::LowerBits<TWidth, TResult>( result );
 
        word= bb.GetWord(idx) >> idx.bit;
 
        return result;
    }
#endif
 
// Doxygen (V1.15) would create identical entries in its tag-file, so those are not reachable.
// On the other hand, it complains if the methods are not doxed. So, we hide them from doxygen.
#if DOXYGEN
    /// Reads the given number of bits from the stream into the given unsigned integral value.
    /// \note
    ///   Two different implementations for different integral types exist and are
    ///   selected with keyword \c requires.
    ///
    /// \see
    ///   A method that uses a template parameter for the number of bits to read, is available
    ///   with #ReadBits<TWidth,TResult>.
    ///   This might be slightly faster and should be used instead of this method, whenever
    ///   the number of bits to read is known at compilation time.
    ///
    /// @tparam TResult  The type of the value to return. Defaults to type \c int.
    /// @param  width    The number of bits to read.
    /// @return The value read.
    template<typename TResult= int>
    TResult ReadBits( lang::ShiftOpRHS width );
#else
    template<typename TResult= int>
    requires ( sizeof(TResult) <= sizeof(TStorage) )
    TResult ReadBits( lang::ShiftOpRHS width ) {
        ALIB_ASSERT_ERROR( idx.pos < bb.Capacity(),  "BITBUFFER", "BitBufferBase overflow" )
        ALIB_ASSERT_ERROR( bitsof(TResult) >= width, "BITBUFFER",
                                                     "Read size given greater than value type.")
 
        TResult     result;
        if ( width < bitsof(TStorage)  )
            result= TResult( word   & lang::LowerMask<TStorage>(width) );
        else
            result= TResult( word  );
        word>>= width;
 
        idx.bit+= width;
        if(idx.bit >= bitsof(TStorage)) {
            idx.pos++;
            word= bb.GetWord(idx);
            idx.bit-= bitsof(TStorage);
 
            if( idx.bit ) {
                lang::ShiftOpRHS bitsRead= width - idx.bit;
                result |= TResult( (   word << bitsRead )
                                     & lang::LowerMask<TStorage>(width) );
                word>>= idx.bit;
        }   }
 
        return result;
    }
 
    template<typename TResult= int>
    requires ( sizeof(TResult) > sizeof(TStorage) )
    TResult ReadBits( lang::ShiftOpRHS width ) {
        ALIB_ASSERT_ERROR( idx.pos < bb.Capacity(),   "BITBUFFER", "BitBufferBase overflow" )
        ALIB_ASSERT_ERROR( bitsof(TResult) >= width , "BITBUFFER",
                                                      "Read size given greater than value type.")
 
        if( width <= bitsof(TStorage)) {
            TResult     result;
            if ( width < bitsof(TStorage)  )
                result= TResult( word   & lang::LowerMask<TStorage>(width) );
            else
                result= TResult( word  );
            word>>= width;
 
            idx.bit+= width;
            if(idx.bit >= bitsof(TStorage)) {
                idx.pos++;
                word= bb.GetWord(idx);
                idx.bit-= bitsof(TStorage);
 
                if( idx.bit ) {
                    lang::ShiftOpRHS bitsRead= width - idx.bit;
                    result |= TResult( (   word << bitsRead )
                                         & lang::LowerMask<TStorage>(width) );
                    word>>= idx.bit;
            }   }
 
            return result;
        } else {
            TResult     result  = TResult( word );
            lang::ShiftOpRHS  bitsRead= bitsof(TStorage) - idx.bit;
            do { // the loop is at least hit once and bit is 0! (but not written in bit)
                idx.pos++;
                word= bb.GetWord(idx);
                result|= TResult(word) << bitsRead;
                bitsRead+= bitsof(TStorage);
            }
            while( bitsRead < width);
 
            idx.bit= (idx.bit + width) % bitsof(TStorage);
 
            // next buffer value reached?
            if(idx.bit == 0 ) {
                idx.pos++;
                word= bb.GetWord(idx);
            } else {
                result= lang::LowerBits<TResult>( width, result );
                word>>= width;
            }
            return result;
    }   }
 
#endif
 
 
// Doxygen (V1.15) would create identical entries in its tag-file, so those are not reachable.
// On the other hand, it complains if the methods are not doxed. So, we hide them from doxygen.
#if DOXYGEN
    /// Reads the given integral value from the stream.
    /// Information about the encoding of the values is given with the documentation of
    /// #"BitWriter::WriteBits(TIntegral);WriteBits<TIntegral>(TIntegral)".<br>
    ///
    /// Note that the implementation of this method consists of various versions which
    /// are selected using C++20 keyword \c requires.
    /// @tparam TUIntegral The unsigned integral type to read.
    /// @return The value read from the bit buffer.
    template< typename TUIntegral>
    TUIntegral ReadInt()                                                   { return readUIntegral8(); }
#else
    template< typename TUIntegral>
    requires( std::unsigned_integral<TUIntegral> && (bitsof(TUIntegral) == 8) )
    TUIntegral ReadInt()                                                   { return readUIntegral8(); }
 
    template< typename TUIntegral>
    requires( std::unsigned_integral<TUIntegral> && (bitsof(TUIntegral) == 16) )
    TUIntegral ReadInt()                                                  { return readUIntegral16(); }
 
 
    template< typename TUIntegral>
    requires( std::unsigned_integral<TUIntegral> && (bitsof(TUIntegral) == 32) )
    TUIntegral ReadInt()                                                  { return readUIntegral32(); }
 
    template< typename TUIntegral>
    requires( std::unsigned_integral<TUIntegral> && (bitsof(TUIntegral) == 64) )
    TUIntegral  ReadInt()                                                 { return readUIntegral64(); }
 
    template< typename TSIntegral>
    requires( std::signed_integral<TSIntegral> )
    TSIntegral ReadInt() {
        using TUnsigned= typename std::make_unsigned<TSIntegral>::type;
        TUnsigned result= ReadInt<TUnsigned>();
        return    result & 1 ?  TSIntegral( -TSIntegral( result >> 1 ) - 1 )
                             :  TSIntegral(              result >> 1 );
    }
#endif
 
  protected:
    /// Internal method that reads a unsigned 8-bit value.
    /// @return The value read.
    ALIB_DLL uint8_t   readUIntegral8();
 
    /// Internal method that reads a unsigned 16-bit value.
    /// @return The value read.
    ALIB_DLL uint16_t  readUIntegral16();
 
    /// Internal method that reads a unsigned 32-bit value.
    /// @return The value read.
    ALIB_DLL uint32_t  readUIntegral32();
 
    /// Internal method that reads a unsigned 64-bit value.
    /// @return The value read.
    ALIB_DLL uint64_t  readUIntegral64();
 
 
}; // class BitReader
 
} // namespace alib[::bitbuffer]
 
/// Type alias in namespace \b alib.
using       BitBuffer       = bitbuffer::BitBuffer;
 
/// Type alias in namespace \b alib.
using       BitBufferMA     = bitbuffer::BitBufferMA;
 
/// Type alias in namespace \b alib.
template<uinteger TCapacity>
using       BitBufferLocal  = bitbuffer::BitBufferLocal<TCapacity>;
 
/// Type alias in namespace \b alib.
using       BitWriter       = bitbuffer::BitWriter;
 
/// Type alias in namespace \b alib.
using       BitReader       = bitbuffer::BitReader;
 
/// Type alias in namespace \b alib.
using       ShiftOpRHS      = int;
 
}  // namespace [alib]