ALib C++ Library
Library Version: 2510 R0
Documentation generated by doxygen
Loading...
Searching...
No Matches
alib::bitbuffer::BitWriter Class Reference

Description:

Writes bits into a BitBufferBase.

Definition at line 652 of file bitbuffer.inl.

Inheritance diagram for alib::bitbuffer::BitWriter:
[legend]
Collaboration diagram for alib::bitbuffer::BitWriter:
[legend]

Public Method Index:

 BitWriter (BitBufferBase &buffer)
 
 BitWriter (BitBufferBase &buffer, const BitBufferBase::Index &index)
 
 ~BitWriter ()
 Destructs a bit writer. Invokes Flush().
 
void Flush ()
 
void Reset ()
 Resets the internal index of this writer to the start of the bit buffer.
 
void Reset (const BitBufferBase::Index &index)
 
template<typename TValue, bool TMaskValue = false>
requires ( std::integral<TValue> && ( sizeof(TValue) <= sizeof(TStorage) ) )
void Write (lang::ShiftOpRHS width, TValue value)
 
template<typename TValue, bool TMaskValue = false>
requires ( std::integral<TValue> && ( sizeof(TValue) > sizeof(TStorage) ) )
void Write (lang::ShiftOpRHS width, TValue value)
 
template<ShiftOpRHS TWidth, typename TIntegral, bool TMaskValue = false>
void Write (TIntegral value)
 
template<typename TSIntegral>
requires ( std::signed_integral<TSIntegral> && !std::same_as< TSIntegral, bool> )
void Write (TSIntegral value)
 
template<typename TUIntegral>
requires ( std::unsigned_integral<TUIntegral> && !std::same_as< TUIntegral, bool> )
void Write (TUIntegral value)
 
- Public Method Index: inherited from alib::bitbuffer::BitRWBase
BitBufferBaseGetBuffer () const
 
BitBufferBase::Index GetIndex () const
 
uinteger RemainingSize () const
 
uinteger Usage () const
 

Protected Method Index:

ALIB_DLL void writeUIntegral (uint16_t value)
 
ALIB_DLL void writeUIntegral (uint32_t value)
 
ALIB_DLL void writeUIntegral (uint64_t value)
 
ALIB_DLL void writeUIntegral (uint8_t value)
 
- Protected Method Index: inherited from alib::bitbuffer::BitRWBase
 BitRWBase (BitBufferBase &buffer)
 

Private Type Index:

using TStorage = BitBufferBase::TStorage
 Local type alias (shortcut)
 

Private Field Index:

BitBufferBase::TStorage word
 The current word, which is partly written and not stored in buffer, yet.
 

Additional Inherited Members

- Protected Field Index: inherited from alib::bitbuffer::BitRWBase
BitBufferBasebb
 The bit buffer to write into. Provided on construction.
 
BitBufferBase::Index idx
 The current reading/writing index within bb.
 

Type Definition Details:

◆ TStorage

Local type alias (shortcut)

Definition at line 655 of file bitbuffer.inl.

Field Details:

◆ word

BitBufferBase::TStorage alib::bitbuffer::BitWriter::word
private

The current word, which is partly written and not stored in buffer, yet.

Definition at line 658 of file bitbuffer.inl.

Constructor(s) / Destructor Details:

◆ BitWriter() [1/2]

alib::bitbuffer::BitWriter::BitWriter ( BitBufferBase & buffer)
inlineexplicit

Constructs a bit writer operating on the given bit buffer.

Parameters
bufferThe buffer to write to (starting at the beginning).

Definition at line 663 of file bitbuffer.inl.

Here is the call graph for this function:

◆ BitWriter() [2/2]

alib::bitbuffer::BitWriter::BitWriter ( BitBufferBase & buffer,
const BitBufferBase::Index & index )
inlineexplicit

Constructs a bit writer operating on the given bit buffer, starting to write at the given Index.

Parameters
bufferThe buffer to write to.
indexAn index providing the postion of the first bit to (over-) write in buffer.

Definition at line 674 of file bitbuffer.inl.

Here is the call graph for this function:

◆ ~BitWriter()

alib::bitbuffer::BitWriter::~BitWriter ( )
inline

Destructs a bit writer. Invokes Flush().

Definition at line 682 of file bitbuffer.inl.

Here is the call graph for this function:

Method Details:

◆ Flush()

void alib::bitbuffer::BitWriter::Flush ( )
inline

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.

Definition at line 706 of file bitbuffer.inl.

◆ Reset() [1/2]

void alib::bitbuffer::BitWriter::Reset ( )
inline

Resets the internal index of this writer to the start of the bit buffer.

Definition at line 688 of file bitbuffer.inl.

◆ Reset() [2/2]

void alib::bitbuffer::BitWriter::Reset ( const BitBufferBase::Index & index)
inline

Resets the internal index of this writer to the given one.

Parameters
indexThe position of the next bit in the buffer to write to.

Definition at line 696 of file bitbuffer.inl.

Here is the call graph for this function:

◆ Write() [1/5]

template<typename TValue, bool TMaskValue = false>
requires ( std::integral<TValue> && ( sizeof(TValue) <= sizeof(TStorage) ) )
void alib::bitbuffer::BitWriter::Write ( lang::ShiftOpRHS width,
TValue value )
inline

Writes the given integral value with the given number of bits to the stream.

Note
Two overloads of this method, selected with keyword requires, for different integral types exist. This is version 1/2 which requires that the given value type is smaller than or equal to the storage type.
See also
A method that uses a template parameter for the number of bits to write, is available with Write<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.
Template Parameters
TValueThe integral type of the value to write. (Deduced from parameter value.)
TMaskValueDetermines if bits beyond width of given value may be set and have to be masked out. Defaults to false.
Parameters
widthThe number of bits in value.
valueThe value to write.

Definition at line 838 of file bitbuffer.inl.

Here is the call graph for this function:

◆ Write() [2/5]

template<typename TValue, bool TMaskValue = false>
requires ( std::integral<TValue> && ( sizeof(TValue) > sizeof(TStorage) ) )
void alib::bitbuffer::BitWriter::Write ( lang::ShiftOpRHS width,
TValue value )
inline

Writes the given integral value with the given number of bits to the stream.

Note
Two overloads of this method, selected with keyword requires, for different integral types exist. This is version 2/2 which requires that the given value type is greater than as the storage type.
Template Parameters
TValueThe integral type of the value to write. (Deduced from parameter value.)
TMaskValueDetermines if bits beyond width of given value may be set and have to be masked out. Defaults to false.
Parameters
widthThe number of bits in value.
valueThe value to write.

Definition at line 880 of file bitbuffer.inl.

Here is the call graph for this function:

◆ Write() [3/5]

template<ShiftOpRHS TWidth, typename TIntegral, bool TMaskValue = false>
void alib::bitbuffer::BitWriter::Write ( TIntegral value)

Writes the given integral value with the given number of bits to the stream.

Note
Internally, different template functions selected with keyword requires for the different integral types exist.
See also
This method uses a template parameter for the number of bits to write. A slightly slower, non-templated version is available with Write<TValue, TMaskValue>( ShiftOpRHS, TValue) which is to be used when the value is determined only at run-time.
Template Parameters
TWidthThe number of bits in value to write.
TValueThe type of value to write. (Deduced from parameter value.)
TMaskValueDetermines if bits beyond width of given value may be set and have to be masked out. Defaults to false.
Parameters
valueThe value to write.

◆ Write() [4/5]

template<typename TSIntegral>
requires ( std::signed_integral<TSIntegral> && !std::same_as< TSIntegral, bool> )
void alib::bitbuffer::BitWriter::Write ( TSIntegral value)
inline

Converts the given 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.

The conversion hence is as follows: unsigned = signed >= 0 ? signed * 2 : ( (-signed -1 ) * 2 ) | 1

Then calls Write<TUIntegral>.

Template Parameters
TSIntegralThe type of the given signed integral.
Parameters
valueThe value to write.

Definition at line 978 of file bitbuffer.inl.

Here is the call graph for this function:

◆ Write() [5/5]

template<typename TUIntegral>
requires ( std::unsigned_integral<TUIntegral> && !std::same_as< TUIntegral, bool> )
void alib::bitbuffer::BitWriter::Write ( TUIntegral value)
inline

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 unsigned integrals is as follows:

  • For byte value types, a single bit '0' is written if the value is below 8, followed by the three bits containing the value. Otherwise, a single bit '1' 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.

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.

The conversion hence is as follows: unsigned = signed >= 0 ? signed * 2 : ( (-signed -1 ) * 2 ) | 1

Template Parameters
TUIntegralThe type of the given unsigned integral.
Parameters
valueThe value to write.

Definition at line 959 of file bitbuffer.inl.

Here is the call graph for this function:

◆ writeUIntegral() [1/4]

void alib::bitbuffer::BitWriter::writeUIntegral ( uint16_t value)
protected

Internal method that writes a unsigned 16-bit value.

Parameters
valueThe value to write.

Definition at line 212 of file bitbuffer.cpp.

Here is the call graph for this function:

◆ writeUIntegral() [2/4]

void alib::bitbuffer::BitWriter::writeUIntegral ( uint32_t value)
protected

Internal method that writes a unsigned 32-bit value.

Parameters
valueThe value to write.

Definition at line 224 of file bitbuffer.cpp.

Here is the call graph for this function:

◆ writeUIntegral() [3/4]

void alib::bitbuffer::BitWriter::writeUIntegral ( uint64_t value)
protected

Internal method that writes a unsigned 64-bit value.

Parameters
valueThe value to write.

Definition at line 234 of file bitbuffer.cpp.

Here is the call graph for this function:

◆ writeUIntegral() [4/4]

void alib::bitbuffer::BitWriter::writeUIntegral ( uint8_t value)
protected

Internal method that writes a unsigned 8-bit value.

Parameters
valueThe value to write.

Definition at line 200 of file bitbuffer.cpp.

Here is the call graph for this function:

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