Versatile Bitstream implementation supporting: More...

#include <bit_stream.hpp>

Collaboration diagram for jau::io::Bitstream:

Public Types
using	size_type = jau::io::ByteStream::size_type
	uint64_t size data type, bit position and count

Public Member Functions
	Bitstream (std::unique_ptr< ByteStream > &&stream, ioaccess_t access)

data_type	bitCache ()
	Returns the 64-bit MaxBitCacheSize cache buffer value.

constexpr jau::nsize_t	bitCacheSizeRead () const noexcept
	Returns filled read bit-cache-size, i.e.

constexpr_cxx23 lb_endian_t	byteOrder () const noexcept
	Returns endian byte-order of stream storage.

ByteStream &	byteStream ()
	Returns the used underlying ByteStream.

constexpr jau::nsize_t	cachedBitCount () const noexcept
	Returns number of cached bits.

constexpr jau::nsize_t	cachedBitPos () const noexcept
	Return the next cached bit position.

constexpr bool	canWrite () const noexcept
	Returns true in case stream is in write mode, false if in read mode.

void	close () noexcept
	Closing the underlying stream, implies `flush()`.

size_type	flush () noexcept
	Synchronizes underlying ByteStream output stream operations in writeMode(), or does nothing.

constexpr ioaccess_t	ioaccess () const noexcept
	Returns ioaccess_t stream mode.

size_type	mark () const noexcept
	Returns the `markpos` set via setMark() or ByteStream::npos if unset.

uint64_t	markReadLimit () const noexcept
	Returns the `readLimit` set via setMark().

constexpr_cxx23 iomode_t	mode () const noexcept

size_type	position () const noexcept
	Returns the bit position in the stream.

int	readBit () noexcept
	Read incoming bit in least-significant-bit (LSB) first order.

jau::nsize_t	readBits64 (jau::nsize_t n, data_type &r) noexcept
	Read incoming bits in least-significant-bit (LSB) first order.

bool	readSInt16 (int16_t &bits) noexcept
	Read `int16_t`.

bool	readU32 (uint32_t &bits) noexcept
	Read `uint32_t`.

bool	readUInt16 (uint16_t &bits) noexcept
	Read `uint16_t`.

bool	readUInt8 (uint8_t &bits) noexcept
	Read incoming `uint8_t` via readBits32().

size_type	seek (size_type newPos) noexcept
	Sets this stream's bit position.

bool	seekMark () noexcept
	Seeks stream bit-position to `markpos` as set via setMark().

bool	setAccess (ioaccess_t access) noexcept
	Changes the access-mode to write or read and resets position and cache to zero.

bool	setImmutable () noexcept
	Changes the write-mode to read, sets the underlying ByteStream to read-only and resets position and cache to zero.

bool	setMark (size_type readLimit) noexcept
	Set `markpos` to current bit-position, allowing the stream to be seekMark().

size_type	skip (size_type n) noexcept
	Skip given number of bits.

std::string	toString () const

std::string	toStringImpl () const

bool	writeBit (uint8_t bit) noexcept
	Write given bit in least-significant-bit (LSB) first order.

jau::nsize_t	writeBits64 (jau::nsize_t n, data_type bits) noexcept
	Write given bits in least-significant-bit (LSB) first order.

bool	writeU32 (uint32_t bits) noexcept
	Write `uint32_t`.

bool	writeUInt16 (uint16_t bits) noexcept
	Write `uint16_t`

bool	writeUInt8 (uint8_t bits) noexcept
	Write the given 8 bits via `writeBits31(int, int)`.

Static Public Member Functions
static std::string	toHexBinaryString (uint64_t v, unsigned bitCount=MaxBitCacheSize)

Static Public Attributes
static constexpr jau::nsize_t	MaxBitCacheSize = sizeof(data_type)*CHAR_BIT
	Maximum read bitCacheSizeRead() and fixed 64-bit write cache size.

static constexpr size_type	npos = jau::io::ByteStream::npos
	Invalid position constant, denoting unset mark() or invalid position.

Detailed Description

Versatile Bitstream implementation supporting:

Utilize I/O operations on I/O streams, buffers and arrays
Uses least-significant-bit (lsb) first addressing and order for bit-operations
Linear bit R/W operations
Bulk 64-bit R/W bit-operations
Bulk data-type operations w/ endian conversion
Allow mark/reset and switching streams and input/output mode
Optimized bulk-operations

Definition at line 64 of file bit_stream.hpp.

Member Typedef Documentation

◆ size_type

using jau::io::Bitstream::size_type = jau::io::ByteStream::size_type

uint64_t size data type, bit position and count

Definition at line 71 of file bit_stream.hpp.

Constructor & Destructor Documentation

◆ Bitstream()

jau::io::Bitstream::Bitstream	(	std::unique_ptr< ByteStream > &&	stream,
		ioaccess_t	access )

inline

Parameters

stream	input and/or output stream
access	ioaccess_t::read for read-access and ioaccess_t::write for read-access

Exceptions

IllegalArgumentError if requested writeMode doesn't match stream's ByteStream::canRead() and ByteStream::canWrite().

Definition at line 105 of file bit_stream.hpp.

Member Function Documentation

◆ byteStream()

ByteStream & jau::io::Bitstream::byteStream ( )

inline

Returns the used underlying ByteStream.

Definition at line 169 of file bit_stream.hpp.

Here is the caller graph for this function:

◆ mode()

constexpr_cxx23 iomode_t jau::io::Bitstream::mode ( ) const

inlinenoexcept

Definition at line 171 of file bit_stream.hpp.

◆ setAccess()

bool jau::io::Bitstream::setAccess ( ioaccess_t access )

inlinenodiscardnoexcept

Changes the access-mode to write or read and resets position and cache to zero.

If the previous stream was in ioaccess_t::write mode, flush() is being called.

Certain ByteStream implementations may not allow random rewinding of the stream,

Parameters

writeMode new access-mode

Returns: false if requested access doesn't match stream's ByteStream::canRead() and ByteStream::canWrite() - or flush() failed, otherwise true

Definition at line 184 of file bit_stream.hpp.

Here is the caller graph for this function:

◆ setImmutable()

bool jau::io::Bitstream::setImmutable ( )

inlinenodiscardnoexcept

Changes the write-mode to read, sets the underlying ByteStream to read-only and resets position and cache to zero.

If the previous stream was in ioaccess_t::write mode, flush() is being called.

Certain ByteStream implementations may not allow random rewinding of the stream,

Returns: false if requested ioaccess_t::read doesn't match stream's ByteStream::canRead() - or flush() failed, otherwise true

Definition at line 208 of file bit_stream.hpp.

Here is the caller graph for this function:

◆ byteOrder()

constexpr_cxx23 lb_endian_t jau::io::Bitstream::byteOrder ( ) const

inlinenoexcept

Returns endian byte-order of stream storage.

Only affects multi-byte r/w operations, e.g. readU16(), writeU16(), etc.

Definition at line 231 of file bit_stream.hpp.

Here is the caller graph for this function:

◆ canWrite()

bool jau::io::Bitstream::canWrite ( ) const

inlineconstexprnoexcept

Returns true in case stream is in write mode, false if in read mode.

Definition at line 234 of file bit_stream.hpp.

Here is the caller graph for this function:

◆ ioaccess()

ioaccess_t jau::io::Bitstream::ioaccess ( ) const

inlineconstexprnoexcept

Returns ioaccess_t stream mode.

Definition at line 236 of file bit_stream.hpp.

◆ close()

void jau::io::Bitstream::close ( )

inlinenoexcept

Closing the underlying stream, implies flush().

Implementation will null the stream references, hence setStream(Object) must be called before re-using instance.

If the closed stream was in output mode, flush() is being called.

Exceptions

IOException

Definition at line 251 of file bit_stream.hpp.

◆ flush()

size_type jau::io::Bitstream::flush ( )

inlinenoexcept

Synchronizes underlying ByteStream output stream operations in writeMode(), or does nothing.

Method also flushes incomplete bytes to the underlying ByteStream and hence skips to the next byte position.

Returns: npos caused by writing failure, otherwise one if pending bit-buffer was written or zero for none.

Definition at line 265 of file bit_stream.hpp.

Here is the caller graph for this function:

◆ setMark()

bool jau::io::Bitstream::setMark ( size_type readLimit )

inlinenodiscardnoexcept

Set markpos to current bit-position, allowing the stream to be seekMark().

seek() will clear markpos if > newPos.

For implementations where seek() doesn't allow random rewinding of the stream, setMark() will allow rewinding back to markpos if not exceeding readLimit.

Parameters

readlimit maximum number of bytes able to read before invalidating the markpos.

Returns: true if marks is set successfully, otherwise false

Definition at line 291 of file bit_stream.hpp.

Here is the caller graph for this function:

◆ mark()

size_type jau::io::Bitstream::mark ( ) const

inlinenoexcept

Returns the markpos set via setMark() or ByteStream::npos if unset.

Definition at line 301 of file bit_stream.hpp.

◆ markReadLimit()

uint64_t jau::io::Bitstream::markReadLimit ( ) const

inlinenoexcept

Returns the readLimit set via setMark().

If unset either 0 or implicit limit.

Definition at line 304 of file bit_stream.hpp.

◆ seekMark()

bool jau::io::Bitstream::seekMark ( )

inlinenodiscardnoexcept

Seeks stream bit-position to markpos as set via setMark().

markpos is kept, hence seekMark() can be called multiple times.

Returns: true if successful (incl eofbit), otherwise false with unchanged position due to I/O failure (iostate::fail set) or setMark() not set.

Definition at line 314 of file bit_stream.hpp.

Here is the caller graph for this function:

◆ bitCacheSizeRead()

jau::nsize_t jau::io::Bitstream::bitCacheSizeRead ( ) const

inlineconstexprnoexcept

Returns filled read bit-cache-size, i.e.

up to 64-bit MaxBitCacheSize reading.

See also: MaxBitCacheSize; cachedBitCount(); position()

Definition at line 329 of file bit_stream.hpp.

◆ cachedBitCount()

jau::nsize_t jau::io::Bitstream::cachedBitCount ( ) const

inlineconstexprnoexcept

Returns number of cached bits.

Read operation
- Number of bits cached before next up-to 64-bit-read when zero is reached, flipping over to bitCacheSizeRead()
- Counting down
- Range (bitCacheSizeRead()..0]
- bitCacheSizeRead() is set when zero is reached and cache is filled
Write operation
- Number of bits cached before next 64-bit MaxBitCacheSize write when 64-bits limit is reached, flipping over to 0
- Counting up
- Range [0..MaxBitCacheSize)
- bitCacheSizeRead() is set to cachedBitCount() after writing

See also: MaxBitCacheSize; bitCacheSizeRead(); bitCache(); position()

Definition at line 351 of file bit_stream.hpp.

Here is the caller graph for this function:

◆ cachedBitPos()

jau::nsize_t jau::io::Bitstream::cachedBitPos ( ) const

inlineconstexprnoexcept

Return the next cached bit position.

See also: MaxBitCacheSize; bitCacheSizeRead(); cachedBitCount()

Definition at line 359 of file bit_stream.hpp.

Here is the caller graph for this function:

◆ bitCache()

data_type jau::io::Bitstream::bitCache ( )

inline

Returns the 64-bit MaxBitCacheSize cache buffer value.

See also: MaxBitCacheSize; bitCacheSizeRead(); cachedBitCount(); position()

Definition at line 374 of file bit_stream.hpp.

◆ position()

size_type jau::io::Bitstream::position ( ) const

inlinenoexcept

Returns the bit position in the stream.

See also: MaxBitCacheSize; bitCacheSizeRead(); cachedBitCount()

Definition at line 382 of file bit_stream.hpp.

Here is the caller graph for this function:

◆ seek()

size_type jau::io::Bitstream::seek ( size_type newPos )

inlinenodiscardnoexcept

Sets this stream's bit position.

A set mark is cleared.

Known supporting implementation is ByteBufferStream and ByteArrayStream.

Parameters

newPos desired absolute bit-position

Returns: resulting bit-position if successful (incl EOF) or npos otherwise having an unchanged position().

Definition at line 404 of file bit_stream.hpp.

Here is the caller graph for this function:

◆ skip()

size_type jau::io::Bitstream::skip ( size_type n )

inlinenodiscardnoexcept

Skip given number of bits.

Parameters

n	number of bits to skip

Returns: actual skipped bits

Definition at line 431 of file bit_stream.hpp.

Here is the caller graph for this function:

◆ readBit()

int jau::io::Bitstream::readBit ( )

inlinenodiscardnoexcept

Read incoming bit in least-significant-bit (LSB) first order.

Returns: the read bit or -1 if end-of-stream is reached.

See also: msbFirst()

Definition at line 487 of file bit_stream.hpp.

Here is the caller graph for this function:

◆ writeBit()

bool jau::io::Bitstream::writeBit ( uint8_t bit )

inlinenodiscardnoexcept

Write given bit in least-significant-bit (LSB) first order.

Parameters

bit

Returns: true if successful, otherwise false

See also: msbFirst()

Definition at line 511 of file bit_stream.hpp.

Here is the caller graph for this function:

◆ readBits64()

jau::nsize_t jau::io::Bitstream::readBits64	(	jau::nsize_t	n,
		data_type &	r )

inlinenodiscardnoexcept

Read incoming bits in least-significant-bit (LSB) first order.

Parameters

n	number of bits, maximum 64 bits

Returns: the number of bits read. Zero for none, including errors.

Definition at line 530 of file bit_stream.hpp.

Here is the caller graph for this function:

◆ writeBits64()

jau::nsize_t jau::io::Bitstream::writeBits64	(	jau::nsize_t	n,
		data_type	bits )

inlinenodiscardnoexcept

Write given bits in least-significant-bit (LSB) first order.

Parameters

n	number of bits, maximum 64 bits
bits	the bits to write

Returns: the number of bits written. Zero for none, including errors.

Definition at line 580 of file bit_stream.hpp.

Here is the caller graph for this function:

◆ readUInt8()

bool jau::io::Bitstream::readUInt8 ( uint8_t & bits )

inlinenodiscardnoexcept

Read incoming uint8_t via readBits32().

In case of a int8_t 2-complement signed value, simply cast the result.

Parameters

bits	reference to result

Returns: true if successful, otherwise false

Definition at line 638 of file bit_stream.hpp.

◆ writeUInt8()

bool jau::io::Bitstream::writeUInt8 ( uint8_t bits )

inlinenodiscardnoexcept

Write the given 8 bits via writeBits31(int, int).

Returns: true if successful, otherwise false

Definition at line 654 of file bit_stream.hpp.

◆ readUInt16()

bool jau::io::Bitstream::readUInt16 ( uint16_t & bits )

inlinenodiscardnoexcept

Read uint16_t.

If stream byteOrder() != lb_endian_t::native, result is bytes swapped via jau::bswap().

Parameters

bits	reference to result

Returns: true if successful, otherwise false

Definition at line 669 of file bit_stream.hpp.

Here is the caller graph for this function:

◆ readSInt16()

bool jau::io::Bitstream::readSInt16 ( int16_t & bits )

inlinenodiscardnoexcept

Read int16_t.

If stream byteOrder() != lb_endian_t::native, result is bytes swapped via jau::bswap().

Parameters

bits	reference to result

Returns: true if successful, otherwise false

Definition at line 690 of file bit_stream.hpp.

◆ writeUInt16()

bool jau::io::Bitstream::writeUInt16 ( uint16_t bits )

inlinenodiscardnoexcept

Write uint16_t

If stream byteOrder() != lb_endian_t::native, result is bytes swapped via jau::bswap().

Parameters

bits	data to write

Returns: true if successful, otherwise false

Definition at line 699 of file bit_stream.hpp.

◆ readU32()

bool jau::io::Bitstream::readU32 ( uint32_t & bits )

inlinenodiscardnoexcept

Read uint32_t.

If stream byteOrder() != lb_endian_t::native, result is bytes swapped via jau::bswap().

Parameters

bits	reference to result

Returns: true if successful, otherwise false

Definition at line 721 of file bit_stream.hpp.

◆ writeU32()

bool jau::io::Bitstream::writeU32 ( uint32_t bits )

inlinenodiscardnoexcept

Write uint32_t.

If stream byteOrder() != lb_endian_t::native, result is bytes swapped via jau::bswap().

Parameters

bits	data to write

Returns: true if successful, otherwise false

Definition at line 747 of file bit_stream.hpp.

◆ toString()

std::string jau::io::Bitstream::toString ( ) const

inline

Definition at line 762 of file bit_stream.hpp.

Here is the caller graph for this function:

◆ toStringImpl()

std::string jau::io::Bitstream::toStringImpl ( ) const

inline

Definition at line 766 of file bit_stream.hpp.

Here is the caller graph for this function:

◆ toHexBinaryString()

static std::string jau::io::Bitstream::toHexBinaryString	(	uint64_t	v,
		unsigned	bitCount = MaxBitCacheSize )

inlinestatic

Definition at line 781 of file bit_stream.hpp.

Here is the caller graph for this function:

Member Data Documentation

◆ npos

size_type jau::io::Bitstream::npos = jau::io::ByteStream::npos

staticconstexpr

Invalid position constant, denoting unset mark() or invalid position.

Value: std::numeric_limits<size_type>::max()

Definition at line 74 of file bit_stream.hpp.

◆ MaxBitCacheSize

jau::nsize_t jau::io::Bitstream::MaxBitCacheSize = sizeof(data_type)*CHAR_BIT

staticconstexpr

Maximum read bitCacheSizeRead() and fixed 64-bit write cache size.

Definition at line 77 of file bit_stream.hpp.

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

include/jau/io/bit_stream.hpp

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

◆ size_type

Constructor & Destructor Documentation

◆ Bitstream()

Member Function Documentation

◆ byteStream()

◆ mode()

◆ setAccess()

◆ setImmutable()

◆ byteOrder()

◆ canWrite()

◆ ioaccess()

◆ close()

◆ flush()

◆ setMark()

◆ mark()

◆ markReadLimit()

◆ seekMark()

◆ bitCacheSizeRead()

◆ cachedBitCount()

◆ cachedBitPos()

◆ bitCache()

◆ position()

◆ seek()

◆ skip()

◆ readBit()

◆ writeBit()

◆ readBits64()

◆ writeBits64()

◆ readUInt8()

◆ writeUInt8()

◆ readUInt16()

◆ readSInt16()

◆ writeUInt16()

◆ readU32()

◆ writeU32()

◆ toString()

◆ toStringImpl()

◆ toHexBinaryString()

Member Data Documentation

◆ npos

◆ MaxBitCacheSize