Strings

## Typedefs

typedef struct _cx_string_ | cx_string
| The cx_string data type.

## Functions

cx_string * | cx_string_new (void)
| Create a new, empty string container.
cx_string * | cx_string_copy (const cx_string *self)
| Create a copy a cx_string.
cx_string * | cx_string_create (const cxchar *value)
| Create a new string from a standard C string.
void | cx_string_delete (cx_string *self)
| Destroy a string.
cxsize | cx_string_size (const cx_string *self)
| Computes the length of the string.
cxbool | cx_string_empty (const cx_string *self)
| Checks whether a string contains any characters.
void | cx_string_set (cx_string *self, const cxchar *data)
| Assign a value to a string.
const cxchar * | cx_string_get (const cx_string *self)
| Get the string's value.
cx_string * | cx_string_upper (cx_string *self)
| Converts the string into uppercase.
cx_string * | cx_string_lower (cx_string *self)
| Converts the string into lowercase.
cx_string * | cx_string_trim (cx_string *self)
| Remove leading whitespaces from the string.
cx_string * | cx_string_rtrim (cx_string *self)
| Remove trailing whitespaces from the string.
cx_string * | cx_string_strip (cx_string *self)
| Remove leading and trailing whitespaces from the string.
cx_string * | cx_string_prepend (cx_string *self, const cxchar *data)
| Prepend an array of characters to the string.
cx_string * | cx_string_append (cx_string *self, const cxchar *data)
| Append an array of characters to the string.
cx_string * | cx_string_insert (cx_string *self, cxssize position, const cxchar *data)
| Inserts a copy of a string at a given position.
cx_string * | cx_string_erase (cx_string *self, cxssize position, cxssize length)
| Erase a portion of the string.
cx_string * | cx_string_truncate (cx_string *self, cxsize length)
| Truncate the string.
cxbool | cx_string_equal (const cx_string *string1, const cx_string *string2)
| Compare two cx_string for equality.
cxint | cx_string_compare (const cx_string *string1, const cx_string *string2)
| Compare two strings.
cxint | cx_string_casecmp (const cx_string *string1, const cx_string *string2)
| Compare two strings ignoring the case of characters.
cxint | cx_string_ncasecmp (const cx_string *string1, const cx_string *string2, cxsize n)
| Compare the first n characters of two strings ignoring the case of characters.
cxint | cx_string_sprintf (cx_string *self, const char *format,...)
| Writes to a string under format control.
cxint | cx_string_vsprintf (cx_string *self, const cxchar *format, va_list args)
| Write to the string from a variable-length argument list under format control.
void | cx_string_print (const cx_string *string)
| Print the value of a cx_string to the standard output.
void | cx_string_replace_character (cx_string *self, cxsize start, cxsize end, cxchar old_value, cxchar new_value)
| Replace a given character with a new character in a portion of a string.
void | cx_string_resize (cx_string *self, cxsize size, cxchar c)
| Resize a string to a given length.
void | cx_string_extend (cx_string *self, cxsize size, cxchar c)
| Extend a string to a given length.
cxsize | cx_string_find_first_not_of (const cx_string *self, const cxchar *characters)
| Search a string for the first character that does not match any of the given characters.
cxsize | cx_string_find_last_not_of (const cx_string *self, const cxchar *characters)
| Search a string for the last character that does not match any of the given characters.
cx_string * | cx_string_substr (const cx_string *self, cxsize pos, cxsize len)
| Create a new string from a portion of a string.

## Detailed Description

A cx_string is similar to a standard C string, except that it grows automatically as text is appended or inserted. The character data the string contains is '\0' terminated in order to guarantee full compatibility with string utility functions processing standard C strings. Together with the character data it also stores the length of the string.

## Function Documentation

## cx_string_append()

cx_string * cx_string_append | ( | cx_string * | self,
|  | const cxchar * | data )

Append an array of characters to the string.

Parameters

  self | The string.
  data | Pointer to character array to be appended.

Returns
  The passed string self with the characters appended, or `NULL` in case of errors.

The function adds the contents of the character buffer data to the end of the string. If data is a `NULL` pointer the string self is not modified.

References cx_free(), and cx_malloc().

Referenced by cx_log_default_handler().

## cx_string_casecmp()

cxint cx_string_casecmp | ( | const cx_string * | string1,
|  | const cx_string * | string2 )

Compare two strings ignoring the case of characters.

Parameters

  string1 | First cx_string.
  string2 | Second cx_string.

Returns
  The function returns an interger less than, equal to, or greater than `0` if string1 is found, respectively, to be less than, to match, or to be greater than string2.

The function compares string2 with string in the same way as the standard C function strcmp() does, but ignores the case of ASCII characters.

References cx_strcasecmp().

## cx_string_compare()

cxint cx_string_compare | ( | const cx_string * | string1,
|  | const cx_string * | string2 )

Compare two strings.

Parameters

  string1 | First cx_string.
  string2 | Second cx_string.

Returns
  The function returns an interger less than, equal to, or greater than `0` if string1 is found, respectively, to be less than, to match, or to be greater than string2.

The function compares string2 with string in the same way as the standard C function strcmp() does.

## cx_string_copy()

cx_string * cx_string_copy | ( | const cx_string * | self | ) |

Create a copy a cx_string.

Parameters

  self | The string to copy.

Returns
  Pointer to the newly created copy of string.

## cx_string_create()

cx_string * cx_string_create | ( | const cxchar * | value | ) |

Create a new string from a standard C string.

Parameters

  value | The initial text to copy into the string.

Returns
  Pointer to newly created string.

A new string is created and the text value is initially copied into the string.

Referenced by cx_string_substr().

## cx_string_delete()

void cx_string_delete | ( | cx_string * | self | ) |

Destroy a string.

Parameters

  self | The string to destroy.

Returns
  Nothing.

The function deallocates string's character buffer and finally frees the memory allocated for string itself.

References cx_free().

Referenced by cx_log_default_handler().

## cx_string_empty()

cxbool cx_string_empty | ( | const cx_string * | self | ) |

Checks whether a string contains any characters.

Parameters

  self | The string.

Returns
  The function returns TRUE if the string is empty, or FALSE otherwise.

A string is considered to be empty if its size is 0 or if it has not been initialized, i.e. no value has been assigned yet.

## cx_string_equal()

cxbool cx_string_equal | ( | const cx_string * | string1,
|  | const cx_string * | string2 )

Compare two cx_string for equality.

Parameters

  string1 | First cx_string.
  string2 | Second cx_string.

Returns
  TRUE if equal, FALSE if not.

The function checks whether two strings are equal. Two strings are equal if their values match on a character by character basis.

## cx_string_erase()

cx_string * cx_string_erase | ( | cx_string * | self,
|  | cxssize | position,
|  | cxssize | length )

Erase a portion of the string.

Parameters

  self | The string.
  position | Position of the first character to be erased.
  length | Number of characters to erase.

Returns
  The passed string self with the characters removed, or `NULL` in case of errors.

The function removes length characters from the string starting at the character index position. The number of characters to be removed is inclusive the character at index position. The characters following the removed portion are shifted to fill the gap. Character positions start counting from 0.

If the number of characters to erase length is less the `0` all characters starting at position up to the end of the string are erased.

References cx_free(), and cx_malloc().

## cx_string_extend()

void cx_string_extend | ( | cx_string * | self,
|  | cxsize | size,
|  | cxchar | c )

Extend a string to a given length.

Parameters

  self | A cx_string.
  size | The number of characters by which the string is enlarged.
  c | The character used to fill the new character space

Returns
  Nothing.

The function extends a string by adding to its end size number of of characters. The added characters are initialized with the character c.

Extending a string with zero characters leaves the string untouched.

See also
  cx_string_resize()

References cx_calloc(), and cx_free().

## cx_string_find_first_not_of()

cxsize cx_string_find_first_not_of | ( | const cx_string * | self,
|  | const cxchar * | characters )

Search a string for the first character that does not match any of the given characters.

Parameters

  self | A string.
  characters | Another string with a set of characters to be used in the search of the string.

Returns
  The function returns the position of the first character that does not match, or the position one past the last element of the string(i.e. the current size of the string) if no such character exists.

The function searches the given string for the first character that does not match any of the characters specified in the set of characters characters.

## cx_string_find_last_not_of()

cxsize cx_string_find_last_not_of | ( | const cx_string * | self,
|  | const cxchar * | characters )

Search a string for the last character that does not match any of the given characters.

Parameters

  self | A string.
  characters | Another string with a set of characters to be used in the search of the string.

Returns
  The function returns the position of the last character that does not match, or the position one past the last element of the string(i.e. the current size of the string) if no such character exists.

The function searches the given string for the last character that does not match any of the characters specified in the set of characters characters.

## cx_string_get()

const cxchar * cx_string_get | ( | const cx_string * | self | ) |

Get the string's value.

Parameters

  self | The string.

Returns
  A constant pointer to the string's data member, or `NULL` if the string is uninitialized.

A pointer to the strings character data. The character array pointed to by this pointer is an standard C string, i.e. '\0' terminated and can be used together with any string processing function from the standard C library (but see below).

Warning
  The string's data must not be modified using the returned pointer, otherwise the internal consistency may be lost.

Referenced by cx_log_default_handler().

## cx_string_insert()

cx_string * cx_string_insert | ( | cx_string * | self,
|  | cxssize | position,
|  | const cxchar * | data )

Inserts a copy of a string at a given position.

Parameters

  self | The string.
  position | Character position at which the data is inserted.
  data | Pointer to character array to be inserted.

Returns
  The passed string self with the characters inserted, or `NULL` in case of errors.

The function inserts the contents of the character buffer data at the character index position into the string, expanding the string if necessary. Character positions start counting from 0. If data is a `NULL` pointer the string self is not modified.

References cx_free(), and cx_malloc().

## cx_string_lower()

cx_string * cx_string_lower | ( | cx_string * | self | ) |

Converts the string into lowercase.

Parameters

  self | The string.

Returns
  The passed string self with all characters converted to lowercase, or `NULL` in case of errors.

All uppercase letters stored in the string are converted to lowercase letters. The conversion is done using the standard C function tolower().

## cx_string_ncasecmp()

cxint cx_string_ncasecmp | ( | const cx_string * | string1,
|  | const cx_string * | string2,
|  | cxsize | n )

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

Parameters

  string1 | First string.
  string2 | 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 string1 are found, respectively, to be less than, to match, or be greater than the first n characters of string2.

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

References cx_strncasecmp().

## cx_string_new()

cx_string * cx_string_new | ( | void |  | ) |

Create a new, empty string container.

Returns
  Pointer to newly created string.

The function allocates memory for a new string object and initializes it to represent the empty string.

Using this constructor is the only way to correctly create and setup a new string.

Referenced by cx_log_default_handler(), and cx_string_substr().

## cx_string_prepend()

cx_string * cx_string_prepend | ( | cx_string * | self,
|  | const cxchar * | data )

Prepend an array of characters to the string.

Parameters

  self | The string.
  data | Pointer to character array to be prepended.

Returns
  The passed string self with the characters prepended, or `NULL` in case of errors.

The function adds the contents of the character buffer data to the beginning of the string. If data is a `NULL` pointer the string self is not modified.

References cx_free(), and cx_malloc().

Referenced by cx_log_default_handler().

## cx_string_print()

void cx_string_print | ( | const cx_string * | string | ) |

Print the value of a cx_string to the standard output.

Parameters

  string | A cx_string.

This function is provided for debugging purposes. It just writes the strings contents to the standard output using cx_print().

References cx_print().

## cx_string_replace_character()

void cx_string_replace_character | ( | cx_string * | self,
|  | cxsize | start,
|  | cxsize | end,
|  | cxchar | old_value,
|  | cxchar | new_value )

Replace a given character with a new character in a portion of a string.

Parameters

  self | A cx_string.
  start | The initial position of the range.
  end | The final position of the range.
  old_value | The character to be replaced.
  new_value | The character used as replacement.

Returns
  Nothing.

The function replaces the all occurrences of the character old_value with the character new_value in the given range. The range of characters considered is given by the initial position start and the final position end, and does not include the final position, i.e. the range of characters is defined as [start, end).

If start is larger than the size of the string string, the function does nothing.

## cx_string_resize()

void cx_string_resize | ( | cx_string * | self,
|  | cxsize | size,
|  | cxchar | c )

Resize a string to a given length.

Parameters

  self | A cx_string.
  size | The new length of the string.
  c | The character used to fill the new character space

Returns
  Nothing.

The function resizes a string to a new length size. If the new length is smaller than the current length of the string, the string is shortened to its first size characters. If size is larger than the current length of the string its current contents is extended by adding to its end as many characters as needed to reach a length of size characters. In this latter case the added characters are initialized with the character c.

Specifying zero as the new length of the string, results in the empty string.

See also
  cx_string_truncate(), cx_string_extend()

References cx_free(), and cx_malloc().

## cx_string_rtrim()

cx_string * cx_string_rtrim | ( | cx_string * | self | ) |

Remove trailing whitespaces from the string.

Parameters

  self | The string.

Returns
  The passed string self with trailing whitespaces revoved, or `NULL` in case of errors.

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

## cx_string_set()

void cx_string_set | ( | cx_string * | self,
|  | const cxchar * | data )

Assign a value to a string.

Parameters

  self | The string.
  data | Character array to be assigned.

Returns
  Nothing.

Stores the contents of the character array pointed to by data into the string.

## cx_string_size()

cxsize cx_string_size | ( | const cx_string * | self | ) |

Computes the length of the string.

Parameters

  self | The string.

Returns
  The string's length, or 0 for uninitialized or empty strings.

Computes the length of the string.

## cx_string_sprintf()

cxint cx_string_sprintf | ( | cx_string * | self,
|  | const char * | format,
|  |  | ... )

Writes to a string under format control.

Parameters

  self | The string to write to.
  format | The format string.
  ... | The arguments to insert into format.

Returns
  The number of characters (excluding the trailing null) written to self, i.e. its length. If sufficient space cannot be allocated, -1 is returned.

The function writes the formatted character array to the string. The function works similar to sprintf() function, except that the string's buffer expands automatically to contain the formatted result. The previous contents of the string is destroyed.

Referenced by cx_log_default_handler().

## cx_string_strip()

cx_string * cx_string_strip | ( | cx_string * | self | ) |

Remove leading and trailing whitespaces from the string.

Parameters

  self | The string.

Returns
  The passed string self with leading and trailing whitespaces removed, or `NULL` in case of errors.

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

## cx_string_substr()

cx_string * cx_string_substr | ( | const cx_string * | self,
|  | cxsize | pos,
|  | cxsize | len )

Create a new string from a portion of a string.

Parameters

  self | A string.
  pos | Position of the first character of the substring.
  len | The length of the substring.

Returns
  The function returns a new string initialized with the characters of the specified substring.

The function constructs a new string with its value initialized to a copy of a substring of self. The substring is specified by the position of the first character of the substring pos, and the number of characters of the substring len (or the end of the string, whichever comes first).

If pos is equal to the length of self, an empty string is returned. It is an error if pos is greater than the length of self.

References cx_free(), cx_malloc(), cx_string_create(), and cx_string_new().

## cx_string_trim()

cx_string * cx_string_trim | ( | cx_string * | self | ) |

Remove leading whitespaces from the string.

Parameters

  self | The string.

Returns
  The passed string self with leading whitespaces removed, or `NULL` in case of errors.

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

## cx_string_truncate()

cx_string * cx_string_truncate | ( | cx_string * | self,
|  | cxsize | length )

Truncate the string.

Parameters

  self | The string.
  length | The length to which the string is truncated.

Returns
  The truncated string self, or `NULL` in case of errors.

The function removes all characters from the string starting at the character index length up to the end of the string, effectively truncating the string from its original size to a string of length length.

Calling the truncate method is equivalent to:

cx_string *s;
cx_string_erase(s, length, -1);
cx_string
struct _cx_string_ cx_string
The cx_string data type.
Definition cxstring.h:48
cx_string_erase
cx_string * cx_string_erase(cx_string *self, cxssize position, cxssize length)
Erase a portion of the string.
Definition cxstring.c:716

## cx_string_upper()

cx_string * cx_string_upper | ( | cx_string * | self | ) |

Converts the string into uppercase.

Parameters

  self | The string.

Returns
  The passed string self with all characters converted to uppercase, or `NULL` in case of errors.

All lowercase letters stored in the string are converted to uppercase letters. The conversion is done using the standard C function toupper().

## cx_string_vsprintf()

cxint cx_string_vsprintf | ( | cx_string * | self,
|  | const cxchar * | format,
|  | va_list | args )

Write to the string from a variable-length argument list under format control.

Parameters

  self | The string.
  format | The format string.
  args | Variable-length arguments to be inserted into format.

Returns
  The number of characters (excluding the trailing null) written to self, i.e. its length. If sufficient space cannot be allocated, -1 is returned.

The function writes the formatted character array to the string. The function works similar to vsprintf() function, except that the string's buffer expands automatically to contain the formatted result. The previous contents of the string is destroyed.