strutils#

Cross-platform string utility functions.

Typedefs and structs

enum _StrquoteFlags#

Flags for strquote()

Values:

enumerator strquoteInitialBlanks#: Do not skip initial blanks

enumerator strquoteNoQuote#: Input is not expected to start and end with double quote

enumerator strquoteNoEscape#: Do not escape embedded double quotes

enumerator strquoteRaw#: Copy the input without conversions

enum StrCategory#

Character categories, from, RFC 3986

Values:

enumerator strcatUpper#: A-Z.

enumerator strcatLower#: a-z

enumerator strcatDigit#: 0-9

enumerator strcatUnreserved#: “-._~” (in addition to upper + lower + digit)

enumerator strcatSubDelims#: “!$&’()*+,;=”

enumerator strcatGenDelims#: “:/?#[]@”

enumerator strcatReserved#: strcatSubDelims | strcatGenDelims

enumerator strcatPercent#: “%”

enumerator strcatCExtra#: “"\<>^{}|” (extra characters in the C standard)

enumerator strcatSpace#: ” \f\n\r\t\v”

enumerator strcatOther#: anything else, except NUL

enumerator strcatNul#: NUL.

typedef enum _StrquoteFlags StrquoteFlags#: Flags for strquote()

Print allocated string

char *aprintf(const char *fmt, ...)#: A convinient variant of asprintf() that returns the allocated string, or NULL on error.

Functions for writing characters to a buffer

int strsetc(char *dest, long size, int c)#

Writes character c to buffer dest of size size. If there is space, the buffer will always be NUL-terminated.

Returns always 1 (number of characters written to dest, or would have been written to dest if it had been large enough).

int strsets(char *dest, long size, const char *src)#

Copies src to dest.

At most size bytes will be written to dest. If size is larger than zero, dest will always be NUL-terminated. No, partly UTF-8 code point will be written to dest.

Returns number of bytes written to dest or the number of bytes that would have been written to dest if it had been large enough.

int strsetn(char *dest, long size, const char *src, int len)#: Like strset(), but copies at most len bytes from src.

int strput(char **destp, size_t *sizep, size_t pos, const char *src)#

Copies src string to malloc’ed memory pointed to by *destp.

The string pointed to by *destp may be reallocated. It will always be NUL-terminated.

If sizep is not NULL, the value it points to should be the allocated size of *destp. It will be updated on return.

pos is the position of *destp that src will be copied to.

Returns number of characters written (excluding terminating NUL). On allocation error, a negative number is returned and destp and sizep will not be touched.

int strnput(char **destp, size_t *sizep, size_t pos, const char *src, int n)#: Like strput(), but at most n bytes from src will be copied. If n is negative, all of src will be copited.

int strnput_escape(char **destp, size_t *sizep, size_t pos, const char *src, int len, StrCategory unescaped, const char *escape)#

Like strnput(), but escapes all characters in categories larger than unescaped, which should be less than strcatOther.

Escaped characters are written as escape followed by 2-character hex representation of the character (byte) value.

Returns -1 on error.

Quoting/unquoting strings

int strquote(char *dest, size_t size, const char *s)#

Double-quote input string s and write it to dest.

Embedded double-quotes are escaped with backslash. At most size characters are written to dest (including terminating NUL).

Returns number of characters written to dest (excluding terminating NUL). If the output is truncated, the number of characters which should have been written is returned.

int strnquote(char *dest, size_t size, const char *s, int n, StrquoteFlags flags)#: Like strquote(), but reads at most n bytes from s.

int strunquote(char *dest, size_t size, const char *s, int *consumed, StrquoteFlags flags)#

Strip double-quotes from s and write the result to dest.

At most size characters are written to dest (including terminating NUL). The input s may optionally starts with a sequence of blanks. It should then be followed by a double quote. The scanning stops at the next unescaped double quote.

Returns number of characters written to dest (excluding terminating NUL). If the output is truncated, the number of characters which should have been written is returned.

Returns a negative value on error (-1 if the first non-blank character in s is not a double quote and -2 if no terminating double quote is found).

int strnunquote(char *dest, size_t size, const char *s, int n, int *consumed, StrquoteFlags flags)#

Like strunquote, but if n is non-negative, at most n bytes are read from s.

This mostly make sense in combination when flags & strquoteNoEscape is true.

int strnput_unquote(char **destp, size_t *sizep, size_t pos, const char *s, int n, int *consumed, StrquoteFlags flags)#

Like strnunquote(), but reallocates the destination and writes to position pos.

On allocation error, -3 is returned.

Hexadecimal encoding/decoding

int strhex_encode(char *hex, size_t hexsize, const unsigned char *data, size_t size)#

Writes binary data to hex-encoded string.

hex destination string. Will be NUL-terminated. hexsize size of memory poined to by hex (incl. NUL terminator). data points to the first byte of binary data of size size. size number of bytes to read from data.

Returns number of bytes one wants to write to hex (not incl. NUL terminator), or -1 on error.

int strhex_decode(unsigned char *data, size_t size, const char *hex, int hexsize)#

Read binary data from hex-encoded string.

data pointer to buffer to write to. No more than size bytes are written. size size of data in bytes. hex hex-encoded string to read from. hexsize number of bytes to read from hex. If negative, hex is assumed to be NUL-terminated and the whole string is read.

Returns number of bytes written to data, assuming size is sufficiently large, or -1 on error.

Character categorisation

StrCategory strcategory(int c)#: Returns the category of character c.

int strcatspn(const char *s, StrCategory cat)#: Returns the length of initial segment of s which concists entirely of bytes in category cat.

int strcatcspn(const char *s, StrCategory cat)#: Returns the length of initial segment of s which concists entirely of bytes NOT in category cat.

int strcatjspn(const char *s, StrCategory cat)#: Returns the length of initial segment of s which concists entirely of bytes in all categories less or equal to cat.

int strcatcjspn(const char *s, StrCategory cat)#: Returns the length of initial segment of s which concists entirely of bytes NOT in all categories less or equal to cat.

Allocated string list

A string list is an allocated NULL-terminated array of pointers to allocated strings.

char **strlst_insert(char **strlst, size_t *n, const char *s, int i)#

Insert string s before position i in NULL-terminated array of string pointers strlst.

If i is negative count from the end of the string, like Python. Any i out of range correspond to appending.

n is the allocated length of strlst. If needed strlst will be reallocated and n updated.

Returns a pointer to the new string list or NULL on allocation error.

char **strlst_append(char **strlst, size_t *n, const char *s)#

Appends string s to NULL-terminated array of string pointers strlst. n is the allocated length of strlst. If needed strlst will be reallocated and n updated.

Returns a pointer to the new string list or NULL on allocation error.

size_t strlst_count(char **strlst)#: Return number of elements in string list.

void strlst_free(char **strlst)#: Free all memory in string list.

const char *strlst_get(char **strlst, int i)#

Returns a pointer to element i the string list. Like in Python, negative i counts from the back.

The caller gets a borrowed reference to the string. Do not free it.

Returns NULL if i is out of range.

int strlst_remove(char **strlst, int i)#

Remove element i from the string list. Like in Python, negative i counts from the back.

Returns non-zero if i is out of range.

char *strlst_pop(char **strlst, int i)#

Remove and return element i from the string list. Like in Python, negative i counts from the back.

The caller becomes the owner of the returned string and is responsible to free it.

Returns NULL if i is out of range.

Defines

__attribute__(x)