NUL-terminated string utilities (immutable rchar * operations, search, comparison, parsing, formatting, ...). More...

Modules
	Mutable strings
	Heap-allocated mutable string-builder type, complement to the immutable `rchar` `*` helpers in `rlib/rstr.h`.

Files
file	rstr.h
	NUL-terminated string utilities.

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...

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`.

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`.
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`.

#define	r_str_equals(a, b) (r_strcmp (a, b) == 0)
	Convenience macro: TRUE iff `a` and `b` compare equal.

Prefix / suffix / substring tests
Boolean predicates that don't return a position.
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`.

#define	r_str_has_substring(str, sub) (r_str_idx_of_str (str, -1, sub, -1) >= 0)
	Test whether `str` contains `sub` anywhere.

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).

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`).
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.

#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.

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)

Detailed Description

NUL-terminated string utilities (immutable rchar * operations, search, comparison, parsing, formatting, ...).

Macro Definition Documentation

◆ r_str_has_substring

#define r_str_has_substring	(	str,
		sub
	)	(r_str_idx_of_str (str, -1, sub, -1) >= 0)

Test whether str contains sub anywhere.

Convenience macro equivalent to r_str_idx_of_str(str,-1,sub,-1) >= 0.

◆ R_STR_SIZEOF

#define R_STR_SIZEOF ( str ) (sizeof (str) - 1)

Compile-time string length, excluding the terminating NUL.

Only meaningful on string literals or fixed-size arrays of rchar.

Parameters

str	A string literal or character array.

Returns: Length of str in bytes.

◆ R_STR_WITH_SIZE_ARGS

#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.

Convenience helper for call sites like r_str_idx_of_str(haystack, -1, R_STR_WITH_SIZE_ARGS("needle")) that avoids spelling the literal twice.

Parameters

str	A string literal or character array.

Enumeration Type Documentation

◆ RStrParse

enum RStrParse

Status code returned by the string-parsing helpers.

Returned by the r_str_to_* numeric parsers, r_str_chunk_next_line, and the r_str_kv_parse family.

Enumerator
R_STR_PARSE_OK	Parse succeeded.
R_STR_PARSE_RANGE	Value parsed but is outside the target type's range.
R_STR_PARSE_INVAL	Input was malformed or no digits were consumed.

Function Documentation

◆ r_asprintf()

int r_asprintf	(	rchar **	str,
		const rchar *	fmt,
			...
	)

Format into a freshly r_malloc'd buffer and store its address at *str.

Returns: Number of bytes written (excluding the terminating NUL), or a negative value on failure.

◆ r_str_has_prefix()

rboolean r_str_has_prefix	(	const rchar *	str,
		const rchar *	prefix
	)

Test whether str begins with prefix.

Parameters

str	NUL-terminated input string.
prefix	NUL-terminated prefix to look for.

Returns: TRUE if str starts with prefix; FALSE otherwise.

◆ r_str_has_suffix()

rboolean r_str_has_suffix	(	const rchar *	str,
		const rchar *	suffix
	)

Test whether str ends with suffix.

Parameters

str	NUL-terminated input string.
suffix	NUL-terminated suffix to look for.

Returns: TRUE if str ends with suffix; FALSE otherwise.

◆ r_str_idx_of_c()

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.

Returns: Byte index of the match, or -1 if not found.

◆ r_str_ptr_of_c()

rchar * r_str_ptr_of_c	(	const rchar *	str,
		rssize	strsize,
		rchar	c
	)

Locate the first occurrence of byte c in str.

Parameters

str	Input buffer.
strsize	Size of `str` in bytes, or -1 to fall back to `r_strlen`.
c	Byte to find.

Returns: Pointer into str at the match, or NULL.

◆ r_str_ptr_of_c_any()

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).

Parameters

str	Input buffer.
strsize	Bytes in `str`, or -1.
c	Pointer to the lookup set.
chars	Bytes in `c`, or -1.

Returns: Pointer into str at the match, or NULL.

◆ r_str_ptr_of_str()

rchar * r_str_ptr_of_str	(	const rchar *	str,
		rssize	strsize,
		const rchar *	sub,
		rssize	subsize
	)

Locate the first occurrence of sub inside str.

Parameters

str	Input buffer.
strsize	Bytes in `str`, or -1.
sub	Substring to search for.
subsize	Bytes in `sub`, or -1.

Returns: Pointer into str at the match, or NULL.

◆ r_str_ptr_of_str_case()

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.

Comparison is case-insensitive in the ASCII range; non-ASCII bytes are compared verbatim.

◆ r_str_to_double()

rdouble r_str_to_double	(	const rchar *	str,
		const rchar **	endptr,
		RStrParse *	res
	)

Parse a double-precision float from str.

Accepts the same syntax as the C runtime's strtod. *res (when non-NULL) is set as for the integer parsers.

◆ r_strchr()

rchar * r_strchr	(	const rchar *	str,
		int	c
	)

Locate the first occurrence of c in str. Behaves like strchr.

Returns: Pointer into str at the match, or NULL if not found.

◆ r_strdup_size()

rchar * r_strdup_size	(	const rchar *	str,
		rssize	size
	)

Duplicate the first size bytes of str.

Parameters

str	Input buffer to copy from.
size	Bytes to copy, or -1 to fall back to r_strlen(str).

◆ r_strerror()

const rchar * r_strerror	(	int	errnum,
		rchar *	buf,
		rsize	size
	)

Thread-safe wrapper around the C runtime's strerror.

Writes the error description for errnum into buf (size bytes, NUL-terminated) and returns either buf or, on GNU libc, a static pointer with the same contents. Always returns a usable string even when errnum is unknown to the C runtime.

Parameters

errnum	The errno value to describe.
buf	Caller-supplied output buffer.
size	Capacity of `buf` in bytes.

Returns: A pointer to a NUL-terminated description; either buf or, on platforms whose runtime returns a static string, that static pointer.

◆ r_strjoin()

rchar * r_strjoin	(	const rchar *	delim,
			...
	)

Concatenate the variadic NUL-terminated strings, separating them with delim, into a freshly allocated buffer.

The variadic list is NULL-terminated; an empty list yields a fresh empty string.

◆ r_strlen()

rsize r_strlen ( const rchar * str )

Return the byte length of the NUL-terminated string str.

Behaves like the standard C strlen.

Parameters

str	A NUL-terminated string.

Returns: Number of bytes preceding the terminating NUL.

◆ r_strnchr()

rchar * r_strnchr	(	const rchar *	str,
		int	c,
		rsize	size
	)

Bounded variant of r_strchr; scans at most size bytes.

Returns: Pointer into str at the match, or NULL.

◆ r_strnjoin()

rchar * r_strnjoin	(	rchar *	str,
		rsize	size,
		const rchar *	delim,
			...
	)

Join into a caller-supplied buffer of size bytes.

Returns: str on success; output is always NUL-terminated. Truncates rather than failing if size is too small.

◆ r_strprintf()

rchar * r_strprintf	(	const rchar *	fmt,
			...
	)

Format into a freshly r_malloc'd buffer and return it.

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

◆ r_strsplit()

rchar ** r_strsplit	(	const rchar *	str,
		const rchar *	delim,
		rsize	max
	)

Split str on delim into a freshly allocated rchar** string vector (NULL-terminated).

Parameters

str	NUL-terminated input string.
delim	NUL-terminated separator string.
max	Upper bound on the number of pieces produced; 0 means unlimited. Use `r_strv_free` on the result.

Modules

Files

Macros

Enumerations

Length and errno descriptions

Comparison

Prefix / suffix / substring tests

Character / substring search

Copy and concatenate

Duplication

Strip

Join and split

printf-style formatting

scanf-style scanning

String-to-number parsing

Length-bounded numeric parsers

Detailed Description

Macro Definition Documentation

◆ r_str_has_substring

◆ R_STR_SIZEOF

◆ R_STR_WITH_SIZE_ARGS

Enumeration Type Documentation

◆ RStrParse

Function Documentation

◆ r_asprintf()

◆ r_str_has_prefix()

◆ r_str_has_suffix()

◆ r_str_idx_of_c()

◆ r_str_ptr_of_c()

◆ r_str_ptr_of_c_any()

◆ r_str_ptr_of_str()

◆ r_str_ptr_of_str_case()

◆ r_str_to_double()

◆ r_strchr()

◆ r_strdup_size()

◆ r_strerror()

◆ r_strjoin()

◆ r_strlen()

◆ r_strnchr()

◆ r_strnjoin()

◆ r_strprintf()

◆ r_strsplit()