ALib C++ Library
Library Version: 2402 R1
Documentation generated by doxygen
Loading...
Searching...
No Matches
BitBufferBase Class Referenceabstract

Description:


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 and BitReader , this class is responsible for storing the data and transferring it to an integral-arrays, which may for example be written and read to and from std::[i/o]stream 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 not invoked automatically!. In contrast, it is the users' responsibility to invoke these methods (or only EnsureCapacity) prior to performing data insertions.
This behaviour is a design decision to maximize execution performance, hence rather a feature.

Own Implementations have to set field data when reallocating the internal buffer.

Definition at line 59 of file bitbuffer.hpp.

#include <bitbuffer.hpp>

Inheritance diagram for BitBufferBase:
[legend]

Inner Type Index:

class  Index
 

Public Type Index:

using TStorage = unsigned int
 

Public Method Index:

 BitBufferBase () noexcept
 
virtual ~BitBufferBase ()
 
virtual ALIB_API uinteger Capacity () const =0
 
char * CharStream (Index idx=Index(0, 0))
 
TStorageData () const
 
virtual ALIB_API bool EnsureCapacity (uinteger bitsRequired, BitBufferBase::Index index)=0
 
ALIB_API void FromLittleEndianEncoding (const Index &startIndex, const Index &endIndex)
 
TStorage GetWord (const Index &index) const
 
uinteger RemainingSize (const Index &idx) const
 
void SetWord (const Index &index, TStorage value)
 
ALIB_API Index Terminate (Index writerIndex)
 
ALIB_API void ToLittleEndianEncoding (const Index &startIndex, const Index &endIndex)
 
ALIB_API Index Unterminate (Index terminationIndex)
 

Type Definition Details:

◆ TStorage

using TStorage = unsigned int

The storage type of bit buffers. This is chosen as being unsigned int, which should be the "fasted" integral type for any compiler/platform combination.

Definition at line 64 of file bitbuffer.hpp.

Field Details:

◆ data

TStorage* data
protected

A pointer to the storage. Implementations of this abstract type have to set this field when reallocating the internal buffer.

Definition at line 312 of file bitbuffer.hpp.

Constructor(s) / Destructor Details::

◆ BitBufferBase()

BitBufferBase ( )
inlinenoexcept

Default Constructor (the only one).

Definition at line 318 of file bitbuffer.hpp.

◆ ~BitBufferBase()

virtual ~BitBufferBase ( )
inlinevirtual

Virtual destructor (does nothing, needed for abstract virtual class).

Definition at line 323 of file bitbuffer.hpp.

Method Details:

◆ Capacity()

virtual ALIB_API uinteger Capacity ( ) const
pure virtual

Virtual function to determine the (currently allocated) capacity.

Returns
The size of the internal storage in bits.

Implemented in BitBuffer, BitBufferMA, and BitBufferLocal< TCapacity >.

◆ CharStream()

char * CharStream ( Index idx = Index(0, 0))
inline

Returns the memory address of the internal storage word denoted by idx reinterpreted to C++ type char*.

Parameters
idxThe index of the word to point to. The bit position within this index is ignored.
Returns
A char pointer to the internal storage word the given index refers to.

Definition at line 397 of file bitbuffer.hpp.

◆ Data()

TStorage * Data ( ) const
inline

Returns the start of the internal storage.

Returns
A pointer to the data array provided by the decendent types.

Definition at line 385 of file bitbuffer.hpp.

◆ EnsureCapacity()

virtual ALIB_API bool EnsureCapacity ( uinteger bitsRequired,
BitBufferBase::Index index )
pure virtual

Virtual function to reserve buffer space by optionally increasing the buffer to enable the writing of the given bits.

Parameters
bitsRequiredThe number of bits required.
indexThe index to which the capacity is currently used.
Returns
true if the space is available or could be made available, false otherwise.

Implemented in BitBuffer, BitBufferMA, and BitBufferLocal< TCapacity >.

◆ FromLittleEndianEncoding()

void FromLittleEndianEncoding ( const Index & startIndex,
const Index & endIndex )

The counter-method to ToLittleEndianEncoding.

Parameters
startIndexThe first storage word to convert. (The bit position of the index is ignored).
endIndexThe first bit behind the storage to be converted. Hence, if the bit position within this argument is not 0, then the whole word that this index points to, will be converted. Otherwise it won't.

Definition at line 160 of file bitbuffer.cpp.

◆ GetWord()

TStorage GetWord ( const Index & index) const
inline

Returns the storage word at the given position

Parameters
indexThe index to read the word from. Note that the bit number in this value is ignored.
Returns
The word at the given index.

Definition at line 351 of file bitbuffer.hpp.

◆ RemainingSize()

uinteger RemainingSize ( const Index & idx) const
inline

Returns the number of remaining bits in this buffer in relation to a given index.

Parameters
idxAn actual writing/reading position.
Returns
The number of bits dived remaining in this buffer.

Definition at line 376 of file bitbuffer.hpp.

Here is the call graph for this function:

◆ SetWord()

void SetWord ( const Index & index,
TStorage value )
inline

Stores the given value at the given index.

Parameters
indexThe index to read the word at. Note that the bit number in this value is ignored.
valueThe value to store

Definition at line 364 of file bitbuffer.hpp.

◆ Terminate()

BitBufferBase::Index Terminate ( Index writerIndex)

Writes a termination bit of value 1 and lets this buffer's index point to the next buffer word.
Termination can be undone using the result index of this method with Unterminate. This method should be invoked prior to serializing a buffer and method Unterminate may be used after deserialization to continue writing to the buffer without creating a gap.

Parameters
writerIndexThe index to the last bit before termination.
Returns
The 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.

Definition at line 26 of file bitbuffer.cpp.

Here is the call graph for this function:

◆ ToLittleEndianEncoding()

void ToLittleEndianEncoding ( const Index & startIndex,
const Index & endIndex )

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 prior to 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 prior to using this method. and to pass the index returned by method Terminate as second parameter endIndex.
See also
Method FromLittleEndianEncoding.
Parameters
startIndexThe first storage word to convert. (The bit position of the index is ignored).
endIndexThe first bit behind the storage to be converted. Hence, if the bit position within this argument is not 0, then the whole word that this index points to, will be converted. Otherwise it won't.

Definition at line 125 of file bitbuffer.cpp.

Here is the call graph for this function:

◆ Unterminate()

BitBufferBase::Index Unterminate ( Index terminationIndex)

Removes the termination bit found in the word before given terminationIndex.

Parameters
terminationIndexThe index returned by previous invocation of method Terminate.
Returns
The index of the next bit to write to the now unterminated buffer.

Definition at line 44 of file bitbuffer.cpp.

Here is the call graph for this function:

The documentation for this class was generated from the following files: