STRING(3) Library Functions Manual STRING(3)

KS_str_match_init, KS_str_match_init_once, KS_str_match, KS_str_match_spaces, KS_str_match_until, KS_str_match_until_spaces, KS_str_split, KS_str_split_spaces, KS_str_vis — string utility functions

#include <libks/string.h>

int
KS_str_match_init(const char *ranges, struct KS_str_match *match);

void
KS_str_match_init_once(const char *ranges, struct KS_str_match *match);

size_t
KS_str_match(const char *str, size_t len, const struct KS_str_match *match);

size_t
KS_str_match_spaces(const char *str, size_t len);

size_t
KS_str_match_until(const char *str, size_t len, const struct KS_str_match *match);

size_t
KS_str_match_until_spaces(const char *str, size_t len);

VECTOR(char *)
KS_str_split(const char *str, const struct KS_str_match *match, struct arena_scope *s);

VECTOR(char *)
KS_str_split_spaces(const char *str, struct arena_scope *s);

char *
KS_str_vis(const char *str, size_t len, struct arena_scope *s);

The string API provides functions for efficient string handling and manipulation.

The () function initializes match for usage with KS_str_match(), KS_str_match_until() and KS_str_split() in which ranges denotes character ranges to match against. Each range is expressed using two consecutive characters in which the first character denotes the lower bound and second the upper bound. A character is covered by a range if it inclusively resides within the lower and upper bound. A range covering a single character can be expressed using the same character as both lower and upper bound. Up to 8 ranges are supported.

The () function initializes match once through a transparently provided constructor function.

The () function matches up to len number of characters from str against the ranges given by match. Its return value reflects the number of consecutive characters covered by the ranges. If the first character is not covered by the ranges, zero is returned.

The () function is a convenience wrapper around KS_str_match() using ranges matching space (‘ ’), form feed (‘\f’), new-line (‘\n’), carriage return (‘\r’), horizontal tab (‘\t’) and vertical tab (‘\v’) characters.

The () function has the same API as KS_str_match() but skips any prefix in str not covered by the ranges and returns upon encountering a character covered by the ranges. Its return value represents the length of any prefix not covered by the ranges.

The () function is a convenience wrapper around KS_str_match_until() behaving like the inverse of KS_str_match_spaces().

The () function splits str using match to find delimiter(s). It returns a vector with each substring excluding the delimiter(s).

The () is a convenience wrapper around KS_str_split() that splits str on each occurrence of (‘ ’), form feed (‘\f’), new-line (‘\n’), carriage return (‘\r’), horizontal tab (‘\t’) and vertical tab (‘\v’) characters.

The () function converts non-printable characters in str to a visual representation. Intended to be used while displaying untrusted data.

The KS_str_match_init() returns 0 on success and -1 otherwise and errno is set accordingly.

Using KS_str_match() to match C identifiers:

struct KS_str_match match;

if (KS_str_match_init("AZaz09__", &match) == -1)
	err(1, "KS_str_match_init");

size_t len = KS_str_match(buf, buflen, &match);
if (len > 0)
	printf("%.*s\n", (int)len, buf);

Using KS_str_match_until_spaces() to find a token delimited by whitespace characters.

size_t len = KS_str_match_until_spaces(buf, buflen);
if (len > 0)
	printf("%.*s\n", (int)len, buf);

The KS_str_match_init() function will fail if:

[]
The ranges is either empty or malformed.
[]
The ranges is too long.

Anton Lindqvist <anton@basename.se>

OpenBSD 7.8 August 12, 2023 STRING(3)