ucc::string Class Reference

A copy-on-write string class that operates by reference count. More...

#include <string.h>

Inheritance diagram for ucc::string:

Inheritance graph
[legend]
Collaboration diagram for ucc::string:

Collaboration graph
[legend]

Data Structures

class  cstring
 This is an internal class which contains the actual string data along with some control fields. More...

Public Member Functions

 string ()
 Create a new empty string object.
 string (StringFormat &format)
 Create a string from a formatting object.
 string (strsize_t size)
 Create an empty string with a buffer pre-allocated to a specified size.
 string (strsize_t size, char fill)
 Create a filled string with a buffer pre-allocated to a specified size.
 string (strsize_t size, char *format,...)
 Create a string by printf-like formating into a pre-allocated space of a specified size.
 string (char *text)
 Create a string from null terminated text.
 string (char *text, strsize_t size)
 Create a string from null terminated text up to a maximum specified size.
 string (char *text, char *end)
 Create a string for a substring.
 string (string &existing)
 Construct a copy of a string object.
virtual ~string ()
 Destroy string.
string get (strsize_t offset, strsize_t size=0)
 Get a new string object as a substring of the current object.
int __isoc99_scanf (char *format,...)
 Scan input items from a string object.
int __isoc99_vscanf (char *format, va_list args)
 Scan input items from a string object.
strsize_t printf (char *format,...)
 Print items into a string object.
strsize_t vprintf (char *format, va_list args)
 Print items into a string object.
char * c_mem (void)
 Get memory text buffer of string object.
char * c_str (void)
 Get character text buffer of string object.
virtual bool resize (strsize_t size)
 Resize and re-allocate string memory.
void set (char *text)
 Set string object to text of a null terminated string.
void set (StringFormat &format)
 Set string object to text of a formatted object.
void set (strsize_t offset, char *text, strsize_t size=0)
 Set a portion of the string object at a specified offset to a text string.
void set (char *text, char overflow, strsize_t offset, strsize_t size=0)
 Set a text field within our string object.
void rset (char *text, char overflow, strsize_t offset, strsize_t size=0)
 Set a text field within our string object offset from the end of buffer.
void add (StringFormat &format)
 Append formatted object to our string buffer.
void add (char *text)
 Append null terminated text to our string buffer.
void add (char character)
 Append a single character to our string buffer.
void trim (char *list)
 Trim lead characters from the string.
void chop (char *list)
 Chop trailing characters from the string.
void strip (char *list)
 Strip lead and trailing characters from the string.
bool unquote (char *quote)
 Unquote a quoted string.
void cut (strsize_t offset, strsize_t size=0)
 Cut (remove) text from string.
void clear (strsize_t offset, strsize_t size=0)
 Clear a field of a filled string with filler.
void clear (void)
 Clear string by setting to empty.
void upper (void)
 Convert string to upper case.
void lower (void)
 Convert string to lower case.
strsize_t ccount (char *list)
 Count number of occurrances of characters in string.
strsize_t count (void)
 Count all characters in the string (strlen).
strsize_t size (void)
 Get the size of currently allocated space for string.
strsize_t offset (char *pointer)
 Find offset of a pointer into our string buffer.
char at (int position)
 Return character found at a specific position in the string.
char * last (char *list)
 Find last occurance of a character in the string.
char * first (char *list)
 Find first occurance of a character in the string.
char * begin (void)
 Get pointer to first character in string for iteration.
char * end (void)
 Get pointer to last character in string for iteration.
char * skip (char *list, strsize_t offset=0)
 Skip lead characters in the string.
char * rskip (char *list, strsize_t offset=npos)
 Skip trailing characters in the string.
char * find (char *list, strsize_t offset=0)
 Find a character in the string.
char * rfind (char *list, strsize_t offset=npos)
 Find last occurance of character in the string.
void split (char *pointer)
 Split the string by a pointer position.
void split (strsize_t offset)
 Split the string at a specific offset.
void rsplit (char *pointer)
 Split the string by a pointer position.
void rsplit (strsize_t offset)
 Split the string at a specific offset.
char * chr (char character)
 Find pointer in string where specified character appears.
char * rchr (char character)
 Find pointer in string where specified character last appears.
strsize_t len (void)
 Get length of string.
char fill (void)
 Get filler character used for field array strings.
 operator char * ()
 Casting reference to raw text string.
char * operator* ()
 Reference raw text buffer by pointer operator.
bool full (void)
 Test if the string's allocated space is all used up.
string operator() (int offset, strsize_t size)
 Get a new substring through object expression.
char * operator() (int offset)
 Reference a string in the object by relative offset.
char operator[] (int offset)
 Reference a single character in string object by array offset.
bool operator! ()
 Test if string is empty.
 operator bool ()
 Test if string has data.
stringoperator^= (string &object)
 Create new cow instance and assign value from another string object.
stringoperator^= (StringFormat &format)
 Create new cow instance and assign value from formatted string object.
stringoperator^= (char *text)
 Create new cow instance and assign value from null terminated text.
stringoperator+ (char *text)
 Concatenate null terminated text to our object.
stringoperator+ (StringFormat &format)
 Concatenate string formatted object to our object.
stringoperator& (char *text)
 Concatenate null terminated text to our object.
stringoperator& (StringFormat &format)
 Concatenate formatted string object to our object.
stringoperator= (string &object)
 Assign our string with the cstring of another object.
stringoperator= (StringFormat &format)
 Assign our string from a string formatting object.
stringoperator= (char *text)
 Assign text to our existing buffer.
stringoperator++ (void)
 Delete first character from string.
stringoperator+= (strsize_t number)
 Delete a specified number of characters from start of string.
stringoperator-- (void)
 Delete last character from string.
stringoperator-= (strsize_t number)
 Delete a specified number of characters from end of string.
bool operator== (char *text)
 Compare our object with null terminated text.
bool operator!= (char *text)
 Compare our object with null terminated text.
bool operator< (char *text)
 Compare our object with null terminated text.
bool operator<= (char *text)
 Compare our object with null terminated text.
bool operator> (char *text)
 Compare our object with null terminated text.
bool operator>= (char *text)
 Compare our object with null terminated text.

Static Public Member Functions

static int __isoc99_scanf (string &object, char *format,...)
 Scan input items from a string object.
static strsize_t printf (string &object, char *format,...)
 Print formatted items into a string object.
static int read (Socket &socket, string &object)
 Read arbitrary binary data from socket into a string object.
static int write (Socket &socket, string &object)
 Write the string object to a socket.
static int read (FILE *file, string &object)
 Read arbitrary binary data from a file into a string object.
static int write (FILE *file, string &object)
 Write the string object to a file.
static bool getline (Socket &socket, string &object)
 Read a line of text input from a socket into the object.
static bool putline (Socket &socket, string &object)
 Write string as a line of text data to a socket.
static bool getline (FILE *file, string &object)
 Read a line of text input from a file into the object.
static bool putline (FILE *file, string &object)
 Write string as a line of text data to a file.
static void swap (string &object1, string &object2)
 Swap the cstring references between two strings.
static void fix (string &object)
 Fix and reset string object filler.
static void lower (char *text)
 Convert null terminated text to lower case.
static void upper (char *text)
 Convert null terminated text to upper case.
static char * token (char *text, char **last, char *list, char *quote=((void *) 0), char *end=((void *) 0))
 A thread-safe token parsing routine for null terminated strings.
static char * skip (char *text, char *list)
 Skip after lead characters in a null terminated string.
static char * rskip (char *text, char *list)
 Skip before trailing characters in a null terminated string.
static char * unquote (char *text, char *quote)
 Unquote a quoted null terminated string.
static char * rset (char *buffer, size_t size, char *text)
 Set a field in a null terminated string relative to the end of text.
static char * set (char *buffer, size_t size, char *text)
 Safely set a null terminated string buffer in memory.
static char * set (char *buffer, size_t size, char *text, size_t max)
 Safely set a null terminated string buffer in memory.
static char * add (char *buffer, size_t size, char *text)
 Safely append a null terminated string into an existing string in memory.
static char * add (char *buffer, size_t size, char *text, size_t max)
 Safely append a null terminated string into an existing string in memory.
static char * ifind (char *text, char *key, char *optional)
 Find position of case insensitive substring within a string.
static char * find (char *text, char *key, char *optional)
 Find position of substring within a string.
static size_t count (char *text)
 Safe version of strlen function.
static int compare (char *text1, char *text2)
 Safe string comparison function.
static bool equal (char *text1, char *text2)
 Simple equal test for strings.
static int compare (char *text1, char *text2, size_t size)
 Safe string comparison function.
static bool equal (char *text1, char *text2, size_t size)
 Simple equal test for strings.
static int case_compare (char *text1, char *text2)
 Safe case insensitive string comparison function.
static bool case_equal (char *text1, char *text2)
 Simple case insensitive equal test for strings.
static int case_compare (char *text1, char *text2, size_t size)
 Safe case insensitive string comparison function.
static bool case_equal (char *text1, char *text2, size_t size)
 Simple case insenstive equal test for strings.
static char * trim (char *text, char *list)
 Return start of string after characters to trim from beginning.
static char * chop (char *text, char *list)
 Strip trailing characters from the text string.
static char * strip (char *text, char *list)
 Skip lead and remove trailing characters from a text string.
static char * fill (char *text, size_t size, char character)
 Fill a section of memory with a fixed text character.
static unsigned ccount (char *text, char *list)
 Count instances of characters in a list in a text buffer.
static char * find (char *text, char *list)
 Find the first occurance of a character in a text buffer.
static char * rfind (char *text, char *list)
 Find the last occurance of a character in a text buffer.
static char * first (char *text, char *list)
 Get pointer to first character past character requested.
static char * last (char *text, char *list)
 Get pointer to last character before character requested.
static char * dup (char *text)
 Duplicate null terminated text into the heap.
static char * token (string &object, char **last, char *list, char *quote=((void *) 0), char *end=((void *) 0))
 A thread-safe token parsing routine for strings objects.
static int __isoc99_vscanf (string &object, char *format, va_list args)
 Scan input items from a string object.
static strsize_t vprintf (string &object, char *format, va_list args)
 Print items into a string object.
static strsize_t len (string &object)
 Count all characters in the string object (strlen).
static char * mem (string &object)
 Get memory text buffer of string object.
static strsize_t size (string &object)
 Get the size of currently allocated space for string.
static void clear (string &object)
 Clear a string object.
static unsigned ccount (string &object, char *list)
 Count number of occurrances of characters in string object.
static size_t count (string &object)
 Count all characters in the string object (strlen).
static void upper (string &object)
 Convert string object to upper case.
static void lower (string &object)
 Convert string object to lower case.
static bool unquote (string &object, char *quote)
 Unquote a quoted string.
static void trim (string &object, char *list)
 Trim lead characters from the string.
static void chop (string &object, char *list)
 Chop trailing characters from the string.
static void strip (string &object, char *list)
 Strip lead and trailing characters from the string.
static char * find (string &object, char *list)
 Find a character in the string.
static char * rfind (string &object, char *list)
 Find last character in the string.
static char * first (string &object, char *list)
 Get pointer to first character past character requested.
static char * last (string &object, char *list)
 Get pointer to last character past character requested.
static double tod (string &object, char **pointer=((void *) 0))
 Convert string to a double value.
static long tol (string &object, char **pointer=((void *) 0))
 Convert string to a long value.
static double tod (char *text, char **pointer=((void *) 0))
 Convert text to a double value.
static long tol (char *text, char **pointer=((void *) 0))
 Convert text to a long value.

Static Public Attributes

static strsize_t npos
 A constant for an invalid position value.

Protected Member Functions

cstringcreate (strsize_t size, char fill=0)
 Factory create a cstring object of specified size.
virtual int compare (char *string)
 Compare the values of two string.
bool equal (char *string)
 Test if two string values are equal.
virtual void retain (void)
 Increase retention of our reference counted cstring.
virtual void release (void)
 Decrease retention of our reference counted cstring.
virtual cstringc_copy (void)
 Return cstring to use in copy constructors.
virtual void cow (strsize_t size=0)
 Copy on write operation for cstring.
strsize_t getStringSize (void)

Protected Attributes

cstringstr
 cstring instance our object references.

Friends

class StringFormat

Detailed Description

A copy-on-write string class that operates by reference count.

This string class anchors a counted object that is managed as a copy-on-write instance of the string data. This means that multiple instances of the string class can refer to the same string in memory if it has not been modifed, which reduces heap allocation. The string class offers functions to manipulate both the string object, and generic safe string functions to manipulate ordinary null terminated character arrays directly in memory.

Author:
David Sugar <dyfet@gnutelephony.org>

Definition at line 72 of file string.h.


Constructor & Destructor Documentation

ucc::string::string ( StringFormat format  ) 

Create a string from a formatting object.

Parameters:
format object to use in creating string.

ucc::string::string ( strsize_t  size  ) 

Create an empty string with a buffer pre-allocated to a specified size.

Parameters:
size of buffer to allocate.

ucc::string::string ( strsize_t  size,
char  fill 
)

Create a filled string with a buffer pre-allocated to a specified size.

Parameters:
size of buffer to allocate.
fill character to use.

ucc::string::string ( strsize_t  size,
char *  format,
  ... 
)

Create a string by printf-like formating into a pre-allocated space of a specified size.

Parameters:
size of buffer to allocate.
format control for string.

ucc::string::string ( char *  text  ) 

Create a string from null terminated text.

Parameters:
text to use for string.

ucc::string::string ( char *  text,
strsize_t  size 
)

Create a string from null terminated text up to a maximum specified size.

Parameters:
text to use for string.
size limit of new string.

ucc::string::string ( char *  text,
char *  end 
)

Create a string for a substring.

The end of the substring is a pointer within the substring itself.

Parameters:
text to use for string.
end of text in substring.

ucc::string::string ( string existing  ) 

Construct a copy of a string object.

Our copy inherets the same reference counted instance of cstring as in the original.

Parameters:
existing string to copy from.

virtual ucc::string::~string (  )  [virtual]

Destroy string.

De-reference cstring. If last reference to cstring, then also remove cstring from heap.


Member Function Documentation

static int ucc::string::__isoc99_scanf ( string object,
char *  format,
  ... 
) [static]

Scan input items from a string object.

Parameters:
object to scan from.
format string of input to scan.
Returns:
number of items scanned.

int ucc::string::__isoc99_scanf ( char *  format,
  ... 
)

Scan input items from a string object.

Parameters:
format string of input to scan.
Returns:
number of items scanned.

static int ucc::string::__isoc99_vscanf ( string object,
char *  format,
va_list  args 
) [inline, static]

Scan input items from a string object.

Parameters:
object to scan.
format string of input to scan.
args list to scan into.
Returns:
number of items scanned.

Definition at line 1235 of file string.h.

int ucc::string::__isoc99_vscanf ( char *  format,
va_list  args 
)

Scan input items from a string object.

Parameters:
format string of input to scan.
args list to scan into.
Returns:
number of items scanned.

static char* ucc::string::add ( char *  buffer,
size_t  size,
char *  text,
size_t  max 
) [static]

Safely append a null terminated string into an existing string in memory.

If the resulting string is too large to fit into the buffer, it is truncated to the size.

Parameters:
buffer to set.
size of buffer. Includes null byte at end of string.
text to set in buffer.
max size of text to append.
Returns:
pointer to text buffer.

static char* ucc::string::add ( char *  buffer,
size_t  size,
char *  text 
) [static]

Safely append a null terminated string into an existing string in memory.

If the resulting string is too large to fit into the buffer, it is truncated to the size.

Parameters:
buffer to set.
size of buffer. Includes null byte at end of string.
text to set in buffer.
Returns:
pointer to text buffer.

void ucc::string::add ( char  character  ) 

Append a single character to our string buffer.

Parameters:
character to append.

void ucc::string::add ( char *  text  ) 

Append null terminated text to our string buffer.

Parameters:
text to append.

void ucc::string::add ( StringFormat format  ) 

Append formatted object to our string buffer.

Parameters:
format object to append.

char ucc::string::at ( int  position  ) 

Return character found at a specific position in the string.

Parameters:
position in string, negative values computed from end.
Returns:
character code at specified position in string.

char* ucc::string::begin ( void   ) 

Get pointer to first character in string for iteration.

Returns:
first character pointer or NULL if empty.

virtual cstring* ucc::string::c_copy ( void   )  [protected, virtual]

Return cstring to use in copy constructors.

Is virtual for memstring.

Returns:
cstring for copy constructor.

Reimplemented in ucc::memstring.

char* ucc::string::c_mem ( void   ) 

Get memory text buffer of string object.

Returns:
writable string buffer.

char* ucc::string::c_str ( void   ) 

Get character text buffer of string object.

Returns:
character text buffer.

static int ucc::string::case_compare ( char *  text1,
char *  text2,
size_t  size 
) [static]

Safe case insensitive string comparison function.

Parameters:
text1 to compare.
text2 to compare.
size limit of strings to compare.
Returns:
0 if equal, >0 if text1 > text2, <0 if text1 < text2.

static int ucc::string::case_compare ( char *  text1,
char *  text2 
) [static]

Safe case insensitive string comparison function.

Parameters:
text1 to compare.
text2 to compare.
Returns:
0 if equal, >0 if text1 > text2, <0 if text1 < text2.

static bool ucc::string::case_equal ( char *  text1,
char *  text2,
size_t  size 
) [static]

Simple case insenstive equal test for strings.

Parameters:
text1 to test.
text2 to test.
size limit of strings to compare.
Returns:
true if equal.

static bool ucc::string::case_equal ( char *  text1,
char *  text2 
) [static]

Simple case insensitive equal test for strings.

Parameters:
text1 to test.
text2 to test.
Returns:
true if equal.

static unsigned ucc::string::ccount ( string object,
char *  list 
) [inline, static]

Count number of occurrances of characters in string object.

Parameters:
object to examine.
list of characters to find.
Returns:
count of instances of characters.

Definition at line 1285 of file string.h.

static unsigned ucc::string::ccount ( char *  text,
char *  list 
) [static]

Count instances of characters in a list in a text buffer.

Parameters:
text buffer to examine.
list of characters to count in buffer.
Returns:
number of instances of the characters in buffer.

strsize_t ucc::string::ccount ( char *  list  ) 

Count number of occurrances of characters in string.

Parameters:
list of characters to find.
Returns:
count of instances of characters in string.

static void ucc::string::chop ( string object,
char *  list 
) [inline, static]

Chop trailing characters from the string.

Parameters:
object to chop.
list of characters to remove.

Definition at line 1332 of file string.h.

static char* ucc::string::chop ( char *  text,
char *  list 
) [static]

Strip trailing characters from the text string.

This function will modify memory.

Parameters:
text buffer to examine.
list of characters to chop from trailing end of string.
Returns:
pointer to text buffer.

void ucc::string::chop ( char *  list  ) 

Chop trailing characters from the string.

Parameters:
list of characters to remove.

char* ucc::string::chr ( char  character  ) 

Find pointer in string where specified character appears.

Parameters:
character to find.
Returns:
string pointer for character if found, NULL if not.

static void ucc::string::clear ( string object  )  [inline, static]

Clear a string object.

Parameters:
object to clear.

Definition at line 1276 of file string.h.

void ucc::string::clear ( strsize_t  offset,
strsize_t  size = 0 
)

Clear a field of a filled string with filler.

Parameters:
offset to start of field to clear.
size of field to fill or 0 to fill to end of string.

static int ucc::string::compare ( char *  text1,
char *  text2,
size_t  size 
) [static]

Safe string comparison function.

Parameters:
text1 to compare.
text2 to compare.
size limit of strings to compare.
Returns:
0 if equal, >0 if text1 > text2, <0 if text1 < text2.

static int ucc::string::compare ( char *  text1,
char *  text2 
) [static]

Safe string comparison function.

Parameters:
text1 to compare.
text2 to compare.
Returns:
0 if equal, >0 if text1 > text2, <0 if text1 < text2.

virtual int ucc::string::compare ( char *  string  )  [protected, virtual]

Compare the values of two string.

This is a virtual so that it can be overriden for example if we want to create strings which ignore case, or which have special ordering rules.

Parameters:
string to compare with.
Returns:
0 if equal, <0 if less than, 0> if greater than.

static size_t ucc::string::count ( string object  )  [inline, static]

Count all characters in the string object (strlen).

Parameters:
object to count.
Returns:
count of characters.

Definition at line 1293 of file string.h.

static size_t ucc::string::count ( char *  text  )  [static]

Safe version of strlen function.

Accepts NULL as 0 length strings.

Parameters:
text string.
Returns:
length of string.

strsize_t ucc::string::count ( void   ) 

Count all characters in the string (strlen).

Returns:
count of characters.

virtual void ucc::string::cow ( strsize_t  size = 0  )  [protected, virtual]

Copy on write operation for cstring.

This always creates a new unique copy for write/modify operations and is a virtual for memstring to disable.

Parameters:
size to add to allocated space when creating new cstring.

cstring* ucc::string::create ( strsize_t  size,
char  fill = 0 
) [protected]

Factory create a cstring object of specified size.

Parameters:
size of allocated space for string buffer.
fill character to use or 0 if null.
Returns:
new cstring object.

Reimplemented in ucc::memstring.

void ucc::string::cut ( strsize_t  offset,
strsize_t  size = 0 
)

Cut (remove) text from string.

Parameters:
offset to start of text field to remove.
size of text field to remove or 0 to remove to end of string.

static char* ucc::string::dup ( char *  text  )  [static]

Duplicate null terminated text into the heap.

Parameters:
text to duplicate.
Returns:
duplicate copy of text allocated from heap.

char* ucc::string::end ( void   ) 

Get pointer to last character in string for iteration.

Returns:
last character pointer or NULL if empty.

static bool ucc::string::equal ( char *  text1,
char *  text2,
size_t  size 
) [static]

Simple equal test for strings.

Parameters:
text1 to test.
text2 to test.
size limit of strings to compare.
Returns:
true if equal and case is same.

static bool ucc::string::equal ( char *  text1,
char *  text2 
) [static]

Simple equal test for strings.

Parameters:
text1 to test.
text2 to test.
Returns:
true if equal and case is same.

bool ucc::string::equal ( char *  string  )  [protected]

Test if two string values are equal.

Parameters:
string to compare with.
Returns:
true if equal.

static char* ucc::string::fill ( char *  text,
size_t  size,
char  character 
) [static]

Fill a section of memory with a fixed text character.

Adds a null byte at the end.

Parameters:
text buffer to fill.
size of text buffer with null terminated byte.
character to fill with.
Returns:
pointer to text buffer.

char ucc::string::fill ( void   ) 

Get filler character used for field array strings.

Returns:
filler character or 0 if none.

static char* ucc::string::find ( string object,
char *  list 
) [inline, static]

Find a character in the string.

Parameters:
object to search.
list of characters to search for.
Returns:
pointer to first occurance of character.

Definition at line 1349 of file string.h.

static char* ucc::string::find ( char *  text,
char *  list 
) [static]

Find the first occurance of a character in a text buffer.

Parameters:
text buffer to examine.
list of characters to search for.
Returns:
pointer to first instance found or NULL.

static char* ucc::string::find ( char *  text,
char *  key,
char *  optional 
) [static]

Find position of substring within a string.

Parameters:
text to search in.
key string to locate.
optional separator chars if formatted as list of keys.
Returns:
substring position if found, or NULL.

char* ucc::string::find ( char *  list,
strsize_t  offset = 0 
)

Find a character in the string.

Parameters:
list of characters to search for.
offset to start of search.
Returns:
pointer to first occurance of character.

static char* ucc::string::first ( string object,
char *  list 
) [inline, static]

Get pointer to first character past character requested.

Parameters:
object to examine.
list of characters.
Returns:
first character pointer past list.

Definition at line 1367 of file string.h.

static char* ucc::string::first ( char *  text,
char *  list 
) [static]

Get pointer to first character past character requested.

Parameters:
text buffer to examine.
list of characters.
Returns:
first character pointer past list.

char* ucc::string::first ( char *  list  ) 

Find first occurance of a character in the string.

Parameters:
list of characters to search for.
Returns:
pointer to first occurance from list or NULL.

static void ucc::string::fix ( string object  )  [static]

Fix and reset string object filler.

Parameters:
object to fix.

bool ucc::string::full ( void   ) 

Test if the string's allocated space is all used up.

Returns:
true if no more room for append.

string ucc::string::get ( strsize_t  offset,
strsize_t  size = 0 
)

Get a new string object as a substring of the current object.

Parameters:
offset of substring.
size of substring or 0 if to end.
Returns:
string object holding substring.

static bool ucc::string::getline ( FILE *  file,
string object 
) [static]

Read a line of text input from a file into the object.

The maximum number of bytes that may be read is based on the currently allocated size of the object.

Parameters:
file to read from.
object to save read data.
Returns:
false if end of file.

static bool ucc::string::getline ( Socket socket,
string object 
) [static]

Read a line of text input from a socket into the object.

The maximum number of bytes that may be read is based on the currently allocated size of the object.

Parameters:
socket to read from.
object to save read data.
Returns:
false if end of file.

static char* ucc::string::ifind ( char *  text,
char *  key,
char *  optional 
) [static]

Find position of case insensitive substring within a string.

Parameters:
text to search in.
key string to locate.
optional separator chars if formatted as list of keys.
Returns:
substring position if found, or NULL.

static char* ucc::string::last ( string object,
char *  list 
) [inline, static]

Get pointer to last character past character requested.

Parameters:
object to examine.
list of characters.
Returns:
last character pointer before list.

Definition at line 1376 of file string.h.

static char* ucc::string::last ( char *  text,
char *  list 
) [static]

Get pointer to last character before character requested.

Parameters:
text buffer to examine.
list of characters.
Returns:
last character pointer past list.

char* ucc::string::last ( char *  list  ) 

Find last occurance of a character in the string.

Parameters:
list of characters to search for.
Returns:
pointer to last occurance from list or NULL.

static strsize_t ucc::string::len ( string object  )  [inline, static]

Count all characters in the string object (strlen).

Parameters:
object to count.
Returns:
count of characters.

Definition at line 1253 of file string.h.

strsize_t ucc::string::len ( void   ) 

Get length of string.

Returns:
length of string.

static void ucc::string::lower ( string object  )  [inline, static]

Convert string object to lower case.

Parameters:
object to modify.

Definition at line 1307 of file string.h.

static void ucc::string::lower ( char *  text  )  [static]

Convert null terminated text to lower case.

Parameters:
text to convert.

static char* ucc::string::mem ( string object  )  [inline, static]

Get memory text buffer of string object.

Parameters:
object to get string buffer from.
Returns:
writable string buffer.

Definition at line 1261 of file string.h.

strsize_t ucc::string::offset ( char *  pointer  ) 

Find offset of a pointer into our string buffer.

This can be used to find the offset position of a pointer returned by find, for example. This is used when one needs to convert a member function that returns a pointer to call a member function that operates by a offset value. If the pointer is outside the range of the string then npos is returned.

Parameters:
pointer into our object's string buffer.

ucc::string::operator bool (  ) 

Test if string has data.

Returns:
true if string has data.

ucc::string::operator char * (  )  [inline]

Casting reference to raw text string.

Returns:
null terminated text of string.

Definition at line 640 of file string.h.

bool ucc::string::operator! (  ) 

Test if string is empty.

Returns:
true if string is empty.

bool ucc::string::operator!= ( char *  text  ) 

Compare our object with null terminated text.

Compare method is used.

Parameters:
text to compare with.
Returns:
true if we are not equal.

string& ucc::string::operator& ( StringFormat format  ) 

Concatenate formatted string object to our object.

This directly appends the text to the string buffer and does not resize the object if the existing cstring allocation space is fully used.

Parameters:
format object to concatenate.

string& ucc::string::operator& ( char *  text  ) 

Concatenate null terminated text to our object.

This directly appends the text to the string buffer and does not resize the object if the existing cstring allocation space is fully used.

Parameters:
text to concatenate.

char* ucc::string::operator() ( int  offset  ) 

Reference a string in the object by relative offset.

Positive offsets are from the start of the string, negative from the end.

Parameters:
offset to string position.
Returns:
pointer to string data or NULL if invalid offset.

string ucc::string::operator() ( int  offset,
strsize_t  size 
)

Get a new substring through object expression.

Parameters:
offset of substring.
size of substring or 0 if to end.
Returns:
string object holding substring.

char* ucc::string::operator* (  )  [inline]

Reference raw text buffer by pointer operator.

Returns:
null terminated text of string.

Definition at line 647 of file string.h.

string& ucc::string::operator+ ( StringFormat format  ) 

Concatenate string formatted object to our object.

This creates a new copy-on-write instance to hold the concatenated string.

Parameters:
format object to concatenate.

string& ucc::string::operator+ ( char *  text  ) 

Concatenate null terminated text to our object.

This creates a new copy-on-write instance to hold the concatenated string.

Parameters:
text to concatenate.

string& ucc::string::operator+= ( strsize_t  number  ) 

Delete a specified number of characters from start of string.

Parameters:
number of characters to delete.

string& ucc::string::operator-= ( strsize_t  number  ) 

Delete a specified number of characters from end of string.

Parameters:
number of characters to delete.

bool ucc::string::operator< ( char *  text  ) 

Compare our object with null terminated text.

Compare method is used.

Parameters:
text to compare with.
Returns:
true if we are less than text.

bool ucc::string::operator<= ( char *  text  ) 

Compare our object with null terminated text.

Compare method is used.

Parameters:
text to compare with.
Returns:
true if we are less than or equal to text.

string& ucc::string::operator= ( char *  text  ) 

Assign text to our existing buffer.

This performs a set method.

Parameters:
text to assign from.

Reimplemented in ucc::memstring, and ucc::stringbuf< S >.

string& ucc::string::operator= ( StringFormat format  ) 

Assign our string from a string formatting object.

Parameters:
format object to assign from.

string& ucc::string::operator= ( string object  ) 

Assign our string with the cstring of another object.

If we had an active string reference, it is released. The object now has a duplicate reference to the cstring of the other object.

Parameters:
object to assign from.

Reimplemented in ucc::memstring, and ucc::stringbuf< S >.

bool ucc::string::operator== ( char *  text  ) 

Compare our object with null terminated text.

Parameters:
text to compare with.
Returns:
true if we are equal.

bool ucc::string::operator> ( char *  text  ) 

Compare our object with null terminated text.

Compare method is used.

Parameters:
text to compare with.
Returns:
true if we are greater than text.

bool ucc::string::operator>= ( char *  text  ) 

Compare our object with null terminated text.

Compare method is used.

Parameters:
text to compare with.
Returns:
true if we are greater than or equal to text.

char ucc::string::operator[] ( int  offset  ) 

Reference a single character in string object by array offset.

Parameters:
offset to character.
Returns:
character value at offset.

string& ucc::string::operator^= ( char *  text  ) 

Create new cow instance and assign value from null terminated text.

Parameters:
text to assign from.
Returns:
our object for expression use.

string& ucc::string::operator^= ( StringFormat format  ) 

Create new cow instance and assign value from formatted string object.

Parameters:
format object to assign from.
Returns:
our object for expression use.

string& ucc::string::operator^= ( string object  ) 

Create new cow instance and assign value from another string object.

Parameters:
object to assign from.
Returns:
our object for expression use.

static strsize_t ucc::string::printf ( string object,
char *  format,
  ... 
) [static]

Print formatted items into a string object.

Parameters:
object to print into.
format string to print with.
Returns:
number of bytes written into object.

strsize_t ucc::string::printf ( char *  format,
  ... 
)

Print items into a string object.

Parameters:
format string of print format.
Returns:
number of bytes written to string.

static bool ucc::string::putline ( FILE *  file,
string object 
) [static]

Write string as a line of text data to a file.

A newline will be appended to the end.

Parameters:
file to print to.
object to get text line to put into file.
Returns:
true if successful.

static bool ucc::string::putline ( Socket socket,
string object 
) [static]

Write string as a line of text data to a socket.

A newline will be appended to the end.

Parameters:
socket to print to.
object to get text line from.
Returns:
true if successful.

char* ucc::string::rchr ( char  character  ) 

Find pointer in string where specified character last appears.

Parameters:
character to find.
Returns:
string pointer for last occurance of character if found, NULL if not.

static int ucc::string::read ( FILE *  file,
string object 
) [static]

Read arbitrary binary data from a file into a string object.

The total number of bytes that may be read is based on the allocated size of the object.

Parameters:
file to read from.
object to save read data.
Returns:
number of bytes read.

static int ucc::string::read ( Socket socket,
string object 
) [static]

Read arbitrary binary data from socket into a string object.

The total number of bytes that may be read is based on the allocated size of the object.

Parameters:
socket to read from.
object to save read data.
Returns:
number of bytes read.

virtual void ucc::string::release ( void   )  [protected, virtual]

Decrease retention of our reference counted cstring.

May be overriden for memstring which has fixed cstring object.

Reimplemented from ucc::Object.

virtual bool ucc::string::resize ( strsize_t  size  )  [virtual]

Resize and re-allocate string memory.

Parameters:
size to allocate for string.
Returns:
true if re-allocated. False in derived memstring.

virtual void ucc::string::retain ( void   )  [protected, virtual]

Increase retention of our reference counted cstring.

May be overriden for memstring which has fixed cstring object.

Reimplemented from ucc::Object.

static char* ucc::string::rfind ( string object,
char *  list 
) [inline, static]

Find last character in the string.

Parameters:
object to search.
list of characters to search for.
Returns:
pointer to last occurance of character.

Definition at line 1358 of file string.h.

static char* ucc::string::rfind ( char *  text,
char *  list 
) [static]

Find the last occurance of a character in a text buffer.

Parameters:
text buffer to examine.
list of characters to search for.
Returns:
pointer to last instance found or NULL.

char* ucc::string::rfind ( char *  list,
strsize_t  offset = npos 
)

Find last occurance of character in the string.

Parameters:
list of characters to search for.
offset to start of search. Default is end of string.
Returns:
pointer to last occurance of character.

static char* ucc::string::rset ( char *  buffer,
size_t  size,
char *  text 
) [static]

Set a field in a null terminated string relative to the end of text.

Parameters:
buffer to modify.
size of field to set.
text to replace end of string with.
Returns:
pointer to text buffer.

void ucc::string::rset ( char *  text,
char  overflow,
strsize_t  offset,
strsize_t  size = 0 
)

Set a text field within our string object offset from the end of buffer.

Parameters:
text to set.
overflow character to use as filler if text is too short.
offset from end of object string buffer to set text at.
size of part of buffer to set with text and overflow.

static char* ucc::string::rskip ( char *  text,
char *  list 
) [static]

Skip before trailing characters in a null terminated string.

Parameters:
text pointer to start at.
list of characters to skip when found.
Returns:
pointer to last part of string past skipped characters.

char* ucc::string::rskip ( char *  list,
strsize_t  offset = npos 
)

Skip trailing characters in the string.

This searches the string in reverse order.

Parameters:
list of characters to skip when found.
offset to start of scan. Default is end of string.
Returns:
pointer to first part of string before skipped characters.

void ucc::string::rsplit ( strsize_t  offset  ) 

Split the string at a specific offset.

Everything before the offset is removed.

Parameters:
offset to split position in string.

void ucc::string::rsplit ( char *  pointer  ) 

Split the string by a pointer position.

Everything before the pointer is removed.

Parameters:
pointer to split position in string.

static char* ucc::string::set ( char *  buffer,
size_t  size,
char *  text,
size_t  max 
) [static]

Safely set a null terminated string buffer in memory.

If the text is too large to fit into the buffer, it is truncated to the size.

Parameters:
buffer to set.
size of buffer. Includes null byte at end of string.
text to set in buffer.
max size of text to set.
Returns:
pointer to text buffer.

static char* ucc::string::set ( char *  buffer,
size_t  size,
char *  text 
) [static]

Safely set a null terminated string buffer in memory.

If the text is too large to fit into the buffer, it is truncated to the size.

Parameters:
buffer to set.
size of buffer. Includes null byte at end of string.
text to set in buffer.
Returns:
pointer to text buffer.

void ucc::string::set ( char *  text,
char  overflow,
strsize_t  offset,
strsize_t  size = 0 
)

Set a text field within our string object.

Parameters:
text to set.
overflow character to use as filler if text is too short.
offset in object string buffer to set text at.
size of part of buffer to set with text and overflow.

void ucc::string::set ( strsize_t  offset,
char *  text,
strsize_t  size = 0 
)

Set a portion of the string object at a specified offset to a text string.

Parameters:
offset in object string buffer.
text to set at offset.
size of text area to set or 0 until end of text.

void ucc::string::set ( StringFormat format  ) 

Set string object to text of a formatted object.

Parameters:
format object to use.

void ucc::string::set ( char *  text  ) 

Set string object to text of a null terminated string.

Parameters:
text string to set.

static strsize_t ucc::string::size ( string object  )  [inline, static]

Get the size of currently allocated space for string.

Parameters:
object to examine.
Returns:
size allocated for text.

Definition at line 1269 of file string.h.

strsize_t ucc::string::size ( void   ) 

Get the size of currently allocated space for string.

Returns:
size allocated for text.

static char* ucc::string::skip ( char *  text,
char *  list 
) [static]

Skip after lead characters in a null terminated string.

Parameters:
text pointer to start at.
list of characters to skip when found.
Returns:
pointer to first part of string past skipped characters.

char* ucc::string::skip ( char *  list,
strsize_t  offset = 0 
)

Skip lead characters in the string.

Parameters:
list of characters to skip when found.
offset to start of scan.
Returns:
pointer to first part of string past skipped characters.

void ucc::string::split ( strsize_t  offset  ) 

Split the string at a specific offset.

Everything after the offset is removed.

Parameters:
offset to split position in string.

void ucc::string::split ( char *  pointer  ) 

Split the string by a pointer position.

Everything after the pointer is removed.

Parameters:
pointer to split position in string.

static void ucc::string::strip ( string object,
char *  list 
) [inline, static]

Strip lead and trailing characters from the string.

Parameters:
object to strip.
list of characters to remove.

Definition at line 1340 of file string.h.

static char* ucc::string::strip ( char *  text,
char *  list 
) [static]

Skip lead and remove trailing characters from a text string.

This function will modify memory.

Parameters:
text buffer to examine.
list of characters to trim and chop.
Returns:
position in text past lead trim.

void ucc::string::strip ( char *  list  ) 

Strip lead and trailing characters from the string.

Parameters:
list of characters to remove.

static void ucc::string::swap ( string object1,
string object2 
) [static]

Swap the cstring references between two strings.

Parameters:
object1 to swap.
object2 to swap.

static double ucc::string::tod ( char *  text,
char **  pointer = ((void*)0) 
) [inline, static]

Convert text to a double value.

Parameters:
text to convert.
pointer to update with end of parsed value.
Returns:
double value of object.

Definition at line 1403 of file string.h.

static double ucc::string::tod ( string object,
char **  pointer = ((void*)0) 
) [inline, static]

Convert string to a double value.

Parameters:
object to convert.
pointer to update with end of parsed value.
Returns:
double value of object.

Definition at line 1385 of file string.h.

static char* ucc::string::token ( string object,
char **  last,
char *  list,
char *  quote = ((void*)0),
char *  end = ((void*)0) 
) [inline, static]

A thread-safe token parsing routine for strings objects.

This is related to strtok, but with safety checks for NULL values and a number of enhancements including support for quoted text that may contain token seperators within quotes. The object is modified as it is parsed.

Parameters:
object to examine for tokens.
last token position or set to NULL for start of string.
list of characters to use as token seperators.
quote pairs of characters for quoted text or NULL if not used.
end of line marker characters or NULL if not used.
Returns:
token extracted from string or NULL if no more tokens found.

Definition at line 1225 of file string.h.

Here is the call graph for this function:

static char* ucc::string::token ( char *  text,
char **  last,
char *  list,
char *  quote = ((void *) 0),
char *  end = ((void *) 0) 
) [static]

A thread-safe token parsing routine for null terminated strings.

This is related to strtok, but with safety checks for NULL values and a number of enhancements including support for quoted text that may contain token seperators within quotes. The text string is modified as it is parsed.

Parameters:
text string to examine for tokens.
last token position or set to NULL for start of string.
list of characters to use as token seperators.
quote pairs of characters for quoted text or NULL if not used.
end of line marker characters or NULL if not used.
Returns:
token extracted from string or NULL if no more tokens found.

static long ucc::string::tol ( char *  text,
char **  pointer = ((void*)0) 
) [inline, static]

Convert text to a long value.

Parameters:
text to convert.
pointer to update with end of parsed value.
Returns:
long value of object.

Definition at line 1412 of file string.h.

static long ucc::string::tol ( string object,
char **  pointer = ((void*)0) 
) [inline, static]

Convert string to a long value.

Parameters:
object to convert.
pointer to update with end of parsed value.
Returns:
long value of object.

Definition at line 1394 of file string.h.

static void ucc::string::trim ( string object,
char *  list 
) [inline, static]

Trim lead characters from the string.

Parameters:
object to trim.
list of characters to remove.

Definition at line 1324 of file string.h.

static char* ucc::string::trim ( char *  text,
char *  list 
) [static]

Return start of string after characters to trim from beginning.

This function does not modify memory.

Parameters:
text buffer to examine.
list of characters to skip from start.
Returns:
position in text past lead trim.

void ucc::string::trim ( char *  list  ) 

Trim lead characters from the string.

Parameters:
list of characters to remove.

static bool ucc::string::unquote ( string object,
char *  quote 
) [inline, static]

Unquote a quoted string.

Removes lead and trailing quote marks.

Parameters:
object to unquote.
quote pairs of characters for open and close quote.
Returns:
true if string was quoted.

Definition at line 1316 of file string.h.

static char* ucc::string::unquote ( char *  text,
char *  quote 
) [static]

Unquote a quoted null terminated string.

Returns updated string position and replaces trailing quote with null byte if quoted.

Parameters:
text to examine.
quote pairs of character for open and close quote.
Returns:
new text pointer if quoted, NULL if unchanged.

bool ucc::string::unquote ( char *  quote  ) 

Unquote a quoted string.

Removes lead and trailing quote marks.

Parameters:
quote pairs of characters for open and close quote.
Returns:
true if string was quoted.

static void ucc::string::upper ( string object  )  [inline, static]

Convert string object to upper case.

Parameters:
object to modify.

Definition at line 1300 of file string.h.

static void ucc::string::upper ( char *  text  )  [static]

Convert null terminated text to upper case.

Parameters:
text to convert.

static strsize_t ucc::string::vprintf ( string object,
char *  format,
va_list  args 
) [inline, static]

Print items into a string object.

Parameters:
object to print into.
format string of print format.
args list to print.
Returns:
number of bytes written to string.

Definition at line 1245 of file string.h.

strsize_t ucc::string::vprintf ( char *  format,
va_list  args 
)

Print items into a string object.

Parameters:
format string of print format.
args list to print.
Returns:
number of bytes written to string.

static int ucc::string::write ( FILE *  file,
string object 
) [static]

Write the string object to a file.

Parameters:
file to write to.
object to get data from.
Returns:
number of bytes written.

static int ucc::string::write ( Socket socket,
string object 
) [static]

Write the string object to a socket.

Parameters:
socket to write to.
object to get data from.
Returns:
number of bytes written.


Field Documentation

cstring* ucc::string::str [protected]

cstring instance our object references.

Definition at line 189 of file string.h.


The documentation for this class was generated from the following file:

Generated on Tue Jul 28 21:44:03 2009 for UCommon by  doxygen 1.5.9