UCommon

string Class Reference

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

#include <string.h>

Inheritance diagram for string:
Collaboration diagram for string:

Data Structures

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

Public Member Functions

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

Static Public Member Functions

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 int case_compare (char *text1, char *text2)
 Safe case insensitive string comparison function.
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)
 Simple case insensitive equal test for strings.
static bool case_equal (char *text1, char *text2, size_t size)
 Simple case insensitive equal test for strings.
static unsigned ccount (string &object, char *list)
 Count number of occurrences of characters in string object.
static unsigned ccount (char *text, char *list)
 Count instances of characters in a list in a text buffer.
static void chop (string &object, char *list)
 Chop trailing characters from the string.
static char * chop (char *text, char *list)
 Strip trailing characters from the text string.
static void clear (string &object)
 Clear a string object.
static int compare (char *text1, char *text2)
 Safe string comparison function.
static int compare (char *text1, char *text2, size_t size)
 Safe string comparison function.
static size_t count (char *text)
 Safe version of strlen function.
static size_t count (string &object)
 Count all characters in the string object (strlen).
static char * dup (char *text)
 Duplicate null terminated text into the heap.
static bool equal (char *text1, char *text2)
 Simple equal test for strings.
static bool equal (char *text1, char *text2, size_t size)
 Simple equal test for strings.
static char * fill (char *text, size_t size, char character)
 Fill a section of memory with a fixed text character.
static char * find (char *text, char *list)
 Find the first occurrence of a character in a text buffer.
static char * find (char *text, char *key, char *optional)
 Find position of substring within a string.
static char * find (string &object, char *list)
 Find a character in the string.
static char * first (char *text, char *list)
 Get pointer to first character past character requested.
static char * first (string &object, char *list)
 Get pointer to first character past character requested.
static void fix (string &object)
 Fix and reset string object filler.
static unsigned hexdump (unsigned char *binary, char *string, char *format)
 Dump hex data to a string buffer.
static unsigned hexpack (unsigned char *binary, char *string, char *format)
 Pack hex data from a string buffer.
static unsigned hexsize (char *format)
static char * ifind (char *text, char *key, char *optional)
 Find position of case insensitive substring within a string.
static char * last (char *text, char *list)
 Get pointer to last character before character requested.
static char * last (string &object, char *list)
 Get pointer to last character past character requested.
static void lower (char *text)
 Convert null terminated text to lower case.
static void lower (string &object)
 Convert string object to lower case.
static char * mem (string &object)
 Get memory text buffer of string object.
static int static strsize_t printf (string &object, char *format,...) __PRINTF(2
 Print formatted items into a string object.
static char * rfind (char *text, char *list)
 Find the last occurrence of a character in a text buffer.
static char * rfind (string &object, char *list)
 Find last character in the 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 * rskip (char *text, char *list)
 Skip before trailing characters in a null terminated string.
static int scanf (string &object, char *format,...) __SCANF(2
 Scan input items from a string object.
static char * set (char *buffer, size_t size, char *text, size_t max)
 Safely set a null terminated string buffer in memory.
static char * set (char *buffer, size_t size, char *text)
 Safely set a null terminated string buffer in memory.
static strsize_t size (string &object)
 Get the size of currently allocated space for string.
static char * skip (char *text, char *list)
 Skip after lead characters in a null terminated string.
static char * strip (char *text, char *list)
 Skip lead and remove trailing characters from a text string.
static void strip (string &object, char *list)
 Strip lead and trailing characters from the string.
static int static strsize_t
static void 
swap (string &object1, string &object2)
 Swap the cstring references between two strings.
static double tod (char *text, char **pointer=NULL)
 Convert text to a double value.
static double tod (string &object, char **pointer=NULL)
 Convert string to a double value.
static char * token (char *text, char **last, char *list, char *quote=NULL, char *end=NULL)
 A thread-safe token parsing routine for null terminated strings.
static char * token (string &object, char **last, char *list, char *quote=NULL, char *end=NULL)
 A thread-safe token parsing routine for strings objects.
static long tol (char *text, char **pointer=NULL)
 Convert text to a long value.
static long tol (string &object, char **pointer=NULL)
 Convert string to a long value.
static char * trim (char *text, char *list)
 Return start of string after characters to trim from beginning.
static void trim (string &object, char *list)
 Trim lead characters from the string.
static char * unquote (char *text, char *quote)
 Unquote a quoted null terminated string.
static bool unquote (string &object, char *quote)
 Unquote a quoted string.
static void upper (string &object)
 Convert string object to upper case.
static void upper (char *text)
 Convert null terminated text to upper case.

Data Fields

char * format

Static Public Attributes

static strsize_t npos
 A constant for an invalid position value.

Protected Member Functions

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

Protected Attributes

cstringstr
 cstring instance our object references.

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>
Examples:

datetime.cpp, and string.cpp.

Definition at line 75 of file string.h.


Constructor & Destructor Documentation

string::string ( long  value)

Create a string from a long integer.

Parameters:
valueto convert to string.
string::string ( double  value)

Create a string from a floating point.

Parameters:
valueto convert to string.
string::string ( strsize_t  size)

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

Parameters:
sizeof buffer to allocate.
string::string ( strsize_t  size,
char  fill 
)

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

Parameters:
sizeof buffer to allocate.
fillcharacter to use.
string::string ( strsize_t  size,
char *  format,
  ... 
)

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

A typical use might be in a concat function like String x = (String)something + (String){10, "%ud", var}.

Parameters:
sizeof buffer to allocate.
formatcontrol for string.
string::string ( char *  text)

Create a string from null terminated text.

Parameters:
textto use for string.
string::string ( char *  text,
strsize_t  size 
)

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

Parameters:
textto use for string.
sizelimit of new string.
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:
textto use for string.
endof text in substring.
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:
existingstring to copy from.
virtual string::~string ( ) [virtual]

Destroy string.

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


Member Function Documentation

string::__PRINTF ( ,
 
)

Print items into a string object.

Parameters:
objectto print into.
formatstring of print format.
argslist to print.
Returns:
number of bytes written to string.
string::__SCANF ( ,
 
)

Scan input items from a string object.

Parameters:
objectto scan.
formatstring of input to scan.
argslist to scan into.
Returns:
number of items scanned.
void string::add ( char  character)

Append a single character to our string buffer.

Parameters:
characterto append.
static char* 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:
bufferto set.
sizeof buffer. Includes null byte at end of string.
textto set in buffer.
maxsize of text to append.
Returns:
pointer to text buffer.
void string::add ( char *  text)

Append null terminated text to our string buffer.

Parameters:
textto append.
static char* 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:
bufferto set.
sizeof buffer. Includes null byte at end of string.
textto set in buffer.
Returns:
pointer to text buffer.
char string::at ( int  position)

Return character found at a specific position in the string.

Parameters:
positionin string, negative values computed from end.
Returns:
character code at specified position in string.
char* string::begin ( void  )

Get pointer to first character in string for iteration.

Returns:
first character pointer or NULL if empty.
virtual cstring* string::c_copy ( void  ) [protected, virtual]

Return cstring to use in copy constructors.

Is virtual for memstring.

Returns:
cstring for copy constructor.

Reimplemented in memstring.

int int strsize_t strsize_t char* string::c_mem ( void  )

Get memory text buffer of string object.

Returns:
writable string buffer.
char* string::c_str ( void  )

Get character text buffer of string object.

Returns:
character text buffer.
static int string::case_compare ( char *  text1,
char *  text2 
) [static]

Safe case insensitive string comparison function.

Parameters:
text1to compare.
text2to compare.
Returns:
0 if equal, >0 if text1 > text2, <0 if text1 < text2.
static int string::case_compare ( char *  text1,
char *  text2,
size_t  size 
) [static]

Safe case insensitive string comparison function.

Parameters:
text1to compare.
text2to compare.
sizelimit of strings to compare.
Returns:
0 if equal, >0 if text1 > text2, <0 if text1 < text2.
static bool string::case_equal ( char *  text1,
char *  text2 
) [static]

Simple case insensitive equal test for strings.

Parameters:
text1to test.
text2to test.
Returns:
true if equal.
static bool string::case_equal ( char *  text1,
char *  text2,
size_t  size 
) [static]

Simple case insensitive equal test for strings.

Parameters:
text1to test.
text2to test.
sizelimit of strings to compare.
Returns:
true if equal.
strsize_t string::ccount ( char *  list)

Count number of occurrences of characters in string.

Parameters:
listof characters to find.
Returns:
count of instances of characters in string.
static unsigned string::ccount ( char *  text,
char *  list 
) [static]

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

Parameters:
textbuffer to examine.
listof characters to count in buffer.
Returns:
number of instances of the characters in buffer.
static unsigned string::ccount ( string object,
char *  list 
) [inline, static]

Count number of occurrences of characters in string object.

Parameters:
objectto examine.
listof characters to find.
Returns:
count of instances of characters.

Definition at line 1210 of file string.h.

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

Chop trailing characters from the string.

Parameters:
objectto chop.
listof characters to remove.

Definition at line 1257 of file string.h.

void string::chop ( char *  list)

Chop trailing characters from the string.

Parameters:
listof characters to remove.
static char* string::chop ( char *  text,
char *  list 
) [static]

Strip trailing characters from the text string.

This function will modify memory.

Parameters:
textbuffer to examine.
listof characters to chop from trailing end of string.
Returns:
pointer to text buffer.
char* string::chr ( char  character)

Find pointer in string where specified character appears.

Parameters:
characterto find.
Returns:
string pointer for character if found, NULL if not.
void string::clear ( strsize_t  offset,
strsize_t  size = 0 
)

Clear a field of a filled string with filler.

Parameters:
offsetto start of field to clear.
sizeof field to fill or 0 to fill to end of string.
static void string::clear ( string object) [inline, static]

Clear a string object.

Parameters:
objectto clear.

Definition at line 1201 of file string.h.

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

Safe string comparison function.

Parameters:
text1to compare.
text2to compare.
Returns:
0 if equal, >0 if text1 > text2, <0 if text1 < text2.
static int string::compare ( char *  text1,
char *  text2,
size_t  size 
) [static]

Safe string comparison function.

Parameters:
text1to compare.
text2to compare.
sizelimit of strings to compare.
Returns:
0 if equal, >0 if text1 > text2, <0 if text1 < text2.
virtual int string::compare ( char *  string) [protected, virtual]

Compare the values of two string.

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

Parameters:
stringto compare with.
Returns:
0 if equal, <0 if less than, 0> if greater than.
strsize_t string::count ( void  )

Count all characters in the string (strlen).

Returns:
count of characters.
static size_t string::count ( char *  text) [static]

Safe version of strlen function.

Accepts NULL as 0 length strings.

Parameters:
textstring.
Returns:
length of string.
static size_t string::count ( string object) [inline, static]

Count all characters in the string object (strlen).

Parameters:
objectto count.
Returns:
count of characters.

Definition at line 1218 of file string.h.

virtual void 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:
sizeto add to allocated space when creating new cstring.
cstring* string::create ( strsize_t  size,
char  fill = 0 
) [protected]

Factory create a cstring object of specified size.

Parameters:
sizeof allocated space for string buffer.
fillcharacter to use or 0 if null.
Returns:
new cstring object.

Reimplemented in memstring.

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

Cut (remove) text from string.

Parameters:
offsetto start of text field to remove.
sizeof text field to remove or 0 to remove to end of string.
static char* string::dup ( char *  text) [static]

Duplicate null terminated text into the heap.

Parameters:
textto duplicate.
Returns:
duplicate copy of text allocated from heap.
char* string::end ( void  )

Get pointer to last character in string for iteration.

Returns:
last character pointer or NULL if empty.
bool string::equal ( char *  string) [protected]

Test if two string values are equal.

Parameters:
stringto compare with.
Returns:
true if equal.
static bool string::equal ( char *  text1,
char *  text2 
) [static]

Simple equal test for strings.

Parameters:
text1to test.
text2to test.
Returns:
true if equal and case is same.
static bool string::equal ( char *  text1,
char *  text2,
size_t  size 
) [static]

Simple equal test for strings.

Parameters:
text1to test.
text2to test.
sizelimit of strings to compare.
Returns:
true if equal and case is same.
char string::fill ( void  )

Get filler character used for field array strings.

Returns:
filler character or 0 if none.
Examples:
string.cpp.
static char* 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:
textbuffer to fill.
sizeof text buffer with null terminated byte.
characterto fill with.
Returns:
pointer to text buffer.
static char* string::find ( string object,
char *  list 
) [inline, static]

Find a character in the string.

Parameters:
objectto search.
listof characters to search for.
Returns:
pointer to first occurrence of character.

Definition at line 1274 of file string.h.

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

Find a character in the string.

Parameters:
listof characters to search for.
offsetto start of search.
Returns:
pointer to first occurrence of character.
static char* string::find ( char *  text,
char *  key,
char *  optional 
) [static]

Find position of substring within a string.

Parameters:
textto search in.
keystring to locate.
optionalseparator chars if formatted as list of keys.
Returns:
substring position if found, or NULL.
static char* string::find ( char *  text,
char *  list 
) [static]

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

Parameters:
textbuffer to examine.
listof characters to search for.
Returns:
pointer to first instance found or NULL.
static char* string::first ( string object,
char *  list 
) [inline, static]

Get pointer to first character past character requested.

Parameters:
objectto examine.
listof characters.
Returns:
first character pointer past list.

Definition at line 1292 of file string.h.

char* string::first ( char *  list)

Find first occurrence of a character in the string.

Parameters:
listof characters to search for.
Returns:
pointer to first occurrence from list or NULL.
static char* string::first ( char *  text,
char *  list 
) [static]

Get pointer to first character past character requested.

Parameters:
textbuffer to examine.
listof characters.
Returns:
first character pointer past list.
static void string::fix ( string object) [static]

Fix and reset string object filler.

Parameters:
objectto fix.
bool string::full ( void  )

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

Returns:
true if no more room for append.
string string::get ( strsize_t  offset,
strsize_t  size = 0 
)

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

Parameters:
offsetof substring.
sizeof substring or 0 if to end.
Returns:
string object holding substring.
static unsigned string::hexdump ( unsigned char *  binary,
char *  string,
char *  format 
) [static]

Dump hex data to a string buffer.

Parameters:
binarymemory to dump.
stringto save into.
formatstring to convert with.
Returns:
number of bytes processed.
Examples:
string.cpp.
static unsigned string::hexpack ( unsigned char *  binary,
char *  string,
char *  format 
) [static]

Pack hex data from a string buffer.

Parameters:
binarymemory to pack.
stringto save into.
formatstring to convert with.
Returns:
number of bytes processed.
Examples:
string.cpp.
static char* string::ifind ( char *  text,
char *  key,
char *  optional 
) [static]

Find position of case insensitive substring within a string.

Parameters:
textto search in.
keystring to locate.
optionalseparator chars if formatted as list of keys.
Returns:
substring position if found, or NULL.
static char* string::last ( string object,
char *  list 
) [inline, static]

Get pointer to last character past character requested.

Parameters:
objectto examine.
listof characters.
Returns:
last character pointer before list.

Definition at line 1301 of file string.h.

char* string::last ( char *  list)

Find last occurrence of a character in the string.

Parameters:
listof characters to search for.
Returns:
pointer to last occurrence from list or NULL.
static char* string::last ( char *  text,
char *  list 
) [static]

Get pointer to last character before character requested.

Parameters:
textbuffer to examine.
listof characters.
Returns:
last character pointer past list.
strsize_t string::len ( void  )

Get length of string.

Returns:
length of string.
Examples:
string.cpp.
static void string::lower ( string object) [inline, static]

Convert string object to lower case.

Parameters:
objectto modify.

Definition at line 1232 of file string.h.

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

Convert null terminated text to lower case.

Parameters:
textto convert.
static char* string::mem ( string object) [inline, static]

Get memory text buffer of string object.

Parameters:
objectto get string buffer from.
Returns:
writable string buffer.

Definition at line 1186 of file string.h.

strsize_t 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:
pointerinto our object's string buffer.
string::operator bool ( )

Test if string has data.

Returns:
true if string has data.
string::operator char * ( ) [inline]

Casting reference to raw text string.

Returns:
null terminated text of string.

Definition at line 624 of file string.h.

bool string::operator! ( )

Test if string is empty.

Returns:
true if string is empty.
bool string::operator!= ( char *  text)

Compare our object with null terminated text.

Compare method is used.

Parameters:
textto compare with.
Returns:
true if we are not equal.
string& string::operator% ( short &  value)

Parse short integer value from a string.

Parameters:
valueto store.
Returns:
object in expression.
string& string::operator% ( unsigned short &  value)

Parse long integer value from a string.

Parameters:
valueto store.
Returns:
object in expression.
string& string::operator% ( long &  value)

Parse long integer value from a string.

Parameters:
valueto store.
Returns:
object in expression.
string& string::operator% ( unsigned long &  value)

Parse long integer value from a string.

Parameters:
valueto store.
Returns:
object in expression.
string& string::operator% ( double &  value)

Parse double value from a string.

Parameters:
valueto store.
Returns:
object in expression.
string& string::operator% ( char *  text)

Parse text from a string in a scan expression.

Parameters:
textto scan and bypass.
Returns:
object in expression.
string& 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:
textto concatenate.
string string::operator() ( int  offset,
strsize_t  size 
)

Get a new substring through object expression.

Parameters:
offsetof substring.
sizeof substring or 0 if to end.
Returns:
string object holding substring.
char* 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:
offsetto string position.
Returns:
pointer to string data or NULL if invalid offset.
char* string::operator* ( ) [inline]

Reference raw text buffer by pointer operator.

Returns:
null terminated text of string.

Definition at line 631 of file string.h.

string& 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:
textto concatenate.
string& string::operator+= ( strsize_t  number)

Delete a specified number of characters from start of string.

Parameters:
numberof characters to delete.
string& string::operator-= ( strsize_t  number)

Delete a specified number of characters from end of string.

Parameters:
numberof characters to delete.
bool string::operator< ( char *  text)

Compare our object with null terminated text.

Compare method is used.

Parameters:
textto compare with.
Returns:
true if we are less than text.
bool string::operator<= ( char *  text)

Compare our object with null terminated text.

Compare method is used.

Parameters:
textto compare with.
Returns:
true if we are less than or equal to text.
string& string::operator= ( char *  text)

Assign text to our existing buffer.

This performs a set method.

Parameters:
textto assign from.

Reimplemented in memstring, and stringbuf< S >.

string& 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:
objectto assign from.

Reimplemented in memstring, and stringbuf< S >.

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

Compare our object with null terminated text.

Parameters:
textto compare with.
Returns:
true if we are equal.
bool string::operator> ( char *  text)

Compare our object with null terminated text.

Compare method is used.

Parameters:
textto compare with.
Returns:
true if we are greater than text.
bool string::operator>= ( char *  text)

Compare our object with null terminated text.

Compare method is used.

Parameters:
textto compare with.
Returns:
true if we are greater than or equal to text.
char string::operator[] ( int  offset)

Reference a single character in string object by array offset.

Parameters:
offsetto character.
Returns:
character value at offset.
string& string::operator^= ( char *  text)

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

Parameters:
textto assign from.
Returns:
our object for expression use.
string& string::operator^= ( string object)

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

Parameters:
objectto assign from.
Returns:
our object for expression use.
static int static strsize_t string::printf ( string object,
char *  format,
  ... 
) [static]

Print formatted items into a string object.

Parameters:
objectto print into.
formatstring to print with.
Returns:
number of bytes written into object.
int int strsize_t string::printf ( char *  format,
  ... 
)

Print items into a string object.

Parameters:
formatstring of print format.
Returns:
number of bytes written to string.
char* string::rchr ( char  character)

Find pointer in string where specified character last appears.

Parameters:
characterto find.
Returns:
string pointer for last occurrence of character if found, NULL if not.
virtual void string::release ( void  ) [protected, virtual]

Decrease retention of our reference counted cstring.

May be overridden for memstring which has fixed cstring object.

Reimplemented from Object.

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

Resize and re-allocate string memory.

Parameters:
sizeto allocate for string.
Returns:
true if re-allocated. False in derived memstring.
virtual void string::retain ( void  ) [protected, virtual]

Increase retention of our reference counted cstring.

May be overridden for memstring which has fixed cstring object.

Reimplemented from Object.

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

Find last occurrence of character in the string.

Parameters:
listof characters to search for.
offsetto start of search. Default is end of string.
Returns:
pointer to last occurrence of character.
static char* string::rfind ( string object,
char *  list 
) [inline, static]

Find last character in the string.

Parameters:
objectto search.
listof characters to search for.
Returns:
pointer to last occurrence of character.

Definition at line 1283 of file string.h.

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

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

Parameters:
textbuffer to examine.
listof characters to search for.
Returns:
pointer to last instance found or NULL.
void 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:
textto set.
overflowcharacter to use as filler if text is too short.
offsetfrom end of object string buffer to set text at.
sizeof part of buffer to set with text and overflow.
static char* 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:
bufferto modify.
sizeof field to set.
textto replace end of string with.
Returns:
pointer to text buffer.
char* string::rskip ( char *  list,
strsize_t  offset = npos 
)

Skip trailing characters in the string.

This searches the string in reverse order.

Parameters:
listof characters to skip when found.
offsetto start of scan. Default is end of string.
Returns:
pointer to first part of string before skipped characters.
static char* string::rskip ( char *  text,
char *  list 
) [static]

Skip before trailing characters in a null terminated string.

Parameters:
textpointer to start at.
listof characters to skip when found.
Returns:
pointer to last part of string past skipped characters.
void string::rsplit ( char *  pointer)

Split the string by a pointer position.

Everything before the pointer is removed.

Parameters:
pointerto split position in string.
void string::rsplit ( strsize_t  offset)

Split the string at a specific offset.

Everything before the offset is removed.

Parameters:
offsetto split position in string.
static int string::scanf ( string object,
char *  format,
  ... 
) [static]

Scan input items from a string object.

Parameters:
objectto scan from.
formatstring of input to scan.
Returns:
number of items scanned.
int string::scanf ( char *  format,
  ... 
)

Scan input items from a string object.

Parameters:
formatstring of input to scan.
Returns:
number of items scanned.
static char* 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:
bufferto set.
sizeof buffer. Includes null byte at end of string.
textto set in buffer.
maxsize of text to set.
Returns:
pointer to text buffer.
void string::set ( char *  text)

Set string object to text of a null terminated string.

Parameters:
textstring to set.
Examples:
string.cpp.
void string::set ( char *  text,
char  overflow,
strsize_t  offset,
strsize_t  size = 0 
)

Set a text field within our string object.

Parameters:
textto set.
overflowcharacter to use as filler if text is too short.
offsetin object string buffer to set text at.
sizeof part of buffer to set with text and overflow.
void 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:
offsetin object string buffer.
textto set at offset.
sizeof text area to set or 0 until end of text.
static char* 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:
bufferto set.
sizeof buffer. Includes null byte at end of string.
textto set in buffer.
Returns:
pointer to text buffer.
static strsize_t string::size ( string object) [inline, static]

Get the size of currently allocated space for string.

Parameters:
objectto examine.
Returns:
size allocated for text.

Definition at line 1194 of file string.h.

strsize_t string::size ( void  )

Get the size of currently allocated space for string.

Returns:
size allocated for text.
static char* string::skip ( char *  text,
char *  list 
) [static]

Skip after lead characters in a null terminated string.

Parameters:
textpointer to start at.
listof characters to skip when found.
Returns:
pointer to first part of string past skipped characters.
char* string::skip ( char *  list,
strsize_t  offset = 0 
)

Skip lead characters in the string.

Parameters:
listof characters to skip when found.
offsetto start of scan.
Returns:
pointer to first part of string past skipped characters.
void string::split ( strsize_t  offset)

Split the string at a specific offset.

Everything after the offset is removed.

Parameters:
offsetto split position in string.
void string::split ( char *  pointer)

Split the string by a pointer position.

Everything after the pointer is removed.

Parameters:
pointerto split position in string.
void string::strip ( char *  list)

Strip lead and trailing characters from the string.

Parameters:
listof characters to remove.
Examples:
string.cpp.
static void string::strip ( string object,
char *  list 
) [inline, static]

Strip lead and trailing characters from the string.

Parameters:
objectto strip.
listof characters to remove.

Definition at line 1265 of file string.h.

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

Skip lead and remove trailing characters from a text string.

This function will modify memory.

Parameters:
textbuffer to examine.
listof characters to trim and chop.
Returns:
position in text past lead trim.
static int static strsize_t static void string::swap ( string object1,
string object2 
) [static]

Swap the cstring references between two strings.

Parameters:
object1to swap.
object2to swap.
static double string::tod ( char *  text,
char **  pointer = NULL 
) [inline, static]

Convert text to a double value.

Parameters:
textto convert.
pointerto update with end of parsed value.
Returns:
double value of object.

Definition at line 1328 of file string.h.

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

Convert string to a double value.

Parameters:
objectto convert.
pointerto update with end of parsed value.
Returns:
double value of object.

Definition at line 1310 of file string.h.

static char* string::token ( string object,
char **  last,
char *  list,
char *  quote = NULL,
char *  end = NULL 
) [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 separators within quotes. The object is modified as it is parsed.

Parameters:
objectto examine for tokens.
lasttoken position or set to NULL for start of string.
listof characters to use as token separators.
quotepairs of characters for quoted text or NULL if not used.
endof line marker characters or NULL if not used.
Returns:
token extracted from string or NULL if no more tokens found.

Definition at line 1150 of file string.h.

Here is the call graph for this function:

static char* string::token ( char *  text,
char **  last,
char *  list,
char *  quote = NULL,
char *  end = NULL 
) [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 separators within quotes. The text string is modified as it is parsed.

Parameters:
textstring to examine for tokens.
lasttoken position or set to NULL for start of string.
listof characters to use as token separators.
quotepairs of characters for quoted text or NULL if not used.
endof line marker characters or NULL if not used.
Returns:
token extracted from string or NULL if no more tokens found.
Examples:
string.cpp.
static long string::tol ( char *  text,
char **  pointer = NULL 
) [inline, static]

Convert text to a long value.

Parameters:
textto convert.
pointerto update with end of parsed value.
Returns:
long value of object.

Definition at line 1337 of file string.h.

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

Convert string to a long value.

Parameters:
objectto convert.
pointerto update with end of parsed value.
Returns:
long value of object.

Definition at line 1319 of file string.h.

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

Trim lead characters from the string.

Parameters:
objectto trim.
listof characters to remove.

Definition at line 1249 of file string.h.

void string::trim ( char *  list)

Trim lead characters from the string.

Parameters:
listof characters to remove.
static char* string::trim ( char *  text,
char *  list 
) [static]

Return start of string after characters to trim from beginning.

This function does not modify memory.

Parameters:
textbuffer to examine.
listof characters to skip from start.
Returns:
position in text past lead trim.
static char* 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:
textto examine.
quotepairs of character for open and close quote.
Returns:
new text pointer if quoted, NULL if unchanged.
static bool string::unquote ( string object,
char *  quote 
) [inline, static]

Unquote a quoted string.

Removes lead and trailing quote marks.

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

Definition at line 1241 of file string.h.

bool string::unquote ( char *  quote)

Unquote a quoted string.

Removes lead and trailing quote marks.

Parameters:
quotepairs of characters for open and close quote.
Returns:
true if string was quoted.
static void string::upper ( char *  text) [static]

Convert null terminated text to upper case.

Parameters:
textto convert.
static void string::upper ( string object) [inline, static]

Convert string object to upper case.

Parameters:
objectto modify.

Definition at line 1225 of file string.h.

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

Print items into a string object.

Parameters:
formatstring of print format.
argslist to print.
Returns:
number of bytes written to string.
int int string::vscanf ( char *  format,
va_list  args 
)

Scan input items from a string object.

Parameters:
formatstring of input to scan.
argslist to scan into.
Returns:
number of items scanned.

Field Documentation

cstring* string::str [protected]

cstring instance our object references.

Definition at line 178 of file string.h.


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