ALib C++ Library
Library Version: 2312 R0
Documentation generated by doxygen
Public Methods | Private Static Fields | Private Fields | Protected Methods | Private Types | List of all members
BitWriter Class Reference

#include <bitbuffer.hpp>

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

Class Description


Writes bits into a BitBufferBase.

Definition at line 732 of file bitbuffer.hpp.

Public Methods

 BitWriter (BitBufferBase &buffer)
 
 BitWriter (BitBufferBase &buffer, const BitBufferBase::Index &index)
 
 ~BitWriter ()
 
void Flush ()
 
void Reset ()
 
void Reset (const BitBufferBase::Index &index)
 
template<typename TValue , bool TMaskValue = false>
void Write (ShiftOpRHS width, TValue value)
 
template<ShiftOpRHS TWidth, typename TIntegral , bool TMaskValue = false>
void Write (TIntegral value)
 
template<typename TIntegral >
void Write (TIntegral value)
 
- Public Methods inherited from BitRWBase
BitBufferBaseGetBuffer () const
 
BitBufferBase::Index GetIndex () const
 
uinteger RemainingSize () const
 
uinteger Usage () const
 

Private Static Fields

static constexpr ShiftOpRHS TStorageWidth = sizeof( TStorage ) * 8
 

Private Fields

BitBufferBase::TStorage word
 

Protected Methods

ALIB_API void writeUIntegral (uint16_t val)
 
ALIB_API void writeUIntegral (uint32_t val)
 
ALIB_API void writeUIntegral (uint64_t val)
 
ALIB_API void writeUIntegral (uint8_t val)
 
- Protected Methods inherited from BitRWBase
 BitRWBase (BitBufferBase &buffer)
 

Private Types

using TStorage = BitBufferBase::TStorage
 

Additional Inherited Members

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

Member Typedef Documentation

◆ TStorage

Local type alias (shortcut)

Definition at line 735 of file bitbuffer.hpp.

Constructor & Destructor Documentation

◆ BitWriter() [1/2]

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

◆ BitWriter() [2/2]

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

Here is the call graph for this function:

◆ ~BitWriter()

~BitWriter ( )
inline

Destructs a bit writer. Invokes Flush().

Definition at line 770 of file bitbuffer.hpp.

Here is the call graph for this function:

Member Function Documentation

◆ Flush()

void Flush ( )
inline

Writes the last word of bits into the underlying buffer. This method has to be called prior to writing the buffer to a file or similar. The method is automatically invoked on destruction.

Definition at line 798 of file bitbuffer.hpp.

Here is the call graph for this function:

◆ Reset() [1/2]

void Reset ( )
inline

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

Definition at line 776 of file bitbuffer.hpp.

◆ Reset() [2/2]

void 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 786 of file bitbuffer.hpp.

Here is the call graph for this function:

◆ Write() [1/3]

void Write ( ShiftOpRHS  width,
TValue  value 
)

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

Note
Internally, different template functions selected with std::enable_if for different integral types.
See also
A method that uses a template parameter for the number of bits to write, is 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.

◆ Write() [2/3]

void Write ( TIntegral  value)

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

Note
Internally, different template functions selected with std::enable_if for the different integral types.
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() [3/3]

void Write ( TIntegral  value)

Writes the given integral value to the stream by writing lower values with smaller sizes, due to the general assumption that lower values are more frequent and the average written size is less than the full size, despite the overhead needed to write information about how a value is encoded.

The endcoding for unsigned integrals is as follows:

  • For byte value type, a single bit '0' is written if the value is below 8, followed by the 3 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 number 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 of-course that small numbers, negative or positive, remain small in respect to their bitwise representation.

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

Parameters
valueThe value to write.

◆ writeUIntegral() [1/4]

void writeUIntegral ( uint16_t  val)
protected

Internal method that writes a unsigned 16-bit value.

Parameters
valThe value to write.

Definition at line 207 of file bitbuffer.cpp.

◆ writeUIntegral() [2/4]

void writeUIntegral ( uint32_t  val)
protected

Internal method that writes a unsigned 32-bit value.

Parameters
valThe value to write.

Definition at line 219 of file bitbuffer.cpp.

◆ writeUIntegral() [3/4]

void writeUIntegral ( uint64_t  val)
protected

Internal method that writes a unsigned 64-bit value.

Parameters
valThe value to write.

Definition at line 229 of file bitbuffer.cpp.

◆ writeUIntegral() [4/4]

void writeUIntegral ( uint8_t  val)
protected

Internal method that writes a unsigned 8-bit value.

Parameters
valThe value to write.

Definition at line 195 of file bitbuffer.cpp.

Member Data Documentation

◆ TStorageWidth

constexpr ShiftOpRHS TStorageWidth = sizeof( TStorage ) * 8
staticconstexprprivate

The width in bits of the storage type which is of type int. Consequently, this evaluates to 32 or 64 on most common platforms.

Definition at line 742 of file bitbuffer.hpp.

◆ word

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

Definition at line 738 of file bitbuffer.hpp.


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