String Utility Functions

## Functions

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

## Detailed Description

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

Synopsis:
  #include "cxstrutils.h"

## Function Documentation

## cx_stpcpy()

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

Copy a string returning a pointer to its end.

Parameters

  dest | Destination string.
  src | Source 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.

## cx_strcasecmp()

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

Compare two strings ignoring the case of ASCII characters.

Parameters

  s1 | First string.
  s2 | Second 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().

## cx_strdup()

cxchar * cx_strdup | ( | const cxchar * | string | ) |

Duplicate a string.

Parameters

  string | String 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().

## cx_strempty()

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

Test if a string represents an empty string.

Parameters

  string | String to be tested.
  pattern | String 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.

## cx_strfreev()

void cx_strfreev | ( | cxchar ** | sarray | ) |

Deallocate a `NULL` terminated string array.

Parameters

  sarray | String array to deallocate

Returns
  Nothing.

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

References cx_free().

## cx_strjoinv()

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

Join strings from an array of strings.

Parameters

  separator | Optional separator string.
  sarray | Array 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().

## cx_strlower()

cxchar * cx_strlower | ( | cxchar * | s | ) |

Convert all uppercase characters in a string into lowercase characters.

Parameters

  s | The 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()

## cx_strncasecmp()

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

  s1 | First string.
  s2 | Second string.
  n | Number 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().

## cx_strndup()

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

Duplicate the first n charactes of a string.

Parameters

  string | Source string
  n | Maximum 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().

## cx_strrtrim()

cxchar * cx_strrtrim | ( | cxchar * | string | ) |

Remove trailing whitespace characters from a string.

Parameters

  string | String 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().

## cx_strskip()

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.

Parameters

  string | String to be processed.
  ctype | Character 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'.

## cx_strsplit()

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

Split a string into pieces at a given delimiter.

Parameters

  string | The string to split.
  delimiter | String specifying the locations where to split.
  max_tokens | The 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().

## cx_strstrip()

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

  string | String to be processed.

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

## cx_strtrim()

cxchar * cx_strtrim | ( | cxchar * | string | ) |

Remove leading whitespace characters from a string.

Parameters

  string | String 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().

## cx_strupper()

cxchar * cx_strupper | ( | cxchar * | s | ) |

Convert all lowercase characters in a string into uppercase characters.

Parameters

  s | The 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()

## cx_strvdupf()

cxchar * cx_strvdupf | ( | const cxchar * | format,
|  | va_list | args )

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

Parameters

  format | The format string.
  args | Variable-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().