NUL-terminated string utilities. More...

#include <rlib/rtypes.h>
#include <rlib/data/rlist.h>
#include <stdarg.h>
#include <stdio.h>

Data Structures
struct	RStrChunk
	Pointer-and-size view of a string region. More...

struct	RStrKV
	A pair of borrowed chunks representing one key / value binding inside a larger string. More...

struct	RStrMatchToken
	One token of a parsed pattern, paired with the matched span. More...

struct	RStrMatchResult
	Result of r_str_match_pattern. More...

Macros
#define	R_STR_SIZEOF(str) (sizeof (str) - 1)
	Compile-time string length, excluding the terminating NUL.

#define	R_STR_WITH_SIZE_ARGS(str) (str), R_STR_SIZEOF (str)
	Expand a string literal into a (pointer, length) argument pair suitable for functions that take a separate size.

#define	r_strtod(str, endptr) r_str_to_double (str, endptr, NULL)
	`strtod` equivalent; drops the optional res argument.

#define	r_strtof(str, endptr) r_str_to_float (str, endptr, NULL)
	`strtof` equivalent; drops the optional res argument.

#define	r_strtoll(str, endptr, base) r_str_to_int64 (str, endptr, base, NULL)
	`strtoll` equivalent (always 64-bit).

#define	r_strtoull(str, endptr, base) r_str_to_uint64 (str, endptr, base, NULL)
	`strtoull` equivalent (always 64-bit).

Enumerations
enum	RStrParse { R_STR_PARSE_OK , R_STR_PARSE_RANGE , R_STR_PARSE_INVAL }
	Status code returned by the string-parsing helpers. More...

Functions
Length and errno descriptions
Basic utilities used by the rest of this header. `r_strlen` mirrors `strlen`; `r_strerror` is a thread-safe wrapper around the C runtime's `strerror`.
const rchar *	r_strerror (int errnum, rchar *buf, rsize size)
	Thread-safe wrapper around the C runtime's strerror.

rsize	r_strlen (const rchar *str)
	Return the byte length of the NUL-terminated string `str`.

Character / substring search
The `r_str` names mirror their C-stdlib equivalents (`strspn`, `strchr`, `strstr`, etc.) and require NUL-terminated input. The `r_str_ptr_of_` / `r_str_idx_of_*` variants take an explicit size (-1 = NUL-terminated) and return either a pointer into `str` on match (or NULL on miss) or a byte index (or -1).
rssize	r_str_idx_of_c (const rchar *str, rssize strsize, rchar c)
	Locate the first occurrence of byte `c` in `str`, returning its index.

rssize	r_str_idx_of_c_any (const rchar str, rssize strsize, const rchar c, rssize chars)
	Index of the first byte in `str` that occurs in the set `c` (the first `chars` bytes of which form the set).

rssize	r_str_idx_of_c_case (const rchar *str, rssize strsize, rchar c)
	Case-insensitive variant of r_str_idx_of_c.

rssize	r_str_idx_of_str (const rchar str, rssize strsize, const rchar sub, rssize subsize)
	Index of the first occurrence of `sub` inside `str`.

rssize	r_str_idx_of_str_case (const rchar str, rssize strsize, const rchar sub, rssize subsize)
	Case-insensitive variant of r_str_idx_of_str.

rchar *	r_str_ptr_of_c (const rchar *str, rssize strsize, rchar c)
	Locate the first occurrence of byte `c` in `str`.

rchar *	r_str_ptr_of_c_any (const rchar str, rssize strsize, const rchar c, rssize chars)
	Locate the first occurrence in `str` of any byte from the set `c` (the first `chars` bytes of which form the lookup set).

rchar *	r_str_ptr_of_str (const rchar str, rssize strsize, const rchar sub, rssize subsize)
	Locate the first occurrence of `sub` inside `str`.

rchar *	r_str_ptr_of_str_case (const rchar str, rssize strsize, const rchar sub, rssize subsize)
	Case-insensitive variant of r_str_ptr_of_str.

rchar *	r_strchr (const rchar *str, int c)
	Locate the first occurrence of `c` in `str`. Behaves like `strchr`.

rsize	r_strcspn (const rchar str, const rchar cset)
	Length of the initial substring of `str` that contains no bytes from `cset`. Behaves like `strcspn`.

rchar *	r_strnchr (const rchar *str, int c, rsize size)
	Bounded variant of r_strchr; scans at most `size` bytes.

rchar *	r_strnrchr (const rchar *str, int c, rsize size)
	Bounded variant of r_strrchr; scans at most `size` bytes.

rchar *	r_strnstr (const rchar str, const rchar sub, rsize size)
	Bounded variant of r_strstr; scans at most `size` bytes.

rchar *	r_strpbrk (const rchar str, const rchar set)
	Locate the first byte in `str` that occurs in `set`. Behaves like `strpbrk`.

rchar *	r_strrchr (const rchar *str, int c)
	Locate the last occurrence of `c` in `str`. Behaves like `strrchr`.

rsize	r_strspn (const rchar str, const rchar set)
	Length of the initial substring of `str` that consists entirely of bytes from `set`. Behaves like `strspn`.

rchar *	r_strstr (const rchar str, const rchar sub)
	Locate the first occurrence of `sub` inside `str`. Behaves like `strstr`.

Copy and concatenate
`r_strcpy` / `r_strncpy` / `r_strcat` / `r_strncat` behave exactly as their standard C counterparts. `r_stpcpy` / `r_stpncpy` return a pointer to the terminating NUL of the destination after the copy, useful for chained appends.
rchar *	r_stpcpy (rchar dst, const rchar src)
	Like r_strcpy but returns the address of the NUL it wrote.

rchar *	r_stpncpy (rchar dst, const rchar src, rsize len)
	Like r_strncpy but returns the address of the NUL it wrote.

rchar *	r_strcat (rchar dst, const rchar src)
	Append `src` to `dst`. Behaves like `strcat`.

rchar *	r_strcpy (rchar dst, const rchar src)
	Copy `src` into `dst` including the terminating NUL. Behaves like `strcpy`.

rchar *	r_strncat (rchar dst, const rchar src, rsize len)
	Append at most `len` bytes of `src` to `dst`. Behaves like `strncat`.

rchar *	r_strncpy (rchar dst, const rchar src, rsize len)
	Copy at most `len` bytes of `src` into `dst`. Behaves like `strncpy`.

Duplication
All return freshly `r_malloc'd` buffers; caller `r_free's`. NULL is returned on allocation failure (and, for r_strdup, when `str` itself is NULL).
rchar *	r_strdup (const rchar *str)
	Duplicate a NUL-terminated string.

rchar *	r_strdup_size (const rchar *str, rssize size)
	Duplicate the first `size` bytes of `str`.

rchar *	r_strdup_strip (const rchar str, const rchar chars)
	Duplicate `str` with leading and trailing `chars` removed.

rchar *	r_strdup_wstrip (const rchar *str)
	Duplicate `str` with leading and trailing whitespace removed.

rchar *	r_strndup (const rchar *str, rsize n)
	Duplicate at most `n` bytes of `str` (always NUL-terminated).

Strip
In-place strip functions mutate `str` by NUL-truncating from the trailing side and return a pointer somewhere inside `str` past any leading match. The `l-prefixed` variants only strip leading characters and return a const pointer (the source isn't written). The `t-prefixed` variants only strip trailing characters.
const rchar *	r_str_lstrip (const rchar str, const rchar chars)
	Skip leading `chars`; returns a pointer past them.

const rchar *	r_str_lwstrip (const rchar *str)
	Skip leading whitespace; returns a pointer past it.

rchar *	r_str_strip (rchar str, const rchar chars)
	Strip leading and trailing `chars` from `str` in place.

rchar *	r_str_tstrip (rchar str, const rchar chars)
	Strip trailing `chars` from `str` in place.

rchar *	r_str_twstrip (rchar *str)
	Strip trailing whitespace from `str` in place.

rchar *	r_str_wstrip (rchar *str)
	Strip leading and trailing whitespace from `str` in place.

Join and split
Join and split helpers that allocate fresh buffers. Caller owns the result and is responsible for `r_free` / `r_strv_free`.
rchar *	r_strjoin (const rchar *delim,...)
	Concatenate the variadic NUL-terminated strings, separating them with `delim`, into a freshly allocated buffer.

rchar *	r_strjoinv (const rchar *delim, va_list args)
	va_list flavour of r_strjoin.

rchar *	r_strnjoin (rchar str, rsize size, const rchar delim,...)
	Join into a caller-supplied buffer of `size` bytes.

rchar *	r_strnjoinv (rchar str, rsize size, const rchar delim, va_list args)
	va_list flavour of r_strnjoin.

rchar **	r_strsplit (const rchar str, const rchar delim, rsize max)
	Split `str` on `delim` into a freshly allocated rchar** string vector (NULL-terminated).

scanf-style scanning
int	r_strscanf (const rchar str, const rchar fmt,...) R_ATTR_SCANF(2
	`sscanf` passthrough.

int int	r_strvscanf (const rchar str, const rchar fmt, va_list args) R_ATTR_SCANF(2
	va_list flavour of r_strscanf.

String-to-number parsing
Each function parses an integer from `str` using base `base` (2 through 36; 0 means autodetect: a `0x` / `0X` prefix selects base 16 and a leading `0` selects base 8, otherwise base 10). On success the parsed value is returned and, if `endptr` is non-NULL, `endptr` is set to one past the last consumed character. On failure the return value is 0 and `res` (if non-NULL) carries `R_STR_PARSE_INVAL` or `R_STR_PARSE_RANGE`; `endptr` then points at the first character that could not be consumed (equal to `str` only for a NULL / empty / bad-base input). The fixed-width spellings are the source of truth; `r_str_to_int` / `r_str_to_uint` and the `r_strto` shortcut macros below dispatch to the right width based on the host's `int` / `long` size.
rdouble	r_str_to_double (const rchar str, const rchar endptr, RStrParse res)
	Parse a double-precision float from `str`.

rfloat	r_str_to_float (const rchar str, const rchar endptr, RStrParse res)
	Single-precision counterpart of r_str_to_double.

rint8	r_str_to_int8 (const rchar str, const rchar endptr, ruint base, RStrParse res)
	Parse an 8-bit signed integer from `str`.

rint16	r_str_to_int16 (const rchar str, const rchar endptr, ruint base, RStrParse res)
	Parse a 16-bit signed integer from `str`.

rint32	r_str_to_int32 (const rchar str, const rchar endptr, ruint base, RStrParse res)
	Parse a 32-bit signed integer from `str`.

rint64	r_str_to_int64 (const rchar str, const rchar endptr, ruint base, RStrParse res)
	Parse a 64-bit signed integer from `str`.

ruint8	r_str_to_uint8 (const rchar str, const rchar endptr, ruint base, RStrParse res)
	Parse an 8-bit unsigned integer from `str`.

ruint16	r_str_to_uint16 (const rchar str, const rchar endptr, ruint base, RStrParse res)
	Parse a 16-bit unsigned integer from `str`.

ruint32	r_str_to_uint32 (const rchar str, const rchar endptr, ruint base, RStrParse res)
	Parse a 32-bit unsigned integer from `str`.

ruint64	r_str_to_uint64 (const rchar str, const rchar endptr, ruint base, RStrParse res)
	Parse a 64-bit unsigned integer from `str`.

Length-bounded numeric parsers
Each `_size` variant behaves like its unbounded sibling but parses only the first `size` bytes of `str`, so it is safe on a region that is not NUL-terminated (e.g. a slice of a memory-mapped buffer). The returned `endptr` points into `str`.
rdouble	r_str_to_double_size (const rchar str, rssize size, const rchar endptr, RStrParse res)

rfloat	r_str_to_float_size (const rchar str, rssize size, const rchar endptr, RStrParse res)

rint8	r_str_to_int8_size (const rchar str, rssize size, const rchar endptr, ruint base, RStrParse res)

rint16	r_str_to_int16_size (const rchar str, rssize size, const rchar endptr, ruint base, RStrParse res)

rint32	r_str_to_int32_size (const rchar str, rssize size, const rchar endptr, ruint base, RStrParse res)

rint64	r_str_to_int64_size (const rchar str, rssize size, const rchar endptr, ruint base, RStrParse res)

ruint8	r_str_to_uint8_size (const rchar str, rssize size, const rchar endptr, ruint base, RStrParse res)

ruint16	r_str_to_uint16_size (const rchar str, rssize size, const rchar endptr, ruint base, RStrParse res)

ruint32	r_str_to_uint32_size (const rchar str, rssize size, const rchar endptr, ruint base, RStrParse res)

ruint64	r_str_to_uint64_size (const rchar str, rssize size, const rchar endptr, ruint base, RStrParse res)

String list / string vector
Two flavours of list-of-strings. The `r_str_list_` form returns an `RSList` (singly linked list of `rchar` ``). The `r_strv_` form returns a NULL-terminated `rchar` `*` array. Both copy the input strings; ownership of the result transfers to the caller.
RSList *	r_str_list_new (const rchar *str0,...)
	Build an RSList from a NULL-terminated variadic argument list of NUL-terminated strings.

RSList *	r_str_list_newv (const rchar *str0, va_list args)
	va_list flavour of r_str_list_new.

rchar **	r_strv_new (const rchar *str0,...)
	Build a NULL-terminated `rchar**` vector from a variadic argument list of NUL-terminated strings.

rchar **	r_strv_newv (const rchar *str0, va_list args)
	va_list flavour of r_strv_new.

rchar **	r_strv_copy (rchar const strv)
	Duplicate a string vector (each element and the vector itself).

rboolean	r_strv_contains (rchar const strv, const rchar *str)
	TRUE iff `strv` contains a string equal to `str`.

void	r_strv_foreach (rchar **strv, RFunc func, rpointer user)
	Invoke `func`(s, `user`) for each string `s` in `strv`.

rchar *	r_strv_join (rchar const strv, const rchar *delim)
	Join the strings in `strv` with `delim` into a freshly allocated buffer; caller `r_free's`.

rsize	r_strv_len (rchar const strv)
	Number of strings in `strv` (the trailing NULL excluded).

void	r_strv_free (rchar **strv)
	Free a string vector built by r_strv_new and friends.

Comparison
Match the standard C strcmp / strncmp semantics: a negative, zero or positive result indicates `a` < `b`, `a` == `b` or `a` > `b` respectively. The `casecmp` variants compare case-insensitively in the ASCII range. The `_size` variants take explicit lengths instead of requiring NUL termination; pass -1 on either side to fall back to `r_strlen`.
#define	r_str_equals(a, b) (r_strcmp (a, b) == 0)
	Convenience macro: TRUE iff `a` and `b` compare equal.

int	r_strcasecmp (const rchar a, const rchar b)
	Case-insensitive byte-comparison of two NUL-terminated strings.

int	r_strcasecmp_size (const rchar a, rssize asize, const rchar b, rssize bsize)
	Case-insensitive byte-comparison with explicit sizes; -1 means NUL-terminated.

int	r_strcmp (const rchar a, const rchar b)
	Byte-comparison of two NUL-terminated strings. Behaves like `strcmp`.

int	r_strcmp_size (const rchar a, rssize asize, const rchar b, rssize bsize)
	Byte-comparison with explicit sizes; -1 means NUL-terminated.

int	r_strncasecmp (const rchar a, const rchar b, rsize len)
	Case-insensitive byte-comparison of at most `len` bytes.

int	r_strncmp (const rchar a, const rchar b, rsize len)
	Byte-comparison of at most `len` bytes. Behaves like `strncmp`.

Prefix / suffix / substring tests
Boolean predicates that don't return a position.
#define	r_str_has_substring(str, sub) (r_str_idx_of_str (str, -1, sub, -1) >= 0)
	Test whether `str` contains `sub` anywhere.

rboolean	r_str_has_prefix (const rchar str, const rchar prefix)
	Test whether `str` begins with `prefix`.

rboolean	r_str_has_suffix (const rchar str, const rchar suffix)
	Test whether `str` ends with `suffix`.

printf-style formatting
Thin wrappers around the C runtime's printf family. The `r_sprintf` / `r_vsprintf` forms exist mostly to silence MSVC's deprecation warning on plain `sprintf`; the rest match their standard counterparts. `r_asprintf` / `r_vasprintf` allocate the output buffer; `r_strprintf` / `r_strvprintf` return the allocated buffer directly (caller `r_free's`).
#define	r_snprintf snprintf
	`snprintf` passthrough.

#define	r_sprintf sprintf
	`sprintf` passthrough on non-MSVC platforms.

#define	r_vsprintf vsprintf
	`vsprintf` passthrough on non-MSVC platforms.

#define	r_vsnprintf vsnprintf
	`vsnprintf` passthrough.

int	r_asprintf (rchar *str, const rchar fmt,...)
	Format into a freshly `r_malloc'd` buffer and store its address at *`str`.

rchar *	r_strprintf (const rchar *fmt,...)
	Format into a freshly `r_malloc'd` buffer and return it.

rchar *	r_strvprintf (const rchar *fmt, va_list args)
	va_list flavour of r_strprintf.

int	r_vasprintf (rchar *str, const rchar fmt, va_list args)
	va_list flavour of r_asprintf.

String chunk (pointer-and-size view)
`RStrChunk` borrows its bytes from elsewhere - the chunk does not own the storage and freeing it is up to the caller. Used by the parsers and tokenisers in this header so they can return spans without allocating, and by `r_str_kv_*` for key / value pairs. The macro shorthand for search and indexing methods (e.g. `r_str_chunk_idx_of_c`) delegates to the non-chunk equivalents in the "Character / substring search" group above.
#define	R_STR_CHUNK_INIT { NULL, 0 }
	Zero-initialiser for stack RStrChunk values.

#define	r_str_chunk_dup(chunk) r_strndup ((chunk)->str, (chunk)->size)
	Duplicate the chunk's bytes into a fresh NUL-terminated string.

#define	r_str_chunk_end(chunk) ((chunk)->str + (chunk)->size)
	Pointer one past the last byte of the chunk.

#define	r_str_chunk_idx_of_c(buf, c) r_str_idx_of_c ((buf)->str, (buf)->size, c)
	Convenience: r_str_idx_of_c on the chunk's bytes.

#define	r_str_chunk_idx_of_c_any(buf, c, chars) r_str_idx_of_c_any ((buf)->str, (buf)->size, c, chars)
	Convenience: r_str_idx_of_c_any on the chunk's bytes.

#define	r_str_chunk_idx_of_c_case(buf, c) r_str_idx_of_c_case ((buf)->str, (buf)->size, c)
	Convenience: r_str_idx_of_c_case on the chunk's bytes.

#define	r_str_chunk_idx_of_str(buf, sub, subsize) r_str_idx_of_str ((buf)->str, (buf)->size, sub, subsize)
	Convenience: r_str_idx_of_str on the chunk's bytes.

#define	r_str_chunk_idx_of_str_case(buf, sub, subsize) r_str_idx_of_str_case ((buf)->str, (buf)->size, sub, subsize)
	Convenience: r_str_idx_of_str_case on the chunk's bytes.

#define	r_str_chunk_ptr_of_c(buf, c) r_str_ptr_of_c ((buf)->str, (buf)->size, c)
	Convenience: r_str_ptr_of_c on the chunk's bytes.

#define	r_str_chunk_ptr_of_c_any(buf, c, chars) r_str_ptr_of_c_any ((buf)->str, (buf)->size, c, chars)
	Convenience: r_str_ptr_of_c_any on the chunk's bytes.

#define	r_str_chunk_ptr_of_c_case(buf, c) r_str_ptr_of_c_case ((buf)->str, (buf)->size, c)
	Convenience: r_str_ptr_of_c_case on the chunk's bytes.

#define	r_str_chunk_ptr_of_str(buf, sub, subsize) r_str_ptr_of_str ((buf)->str, (buf)->size, sub, subsize)
	Convenience: r_str_ptr_of_str on the chunk's bytes.

#define	r_str_chunk_ptr_of_str_case(buf, sub, subsize) r_str_ptr_of_str_case ((buf)->str, (buf)->size, sub, subsize)
	Convenience: r_str_ptr_of_str_case on the chunk's bytes.

int	r_str_chunk_casecmp (const RStrChunk buf, const rchar str, rssize size)
	Case-insensitive variant of r_str_chunk_cmp.

int	r_str_chunk_cmp (const RStrChunk buf, const rchar str, rssize size)
	Compare a chunk against a (str, size) pair byte-for-byte.

rboolean	r_str_chunk_has_prefix (const RStrChunk buf, const rchar str, rssize size)
	Test whether the chunk starts with the given prefix.

void	r_str_chunk_lwstrip (RStrChunk *buf)
	Strip leading whitespace from the chunk in place.

RStrParse	r_str_chunk_next_line (const RStrChunk buf, RStrChunk line)
	Consume one line from `buf` into `line`.

ruint	r_str_chunk_split (RStrChunk buf, const rchar delim,...)
	Split `buf` into chunks using the NUL-terminated string `delim` as the separator.

ruint	r_str_chunk_splitv (RStrChunk buf, const rchar delim, va_list args)
	va_list flavour of r_str_chunk_split.

void	r_str_chunk_wstrip (RStrChunk *buf)
	Strip leading and trailing whitespace from the chunk in place.

Key-value parsing
`RStrKV` is a pair of chunks built from one `key<delim>value` binding inside a larger string. Like `RStrChunk`, neither member owns the underlying storage; freeing is up to whoever owns the input buffer.
#define	R_STR_KV_INIT { R_STR_CHUNK_INIT, R_STR_CHUNK_INIT }
	Zero-initialiser for stack RStrKV values.

#define	r_str_kv_dup_key(kv) r_str_chunk_dup (&(kv)->key)
	Duplicate the key chunk into a fresh NUL-terminated string.

#define	r_str_kv_dup_value(kv) r_str_chunk_dup (&(kv)->val)
	Duplicate the value chunk into a fresh NUL-terminated string.

RStrParse	r_str_kv_parse (RStrKV kv, const rchar str, rssize size, const rchar delim, const rchar *endptr)
	Parse one `key<delim>value` pair starting at `str`.

RStrParse	r_str_kv_parse_multiple (RStrKV kv, const rchar str, rssize size, const rchar kvdelim, rssize kvdsize, const rchar delim, rssize dsize, const rchar **endptr)
	Parse a sequence of key / value pairs.

rboolean	r_str_kv_is_key (const RStrKV kv, const rchar key, rssize size)
	Test whether the KV's key matches `key` (first `size` bytes; -1 = NUL-terminated).

rboolean	r_str_kv_is_value (const RStrKV kv, const rchar val, rssize size)
	Test whether the KV's value matches `val`.

Memory dump and hex
Helpers that render a byte buffer as printable text - either a hex+ASCII dump suitable for logging, or a plain hex string for serialisation. `r_str_hex_to_binary` / `r_str_hex_mem` invert the hex variants.
#define	R_STR_MEM_DUMP_SIZE(align) ((align * 4) + (align / 4) + (RLIB_SIZEOF_VOID_P * 2) + 8)
	Required bytes in the destination buffer to dump `align` source bytes per line via `r_str_mem_dump`.

void	r_str_dump (rchar dst, const rchar src, rsize size)
	Render the pointer of `src` followed by the printable-ASCII rendering of its `size` bytes (non-printable bytes shown as `'`.') into `dst`, NUL-terminated.

ruint8 *	r_str_hex_mem (const rchar hex, rsize outsize)
	Decode hex digits from `hex` into a freshly allocated byte buffer; stores the resulting size in *`outsize`.

rsize	r_str_hex_to_binary (const rchar hex, ruint8 bin, rsize size)
	Decode hex digits from `hex` into `bin` (capacity `size` bytes).

rboolean	r_str_mem_dump (rchar str, const ruint8 ptr, rsize size, rsize align)
	Render `size` bytes from `ptr` into `str` as a multi-line hex+ASCII dump.

rchar *	r_str_mem_dump_dup (const ruint8 *ptr, rsize size, rsize align)
	Like r_str_mem_dump but allocates the destination buffer.

rchar *	r_str_mem_hex (const ruint8 *ptr, rsize size)
	Encode `size` bytes from `ptr` as a contiguous lowercase hex string.

rchar *	r_str_mem_hex_full (const ruint8 ptr, rsize size, const rchar divider, rsize interval)
	Encode `ptr` as hex with an arbitrary divider inserted every `interval` bytes (e.g. ":" for "DE:AD:BE:EF").

Pattern matching
Simple shell-style pattern matching (`'`?' single-byte wildcard, `'*'` any-length wildcard). The detailed variant (`r_str_match_pattern`) populates an `RStrMatchResult` with the exact span each pattern token consumed; the simple variant just returns TRUE / FALSE.
enum	RStrTokenType { R_STR_TOKEN_NONE = -1 , R_STR_TOKEN_CHARS , R_STR_TOKEN_WILDCARD , R_STR_TOKEN_WILDCARD_SIZED , R_STR_TOKEN_COUNT }
	Token type produced by the pattern matcher. More...

enum	RStrMatchResultType { R_STR_MATCH_RESULT_INVAL = -4 , R_STR_MATCH_RESULT_OOM = -3 , R_STR_MATCH_RESULT_INVALID_PATTERN = -2 , R_STR_MATCH_RESULT_PATTERN_NOT_IMPL = -1 , R_STR_MATCH_RESULT_OK = 0 , R_STR_MATCH_RESULT_NO_MATCH }
	Status code from r_str_match_pattern. More...

rboolean	r_str_match_simple_pattern (const rchar str, rssize size, const rchar pattern)
	Test whether `str` matches a simple shell-style pattern.

RStrMatchResultType	r_str_match_pattern (const rchar str, rssize size, const rchar pattern, RStrMatchResult **result)
	Match `str` against `pattern` and, on success, allocate a detailed match-result record into *`result`.

Detailed Description

NUL-terminated string utilities.

Mostly thin wrappers around the C runtime's string functions, plus rlib-specific helpers for pointer-and-size string views (RStrChunk), key-value parsing (RStrKV), pattern matching, integer / float parsing, ASCII string lists (rchar **), and printf / scanf convenience.

Functions in this header generally operate on rchar * strings; a separate rssize size argument indicates that -1 means "scan to the terminating NUL" while a non-negative value bounds the operation regardless of NUL bytes within. Functions that take only a pointer (no size) require a NUL-terminated input.

Enumeration Type Documentation

◆ RStrMatchResultType

enum RStrMatchResultType

Status code from r_str_match_pattern.

Negative values are errors; R_STR_MATCH_RESULT_OK and R_STR_MATCH_RESULT_NO_MATCH are the two regular outcomes.

Enumerator
R_STR_MATCH_RESULT_INVAL	Caller passed a bad argument.
R_STR_MATCH_RESULT_OOM	Allocation for the result failed.
R_STR_MATCH_RESULT_INVALID_PATTERN	`pattern` didn't parse.
R_STR_MATCH_RESULT_PATTERN_NOT_IMPL	Recognised pattern token isn't yet supported.
R_STR_MATCH_RESULT_OK	Match found; result populated.
R_STR_MATCH_RESULT_NO_MATCH	Pattern parsed but didn't match.

◆ RStrTokenType

enum RStrTokenType

Token type produced by the pattern matcher.

The same vocabulary as r_mem_scan_*: a pattern is a sequence of literal-byte runs interleaved with single-byte and sized wildcards.

Enumerator
R_STR_TOKEN_NONE	Sentinel for "unset" token type.
R_STR_TOKEN_CHARS	Literal byte run.
R_STR_TOKEN_WILDCARD	Single-byte wildcard ("?").
R_STR_TOKEN_WILDCARD_SIZED	Multi-byte wildcard with an explicit length.
R_STR_TOKEN_COUNT	Number of token types; not a value.

Function Documentation

◆ r_str_chunk_cmp()

int r_str_chunk_cmp	(	const RStrChunk *	buf,
		const rchar *	str,
		rssize	size
	)

Compare a chunk against a (str, size) pair byte-for-byte.

Parameters

buf	Chunk under test.
str	String to compare against.
size	Bytes in `str`, or -1 to fall back to r_strlen.

Returns: Negative, zero, or positive as in r_strcmp.

◆ r_str_chunk_has_prefix()

rboolean r_str_chunk_has_prefix	(	const RStrChunk *	buf,
		const rchar *	str,
		rssize	size
	)

Test whether the chunk starts with the given prefix.

Parameters

buf	Chunk under test.
str	Prefix to look for.
size	Bytes in `str`, or -1 to fall back to r_strlen.

◆ r_str_chunk_next_line()

RStrParse r_str_chunk_next_line	(	const RStrChunk *	buf,
		RStrChunk *	line
	)

Consume one line from buf into line.

Iteration state lives in line, not buf (which is never modified): zero-initialise line for the first call and pass the same line back on each subsequent call to advance through buf. Line terminators are not included in line. Returns R_STR_PARSE_OK per line, R_STR_PARSE_RANGE when the input is exhausted, or R_STR_PARSE_INVAL on bad arguments / empty buf.

◆ r_str_chunk_split()

ruint r_str_chunk_split	(	RStrChunk *	buf,
		const rchar *	delim,
			...
	)

Split buf into chunks using the NUL-terminated string delim as the separator.

The variadic arguments must be (RStrChunk *) pointers terminated by a single NULL; each is filled with one piece of buf in order.

Returns: Number of output chunks that were filled.

◆ r_str_dump()

void r_str_dump	(	rchar *	dst,
		const rchar *	src,
		rsize	size
	)

Render the pointer of src followed by the printable-ASCII rendering of its size bytes (non-printable bytes shown as '.') into dst, NUL-terminated.

dst must hold the pointer text plus size bytes plus the NUL. Unlike r_str_mem_dump this is ASCII-only (no hex columns) and takes no align argument.

◆ r_str_hex_mem()

ruint8 * r_str_hex_mem	(	const rchar *	hex,
		rsize *	outsize
	)

Decode hex digits from hex into a freshly allocated byte buffer; stores the resulting size in *outsize.

Returns: The buffer, or NULL on failure. Caller r_free's.

◆ r_str_hex_to_binary()

rsize r_str_hex_to_binary	(	const rchar *	hex,
		ruint8 *	bin,
		rsize	size
	)

Decode hex digits from hex into bin (capacity size bytes).

Returns: Number of bytes written to bin.

◆ r_str_kv_parse()

RStrParse r_str_kv_parse	(	RStrKV *	kv,
		const rchar *	str,
		rssize	size,
		const rchar *	delim,
		const rchar **	endptr
	)

Parse one key<delim>value pair starting at str.

On success, kv->key and kv->val are filled with views into str (no copies) and *endptr (when non-NULL) is set to one past the consumed bytes. delim is a NUL-terminated string of separator characters; the first occurrence of any of them ends the key.

Parameters

kv	Receives the parsed key / value chunks.
str	Input buffer.
size	Bytes in `str`, or -1 to fall back to r_strlen.
delim	NUL-terminated set of separator characters.
endptr	Optional out-pointer set to one past the consumed bytes.

◆ r_str_kv_parse_multiple()

RStrParse r_str_kv_parse_multiple	(	RStrKV *	kv,
		const rchar *	str,
		rssize	size,
		const rchar *	kvdelim,
		rssize	kvdsize,
		const rchar *	delim,
		rssize	dsize,
		const rchar **	endptr
	)

Parse a sequence of key / value pairs.

kv must point to enough storage for the caller's expected number of pairs. kvdelim separates keys from values within each pair; delim separates pairs from each other. Sizes may be -1 to fall back to r_strlen on each delimiter string.

Returns: R_STR_PARSE_OK on success.

◆ r_str_match_pattern()

RStrMatchResultType r_str_match_pattern	(	const rchar *	str,
		rssize	size,
		const rchar *	pattern,
		RStrMatchResult **	result
	)

Match str against pattern and, on success, allocate a detailed match-result record into *result.

The record carries one RStrMatchToken per pattern token, giving the exact input span each token matched. Caller r_free's *result on success.

Returns: One of R_STR_MATCH_RESULT_OK / _NO_MATCH; negative on error.

◆ r_str_match_simple_pattern()

rboolean r_str_match_simple_pattern	(	const rchar *	str,
		rssize	size,
		const rchar *	pattern
	)

Test whether str matches a simple shell-style pattern.

Accepts '?' (single-byte wildcard) and '*' (any-length wildcard) in pattern. Returns TRUE on match. Cheaper than r_str_match_pattern when the caller only needs the boolean answer.

Parameters

str	Input buffer.
size	Bytes in `str`, or -1 to fall back to r_strlen.
pattern	NUL-terminated pattern with '?' / '*' wildcards.

◆ r_str_mem_dump()

rboolean r_str_mem_dump	(	rchar *	str,
		const ruint8 *	ptr,
		rsize	size,
		rsize	align
	)

Render size bytes from ptr into str as a multi-line hex+ASCII dump.

Parameters

str	Destination buffer.
ptr	Source bytes to render.
size	Number of bytes to consume from `ptr`.
align	Number of source bytes per line; see R_STR_MEM_DUMP_SIZE for the destination capacity formula.

Returns: TRUE on success.

◆ r_str_mem_dump_dup()

rchar * r_str_mem_dump_dup	(	const ruint8 *	ptr,
		rsize	size,
		rsize	align
	)

Like r_str_mem_dump but allocates the destination buffer.

Returns: Freshly allocated NUL-terminated dump; caller r_free's.

◆ r_str_mem_hex()

rchar * r_str_mem_hex	(	const ruint8 *	ptr,
		rsize	size
	)

Encode size bytes from ptr as a contiguous lowercase hex string.

Returns: Freshly allocated NUL-terminated hex string.

◆ r_strv_new()

rchar ** r_strv_new	(	const rchar *	str0,
			...
	)

Build a NULL-terminated rchar** vector from a variadic argument list of NUL-terminated strings.

Use r_strv_free on the result.

Data Structures

Macros

Enumerations

Functions

Comparison

Prefix / suffix / substring tests

printf-style formatting

String chunk (pointer-and-size view)

Key-value parsing

Memory dump and hex

Pattern matching

Detailed Description

Enumeration Type Documentation

◆ RStrMatchResultType

◆ RStrTokenType

Function Documentation

◆ r_str_chunk_cmp()

◆ r_str_chunk_has_prefix()

◆ r_str_chunk_next_line()

◆ r_str_chunk_split()

◆ r_str_dump()

◆ r_str_hex_mem()

◆ r_str_hex_to_binary()

◆ r_str_kv_parse()

◆ r_str_kv_parse_multiple()

◆ r_str_match_pattern()

◆ r_str_match_simple_pattern()

◆ r_str_mem_dump()

◆ r_str_mem_dump_dup()

◆ r_str_mem_hex()

◆ r_strv_new()