String Functions

UTF-8 aware string utilities and functions.

Summary

s_strsize	Return the size of the given UTF-8 string in bytes, excluding the trailing zero.
s_strnsize	Return the size of n characters of the given UTF-8 string in bytes.
s_strzsize	Return the size of the given UTF-8 string in bytes, including the trailing zero.
s_strlen	Return the length (number of characters) of the given UTF-8 string.
s_strdup	Return a newly allocated copy of the given UTF-8 string.
s_strzcpy	Copy the given UTF-8 string src to dest, size specified.
s_strcpy	Copy the given UTF-8 string src to dest.
s_strncpy	Copy n characters of the given UTF-8 string src to dest.
s_strzncpy	Copy n characters of the given UTF-8 string src to dest, size specified.
s_strzcat	Concatenate two UTF-8 strings, size specified.
s_strcat	Concatenate two UTF-8 strings.
s_strncat	Concatenate n characters of the given UTF-8 string src to dest.
s_strzncat	Concatenate n characters of the given UTF-8 string src to dest, size specified.
s_strcmp	Compare two UTF-8 strings.
s_strncmp	Compare n characters of two UTF-8 strings.
s_stricmp	Compare two UTF-8 strings (case insensitive).
s_strnicmp	Compare n characters of two UTF-8 strings (case insensitive).
s_strlwr	Replace all upper case characters in the given UTF-8 string with lower case characters.
s_strupr	Replace all lower case characters in the given UTF-8 string with upper case characters.
s_strchr	Locate a character in the given UTF-8 string.
s_strrchr	Reverse locate a character in the given UTF-8 string.
s_strstr	Locate a sub-string in the given UTF-8 string.
s_strpbrk	Search the given UTF-8 string for any of a set of characters.
s_strtok	Extract tokens from the given UTF-8 string.
s_strtok_r	Re-entrant version s_strtok.
s_atof	Convert the given UTF-8 string to a double.
s_strtol	Return long int value of the given UTF-8 string.
s_strtod	Convert the given UTF-8 string to a double, first valid character address.
s_strerror	Convert the given error number to a UTF-8 string.
s_isvalid	Validate the given UTF-8 string.
s_smatches	Test to see if the given UTF-8 string matches the given regular expression.
s_safter	Return the UTF-8 string that is after the first occurrence of the given character in the given UTF-8 string.
s_sbefore	Return the UTF-8 string that is before the first occurrence of the given character in the given UTF-8 string.
s_sappend	Append two UTF-8 strings.

Size/Length

size_t s_strsize(const char *s, s_erc *error)

Return the size of the given UTF-8 string in bytes, excluding the trailing zero.

Parameters:

• s –

  The string of which the size is to be determined.

• error –

  Error code.

Return:

Size in bytes, excluding the trailing zero.

size_t s_strnsize(const char *s, size_t n, s_erc *error)

Return the size of n characters of the given UTF-8 string in bytes.

Parameters:

• s –

  The string of which the size is to be determined.

• n –

  The number of characters.

• error –

  Error code.

Return:

Size of n characters of s in bytes.

size_t s_strzsize(const char *s, s_erc *error)

Return the size of the given UTF-8 string in bytes, including the trailing zero.

Parameters:

• s –

  The string of which the size is to be determined.

• error –

  Error code.

Return:

Size in bytes, including the trailing zero.

size_t s_strlen(const char *s, s_erc *error)

Return the length (number of characters) of the given UTF-8 string.

Parameters:

• s –

  The string.

• error –

  Error code.

Return:

The character length of the string.

Duplicate

char *s_strdup(const char *src, s_erc *error)

Return a newly allocated copy of the given UTF-8 string.

Parameters:

• src –

  The source string.

• error –

  Error code.

Return:

A copy of src.

Note:

Caller is responsible for the memory of the returned string.

Copy

char *s_strzcpy(char *dest, const char *src, size_t size, s_erc *error)

Copy the given UTF-8 string src to dest, size specified.

The size of dest is specified by size.

Parameters:

• dest –

  The destination string.

• src –

  The source string.

• size –

  The size of the destination string (bytes).

• error –

  Error code.

Return:

The destination string dest.

Note:

The trailing zero is copied.

macro s_strcpy(dest, src, error)

Copy the given UTF-8 string src to dest.

The size of dest is ignored (should be set correctly by caller).

Parameters:

• dest –

  Pointer to the destination string.

• src –

  Pointer to the source string.

• error –

  Error code.

Return:

Pointer to the destination string dest.

Note:

The trailing zero is copied.

See also:

s_strzcpy.

macro s_strncpy(dest, src, n, error)

Copy n characters of the given UTF-8 string src to dest.

The size of dest is ignored (should be set correctly by caller).

Parameters:

• dest –

  Pointer to the destination string.

• src –

  Pointer to the source string.

• n –

  Number of characters to copy.

• error –

  Error code.

Return:

The destination string dest.

See also:

s_strzncpy

char *s_strzncpy(char *dest, const char *src, size_t n, size_t size, s_erc *error)

Copy n characters of the given UTF-8 string src to dest, size specified.

The size of dest is specified by size.

Parameters:

• dest –

  The destination string.

• src –

  The source string.

• n –

  Number of characters to copy.

• size –

  The size of the destination string (bytes).

• error –

  Error code.

Return:

The destination string dest.

Concatenate

char *s_strzcat(char *dest, const char *src, size_t size, s_erc *error)

Concatenate two UTF-8 strings, size specified.

The size of dest is specified by size.

Parameters:

• dest –

  The destination string.

• src –

  The source string.

• size –

  The size of the destination string (bytes).

• error –

  Error code.

Return:

The concatenation of dest and src or NULL if size <= 0 or src or dest is NULL.

Note:

The dest string will be zero terminated.

macro s_strcat(dest, src, error)

Concatenate two UTF-8 strings.

The size of dest is ignored (should be set correctly by caller).

Parameters:

• dest –

  Pointer to the destination string.

• src –

  Pointer to the source string.

• error –

  Error code.

Return:

The concatenation of dest and src.

See also:

s_strzcat.

Note:

The dest string will be zero terminated.

macro s_strncat(dest, src, n, error)

Concatenate n characters of the given UTF-8 string src to dest.

The size of dest is ignored (should be set correctly by caller).

Parameters:

• dest –

  Pointer to the destination string.

• src –

  Pointer to the source string.

• n –

  Number of characters to concatenate.

• error –

  Error code.

Return:

The concatenation of dest and n characters of src.

See also:

s_strzncat

Note:

The dest string will be zero terminated.

char *s_strzncat(char *dest, const char *src, size_t n, size_t size, s_erc *error)

Concatenate n characters of the given UTF-8 string src to dest, size specified.

The size of dest is specified by size.

Parameters:

• dest –

  The destination string.

• src –

  The source string.

• n –

  Number of characters to concatenate.

• size –

  The size of the destination string (bytes).

• error –

  Error code.

Return:

The concatenation of dest and n characters of src or NULL if src or dest is NULL or n or size is 0.

Note:

The dest string will be zero terminated.

Compare

int s_strcmp(const char *s1, const char *s2, s_erc *error)

Compare two UTF-8 strings.

Parameters:

• s1 –

  String to compare.

• s2 –

  String to compare.

• error –

  Error code.

Return:

Integer less than, equal to, or greater than zero if s1 is found, respectively, to be less than, to match, or be greater than s2.

int s_strncmp(const char *s1, const char *s2, size_t n, s_erc *error)

Compare n characters of two UTF-8 strings.

Parameters:

• s1 –

  String to compare.

• s2 –

  String to compare.

• n –

  Number of characters to compare.

• error –

  Error code.

Return:

Integer less than, equal to, or greater than zero if s1 is found, respectively, to be less than, to match, or be greater than s2.

int s_stricmp(const char *s1, const char *s2, s_erc *error)

Compare two UTF-8 strings (case insensitive).

Parameters:

• s1 –

  String to compare.

• s2 –

  String to compare.

• error –

  Error code.

Return:

Integer less than, equal to, or greater than zero if s1 is found, respectively, to be less than, to match, or be greater than s2.

See also:

s_strcmp.

int s_strnicmp(const char *s1, const char *s2, size_t n, s_erc *error)

Compare n characters of two UTF-8 strings (case insensitive).

Parameters:

• s1 –

  String to compare.

• s2 –

  String to compare.

• n –

  Number of characters to compare.

• error –

  Error code.

Return:

Integer less than, equal to, or greater than zero if s1 is found, respectively, to be less than, to match, or be greater than s2.

See also:

s_strncmp.

Case conversion

char *s_strlwr(char *s, s_erc *error)

Replace all upper case characters in the given UTF-8 string with lower case characters.

Parameters:

• s –

  The string.

• error –

  Error code.

Return:

Modified string.

Note:

The string s is modified in place.

char *s_strupr(char *s, s_erc *error)

Replace all lower case characters in the given UTF-8 string with upper case characters.

Parameters:

• s –

  The string.

• error –

  Error code.

Return:

Modified string.

Note:

The string s is modified in place.

Character search

const char *s_strchr(const char *s, uint32 c, s_erc *error)

Locate a character in the given UTF-8 string.

Parameters:

• s –

  The string.

• c –

  The character to locate.

• error –

  Error code.

Return:

Pointer to first occurance of c in s.

const char *s_strrchr(const char *s, uint32 c, s_erc *error)

Reverse locate a character in the given UTF-8 string.

Parameters:

• s –

  The string.

• c –

  The character to locate.

• error –

  Error code.

Return:

Pointer to last occurance of c in s.

String search

char *s_strstr(const char *haystack, const char *needle, s_erc *error)

Locate a sub-string in the given UTF-8 string.

Parameters:

• haystack –

  String to search in.

• needle –

  String to search for.

• error –

  Error code.

Return:

Pointer to first occurance of needle in haystack.

char *s_strpbrk(const char *s, const char *set, s_erc *error)

Search the given UTF-8 string for any of a set of characters.

Parameters:

• s –

  The string.

• set –

  The set of characters.

• error –

  Error code.

Return:

Pointer to first occurance of any characters in set in string s.

Token search

char *s_strtok(char *s, const char *set, s_erc *error)

Extract tokens from the given UTF-8 string.

UTF-8 aware replacement for standard c library function strtok().

Parameters:

• s –

  The string.

• set –

  The set of tokens.

• error –

  Error code.

Return:

Pointer to next token in s.

Note:

Not thread-safe.

char *s_strtok_r(char *s, const char *set, char **last, s_erc *error)

Re-entrant version s_strtok.

The last argument is a pointer to a char* variable that is used internally in order to maintain context between successive calls that parse the same string.

Parameters:

• s –

  The string to parse.

• set –

  The set of tokens.

• last –

  Pointer to maintain context.

• error –

  Error code.

Return:

Pointer to next token in s.

Note:

Thread-safe.

Number conversions

double s_atof(const char *s, s_erc *error)

Convert the given UTF-8 string to a double.

Parameters:

• s –

  The string.

• error –

  Error code.

Return:

Double point value of s.

Note:

This is merely a wrapper to the standard ISO C atof() function.

long s_strtol(const char *s, char **endp, uint base, s_erc *error)

Return long int value of the given UTF-8 string.

Converts the initial part of the string in s to a long integer value according to the given base, which must be between 2 and 36 inclusive, or be the special value 0. Also see the standard ISO C strtol() function.

Parameters:

• s –

  The string.

• endp –

  If not NULL, address of first valid character is stored here.

• base –

  Between 2 and 36 inclusive, or be the special value 0.

• error –

  Error code.

Return:

Long value of string s.

double s_strtod(const char *s, char **endp, s_erc *error)

Convert the given UTF-8 string to a double, first valid character address.

UTF-8 ware version of the standard ISO C strtod() function.

Parameters:

• s –

  The string.

• endp –

  If not NULL, address of first valid character is stored here.

• error –

  Error code.

Return:

Double value of string s.

Error to string conversion

const char *s_strerror(int err)

Convert the given error number to a UTF-8 string.

Parameters:

• err –

  Error value.

Return:

UTF-8 string of error value.

Note:

Not thread safe.

Auxiliary functions

s_bool s_isvalid(const char *s, s_erc *error)

Validate the given UTF-8 string.

Parameters:

• s –

  The string to validate.

• error –

  Error code.

Return:

TRUE or FALSE.

s_bool s_smatches(const char *string, const char *regex, s_erc *error)

Test to see if the given UTF-8 string matches the given regular expression.

Parameters:

• string –

  The string to test.

• regex –

  The regular expression string.

• error –

  Error code.

Return:

TRUE or FALSE.

char *s_safter(const char *haystack, const char *needle, s_erc *error)

Return the UTF-8 string that is after the first occurrence of the given character in the given UTF-8 string.

Parameters:

• haystack –

  The given string.

• needle –

  The given character.

• error –

  Error code.

Return:

A new reference to the string after the character.

Note:

Caller is responsible for memory of returned string.

char *s_sbefore(const char *haystack, const char *needle, s_erc *error)

Return the UTF-8 string that is before the first occurrence of the given character in the given UTF-8 string.

Parameters:

• haystack –

  The given string.

• needle –

  The given character.

• error –

  Error code.

Return:

A new reference to the string before the character.

Note:

Caller is responsible for memory of returned string.

void s_sappend(char **str1, const char *str2, s_erc *error)

Append two UTF-8 strings.

If the string str1 is NULL, then this function performs the same task as s_strdup.

Parameters:

• str1 –

  First string.

• str2 –

  Second string, to append onto first string.

• error –

  Error code.