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) before performing data insertions.
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.

Definition at line 34 of file bitbuffer.inl.

Inheritance diagram for alib::bitbuffer::BitBufferBase:

[legend]

Inner Type Index:
class	Index

Public Type Index:
using	TStorage = unsigned int

Public Method Index:
	BitBufferBase () noexcept
	Default Constructor (the only one).

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

virtual ALIB_DLL uinteger	Capacity () const =0

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

TStorage *	Data () const

virtual ALIB_DLL bool	EnsureCapacity (uinteger bitsRequired, BitBufferBase::Index index)=0

ALIB_DLL 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_DLL Index	Terminate (Index writerIndex)

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

ALIB_DLL Index	Unterminate (Index terminationIndex)

Protected Field Index:
TStorage *	data

Type Definition Details:

◆ TStorage

using alib::bitbuffer::BitBufferBase::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 39 of file bitbuffer.inl.

Field Details:

◆ data

TStorage* alib::bitbuffer::BitBufferBase::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 259 of file bitbuffer.inl.

Constructor(s) / Destructor Details:

◆ BitBufferBase()

alib::bitbuffer::BitBufferBase::BitBufferBase ( )

inlinenoexcept

Default Constructor (the only one).

Definition at line 265 of file bitbuffer.inl.

◆ ~BitBufferBase()

virtual alib::bitbuffer::BitBufferBase::~BitBufferBase ( )

inlinevirtual

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

Definition at line 270 of file bitbuffer.inl.

Method Details:

◆ Capacity()

virtual ALIB_DLL uinteger alib::bitbuffer::BitBufferBase::Capacity ( ) const

pure virtual

Virtual function to determine the (currently allocated) capacity.

Returns: The size of the internal storage in bits.

Implemented in alib::bitbuffer::BitBuffer, alib::bitbuffer::BitBufferLocal< TCapacity >, and alib::bitbuffer::BitBufferMA.

◆ CharStream()

char * alib::bitbuffer::BitBufferBase::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 340 of file bitbuffer.inl.

◆ Data()

TStorage * alib::bitbuffer::BitBufferBase::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 328 of file bitbuffer.inl.

◆ EnsureCapacity()

virtual ALIB_DLL bool alib::bitbuffer::BitBufferBase::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 space is available or could be made available, false otherwise.

Implemented in alib::bitbuffer::BitBuffer, alib::bitbuffer::BitBufferLocal< TCapacity >, and alib::bitbuffer::BitBufferMA.

◆ FromLittleEndianEncoding()

void alib::bitbuffer::BitBufferBase::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 164 of file bitbuffer.cpp.

◆ GetWord()

TStorage alib::bitbuffer::BitBufferBase::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 298 of file bitbuffer.inl.

◆ RemainingSize()

uinteger alib::bitbuffer::BitBufferBase::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 319 of file bitbuffer.inl.

Here is the call graph for this function:

◆ SetWord()

void alib::bitbuffer::BitBufferBase::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 309 of file bitbuffer.inl.

◆ Terminate()

BitBufferBase::Index alib::bitbuffer::BitBufferBase::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 before 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 37 of file bitbuffer.cpp.

Here is the call graph for this function:

◆ ToLittleEndianEncoding()

void alib::bitbuffer::BitBufferBase::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 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 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 131 of file bitbuffer.cpp.

Here is the call graph for this function:

◆ Unterminate()

BitBufferBase::Index alib::bitbuffer::BitBufferBase::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 55 of file bitbuffer.cpp.

Here is the call graph for this function:

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

Description:

Inner Type Index:

Public Type Index:

Public Method Index:

Protected Field Index:

Type Definition Details:

◆ TStorage

Field Details:

◆ data

Constructor(s) / Destructor Details:

◆ BitBufferBase()

◆ ~BitBufferBase()

Method Details:

◆ Capacity()

◆ CharStream()

◆ Data()

◆ EnsureCapacity()

◆ FromLittleEndianEncoding()

◆ GetWord()

◆ RemainingSize()

◆ SetWord()

◆ Terminate()

◆ ToLittleEndianEncoding()

◆ Unterminate()