C Standard Library Extensions  1.2.2
Functions
String Utility Functions

Functions

cxint cx_strcasecmp (const cxchar *s1, const cxchar *s2)
 Compare two strings ignoring the case of ASCII characters. More...
 
cxint cx_strncasecmp (const cxchar *s1, const cxchar *s2, cxsize n)
 Compare the first n characters of two strings ignoring the case of ASCII characters. More...
 
cxint cx_strempty (const cxchar *string, const cxchar *pattern)
 Test if a string represents an empty string. More...
 
cxchar * cx_strlower (cxchar *s)
 Convert all uppercase characters in a string into lowercase characters. More...
 
cxchar * cx_strupper (cxchar *s)
 Convert all lowercase characters in a string into uppercase characters. More...
 
cxchar * cx_strtrim (cxchar *string)
 Remove leading whitespace characters from a string. More...
 
cxchar * cx_strrtrim (cxchar *string)
 Remove trailing whitespace characters from a string. More...
 
cxchar * cx_strstrip (cxchar *string)
 Remove leading and trailing whitespace characters from a string. More...
 
cxchar * cx_strskip (const cxchar *string, int(*ctype)(int))
 Locate the first character in a string that does not belong to a given character class. More...
 
cxchar * cx_strdup (const cxchar *string)
 Duplicate a string. More...
 
cxchar * cx_strndup (const cxchar *string, cxsize n)
 Duplicate the first n charactes of a string. More...
 
cxchar * cx_strvdupf (const cxchar *format, va_list args)
 Create a string from a variable-length argument list under format control. More...
 
cxchar * cx_stpcpy (cxchar *dest, const cxchar *src)
 Copy a string returning a pointer to its end. More...
 
void cx_strfreev (cxchar **sarray)
 Deallocate a NULL terminated string array. More...
 
cxchar ** cx_strsplit (const cxchar *string, const cxchar *delimiter, cxint max_tokens)
 Split a string into pieces at a given delimiter. More...
 
cxchar * cx_strjoinv (const cxchar *separator, cxchar **sarray)
 Join strings from an array of strings. More...
 

Detailed Description

The module implements various string-related utility functions suitable for creating, searching and modifying C strings.

Synopsis:
#include <cxstrutils.h>

Function Documentation

cxchar* cx_stpcpy ( cxchar *  dest,
const cxchar *  src 
)

Copy a string returning a pointer to its end.

Parameters
destDestination string.
srcSource string.
Returns
Pointer to the terminating '\0' of the concatenated string.

The function copies the string src, including its terminating '\0', to the string dest. The source and the destination string may not overlap and the destination buffer must be large enough to receive the copy.

cxint cx_strcasecmp ( const cxchar *  s1,
const cxchar *  s2 
)

Compare two strings ignoring the case of ASCII characters.

Parameters
s1First string.
s2Second string.
Returns
An 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.

The function compares the two strings s1 and s2 as strcmp() does, but ignores the case of ASCII characters.

Referenced by cx_string_casecmp().

cxchar* cx_strdup ( const cxchar *  string)

Duplicate a string.

Parameters
stringString to be duplicated.
Returns
Newly allocated copy of the original string.

Duplicates the input string string. The newly allocated copy returned to the caller can be deallocated using cx_free().

Referenced by cx_program_set_name(), and cx_vasprintf().

cxint cx_strempty ( const cxchar *  string,
const cxchar *  pattern 
)

Test if a string represents an empty string.

Parameters
stringString to be tested.
patternString containing all allowed comment characters.
Returns
The function returns 1 if the string is found to be empty or if the first non–whitespace character is one out of the set of provided comment characters. Otherwise the function returns 0.

The function skips all leading whitespace characters in the string string. Whitespace characters are recognized by isspace(). If the first character which is not a whitespace character is either '\0' or one out of the pattern string pattern, the string is considered as empty and the function returns 1.

If pattern is set to NULL there is no checking for special characters that should be considered as whitespaces.

void cx_strfreev ( cxchar **  sarray)

Deallocate a NULL terminated string array.

Parameters
sarrayString array to deallocate
Returns
Nothing.

The function deallocates the array of strings sarray and any string it possibly contains.

References cx_free().

cxchar* cx_strjoinv ( const cxchar *  separator,
cxchar **  sarray 
)

Join strings from an array of strings.

Parameters
separatorOptional separator string.
sarrayArray of strings to join.
Returns
A newly allocated string containing the joined input strings separated by separator, or NULL in case of error.

The function builds a single string from the strings referenced by sarray. The array of input strings sarray has to be NULL terminated. Optionally, a separator string can be passed through separator which will then be inserted between two strings. If no separator should be inserted when joining, separator must be set to NULL.

References cx_malloc().

cxchar* cx_strlower ( cxchar *  s)

Convert all uppercase characters in a string into lowercase characters.

Parameters
sThe string to convert.
Returns
Returns a pointer to the converted string.

Walks through the given string and turns uppercase characters into lowercase characters using tolower().

See also
cx_strupper()
cxint cx_strncasecmp ( const cxchar *  s1,
const cxchar *  s2,
cxsize  n 
)

Compare the first n characters of two strings ignoring the case of ASCII characters.

Parameters
s1First string.
s2Second string.
nNumber of characters to compare.
Returns
An integer less than, equal to, or greater than zero if the first n characters of s1 are found, respectively, to be less than, to match, or be greater than the first n characters of s2.

The function compares the first n characters of the two strings s1 and s2 as strncmp() does, but ignores the case of ASCII characters.

Referenced by cx_string_ncasecmp().

cxchar* cx_strndup ( const cxchar *  string,
cxsize  n 
)

Duplicate the first n charactes of a string.

Parameters
stringSource string
nMaximum number of characters to be duplicated.
Returns
Newly allocated copy of the first n characters of string.

Duplicates the first n characters of the source string string, returning the copied characters in newly allocated string of the size n + 1. The returned string is always null terminated. If the length of string is less than n the returned string is padded with nulls. The newly allocated string can be deallocated using cx_free().

References cx_calloc().

cxchar* cx_strrtrim ( cxchar *  string)

Remove trailing whitespace characters from a string.

Parameters
stringString to be processed.
Returns
The function returns a pointer to the modified string if no error occurred, otherwise NULL.

The function removes trailing whitespace characters, or from the string string. Whitespace characters are recognized by isspace().

cxchar* cx_strskip ( const cxchar *  string,
int(*)(int)  ctype 
)

Locate the first character in a string that does not belong to a given character class.

Parameters
stringString to be processed.
ctypeCharacter class test function.
Returns
Pointer to the first character that is not a member of the character class described by ctype.

Searches the string string for the first occurence of a character which does not belong to a certain character class. The character class is represented through a function that returns a non zero value if a character belongs to that class and 0 otherwise. Such functions are the character classification routines like isspace() for instance. It is expected that the input string is properly terminated. In case the whole string consists of characters of the specified class the function will return the location of the terminating '\0'.

cxchar** cx_strsplit ( const cxchar *  string,
const cxchar *  delimiter,
cxint  max_tokens 
)

Split a string into pieces at a given delimiter.

Parameters
stringThe string to split.
delimiterString specifying the locations where to split.
max_tokensThe maximum number of tokens the string is split into.
Returns
The function returns a newly allocated, NULL terminated array of strings, or NULL in case of an error.

The function breaks up the string string into, at most, max_tokens pieces at the places indicated by delimiter. If max_tokens is reached, the remainder of the string is appended to the last token. If max_tokens is less than 1 the string string is split completely.

The delimiter string delimiter never shows up in any of the resulting strings, unless max_tokens is reached.

As a special case, the result of splitting the empty string "" is an empty vector, not a vector containing a single string.

The created result vector can be deallocated using cx_strfreev().

References cx_malloc(), cx_slist_begin(), cx_slist_delete(), cx_slist_end(), cx_slist_get(), cx_slist_new(), cx_slist_next(), and cx_slist_push_front().

cxchar* cx_strstrip ( cxchar *  string)

Remove leading and trailing whitespace characters from a string.

Returns
The function returns a pointer to the modified string if no error occurred, otherwise NULL.
Parameters
stringString to be processed.

The function removes leading and trailing whitespace characters from the string string. Whitespace characters are recognized by isspace().

cxchar* cx_strtrim ( cxchar *  string)

Remove leading whitespace characters from a string.

Parameters
stringString to be processed.
Returns
The function returns a pointer to the modified string if no error occurred, otherwise NULL.

The function removes leading whitespace characters, or from the string string. Whitespace characters are recognized by isspace().

cxchar* cx_strupper ( cxchar *  s)

Convert all lowercase characters in a string into uppercase characters.

Parameters
sThe string to convert.
Returns
Returns a pointer to the converted string.

Walks through the given string and turns lowercase characters into uppercase characters using toupper().

See also
strlower()
cxchar* cx_strvdupf ( const cxchar *  format,
va_list  args 
)

Create a string from a variable-length argument list under format control.

Parameters
formatThe format string.
argsVariable-length arguments to be inserted into format.
Returns
An newly allocated string containing the formatted result.

The function is similar to vsprintf() but calculates the size needed to store the formatted result string and allocates the memory. The newly allocated string can be deallocated using cx_free().

References cx_vasprintf().

Referenced by cx_logv(), cx_print(), and cx_printerr().