General-purpose memory buffer with bit access. More...

#include <tsBuffer.h>

Inheritance diagram for ts::Buffer:

Public Member Functions
	Buffer (Buffer &&other)
	Move constructor.

	Buffer (const Buffer &other)
	Copy constructor.

	Buffer (const void *data, size_t size)
	Constructor using a read-only external memory area which must remain valid as long as the Buffer object is used and not reset.

	Buffer (size_t size=DEFAULT_SIZE)
	Default constructor.

	Buffer (void *data, size_t size, bool read_only=false)
	Constructor using an external memory area which must remain valid as long as the Buffer object is used and not reset.

	~Buffer ()
	Destructor.

bool	backBits (size_t bits)
	Skip read bits backward.

bool	backBytes (size_t bytes)
	Skip read bytes backward.

bool	canRead () const
	Check if we can still read from the buffer.

bool	canReadBits (size_t bits) const
	Check if we can read at least the specified number of bits from the buffer.

bool	canReadBytes (size_t bytes) const
	Check if we can read at least the specified number of bytes from the buffer.

bool	canWrite () const
	Check if we can still write in the buffer.

bool	canWriteBits (size_t bits) const
	Check if we can write at least the specified number of bits in the buffer.

bool	canWriteBytes (size_t bytes) const
	Check if we can write at least the specified number of bytes in the buffer.

size_t	capacity () const
	Get the maximum buffer size in bytes.

void	clearError ()
	Clear all error states.

void	clearReadError ()
	Clear the read error state.

void	clearUserError ()
	Clear the user-generated error state.

void	clearWriteError ()
	Clear the write error state.

const uint8_t *	currentReadAddress () const
	Get starting address of current read data (ignoring bit offset inside first byte to read).

size_t	currentReadBitOffset () const
	Get current read bit offset from the beginning of the buffer.

size_t	currentReadByteOffset () const
	Get current read byte index (ignoring bit offset inside bytes).

size_t	currentWriteBitOffset () const
	Get current write bit offset from the beginning of the buffer.

size_t	currentWriteByteOffset () const
	Get current write byte index (ignoring bit offset inside bytes).

const uint8_t *	data () const
	Get the current base address of the buffer.

bool	dropState (size_t level=NPOS)
	Drop the last saved state of the read/write streams from the stack of saved states.

bool	endOfRead () const
	Check end of read stream.

bool	endOfWrite () const
	Check end of write stream.

bool	error () const
	Check if there was any kind of error.

bool	externalMemory () const
	Check if the buffer is linked to some external memory area.

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
bool	getBCD (INT &value, size_t bcd_count)
	Read the next 4*n bits as a Binary Coded Decimal (BCD) value and advance the read pointer.

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
INT	getBCD (size_t bcd_count)
	Read the next 4*n bits as a Binary Coded Decimal (BCD) value and advance the read pointer.

uint8_t	getBit ()
	Read the next bit and advance the read pointer.

template<class Rep , class Period >
void	getBits (cn::duration< Rep, Period > &value, size_t bits)
	Read the next n bits as a std::chrono::duration value and advance the read pointer.

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
void	getBits (INT &value, size_t bits)
	Read the next n bits as an integer value and advance the read pointer.

template<typename INT , typename std::enable_if< std::is_integral< INT >::value &&std::is_unsigned< INT >::value >::type * = nullptr>
INT	getBits (size_t bits)
	Read the next n bits as an integer value and advance the read pointer.

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
void	getBits (std::optional< INT > &value, size_t bits)
	Read the next n bits as an integer value and advance the read pointer.

bool	getBool ()
	Read the next bit as a boolean and advance the read pointer.

void	getBytes (ByteBlock &bb, size_t bytes=NPOS)
	Get bulk bytes from the buffer.

ByteBlock	getBytes (size_t bytes=NPOS)
	Get bulk bytes from the buffer.

size_t	getBytes (uint8_t *buffer, size_t bytes)
	Get bulk bytes from the buffer.

size_t	getBytesAppend (ByteBlock &bb, size_t bytes=NPOS)
	Get bulk bytes from the buffer.

ieee_float32_t	getFloat32 ()
	Read the next 32 bits as an IEEE float value and advance the read pointer.

ieee_float64_t	getFloat64 ()
	Read the next 64 bits as an IEEE float value and advance the read pointer.

int16_t	getInt16 ()
	Read the next 16 bits as a signed integer value and advance the read pointer.

int32_t	getInt24 ()
	Read the next 24 bits as a signed integer value and advance the read pointer.

int32_t	getInt32 ()
	Read the next 32 bits as a signed integer value and advance the read pointer.

int64_t	getInt40 ()
	Read the next 40 bits as a signed integer value and advance the read pointer.

int64_t	getInt48 ()
	Read the next 48 bits as a signed integer value and advance the read pointer.

int64_t	getInt64 ()
	Read the next 64 bits as a signed integer value and advance the read pointer.

int8_t	getInt8 ()
	Read the next 8 bits as a signed integer value and advance the read pointer.

uint16_t	getUInt16 ()
	Read the next 16 bits as an unsigned integer value and advance the read pointer.

uint32_t	getUInt24 ()
	Read the next 24 bits as an unsigned integer value and advance the read pointer.

uint32_t	getUInt32 ()
	Read the next 32 bits as an unsigned integer value and advance the read pointer.

uint64_t	getUInt40 ()
	Read the next 40 bits as an unsigned integer value and advance the read pointer.

uint64_t	getUInt48 ()
	Read the next 48 bits as an unsigned integer value and advance the read pointer.

uint64_t	getUInt64 ()
	Read the next 64 bits as an unsigned integer value and advance the read pointer.

uint8_t	getUInt8 ()
	Read the next 8 bits as an unsigned integer value and advance the read pointer.

UString	getUTF16 (size_t bytes=NPOS)
	Get a UTF-16 string.

bool	getUTF16 (UString &result, size_t bytes=NPOS)
	Get a UTF-16 string.

UString	getUTF16WithLength (size_t length_bits=8)
	Get a UTF-16 string (preceded by its length).

bool	getUTF16WithLength (UString &result, size_t length_bits=8)
	Get a UTF-16 string (preceded by its length).

UString	getUTF8 (size_t bytes=NPOS)
	Get a UTF-8 string.

bool	getUTF8 (UString &result, size_t bytes=NPOS)
	Get a UTF-8 string.

UString	getUTF8WithLength (size_t length_bits=8)
	Get a UTF-8 string (preceded by its length).

bool	getUTF8WithLength (UString &result, size_t length_bits=8)
	Get a UTF-8 string (preceded by its length).

bool	internalMemory () const
	Check if the buffer uses some internal private memory buffer.

bool	isBigEndian () const
	Check if read/write operations of integers use big endian representation.

bool	isLittleEndian () const
	Check if read/write operations of integers use little endian representation.

bool	isNativeEndian () const
	Check if read/write operations of integers use the native endian representation.

bool	isValid () const
	Check if the buffer is valid and contains some memory.

Buffer &	operator= (Buffer &&other)
	Move-assignment operator.

Buffer &	operator= (const Buffer &other)
	Assignment operator.

bool	popState (size_t level=NPOS)
	Pop the current state of the read/write streams from the stack of saved states and perform appropriate actions.

size_t	pushedLevels () const
	Get the current number of pushed states of the read/write streams.

size_t	pushReadSize (size_t size)
	Temporary reduce the readable size of the buffer.

size_t	pushReadSizeFromLength (size_t length_bits)
	Temporary reduce the readable size of the buffer using a length field from the stream.

size_t	pushState ()
	Push the current state of the read/write streams on a stack of saved states.

size_t	pushWriteSequenceWithLeadingLength (size_t length_bits)
	Start a write sequence with a leading length field.

size_t	pushWriteSize (size_t size)
	Temporary reduce the writable size of the buffer.

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
bool	putBCD (INT value, size_t bcd_count)
	Put the next 4*n bits as a Binary Coded Decimal (BCD) value and advance the write pointer.

bool	putBit (uint8_t bit)
	Write the next bit and advance the write pointer.

template<class Rep , class Period >
bool	putBits (cn::duration< Rep, Period > value, size_t bits)
	Put the next n bits from a std::chrono::duration value and advance the write pointer.

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
bool	putBits (const std::optional< INT > &value, size_t bits)
	Put the next n bits from an integer value and advance the write pointer.

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
bool	putBits (INT value, size_t bits)
	Put the next n bits from an integer value and advance the write pointer.

size_t	putBytes (const ByteBlock &bb, size_t start=0, size_t count=NPOS)
	Put bulk bytes in the buffer.

size_t	putBytes (const uint8_t *buffer, size_t bytes)
	Put bytes in the buffer.

bool	putFixedUTF16 (const UString &str, size_t size, uint16_t pad=0, size_t start=0, size_t count=NPOS)
	Put a string using UTF-16 format with a fixed binary size (truncate or pad).

bool	putFixedUTF8 (const UString &str, size_t size, uint8_t pad=0, size_t start=0, size_t count=NPOS)
	Put a string using UTF-8 format with a fixed binary size (truncate or pad).

bool	putFloat32 (ieee_float32_t f)
	Write a 32-bit IEEE float value and advance the write pointer.

bool	putFloat64 (ieee_float64_t f)
	Write a 64-bit IEEE float value and advance the write pointer.

bool	putInt16 (int16_t i)
	Write a 16-bit signed integer value and advance the write pointer.

bool	putInt24 (int32_t i)
	Write a 24-bit signed integer value and advance the write pointer.

bool	putInt32 (int32_t i)
	Write a 32-bit signed integer value and advance the write pointer.

bool	putInt40 (int64_t i)
	Write a 40-bit signed integer value and advance the write pointer.

bool	putInt48 (int64_t i)
	Write a 48-bit signed integer value and advance the write pointer.

bool	putInt64 (int64_t i)
	Write a 64-bit signed integer value and advance the write pointer.

bool	putInt8 (int8_t i)
	Write an 8-bit signed integer value and advance the write pointer.

size_t	putPartialUTF16 (const UString &str, size_t start=0, size_t count=NPOS)
	Put a partial string using UTF-8 format.

size_t	putPartialUTF16WithLength (const UString &str, size_t start=0, size_t count=NPOS, size_t length_bits=8)
	Put a partial string (preceded by its length) using UTF-16 format.

size_t	putPartialUTF8 (const UString &str, size_t start=0, size_t count=NPOS)
	Put a partial string using UTF-8 format.

size_t	putPartialUTF8WithLength (const UString &str, size_t start=0, size_t count=NPOS, size_t length_bits=8)
	Put a partial string (preceded by its length) using UTF-8 format.

bool	putReserved (size_t bits)
	Serialize the number of reserved '1' bits.

bool	putReservedZero (size_t bits)
	Serialize the number of reserved '0' bits.

bool	putUInt16 (uint16_t i)
	Write a 16-bit unsigned integer value and advance the write pointer.

bool	putUInt24 (uint32_t i)
	Write a 24-bit unsigned integer value and advance the write pointer.

bool	putUInt32 (uint32_t i)
	Write a 32-bit unsigned integer value and advance the write pointer.

bool	putUInt40 (uint64_t i)
	Write a 40-bit unsigned integer value and advance the write pointer.

bool	putUInt48 (uint64_t i)
	Write a 48-bit unsigned integer value and advance the write pointer.

bool	putUInt64 (uint64_t i)
	Write a 64-bit unsigned integer value and advance the write pointer.

bool	putUInt8 (uint8_t i)
	Write an 8-bit unsigned integer value and advance the write pointer.

bool	putUTF16 (const UString &str, size_t start=0, size_t count=NPOS)
	Put a string using UTF-16 format.

bool	putUTF16WithLength (const UString &str, size_t start=0, size_t count=NPOS, size_t length_bits=8)
	Put a string (preceded by its length) using UTF-16 format.

bool	putUTF8 (const UString &str, size_t start=0, size_t count=NPOS)
	Put a string using UTF-8 format.

bool	putUTF8WithLength (const UString &str, size_t start=0, size_t count=NPOS, size_t length_bits=8)
	Put a string (preceded by its length) using UTF-8 format.

bool	readError () const
	Check if there was a read error.

bool	readIsByteAligned () const
	Check if the current read bit pointer is on a byte boundary.

bool	readOnly () const
	Check if the buffer is read-only.

bool	readRealignByte ()
	Align the read pointer to the next byte boundary if not already aligned.

bool	readSeek (size_t byte, size_t bit=0)
	Reset reading at the specified offset in the buffer.

size_t	remainingReadBits () const
	Get number of remaining bits to read.

size_t	remainingReadBytes () const
	Get number of remaining bytes to read (ignoring bit offset inside bytes).

size_t	remainingWriteBits () const
	Get number of remaining bits to write.

size_t	remainingWriteBytes () const
	Get number of remaining bytes to write (ignoring bit offset inside bytes).

bool	reservedBitsError () const
	Check if there were "reserved bits errors".

UString	reservedBitsErrorString (size_t base_offset=0, const UString &margin=UString())
	Return a string describing the "reserved bits errors".

void	reset (const void *data, size_t size)
	Reset the buffer using a read-only external memory area which must remain valid as long as the Buffer object is used and not reset.

void	reset (size_t size)
	Reset the buffer, remove link to any external memory, reallocate an internal buffer if necessary.

void	reset (void *data, size_t size, bool read_only=false)
	Reset the buffer using an external memory area which must remain valid as long as the Buffer object is used and not reset.

bool	resize (size_t size, bool reallocate)
	Change the usable size of the buffer.

void	setBigEndian ()
	Specify that read/write operations of integers should use big endian representation.

void	setLittleEndian ()
	Specify that read/write operations of integers should use little endian representation.

void	setNativeEndian ()
	Specify that read/write operations of integers should use the native endian representation.

void	setUserError ()
	Set the user-generated error state.

size_t	size () const
	Get the current buffer size in bytes.

bool	skipBits (size_t bits)
	Skip read bits forward.

bool	skipBytes (size_t bytes)
	Skip read bytes forward (ignoring bit offset inside bytes).

bool	skipReservedBits (size_t bits, int expected=1)
	Skip read reserved bits forward.

size_t	swapState ()
	Swap the current state of the read/write streams with the one on top of the stack of saved states.

void	switchEndian ()
	Switch the endianness of read/write operations of integers.

UString	tryGetASCII (size_t bytes=NPOS)
	Try to get an ASCII string.

bool	tryGetASCII (UString &result, size_t bytes=NPOS)
	Try to get an ASCII string.

bool	userError () const
	Check if there was a user-generated error.

bool	writeError () const
	Check if there was a write error.

bool	writeIsByteAligned () const
	Check if the current write bit pointer is on a byte boundary.

bool	writeRealignByte (int stuffing=0)
	Align the write pointer to the next byte boundary if not already aligned.

bool	writeSeek (size_t byte, size_t bit, uint8_t stuffing)
	Reset writing at the specified offset in the buffer and trash forward memory.

bool	writeSeek (size_t byte, size_t bit=0)
	Reset writing at the specified offset in the buffer.

Static Public Member Functions
static UString	ReservedBitsErrorString (std::vector< size_t > &errors, size_t base_offset=0, const UString &margin=UString())
	This static method returns a string describing "reserved bits errors".

Static Public Attributes
static constexpr size_t	DEFAULT_SIZE = 1024
	Default internal size in bytes of a buffer.

static constexpr size_t	MINIMUM_SIZE = 16
	Minimal internal allocation size (capacity) in bytes of an internal private buffer.

Protected Member Functions
uint8_t *	currentWriteAddress () const
	Get starting address of current write area (ignoring bit offset inside first byte to read).

void	setReadError ()
	Set the read error state (reserved to subclasses).

void	setWriteError ()
	Set the write error state (reserved to subclasses).

Detailed Description

General-purpose memory buffer with bit access.

A buffer has the following properties:

Internal memory space (freeed with the buffer object) or external memory area.
Access mode: read/write or read-only.
Maximum size (in bytes).
Read pointer (in bits).
Write pointer (in bits).
Error state (read error, write error, user-generated error).
Endianness: byte and bit order, used when reading or writing integer data.

In a read/write buffer, both read and write pointers initially point to the start of the buffer. Then, the read pointer always remains behind the write pointer. In other words, we can read only what was previously written. The application cannot write beyond the current maximum buffer size and cannot read beyond the current write pointer.

In a read-only buffer, the write pointer always points to the end of the buffer and cannot be changed.

Read and write pointers are composed of a byte offset from the beginning of the buffer and a bit offset (0 to 7) in this byte. In big endian mode (the default), bit 0 is the most significant bit (msb) and bit 7 is the least significant bit (lsb). In little endian mode, bit 0 is the lsb and bit 7 is the msb.

It is possible to read and write integer values of any number of bits, starting at any bit offset. Best performances are, of course, achieved on 8, 16, 32 and 64-bit integers starting at a byte boundary (bit offset 0).

The two read-error and write-error states are independent. They are most commonly set when trying to read or write past the write pointer or end of buffer, respectively. When some multi-byte data cannot be read or written, the corresponding error is set and the read or write pointer is left unmodified (no partial read or write).

Once the read error is set, all subsequent read operations will fail until the read error state is explicitly cleared. The same principle applies to write error state and write operations.

For example, consider that the remaining number of bytes to read is 2. Trying to read a 32-bit data fails and the read error is set. Attempting to read an 8-bit or 16-bit data will then fail because the read error is set, even though there are enough bytes to read.

Note: The principles of the C++ class ts::Buffer were freely inspired by the Java class java.nio.ByteBuffer. There are differences between the two but the main principles are similar.

Constructor & Destructor Documentation

◆ Buffer() [1/5]

ts::Buffer::Buffer ( size_t size = DEFAULT_SIZE )

Default constructor.

The read and write index are at the beginning of the buffer. So, initially, there is nothing to read and the entire buffer to write.

Parameters

[in] size Initial internal size in bytes of the buffer.

◆ Buffer() [2/5]

ts::Buffer::Buffer	(	void *	data,
		size_t	size,
		bool	read_only = `false`
	)

Constructor using an external memory area which must remain valid as long as the Buffer object is used and not reset.

When read_only is true, the read index is at the beginning of the buffer and the write index is at the end of the buffer. When read_only is false, the read and write index are both at the beginning of the buffer.

Parameters

[in]	data	Address of data area to use as memory buffer.
[in]	size	Size in bytes of the data area.
[in]	read_only	The buffer is read-only.

◆ Buffer() [3/5]

ts::Buffer::Buffer	(	const void *	data,
		size_t	size
	)

Constructor using a read-only external memory area which must remain valid as long as the Buffer object is used and not reset.

The read index is at the beginning of the buffer and the write index is at the end of the buffer.

Parameters

[in]	data	Address of data area to use as memory buffer.
[in]	size	Size in bytes of the data area.

◆ Buffer() [4/5]

ts::Buffer::Buffer ( const Buffer & other )

Copy constructor.

Parameters

[in] other Other instance to copy.

◆ Buffer() [5/5]

ts::Buffer::Buffer ( Buffer && other )

Move constructor.

Parameters

[in,out] other Other instance to move. Reset and invalidated on return.

Member Function Documentation

◆ operator=() [1/2]

Buffer & ts::Buffer::operator= ( const Buffer & other )

Assignment operator.

Parameters

[in] other Other instance to copy.

Returns: A reference to this object.

◆ operator=() [2/2]

Buffer & ts::Buffer::operator= ( Buffer && other )

Move-assignment operator.

Parameters

[in,out] other Other instance to move. Reset and invalidated on return.

Returns: A reference to this object.

◆ isValid()

bool ts::Buffer::isValid ( ) const

Check if the buffer is valid and contains some memory.

Returns: True if the buffer is valid and contains some memory.

◆ readOnly()

bool ts::Buffer::readOnly ( ) const

inline

Check if the buffer is read-only.

Returns: True if the buffer is read-only.

◆ internalMemory()

bool ts::Buffer::internalMemory ( ) const

inline

Check if the buffer uses some internal private memory buffer.

Returns: True if the buffer uses some internal private memory buffer.

◆ externalMemory()

bool ts::Buffer::externalMemory ( ) const

inline

Check if the buffer is linked to some external memory area.

Returns: True if the buffer is linked to some external memory area.

◆ capacity()

size_t ts::Buffer::capacity ( ) const

inline

Get the maximum buffer size in bytes.

Returns: The maximum buffer size in bytes.

◆ size()

size_t ts::Buffer::size ( ) const

inline

Get the current buffer size in bytes.

Returns: The current buffer size in bytes.

◆ data()

const uint8_t * ts::Buffer::data ( ) const

inline

Get the current base address of the buffer.

Returns: A constant pointer the base of the buffer.

◆ setBigEndian()

void ts::Buffer::setBigEndian ( )

inline

Specify that read/write operations of integers should use big endian representation.

The endianness of the buffer is not changed by the various reset() operations.

◆ setLittleEndian()

void ts::Buffer::setLittleEndian ( )

inline

Specify that read/write operations of integers should use little endian representation.

The endianness of the buffer is not changed by the various reset() operations.

◆ setNativeEndian()

void ts::Buffer::setNativeEndian ( )

inline

Specify that read/write operations of integers should use the native endian representation.

The endianness of the buffer is not changed by the various reset() operations.

◆ switchEndian()

void ts::Buffer::switchEndian ( )

inline

Switch the endianness of read/write operations of integers.

The endianness of the buffer is not changed by the various reset() operations.

◆ isBigEndian()

bool ts::Buffer::isBigEndian ( ) const

inline

Check if read/write operations of integers use big endian representation.

Returns: True if big endian is used, false if little endian.

◆ isLittleEndian()

bool ts::Buffer::isLittleEndian ( ) const

inline

Check if read/write operations of integers use little endian representation.

Returns: True if little endian is used, false if big endian.

◆ isNativeEndian()

bool ts::Buffer::isNativeEndian ( ) const

inline

Check if read/write operations of integers use the native endian representation.

Returns: True if the native endian is used, false otherwise.

◆ reset() [1/3]

void ts::Buffer::reset ( size_t size )

Reset the buffer, remove link to any external memory, reallocate an internal buffer if necessary.

The read and write index are at the beginning of the buffer. So, initially, there is nothing to read and the entire buffer to write.

Parameters

[in] size Internal size in bytes of the buffer. If an internal buffer already exists and is larger than the requested size, it is not shrunk.

◆ reset() [2/3]

void ts::Buffer::reset	(	void *	data,
		size_t	size,
		bool	read_only = `false`
	)

Reset the buffer using an external memory area which must remain valid as long as the Buffer object is used and not reset.

When read_only is true, the read index is at the beginning of the buffer and the write index is at the end of the buffer. When read_only is false, the read and write index are both at the beginning of the buffer.

Parameters

[in]	data	Address of data area to use as memory buffer.
[in]	size	Size in bytes of the data area.
[in]	read_only	The buffer is read-only.

◆ reset() [3/3]

void ts::Buffer::reset	(	const void *	data,
		size_t	size
	)

Reset the buffer using a read-only external memory area which must remain valid as long as the Buffer object is used and not reset.

The read index is at the beginning of the buffer and the write index is at the end of the buffer.

Parameters

[in]	data	Address of data area to use as memory buffer.
[in]	size	Size in bytes of the data area.

◆ readError()

bool ts::Buffer::readError ( ) const

inline

Check if there was a read error.

Returns: True if there was a read error.

◆ writeError()

bool ts::Buffer::writeError ( ) const

inline

Check if there was a write error.

Returns: True if there was a write error.

◆ userError()

bool ts::Buffer::userError ( ) const

inline

Check if there was a user-generated error.

Returns: True if there was a user-generated error.

See also: setUserError()

◆ error()

bool ts::Buffer::error ( ) const

inline

Check if there was any kind of error.

Returns: True if there was any kind of error.

◆ setUserError()

void ts::Buffer::setUserError ( )

inline

Set the user-generated error state.

This can be used to indicate an application error such as invalid data format for instance.

◆ readSeek()

bool ts::Buffer::readSeek	(	size_t	byte,
		size_t	bit = `0`
	)

Reset reading at the specified offset in the buffer.

Seeking past the write pointer moves the read pointer to the write pointer and generates a read error.

Parameters

[in]	byte	Index of next byte to read.
[in]	bit	Offset of next bit to read in this byte.

Returns: True on success, false on error.

◆ writeSeek() [1/2]

bool ts::Buffer::writeSeek	(	size_t	byte,
		size_t	bit = `0`
	)

Reset writing at the specified offset in the buffer.

Seeking backward beyond the read pointer moves the write pointer to the read pointer and generates a write error. Seeking forward past the end of buffer moves the write pointer to the end of the buffer and generates a write error.

Parameters

[in]	byte	Index of next byte to write.
[in]	bit	Offset of next bit to write in this byte.

Returns: True on success, false on error.

◆ writeSeek() [2/2]

bool ts::Buffer::writeSeek	(	size_t	byte,
		size_t	bit,
		uint8_t	stuffing
	)

Reset writing at the specified offset in the buffer and trash forward memory.

Seeking backward beyond the read pointer moves the write pointer to the read pointer and generates a write error. Seeking forward past the end of buffer moves the write pointer to the end of the buffer and generates a write error.

Parameters

[in]	byte	Index of next byte to write.
[in]	bit	Offset of next bit to write in this byte.
[in]	stuffing	When seeking forward, byte value to write in skipped bytes.

Returns: True on success, false on error.

◆ readIsByteAligned()

bool ts::Buffer::readIsByteAligned ( ) const

inline

Check if the current read bit pointer is on a byte boundary.

Returns: True if the next bit to read is at the beginning of a byte.

◆ writeIsByteAligned()

bool ts::Buffer::writeIsByteAligned ( ) const

inline

Check if the current write bit pointer is on a byte boundary.

Returns: True if the next bit to write is at the beginning of a byte.

◆ readRealignByte()

bool ts::Buffer::readRealignByte ( )

Align the read pointer to the next byte boundary if not already aligned.

Skip any bit in a partially read byte.

Returns: True on success, false if would got beyond write pointer (and set read error flag).

◆ writeRealignByte()

bool ts::Buffer::writeRealignByte ( int stuffing = 0 )

Align the write pointer to the next byte boundary if not already aligned.

Fill bits in a partially written byte with a know value.

Parameters

[in] stuffing Bit value (must be 0 or 1) to write in skipped bits.

Returns: Always true.

◆ skipBytes()

bool ts::Buffer::skipBytes ( size_t bytes )

Skip read bytes forward (ignoring bit offset inside bytes).

Parameters

[in] bytes Number of bytes to skip.

Returns: True on success, false if would got beyond write pointer (and set read error flag).

◆ skipBits()

bool ts::Buffer::skipBits ( size_t bits )

Skip read bits forward.

Parameters

[in] bits Number of bits to skip.

Returns: True on success, false if would got beyond write pointer (and set read error flag).

◆ skipReservedBits()

bool ts::Buffer::skipReservedBits	(	size_t	bits,
		int	expected = `1`
	)

Skip read reserved bits forward.

Parameters

[in]	bits	Number of reserved bits to skip.
[in]	expected	Expected value of each reserved bit. Must be 0 or 1, default is 1. For each reserved bit which does not have the expected value, a "reserved bit error" is logged.

Returns: True on success, false if would got beyond write pointer (and set read error flag).

See also: reservedBitsError()

◆ reservedBitsError()

bool ts::Buffer::reservedBitsError ( ) const

inline

Check if there were "reserved bits errors".

Returns: True if there were "reserved bits errors".

See also: skipReservedBits()

◆ reservedBitsErrorString()

UString ts::Buffer::reservedBitsErrorString	(	size_t	base_offset = `0`,
		const UString &	margin = `UString()`
	)

inline

Return a string describing the "reserved bits errors".

Parameters

[in]	base_offset	Artificial base offset in bytes which is used to describe the placement of each bit error. When the Buffer instance describes the payload of a structure, specify the structure header size as base_offset in order to display each bit error relatively to the complete structure.
[in]	margin	Prepend that string to each line.

Returns: A string describing the "reserved bits errors". This is a mul

See also: skipReservedBits()

◆ ReservedBitsErrorString()

static UString ts::Buffer::ReservedBitsErrorString	(	std::vector< size_t > &	errors,
		size_t	base_offset = `0`,
		const UString &	margin = `UString()`
	)

static

This static method returns a string describing "reserved bits errors".

Parameters

[in,out]	errors	A vector of error description. Each value is made of byte offset \|\| bit offset (3 bits) \|\| expected bit value (1 bit). The vector is sorted first.
[in]	base_offset	Artificial base offset in bytes which is used to describe the placement of each bit error. When the Buffer instance describes the payload of a structure, specify the structure header size as base_offset in order to display each bit error relatively to the complete structure.
[in]	margin	Prepend that string to each line.

Returns: A string describing the "reserved bits errors". This is a mul

See also: skipReservedBits()

◆ backBytes()

bool ts::Buffer::backBytes ( size_t bytes )

Skip read bytes backward.

Parameters

[in] bytes Number of bytes to skip back.

Returns: True on success, false if would got beyond start of buffer (and set read error flag).

◆ backBits()

bool ts::Buffer::backBits ( size_t bits )

Skip read bits backward.

Parameters

[in] bits Number of bits to skip back.

Returns: True on success, false if would got beyond start of buffer (and set read error flag).

◆ currentReadAddress()

const uint8_t * ts::Buffer::currentReadAddress ( ) const

inline

Get starting address of current read data (ignoring bit offset inside first byte to read).

Returns: The starting address of current read data.

◆ currentReadByteOffset()

size_t ts::Buffer::currentReadByteOffset ( ) const

inline

Get current read byte index (ignoring bit offset inside bytes).

Returns: The offset of the byte to read from the beginning of the buffer.

◆ currentReadBitOffset()

size_t ts::Buffer::currentReadBitOffset ( ) const

inline

Get current read bit offset from the beginning of the buffer.

Returns: The offset of the current bit to read from the beginning of the buffer.

◆ currentWriteByteOffset()

size_t ts::Buffer::currentWriteByteOffset ( ) const

inline

Get current write byte index (ignoring bit offset inside bytes).

Returns: The offset of the next byte to write from the beginning of the buffer.

◆ currentWriteBitOffset()

size_t ts::Buffer::currentWriteBitOffset ( ) const

inline

Get current write bit offset from the beginning of the buffer.

Returns: The offset of the next bit to write from the beginning of the buffer.

◆ remainingReadBytes()

size_t ts::Buffer::remainingReadBytes ( ) const

Get number of remaining bytes to read (ignoring bit offset inside bytes).

Returns: The number of remaining bytes to read.

◆ remainingReadBits()

size_t ts::Buffer::remainingReadBits ( ) const

Get number of remaining bits to read.

Returns: The number of remaining bits to read.

◆ remainingWriteBytes()

size_t ts::Buffer::remainingWriteBytes ( ) const

Get number of remaining bytes to write (ignoring bit offset inside bytes).

Returns: The number of remaining bytes to write.

◆ remainingWriteBits()

size_t ts::Buffer::remainingWriteBits ( ) const

Get number of remaining bits to write.

Returns: The number of remaining bits to write.

◆ endOfRead()

bool ts::Buffer::endOfRead ( ) const

inline

Check end of read stream.

Returns: True if the end of read stream is reached.

◆ endOfWrite()

bool ts::Buffer::endOfWrite ( ) const

inline

Check end of write stream.

Returns: True if the end of write stream is reached.

◆ canRead()

bool ts::Buffer::canRead ( ) const

inline

Check if we can still read from the buffer.

Returns: True if we can still read from the buffer.

◆ canReadBytes()

bool ts::Buffer::canReadBytes ( size_t bytes ) const

inline

Check if we can read at least the specified number of bytes from the buffer.

Parameters

[in] bytes Number of bytes.

Returns: True if we can read at least bytes.

◆ canReadBits()

bool ts::Buffer::canReadBits ( size_t bits ) const

inline

Check if we can read at least the specified number of bits from the buffer.

Parameters

[in] bits Number of bits.

Returns: True if we can read at least bits.

◆ canWrite()

bool ts::Buffer::canWrite ( ) const

inline

Check if we can still write in the buffer.

Returns: True if we can still write in the buffer.

◆ canWriteBytes()

bool ts::Buffer::canWriteBytes ( size_t bytes ) const

inline

Check if we can write at least the specified number of bytes in the buffer.

Parameters

[in] bytes Number of bytes.

Returns: True if we can write at least bytes.

◆ canWriteBits()

bool ts::Buffer::canWriteBits ( size_t bits ) const

inline

Check if we can write at least the specified number of bits in the buffer.

Parameters

[in] bits Number of bits.

Returns: True if we can write at least bits.

◆ pushState()

size_t ts::Buffer::pushState ( )

Push the current state of the read/write streams on a stack of saved states.

There is an internal stack of read/write states. It is possible to save the current state of the buffer, try to do some operations and then either restore (pop) the previous state if the attempted operations failed or drop the saved state and continue with the new state.

Returns: The level of pushed state (0 for the first push, then 1, etc.) The returned level can be used by popState() and dropState().

See also: popState()

◆ pushReadSize()

size_t ts::Buffer::pushReadSize ( size_t size )

Temporary reduce the readable size of the buffer.

The previous state is pushed to the internal stack of state and can be restored later. Saving the readable size temporarily changes the write pointer and sets the buffer as read only. When the state is restored using popState(), the previous readable size (write pointer) and read-only indicator are restored. The read pointer is set to the end of previous readable size.

Parameters

[in] size New readable size in bytes of the buffer. In some cases, the final granted size can be different. The final value is bounded by the current read and write pointers.

Returns: The level of pushed state (0 for the first push, then 1, etc.) Return NPOS on error.

See also: popState()

◆ pushReadSizeFromLength()

size_t ts::Buffer::pushReadSizeFromLength ( size_t length_bits )

Temporary reduce the readable size of the buffer using a length field from the stream.

An integer value is read from the stream (given the value size in bits). The read pointer must then be byte-aligned. Finally, pushReadSize() is called so that the remaining number of bytes to read is the length value that was just read.

Parameters

[in] length_bits Size in bits of the length field to read.

Returns: The level of pushed state (0 for the first push, then 1, etc.) Return NPOS on error.

See also: pushReadSize()

◆ pushWriteSize()

size_t ts::Buffer::pushWriteSize ( size_t size )

Temporary reduce the writable size of the buffer.

The previous state is pushed to the internal stack of state and can be restored later. Saving the writable size temporarily changes the end of buffer. When the state is restored using popState(), the previous end of buffer is restored. The read and write pointers are not restored (everything that was read or written in the meantime remain valid).

Parameters

[in] size New writable size in bytes of the buffer. In some cases, the final granted size can be different. The final value is bounded by the current write pointer and end of buffer.

Returns: The level of pushed state (0 for the first push, then 1, etc.) Return NPOS on error.

See also: popState()

◆ pushWriteSequenceWithLeadingLength()

size_t ts::Buffer::pushWriteSequenceWithLeadingLength ( size_t length_bits )

Start a write sequence with a leading length field.

The current state is pushed and the specified number of bits are skipped in the write field. The write stream must then be byte-aligned or an error is generated. Writing data can be continued by the application. When popState() is called, the size in bytes starting after the length field is then written in the length field.

Parameters

[in] length_bits Size in bits of the length field to write. Must be in the range 1 to 64.

Returns: The level of pushed state (0 for the first push, then 1, etc.) Return NPOS on error.

See also: popState()

◆ swapState()

size_t ts::Buffer::swapState ( )

Swap the current state of the read/write streams with the one on top of the stack of saved states.

The previous state must have been fully saved using pushState() only, not any other push method such as pushReadSize() or pushWriteSize(). Otherwise, the buffer is set in read and write error state.

As a result, the previously saved state is restored and the current state (just before restoring the saved state) is pushed. If there was no saved state, the current state is unchanged but still saved. So it is always safe to assume that the current state was saved.

Returns: The level of pushed state (0 for the first push, then 1, etc.) Return NPOS on error.

◆ popState()

bool ts::Buffer::popState ( size_t level = NPOS )

Pop the current state of the read/write streams from the stack of saved states and perform appropriate actions.

The new state depends on which method was used to push the previous state.

Parameters

[in] level Saved level to restore. The default is NPOS, meaning the last saved state. Another inner level can be specified, in which case all outer levels are also popped.

Returns: True on success. False if there is no saved state or level does not exist.

See also: pushState(); pushReadSize(); pushWriteSize()

◆ dropState()

bool ts::Buffer::dropState ( size_t level = NPOS )

Drop the last saved state of the read/write streams from the stack of saved states.

Parameters

[in] level Saved level to drop. The default is NPOS, meaning the last saved state. Another inner level can be specified, in which case the specified level and all outer levels are dropped.

Returns: True on success. False if there is no saved state or level does not exist.

See also: pushReadWriteState()

◆ pushedLevels()

size_t ts::Buffer::pushedLevels ( ) const

inline

Get the current number of pushed states of the read/write streams.

Returns: The current number of pushed states of the read/write streams.

◆ resize()

bool ts::Buffer::resize	(	size_t	size,
		bool	reallocate
	)

Change the usable size of the buffer.

Parameters

[in]	size	New usable size in bytes of the buffer. In some cases, the final granted size can be different: If size is lower than the current write pointer, the new usable size is set to the current write pointer. If size is greater than the current capacity() and the buffer is an external memory or reallocate is false, the new usable size is set to the current capacity().
[in]	reallocate	If true and the buffer is internally allocated, then reallocate the internal buffer to the final accepted size.

Returns: True in case of success. False if the requested size could not be granted. When the result is false, call size() to get the new actual buffer size.

See also: size(); capacity()

◆ getBit()

uint8_t ts::Buffer::getBit ( )

Read the next bit and advance the read pointer.

Returns: The value of the next bit.

◆ getBool()

bool ts::Buffer::getBool ( )

inline

Read the next bit as a boolean and advance the read pointer.

Returns: The value of the next bit.

◆ putBit()

bool ts::Buffer::putBit ( uint8_t bit )

Write the next bit and advance the write pointer.

Parameters

[in] bit The bit value (0 or 1).

Returns: True on success, false on error (read only or no more space to write).

◆ getBits() [1/4]

template<typename INT , typename std::enable_if< std::is_integral< INT >::value &&std::is_unsigned< INT >::value >::type * >

INT ts::Buffer::getBits ( size_t bits )

Read the next n bits as an integer value and advance the read pointer.

Template Parameters

INT	An integer type for the result.

Parameters

[in] bits Number of bits to read.

Returns: The value of the next bits.

◆ getBits() [2/4]

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>

void ts::Buffer::getBits	(	INT &	value,
		size_t	bits
	)

inline

Read the next n bits as an integer value and advance the read pointer.

Template Parameters

INT	An integer type for the result.

Parameters

[out]	value	The value of the next bits.
[in]	bits	Number of bits to read.

◆ getBits() [3/4]

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * >

void ts::Buffer::getBits	(	std::optional< INT > &	value,
		size_t	bits
	)

Read the next n bits as an integer value and advance the read pointer.

Template Parameters

INT	An integer type for the result.

Parameters

[out]	value	The value of the next bits as a std::optional instance. If no integer can be read, the std::optional is unset.
[in]	bits	Number of bits to read.

◆ getBits() [4/4]

template<class Rep , class Period >

void ts::Buffer::getBits	(	cn::duration< Rep, Period > &	value,
		size_t	bits
	)

Read the next n bits as a std::chrono::duration value and advance the read pointer.

Parameters

[out]	value	The value of the next bits.
[in]	bits	Number of bits to read.

◆ putBits() [1/3]

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * >

bool ts::Buffer::putBits	(	INT	value,
		size_t	bits
	)

Put the next n bits from an integer value and advance the write pointer.

Template Parameters

INT	An integer type.

Parameters

[in]	value	Integer value to write.
[in]	bits	Number of bits to write.

Returns: True on success, false on error (read only or no more space to write).

◆ putBits() [2/3]

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>

bool ts::Buffer::putBits	(	const std::optional< INT > &	value,
		size_t	bits
	)

inline

Put the next n bits from an integer value and advance the write pointer.

Template Parameters

INT	An integer type.

Parameters

[in]	value	Integer value to write as a std::optional instance. If value is unset, nothing is written.
[in]	bits	Number of bits to write.

Returns: True on success, false on error (read only or no more space to write).

◆ putBits() [3/3]

template<class Rep , class Period >

bool ts::Buffer::putBits	(	cn::duration< Rep, Period >	value,
		size_t	bits
	)

inline

Put the next n bits from a std::chrono::duration value and advance the write pointer.

Parameters

[in]	value	Integer value to write.
[in]	bits	Number of bits to write.

Returns: True on success, false on error (read only or no more space to write).

◆ putReserved()

bool ts::Buffer::putReserved ( size_t bits )

Serialize the number of reserved '1' bits.

Parameters

[in] bits Number of reserved '1' bits to write.

Returns: True on success, false on error (read only or no more space to write).

◆ putReservedZero()

bool ts::Buffer::putReservedZero ( size_t bits )

inline

Serialize the number of reserved '0' bits.

Parameters

[in] bits Number of reserved '0' bits to write.

Returns: True on success, false on error (read only or no more space to write).

◆ getBytes() [1/3]

size_t ts::Buffer::getBytes	(	uint8_t *	buffer,
		size_t	bytes
	)

Get bulk bytes from the buffer.

The bit aligment is ignored, reading starts at the current read byte pointer, even if a few bits were already read from that byte.

Parameters

[out]	buffer	Address of the buffer receiving the read bytes.
[in]	bytes	Number of bytes to read.

Returns: Actual number of returned bytes. If the requested number of bytes is not available, return as much as possible and set the read error.

◆ getBytes() [2/3]

ByteBlock ts::Buffer::getBytes ( size_t bytes = NPOS )

Get bulk bytes from the buffer.

The bit aligment is ignored, reading starts at the current read byte pointer, even if a few bits were already read from that byte.

Parameters

[in] bytes Number of bytes to read. If specified as NPOS, return all remaining bytes.

Returns: Read data as a byte block. If the requested number of bytes is not available, return as much as possible and set the read error.

◆ getBytes() [3/3]

void ts::Buffer::getBytes	(	ByteBlock &	bb,
		size_t	bytes = `NPOS`
	)

Get bulk bytes from the buffer.

The bit aligment is ignored, reading starts at the current read byte pointer, even if a few bits were already read from that byte.

Parameters

[out]	bb	Byte block receiving the read bytes.
[in]	bytes	Number of bytes to read. If specified as NPOS, return all remaining bytes.

◆ getBytesAppend()

size_t ts::Buffer::getBytesAppend	(	ByteBlock &	bb,
		size_t	bytes = `NPOS`
	)

Get bulk bytes from the buffer.

The bit aligment is ignored, reading starts at the current read byte pointer, even if a few bits were already read from that byte.

Parameters

[in,out]	bb	Byte block receiving the read bytes. The read data are appended to bb.
[in]	bytes	Number of bytes to read. If specified as NPOS, return all remaining bytes.

Returns: Actual number of appended bytes. If the requested number of bytes is not available, return as much as possible and set the read error.

◆ putBytes() [1/2]

size_t ts::Buffer::putBytes	(	const uint8_t *	buffer,
		size_t	bytes
	)

Put bytes in the buffer.

Parameters

[in]	buffer	Address of the data to write.
[in]	bytes	Number of bytes to write.

Returns: Actual number of written bytes. If the requested number of bytes is not available, write as much as possible and set the write error.

◆ putBytes() [2/2]

size_t ts::Buffer::putBytes	(	const ByteBlock &	bb,
		size_t	start = `0`,
		size_t	count = `NPOS`
	)

Put bulk bytes in the buffer.

The bit aligment is ignored, writing starts at the current write byte pointer, even if a few bits were already written in that byte.

Parameters

[in]	bb	Byte block containing the data to write.
[in]	start	Start in index in bb.
[in]	count	Number of bytes to write.

Returns: Actual number of written bytes. If the requested number of bytes is not available, write as much as possible and set the write error.