CBuffer

CBufferHeap_#

CBufferHeap_();

CBufferHeap_(B&& b);

Creates an empty pointer-serialization heap, or takes the supplied buffer as its encoded storage.

put#

template<class T> void put(B& b, T* v);

Writes an object ID into the destination and stores a non-null pointee on its first encounter. Later occurrences of the same pointer reuse that ID.

get#

template<class T> T get(B& b);

Reads an object ID and returns its decoded pointer, reusing a previous result for repeated IDs. Restored pointees require caller-managed ownership.

buffer#

B& buffer();

Returns the heap’s encoded byte buffer by reference. This contains pointee data; the main buffer holds the corresponding IDs.

CBuffer#

CBuffer();

CBuffer(size_t size);

CBuffer(const CBuffer& b);

CBuffer(CBuffer&& b);

CBuffer(char* data, size_t size);

CBuffer(const CBuffer& b, size_t offset);

The size-taking constructor creates owned bytes with the cursor at the beginning. The pointer/size and offset constructors borrow existing bytes; their backing storage must outlive the view. Copying an owning buffer copies its bytes and resets the cursor; copying a borrowed buffer retains the view and cursor.

~CBuffer#

~CBuffer();

operator=#

CBuffer& operator=(CBuffer&& b);

CBuffer& operator=(const CBuffer& b);

Replaces bytes, child buffers, and heap state. Owned storage is copied or moved and its cursor resets to the beginning; a borrowed source remains a borrowed view with the source cursor.

size#

size_t size() const;

Returns the total byte length, independent of the current read/write cursor. Use remaining() for unread bytes.

capacity#

size_t capacity() const;

Returns allocated capacity for an owning buffer. Borrowed buffer views do not support this operation.

clear#

void clear();

Releases owned contents, attached child buffers, and the serialization heap, then resets the cursor. Only owning buffers support clearing.

resize#

void resize(size_t n);

Changes the owned byte length and clamps the cursor to the new end if necessary. References and pointers into the bytes can be invalidated.

setPersistent#

void setPersistent(bool persistent);

Controls whether a containing cvar borrows this buffer instead of copying or deleting it. The caller must keep a persistent buffer alive; the marker does not prevent normal CBuffer destruction or change ownership of its byte storage.

persistent#

bool persistent() const;

Reports the marker that makes cvar retain a buffer pointer without copying or deleting that buffer. This does not describe whether the buffer’s byte storage is owned or borrowed.

peek#

template<class T> const T& peek() const;

Reads at the cursor without advancing it. Trivial values use an aligned borrowed snapshot; nontrivial object views require a live object at the address.

peekValue#

template<class T> requires(std::is_trivially_copyable_v<T>) T peekValue() const;

Copies a trivially copyable value at the cursor without advancing it. Checks that enough bytes remain and supports unaligned byte storage.

get#

template<class T> requires(std::is_trivially_copyable_v<T> && !CStorable<T>) T get();

template<class T> requires(std::is_pointer_v<T>) T get(T);

template<class T> requires(std::is_trivially_copyable_v<T> && !std::is_pointer_v<T> && !CStorable<T>) T get(T&);

template<class T> T get(std::atomic<T>&);

template<class T> requires(CStorable<T>) T get();

template<class T> requires(CStorable<T>) T get(T&);

void get(void* data, size_t n);

template<class T> requires(CSame<T, cstr>) cstr get();

Reads a value and advances the cursor. The type-directed get(x) forms return the decoded value without assigning x; use set(x) to assign. Raw-byte reads fill the supplied destination, and storable types are constructed from this buffer.

getPtr#

template<class T> requires(std::is_trivially_copyable_v<T> && !CStorable<T>) T getPtr();

template<class T> requires(CStorable<T>) T getPtr();

Allocates and decodes a pointee, returning it as pointer type T. The caller owns the returned object; this is distinct from a borrowed pointer into the buffer.

set#

template<class T> requires(std::is_trivially_copyable_v<T> && !std::is_pointer_v<T> && !CStorable<T>) void set(T& x);

template<class T> requires(CStorable<T>) void set(T& x);

void set(cstr& x);

Reads the next encoded value into the supplied destination, advancing the cursor. This is the assigning counterpart of get(x).

tryGet#

template<class T> std::expected<T, CError> tryGet();

Returns the decoded value or an unexpected CError. On a caught error, the read cursor is restored to its prior offset.

skip#

template<class T> void skip();

void skip(size_t n);

Advances the cursor by a byte count, or by sizeof(T), without decoding. Raises CError if insufficient bytes remain.

put#

template<class T> requires(std::is_pointer_v<T>) void put(T x);

template<class T> requires(std::is_trivially_copyable_v<T> && !std::is_pointer_v<T> && !CStorable<T>) void put(const T& x);

template<class T> requires(CStorable<T>) void put(const T& x);

void put(const void* bytes, size_t n);

void put(const cstr& s);

Appends bytes or a storable value. Pair with the corresponding read overload.

operator<<#

template<class T> CBuffer& operator<<(T&& x);

Writes a value through put() and returns this buffer so writes can be chained.

rewind#

void rewind();

Sets the cursor to the beginning while retaining all bytes and attachments. Call before reading back a sequence that has just been written.

bufferCount#

size_t bufferCount() const;

Returns the number of child-buffer slots, including slots emptied by take(). It is not a count of non-null attachments.

add#

uint32_t add(CBuffer* subBuffer);

Transfers a sub-buffer to this buffer and returns its attachment ID.

take#

CBuffer* take(uint32_t id);

Transfers an attached buffer back to the caller.

buffer#

CBuffer* buffer(uint32_t id);

Returns a borrowed child pointer for a valid, occupied ID. Invalid or previously taken IDs raise CError.

getHeap#

Heap& getHeap();

Returns the auxiliary heap used for pointer serialization, creating it on first use. Repeated pointers can be stored once and referenced by ID.

maybeGetHeap#

Heap* maybeGetHeap();

Returns the existing serialization heap, or nullptr if none exists. The pointer remains owned by this buffer.

maybeTakeHeap#

Heap* maybeTakeHeap();

Detaches and returns the serialization heap, or nullptr. The caller assumes ownership and this buffer no longer has a heap.

createHeap#

void createHeap(CBuffer&& b);

Creates the serialization heap from the supplied buffer’s bytes. This buffer must not already have a heap.

data#

char* data();

const char* data() const;

Returns a borrowed pointer to the start of owned bytes, regardless of the cursor. Borrowed buffer views reject this call; bytes() addresses their current cursor.

bytes#

char* bytes();

const char* bytes() const;

Returns a borrowed pointer at the current cursor, for owned buffers and views. Available readable bytes are given by remaining().

end#

char* end();

const char* end() const;

Returns one past the owned byte storage. It does not identify the current cursor and is not supported for a borrowed view.

advance#

void advance(size_t n);

template<class T> void advance();

Grows owned storage by the byte count, or sizeof(T), while preserving the cursor position. Despite its name, this reserves additional bytes rather than skipping over them.

compress#

void compress(int level = -1);

Replaces the owned bytes with zlib-compressed bytes and rewinds the cursor. Levels 0–9 select compression effort; -1 selects the default.

compressGZ#

void compressGZ(int level = -1);

Replaces the owned bytes with a gzip stream and rewinds the cursor. Levels 0–9 select compression effort; -1 selects the default.

decompress#

void decompress();

Replaces zlib-compressed owned bytes with the decompressed contents and rewinds the cursor.

decompressGZ#

void decompressGZ();

Replaces gzip-compressed owned bytes with the decompressed contents and rewinds the cursor.

setOffset#

void setOffset(size_t offset);

Moves the cursor to an absolute byte offset, including the end position. Offsets greater than size() raise CError.

offset#

size_t offset() const;

Returns the current read/write cursor’s byte offset from the start of the buffer.

remaining#

size_t remaining() const;

Returns the number of bytes from the cursor to the end. Reads and skips reduce this value.

require#

void require(size_t n) const;

Checks that at least n bytes remain at the cursor and raises CError for truncated input. It does not advance the cursor.

save#

void save(const cstr& path) const;

Writes all owned bytes to the file, regardless of cursor position. This saves the byte stream, not attached child buffers or an auxiliary heap.

open#

void open(const cstr& path);

Reads a file into owned storage, replacing existing bytes and attachments and rewinding the cursor. A read failure leaves the previous contents intact.

cRestoreMap#

template<class T> inline void cRestoreMap(T& m, CBuffer& b);

Reads entries in the typed map format and inserts them into the destination without clearing it first. Existing keys retain their values when the destination uses unique-key insertion.

cStoreMap#

template<class T> inline void cStoreMap(T& m, CBuffer& b);

Writes a container count followed by map keys and values in iteration order. Pointer entries use the buffer’s heap support; this typed container format is distinct from cvar::storeMap().

cStoreSet#

template<class T> inline void cStoreSet(const T& s, CBuffer& b);

Writes a container count followed by set elements in iteration order, using buffer heap support for pointer elements.

cRestoreSet#

template<class T> inline void cRestoreSet(T& s, CBuffer& b);

Reads a typed set representation and inserts its elements into the destination. Existing entries are retained, with duplicates handled by the destination set.