cellularum_laboro.h File Reference

Bounded string work: the three argument types, the calls, and the cellul dispatch table. More...

#include "verbum_scrutor/verbum_scrutor.h"
#include "mmgr.h"

Go to the source code of this file.

Data Structures
struct	CatenaFinitaCfg
	Arguments for the string calls, where each call reads only the members it needs. More...
struct	VerboProgrediorCfg
	Arguments for the single-step compares used to drive a walk. More...
struct	TransfiguroCfg
	Arguments for the conversions from text to number. More...
struct	CellularumLaboroNs
	Type of the cellul dispatch table. More...

Macros
#define	MMGR_SIEVE_ROWS
	Most needle offsets the search sieve tests per candidate word.
#define	MMGR_FIND_CHAIN_MAX
	Longest haystack a one or two byte needle is settled over by a mask chain and not by building a sieve.

Functions
CatenaFinitaCfg	mmgr_cellul_init (const CatenaFinitaCfg *args)
	Returns a copy of the argument struct.
size_t	mmgr_cellul_len (const CatenaFinitaCfg *args)
	Returns the bytes in src before its terminator, starting at args->at.
size_t	mmgr_cellul_diff (const CatenaFinitaCfg *args)
	Returns the offset of the first byte where src and other differ.
embed_bool	mmgr_cellul_eq (const CatenaFinitaCfg *args)
	Reports whether src and other hold the same terminated string.
embed_bool	mmgr_cellul_starts (const CatenaFinitaCfg *args)
	Reports whether src begins with other.
const char *	mmgr_cellul_find (const CatenaFinitaCfg *args)
	Finds the first occurrence of other within src.
embed_bool	mmgr_cellul_has (const CatenaFinitaCfg *args)
	Reports whether other occurs within src.
const char *	mmgr_cellul_chr (const CatenaFinitaCfg *args)
	Finds the first occurrence of args->byte in src, before the terminator.
size_t	mmgr_cellul_copy (const CatenaFinitaCfg *args)
	Copies src into dst, writing at most cap bytes including the terminator.
embed_bool	mmgr_cellul_ws (const CatenaFinitaCfg *args)
	Tests src[at] for whitespace.
embed_bool	mmgr_cellul_digit (const CatenaFinitaCfg *args)
	Tests src[at] for a decimal digit.
embed_iword	mmgr_cellul_step_word (const VerboProgrediorCfg *args)
	Compares one word pair and reports whether a walk should continue.
embed_iword	mmgr_cellul_step_byte (const VerboProgrediorCfg *args)
	Compares one byte pair and reports whether a walk should continue.
embed_iword	mmgr_cellul_to_long (const TransfiguroCfg *args)
	Reads a signed decimal integer from args->src.
embed_word	mmgr_cellul_to_ulong (const TransfiguroCfg *args)
	Reads an unsigned decimal integer from args->src.
double	mmgr_cellul_to_double (const TransfiguroCfg *args)
	Reads a decimal floating point number from args->src.
float	mmgr_cellul_to_float (const TransfiguroCfg *args)
	Reads a decimal floating point number from args->src and narrows it to float.

Variables
static const CellularumLaboroNs	cellul
	Dispatch table instance named cellul, with each member set to its mmgr_cellul_ function.

Detailed Description

Bounded string work: the three argument types, the calls, and the cellul dispatch table.

Author

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

Date

2026-08-29

Note

The calls taking CatenaFinitaCfg are bounded by a cap the caller states, and so no walk runs past it even where the bytes carry no terminator. That bound makes these usable where a libc string call is not, since a missing terminator stops a walk and not running it off the end.

ws and digit are the exception. Each reads the single byte at args->at and never consults cap, because a one byte test has nothing to run past.

The TransfiguroCfg conversions carry no bound at all. Each reads until the first byte that is not part of the number, and so the caller owes them such a byte inside readable storage. A terminator is the usual one.

The VerboProgrediorCfg pair take their operands by value and read no memory, and so neither carries a bound.

Warning

Nothing here allocates or hands back ownership. Every pointer in and out is the caller's, and the addresses find and chr return point into the src they were given.

Definition in file cellularum_laboro.h.

Macro Definition Documentation

MMGR_SIEVE_ROWS

#define MMGR_SIEVE_ROWS

Most needle offsets the search sieve tests per candidate word.

Note

A ceiling and not a count. cellul_pick_rows takes the smallest of this, the needle length and MMGR_SWAR_BYTES. A short needle is sieved on fewer offsets than this allows.

cellul_find_core sizes two arrays by it, the chosen offsets and their broadcasts, and reads element 0 of each outside the loop that walks the rest.

Warning

Taken only when MMGR_SIEVE_ROWS is not already defined. A build may supply its own.

A build's own value must be at least 1. At 0 both arrays are declared zero length and the search still reads element 0 of each, and nothing here asserts against it.

Definition at line 49 of file cellularum_laboro.h.

MMGR_FIND_CHAIN_MAX

#define MMGR_FIND_CHAIN_MAX

Longest haystack a one or two byte needle is settled over by a mask chain and not by building a sieve.

Note

Case sensitive searches only. The chain compares its broadcasts without folding them. A folded search takes the sieve at every length, whatever this is set to.

Defaults to no limit, which folds the test away: read_cap <= SIZE_MAX is true for every size_t. A default build emits no comparison and no second path is chosen at run time.

The chain settles every start position in a word at once, with no anchor to choose and nothing to verify afterwards. A two byte needle costs it a second read a step and a one byte needle none. The sieve picks its offsets out of the cost table before a haystack byte is read, reads a word per offset on top of the one it tests for the terminator, and proves every surviving lane in full. Measured with a two byte needle, cycles for the whole call:

n              8      64    2048
Xtensa chain 124     489   13391
Xtensa sieve 187     607   15494
RISC-V chain 124     488   13393
RISC-V sieve 219     680   17059

The chain wins at every length on both parts, and so the default is no limit. The knob is kept because that is a measurement instead of a proof, and a part or a workload that disagrees should be able to say so without editing the walk.

Warning

Taken only when MMGR_FIND_CHAIN_MAX is not already defined. A build may supply its own. Zero sends every needle through the sieve.

Definition at line 80 of file cellularum_laboro.h.

Function Documentation

mmgr_cellul_init()

CatenaFinitaCfg mmgr_cellul_init

(

const CatenaFinitaCfg *

args

)

Returns a copy of the argument struct.

Parameters

[in]

args

Struct to copy [BORROWS].

Returns

A copy of *args.

Note

Copies the members only. Nothing they point at is read.

References mmgr_cellul_init().

Referenced by mmgr_cellul_init().

mmgr_cellul_len()

size_t mmgr_cellul_len

(

const CatenaFinitaCfg *

args

)

Returns the bytes in src before its terminator, starting at args->at.

Parameters

[in]

args

Bytes src, the extent cap, and the start offset at [BORROWS].

Returns

Bytes before the terminator, at most cap minus at.

Note

Returns cap minus at when no terminator is found in range.

Warning

args->at must not exceed args->cap, and src must be readable to args->cap. The last partial word is loaded whole and masked after, and so up to MMGR_SWAR_BYTES - 1 bytes past cap are read.

References mmgr_cellul_len().

Referenced by mmgr_cellul_len().

mmgr_cellul_diff()

size_t mmgr_cellul_diff

(

const CatenaFinitaCfg *

args

)

Returns the offset of the first byte where src and other differ.

Parameters

[in]

args

Bytes src and other, the extent cap, and ci [BORROWS].

Returns

Offset of the first difference, or cap when the two agree throughout.

Note

A terminator does not end the scan. cap is the only bound.

Warning

Both src and other must be readable for cap bytes. The last partial word is loaded whole and masked after, and up to MMGR_SWAR_BYTES - 1 bytes past cap are read from each.

References mmgr_cellul_diff().

Referenced by mmgr_cellul_diff().

mmgr_cellul_eq()

embed_bool mmgr_cellul_eq

(

const CatenaFinitaCfg *

args

)

Reports whether src and other hold the same terminated string.

Parameters

[in]

args

Bytes src and other, the extent cap, and ci [BORROWS].

Returns

EMBED_TRUE when both reach a terminator with no difference before it.

Warning

Both src and other must be readable for cap bytes. The last partial word is loaded whole and masked after, and up to MMGR_SWAR_BYTES - 1 bytes past cap are read from each.

References mmgr_cellul_eq().

Referenced by mmgr_cellul_eq().

mmgr_cellul_starts()

embed_bool mmgr_cellul_starts

(

const CatenaFinitaCfg *

args

)

Reports whether src begins with other.

Parameters

[in]

args

Bytes src and other, the extent cap, and ci [BORROWS].

Returns

EMBED_TRUE when other reaches its terminator with no difference before it.

Note

An empty other matches any src.

Warning

Both src and other must be readable for cap bytes. The last partial word is loaded whole and masked after, and up to MMGR_SWAR_BYTES - 1 bytes past cap are read from each.

References mmgr_cellul_starts().

Referenced by mmgr_cellul_starts().

mmgr_cellul_find()

const char * mmgr_cellul_find

(

const CatenaFinitaCfg *

args

)

Finds the first occurrence of other within src.

Parameters

[in]

args

Haystack src with cap, needle other with other_cap, and ci [BORROWS].

Returns

Address inside src, or NULL when there is no match [BORROWS].

Note

An empty needle returns src. A needle longer than cap returns NULL.

Warning

src must be readable for cap bytes and other for other_cap bytes. The needle is loaded a whole word at a time and masked after, and so up to MMGR_SWAR_BYTES - 1 bytes past other_cap are read. The haystack walk holds itself inside cap.

References mmgr_cellul_find().

Referenced by mmgr_cellul_find().

mmgr_cellul_has()

embed_bool mmgr_cellul_has

(

const CatenaFinitaCfg *

args

)

Reports whether other occurs within src.

Parameters

[in]

args

Haystack src with cap, needle other with other_cap, and ci [BORROWS].

Returns

EMBED_TRUE when mmgr_cellul_find reports a match.

Warning

src must be readable for cap bytes and other for other_cap bytes, with the needle read past other_cap exactly as mmgr_cellul_find describes.

References mmgr_cellul_has().

Referenced by mmgr_cellul_has().

mmgr_cellul_chr()

const char * mmgr_cellul_chr

(

const CatenaFinitaCfg *

args

)

Finds the first occurrence of args->byte in src, before the terminator.

Parameters

[in]

args

Bytes src, the extent cap, and the byte sought [BORROWS].

Returns

Address inside src, or NULL when the byte does not occur [BORROWS].

Note

A byte of 0 returns the terminator's own address, or src plus cap when no terminator is in range.

Warning

src must be readable for cap bytes. The last partial word is loaded whole and masked after, and up to MMGR_SWAR_BYTES - 1 bytes past cap are read.

References mmgr_cellul_chr().

Referenced by mmgr_cellul_chr().

mmgr_cellul_copy()

size_t mmgr_cellul_copy

(

const CatenaFinitaCfg *

args

)

Copies src into dst, writing at most cap bytes including the terminator.

Parameters

[in,out]

args

Source src, destination dst, and the destination extent cap [BORROWS].

Returns

Bytes copied and not counting the terminator.

Note

A cap of 0 writes nothing at all and not even a terminator.

Warning

dst must be writable for cap bytes and src readable for cap minus one.

References mmgr_cellul_copy().

Referenced by mmgr_cellul_copy().

mmgr_cellul_ws()

embed_bool mmgr_cellul_ws

(

const CatenaFinitaCfg *

args

)

Tests src[at] for whitespace.

Parameters

[in]

args

Bytes src and the offset at [BORROWS].

Returns

EMBED_TRUE for space, tab, newline, carriage return, form feed or vertical tab.

Warning

src[at] must be readable. cap does not bound this call.

References mmgr_cellul_ws().

Referenced by mmgr_cellul_ws().

mmgr_cellul_digit()

embed_bool mmgr_cellul_digit

(

const CatenaFinitaCfg *

args

)

Tests src[at] for a decimal digit.

Parameters

[in]

args

Bytes src and the offset at [BORROWS].

Returns

EMBED_TRUE for the ten decimal digits, '0' through '9'.

Warning

src[at] must be readable. cap does not bound this call.

References mmgr_cellul_digit().

Referenced by mmgr_cellul_digit().

mmgr_cellul_step_word()

embed_iword mmgr_cellul_step_word

(

const VerboProgrediorCfg *

args

)

Compares one word pair and reports whether a walk should continue.

Parameters

[in]

args

Words word_left and word_right, with ci and end_wins [BORROWS].

Returns

MMGR_SWAR_GO to continue, MMGR_SWAR_YES on agreement, MMGR_SWAR_NO on difference.

Note

MMGR_SWAR_YES means word_left's terminator arrived before the first difference.

end_wins makes a terminator in the same lane as the difference count as agreement.

References mmgr_cellul_step_word().

Referenced by mmgr_cellul_step_word().

mmgr_cellul_step_byte()

embed_iword mmgr_cellul_step_byte

(

const VerboProgrediorCfg *

args

)

Compares one byte pair and reports whether a walk should continue.

Parameters

[in]

args

Bytes byte_left and byte_right, with ci and end_wins [BORROWS].

Returns

MMGR_SWAR_GO to continue, MMGR_SWAR_YES on agreement, MMGR_SWAR_NO on difference.

Note

A terminating byte_left gives MMGR_SWAR_YES when byte_right also terminates, or when end_wins is set.

References mmgr_cellul_step_byte().

Referenced by mmgr_cellul_step_byte().

mmgr_cellul_to_long()

embed_iword mmgr_cellul_to_long

(

const TransfiguroCfg *

args

)

Reads a signed decimal integer from args->src.

Parameters

[in,out]

args

Text src and the optional end target [BORROWS].

Returns

The value, negated when a minus sign was read.

Note

Skips leading whitespace, then accepts one optional '+' or '-'.

When end is not NULL it is set past the last digit, or back to src when none was read.

Warning

The read stops at the first byte that is not part of the number. No length bounds it.

The digit accumulator is embed_word wide and wraps on a longer run.

References mmgr_cellul_to_long().

Referenced by mmgr_cellul_to_long().

mmgr_cellul_to_ulong()

embed_word mmgr_cellul_to_ulong

(

const TransfiguroCfg *

args

)

Reads an unsigned decimal integer from args->src.

Parameters

[in,out]

args

Text src and the optional end target [BORROWS].

Returns

The accumulated value.

Note

Skips leading whitespace, then accepts one optional '+'. A '-' stops the read.

When end is not NULL it is set past the last digit, or back to src when none was read.

Warning

The read stops at the first byte that is not part of the number. No length bounds it.

The digit accumulator is embed_word wide and wraps on a longer run.

References mmgr_cellul_to_ulong().

Referenced by mmgr_cellul_to_ulong().

mmgr_cellul_to_double()

double mmgr_cellul_to_double

(

const TransfiguroCfg *

args

)

Reads a decimal floating point number from args->src.

Parameters

[in,out]

args

Text src and the optional end target [BORROWS].

Returns

The assembled value.

Note

Accepts whitespace, one optional sign, digits, one optional point, then an optional exponent.

An exponent is read only when at least one digit was seen before it.

When end is not NULL it is set past the number, or back to src when no digit was read.

Warning

The read stops at the first byte that is not part of the number. No length bounds it.

References mmgr_cellul_to_double().

Referenced by mmgr_cellul_to_double().

mmgr_cellul_to_float()

float mmgr_cellul_to_float

(

const TransfiguroCfg *

args

)

Reads a decimal floating point number from args->src and narrows it to float.

Parameters

[in,out]

args

Text src and the optional end target [BORROWS].

Returns

The value from mmgr_cellul_to_double, narrowed to float.

Note

Accepts the same input as mmgr_cellul_to_double, with only the result width differing.

Warning

The read stops at the first byte that is not part of the number. No length bounds it.

References mmgr_cellul_to_float().

Referenced by mmgr_cellul_to_float().

Variable Documentation

cellul

const CellularumLaboroNs cellul

static

Dispatch table instance named cellul, with each member set to its mmgr_cellul_ function.

Definition at line 341 of file cellularum_laboro.h.