sapi_string.h File Reference

Bounded, checked string manipulation (ADR-006). Replaces strcpy/strcat/sprintf/atoi/strtok-style unbounded operations with checked equivalents built on sapi_buffer_t. More...

#include "safeapi/utils/buffer/sapi_buffer.h"
#include "safeapi/utils/status/sapi_status.h"
#include "safeapi/utils/types/sapi_types.h"

Include dependency graph for sapi_string.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

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

Bounded, checked string manipulation (ADR-006). Replaces strcpy/strcat/sprintf/atoi/strtok-style unbounded operations with checked equivalents built on sapi_buffer_t.

sapi_string_t wraps a sapi_buffer_t; buf.length tracks the string's length NOT counting a NUL terminator. A NUL is only materialized on demand by sapi_string_c_str() (ADR-006 section 2.1) - callers that hand a sapi_string_t's storage directly to a legacy API without calling sapi_string_c_str() first will not find a NUL terminator there.

REQ-COMMON-STR-001: no dynamic allocation; the caller owns the backing storage for the lifetime of the string. REQ-COMMON-STR-002: sapi_string_copy() shall never call strlen() on its source; it scans for a NUL only up to the destination's capacity and fails rather than reading past it. REQ-COMMON-STR-003: content is treated as raw bytes/ASCII; no multi-byte/UTF-8-aware operations are provided.

Definition in file sapi_string.h.