str.h File Reference

Utilities for string slices. More...

#include <stddef.h>
#include <stdbool.h>

Go to the source code of this file.

Data Structures
struct	str
	A string "slice", which is a pointer & length pair. More...

Macros
#define	str_literal(SZ_LITERAL)
	Constructs a str from a C-string literal.
#define	str_strip_prefix(IT, PREFIX)
	Returns a non-owning copy of a str with a given prefix removed, if it is present.
#define	str_strip_postfix(IT, POSTFIX)
	Returns a non-owning copy of a str with a given postfix removed, if it is present.
#define	cstr_cmp_cstr   strcmp
	Compares two strings lexicographically. This is an alias to strncmp() for convenience.
#define	str_cmp(LHS, RHS)
	Compares two strings lexicographically.
#define	str_eq(LHS, RHS)
	Compares two strings to see if their contents are equal.
#define	str_eq_any(LHS, COUNT, RHS, ...)
	Compares a string to several others to see if its contents are equal to any of them.
#define	str_has_prefix(LHS, RHS)
	Checks if a string begins with another string.
#define	str_has_postfix(LHS, RHS)
	Checks if a string ends with another string.

Typedefs
typedef struct str	str
	A string "slice", which is a pointer & length pair.

Functions
str	str_from_cstr (char *sz)
	Constructs a non-owning str from a nil-terminated C-string.
str	str_slice_cstr (char *sz, size_t len)
	Constructs a non-owning str from part of a nil-terminated C-string.
str	str_strip_whitespace_pre (str it)
	Returns a non-owning copy of a str with all leading whitespace removed.
str	str_strip_whitespace_post (str it)
	Returns a non-owning copy of a str with all trailing whitespace removed.
str	str_strip_whitespace (str it)
	Returns a non-owning copy of a str with all leading and trailing whitespace removed.
str	str_strip_prefix_str (str it, str prefix)
	Returns a non-owning copy of a str with a given prefix removed, if it is present.
str	str_strip_prefix_cstr (str it, const char *prefix)
	Returns a non-owning copy of a str with a given prefix removed, if it is present.
str	str_strip_prefix_if (str it, bool(*predicate)(char))
	Returns a non-owning copy of a str with all leading characters satisfying predicate removed.
str	str_strip_postfix_str (str it, str postfix)
	Returns a non-owning copy of a str with a given postfix removed, if it is present.
str	str_strip_postfix_cstr (str it, const char *postfix)
	Returns a non-owning copy of a str with a given postfix removed, if it is present.
str	str_strip_postfix_if (str it, bool(*predicate)(char))
	Returns a non-owning copy of a str with all trailing characters satisfying predicate removed.
int	str_cmp_str (str a, str b)
	Compares two strings lexicographically.
int	str_cmp_cstr (str a, const char *b)
	Compares two strings lexicographically.
int	cstr_cmp_str (const char *a, str b)
	Compares two strings lexicographically.
bool	str_eq_str (str a, str b)
	Compares two strings to see if their contents are equal.
bool	str_eq_cstr (str a, const char *b)
	Compares two strings to see if their contents are equal.
bool	cstr_eq_str (const char *a, str b)
	Compares two strings to see if their contents are equal.
bool	cstr_eq_cstr (const char *a, const char *b)
	Compares two strings to see if their contents are equal.
size_t	str_eq_str_any (str it, size_t count,...)
	Compares a string to several others to see if its contents are equal to any of them.
size_t	str_eq_strs_any (str it, size_t count, const str others[static count])
	Compares a string to several others to see if its contents are equal to any of them.
size_t	str_eq_cstr_any (str it, size_t count,...)
	Compares a string to several others to see if its contents are equal to any of them.
size_t	str_eq_cstrs_any (str it, size_t count, const char *others[static count])
	Compares a string to several others to see if its contents are equal to any of them.
size_t	cstr_eq_str_any (const char *it, size_t count,...)
	Compares a string to several others to see if its contents are equal to any of them.
size_t	cstr_eq_strs_any (const char *it, size_t count, const str others[static count])
	Compares a string to several others to see if its contents are equal to any of them.
size_t	cstr_eq_cstr_any (const char *it, size_t count,...)
	Compares a string to several others to see if its contents are equal to any of them.
size_t	cstr_eq_cstrs_any (const char *it, size_t count, const char *others[static count])
	Compares a string to several others to see if its contents are equal to any of them.
size_t	str_satisfies_any (str it, size_t count,...)
	Checks if a string satisfies any of several predicates.
size_t	str_satisfies_anys (str it, size_t count, bool(*predicates[static count])(str))
	Checks if a string satisfies any of several predicates.
size_t	cstr_satisfies_any (const char *it, size_t count,...)
	Checks if a string satisfies any of several predicates.
size_t	cstr_satisfies_anys (const char *it, size_t count, bool(*predicates[static count])(const char *))
	Checks if a string satisfies any of several predicates.
bool	str_satisfies_all (str it, size_t count,...)
	Checks if a string satisfies all of several predicates.
bool	str_satisfies_alls (str it, size_t count, bool(*predicates[static count])(str))
	Checks if a string satisfies all of several predicates.
bool	cstr_satisfies_all (const char *it, size_t count,...)
	Checks if a string satisfies all of several predicates.
bool	cstr_satisfies_alls (const char *it, size_t count, bool(*predicates[static count])(const char *))
	Checks if a string satisfies all of several predicates.
bool	str_chars_satisfies (str it, bool(*predicate)(char))
	Checks if all characters in a string satisfies a predicate.
bool	cstr_chars_satisfies (const char *it, bool(*predicate)(char))
	Checks if all characters in a string satisfies a predicate.
size_t	str_has_prefix_str (str it, str prefix)
	Checks if a string begins with another string.
size_t	str_has_prefix_cstr (str it, const char *prefix)
	Checks if a string begins with another string.
size_t	cstr_has_prefix_str (const char *it, str prefix)
	Checks if a string begins with another string.
size_t	cstr_has_prefix_cstr (const char *it, const char *prefix)
	Checks if a string begins with another string.
size_t	str_has_postfix_str (str it, str postfix)
	Checks if a string ends with another string.
size_t	str_has_postfix_cstr (str it, const char *postfix)
	Checks if a string ends with another string.
size_t	cstr_has_postfix_str (const char *it, str postfix)
	Checks if a string ends with another string.
size_t	cstr_has_postfix_cstr (const char *it, const char *postfix)
	Checks if a string ends with another string.

Detailed Description

Utilities for string slices.

Macro Definition Documentation

str_cmp

#define str_cmp	(		LHS,
			RHS )

Value:

    _Generic((LHS),\
    const str: _Generic((RHS),\
        const str  : str_cmp_str,\
              str  : str_cmp_str,\
        const char*: str_cmp_cstr,\
              char*: str_cmp_cstr\
    ),\
    str: _Generic((RHS),\
        const str  : str_cmp_str,\
              str  : str_cmp_str,\
        const char*: str_cmp_cstr,\
              char*: str_cmp_cstr\
    ),\
    const char*: _Generic((RHS),\
        const str  : cstr_cmp_str,\
              str  : cstr_cmp_str,\
        const char*: strcmp,\
              char*: strcmp\
    ),\
    char*: _Generic((RHS),\
        const str  : cstr_cmp_str,\
              str  : cstr_cmp_str,\
        const char*: strcmp,\
              char*: strcmp\
    )\
)((LHS), (RHS))

Compares two strings lexicographically.

See also

C89 strncmp()

str_eq

#define str_eq	(		LHS,
			RHS )

Value:

    _Generic((LHS),\
    const str: _Generic((RHS),\
        const str  : str_eq_str,\
              str  : str_eq_str,\
        const char*: str_eq_cstr,\
              char*: str_eq_cstr\
    ),\
    str: _Generic((RHS),\
        const str  : str_eq_str,\
              str  : str_eq_str,\
        const char*: str_eq_cstr,\
              char*: str_eq_cstr\
    ),\
    const char*: _Generic((RHS),\
        const str  : cstr_eq_str,\
              str  : cstr_eq_str,\
        const char*: cstr_eq_cstr,\
              char*: cstr_eq_cstr\
    ),\
    char*: _Generic((RHS),\
        const str  : cstr_eq_str,\
              str  : cstr_eq_str,\
        const char*: cstr_eq_cstr,\
              char*: cstr_eq_cstr\
    )\
)((LHS), (RHS))

Compares two strings to see if their contents are equal.

str_eq_any

#define str_eq_any	(		LHS,
			COUNT,
			RHS,
			... )

Compares a string to several others to see if its contents are equal to any of them.

Parameters

LHS	The string to compare against many others.
COUNT	The number of other strings to compare against. This must be no greater than SIZE_MAX - 1.
RHS	The first other string to test LHS against. The type of ... is inferred to be the type of this parameter.
...	The remaining strings to test LHS against.

Returns

1 if LHS was equal to RHS, or the number of the string in ... that LHS was equal to, counting from 2, or 0 if LHS was equal to none of them.

str_has_postfix

#define str_has_postfix	(		LHS,
			RHS )

Value:

    _Generic((LHS),\
    const str: _Generic((RHS),\
        const str  : str_has_postfix_str,\
              str  : str_has_postfix_str,\
        const char*: str_has_postfix_cstr,\
              char*: str_has_postfix_cstr\
    ),\
    str: _Generic((RHS),\
        const str  : str_has_postfix_str,\
              str  : str_has_postfix_str,\
        const char*: str_has_postfix_cstr,\
              char*: str_has_postfix_cstr\
    ),\
    const char*: _Generic((RHS),\
        const str  : cstr_has_postfix_str,\
              str  : cstr_has_postfix_str,\
        const char*: cstr_has_postfix_cstr,\
              char*: cstr_has_postfix_cstr\
    ),\
    char*: _Generic((RHS),\
        const str  : cstr_has_postfix_str,\
              str  : cstr_has_postfix_str,\
        const char*: cstr_has_postfix_cstr,\
              char*: cstr_has_postfix_cstr\
    )\
)((LHS), (RHS))

Checks if a string ends with another string.

Returns

The length of postfix if it is found; otherwise, 0

str_has_prefix

#define str_has_prefix	(		LHS,
			RHS )

Value:

    _Generic((LHS),\
    const str: _Generic((RHS),\
        const str  : str_has_prefix_str,\
              str  : str_has_prefix_str,\
        const char*: str_has_prefix_cstr,\
              char*: str_has_prefix_cstr\
    ),\
    str: _Generic((RHS),\
        const str  : str_has_prefix_str,\
              str  : str_has_prefix_str,\
        const char*: str_has_prefix_cstr,\
              char*: str_has_prefix_cstr\
    ),\
    const char*: _Generic((RHS),\
        const str  : cstr_has_prefix_str,\
              str  : cstr_has_prefix_str,\
        const char*: cstr_has_prefix_cstr,\
              char*: cstr_has_prefix_cstr\
    ),\
    char*: _Generic((RHS),\
        const str  : cstr_has_prefix_str,\
              str  : cstr_has_prefix_str,\
        const char*: cstr_has_prefix_cstr,\
              char*: cstr_has_prefix_cstr\
    )\
)((LHS), (RHS))

Checks if a string begins with another string.

Returns

The length of prefix if it is found; otherwise, 0

str_literal

#define str_literal

(

SZ_LITERAL

)

Value:

(str){ (SZ_LITERAL), sizeof(SZ_LITERAL) - 1 }

Constructs a str from a C-string literal.

str_strip_postfix

#define str_strip_postfix	(		IT,
			POSTFIX )

Value:

    _Generic((POSTFIX),\
    const str            : str_strip_postfix_str,\
          str            : str_strip_postfix_str,\
    const char*          : str_strip_postfix_cstr,\
          char*          : str_strip_postfix_cstr,\
    bool (*)(char c)     : str_strip_postfix_if\
)((IT), (POSTFIX))

Returns a non-owning copy of a str with a given postfix removed, if it is present.

str_strip_prefix

#define str_strip_prefix	(		IT,
			PREFIX )

Value:

    _Generic((PREFIX),\
    const str            : str_strip_prefix_str,\
          str            : str_strip_prefix_str,\
    const char*          : str_strip_prefix_cstr,\
          char*          : str_strip_prefix_cstr,\
    bool (*)(char c)     : str_strip_prefix_if\
)((IT), (PREFIX))

Returns a non-owning copy of a str with a given prefix removed, if it is present.

Typedef Documentation

str

typedef struct str str

A string "slice", which is a pointer & length pair.

A str can be printed using the "%.*s" format specifier:

str s = str_from_cstr("World!");
printf("Hello %.*s", (int)(s.len), s.data);

Function Documentation

cstr_chars_satisfies()

bool cstr_chars_satisfies	(	const char *	it,
		bool(*	predicate )(char) )

Checks if all characters in a string satisfies a predicate.

Parameters

it	The string whose characters to test
predicate	The predicate to test each character in it against

Returns

Whether or not every character in it satisfied predicate

cstr_cmp_str()

int cstr_cmp_str	(	const char *	a,
		str	b )

Compares two strings lexicographically.

See also

C89 strncmp()

cstr_eq_cstr_any()

size_t cstr_eq_cstr_any	(	const char *	it,
		size_t	count,
			... )

Compares a string to several others to see if its contents are equal to any of them.

Parameters

it	The string to compare against many others.
count	The number of other strings to compare against. This must be no greater than SIZE_MAX - 1.
...	The other strings to test it against.

Returns

The number of the string in ... that it was equal to, counting from 1, or 0 if it was equal to none of them.

cstr_eq_cstrs_any()

size_t cstr_eq_cstrs_any	(	const char *	it,
		size_t	count,
		const char *	others[static count] )

Compares a string to several others to see if its contents are equal to any of them.

Parameters

it	The string to compare against many others.
count	The number of other strings to compare against. This must be no greater than SIZE_MAX - 1.
others	The other strings to test it against.

Returns

The number of the string in others that it was equal to, counting from 1 (or rather, 1 greater than the index), or 0 if it was equal to none of them.

cstr_eq_str_any()

size_t cstr_eq_str_any	(	const char *	it,
		size_t	count,
			... )

Compares a string to several others to see if its contents are equal to any of them.

Parameters

it	The string to compare against many others.
count	The number of other strings to compare against. This must be no greater than SIZE_MAX - 1.
...	The other strings to test it against.

Returns

The number of the string in ... that it was equal to, counting from 1, or 0 if it was equal to none of them.

cstr_eq_strs_any()

size_t cstr_eq_strs_any	(	const char *	it,
		size_t	count,
		const str	others[static count] )

Compares a string to several others to see if its contents are equal to any of them.

Parameters

it	The string to compare against many others.
count	The number of other strings to compare against. This must be no greater than SIZE_MAX - 1.
others	The other strings to test it against.

Returns

The number of the string in others that it was equal to, counting from 1 (or rather, 1 greater than the index), or 0 if it was equal to none of them.

cstr_has_postfix_cstr()

size_t cstr_has_postfix_cstr	(	const char *	it,
		const char *	postfix )

Checks if a string ends with another string.

Returns

The length of postfix if it is found; otherwise, 0

cstr_has_postfix_str()

size_t cstr_has_postfix_str	(	const char *	it,
		str	postfix )

Checks if a string ends with another string.

Returns

The length of postfix if it is found; otherwise, 0

cstr_has_prefix_cstr()

size_t cstr_has_prefix_cstr	(	const char *	it,
		const char *	prefix )

Checks if a string begins with another string.

Returns

The length of prefix if it is found; otherwise, 0

cstr_has_prefix_str()

size_t cstr_has_prefix_str	(	const char *	it,
		str	prefix )

Checks if a string begins with another string.

Returns

The length of prefix if it is found; otherwise, 0

cstr_satisfies_all()

bool cstr_satisfies_all	(	const char *	it,
		size_t	count,
			... )

Checks if a string satisfies all of several predicates.

Parameters

it	The string to test
count	The number of predicates to test against. This must be no greater than SIZE_MAX - 1.
...	The predicates to test it against; must be of type bool (*)(const char*)

Returns

Whether or not it satisfied all predicates in ...

cstr_satisfies_alls()

bool cstr_satisfies_alls	(	const char *	it,
		size_t	count,
		bool(*[])(const char *)	count )

Checks if a string satisfies all of several predicates.

Parameters

it	The string to test
count	The number of predicates to test against. This must be no greater than SIZE_MAX - 1.
predicates	The predicates to test it against

Returns

Whether or not it satisfied all predicates in predicates

cstr_satisfies_any()

size_t cstr_satisfies_any	(	const char *	it,
		size_t	count,
			... )

Checks if a string satisfies any of several predicates.

Parameters

it	The string to test
count	The number of predicates to test against. This must be no greater than SIZE_MAX - 1.
...	The predicates to test it against; must be of type bool (*)(const char*)

Returns

The number of the predicate in ... that was satisfied by it, counting from 1, or 0 if satisfied none of them.

cstr_satisfies_anys()

size_t cstr_satisfies_anys	(	const char *	it,
		size_t	count,
		bool(*[])(const char *)	count )

Checks if a string satisfies any of several predicates.

Parameters

it	The string to test
count	The number of predicates to test against. This must be no greater than SIZE_MAX - 1.
predicates	The predicates to test it against

Returns

The number of the predicate in predicates that was satisfied by it, counting from 1 (or rather, 1 greater than the index), or 0 if satisfied none of them.

str_chars_satisfies()

bool str_chars_satisfies	(	str	it,
		bool(*	predicate )(char) )

Checks if all characters in a string satisfies a predicate.

Parameters

it	The string whose characters to test
predicate	The predicate to test each character in it against

Returns

Whether or not every character in it satisfied predicate

str_cmp_cstr()

int str_cmp_cstr	(	str	a,
		const char *	b )

Compares two strings lexicographically.

See also

C89 strncmp()

str_cmp_str()

int str_cmp_str	(	str	a,
		str	b )

Compares two strings lexicographically.

See also

C89 strncmp()

str_eq_cstr_any()

size_t str_eq_cstr_any	(	str	it,
		size_t	count,
			... )

Compares a string to several others to see if its contents are equal to any of them.

Parameters

it	The string to compare against many others.
count	The number of other strings to compare against. This must be no greater than SIZE_MAX - 1.
...	The other strings to test it against.

Returns

The number of the string in ... that it was equal to, counting from 1, or 0 if it was equal to none of them.

str_eq_cstrs_any()

size_t str_eq_cstrs_any	(	str	it,
		size_t	count,
		const char *	others[static count] )

Compares a string to several others to see if its contents are equal to any of them.

Parameters

it	The string to compare against many others.
count	The number of other strings to compare against. This must be no greater than SIZE_MAX - 1.
others	The other strings to test it against.

Returns

The number of the string in others that it was equal to, counting from 1 (or rather, 1 greater than the index), or 0 if it was equal to none of them.

str_eq_str_any()

size_t str_eq_str_any	(	str	it,
		size_t	count,
			... )

Compares a string to several others to see if its contents are equal to any of them.

Parameters

it	The string to compare against many others.
count	The number of other strings to compare against. This must be no greater than SIZE_MAX - 1.
...	The other strings to test it against.

Returns

The number of the string in ... that it was equal to, counting from 1, or 0 if it was equal to none of them.

str_eq_strs_any()

size_t str_eq_strs_any	(	str	it,
		size_t	count,
		const str	others[static count] )

Compares a string to several others to see if its contents are equal to any of them.

Parameters

it	The string to compare against many others.
count	The number of other strings to compare against. This must be no greater than SIZE_MAX - 1.
others	The other strings to test it against.

Returns

The number of the string in others that it was equal to, counting from 1 (or rather, 1 greater than the index), or 0 if it was equal to none of them.

str_has_postfix_cstr()

size_t str_has_postfix_cstr	(	str	it,
		const char *	postfix )

Checks if a string ends with another string.

Returns

The length of postfix if it is found; otherwise, 0

str_has_postfix_str()

size_t str_has_postfix_str	(	str	it,
		str	postfix )

Checks if a string ends with another string.

Returns

The length of postfix if it is found; otherwise, 0

str_has_prefix_cstr()

size_t str_has_prefix_cstr	(	str	it,
		const char *	prefix )

Checks if a string begins with another string.

Returns

The length of prefix if it is found; otherwise, 0

str_has_prefix_str()

size_t str_has_prefix_str	(	str	it,
		str	prefix )

Checks if a string begins with another string.

Returns

The length of prefix if it is found; otherwise, 0

str_satisfies_all()

bool str_satisfies_all	(	str	it,
		size_t	count,
			... )

Checks if a string satisfies all of several predicates.

Parameters

it	The string to test
count	The number of predicates to test against. This must be no greater than SIZE_MAX - 1.
...	The predicates to test it against; must be of type bool (*)(str)

Returns

Whether or not it satisfied all predicates in ...

str_satisfies_alls()

bool str_satisfies_alls	(	str	it,
		size_t	count,
		bool(*[])(str)	count )

Checks if a string satisfies all of several predicates.

Parameters

it	The string to test
count	The number of predicates to test against. This must be no greater than SIZE_MAX - 1.
predicates	The predicates to test it against

Returns

Whether or not it satisfied all predicates in predicates

str_satisfies_any()

size_t str_satisfies_any	(	str	it,
		size_t	count,
			... )

Checks if a string satisfies any of several predicates.

Parameters

it	The string to test
count	The number of predicates to test against. This must be no greater than SIZE_MAX - 1.
...	The predicates to test it against; must be of type bool (*)(str)

Returns

The number of the predicate in ... that was satisfied by it, counting from 1, or 0 if satisfied none of them.

str_satisfies_anys()

size_t str_satisfies_anys	(	str	it,
		size_t	count,
		bool(*[])(str)	count )

Checks if a string satisfies any of several predicates.

Parameters

it	The string to test
count	The number of predicates to test against. This must be no greater than SIZE_MAX - 1.
predicates	The predicates to test it against

Returns

The number of the predicate in predicates that was satisfied by it, counting from 1 (or rather, 1 greater than the index), or 0 if satisfied none of them.