verba_linea.h File Reference

A line written into a caller's buffer and handed on as it fills, one field at a time. More...

#include "mmgr.h"

Go to the source code of this file.

Data Structures
struct	VerbaLinea
	A line written into out, at bytes so far, and handed to flush as it fills. More...

Typedefs
typedef int(*)	VerbaLineaFlush(void *context, const char *bytes, size_t size)
	Where a line hands the size bytes at bytes it holds once it is full.

Functions
VerbaLinea	mmgr_line_over (char *out, size_t capacity)
	Makes a line over a buffer, of no capacity where the buffer is NULL.
embed_bool	mmgr_line_flush (VerbaLinea *line)
	Hands what the line holds to its flush and empties it.
size_t	mmgr_line_put_n (VerbaLinea *line, const char *text, size_t length)
	Writes length bytes of text.
size_t	mmgr_line_put (VerbaLinea *line, const char *text)
	Writes a terminated text.
size_t	mmgr_line_put_most (VerbaLinea *line, const char *text, size_t most)
	Writes a terminated text, at most most bytes of it.
void	mmgr_line_put_columns (VerbaLinea *line, const char *text, unsigned int columns)
	Writes a terminated text and spaces after it out to columns.
void	mmgr_line_ch (VerbaLinea *line, char character)
	Writes one character.
void	mmgr_line_decimal (VerbaLinea *line, uint64_t value, unsigned int digits_least)
	Writes value in base ten, padded on the left with zeros to digits_least digits.
void	mmgr_line_decimal_columns (VerbaLinea *line, uint64_t value, unsigned int columns)
	Writes value in base ten, right aligned in columns with spaces before it.
void	mmgr_line_decimal_signed (VerbaLinea *line, int64_t value)
	Writes a signed value in base ten, a minus sign before a negative one.
void	mmgr_line_hex (VerbaLinea *line, uint64_t value, unsigned int digits_least)
	Writes value in lower case base sixteen, padded on the left with zeros to digits_least digits.
size_t	mmgr_line_finish (VerbaLinea *line)
	Stores the terminator, the one store a line no write has reached still needs.
embed_bool	mmgr_line_ok (const VerbaLinea *line)
	Reports whether every write fit.

Detailed Description

A line written into a caller's buffer and handed on as it fills, one field at a time.

Author

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

Date

2026-10-23

Note

Every entry takes the line and the value it writes as plain arguments, and therefore a C++ translation unit calls them as they are. This header includes mmgr.h alone and defines no table, which keeps it free of the designated initializers verba_scribo.h carries.

A write that does not fit a line with no flush writes what fits and leaves at at capacity, and every later write then finds no room. A line with a flush hands what it holds to the flush as it fills and goes on.

Every write leaves the buffer terminated: at at while the line has room, in its last byte once a write did not fit. A written line whose buffer holds no terminator has been corrupted by something other than the line. A line no write has reached has what its buffer contained until mmgr_line_finish runs.

A text entry answers the bytes of the text the line took. Where that is fewer than the text holds the line filled, and text plus the answer is where the caller goes on from, in the same room with at set to zero once those bytes are read.

Definition in file verba_linea.h.

Typedef Documentation

VerbaLineaFlush

typedef int(*) VerbaLineaFlush(void *context, const char *bytes, size_t size)

Where a line hands the size bytes at bytes it holds once it is full.

Parameters

[in]	context	The line's context [BORROWS].
[in]	bytes	What the line holds [BORROWS].
[in]	size	Bytes at bytes.

Returns

1 where the bytes went, 0 where they did not go.

Definition at line 42 of file verba_linea.h.

Function Documentation

mmgr_line_over()

VerbaLinea mmgr_line_over	(	char *	out,
		size_t	capacity )

Makes a line over a buffer, of no capacity where the buffer is NULL.

Parameters

[in]	out	The line's buffer, or NULL where its take was refused [BORROWS].
[in]	capacity	Bytes in out.

Returns

The line, nothing written and no flush.

Note

A line over a refused take stores nothing and mmgr_line_finish answers 0, and therefore a caller tests the take once and writes the line either way.

References mmgr_line_over().

Referenced by mmgr_line_over().

mmgr_line_flush()

embed_bool mmgr_line_flush

(

VerbaLinea *

line

)

Hands what the line holds to its flush and empties it.

Parameters

[in,out]

line

The line [BORROWS].

Returns

EMBED_TRUE where the flush took the bytes or grew the line, EMBED_FALSE where the line has no flush, is full, or its flush refused.

Note

A flush that refuses leaves the line full.

References mmgr_line_flush().

Referenced by mmgr_line_flush().

mmgr_line_put_n()

size_t mmgr_line_put_n	(	VerbaLinea *	line,
		const char *	text,
		size_t	length )

Writes length bytes of text.

Parameters

[in,out]	line	The line [BORROWS].
[in]	text	Bytes to write [BORROWS].
[in]	length	Bytes of text.

Returns

Bytes of text the line took, handed on included: length where every byte went.

Note

A text past the room left is handed on in pieces where the line has a flush, and fills the line where it has none, what fits written.

A line of fewer than two bytes holds none past its terminator, and so any text fills it.

Warning

text must be readable for length bytes.

References mmgr_line_put_n().

Referenced by mmgr_line_put_n().

mmgr_line_put()

size_t mmgr_line_put	(	VerbaLinea *	line,
		const char *	text )

Writes a terminated text.

Parameters

[in,out]	line	The line [BORROWS].
[in]	text	Terminated text to write [BORROWS].

Returns

Bytes of text the line took, handed on included.

Note

The text is read a piece the size of the room left at a time, never past its terminator, and therefore a line with a flush takes a text of any length and needs no bound on it. A line with none is filled by a text longer than its room, what fits written.

References mmgr_line_put().

Referenced by mmgr_line_put().

mmgr_line_put_most()

size_t mmgr_line_put_most	(	VerbaLinea *	line,
		const char *	text,
		size_t	most )

Writes a terminated text, at most most bytes of it.

Parameters

[in,out]	line	The line [BORROWS].
[in]	text	Text to write [BORROWS].
[in]	most	The most bytes of text read.

Returns

Bytes of text the line took, handed on included.

References mmgr_line_put_most().

Referenced by mmgr_line_put_most().

mmgr_line_put_columns()

void mmgr_line_put_columns	(	VerbaLinea *	line,
		const char *	text,
		unsigned int	columns )

Writes a terminated text and spaces after it out to columns.

Parameters

[in,out]	line	The line [BORROWS].
[in]	text	Terminated text to write [BORROWS].
[in]	columns	Bytes the text and its spaces fill. A longer text gets no spaces.

Note

The text is read as mmgr_line_put reads it.

References mmgr_line_put_columns().

Referenced by mmgr_line_put_columns().

mmgr_line_ch()

void mmgr_line_ch	(	VerbaLinea *	line,
		char	character )

Writes one character.

Parameters

[in,out]	line	The line [BORROWS].
[in]	character	The character.

References mmgr_line_ch().

Referenced by mmgr_line_ch().

mmgr_line_decimal()

void mmgr_line_decimal	(	VerbaLinea *	line,
		uint64_t	value,
		unsigned int	digits_least )

Writes value in base ten, padded on the left with zeros to digits_least digits.

Parameters

[in,out]	line	The line [BORROWS].
[in]	value	The value.
[in]	digits_least	Fewest digits written, clamped at 255.

References mmgr_line_decimal().

Referenced by mmgr_line_decimal().

mmgr_line_decimal_columns()

void mmgr_line_decimal_columns	(	VerbaLinea *	line,
		uint64_t	value,
		unsigned int	columns )

Writes value in base ten, right aligned in columns with spaces before it.

Parameters

[in,out]	line	The line [BORROWS].
[in]	value	The value.
[in]	columns	Bytes the value and its spaces fill, clamped at 255.

References mmgr_line_decimal_columns().

Referenced by mmgr_line_decimal_columns().

mmgr_line_decimal_signed()

void mmgr_line_decimal_signed	(	VerbaLinea *	line,
		int64_t	value )

Writes a signed value in base ten, a minus sign before a negative one.

Parameters

[in,out]	line	The line [BORROWS].
[in]	value	The value. INT64_MIN is written whole.

References mmgr_line_decimal_signed().

Referenced by mmgr_line_decimal_signed().

mmgr_line_hex()

void mmgr_line_hex	(	VerbaLinea *	line,
		uint64_t	value,
		unsigned int	digits_least )

Writes value in lower case base sixteen, padded on the left with zeros to digits_least digits.

Parameters

[in,out]	line	The line [BORROWS].
[in]	value	The value.
[in]	digits_least	Fewest digits written, clamped at 255.

References mmgr_line_hex().

Referenced by mmgr_line_hex().

mmgr_line_finish()

size_t mmgr_line_finish

(

VerbaLinea *

line

)

Stores the terminator, the one store a line no write has reached still needs.

Parameters

[in,out]

line

The line [BORROWS].

Returns

The length the line holds, or 0 where it is full.

Note

A full line stands terminated in its last byte and holds capacity minus one bytes.

References mmgr_line_finish().

Referenced by mmgr_line_finish().

mmgr_line_ok()

embed_bool mmgr_line_ok

(

const VerbaLinea *

line

)

Reports whether every write fit.

Parameters

[in]

line

The line [BORROWS].

Returns

EMBED_TRUE while the line has room, EMBED_FALSE once a write did not fit.

References mmgr_line_ok().

Referenced by mmgr_line_ok().