#include <bitbuffer.hpp>

Inheritance diagram for BitBufferBase:

Class 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 63 of file bitbuffer.hpp.

Public Types
using	TStorage = unsigned int

Inner Classes
class	Index

Public Methods
	BitBufferBase () noexcept

virtual	~BitBufferBase ()

virtual ALIB_API uinteger	Capacity () const =0

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

TStorage *	Data () 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)

Protected Fields
TStorage *	data

Member Typedef Documentation

◆ 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 68 of file bitbuffer.hpp.

Constructor & Destructor Documentation

◆ BitBufferBase()

BitBufferBase ( )

inlinenoexcept

Default Constructor (the only one).

Definition at line 333 of file bitbuffer.hpp.

◆ ~BitBufferBase()

virtual ~BitBufferBase ( )

inlinevirtual

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

Definition at line 338 of file bitbuffer.hpp.

Member Function Documentation

◆ 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 BitBufferLocal< TCapacity >, BitBufferMA, and BitBuffer.

◆ 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

idx	The 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 412 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 400 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

bitsRequired	The number of bits required.
index	The index to which the capacity is currently used.

Returns: true if the the space is available or could be made available, false otherwise.

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

◆ FromLittleEndianEncoding()

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

The counter-method to ToLittleEndianEncoding.

Parameters

startIndex	The first storage word to convert. (The bit position of the index is ignored).
endIndex	The 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 157 of file bitbuffer.cpp.

◆ GetWord()

TStorage GetWord ( const Index & index ) const

inline

Returns the storage word at the given position

Parameters

index The 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 366 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

idx	An actual writing/reading position.

Returns: The number of bits dived remaining in this buffer.

Definition at line 391 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

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

Definition at line 379 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

writerIndex The 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

startIndex	The first storage word to convert. (The bit position of the index is ignored).
endIndex	The 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 122 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

terminationIndex The 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:

Member Data Documentation

◆ 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 327 of file bitbuffer.hpp.

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

Class Description

Public Types

Inner Classes

Public Methods

Protected Fields

Member Typedef Documentation

◆ TStorage

Constructor & Destructor Documentation

◆ BitBufferBase()

◆ ~BitBufferBase()

Member Function Documentation

◆ Capacity()

◆ CharStream()

◆ Data()

◆ EnsureCapacity()

◆ FromLittleEndianEncoding()

◆ GetWord()

◆ RemainingSize()

◆ SetWord()

◆ Terminate()

◆ ToLittleEndianEncoding()

◆ Unterminate()

Member Data Documentation

◆ data