Fixed-size 128-byte buffer holder with SBO, five ownership modes and integrated codecs. More...

#include <bytes.h>

Collaboration diagram for vlink::Bytes:

Public Member Functions
	Bytes () noexcept
	Constructs an empty, non-owning carrier with no payload. More...

	Bytes (const Bytes &target) noexcept
	Copy constructor; converts any source into an owned deep copy. More...

	Bytes (Bytes &&target) noexcept
	Move constructor; transfers payload, ownership flags and prefix from `target`. More...

	Bytes (const std::initializer_list< uint8_t > &list) noexcept
	Constructs an owned buffer from an initialiser list of bytes. More...

	Bytes (const std::vector< uint8_t > &data) noexcept
	Constructs an owned buffer from a `std::vector<uint8_t>` by deep copy. More...

	~Bytes () noexcept
	Destructor; releases owned heap storage and ignores loaned / shallow buffers. More...

Bytes &	operator= (const Bytes &target) noexcept
	Copy assignment; converts any source into an owned deep copy of `target`. More...

Bytes &	operator= (Bytes &&target) noexcept
	Move assignment; releases the current buffer and adopts `target's` state. More...

Bytes &	operator= (const std::vector< uint8_t > &data) noexcept
	Replaces the payload with a deep copy of `data`. More...

bool	operator== (const Bytes &target) const noexcept
	Byte-wise equality comparison with another `Bytes`. More...

bool	operator!= (const Bytes &target) const noexcept
	Byte-wise inequality comparison with another `Bytes`. More...

bool	operator== (const std::vector< uint8_t > &data) const noexcept
	Byte-wise equality comparison with a `std::vector<uint8_t>`. More...

bool	operator!= (const std::vector< uint8_t > &data) const noexcept
	Byte-wise inequality comparison with a `std::vector<uint8_t>`. More...

uint8_t &	operator[] (size_t index) noexcept
	Mutable indexed access into the payload region. More...

const uint8_t &	operator[] (size_t index) const noexcept
	Read-only indexed access into the payload region. More...

uint8_t *	data () noexcept
	Returns a mutable pointer to the start of the payload (post-offset). More...

const uint8_t *	data () const noexcept
	Returns a read-only pointer to the start of the payload (post-offset). More...

uint8_t *	real_data () noexcept
	Returns a mutable pointer to the very beginning of the backing buffer. More...

const uint8_t *	real_data () const noexcept
	Returns a read-only pointer to the very beginning of the backing buffer. More...

size_t	size () const noexcept
	Returns the size of the payload region in bytes. More...

size_t	real_size () const noexcept
	Returns the size of the used backing region (payload plus prefix offset). More...

size_t	capacity () const noexcept
	Returns the allocated capacity of the backing buffer. More...

uint8_t	offset () const noexcept
	Returns the reserved header offset preceding the payload. More...

bool	is_owner () const noexcept
	Reports whether this instance owns and will free its storage. More...

bool	is_loaned () const noexcept
	Reports whether the buffer is an iceoryx loan that VLink must not free. More...

bool	empty () const noexcept
	Reports whether the buffer is logically empty. More...

uint8_t *	begin () noexcept
	Returns a mutable iterator to the first payload byte. More...

const uint8_t *	begin () const noexcept
	Returns a read-only iterator to the first payload byte. More...

uint8_t *	end () noexcept
	Returns a mutable iterator one past the last payload byte. More...

const uint8_t *	end () const noexcept
	Returns a read-only iterator one past the last payload byte. More...

uint8_t *	real_begin () noexcept
	Returns a mutable iterator to the start of the raw backing region. More...

const uint8_t *	real_begin () const noexcept
	Returns a read-only iterator to the start of the raw backing region. More...

uint8_t *	real_end () noexcept
	Returns a mutable iterator one past the prefix-plus-payload region. More...

const uint8_t *	real_end () const noexcept
	Returns a read-only iterator one past the prefix-plus-payload region. More...

bool	is_ptr () const noexcept
	Reports whether this carrier merely wraps an opaque pointer. More...

std::vector< uint8_t >	to_raw_data () const noexcept
	Copies the payload region into a new `std::vector<uint8_t>`. More...

std::string	to_string () const noexcept
	Materialises the payload region as a new `std::string`. More...

std::string_view	to_string_view () const noexcept
	Returns a non-owning `std::string_view` into the payload region. More...

template<typename T = void>
T *	to_ptr () const noexcept
	Reinterprets the backing pointer as `T*`. More...

void	clear () noexcept
	Releases owned storage and resets all metadata to the empty state. More...

bool	shrink_to (size_t size) noexcept
	Truncates the logical payload size in place without reallocating. More...

bool	reserve (size_t new_capacity) noexcept
	Ensures the backing capacity is at least `new_capacity` bytes. More...

bool	resize (size_t size) noexcept
	Resizes the logical payload region to `size` bytes. More...

Bytes &	shallow_copy (const Bytes &bytes) noexcept
	Replaces this instance with a non-owning alias of `bytes`. More...

Bytes &	deep_copy (const Bytes &bytes) noexcept
	Replaces this instance with an owned deep copy of `bytes`. More...

Bytes &	deep_copy_self () noexcept
	Converts an existing non-owning carrier into an owning one in place. More...

Static Public Member Functions
static void	init_memory_pool () noexcept
	Eagerly constructs the process-wide `MemoryPool` that backs heap allocations. More...

static void	release_memory_pool () noexcept
	Releases every empty chunk currently cached by the `Bytes` memory pool. More...

static uint8_t *	bytes_malloc (size_t size) noexcept
	Allocates a raw aligned byte buffer through the global memory pool. More...

static void	bytes_free (uint8_t *ptr, size_t size) noexcept
	Returns a buffer previously obtained from `bytes_malloc` to the pool. More...

static Bytes	create (size_t size, uint8_t offset=0) noexcept
	Allocates an owned buffer of the requested size with an optional header offset. More...

static Bytes	shallow_copy (uint8_t *data, size_t size) noexcept
	Wraps an external mutable buffer as a non-owning alias. More...

static Bytes	shallow_copy (const uint8_t *data, size_t size) noexcept
	Wraps an external read-only buffer as a non-owning alias. More...

static Bytes	shallow_copy_ptr (void *data) noexcept
	Wraps an opaque pointer as a zero-size pointer carrier. More...

static Bytes	deep_copy (uint8_t *data, size_t size, uint8_t offset=0) noexcept
	Produces an owned copy of an external mutable buffer. More...

static Bytes	deep_copy (const uint8_t *data, size_t size, uint8_t offset=0) noexcept
	Produces an owned copy of an external read-only buffer. More...

static Bytes	loan_internal (uint8_t *data, size_t size) noexcept
	Wraps an iceoryx-loaned mutable payload as a non-owning, non-aliasing carrier. More...

static Bytes	loan_internal (const uint8_t *data, size_t size) noexcept
	Wraps an iceoryx-loaned read-only payload as a non-owning, non-aliasing carrier. More...

static Bytes	from_string (const std::string &str, uint8_t offset=0) noexcept
	Builds an owned `Bytes` from the bytes of a UTF-8 string. More...

static Bytes	from_user_input (const std::string &str, bool *ok=nullptr) noexcept
	Parses a user-typed hex literal into a `Bytes` payload. More...

static std::string	convert_to_hex_str (const uint8_t *value, size_t size) noexcept
	Renders a raw byte array as space-separated uppercase hex tokens. More...

static Bytes	reverse_order (const Bytes &target) noexcept
	Returns a new owned `Bytes` with the byte order of `target` reversed. More...

static std::string	encode_to_base64 (const Bytes &target) noexcept
	Encodes a payload as a standard Base-64 ASCII string. More...

static Bytes	decode_from_base64 (const std::string &target) noexcept
	Decodes a Base-64 ASCII string back into a binary payload. More...

static uint32_t	get_crc_32 (const Bytes &target) noexcept
	Computes the CRC-32 (ISO-HDLC) checksum of `target`. More...

static uint64_t	get_crc_64 (const Bytes &target) noexcept
	Computes the CRC-64 (ECMA-182) checksum of `target`. More...

static constexpr uint8_t	stack_size () noexcept
	Returns the SBO threshold below which payloads stay inline. More...

static constexpr bool	is_little_endian () noexcept
	Returns `true` at compile time when the platform is little-endian. More...

static constexpr bool	is_big_endian () noexcept
	Returns `true` at compile time when the platform is big-endian. More...

static bool	is_compress_data (const uint8_t *data, size_t size) noexcept
	Detects whether a raw byte buffer matches the VLink LZAV compression frame layout. More...

static Bytes	compress_data (const uint8_t *data, size_t size, bool high_ratio=false) noexcept
	Compresses a payload using LZAV and wraps it in the VLink compression frame. More...

static Bytes	uncompress_data (const uint8_t *data, size_t size, bool check_valid=true) noexcept
	Decompresses an LZAV-framed buffer back into its original payload. More...

Friends
VLINK_EXPORT friend std::ostream &	operator<< (std::ostream &ostream, const Bytes &target) noexcept
	Stream insertion operator; prints the payload as space-separated hex bytes. More...

Detailed Description

Fixed-size 128-byte buffer holder with SBO, five ownership modes and integrated codecs.

Implements VLink's universal binary carrier. Small payloads live inside the embedded stack_data_ array; larger payloads spill to the global MemoryPool. Ownership is encoded in two flags (is_owner_, is_loaned_) so the destructor can route to the correct release primitive: heap free, iceoryx loan release, or no-op for shallow aliases. All public functions are noexcept; failure is reported via empty return values.

Constructor & Destructor Documentation

◆ Bytes() [1/5]

vlink::Bytes::Bytes ( )

noexcept

Constructs an empty, non-owning carrier with no payload.

data() is nullptr and size() is 0; both is_owner() and is_loaned() are false. The SBO region is zero-initialised.

◆ Bytes() [2/5]

vlink::Bytes::Bytes ( const Bytes & target )

noexcept

Copy constructor; converts any source into an owned deep copy.

Allocates a fresh buffer through the memory pool and copies target's bytes into it when target carries data. Empty inputs yield an empty non-owning result. The copy is always an owner regardless of the source's ownership tags – aliasing and loaned semantics are not preserved by this constructor.

Parameters

target Source buffer.

Note: To keep aliasing or loaned semantics use the explicit factory methods (shallow_copy / loan_internal) instead of the copy constructor.

◆ Bytes() [3/5]

vlink::Bytes::Bytes ( Bytes && target )

noexcept

Move constructor; transfers payload, ownership flags and prefix from target.

Parameters

target Source buffer left in the empty state after the move.

◆ Bytes() [4/5]

vlink::Bytes::Bytes ( const std::initializer_list< uint8_t > & list )

noexcept

Constructs an owned buffer from an initialiser list of bytes.

Parameters

list	Byte values to copy into the new buffer.

◆ Bytes() [5/5]

vlink::Bytes::Bytes ( const std::vector< uint8_t > & data )

explicitnoexcept

Constructs an owned buffer from a std::vector<uint8_t> by deep copy.

Parameters

data	Source vector; its contents are copied verbatim.

◆ ~Bytes()

vlink::Bytes::~Bytes ( )

noexcept

Destructor; releases owned heap storage and ignores loaned / shallow buffers.

Member Function Documentation

◆ begin() [1/2]

const uint8_t * vlink::Bytes::begin ( ) const

inlinenoexcept

Returns a read-only iterator to the first payload byte.

Returns: Pointer to the first payload byte, or nullptr when empty.

◆ begin() [2/2]

uint8_t * vlink::Bytes::begin ( )

inlinenoexcept

Returns a mutable iterator to the first payload byte.

Returns: Pointer to the first payload byte, or nullptr when empty.

◆ bytes_free()

static void vlink::Bytes::bytes_free	(	uint8_t *	ptr,
		size_t	size
	)

staticnoexcept

Returns a buffer previously obtained from bytes_malloc to the pool.

Parameters

ptr	Pointer returned by `bytes_malloc`. `nullptr` is a no-op.
size	Original size; must match the value passed to `bytes_malloc`.

◆ bytes_malloc()

static uint8_t* vlink::Bytes::bytes_malloc ( size_t size )

staticnoexcept

Allocates a raw aligned byte buffer through the global memory pool.

Parameters

size	Number of bytes requested.

Returns: Pointer to the newly allocated buffer, or nullptr on upstream OOM.

Note: The same size value must be passed to the matching bytes_free call.

◆ capacity()

size_t vlink::Bytes::capacity ( ) const

inlinenoexcept

Returns the allocated capacity of the backing buffer.

SBO buffers report kStackSize; pool-allocated buffers report the rounded allocation size.

Returns: Capacity in bytes; always >= real_size().

◆ clear()

void vlink::Bytes::clear ( )

noexcept

Releases owned storage and resets all metadata to the empty state.

When is_owner() is true the backing buffer is returned to the pool; loaned and shallow carriers are simply forgotten. After the call empty() reports true.

◆ compress_data()

static Bytes vlink::Bytes::compress_data	(	const uint8_t *	data,
		size_t	size,
		bool	high_ratio = `false`
	)

staticnoexcept

Compresses a payload using LZAV and wraps it in the VLink compression frame.

Emits the layout shown in the file-level diagram. Inputs larger than 1 MiB (kMaxCompressCacheSize) are rejected and produce an empty result.

Parameters

data	Source pointer.
size	Source length in bytes.
high_ratio	`true` to use LZAV's high-compression preset; default `false`.

Returns: Compressed framed buffer, or an empty Bytes on failure.

◆ convert_to_hex_str()

static std::string vlink::Bytes::convert_to_hex_str	(	const uint8_t *	value,
		size_t	size
	)

staticnoexcept

Renders a raw byte array as space-separated uppercase hex tokens.

Parameters

value	Pointer to the source buffer.
size	Number of bytes to render.

Returns: Hex string such as "1A B2 C3" for the input {0x1A, 0xB2, 0xC3}.

◆ create()

static Bytes vlink::Bytes::create	(	size_t	size,
		uint8_t	offset = `0`
	)

staticnoexcept

Allocates an owned buffer of the requested size with an optional header offset.

Payloads up to kStackSize stay in stack_data_; larger payloads use the memory pool. The content is left uninitialised. When offset is non-zero the first offset bytes of the backing buffer are reserved so transport layers can prepend frame headers in place; data() then points past the reserved prefix.

Parameters

size	Number of usable payload bytes after construction.
offset	Header bytes reserved before the payload region. Default: `0`.

Returns: New owning Bytes instance.

Here is the caller graph for this function:

◆ data() [1/2]

const uint8_t * vlink::Bytes::data ( ) const

inlinenoexcept

Returns a read-only pointer to the start of the payload (post-offset).

Returns: Pointer to the first payload byte, or nullptr when empty.

◆ data() [2/2]

uint8_t * vlink::Bytes::data ( )

inlinenoexcept

Returns a mutable pointer to the start of the payload (post-offset).

Returns: Pointer to the first payload byte, or nullptr when empty.

Here is the caller graph for this function:

◆ decode_from_base64()

static Bytes vlink::Bytes::decode_from_base64 ( const std::string & target )

staticnoexcept

Decodes a Base-64 ASCII string back into a binary payload.

Parameters

target Base-64 source string.

Returns: Decoded Bytes, or an empty value on invalid input.

◆ deep_copy() [1/3]

Bytes& vlink::Bytes::deep_copy ( const Bytes & bytes )

noexcept

Replaces this instance with an owned deep copy of bytes.

Releases any owned storage first, then allocates and populates a fresh buffer when bytes carries data. Empty sources leave this instance empty and non-owning.

Parameters

bytes Source carrier to copy.

Returns: Reference to *this.

◆ deep_copy() [2/3]

static Bytes vlink::Bytes::deep_copy	(	const uint8_t *	data,
		size_t	size,
		uint8_t	offset = `0`
	)

staticnoexcept

Produces an owned copy of an external read-only buffer.

Read-only overload of deep_copy(uint8_t*, size_t, uint8_t). Ownership rules for empty sources match the mutable overload exactly.

Parameters

data	Source read-only buffer.
size	Number of bytes to copy.
offset	Header bytes reserved in the new buffer. Default: `0`.

Returns: Owning Bytes containing the copied payload.

◆ deep_copy() [3/3]

static Bytes vlink::Bytes::deep_copy	(	uint8_t *	data,
		size_t	size,
		uint8_t	offset = `0`
	)

staticnoexcept

Produces an owned copy of an external mutable buffer.

Allocates a fresh buffer and memcpy s size bytes from data into it. When the source is empty (null pointer or zero size) and offset is 0 the result is empty and non-owning; with a non-zero offset only the prefix region is allocated.

Parameters

data	Source buffer.
size	Number of bytes to copy.
offset	Header bytes reserved in the new buffer. Default: `0`.

Returns: Owning Bytes containing the copied payload.

Here is the caller graph for this function:

◆ deep_copy_self()

Bytes& vlink::Bytes::deep_copy_self ( )

noexcept

Converts an existing non-owning carrier into an owning one in place.

Owners are returned unchanged. Empty carriers are cleared. Otherwise a fresh buffer is allocated and the current payload copied into it.

Returns: Reference to *this.

◆ empty()

bool vlink::Bytes::empty ( ) const

inlinenoexcept

Reports whether the buffer is logically empty.

Returns: true when data() is nullptr and size() is 0.

Here is the caller graph for this function:

◆ encode_to_base64()

static std::string vlink::Bytes::encode_to_base64 ( const Bytes & target )

staticnoexcept

Encodes a payload as a standard Base-64 ASCII string.

Parameters

target Source buffer.

Returns: Base-64 string representation.

◆ end() [1/2]

const uint8_t * vlink::Bytes::end ( ) const

inlinenoexcept

Returns a read-only iterator one past the last payload byte.

Returns: End pointer, or nullptr when empty.

◆ end() [2/2]

uint8_t * vlink::Bytes::end ( )

inlinenoexcept

Returns a mutable iterator one past the last payload byte.

Returns: End pointer, or nullptr when empty.

◆ from_string()

static Bytes vlink::Bytes::from_string	(	const std::string &	str,
		uint8_t	offset = `0`
	)

staticnoexcept

Builds an owned Bytes from the bytes of a UTF-8 string.

Parameters

str	Source string; copied byte-for-byte.
offset	Header bytes reserved before the payload. Default: `0`.

Returns: Owning Bytes containing str. Empty input with zero offset yields an empty result.

◆ from_user_input()

static Bytes vlink::Bytes::from_user_input	(	const std::string &	str,
		bool *	ok = `nullptr`
	)

staticnoexcept

Parses a user-typed hex literal into a Bytes payload.

Accepts space-separated byte tokens ("1A @c 2B"), a contiguous even-length hex run with or without a 0x / 0X prefix ("0x1A2B"), or mixed forms. Returns an empty result on parse failure and sets ok to false.

Parameters

str	Source hex string.
ok	Optional pointer set to `true` on success and `false` on failure.

Returns: Parsed Bytes, or an empty value on failure.

◆ get_crc_32()

static uint32_t vlink::Bytes::get_crc_32 ( const Bytes & target )

staticnoexcept

Computes the CRC-32 (ISO-HDLC) checksum of target.

Parameters

target Source buffer.

Returns: 32-bit CRC-32 value.

◆ get_crc_64()

static uint64_t vlink::Bytes::get_crc_64 ( const Bytes & target )

staticnoexcept

Computes the CRC-64 (ECMA-182) checksum of target.

Parameters

target Source buffer.

Returns: 64-bit CRC-64 value.

◆ init_memory_pool()

static void vlink::Bytes::init_memory_pool ( )

staticnoexcept

Eagerly constructs the process-wide MemoryPool that backs heap allocations.

Bytes::bytes_malloc routes through MemoryPool::global_instance(). Calling this once at program start front-loads the singleton construction cost and respects VLINK_MEMORY_LEVEL / VLINK_MEMORY_PREALLOC. Subsequent calls are idempotent no-ops.

Here is the caller graph for this function:

◆ is_big_endian()

constexpr bool vlink::Bytes::is_big_endian ( )

inlinestaticconstexprnoexcept

Returns true at compile time when the platform is big-endian.

Returns: Logical negation of is_little_endian().

Here is the call graph for this function:

◆ is_compress_data()

static bool vlink::Bytes::is_compress_data	(	const uint8_t *	data,
		size_t	size
	)

staticnoexcept

Detects whether a raw byte buffer matches the VLink LZAV compression frame layout.

Validates the 4-byte header magic (17 49 B2 6F), the 4-byte footer magic (A7 05 ED 71) and that the buffer is at least 13 bytes long.

Parameters

data	Pointer to the buffer to inspect.
size	Length of the buffer.

Returns: true when both magics match and the size precondition holds.

◆ is_little_endian()

constexpr bool vlink::Bytes::is_little_endian ( )

inlinestaticconstexprnoexcept

Returns true at compile time when the platform is little-endian.

Returns: true on x86 / arm-le / Windows; false on big-endian targets.

Here is the caller graph for this function:

◆ is_loaned()

bool vlink::Bytes::is_loaned ( ) const

inlinenoexcept

Reports whether the buffer is an iceoryx loan that VLink must not free.

Returns: true for objects produced by loan_internal.

Here is the caller graph for this function:

◆ is_owner()

bool vlink::Bytes::is_owner ( ) const

inlinenoexcept

Reports whether this instance owns and will free its storage.

Returns: true for objects produced by create / deep_copy and surviving copy/move assignments that produced an owned deep copy.

◆ is_ptr()

bool vlink::Bytes::is_ptr ( ) const

inlinenoexcept

Reports whether this carrier merely wraps an opaque pointer.

A pointer-only wrapper satisfies data_ != nullptr, size_ == 0, offset_ == 0 and is_owner_ == false. Retrieve the underlying pointer via to_ptr<T>().

Returns: true when this is a pointer-only wrapper.

Here is the caller graph for this function:

◆ loan_internal() [1/2]

static Bytes vlink::Bytes::loan_internal	(	const uint8_t *	data,
		size_t	size
	)

staticnoexcept

Wraps an iceoryx-loaned read-only payload as a non-owning, non-aliasing carrier.

Parameters

data	Pointer to the read-only iceoryx chunk payload.
size	Length of the payload in bytes.

Returns: Loaned Bytes instance.

◆ loan_internal() [2/2]

static Bytes vlink::Bytes::loan_internal	(	uint8_t *	data,
		size_t	size
	)

staticnoexcept

Wraps an iceoryx-loaned mutable payload as a non-owning, non-aliasing carrier.

Marks is_loaned() as true so the destructor skips the free call – the underlying memory is owned by RouDi. Used internally by the shm:// transport backend.

Parameters

data	Pointer to the iceoryx chunk payload.
size	Length of the payload in bytes.

Returns: Loaned Bytes instance.

◆ offset()

uint8_t vlink::Bytes::offset ( ) const

inlinenoexcept

Returns the reserved header offset preceding the payload.

Returns: Offset in bytes.

◆ operator!=() [1/2]

bool vlink::Bytes::operator!= ( const Bytes & target ) const

noexcept

Byte-wise inequality comparison with another Bytes.

Parameters

target Right-hand operand.

Returns: true when either the sizes or the payload bytes differ.

◆ operator!=() [2/2]

bool vlink::Bytes::operator!= ( const std::vector< uint8_t > & data ) const

noexcept

Byte-wise inequality comparison with a std::vector<uint8_t>.

Parameters

data	Right-hand operand.

Returns: true when either the sizes or the bytes differ.

◆ operator=() [1/3]

Bytes& vlink::Bytes::operator= ( Bytes && target )

noexcept

Move assignment; releases the current buffer and adopts target's state.

Parameters

target Source buffer left empty after the move.

Returns: Reference to *this.

◆ operator=() [2/3]

Bytes& vlink::Bytes::operator= ( const Bytes & target )

noexcept

Copy assignment; converts any source into an owned deep copy of target.

Releases the current buffer first when this instance owns one. Empty sources produce an empty non-owning result.

Parameters

target Source buffer.

Returns: Reference to *this.

◆ operator=() [3/3]

Bytes& vlink::Bytes::operator= ( const std::vector< uint8_t > & data )

noexcept

Replaces the payload with a deep copy of data.

Parameters

data	Source vector.

Returns: Reference to *this.

◆ operator==() [1/2]

bool vlink::Bytes::operator== ( const Bytes & target ) const

noexcept

Byte-wise equality comparison with another Bytes.

Parameters

target Right-hand operand.

Returns: true when sizes and payload bytes match exactly.

◆ operator==() [2/2]

bool vlink::Bytes::operator== ( const std::vector< uint8_t > & data ) const

noexcept

Byte-wise equality comparison with a std::vector<uint8_t>.

Parameters

data	Right-hand operand.

Returns: true when sizes and bytes match exactly.

◆ operator[]() [1/2]

const uint8_t & vlink::Bytes::operator[] ( size_t index ) const

inlinenoexcept

Read-only indexed access into the payload region.

Parameters

index Zero-based logical offset within the payload.

Returns: Const reference to the byte at index.

◆ operator[]() [2/2]

uint8_t & vlink::Bytes::operator[] ( size_t index )

inlinenoexcept

Mutable indexed access into the payload region.

Details.

Resolves to real_data()[offset() + index]. No bounds checking is performed; pass indices in [0, size()).

Parameters

index Zero-based logical offset within the payload.

Returns: Reference to the byte at index.

◆ real_begin() [1/2]

const uint8_t * vlink::Bytes::real_begin ( ) const

inlinenoexcept

Returns a read-only iterator to the start of the raw backing region.

Returns: Pointer equal to real_data().

◆ real_begin() [2/2]

uint8_t * vlink::Bytes::real_begin ( )

inlinenoexcept

Returns a mutable iterator to the start of the raw backing region.

Returns: Pointer equal to real_data().

◆ real_data() [1/2]

const uint8_t * vlink::Bytes::real_data ( ) const

inlinenoexcept

Returns a read-only pointer to the very beginning of the backing buffer.

Returns: Pointer to the raw buffer origin, or nullptr when empty.

◆ real_data() [2/2]

uint8_t * vlink::Bytes::real_data ( )

inlinenoexcept

Returns a mutable pointer to the very beginning of the backing buffer.

real_data() points at the prefix region; real_data() + offset() equals data().

Returns: Pointer to the raw buffer origin, or nullptr when empty.

Here is the caller graph for this function:

◆ real_end() [1/2]

const uint8_t * vlink::Bytes::real_end ( ) const

inlinenoexcept

Returns a read-only iterator one past the prefix-plus-payload region.

Returns: End pointer for the used backing region, or nullptr when empty.

◆ real_end() [2/2]

uint8_t * vlink::Bytes::real_end ( )

inlinenoexcept

Returns a mutable iterator one past the prefix-plus-payload region.

Returns: End pointer for the used backing region, or nullptr when empty.

◆ real_size()

size_t vlink::Bytes::real_size ( ) const

inlinenoexcept

Returns the size of the used backing region (payload plus prefix offset).

Returns: size() + offset().

◆ release_memory_pool()

static void vlink::Bytes::release_memory_pool ( )

staticnoexcept

Releases every empty chunk currently cached by the Bytes memory pool.

Forwards to MemoryPool::global_instance().trim(). Only chunks whose blocks are entirely on their tier's free list are returned to the system allocator; chunks still backing a live Bytes instance are preserved. Lifetime statistics and the geometric chunk-growth state are kept intact.

Note: Safe to invoke concurrently with allocations and frees; treat as a periodic maintenance call rather than a hot-path primitive.

◆ reserve()

bool vlink::Bytes::reserve ( size_t new_capacity )

noexcept

Ensures the backing capacity is at least new_capacity bytes.

Valid only for owned buffers. When the current capacity already satisfies the request the call is a no-op; otherwise a fresh buffer is allocated and the existing payload copied.

Parameters

new_capacity Minimum required capacity.

Returns: true on success; false for non-owned buffers or allocation failure.

◆ resize()

bool vlink::Bytes::resize ( size_t size )

noexcept

Resizes the logical payload region to size bytes.

Valid only for owned buffers. When size exceeds the current capacity reserve is invoked first. Newly exposed bytes are uninitialised unless the build defines VLINK_BYTES_MEM_RESET.

Parameters

size	New payload size in bytes.

Returns: true on success; false for non-owned buffers or reallocation failure.

◆ reverse_order()

static Bytes vlink::Bytes::reverse_order ( const Bytes & target )

staticnoexcept

Returns a new owned Bytes with the byte order of target reversed.

Parameters

target Source buffer to reverse.

Returns: New owned buffer with reversed byte order.

◆ shallow_copy() [1/3]

Bytes& vlink::Bytes::shallow_copy ( const Bytes & bytes )

noexcept

Replaces this instance with a non-owning alias of bytes.

Releases any owned storage first. Copies bytes's raw pointer, size and offset without copying the payload. The result is non-owning regardless of bytes's loaned tag; use loan_internal directly to preserve loaned semantics.

Parameters

bytes Source carrier to alias.

Returns: Reference to *this.

◆ shallow_copy() [2/3]

static Bytes vlink::Bytes::shallow_copy	(	const uint8_t *	data,
		size_t	size
	)

staticnoexcept

Wraps an external read-only buffer as a non-owning alias.

Identical to the mutable overload; the const pointer is stored verbatim through a const_cast so the non-const data() accessor returns the same address.

Parameters

data	External read-only buffer to alias.
size	Length of the buffer in bytes.

Returns: Non-owning Bytes pointing at data.

◆ shallow_copy() [3/3]

static Bytes vlink::Bytes::shallow_copy	(	uint8_t *	data,
		size_t	size
	)

staticnoexcept

Wraps an external mutable buffer as a non-owning alias.

Performs no allocation and no copy. The caller guarantees the lifetime of data exceeds the lifetime of the returned object.

Parameters

data	External buffer to alias.
size	Length of the buffer in bytes.

Returns: Non-owning Bytes pointing at data.

Here is the caller graph for this function:

◆ shallow_copy_ptr()

static Bytes vlink::Bytes::shallow_copy_ptr ( void * data )

staticnoexcept

Wraps an opaque pointer as a zero-size pointer carrier.

Sets size() and offset() to 0 so is_ptr() reports true. The wrapped pointer is retrieved through to_ptr<T>(); ownership stays with the caller.

Parameters

data	Opaque pointer value to embed.

Returns: Non-owning, zero-size Bytes carrying data.

Here is the caller graph for this function:

◆ shrink_to()

bool vlink::Bytes::shrink_to ( size_t size )

noexcept

Truncates the logical payload size in place without reallocating.

Valid only for owned buffers. size must be <= current size(); the backing capacity is unchanged.

Parameters

size	New logical size in bytes.

Returns: true on success; false for non-owned buffers or oversized requests.

◆ size()

size_t vlink::Bytes::size ( ) const

inlinenoexcept

Returns the size of the payload region in bytes.

Returns: Number of payload bytes (excluding the prefix offset).

Here is the caller graph for this function:

◆ stack_size()

constexpr uint8_t vlink::Bytes::stack_size ( )

inlinestaticconstexprnoexcept

Returns the SBO threshold below which payloads stay inline.

Returns: kStackSize (96).

◆ to_ptr()

template<typename T >

T * vlink::Bytes::to_ptr

inlinenoexcept

Reinterprets the backing pointer as T*.

Equivalent to reinterpret_cast<T*>(real_data()). Caller is responsible for alignment.

Template Parameters

T	Target pointee type. Defaults to `void`.

Returns: Pointer to T, or nullptr when empty.

Here is the caller graph for this function:

◆ to_raw_data()

std::vector<uint8_t> vlink::Bytes::to_raw_data ( ) const

noexcept

Copies the payload region into a new std::vector<uint8_t>.

Returns: Vector mirroring data()[0, size()).

◆ to_string()

std::string vlink::Bytes::to_string ( ) const

noexcept

Materialises the payload region as a new std::string.

Returns: Owning string with the payload bytes.

◆ to_string_view()

std::string_view vlink::Bytes::to_string_view ( ) const

noexcept

Returns a non-owning std::string_view into the payload region.

The view is valid until the next mutation of this Bytes instance or its destruction.

Returns: View covering data()[0, size()).

◆ uncompress_data()

static Bytes vlink::Bytes::uncompress_data	(	const uint8_t *	data,
		size_t	size,
		bool	check_valid = `true`
	)

staticnoexcept

Decompresses an LZAV-framed buffer back into its original payload.

Strips the header / size / footer fields and feeds the LZAV payload to lzav_decompress. When check_valid is true the magics are verified up front; invalid magics yield an empty result. Stored original sizes of 0 or above 256 MiB are also rejected.

Parameters

data	Framed source pointer.
size	Framed source length in bytes.
check_valid	`true` to verify magics before decompressing. Default: `true`.

Returns: Decompressed payload, or an empty Bytes on failure.

Friends And Related Function Documentation

◆ operator<<

VLINK_EXPORT friend std::ostream& operator<<	(	std::ostream &	ostream,
		const Bytes &	target
	)

friend

Stream insertion operator; prints the payload as space-separated hex bytes.

Parameters

ostream	Target output stream.
target	Buffer to print.

Returns: Reference to ostream.

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

include/vlink/base/bytes.h

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Bytes() [1/5]

◆ Bytes() [2/5]

◆ Bytes() [3/5]

◆ Bytes() [4/5]

◆ Bytes() [5/5]

◆ ~Bytes()

Member Function Documentation

◆ begin() [1/2]

◆ begin() [2/2]

◆ bytes_free()

◆ bytes_malloc()

◆ capacity()

◆ clear()

◆ compress_data()

◆ convert_to_hex_str()

◆ create()

◆ data() [1/2]

◆ data() [2/2]

◆ decode_from_base64()

◆ deep_copy() [1/3]

◆ deep_copy() [2/3]

◆ deep_copy() [3/3]

◆ deep_copy_self()

◆ empty()

◆ encode_to_base64()

◆ end() [1/2]

◆ end() [2/2]

◆ from_string()

◆ from_user_input()

◆ get_crc_32()

◆ get_crc_64()

◆ init_memory_pool()

◆ is_big_endian()

◆ is_compress_data()

◆ is_little_endian()

◆ is_loaned()

◆ is_owner()

◆ is_ptr()

◆ loan_internal() [1/2]

◆ loan_internal() [2/2]

◆ offset()

◆ operator!=() [1/2]

◆ operator!=() [2/2]

◆ operator=() [1/3]

◆ operator=() [2/3]

◆ operator=() [3/3]

◆ operator==() [1/2]

◆ operator==() [2/2]

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ real_begin() [1/2]

◆ real_begin() [2/2]

◆ real_data() [1/2]

◆ real_data() [2/2]

◆ real_end() [1/2]

◆ real_end() [2/2]

◆ real_size()

◆ release_memory_pool()

◆ reserve()

◆ resize()

◆ reverse_order()

◆ shallow_copy() [1/3]

◆ shallow_copy() [2/3]

◆ shallow_copy() [3/3]

◆ shallow_copy_ptr()

◆ shrink_to()

◆ size()

◆ stack_size()

◆ to_ptr()

◆ to_raw_data()

◆ to_string()

◆ to_string_view()

◆ uncompress_data()

Friends And Related Function Documentation

◆ operator<<