C Standard Library Extensions  1.1
Typedefs | Functions
Strings

Typedefs

typedef struct _cx_string_ cx_string
 The cx_string data type.

Functions

cx_stringcx_string_new (void)
 Create a new, initialized string container.
cx_stringcx_string_copy (const cx_string *self)
 Create a copy a cx_string.
cx_stringcx_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_stringcx_string_upper (cx_string *self)
 Converts the string into uppercase.
cx_stringcx_string_lower (cx_string *self)
 Converts the string into lowercase.
cx_stringcx_string_trim (cx_string *self)
 Remove leading whitespaces from the string.
cx_stringcx_string_rtrim (cx_string *self)
 Remove trailing whitespaces from the string.
cx_stringcx_string_strip (cx_string *self)
 Remove leading and trailing whitespaces from the string.
cx_stringcx_string_prepend (cx_string *self, const cxchar *data)
 Prepend an array of characters to the string.
cx_stringcx_string_append (cx_string *self, const cxchar *data)
 Append an array of characters to the string.
cx_stringcx_string_insert (cx_string *self, cxssize position, const cxchar *data)
 Inserts a copy of a string at a given position.
cx_stringcx_string_erase (cx_string *self, cxssize position, cxssize length)
 Erase a portion of the string.
cx_stringcx_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.

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* cx_string_append ( cx_string self,
const cxchar *  data 
)

Append an array of characters to the string.

Parameters:
selfThe string.
dataPointer 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().

cxint cx_string_casecmp ( const cx_string string1,
const cx_string string2 
)

Compare two strings ignoring the case of characters.

Parameters:
string1First cx_string.
string2Second 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().

cxint cx_string_compare ( const cx_string string1,
const cx_string string2 
)

Compare two strings.

Parameters:
string1First cx_string.
string2Second 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* cx_string_copy ( const cx_string self)

Create a copy a cx_string.

Parameters:
selfThe string to copy.
Returns:
Pointer to the newly created copy of string.
cx_string* cx_string_create ( const cxchar *  value)

Create a new string from a standard C string.

Parameters:
valueThe 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.

void cx_string_delete ( cx_string self)

Destroy a string.

Parameters:
selfThe 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().

cxbool cx_string_empty ( const cx_string self)

Checks whether a string contains any characters.

Parameters:
selfThe 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.

cxbool cx_string_equal ( const cx_string string1,
const cx_string string2 
)

Compare two cx_string for equality.

Parameters:
string1First cx_string.
string2Second 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* cx_string_erase ( cx_string self,
cxssize  position,
cxssize  length 
)

Erase a portion of the string.

Parameters:
selfThe string.
positionPosition of the first character to be erased.
lengthNumber 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().

const cxchar* cx_string_get ( const cx_string self)

Get the string's value.

Parameters:
selfThe 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* cx_string_insert ( cx_string self,
cxssize  position,
const cxchar *  data 
)

Inserts a copy of a string at a given position.

Parameters:
selfThe string.
positionCharacter position at which the data is inserted.
dataPointer 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* cx_string_lower ( cx_string self)

Converts the string into lowercase.

Parameters:
selfThe 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().

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:
string1First string.
string2Second string.
nNumber 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* cx_string_new ( void  )

Create a new, initialized string container.

Returns:
Pointer to newly created string.

The function allocates memory for the string and initializes it, i.e. the member functions are hooked into the newly created string.

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

Referenced by cx_log_default_handler().

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

Prepend an array of characters to the string.

Parameters:
selfThe string.
dataPointer 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().

void cx_string_print ( const cx_string string)

Print the value of a cx_string to the standard output.

Parameters:
stringA 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* cx_string_rtrim ( cx_string self)

Remove trailing whitespaces from the string.

Parameters:
selfThe 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().

void cx_string_set ( cx_string self,
const cxchar *  data 
)

Assign a value to a string.

Parameters:
selfThe string.
dataCharacter array to be assigned.
Returns:
Nothing.

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

cxsize cx_string_size ( const cx_string self)

Computes the length of the string.

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

Computes the length of the string.

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

Writes to a string under format control.

Parameters:
selfThe string to write to.
formatThe 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* cx_string_strip ( cx_string self)

Remove leading and trailing whitespaces from the string.

Parameters:
selfThe 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* cx_string_trim ( cx_string self)

Remove leading whitespaces from the string.

Parameters:
selfThe 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* cx_string_truncate ( cx_string self,
cxsize  length 
)

Truncate the string.

Parameters:
selfThe string.
lengthThe 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_erase(s, length, -1);
cx_string* cx_string_upper ( cx_string self)

Converts the string into uppercase.

Parameters:
selfThe 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().

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:
selfThe string.
formatThe format string.
argsVariable-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.