Byte verbs that append into a caller's span or read out of it. More...

#include "spatium/spatium.h"
#include "mmgr.h"

Data Structures
struct	OctetusCfg
	Arguments for the byteio calls, where each call reads only the members it needs. More...
struct	OctetusIntroitusExitusNs
	Type of the byteio dispatch table. More...

Functions
void	mmgr_byteio_put (const OctetusCfg *args)
	Appends args->byte to args->write_span.
void	mmgr_byteio_put_be (const OctetusCfg *args)
	Appends the low args->bytes of args->value to args->write_span, most significant byte first.
void	mmgr_byteio_raw (const OctetusCfg *args)
	Appends args->bytes from args->src to args->write_span as they are.
embed_bool	mmgr_byteio_take_be (const OctetusCfg *args)
	Reads a big endian value of args->bytes at args->read_span's cursor and advances past it.
embed_bool	mmgr_byteio_rd_str (const OctetusCfg *args)
	Reads a big endian 32-bit length at args->read_span's cursor, then points args->blob at the run behind it.
embed_bool	mmgr_byteio_mpint_fixed (const OctetusCfg *args)
	Right-aligns the big endian integer at args->src into args->write_span's whole buffer, zero filling ahead of it.

Variables
static const OctetusIntroitusExitusNs	byteio
	Dispatch table instance named byteio, with each member set to its mmgr_byteio_ function.

Detailed Description

Byte verbs that append into a caller's span or read out of it.

Author: dstroy0 (Douglas Quigg) dquig.nosp@m.g123.nosp@m.@gmai.nosp@m.l.co.nosp@m.m

Date: 2026-08-29

Note: These act on a caller's span and hold nothing of their own. The span carries the cursor and the sticky flag. A caller may append a whole message and test once at the end.; mmgr_byteio_put, mmgr_byteio_put_be and mmgr_byteio_raw return nothing. What a writer emits and how big its buffer is are both fixed before the build, and so writing past the end means the program is wrong. Those three assert, store nothing, and latch overflow to keep a wrong program off the end, and none of that leaves a caller anything to act on.; mmgr_byteio_take_be and mmgr_byteio_rd_str answer EMBED_FALSE when the bytes are not there, set the read span's err, and leave the cursor and the output where they were. A reader is handed whatever was sent to it. A short read is a runtime fact and not a build failure. The cursor does not advance on failure, because a caller that keeps reading still needs it to mean something.; mmgr_byteio_mpint_fixed is neither of those. It writes a whole field and not appending, and answers whether the integer fit, and so its own declaration carries the contract.; Whole values move a word at a time. The big endian entries reverse once and then store or load at the widest step the count allows, instead of walking bytes.

Definition in file octetus_introitus_exitus.h.

Function Documentation

◆ mmgr_byteio_put()

void mmgr_byteio_put ( const OctetusCfg * args )

Appends args->byte to args->write_span.

Parameters

[in,out] args Span and the byte to append [BORROWS].

Warning: Appending past the span's cap is a build failure. It asserts, stores nothing and latches overflow. pos counts the byte either way.

References mmgr_byteio_put().

Referenced by mmgr_byteio_put().

◆ mmgr_byteio_put_be()

void mmgr_byteio_put_be ( const OctetusCfg * args )

Appends the low args->bytes of args->value to args->write_span, most significant byte first.

Parameters

[in,out] args Span, value and byte count [BORROWS].

Note: The value is reversed once and then stored at the widest step the count allows. A count of eight is one store and a count of seven is three.

Warning: Appending past the span's cap is a build failure. It asserts, stores nothing and latches overflow. pos advances either way.; args->bytes must be 1 through 8.

References mmgr_byteio_put_be().

Referenced by mmgr_byteio_put_be().

◆ mmgr_byteio_raw()

void mmgr_byteio_raw ( const OctetusCfg * args )

Appends args->bytes from args->src to args->write_span as they are.

Parameters

[in,out] args Span, source and byte count [BORROWS].

Warning: Appending past the span's cap is a build failure. It asserts, stores nothing and latches overflow. pos advances either way.; args->src must be readable for args->bytes, and must not overlap the span's buffer.

References mmgr_byteio_raw().

Referenced by mmgr_byteio_raw().

◆ mmgr_byteio_take_be()

embed_bool mmgr_byteio_take_be ( const OctetusCfg * args )

Reads a big endian value of args->bytes at args->read_span's cursor and advances past it.

Parameters

[in,out] args Span, byte count and where to store the value [BORROWS].

Returns: EMBED_TRUE when the bytes were there, EMBED_FALSE when the span was short.

Note: Reads at the cursor and nowhere else. A codec that leads with a tag advances past it itself.; A read reaching past the end sets the span's err and leaves the cursor and args->out untouched.

Warning: args->bytes must be 1 through 8.

References mmgr_byteio_take_be().

Referenced by mmgr_byteio_take_be().

◆ mmgr_byteio_rd_str()

embed_bool mmgr_byteio_rd_str ( const OctetusCfg * args )

Reads a big endian 32-bit length at args->read_span's cursor, then points args->blob at the run behind it.

Parameters

[in,out] args Span, and where to report the run and its length [BORROWS].

Returns: EMBED_TRUE when the length and its run both lay within the span.

Note: Nothing is copied. args->blob points into the span's own bytes, and so it lives only as long as they do [BORROWS].; The cursor advances past the length and the run together. A caller reading a sequence of these needs to track nothing between them.; A run reaching past the end leaves the cursor where it started, sets the span's err, and writes nothing through args->blob or args->blob_bytes. The length alone having been read does not move the cursor either, since a partial read is not a read.

References mmgr_byteio_rd_str().

Referenced by mmgr_byteio_rd_str().

◆ mmgr_byteio_mpint_fixed()

embed_bool mmgr_byteio_mpint_fixed ( const OctetusCfg * args )

Right-aligns the big endian integer at args->src into args->write_span's whole buffer, zero filling ahead of it.

Parameters

[in,out] args The integer with its length in args->src and args->bytes, and the field as args->write_span [BORROWS].

Returns: EMBED_TRUE when the integer fits the field, EMBED_FALSE when it does not.

Note: Leading zero bytes of the integer are skipped before the width is tested. A value carrying a sign byte still fits a field of its own size.; The field is written whole and not appended to. On success args->write_span's cursor ends at its cap.; Nothing is written to the field when it returns EMBED_FALSE, but args->write_span's overflow is latched. A span tested later reports the failure too.