Bounded String Manipulation

Checked replacements for strcpy/strcat/sprintf-style operations (ADR-006). More...

Files
file	src/utils/string/sapi_string.c
	Implementation of the bounded string module (ADR-006).

Data Structures
struct	sapi_string_t
	Bounded string: buf.length is the string length, not counting a NUL. More...

Functions
sapi_status_t	sapi_string_init (sapi_string_t *str, char *storage, size_t capacity)
	Binds a string to caller-owned storage. Initial length is 0 (empty string).
sapi_status_t	sapi_string_clear (sapi_string_t *str)
	Resets a string to empty. Capacity and storage are unchanged.
size_t	sapi_string_length (const sapi_string_t *str)
	Returns a string's current length (not counting a NUL terminator).
sapi_status_t	sapi_string_c_str (sapi_string_t *str, const char **out_cstr)
	Ensures a NUL terminator is present within capacity (without incrementing length) and returns a pointer to the string's storage, suitable for passing to a legacy NUL-terminated-string API.
sapi_status_t	sapi_string_copy (sapi_string_t *dest, const char *src)
	Bounded strcpy equivalent. Never calls strlen(src) - scans for a NUL only up to dest's capacity (REQ-COMMON-STR-002).
sapi_status_t	sapi_string_copy_n (sapi_string_t *dest, const char *src, size_t src_len)
	Bounded copy of an exact-length, not-necessarily-NUL-terminated source (e.g. a length-prefixed field). Never scans src.
sapi_status_t	sapi_string_concat (sapi_string_t *dest, const char *src)
	Bounded strcat equivalent. Never calls strlen(src) - scans for a NUL only up to dest's remaining capacity.
sapi_status_t	sapi_string_compare (const sapi_string_t *a, const sapi_string_t *b, int32_t *out_cmp)
	Bounded strcmp equivalent. Compares up to the shorter string's length, then by length if that prefix is equal.
sapi_status_t	sapi_string_find_char (const sapi_string_t *str, char c, bool *out_found, size_t *out_index)
	Bounded strchr equivalent. "Not found" is a normal outcome, not an error - see out_found.
sapi_status_t	sapi_string_find_substr (const sapi_string_t *haystack, const sapi_string_t *needle, bool *out_found, size_t *out_index)
	Bounded strstr equivalent. "Not found" is a normal outcome, not an error - see out_found.
sapi_status_t	sapi_string_split_next (const sapi_string_t *str, char delimiter, size_t *io_cursor, sapi_const_buffer_t *out_token, bool *out_has_token)
	Reentrant, bounded string splitting - unlike strtok(), all state is caller-owned via io_cursor, so multiple splits can run concurrently on different tasks (ADR-006 section 2.4).
sapi_status_t	sapi_string_from_u32 (sapi_string_t *dest, uint32_t value)
	Bounded base-10 itoa equivalent for uint32_t. Replaces dest's content.
sapi_status_t	sapi_string_from_i32 (sapi_string_t *dest, int32_t value)
	Bounded base-10 itoa equivalent for int32_t. Replaces dest's content.
sapi_status_t	sapi_string_from_u64 (sapi_string_t *dest, uint64_t value)
	Bounded base-10 itoa equivalent for uint64_t. Replaces dest's content.
sapi_status_t	sapi_string_from_i64 (sapi_string_t *dest, int64_t value)
	Bounded base-10 itoa equivalent for int64_t. Replaces dest's content.
sapi_status_t	sapi_string_append_u32 (sapi_string_t *dest, uint32_t value)
	Bounded base-10 append of a uint32_t to dest's existing content (unlike sapi_string_from_u32(), which replaces it). Intended to replace snprintf(buf, n, "...u...", v)-style line assembly with a checked, non-variadic, MISRA-clean primitive (ADR-006).
sapi_status_t	sapi_string_append_i32 (sapi_string_t *dest, int32_t value)
	Bounded base-10 append of an int32_t; a leading '-' is emitted for negative values. See sapi_string_append_u32().
sapi_status_t	sapi_string_append_u64 (sapi_string_t *dest, uint64_t value)
	Bounded base-10 append of a uint64_t. See sapi_string_append_u32().
sapi_status_t	sapi_string_append_i64 (sapi_string_t *dest, int64_t value)
	Bounded base-10 append of an int64_t; a leading '-' is emitted for negative values. See sapi_string_append_u32().
sapi_status_t	sapi_string_append_hex_u32 (sapi_string_t *dest, uint32_t value, uint8_t min_digits)
	Bounded append of a uint32_t formatted as lowercase hexadecimal (no "0x" prefix - the caller prepends a literal with sapi_string_concat() if wanted). Replaces snprintf(..., "%02x", v) / "0xx"-style formatting.
sapi_status_t	sapi_string_to_u32 (const sapi_string_t *str, uint32_t *out_value)
	Bounded base-10 atoi equivalent for uint32_t.
sapi_status_t	sapi_string_to_i32 (const sapi_string_t *str, int32_t *out_value)
	As sapi_string_to_u32(), for int32_t; a leading '-' is accepted.
sapi_status_t	sapi_string_to_u64 (const sapi_string_t *str, uint64_t *out_value)
	As sapi_string_to_u32(), for uint64_t.
sapi_status_t	sapi_string_to_i64 (const sapi_string_t *str, int64_t *out_value)
	As sapi_string_to_i32(), for int64_t.

Detailed Description

Checked replacements for strcpy/strcat/sprintf-style operations (ADR-006).

Function Documentation

sapi_string_init()

sapi_status_t sapi_string_init	(	sapi_string_t *	str,
		char *	storage,
		size_t	capacity )

Binds a string to caller-owned storage. Initial length is 0 (empty string).

Parameters

str	String to initialize. Must not be NULL.
storage	Caller-owned backing storage. Must not be NULL and must outlive str.
capacity	Usable size of storage in bytes. Must be > 0.

Returns

SAPI_STATUS_OK; SAPI_STATUS_INVALID_PARAM for a bad argument. REQ-COMMON-STR-010

Definition at line 10 of file sapi_string.c.

sapi_string_clear()

sapi_status_t sapi_string_clear

(

sapi_string_t *

str

)

Resets a string to empty. Capacity and storage are unchanged.

Parameters

str	String to clear. Must not be NULL.

Returns

SAPI_STATUS_OK; SAPI_STATUS_INVALID_PARAM if str is NULL. REQ-COMMON-STR-011

Definition at line 19 of file sapi_string.c.

sapi_string_length()

size_t sapi_string_length

(

const sapi_string_t *

str

)

Returns a string's current length (not counting a NUL terminator).

Parameters

str	String to query; NULL is a valid input (returns 0).

Returns

Current length in bytes, or 0 if str is NULL/invalid. REQ-COMMON-STR-012

Definition at line 28 of file sapi_string.c.

sapi_string_c_str()

sapi_status_t sapi_string_c_str	(	sapi_string_t *	str,
		const char **	out_cstr )

Ensures a NUL terminator is present within capacity (without incrementing length) and returns a pointer to the string's storage, suitable for passing to a legacy NUL-terminated-string API.

Parameters

str	String to terminate. Must not be NULL.
out_cstr	Receives the NUL-terminated pointer. Must not be NULL.

Returns

SAPI_STATUS_OK; SAPI_STATUS_INVALID_PARAM for a bad argument; SAPI_STATUS_RESOURCE_EXHAUSTED if str has no spare byte of capacity for the terminator (length == capacity). REQ-COMMON-STR-013

Definition at line 37 of file sapi_string.c.

sapi_string_copy()

sapi_status_t sapi_string_copy	(	sapi_string_t *	dest,
		const char *	src )

Bounded strcpy equivalent. Never calls strlen(src) - scans for a NUL only up to dest's capacity (REQ-COMMON-STR-002).

Parameters

dest	Destination string. Must not be NULL. Replaces dest's previous content on success; left unmodified on failure.
src	NUL-terminated source. Must not be NULL.

Returns

SAPI_STATUS_OK; SAPI_STATUS_INVALID_PARAM for a bad argument; SAPI_STATUS_RESOURCE_EXHAUSTED if no NUL is found within dest's capacity. REQ-COMMON-STR-014

Definition at line 68 of file sapi_string.c.

sapi_string_copy_n()

sapi_status_t sapi_string_copy_n	(	sapi_string_t *	dest,
		const char *	src,
		size_t	src_len )

Bounded copy of an exact-length, not-necessarily-NUL-terminated source (e.g. a length-prefixed field). Never scans src.

Parameters

dest	Destination string. Must not be NULL. Replaces dest's previous content on success; left unmodified on failure.
src	Source bytes. Must not be NULL.
src_len	Number of bytes to copy from src.

Returns

SAPI_STATUS_OK; SAPI_STATUS_INVALID_PARAM; SAPI_STATUS_RESOURCE_EXHAUSTED if src_len exceeds dest's capacity. REQ-COMMON-STR-015

Definition at line 59 of file sapi_string.c.

sapi_string_concat()

sapi_status_t sapi_string_concat	(	sapi_string_t *	dest,
		const char *	src )

Bounded strcat equivalent. Never calls strlen(src) - scans for a NUL only up to dest's remaining capacity.

Parameters

dest	Destination string. Must not be NULL. Appended to on success; left unmodified on failure.
src	NUL-terminated source. Must not be NULL.

Returns

SAPI_STATUS_OK; SAPI_STATUS_INVALID_PARAM; SAPI_STATUS_RESOURCE_EXHAUSTED if no NUL is found within dest's remaining capacity. REQ-COMMON-STR-016

Definition at line 100 of file sapi_string.c.

sapi_string_compare()

sapi_status_t sapi_string_compare	(	const sapi_string_t *	a,
		const sapi_string_t *	b,
		int32_t *	out_cmp )

Bounded strcmp equivalent. Compares up to the shorter string's length, then by length if that prefix is equal.

Parameters

a	First string. Must not be NULL.
b	Second string. Must not be NULL.
out_cmp	Receives <0, 0, or >0 (like strcmp). Must not be NULL.

Returns

SAPI_STATUS_OK; SAPI_STATUS_INVALID_PARAM for a bad argument. REQ-COMMON-STR-017

Definition at line 140 of file sapi_string.c.

sapi_string_find_char()

sapi_status_t sapi_string_find_char	(	const sapi_string_t *	str,
		char	c,
		bool *	out_found,
		size_t *	out_index )

Bounded strchr equivalent. "Not found" is a normal outcome, not an error - see out_found.

Parameters

str	String to search. Must not be NULL.
c	Character to find.
out_found	Receives whether c was found. Must not be NULL.
out_index	Receives the index of the first occurrence if found; unmodified if not found. Must not be NULL.

Returns

SAPI_STATUS_OK on a completed search (regardless of whether c was found); SAPI_STATUS_INVALID_PARAM for a bad argument. REQ-COMMON-STR-018

Definition at line 186 of file sapi_string.c.

sapi_string_find_substr()

sapi_status_t sapi_string_find_substr	(	const sapi_string_t *	haystack,
		const sapi_string_t *	needle,
		bool *	out_found,
		size_t *	out_index )

Bounded strstr equivalent. "Not found" is a normal outcome, not an error - see out_found.

Parameters

haystack	String to search within. Must not be NULL.
needle	Substring to find. Must not be NULL. An empty needle (length 0) is always found at index 0.
out_found	Receives whether needle was found. Must not be NULL.
out_index	Receives the index of the first occurrence if found; unmodified if not found. Must not be NULL.

Returns

SAPI_STATUS_OK on a completed search; SAPI_STATUS_INVALID_PARAM for a bad argument. REQ-COMMON-STR-019

Definition at line 214 of file sapi_string.c.

sapi_string_split_next()

sapi_status_t sapi_string_split_next	(	const sapi_string_t *	str,
		char	delimiter,
		size_t *	io_cursor,
		sapi_const_buffer_t *	out_token,
		bool *	out_has_token )

Reentrant, bounded string splitting - unlike strtok(), all state is caller-owned via io_cursor, so multiple splits can run concurrently on different tasks (ADR-006 section 2.4).

Parameters

str	String to split. Must not be NULL.
delimiter	Delimiter character.
io_cursor	Caller-owned cursor; caller initializes to 0 before the first call. Updated on each call. Must not be NULL.
out_token	Receives a zero-copy view of the next token (valid only as long as str's storage is), when out_has_token is true. Must not be NULL.
out_has_token	Receives whether a token was produced (false once the cursor has consumed the whole string). Must not be NULL.

Returns

SAPI_STATUS_OK on a completed call (regardless of out_has_token); SAPI_STATUS_INVALID_PARAM for a bad argument, including *io_cursor > str's length. REQ-COMMON-STR-020

Definition at line 257 of file sapi_string.c.

sapi_string_from_u32()

sapi_status_t sapi_string_from_u32	(	sapi_string_t *	dest,
		uint32_t	value )

Bounded base-10 itoa equivalent for uint32_t. Replaces dest's content.

Parameters

dest	Destination string. Must not be NULL.
value	Value to format.

Returns

SAPI_STATUS_OK on success; SAPI_STATUS_INVALID_PARAM if dest is NULL; SAPI_STATUS_RESOURCE_EXHAUSTED if the formatted digits do not fit dest's capacity. REQ-COMMON-STR-021

Definition at line 386 of file sapi_string.c.

sapi_string_from_i32()

sapi_status_t sapi_string_from_i32	(	sapi_string_t *	dest,
		int32_t	value )

Bounded base-10 itoa equivalent for int32_t. Replaces dest's content.

Parameters

dest	Destination string. Must not be NULL.
value	Value to format; a leading '-' is emitted for negative values.

Returns

Same status contract as sapi_string_from_u32(). REQ-COMMON-STR-022

Definition at line 405 of file sapi_string.c.

sapi_string_from_u64()

sapi_status_t sapi_string_from_u64	(	sapi_string_t *	dest,
		uint64_t	value )

Bounded base-10 itoa equivalent for uint64_t. Replaces dest's content.

Parameters

dest	Destination string. Must not be NULL.
value	Value to format.

Returns

Same status contract as sapi_string_from_u32(). REQ-COMMON-STR-023

Definition at line 341 of file sapi_string.c.

sapi_string_from_i64()

sapi_status_t sapi_string_from_i64	(	sapi_string_t *	dest,
		int64_t	value )

Bounded base-10 itoa equivalent for int64_t. Replaces dest's content.

Parameters

dest	Destination string. Must not be NULL.
value	Value to format; a leading '-' is emitted for negative values.

Returns

Same status contract as sapi_string_from_u32(). REQ-COMMON-STR-024

Definition at line 354 of file sapi_string.c.

sapi_string_append_u32()

sapi_status_t sapi_string_append_u32	(	sapi_string_t *	dest,
		uint32_t	value )

Bounded base-10 append of a uint32_t to dest's existing content (unlike sapi_string_from_u32(), which replaces it). Intended to replace snprintf(buf, n, "...u...", v)-style line assembly with a checked, non-variadic, MISRA-clean primitive (ADR-006).

Parameters

dest	Destination string. Must not be NULL. Appended to on success; left unmodified on failure.
value	Value to format and append.

Returns

SAPI_STATUS_OK; SAPI_STATUS_INVALID_PARAM if dest is NULL or its backing buffer is invalid; SAPI_STATUS_RESOURCE_EXHAUSTED if the formatted digits do not fit dest's remaining capacity. REQ-COMMON-STR-029

Definition at line 501 of file sapi_string.c.

sapi_string_append_i32()

sapi_status_t sapi_string_append_i32	(	sapi_string_t *	dest,
		int32_t	value )

Bounded base-10 append of an int32_t; a leading '-' is emitted for negative values. See sapi_string_append_u32().

Parameters

dest	Destination string. Must not be NULL. Appended to on success; left unmodified on failure.
value	Value to format and append.

Returns

Same status contract as sapi_string_append_u32(). REQ-COMMON-STR-030

Definition at line 519 of file sapi_string.c.

sapi_string_append_u64()

sapi_status_t sapi_string_append_u64	(	sapi_string_t *	dest,
		uint64_t	value )

Bounded base-10 append of a uint64_t. See sapi_string_append_u32().

Parameters

dest	Destination string. Must not be NULL. Appended to on success; left unmodified on failure.
value	Value to format and append.

Returns

Same status contract as sapi_string_append_u32(). REQ-COMMON-STR-031

Definition at line 463 of file sapi_string.c.

sapi_string_append_i64()

sapi_status_t sapi_string_append_i64	(	sapi_string_t *	dest,
		int64_t	value )

Bounded base-10 append of an int64_t; a leading '-' is emitted for negative values. See sapi_string_append_u32().

Parameters

dest	Destination string. Must not be NULL. Appended to on success; left unmodified on failure.
value	Value to format and append.

Returns

Same status contract as sapi_string_append_u32(). REQ-COMMON-STR-032

Definition at line 476 of file sapi_string.c.

sapi_string_append_hex_u32()

sapi_status_t sapi_string_append_hex_u32	(	sapi_string_t *	dest,
		uint32_t	value,
		uint8_t	min_digits )

Bounded append of a uint32_t formatted as lowercase hexadecimal (no "0x" prefix - the caller prepends a literal with sapi_string_concat() if wanted). Replaces snprintf(..., "%02x", v) / "0xx"-style formatting.

Parameters

dest	Destination string. Must not be NULL. Appended to on success; left unmodified on failure.
value	Value to format and append.
min_digits	Minimum digit count, zero-padded on the left; clamped to the range 1..8 (0 is treated as 1, values > 8 as 8). A value needing more than min_digits digits is emitted in full, never truncated.

Returns

Same status contract as sapi_string_append_u32(). REQ-COMMON-STR-033

Definition at line 537 of file sapi_string.c.

sapi_string_to_u32()

sapi_status_t sapi_string_to_u32	(	const sapi_string_t *	str,
		uint32_t *	out_value )

Bounded base-10 atoi equivalent for uint32_t.

Parameters

str	Source string. Must not be NULL and must be entirely composed of ASCII digits (no sign, no whitespace).
out_value	Receives the parsed value. Must not be NULL.

Returns

SAPI_STATUS_OK; SAPI_STATUS_INVALID_PARAM if str is empty or contains a non-digit character; SAPI_STATUS_VALUE_OUT_OF_RANGE if the value does not fit uint32_t. REQ-COMMON-STR-025

Definition at line 700 of file sapi_string.c.

sapi_string_to_i32()

sapi_status_t sapi_string_to_i32	(	const sapi_string_t *	str,
		int32_t *	out_value )

As sapi_string_to_u32(), for int32_t; a leading '-' is accepted.

Parameters

str	Source string. Must not be NULL; digits with an optional leading '-', no whitespace.
out_value	Receives the parsed value. Must not be NULL.

Returns

Same status contract as sapi_string_to_u32(). REQ-COMMON-STR-026

Definition at line 717 of file sapi_string.c.

sapi_string_to_u64()

sapi_status_t sapi_string_to_u64	(	const sapi_string_t *	str,
		uint64_t *	out_value )

As sapi_string_to_u32(), for uint64_t.

Parameters

str	Source string. Must not be NULL and must be entirely composed of ASCII digits (no sign, no whitespace).
out_value	Receives the parsed value. Must not be NULL.

Returns

Same status contract as sapi_string_to_u32(). REQ-COMMON-STR-027

Definition at line 586 of file sapi_string.c.

sapi_string_to_i64()

sapi_status_t sapi_string_to_i64	(	const sapi_string_t *	str,
		int64_t *	out_value )

As sapi_string_to_i32(), for int64_t.

Parameters

str	Source string. Must not be NULL; digits with an optional leading '-', no whitespace.
out_value	Receives the parsed value. Must not be NULL.

Returns

Same status contract as sapi_string_to_u32(). REQ-COMMON-STR-028

Definition at line 625 of file sapi_string.c.