sapi_string.c File Reference

Implementation of the bounded string module (ADR-006). More...

#include "safeapi/utils/string/sapi_string.h"
#include "safeapi/utils/cast/sapi_cast.h"
#include <string.h>

Include dependency graph for sapi_string.c:

Go to the source code of this file.

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_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_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_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).
static void	sapi_string_format_u64_digits (uint64_t value, char *out, size_t *out_len)
	Fills out[0..*out_len) with value's base-10 digits, most-significant first, no leading zeros (except "0" itself).
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_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.
static sapi_status_t	sapi_string_append_bytes (sapi_string_t *dest, const char *src, size_t n)
	Appends exactly n bytes of src to dest, no NUL scan, bounds-checked against dest's remaining capacity. Shared tail of every sapi_string_append_*() below - same append semantics as sapi_string_concat() but for a known, not-NUL-terminated length.
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_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_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_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.
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.

Detailed Description

Implementation of the bounded string module (ADR-006).

Definition in file sapi_string.c.

Function Documentation

sapi_string_format_u64_digits()

void sapi_string_format_u64_digits ( uint64_t value, char * out, size_t * out_len )

static

Fills out[0..*out_len) with value's base-10 digits, most-significant first, no leading zeros (except "0" itself).

Parameters

value	Value to format.
out	Destination buffer; must have room for at least 20 characters (UINT64_MAX has 20 decimal digits).
out_len	Receives the number of digit characters written.

Definition at line 312 of file sapi_string.c.

sapi_string_append_bytes()

sapi_status_t sapi_string_append_bytes ( sapi_string_t * dest, const char * src, size_t n )

static

Appends exactly n bytes of src to dest, no NUL scan, bounds-checked against dest's remaining capacity. Shared tail of every sapi_string_append_*() below - same append semantics as sapi_string_concat() but for a known, not-NUL-terminated length.

Parameters

dest	Destination string. Must be non-NULL and valid.
src	Source bytes. Must be non-NULL when n > 0.
n	Number of bytes to append.

Returns

SAPI_STATUS_OK; SAPI_STATUS_INVALID_PARAM for a bad argument; SAPI_STATUS_RESOURCE_EXHAUSTED if n exceeds dest's remaining capacity (dest left unmodified).

Definition at line 436 of file sapi_string.c.