Contiguous append-only stream accumulator with a logical read offset and parser scratch state. More...

#include <stream_buffer.h>

Public Member Functions
	StreamBuffer (std::size_t compact_threshold=4096)
	Constructs an empty stream buffer. More...

template<typename D >
void	InitAny ()
	Initialize the parsed data. More...

template<typename D >
void	InitAnyB ()
	Initializes the secondary parser scratch object as `D`. More...

template<typename D >
void	InitAny (uint64_t type)
	Initialize the parsed data and type. More...

template<typename D >
D &	GetAny ()
	Get the parsed data. More...

template<typename D >
D &	GetAnyB ()
	Gets the secondary parser scratch object. More...

std::optional< uint64_t >	GetAnyType ()
	Get the user defined parsed type value. More...

void	SetAnyType (uint64_t type)
	Set the user-defined parsed data type value. More...

void	Clear ()
	Clears unread data and all parser scratch state. More...

void	ResetAny ()
	Clears both parser scratch objects and the optional parser type without changing stream data. More...

void	ResetAnyB ()
	Clears only the secondary parser scratch object. More...

template<class D >
void	ResetAnyB ()
	Replaces the secondary parser scratch object with a default-constructed `D`. More...

bool	AnyHasValue ()

bool	AnyHasValueB ()

bool	Empty () const noexcept

size_t	Size () noexcept

std::span< const T >	Front () noexcept
	Get the first data byte in stream buffer. More...

std::span< const T >	Front (std::size_t length) noexcept
	Front length number of data bytes. More...

std::span< const T >	Data () noexcept
	All readable data bytes in the stream buffer. More...

BufferT	TakeAll ()
	Surrender everything not yet read, leaving the buffer empty. More...

void	Pop ()
	Consumes one unread element, or does nothing when empty. More...

void	Pop (std::size_t length)
	Consumes up to `length` unread elements. More...

bool	Available (std::size_t length) const noexcept
	Checks if length bytes are available for front. More...

void	Push (const T &value)
	Copies one value to the back of the stream. More...

void	Push (T &&value)
	Moves one value to the back of the stream. More...

void	Push (std::span< const T > value)
	Appends a copy of a contiguous value range. More...

void	PushLengthBytes (std::span< const T > value)
	Appends a QUIC variable-length count followed by the supplied values. More...

std::optional< uint64_t >	DecodeUintV (bool pop=true)

std::optional< UintVar >	ReadUintV (bool pop=true)

std::optional< std::vector< uint8_t > >	DecodeBytes ()

Detailed Description

template<typename T, class Allocator = std::allocator<T>>
class quicr::StreamBuffer< T, Allocator >

Contiguous append-only stream accumulator with a logical read offset and parser scratch state.

Template Parameters

T	Element type; QUIC variable-length decoding requires a byte-compatible integral type.
Allocator	Allocator for the underlying vector.

Pop operations normally advance a logical offset. A later push compacts consumed storage once the offset reaches the configured threshold or exceeds the unread size. The class is not thread-safe. Spans and references returned by accessors are invalidated by compaction, reallocation, clear, or destruction.

Constructor & Destructor Documentation

◆ StreamBuffer()

template<typename T , class Allocator = std::allocator<T>>

quicr::StreamBuffer< T, Allocator >::StreamBuffer ( std::size_t compact_threshold = 4096 )

inline

Constructs an empty stream buffer.

Parameters

compact_threshold Minimum consumed prefix that can trigger compaction on a later push.

Member Function Documentation

◆ AnyHasValue()

template<typename T , class Allocator = std::allocator<T>>

bool quicr::StreamBuffer< T, Allocator >::AnyHasValue ( )

inline

Returns: Whether the primary parser scratch object contains a value.

◆ AnyHasValueB()

template<typename T , class Allocator = std::allocator<T>>

bool quicr::StreamBuffer< T, Allocator >::AnyHasValueB ( )

inline

Returns: Whether the secondary parser scratch object contains a value.

◆ Available()

template<typename T , class Allocator = std::allocator<T>>

bool quicr::StreamBuffer< T, Allocator >::Available ( std::size_t length ) const

inlinenoexcept

Checks if length bytes are available for front.

Parameters

length length of bytes needed

Returns: True if data length is available, false if not.

◆ Clear()

template<typename T , class Allocator = std::allocator<T>>

void quicr::StreamBuffer< T, Allocator >::Clear ( )

inline

Clears unread data and all parser scratch state.

Note: Retained vector capacity is implementation-dependent; all returned spans are invalidated.

◆ Data()

template<typename T , class Allocator = std::allocator<T>>

std::span<const T> quicr::StreamBuffer< T, Allocator >::Data ( )

inlinenoexcept

All readable data bytes in the stream buffer.

Returns: Span of all unread elements, or an empty span.

◆ DecodeBytes()

template<typename T , class Allocator = std::allocator<T>>

std::optional<std::vector<uint8_t> > quicr::StreamBuffer< T, Allocator >::DecodeBytes ( )

inline

Decodes a variable length array of uint8_t bytes from start of stream buffer

Reads uintV from stream buffer to get the length of the byte array. Then reads byte array from stream buffer after the uintV length. Vector of bytes will be returned if all bytes are available. Otherwise nullopt will be returned to indicate not enough bytes available.

Returns: Returns vector<uint8_t> or nullopt if not enough bytes are available

Note: The length prefix and payload are consumed only when the complete payload is available.

Exceptions

Any	exception thrown while constructing the result vector.

◆ DecodeUintV()

template<typename T , class Allocator = std::allocator<T>>

std::optional<uint64_t> quicr::StreamBuffer< T, Allocator >::DecodeUintV ( bool pop = true )

inline

Decodes a variable length int (uintV) from start of stream buffer

Reads uintV from stream buffer. If all bytes are available, the unsigned 64bit integer will be returned and the buffer will be moved past the uintV. Nullopt will be returned if not enough bytes are available.

Parameters

pop	True to move the buffer past the uintV.

Returns: Returns uint64 decoded value or nullopt if not enough bytes are available

◆ Empty()

template<typename T , class Allocator = std::allocator<T>>

bool quicr::StreamBuffer< T, Allocator >::Empty ( ) const

inlinenoexcept

Returns: true when no unread elements remain.

◆ Front() [1/2]

template<typename T , class Allocator = std::allocator<T>>

std::span<const T> quicr::StreamBuffer< T, Allocator >::Front ( )

inlinenoexcept

Get the first data byte in stream buffer.

Returns: One-element span of the first unread value, or an empty span if no data is available.

◆ Front() [2/2]

template<typename T , class Allocator = std::allocator<T>>

std::span<const T> quicr::StreamBuffer< T, Allocator >::Front ( std::size_t length )

inlinenoexcept

Front length number of data bytes.

Parameters

length Get the first up to length number of data bytes

Returns: Span of exactly length unread elements, or an empty span if fewer are available.

Note: A zero length request returns an empty span regardless of availability.

◆ GetAny()

template<typename T , class Allocator = std::allocator<T>>

template<typename D >

D& quicr::StreamBuffer< T, Allocator >::GetAny ( )

inline

Get the parsed data.

Parsed data allows the caller to work on reading data from the stream buffer. The datatype is any to support the caller data types. This returns a reference to the any variable cast to the data type

Template Parameters

D	Data type of value

Returns: Mutable reference to the primary parser scratch object.

Exceptions

std::bad_any_cast If the stored object is not exactly D.

◆ GetAnyB()

template<typename T , class Allocator = std::allocator<T>>

template<typename D >

D& quicr::StreamBuffer< T, Allocator >::GetAnyB ( )

inline

Gets the secondary parser scratch object.

Template Parameters

D	Exact stored type.

Returns: Mutable reference valid until the secondary object is reset or the buffer is destroyed.

Exceptions

std::bad_any_cast If the stored object is not exactly D.

◆ GetAnyType()

template<typename T , class Allocator = std::allocator<T>>

std::optional<uint64_t> quicr::StreamBuffer< T, Allocator >::GetAnyType ( )

inline

Get the user defined parsed type value.

Returns: Parsed data type value, or std::nullopt if none was set.

◆ InitAny() [1/2]

template<typename T , class Allocator = std::allocator<T>>

template<typename D >

void quicr::StreamBuffer< T, Allocator >::InitAny ( )

inline

Initialize the parsed data.

Parsed data allows the caller to work on reading data from the stream buffer. The datatype is any to support the caller data types. This method will initialize the parsed data using the type specified

Template Parameters

D	Data type for value

Exceptions

Any	exception thrown by constructing `D`.

◆ InitAny() [2/2]

template<typename T , class Allocator = std::allocator<T>>

template<typename D >

void quicr::StreamBuffer< T, Allocator >::InitAny ( uint64_t type )

inline

Initialize the parsed data and type.

Template Parameters

D	Data type for value

Parameters

type	user defined type value for the parsed data any object

Exceptions

Any	exception thrown by constructing `D`.

◆ InitAnyB()

template<typename T , class Allocator = std::allocator<T>>

template<typename D >

void quicr::StreamBuffer< T, Allocator >::InitAnyB ( )

inline

Initializes the secondary parser scratch object as D.

Template Parameters

D	Type constructed in place.

Exceptions

Any	exception thrown by constructing `D`.

◆ Pop() [1/2]

template<typename T , class Allocator = std::allocator<T>>

void quicr::StreamBuffer< T, Allocator >::Pop ( )

inline

Consumes one unread element, or does nothing when empty.

◆ Pop() [2/2]

template<typename T , class Allocator = std::allocator<T>>

void quicr::StreamBuffer< T, Allocator >::Pop ( std::size_t length )

inline

Consumes up to length unread elements.

Parameters

length Requested count; zero does nothing. A count at least as large as the unread size empties the buffer.

◆ Push() [1/3]

template<typename T , class Allocator = std::allocator<T>>

void quicr::StreamBuffer< T, Allocator >::Push ( const T & value )

inline

Copies one value to the back of the stream.

Parameters

value Value to append.

Exceptions

Any	exception thrown by compaction, allocation, or copying.

◆ Push() [2/3]

template<typename T , class Allocator = std::allocator<T>>

void quicr::StreamBuffer< T, Allocator >::Push ( std::span< const T > value )

inline

Appends a copy of a contiguous value range.

Parameters

value Source values.

Precondition: value does not alias this buffer's storage, because compaction or reallocation can invalidate it.

Exceptions

Any	exception thrown by compaction, allocation, or copying.

◆ Push() [3/3]

template<typename T , class Allocator = std::allocator<T>>

void quicr::StreamBuffer< T, Allocator >::Push ( T && value )

inline

Moves one value to the back of the stream.

Parameters

value Value to append.

Exceptions

Any	exception thrown by compaction, allocation, or moving.

◆ PushLengthBytes()

template<typename T , class Allocator = std::allocator<T>>

void quicr::StreamBuffer< T, Allocator >::PushLengthBytes ( std::span< const T > value )

inline

Appends a QUIC variable-length count followed by the supplied values.

Parameters

value Values whose element count is encoded first.

Precondition: T can represent the encoded bytes and value does not alias this buffer's storage.

Exceptions

Any	exception thrown by `UintVar`, compaction, allocation, or copying.

◆ ReadUintV()

template<typename T , class Allocator = std::allocator<T>>

std::optional<UintVar> quicr::StreamBuffer< T, Allocator >::ReadUintV ( bool pop = true )

inline

Reads a variable length int (uintV) from start of stream buffer

Reads uintV from stream buffer. If all bytes are available, the encoded uintV will be returned and the buffer will be moved past the uintV. Nullopt will be returned if not enough bytes are available.

Parameters

pop	True to move the buffer past the uintV.

Returns: Returns uintV or nullopt if not enough bytes are available

◆ ResetAny()

template<typename T , class Allocator = std::allocator<T>>

void quicr::StreamBuffer< T, Allocator >::ResetAny ( )

inline

Clears both parser scratch objects and the optional parser type without changing stream data.

◆ ResetAnyB() [1/2]

template<typename T , class Allocator = std::allocator<T>>

void quicr::StreamBuffer< T, Allocator >::ResetAnyB ( )

inline

Clears only the secondary parser scratch object.

◆ ResetAnyB() [2/2]

template<typename T , class Allocator = std::allocator<T>>

template<class D >

void quicr::StreamBuffer< T, Allocator >::ResetAnyB ( )

inline

Replaces the secondary parser scratch object with a default-constructed D.

Template Parameters

D	New scratch type.

Exceptions

Any	exception thrown by constructing `D`.

◆ SetAnyType()

template<typename T , class Allocator = std::allocator<T>>

void quicr::StreamBuffer< T, Allocator >::SetAnyType ( uint64_t type )

inline

Set the user-defined parsed data type value.

Parameters

type	User defined value for the data type

◆ Size()

template<typename T , class Allocator = std::allocator<T>>

size_t quicr::StreamBuffer< T, Allocator >::Size ( )

inlinenoexcept

Returns: Number of unread elements.

◆ TakeAll()

template<typename T , class Allocator = std::allocator<T>>

BufferT quicr::StreamBuffer< T, Allocator >::TakeAll ( )

inline

Surrender everything not yet read, leaving the buffer empty.

For a caller that takes the whole of what has arrived rather than reading messages out of it one at a time, which costs nothing once it has read what came before. What has been parsed so far is left alone, since that is what says how the stream is being read rather than what is left to read.

Returns: The bytes not yet read

When no prefix has been consumed this may transfer the underlying allocation; otherwise it copies unread elements. Parser scratch state is preserved. All previously returned spans are invalidated.

Exceptions

Any	exception thrown while allocating or copying unread elements.

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

include/quicr/containers/stream_buffer.h

Public Member Functions

Detailed Description

template<typename T, class Allocator = std::allocator<T>> class quicr::StreamBuffer< T, Allocator >

Constructor & Destructor Documentation

◆ StreamBuffer()

Member Function Documentation

◆ AnyHasValue()

◆ AnyHasValueB()

◆ Available()

◆ Clear()

◆ Data()

◆ DecodeBytes()

◆ DecodeUintV()

◆ Empty()

◆ Front() [1/2]

◆ Front() [2/2]

◆ GetAny()

◆ GetAnyB()

◆ GetAnyType()

◆ InitAny() [1/2]

◆ InitAny() [2/2]

◆ InitAnyB()

◆ Pop() [1/2]

◆ Pop() [2/2]

◆ Push() [1/3]

◆ Push() [2/3]

◆ Push() [3/3]

◆ PushLengthBytes()

◆ ReadUintV()

◆ ResetAny()

◆ ResetAnyB() [1/2]

◆ ResetAnyB() [2/2]

◆ SetAnyType()

◆ Size()

◆ TakeAll()

template<typename T, class Allocator = std::allocator<T>>
class quicr::StreamBuffer< T, Allocator >