verba_scribo.h File Reference

Text and number formatting, the limits, and one table per kind of thing written. More...

#include "mmgr.h"

Go to the source code of this file.

Data Structures
struct	VerbaTextusCfg
	Arguments for the entries that write text into a buffer. More...
struct	VerbaScriboTextusNs
	Type of the verba_textus dispatch table. More...
struct	VerbaLitteraCfg
	Arguments for the entries that write one character. More...
struct	VerbaScriboLitteraNs
	Type of the verba_littera dispatch table. More...
struct	VerbaNumerusCfg
	Arguments for the entries that write an integer. More...
struct	VerbaScriboNumerusNs
	Type of the verba_numerus dispatch table. More...
struct	VerbaFractioCfg
	Arguments for the entries that write a double. More...
struct	VerbaScriboFractioNs
	Type of the verba_fractio dispatch table. More...
struct	VerbaFinisCfg
	Arguments for the entries that write the buffer itself, with no value to place in it. More...
struct	VerbaScriboFinisNs
	Type of the verba_finis dispatch table. More...

Macros
#define	MMGR_G_MAX_SIG
	Expands to 18u, the most significant digits mmgr_verba_g will keep.
#define	MMGR_FIXED_MAX_DECIMALS
	Expands to 18u, the most digits after the point mmgr_verba_fixed will write.

Functions
size_t	mmgr_verba_put_n (const VerbaTextusCfg *args)
	Writes a counted run of text.
size_t	mmgr_verba_put (const VerbaTextusCfg *args)
	Writes a terminated string, measuring it first.
size_t	mmgr_verba_put_clip (const VerbaTextusCfg *args)
	Writes as much of a string as fits.
size_t	mmgr_verba_xml (const VerbaTextusCfg *args)
	Writes text with the four XML entities substituted.
size_t	mmgr_verba_json (const VerbaTextusCfg *args)
	Writes text as a quoted JSON string.
size_t	mmgr_verba_ch (const VerbaLitteraCfg *args)
	Writes one character.
size_t	mmgr_verba_u64_clip (const VerbaNumerusCfg *args)
	Writes a value right aligned, padded with spaces.
size_t	mmgr_verba_uint (const VerbaNumerusCfg *args)
	Writes a value in the base the caller gives.
size_t	mmgr_verba_u32w (const VerbaNumerusCfg *args)
	Writes a value in base ten, padded to min digits.
size_t	mmgr_verba_hex (const VerbaNumerusCfg *args)
	Writes a value in lower case base sixteen.
size_t	mmgr_verba_u32 (const VerbaNumerusCfg *args)
	Writes a value in base ten, unpadded.
size_t	mmgr_verba_u64 (const VerbaNumerusCfg *args)
	Writes a value in base ten, unpadded.
size_t	mmgr_verba_i64 (const VerbaNumerusCfg *args)
	Writes a signed value in base ten.
size_t	mmgr_verba_g (const VerbaFractioCfg *args)
	Writes a double to a significant digit count.
size_t	mmgr_verba_fixed (const VerbaFractioCfg *args)
	Writes a double to a decimal count.
embed_bool	mmgr_verba_sign_bit (const VerbaFractioCfg *args)
	Reports a double's sign bit.
embed_bool	mmgr_verba_is_inf (const VerbaFractioCfg *args)
	Reports whether a double is an infinity.
embed_bool	mmgr_verba_is_nan (const VerbaFractioCfg *args)
	Reports whether a double is a NaN.
size_t	mmgr_verba_finish (const VerbaFinisCfg *args)
	Stores the terminator and reports the length.
embed_bool	mmgr_verba_ok (const VerbaFinisCfg *args)
	Reports whether there is still room.

Variables
static const VerbaScriboTextusNs	verba_textus
	Dispatch table instance named verba_textus, with each member set to its mmgr_verba_ function.
static const VerbaScriboLitteraNs	verba_littera
	Dispatch table instance named verba_littera, whose one member is set to mmgr_verba_ch.
static const VerbaScriboNumerusNs	verba_numerus
	Dispatch table instance named verba_numerus, with each member set to its mmgr_verba_ function.
static const VerbaScriboFractioNs	verba_fractio
	Dispatch table instance named verba_fractio, with each member set to its mmgr_verba_ function.
static const VerbaScriboFinisNs	verba_finis
	Dispatch table instance named verba_finis, with each member set to its mmgr_verba_ function.

Detailed Description

Text and number formatting, the limits, and one table per kind of thing written.

Author

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

Date

2026-08-29

Note

Five tables and not one, each with the arguments its own entries read. A call carries the destination and the value it is placing,, alone. Writing a character does not pass a double, a base and a column count it will never look at.

Every writing entry takes the offset to write at and returns the offset past what it wrote, and so calls chain.

An entry that will not fit returns args->cap, which every later entry then reads as no room left.

finish stores the terminator and reports the length. Nothing before it terminates the buffer.

Definition in file verba_scribo.h.

Macro Definition Documentation

MMGR_G_MAX_SIG

#define MMGR_G_MAX_SIG

Expands to 18u, the most significant digits mmgr_verba_g will keep.

Note

A larger args->sig is clamped here. An args->sig of 0 is taken as 1.

Definition at line 32 of file verba_scribo.h.

MMGR_FIXED_MAX_DECIMALS

#define MMGR_FIXED_MAX_DECIMALS

Expands to 18u, the most digits after the point mmgr_verba_fixed will write.

Note

A larger args->decimals is clamped here. An args->decimals of 0 writes no point at all.

Definition at line 39 of file verba_scribo.h.

Function Documentation

mmgr_verba_put_n()

size_t mmgr_verba_put_n

(

const VerbaTextusCfg *

args

)

Writes a counted run of text.

Parameters

[in]

args

Buffer, capacity, offset, text and its length [BORROWS].

Returns

The offset past the text, or args->cap when it did not fit.

Note

Writes nothing at all when it does not fit, instead of writing what it can.

Warning

args->text must be readable for args->text_len bytes. No terminator is looked for.

References mmgr_verba_put_n().

Referenced by mmgr_verba_put_n().

mmgr_verba_put()

size_t mmgr_verba_put

(

const VerbaTextusCfg *

args

)

Writes a terminated string, measuring it first.

Parameters

[in]

args

Buffer, capacity, offset and the text [BORROWS].

Returns

The offset past the text, or args->cap when it did not fit.

Note

Takes args->text_len as the length when it is non-zero, and only otherwise measures.

Warning

args->text must not be NULL here, unlike put_clip, xml and json.

References mmgr_verba_put().

Referenced by mmgr_verba_put().

mmgr_verba_put_clip()

size_t mmgr_verba_put_clip

(

const VerbaTextusCfg *

args

)

Writes as much of a string as fits.

Parameters

[in]

args

Buffer, capacity, offset and the text [BORROWS].

Returns

The offset past what was written, which is args->at when nothing was.

Note

Returns args->at and not args->cap when it writes nothing. A later call can still write.

Bounds the measure by the room left, and so the length measured is already the length that fits.

Warning

A NULL args->text writes nothing and not faulting, unlike put.

References mmgr_verba_put_clip().

Referenced by mmgr_verba_put_clip().

mmgr_verba_xml()

size_t mmgr_verba_xml

(

const VerbaTextusCfg *

args

)

Writes text with the four XML entities substituted.

Parameters

[in]

args

Buffer, capacity, offset and the text [BORROWS].

Returns

The offset past what was written, which is args->at for a NULL args->text.

Note

Replaces the ampersand, the two angle brackets and the double quote. The apostrophe is written as it stands, and so this suits element text and double quoted attributes.

Warning

Walks to the terminator. args->text is bounded by its own terminator instead of by args->cap.

References mmgr_verba_xml().

Referenced by mmgr_verba_xml().

mmgr_verba_json()

size_t mmgr_verba_json

(

const VerbaTextusCfg *

args

)

Writes text as a quoted JSON string.

Parameters

[in]

args

Buffer, capacity, offset and the text [BORROWS].

Returns

The offset past the closing quote, or args->cap once something did not fit.

Note

Writes the opening and closing quotes itself, and so the result is a complete JSON string, and a NULL args->text writes an empty pair of quotes where xml writes nothing at all.

Warning

Walks to the terminator. args->text is bounded by its own terminator instead of by args->cap.

References mmgr_verba_json().

Referenced by mmgr_verba_json().

mmgr_verba_ch()

size_t mmgr_verba_ch

(

const VerbaLitteraCfg *

args

)

Writes one character.

Parameters

[in]

args

Buffer, capacity, offset and the character [BORROWS].

Returns

args->at plus one, or args->cap when there is no room.

Note

The building block the escape and digit entries write through, one character at a time.

Warning

args->out must be writable for args->cap bytes. A byte is always reserved for the terminator finish stores.

References mmgr_verba_ch().

Referenced by mmgr_verba_ch().

mmgr_verba_u64_clip()

size_t mmgr_verba_u64_clip

(

const VerbaNumerusCfg *

args

)

Writes a value right aligned, padded with spaces.

Parameters

[in]

args

Buffer, capacity, offset, the value and the column count [BORROWS].

Returns

The offset past what was written, which is args->at when there was no room.

Note

Takes args->columns as a floor. A value needing more digits than that widens the field.

Pads on the left with spaces, where uint pads with leading zeros.

Warning

args->out must be writable for args->cap bytes, and a byte is reserved for the terminator.

References mmgr_verba_u64_clip().

Referenced by mmgr_verba_u64_clip().

mmgr_verba_uint()

size_t mmgr_verba_uint

(

const VerbaNumerusCfg *

args

)

Writes a value in the base the caller gives.

Parameters

[in]

args

Buffer, capacity, offset, the value, the base and the least digit count [BORROWS].

Returns

The offset past the digits, or args->cap when they do not fit.

Note

Raising the digit count to args->min before the room test is what pads with leading zeros.

Warning

Any args->base other than 8 or 16 is written in base ten, whatever value it holds.

References mmgr_verba_uint().

Referenced by mmgr_verba_uint().

mmgr_verba_u32w()

size_t mmgr_verba_u32w

(

const VerbaNumerusCfg *

args

)

Writes a value in base ten, padded to min digits.

Parameters

[in]

args

Buffer, capacity, offset, the value and the least digit count [BORROWS].

Returns

The offset past the digits, or args->cap when they do not fit.

Note

Fixes the base at ten and forwards args->min, as separates it from u32.

Warning

args->base takes no part here, whatever the caller put in it.

References mmgr_verba_u32w().

Referenced by mmgr_verba_u32w().

mmgr_verba_hex()

size_t mmgr_verba_hex

(

const VerbaNumerusCfg *

args

)

Writes a value in lower case base sixteen.

Parameters

[in]

args

Buffer, capacity, offset, the value and the least digit count [BORROWS].

Returns

The offset past the digits, or args->cap when they do not fit.

Note

Fixes the base at sixteen, and so the digits come out lower case, and forwards args->min so the result can be padded with leading zeros to a fixed width.

Warning

args->base takes no part here, whatever the caller put in it.

References mmgr_verba_hex().

Referenced by mmgr_verba_hex().

mmgr_verba_u32()

size_t mmgr_verba_u32

(

const VerbaNumerusCfg *

args

)

Writes a value in base ten, unpadded.

Parameters

[in]

args

Buffer, capacity, offset and the value [BORROWS].

Returns

The offset past the digits, or args->cap when they do not fit.

Note

Fixes both the base at ten and the least digit count at one.

Warning

Neither args->base nor args->min takes any part here. Reach for u32w to pad.

References mmgr_verba_u32().

Referenced by mmgr_verba_u32().

mmgr_verba_u64()

size_t mmgr_verba_u64

(

const VerbaNumerusCfg *

args

)

Writes a value in base ten, unpadded.

Parameters

[in]

args

Buffer, capacity, offset and the value [BORROWS].

Returns

The offset past the digits, or args->cap when they do not fit.

Note

The same walk as u32, since args->val is 64 bits either way. Both names exist to let a caller read the width it means at the call.

Warning

Neither args->base nor args->min takes any part here. Reach for u32w to pad.

References mmgr_verba_u64().

Referenced by mmgr_verba_u64().

mmgr_verba_i64()

size_t mmgr_verba_i64

(

const VerbaNumerusCfg *

args

)

Writes a signed value in base ten.

Parameters

[in]

args

Buffer, capacity, offset and the signed value in sval [BORROWS].

Returns

The offset past the digits, or args->cap when they do not fit.

Note

Writes the sign through ch, then hands the magnitude to uint at base ten.

The magnitude is taken as -(sval + 1) plus one, which stays in range for the most negative value.

Warning

Reads args->sval and not args->val. A caller filling the unsigned member writes a zero.

References mmgr_verba_i64().

Referenced by mmgr_verba_i64().

mmgr_verba_g()

size_t mmgr_verba_g

(

const VerbaFractioCfg *

args

)

Writes a double to a significant digit count.

Parameters

[in]

args

Buffer, capacity, offset, the value and the significant digit count [BORROWS].

Returns

The offset past what was written, or args->cap once something did not fit.

Note

An args->sig of 0 is taken as 1, and anything above MMGR_G_MAX_SIG is clamped there.

Picks the shorter of a plain and an exponential form, dropping trailing zeros before it chooses.

Warning

An infinity writes inf and a NaN writes nan, lower case and unquoted, and so neither is valid JSON on its own.

References mmgr_verba_g().

Referenced by mmgr_verba_g().

mmgr_verba_fixed()

size_t mmgr_verba_fixed

(

const VerbaFractioCfg *

args

)

Writes a double to a decimal count.

Parameters

[in]

args

Buffer, capacity, offset, the value and the decimal count [BORROWS].

Returns

The offset past what was written, or args->cap once something did not fit.

Note

args->decimals is clamped at MMGR_FIXED_MAX_DECIMALS, and a value of 0 writes no point at all.

A half rounds up, and a fraction that carries raises the integer part. The sign is written ahead of the magnitude. A negative half rounds away from zero.

Warning

A magnitude too large for 64 bits of integer part falls back to g at ten significant digits, and so the result is not always in the fixed form asked for.

References mmgr_verba_fixed().

Referenced by mmgr_verba_fixed().

mmgr_verba_sign_bit()

embed_bool mmgr_verba_sign_bit

(

const VerbaFractioCfg *

args

)

Reports a double's sign bit.

Parameters

[in]

args

The value to test, as args->real [BORROWS].

Returns

EMBED_TRUE when the sign bit is set, with nothing written.

Note

Reads the bit instead of comparing against zero. A negative zero returns EMBED_TRUE.

Reads no member but args->real. args->out may be left unset.

References mmgr_verba_sign_bit().

Referenced by mmgr_verba_sign_bit().

mmgr_verba_is_inf()

embed_bool mmgr_verba_is_inf

(

const VerbaFractioCfg *

args

)

Reports whether a double is an infinity.

Parameters

[in]

args

The value to test, as args->real [BORROWS].

Returns

EMBED_TRUE for either infinity, with nothing written.

Note

Wants the exponent field all ones and the mantissa zero, where is_nan wants it non-zero.

The sign takes no part. A negative infinity returns EMBED_TRUE too.

References mmgr_verba_is_inf().

Referenced by mmgr_verba_is_inf().

mmgr_verba_is_nan()

embed_bool mmgr_verba_is_nan

(

const VerbaFractioCfg *

args

)

Reports whether a double is a NaN.

Parameters

[in]

args

The value to test, as args->real [BORROWS].

Returns

EMBED_TRUE for any NaN, with nothing written.

Note

Wants the exponent field all ones and the mantissa non-zero, where is_inf wants it zero.

Quiet and signaling NaNs answer alike, since only the mantissa being non-zero is tested.

References mmgr_verba_is_nan().

Referenced by mmgr_verba_is_nan().

mmgr_verba_finish()

size_t mmgr_verba_finish

(

const VerbaFinisCfg *

args

)

Stores the terminator and reports the length.

Parameters

[in]

args

Buffer, capacity and the offset reached [BORROWS].

Returns

args->at, or 0 when args->at already reached args->cap.

Note

A return of 0 covers both an empty result and one that ran out of room. ok tells them apart.

Warning

The only entry that writes a terminator. A buffer is not a string until this has run.

References mmgr_verba_finish().

Referenced by mmgr_verba_finish().

mmgr_verba_ok()

embed_bool mmgr_verba_ok

(

const VerbaFinisCfg *

args

)

Reports whether there is still room.

Parameters

[in]

args

Capacity and the offset reached [BORROWS].

Returns

EMBED_TRUE while there is still room, EMBED_FALSE once an entry returned args->cap.

Note

Reads neither args->out nor any value member, and so it touches no memory and args->out may be NULL.

References mmgr_verba_ok().

Referenced by mmgr_verba_ok().

Variable Documentation

verba_textus

const VerbaScriboTextusNs verba_textus

static

Dispatch table instance named verba_textus, with each member set to its mmgr_verba_ function.

Definition at line 414 of file verba_scribo.h.

verba_littera

const VerbaScriboLitteraNs verba_littera

static

Dispatch table instance named verba_littera, whose one member is set to mmgr_verba_ch.

Definition at line 425 of file verba_scribo.h.

verba_numerus

const VerbaScriboNumerusNs verba_numerus

static

Dispatch table instance named verba_numerus, with each member set to its mmgr_verba_ function.

Definition at line 432 of file verba_scribo.h.

verba_fractio

const VerbaScriboFractioNs verba_fractio

static

Dispatch table instance named verba_fractio, with each member set to its mmgr_verba_ function.

Definition at line 445 of file verba_scribo.h.

verba_finis

const VerbaScriboFinisNs verba_finis

static

Dispatch table instance named verba_finis, with each member set to its mmgr_verba_ function.

Definition at line 456 of file verba_scribo.h.