TSDuck Version 3.32-2820 (TSDuck - The MPEG Transport Stream Toolkit)
ts::Buffer Class Reference

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

Inheritance diagram for ts::Buffer:

Public Member Functions

 Buffer (Buffer &&other)
 Move constructor. More...
 
 Buffer (const Buffer &other)
 Copy constructor. More...
 
 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. More...
 
 Buffer (size_t size=DEFAULT_SIZE)
 Default constructor. More...
 
 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. More...
 
 ~Buffer ()
 Destructor.
 
bool backBits (size_t bits)
 Skip read bits backward. More...
 
bool backBytes (size_t bytes)
 Skip read bytes backward. More...
 
bool canRead () const
 Check if we can still read from the buffer. More...
 
bool canReadBits (size_t bits) const
 Check if we can read at least the specified number of bits from the buffer. More...
 
bool canReadBytes (size_t bytes) const
 Check if we can read at least the specified number of bytes from the buffer. More...
 
bool canWrite () const
 Check if we can still write in the buffer. More...
 
bool canWriteBits (size_t bits) const
 Check if we can write at least the specified number of bits in the buffer. More...
 
bool canWriteBytes (size_t bytes) const
 Check if we can write at least the specified number of bytes in the buffer. More...
 
size_t capacity () const
 Get the maximum buffer size in bytes. More...
 
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). More...
 
size_t currentReadBitOffset () const
 Get current read bit offset from the beginning of the buffer. More...
 
size_t currentReadByteOffset () const
 Get current read byte index (ignoring bit offset inside bytes). More...
 
size_t currentWriteBitOffset () const
 Get current write bit offset from the beginning of the buffer. More...
 
size_t currentWriteByteOffset () const
 Get current write byte index (ignoring bit offset inside bytes). More...
 
const uint8_t * data () const
 Get the current base address of the buffer. More...
 
bool dropState (size_t level=NPOS)
 Drop the last saved state of the read/write streams from the stack of saved states. More...
 
bool endOfRead () const
 Check end of read stream. More...
 
bool endOfWrite () const
 Check end of write stream. More...
 
bool error () const
 Check if there was any kind of error. More...
 
bool externalMemory () const
 Check if the buffer is linked to some external memory area. More...
 
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. More...
 
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. More...
 
uint8_t getBit ()
 Read the next bit and advance the read pointer. More...
 
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. More...
 
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. More...
 
template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
void getBits (Variable< INT > &value, size_t bits)
 Read the next n bits as an integer value and advance the read pointer. More...
 
bool getBool ()
 Read the next bit as a boolean and advance the read pointer. More...
 
void getBytes (ByteBlock &bb, size_t bytes=NPOS)
 Get bulk bytes from the buffer. More...
 
ByteBlock getBytes (size_t bytes=NPOS)
 Get bulk bytes from the buffer. More...
 
size_t getBytes (uint8_t *buffer, size_t bytes)
 Get bulk bytes from the buffer. More...
 
size_t getBytesAppend (ByteBlock &bb, size_t bytes=NPOS)
 Get bulk bytes from the buffer. More...
 
int16_t getInt16 ()
 Read the next 16 bits as a signed integer value and advance the read pointer. More...
 
int32_t getInt24 ()
 Read the next 24 bits as a signed integer value and advance the read pointer. More...
 
int32_t getInt32 ()
 Read the next 32 bits as a signed integer value and advance the read pointer. More...
 
int64_t getInt40 ()
 Read the next 40 bits as a signed integer value and advance the read pointer. More...
 
int64_t getInt48 ()
 Read the next 48 bits as a signed integer value and advance the read pointer. More...
 
int64_t getInt64 ()
 Read the next 64 bits as a signed integer value and advance the read pointer. More...
 
int8_t getInt8 ()
 Read the next 8 bits as a signed integer value and advance the read pointer. More...
 
uint16_t getUInt16 ()
 Read the next 16 bits as an unsigned integer value and advance the read pointer. More...
 
uint32_t getUInt24 ()
 Read the next 24 bits as an unsigned integer value and advance the read pointer. More...
 
uint32_t getUInt32 ()
 Read the next 32 bits as an unsigned integer value and advance the read pointer. More...
 
uint64_t getUInt40 ()
 Read the next 40 bits as an unsigned integer value and advance the read pointer. More...
 
uint64_t getUInt48 ()
 Read the next 48 bits as an unsigned integer value and advance the read pointer. More...
 
uint64_t getUInt64 ()
 Read the next 64 bits as an unsigned integer value and advance the read pointer. More...
 
uint8_t getUInt8 ()
 Read the next 8 bits as an unsigned integer value and advance the read pointer. More...
 
UString getUTF16 (size_t bytes=NPOS)
 Get a UTF-16 string. More...
 
bool getUTF16 (UString &result, size_t bytes=NPOS)
 Get a UTF-16 string. More...
 
UString getUTF16WithLength (size_t length_bits=8)
 Get a UTF-16 string (preceded by its length). More...
 
bool getUTF16WithLength (UString &result, size_t length_bits=8)
 Get a UTF-16 string (preceded by its length). More...
 
UString getUTF8 (size_t bytes=NPOS)
 Get a UTF-8 string. More...
 
bool getUTF8 (UString &result, size_t bytes=NPOS)
 Get a UTF-8 string. More...
 
UString getUTF8WithLength (size_t length_bits=8)
 Get a UTF-8 string (preceded by its length). More...
 
bool getUTF8WithLength (UString &result, size_t length_bits=8)
 Get a UTF-8 string (preceded by its length). More...
 
bool internalMemory () const
 Check if the buffer uses some internal private memory buffer. More...
 
bool isBigEndian () const
 Check if read/write operations of integers use big endian representation. More...
 
bool isLittleEndian () const
 Check if read/write operations of integers use little endian representation. More...
 
bool isNativeEndian () const
 Check if read/write operations of integers use the native endian representation. More...
 
bool isValid () const
 Check if the buffer is valid and contains some memory. More...
 
Bufferoperator= (Buffer &&other)
 Move-assignment operator. More...
 
Bufferoperator= (const Buffer &other)
 Assignment operator. More...
 
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. More...
 
size_t pushedLevels () const
 Get the current number of pushed states of the read/write streams. More...
 
size_t pushReadSize (size_t size)
 Temporary reduce the readable size of the buffer. More...
 
size_t pushReadSizeFromLength (size_t length_bits)
 Temporary reduce the readable size of the buffer using a length field from the stream. More...
 
size_t pushState ()
 Push the current state of the read/write streams on a stack of saved states. More...
 
size_t pushWriteSequenceWithLeadingLength (size_t length_bits)
 Start a write sequence with a leading length field. More...
 
size_t pushWriteSize (size_t size)
 Temporary reduce the writable size of the buffer. More...
 
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. More...
 
bool putBit (uint8_t bit)
 Write the next bit and advance the write pointer. More...
 
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. More...
 
size_t putBytes (const ByteBlock &bb, size_t start=0, size_t count=NPOS)
 Put bulk bytes in the buffer. More...
 
size_t putBytes (const uint8_t *buffer, size_t bytes)
 Put bytes in the buffer. More...
 
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). More...
 
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). More...
 
bool putInt16 (int16_t i)
 Write a 16-bit signed integer value and advance the write pointer. More...
 
bool putInt24 (int32_t i)
 Write a 24-bit signed integer value and advance the write pointer. More...
 
bool putInt32 (int32_t i)
 Write a 32-bit signed integer value and advance the write pointer. More...
 
bool putInt40 (int64_t i)
 Write a 40-bit signed integer value and advance the write pointer. More...
 
bool putInt48 (int64_t i)
 Write a 48-bit signed integer value and advance the write pointer. More...
 
bool putInt64 (int64_t i)
 Write a 64-bit signed integer value and advance the write pointer. More...
 
bool putInt8 (int8_t i)
 Write an 8-bit signed integer value and advance the write pointer. More...
 
size_t putPartialUTF16 (const UString &str, size_t start=0, size_t count=NPOS)
 Put a partial string using UTF-8 format. More...
 
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. More...
 
size_t putPartialUTF8 (const UString &str, size_t start=0, size_t count=NPOS)
 Put a partial string using UTF-8 format. More...
 
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. More...
 
bool putUInt16 (uint16_t i)
 Write a 16-bit unsigned integer value and advance the write pointer. More...
 
bool putUInt24 (uint32_t i)
 Write a 24-bit unsigned integer value and advance the write pointer. More...
 
bool putUInt32 (uint32_t i)
 Write a 32-bit unsigned integer value and advance the write pointer. More...
 
bool putUInt40 (uint64_t i)
 Write a 40-bit unsigned integer value and advance the write pointer. More...
 
bool putUInt48 (uint64_t i)
 Write a 48-bit unsigned integer value and advance the write pointer. More...
 
bool putUInt64 (uint64_t i)
 Write a 64-bit unsigned integer value and advance the write pointer. More...
 
bool putUInt8 (uint8_t i)
 Write an 8-bit unsigned integer value and advance the write pointer. More...
 
bool putUTF16 (const UString &str, size_t start=0, size_t count=NPOS)
 Put a string using UTF-16 format. More...
 
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. More...
 
bool putUTF8 (const UString &str, size_t start=0, size_t count=NPOS)
 Put a string using UTF-8 format. More...
 
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. More...
 
bool readError () const
 Check if there was a read error. More...
 
bool readIsByteAligned () const
 Check if the current read bit pointer is on a byte boundary. More...
 
bool readOnly () const
 Check if the buffer is read-only. More...
 
bool readRealignByte ()
 Align the read pointer to the next byte boundary if not already aligned. More...
 
bool readSeek (size_t byte, size_t bit=0)
 Reset reading at the specified offset in the buffer. More...
 
size_t remainingReadBits () const
 Get number of remaining bits to read. More...
 
size_t remainingReadBytes () const
 Get number of remaining bytes to read (ignoring bit offset inside bytes). More...
 
size_t remainingWriteBits () const
 Get number of remaining bits to write. More...
 
size_t remainingWriteBytes () const
 Get number of remaining bytes to write (ignoring bit offset inside bytes). More...
 
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. More...
 
void reset (size_t size)
 Reset the buffer, remove link to any external memory, reallocate an internal buffer if necessary. More...
 
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. More...
 
bool resize (size_t size, bool reallocate)
 Change the usable size of the buffer. More...
 
void setBigEndian ()
 Specify that read/write operations of integers should use big endian representation. More...
 
void setLittleEndian ()
 Specify that read/write operations of integers should use little endian representation. More...
 
void setNativeEndian ()
 Specify that read/write operations of integers should use the native endian representation. More...
 
void setUserError ()
 Set the user-generated error state. More...
 
size_t size () const
 Get the current buffer size in bytes. More...
 
bool skipBits (size_t bits)
 Skip read bits forward. More...
 
bool skipBytes (size_t bytes)
 Skip read bytes forward (ignoring bit offset inside bytes). More...
 
size_t swapState ()
 Swap the current state of the read/write streams with the one on top of the stack of saved states. More...
 
void switchEndian ()
 Switch the endianness of read/write operations of integers. More...
 
UString tryGetASCII (size_t bytes=NPOS)
 Try to get an ASCII string. More...
 
bool tryGetASCII (UString &result, size_t bytes=NPOS)
 Try to get an ASCII string. More...
 
bool userError () const
 Check if there was a user-generated error. More...
 
bool writeError () const
 Check if there was a write error. More...
 
bool writeIsByteAligned () const
 Check if the current write bit pointer is on a byte boundary. More...
 
bool writeRealignByte (int stuffing=0)
 Align the write pointer to the next byte boundary if not already aligned. More...
 
bool writeSeek (size_t byte, size_t bit, uint8_t stuffing)
 Reset writing at the specified offset in the buffer and trash forward memory. More...
 
bool writeSeek (size_t byte, size_t bit=0)
 Reset writing at the specified offset in the buffer. More...
 

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). More...
 
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]sizeInitial 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]dataAddress of data area to use as memory buffer.
[in]sizeSize in bytes of the data area.
[in]read_onlyThe 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]dataAddress of data area to use as memory buffer.
[in]sizeSize in bytes of the data area.

◆ Buffer() [4/5]

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

Copy constructor.

Parameters
[in]otherOther instance to copy.

◆ Buffer() [5/5]

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

Move constructor.

Parameters
[in,out]otherOther 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]otherOther instance to copy.
Returns
A reference to this object.

◆ operator=() [2/2]

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

Move-assignment operator.

Parameters
[in,out]otherOther 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]sizeInternal 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]dataAddress of data area to use as memory buffer.
[in]sizeSize in bytes of the data area.
[in]read_onlyThe 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]dataAddress of data area to use as memory buffer.
[in]sizeSize 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]byteIndex of next byte to read.
[in]bitOffset 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 beyon 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]byteIndex of next byte to write.
[in]bitOffset 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 beyon 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]byteIndex of next byte to write.
[in]bitOffset of next bit to write in this byte.
[in]stuffingWhen 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]stuffingBit 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]bytesNumber 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]bitsNumber of bits to skip.
Returns
True on success, false if would got beyond write pointer (and set read error flag).

◆ backBytes()

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

Skip read bytes backward.

Parameters
[in]bytesNumber 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]bitsNumber 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]bytesNumber 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]bitsNumber 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]bytesNumber 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]bitsNumber 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]sizeNew 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_bitsSize 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]sizeNew 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_bitsSize 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]levelSaved 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]levelSaved 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]sizeNew 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]reallocateIf 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]bitThe bit value (0 or 1).
Returns
True on success, false on error (read only or no more space to write).

◆ getBits() [1/3]

template<typename INT , typename std::enable_if< std::is_integral< INT >::value &&std::is_unsigned< INT >::value >::type * = nullptr>
INT ts::Buffer::getBits ( size_t  bits)

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

Template Parameters
INTAn integer type for the result.
Parameters
[in]bitsNumber of bits to read.
Returns
The value of the next bits.

◆ getBits() [2/3]

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
INTAn integer type for the result.
Parameters
[out]valueThe value of the next bits.
[in]bitsNumber of bits to read.

◆ getBits() [3/3]

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
void ts::Buffer::getBits ( Variable< INT > &  value,
size_t  bits 
)

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

Template Parameters
INTAn integer type for the result.
Parameters
[out]valueThe value of the next bits as a Variable instance. If no integer can be read, the Variable is unset.
[in]bitsNumber of bits to read.

◆ putBits()

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
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
INTAn integer type.
Parameters
[in]valueInteger value to write.
[in]bitsNumber of 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]bufferAddress of the buffer receiving the read bytes.
[in]bytesNumber 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]bytesNumber 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]bbByte block receiving the read bytes.
[in]bytesNumber 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]bbByte block receiving the read bytes. The read data are appended to bb.
[in]bytesNumber 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]bufferAddress of the data to write.
[in]bytesNumber 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]bbByte block containing the data to write.
[in]startStart in index in bb.
[in]countNumber 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.

◆ getUInt8()

uint8_t ts::Buffer::getUInt8 ( )
inline

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

Set the read error flag if there are not enough bits to read.

Returns
The decoded integer value.

◆ getUInt16()

uint16_t ts::Buffer::getUInt16 ( )
inline

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

Set the read error flag if there are not enough bits to read.

Returns
The decoded integer value, according to the current endianness of the buffer.

◆ getUInt24()

uint32_t ts::Buffer::getUInt24 ( )
inline

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

Set the read error flag if there are not enough bits to read.

Returns
The decoded integer value, according to the current endianness of the buffer.

◆ getUInt32()

uint32_t ts::Buffer::getUInt32 ( )
inline

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

Set the read error flag if there are not enough bits to read.

Returns
The decoded integer value, according to the current endianness of the buffer.

◆ getUInt40()

uint64_t ts::Buffer::getUInt40 ( )
inline

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

Set the read error flag if there are not enough bits to read.

Returns
The decoded integer value, according to the current endianness of the buffer.

◆ getUInt48()

uint64_t ts::Buffer::getUInt48 ( )
inline

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

Set the read error flag if there are not enough bits to read.

Returns
The decoded integer value, according to the current endianness of the buffer.

◆ getUInt64()

uint64_t ts::Buffer::getUInt64 ( )
inline

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

Set the read error flag if there are not enough bits to read.

Returns
The decoded integer value, according to the current endianness of the buffer.

◆ getInt8()

int8_t ts::Buffer::getInt8 ( )
inline

Read the next 8 bits as a signed integer value and advance the read pointer.

Set the read error flag if there are not enough bits to read.

Returns
The decoded integer value.

◆ getInt16()

int16_t ts::Buffer::getInt16 ( )
inline

Read the next 16 bits as a signed integer value and advance the read pointer.

Set the read error flag if there are not enough bits to read.

Returns
The decoded integer value, according to the current endianness of the buffer.

◆ getInt24()

int32_t ts::Buffer::getInt24 ( )
inline

Read the next 24 bits as a signed integer value and advance the read pointer.

Set the read error flag if there are not enough bits to read.

Returns
The decoded integer value, according to the current endianness of the buffer.

◆ getInt32()

int32_t ts::Buffer::getInt32 ( )
inline

Read the next 32 bits as a signed integer value and advance the read pointer.

Set the read error flag if there are not enough bits to read.

Returns
The decoded integer value, according to the current endianness of the buffer.

◆ getInt40()

int64_t ts::Buffer::getInt40 ( )
inline

Read the next 40 bits as a signed integer value and advance the read pointer.

Set the read error flag if there are not enough bits to read.

Returns
The decoded integer value, according to the current endianness of the buffer.

◆ getInt48()

int64_t ts::Buffer::getInt48 ( )
inline

Read the next 48 bits as a signed integer value and advance the read pointer.

Set the read error flag if there are not enough bits to read.

Returns
The decoded integer value, according to the current endianness of the buffer.

◆ getInt64()

int64_t ts::Buffer::getInt64 ( )
inline

Read the next 64 bits as a signed integer value and advance the read pointer.

Set the read error flag if there are not enough bits to read.

Returns
The decoded integer value, according to the current endianness of the buffer.

◆ putUInt8()

bool ts::Buffer::putUInt8 ( uint8_t  i)
inline

Write an 8-bit unsigned integer value and advance the write pointer.

Parameters
[in]i8-bit unsigned integer value to write.
Returns
True on success, false if there is not enough space to write (and set write error flag).

◆ putUInt16()

bool ts::Buffer::putUInt16 ( uint16_t  i)
inline

Write a 16-bit unsigned integer value and advance the write pointer.

Parameters
[in]i16-bit unsigned integer value to write.
Returns
True on success, false if there is not enough space to write (and set write error flag).

◆ putUInt24()

bool ts::Buffer::putUInt24 ( uint32_t  i)
inline

Write a 24-bit unsigned integer value and advance the write pointer.

Parameters
[in]i24-bit unsigned integer value to write.
Returns
True on success, false if there is not enough space to write (and set write error flag).

◆ putUInt32()

bool ts::Buffer::putUInt32 ( uint32_t  i)
inline

Write a 32-bit unsigned integer value and advance the write pointer.

Parameters
[in]i32-bit unsigned integer value to write.
Returns
True on success, false if there is not enough space to write (and set write error flag).

◆ putUInt40()

bool ts::Buffer::putUInt40 ( uint64_t  i)
inline

Write a 40-bit unsigned integer value and advance the write pointer.

Parameters
[in]i40-bit unsigned integer value to write.
Returns
True on success, false if there is not enough space to write (and set write error flag).

◆ putUInt48()

bool ts::Buffer::putUInt48 ( uint64_t  i)
inline

Write a 48-bit unsigned integer value and advance the write pointer.

Parameters
[in]i48-bit unsigned integer value to write.
Returns
True on success, false if there is not enough space to write (and set write error flag).

◆ putUInt64()

bool ts::Buffer::putUInt64 ( uint64_t  i)
inline

Write a 64-bit unsigned integer value and advance the write pointer.

Parameters
[in]i64-bit unsigned integer value to write.
Returns
True on success, false if there is not enough space to write (and set write error flag).

◆ putInt8()

bool ts::Buffer::putInt8 ( int8_t  i)
inline

Write an 8-bit signed integer value and advance the write pointer.

Parameters
[in]i8-bit signed integer value to write.
Returns
True on success, false if there is not enough space to write (and set write error flag).

◆ putInt16()

bool ts::Buffer::putInt16 ( int16_t  i)
inline

Write a 16-bit signed integer value and advance the write pointer.

Parameters
[in]i16-bit signed integer value to write.
Returns
True on success, false if there is not enough space to write (and set write error flag).

◆ putInt24()

bool ts::Buffer::putInt24 ( int32_t  i)
inline

Write a 24-bit signed integer value and advance the write pointer.

Parameters
[in]i24-bit signed integer value to write.
Returns
True on success, false if there is not enough space to write (and set write error flag).

◆ putInt32()

bool ts::Buffer::putInt32 ( int32_t  i)
inline

Write a 32-bit signed integer value and advance the write pointer.

Parameters
[in]i32-bit signed integer value to write.
Returns
True on success, false if there is not enough space to write (and set write error flag).

◆ putInt40()

bool ts::Buffer::putInt40 ( int64_t  i)
inline

Write a 40-bit signed integer value and advance the write pointer.

Parameters
[in]i40-bit signed integer value to write.
Returns
True on success, false if there is not enough space to write (and set write error flag).

◆ putInt48()

bool ts::Buffer::putInt48 ( int64_t  i)
inline

Write a 48-bit signed integer value and advance the write pointer.

Parameters
[in]i48-bit signed integer value to write.
Returns
True on success, false if there is not enough space to write (and set write error flag).

◆ putInt64()

bool ts::Buffer::putInt64 ( int64_t  i)
inline

Write a 64-bit signed integer value and advance the write pointer.

Parameters
[in]i64-bit signed integer value to write.
Returns
True on success, false if there is not enough space to write (and set write error flag).

◆ getBCD() [1/2]

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
INT ts::Buffer::getBCD ( size_t  bcd_count)

Read the next 4*n bits as a Binary Coded Decimal (BCD) value and advance the read pointer.

If an invalid BCD digit is found, the read error state of the buffer is set after reading all BCD digits.

Template Parameters
INTAn integer type.
Parameters
[in]bcd_countNumber of BCD digits (bcd_count * 4 bits).
Returns
The decoded BCD value or zero in case of error.

◆ getBCD() [2/2]

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
bool ts::Buffer::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.

If an invalid BCD digit is found, the read error state of the buffer is set after reading all BCD digits.

Template Parameters
INTAn integer type.
Parameters
[out]valueThe decoded BCD value or zero in case of error.
[in]bcd_countNumber of BCD digits (bcd_count * 4 bits).
Returns
True on success, false on error.

◆ putBCD()

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
bool ts::Buffer::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.

Template Parameters
INTAn integer type.
Parameters
[in]valueInteger value to write.
[in]bcd_countNumber of BCD digits (bcd_count * 4 bits).
Returns
True on success, false on error (read only or no more space to write).

◆ tryGetASCII() [1/2]

bool ts::Buffer::tryGetASCII ( UString result,
size_t  bytes = NPOS 
)

Try to get an ASCII string.

The read-pointer must be byte-aligned. If all bytes are valid ASCII characters (optionally zero-padded), the corresponding string is returned and the read pointer is moved. If the corresponding area is not a valid ASCII string (optionally zero-padded), do not move the read pointer and return an empty string.

Parameters
[out]resultReturned ASCII string. If the binary area is zero-padded, the trailing zeroes are not included in the string. This means that result can be shorter than bytes.
[in]bytesSize in bytes of the string. If specified as NPOS (the default), read up to the end of the buffer. If different from NPOS, the exact number of bytes must be available or a read error is generated.
Returns
True on success, false on error. Also return false when the binary area is not a valid ASCII string (optionally zero-padded), but do not generate a read error (it was just a try).

◆ tryGetASCII() [2/2]

UString ts::Buffer::tryGetASCII ( size_t  bytes = NPOS)

Try to get an ASCII string.

The read-pointer must be byte-aligned. If all bytes are valid ASCII characters (optionally zero-padded), the corresponding string is returned and the read pointer is moved. If the corresponding area is not a valid ASCII string (optionally zero-padded), do not move the read pointer and return an empty string.

Parameters
[in]bytesSize in bytes of the string. If specified as NPOS (the default), read up to the end of the buffer. If different from NPOS, the exact number of bytes must be available or a read error is generated.
Returns
The ASCII string. If the binary area is zero-padded, the trailing zeroes are not included in the string. This means that result can be shorter than bytes. Return an empty string when the entire binary area is not a valid ASCII string (optionally zero-padded), but do not generate a read error (it was just a try).

◆ getUTF8() [1/2]

bool ts::Buffer::getUTF8 ( UString result,
size_t  bytes = NPOS 
)
inline

Get a UTF-8 string.

The read-pointer must be byte-aligned.

Parameters
[out]resultReturned decoded string.
[in]bytesSize in bytes of the encoded UTF-8 string. If specified as NPOS (the default), read up to the end of the buffer. If different from NPOS, the exact number of bytes must be available or a read error is generated.
Returns
True on success, false on error.

◆ getUTF8() [2/2]

UString ts::Buffer::getUTF8 ( size_t  bytes = NPOS)
inline

Get a UTF-8 string.

The read-pointer must be byte-aligned.

Parameters
[in]bytesSize in bytes of the encoded UTF-8 string. If specified as NPOS (the default), read up to the end of the buffer. If different from NPOS, the exact number of bytes must be available or a read error is generated.
Returns
The decoded string.

◆ getUTF8WithLength() [1/2]

bool ts::Buffer::getUTF8WithLength ( UString result,
size_t  length_bits = 8 
)
inline

Get a UTF-8 string (preceded by its length).

The read-pointer must be byte-aligned after reading the length-field. The specified number of bytes must be available or a read error is generated.

Parameters
[out]resultReturned decoded string.
[in]length_bitsSize in bits in the length field.
Returns
True on success, false on error (truncated, unsupported format, etc.)

◆ getUTF8WithLength() [2/2]

UString ts::Buffer::getUTF8WithLength ( size_t  length_bits = 8)
inline

Get a UTF-8 string (preceded by its length).

The read-pointer must be byte-aligned after reading the length-field. The specified number of bytes must be available or a read error is generated.

Parameters
[in]length_bitsSize in bits in the length field.
Returns
The decoded string.

◆ getUTF16() [1/2]

bool ts::Buffer::getUTF16 ( UString result,
size_t  bytes = NPOS 
)
inline

Get a UTF-16 string.

The read-pointer must be byte-aligned.

Parameters
[out]resultReturned decoded string.
[in]bytesSize in bytes of the encoded UTF-16 string. If specified as NPOS (the default), read up to the end of the buffer. If different from NPOS, the exact number of bytes must be available or a read error is generated. If bytes is an odd value, the last byte is skipped and ignored.
Returns
True on success, false on error.

◆ getUTF16() [2/2]

UString ts::Buffer::getUTF16 ( size_t  bytes = NPOS)
inline

Get a UTF-16 string.

The read-pointer must be byte-aligned.

Parameters
[in]bytesSize in bytes of the encoded UTF-16 string. If specified as NPOS (the default), read up to the end of the buffer. If different from NPOS, the exact number of bytes must be available or a read error is generated. If bytes is an odd value, the last byte is skipped and ignored.
Returns
The decoded string.

◆ getUTF16WithLength() [1/2]

bool ts::Buffer::getUTF16WithLength ( UString result,
size_t  length_bits = 8 
)
inline

Get a UTF-16 string (preceded by its length).

The read-pointer must be byte-aligned after reading the length-field. The specified number of bytes must be available or a read error is generated. If the extracted length is an odd value, the last byte is skipped and ignored.

Parameters
[out]resultReturned decoded string.
[in]length_bitsSize in bits in the length field.
Returns
True on success, false on error (truncated, unsupported format, etc.)

◆ getUTF16WithLength() [2/2]

UString ts::Buffer::getUTF16WithLength ( size_t  length_bits = 8)
inline

Get a UTF-16 string (preceded by its length).

The read-pointer must be byte-aligned after reading the length-field. The specified number of bytes must be available or a read error is generated. If the extracted length is an odd value, the last byte is skipped and ignored.

Parameters
[in]length_bitsSize in bits in the length field.
Returns
The decoded string.

◆ putUTF8()

bool ts::Buffer::putUTF8 ( const UString str,
size_t  start = 0,
size_t  count = NPOS 
)
inline

Put a string using UTF-8 format.

The write-pointer must be byte-aligned. Generate a write error when the buffer is full before writing the complete string.

Parameters
[in]strThe UTF-16 string to encode.
[in]startStarting offset to convert in this UTF-16 string.
[in]countMaximum number of characters to convert.
Returns
True on success, false if there is not enough space to write (and set write error flag).

◆ putFixedUTF8()

bool ts::Buffer::putFixedUTF8 ( const UString str,
size_t  size,
uint8_t  pad = 0,
size_t  start = 0,
size_t  count = NPOS 
)
inline

Put a string using UTF-8 format with a fixed binary size (truncate or pad).

The write-pointer must be byte-aligned. Generate a write error when the buffer is full before writing the complete string.

Parameters
[in]strThe UTF-16 string to encode.
[in]sizeFixed size in bytes to fill. If str cannot be fully serialized, it is truncated.
[in]padIt str does not fill size bytes, pad the remaining bytes with this value.
[in]startStarting offset to convert in this UTF-16 string.
[in]countMaximum number of characters to convert.
Returns
True on success, false if there is not enough space to write (and set write error flag).

◆ putPartialUTF8()

size_t ts::Buffer::putPartialUTF8 ( const UString str,
size_t  start = 0,
size_t  count = NPOS 
)
inline

Put a partial string using UTF-8 format.

The write-pointer must be byte-aligned. Stop either when this string is serialized or when the buffer is full, whichever comes first. Do not generate a write error when the buffer is full.

Parameters
[in]strThe UTF-16 string to encode.
[in]startStarting offset to convert in this UTF-16 string.
[in]countMaximum number of characters to convert.
Returns
The number of serialized characters (which is usually not the same as the number of written bytes).

◆ putUTF8WithLength()

bool ts::Buffer::putUTF8WithLength ( const UString str,
size_t  start = 0,
size_t  count = NPOS,
size_t  length_bits = 8 
)
inline

Put a string (preceded by its length) using UTF-8 format.

The write-pointer must be byte-aligned after writing the length-field. Generate a write error when the buffer is full before writing the complete string.

Parameters
[in]strThe UTF-16 string to encode.
[in]startStarting offset to convert in this UTF-16 string.
[in]countMaximum number of characters to convert.
[in]length_bitsSize in bits in the length field.
Returns
True on success, false if there is not enough space to write (and set write error flag).

◆ putPartialUTF8WithLength()

size_t ts::Buffer::putPartialUTF8WithLength ( const UString str,
size_t  start = 0,
size_t  count = NPOS,
size_t  length_bits = 8 
)
inline

Put a partial string (preceded by its length) using UTF-8 format.

The write-pointer must be byte-aligned after writing the length-field. Do not generate a write error when the buffer is full.

Parameters
[in]strThe UTF-16 string to encode.
[in]startStarting offset to convert in this UTF-16 string.
[in]countMaximum number of characters to convert.
[in]length_bitsSize in bits in the length field.
Returns
The number of serialized characters (which is usually not the same as the number of written bytes).

◆ putUTF16()

bool ts::Buffer::putUTF16 ( const UString str,
size_t  start = 0,
size_t  count = NPOS 
)
inline

Put a string using UTF-16 format.

The write-pointer must be byte-aligned. Generate a write error when the buffer is full before writing the complete string.

Parameters
[in]strThe UTF-16 string to encode.
[in]startStarting offset to convert in this UTF-16 string.
[in]countMaximum number of characters to convert.
Returns
True on success, false if there is not enough space to write (and set write error flag).

◆ putFixedUTF16()

bool ts::Buffer::putFixedUTF16 ( const UString str,
size_t  size,
uint16_t  pad = 0,
size_t  start = 0,
size_t  count = NPOS 
)
inline

Put a string using UTF-16 format with a fixed binary size (truncate or pad).

The write-pointer must be byte-aligned. Generate a write error when the buffer is full before writing the complete string.

Parameters
[in]strThe UTF-16 string to encode.
[in]sizeFixed size in bytes to fill. If str cannot be fully serialized, it is truncated.
[in]padIt str does not fill size bytes, serialize the remaining UTF-16 characters with this value. If size has an odd value, the last byte is padded with the least significant byte of pad.
[in]startStarting offset to convert in this UTF-16 string.
[in]countMaximum number of characters to convert.
Returns
True on success, false if there is not enough space to write (and set write error flag).

◆ putPartialUTF16()

size_t ts::Buffer::putPartialUTF16 ( const UString str,
size_t  start = 0,
size_t  count = NPOS 
)
inline

Put a partial string using UTF-8 format.

The write-pointer must be byte-aligned. Stop either when this string is serialized or when the buffer is full, whichever comes first. Do not generate a write error when the buffer is full.

Parameters
[in]strThe UTF-16 string to encode.
[in]startStarting offset to convert in this UTF-16 string.
[in]countMaximum number of characters to convert.
Returns
The number of serialized characters (which is usually not the same as the number of written bytes).

◆ putUTF16WithLength()

bool ts::Buffer::putUTF16WithLength ( const UString str,
size_t  start = 0,
size_t  count = NPOS,
size_t  length_bits = 8 
)
inline

Put a string (preceded by its length) using UTF-16 format.

The write-pointer must be byte-aligned after writing the length-field. Generate a write error when the buffer is full before writing the complete string.

Parameters
[in]strThe UTF-16 string to encode.
[in]startStarting offset to convert in this UTF-16 string.
[in]countMaximum number of characters to convert.
[in]length_bitsSize in bits in the length field.
Returns
True on success, false if there is not enough space to write (and set write error flag).

◆ putPartialUTF16WithLength()

size_t ts::Buffer::putPartialUTF16WithLength ( const UString str,
size_t  start = 0,
size_t  count = NPOS,
size_t  length_bits = 8 
)
inline

Put a partial string (preceded by its length) using UTF-16 format.

The write-pointer must be byte-aligned after writing the length-field. Do not generate a write error when the buffer is full.

Parameters
[in]strThe UTF-16 string to encode.
[in]startStarting offset to convert in this UTF-16 string.
[in]countMaximum number of characters to convert.
[in]length_bitsSize in bits in the length field.
Returns
The number of serialized characters (which is usually not the same as the number of written bytes).

◆ currentWriteAddress()

uint8_t* ts::Buffer::currentWriteAddress ( ) const
inlineprotected

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

This operation is reserved to subclasses. Applications can only get a read-only pointer to the current read area (see currentReadAddress()).

Returns
The starting address of current write area.

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