UCommon
Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Protected Attributes
ucommon::string Class Reference

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

#include <string.h>

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

Public Types

enum  { SENSITIVE = 0x00, INSENSITIVE = 0x01 }
 This is an internal class which contains the actual string data along with some control fields. More...

Public Member Functions

int __isoc99_scanf (const char *format,...)
 Scan input items from a string object.
int __isoc99_vscanf (const char *format, va_list args)
 Scan input items from a string object.
void add (const 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) const
 Return character found at a specific position in the string.
const char * begin (void) const
 Get pointer to first character in string for iteration.
char * c_mem (void) const
 Get memory text buffer of string object.
const char * c_str (void) const
 Get character text buffer of string object.
strsize_t ccount (const char *list) const
 Count number of occurrences of characters in string.
void chop (const char *list)
 Chop trailing characters from the string.
void chop (strsize_t count=1)
 Chop trailing characters from text.
const char * chr (char character) const
 Find pointer in string where specified character appears.
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.
int collate (const char *string) const
virtual int compare (const char *string) const
 Compare the values of two string.
string copy (strsize_t offset, strsize_t size) const
 Convenience method for substring extraction.
strsize_t count (void) const
 Count all characters in the string (strlen).
void cut (strsize_t offset, strsize_t size=0)
 Cut (remove) text from string.
const char * end (void) const
 Get pointer to last character in string for iteration.
char fill (void)
 Get filler character used for field array strings.
const char * find (const char *list, strsize_t offset=0) const
 Find a character in the string.
bool full (void) const
 Test if the string's allocated space is all used up.
string get (strsize_t offset, strsize_t size=0) const
 Get a new string object as a substring of the current object.
string left (strsize_t size) const
 Convenience method for left of string.
strsize_t len (void)
 Get length of string.
void lower (void)
 Convert string to lower case.
strsize_t offset (const char *pointer) const
 Find offset of a pointer into our string buffer.
 operator bool () const
 Test if string has data.
 operator const char * () const
 Casting reference to raw text string.
bool operator! () const
 Test if string is empty.
bool operator!= (const char *text) const
 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% (unsigned long &value)
 Parse long integer value from a string.
stringoperator% (double &value)
 Parse double value from a string.
stringoperator% (const char *text)
 Parse text from a string in a scan expression.
stringoperator& (const char *text)
 Concatenate null terminated text to our object.
stringoperator&= (const char *text)
string operator() (int offset, strsize_t size) const
 Get a new substring through object expression.
const char * operator() (int offset) const
 Reference a string in the object by relative offset.
const char * operator* () const
 Reference raw text buffer by pointer operator.
bool operator*= (const char *substring)
bool operator*= (regex &expr)
stringoperator*= (strsize_t number)
 Delete a specified number of characters from start of string.
stringoperator+ (const char *text)
 Concatenate null terminated text to our object.
stringoperator++ (void)
 Delete first character from string.
stringoperator+= (const char *text)
 Concatenate text to an existing string object.
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< (const char *text) const
 Compare our object with null terminated text.
stringoperator<< (const char *text)
stringoperator<< (char code)
bool operator<= (const char *text) const
 Compare our object with null terminated text.
stringoperator= (const string &object)
 Assign our string with the cstring of another object.
stringoperator= (const char *text)
 Assign text to our existing buffer.
bool operator== (const char *text) const
 Compare our object with null terminated text.
bool operator> (const char *text) const
 Compare our object with null terminated text.
bool operator>= (const char *text) const
 Compare our object with null terminated text.
const char operator[] (int offset) const
 Reference a single character in string object by array offset.
string operator^ (const char *text)
 Transitional concat operator until abi can be changed.
stringoperator^= (const string &object)
 Create new cow instance and assign value from another string object.
stringoperator^= (const char *text)
 Create new cow instance and assign value from null terminated text.
stringoperator| (const char *text)
 Concatenate null terminated text to our object.
stringoperator|= (const char *text)
 Concatenate text to an existing string object.
void paste (strsize_t offset, const char *text, strsize_t size=0)
 Insert (paste) text into string.
strsize_t printf (const char *format,...)
 Print items into a string object.
const char * rchr (char character) const
 Find pointer in string where specified character last appears.
unsigned replace (const char *string, const char *text=((void *) 0), unsigned flags=0)
unsigned replace (regex &expr, const char *text=((void *) 0), unsigned flags=0)
virtual bool resize (strsize_t size)
 Resize and re-allocate string memory.
const char * rfind (const char *list, strsize_t offset=npos) const
 Find last occurrence of character in the string.
string right (strsize_t offset) const
 Convenience method for right of string.
void rset (const 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.
const char * rskip (const char *list, strsize_t offset=npos) const
 Skip trailing characters in the string.
void rsplit (const char *pointer)
 Split the string by a pointer position.
void rsplit (strsize_t offset)
 Split the string at a specific offset.
const char * search (const char *string, unsigned instance=0, unsigned flags=0) const
 Search for a substring in the string.
const char * search (regex &expr, unsigned instance=0, unsigned flags=0) const
void set (const char *text)
 Set string object to text of a null terminated string.
void set (strsize_t offset, const char *text, strsize_t size=0)
 Set a portion of the string object at a specified offset to a text string.
void set (const char *text, char overflow, strsize_t offset, strsize_t size=0)
 Set a text field within our string object.
strsize_t size (void) const
 Get the size of currently allocated space for string.
const char * skip (const char *list, strsize_t offset=0) const
 Skip lead characters in the string.
void split (const char *pointer)
 Split the string by a pointer position.
void split (strsize_t offset)
 Split the string at a specific offset.
 string ()
 Create a new empty string object.
 string (long value)
 Create a string from a long integer.
 string (double value)
 Create a string from a floating point.
 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, const char *format,...)
 Create a string by printf-like formating into a pre-allocated space of a specified size.
 string (const char *text)
 Create a string from null terminated text.
 string (const char *text, strsize_t size)
 Create a string from null terminated text up to a maximum specified size.
 string (const char *text, const char *end)
 Create a string for a substring.
 string (const string &existing)
 Construct a copy of a string object.
void strip (const char *list)
 Strip lead and trailing characters from the string.
void trim (const char *list)
 Trim lead characters from the string.
void trim (strsize_t count=1)
 Trim lead characters from text.
bool unquote (const char *quote)
 Unquote a quoted string.
void upper (void)
 Convert string to upper case.
strsize_t vprintf (const char *format, va_list args)
 Print items into a string object.
virtual ~string ()
 Destroy string.
- Public Member Functions inherited from ucommon::ObjectProtocol
ObjectProtocolcopy (void)
 Retain (increase retention of) object when copying.
virtual ~ObjectProtocol ()
 Required virtual destructor.

Static Public Member Functions

static int __isoc99_scanf (string &object, const char *format,...)
 Scan input items from a string object.
static int __isoc99_vscanf (string &object, const char *format, va_list args)
 Scan input items from a string object.
static char * add (char *buffer, size_t size, const char *text)
 Safely append a null terminated string into an existing string in memory.
static char * add (char *buffer, size_t size, const char *text, size_t max)
 Safely append a null terminated string into an existing string in memory.
static size_t b64decode (uint8_t *binary, const char *string, size_t size)
 Standard radix 64 decoding.
static size_t b64encode (char *string, const uint8_t *binary, size_t size, size_t width=0)
 Standard radix 64 encoding.
static int case_compare (const char *text1, const char *text2)
 Depreciated case insensitive string comparison function.
static int case_compare (const char *text1, const char *text2, size_t size)
 Depreciated case insensitive string comparison function.
static bool case_equal (const char *text1, const char *text2)
 Simple case insensitive equal test for strings.
static bool case_equal (const char *text1, const char *text2, size_t size)
 Simple case insensitive equal test for strings.
static unsigned ccount (const char *text, const char *list)
 Count instances of characters in a list in a text buffer.
static unsigned ccount (string &object, const char *list)
 Count number of occurrences of characters in string object.
static char * chop (char *text, const char *list)
 Strip trailing characters from the text string.
static void chop (string &object, const char *list)
 Chop trailing characters from the string.
static void chop (string &object, strsize_t count=1)
 Chop last character(s) from the string.
static void clear (string &object)
 Clear a string object.
static int collate (const char *text1, const char *text2)
static int compare (const char *text1, const char *text2)
 Safe string collation function.
static int compare (const char *text1, const char *text2, size_t size)
 Depreciated string comparison function.
static char * copy (const char *text, size_t offset, size_t len)
static string copy (string &object, strsize_t offset, strsize_t size)
static size_t count (const char *text)
 Safe version of strlen function.
static size_t count (string &object)
 Count all characters in the string object (strlen).
static uint16_t crc16 (uint8_t *binary, size_t size)
 ccitt 16 bit crc for binary data.
static uint32_t crc24 (uint8_t *binary, size_t size)
 24 bit crc as used in openpgp.
static void cut (char *text, size_t offset, size_t len)
static void cut (string &object, strsize_t offset, strsize_t size)
static char * dup (const char *text)
 Duplicate null terminated text into the heap.
static bool equal (const char *text1, const char *text2)
 Simple equal test for strings.
static bool equal (const char *text1, const 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 const char * find (const char *text, const char *key, const char *optional)
 Find position of substring within a string.
static char * find (char *text, const char *list)
 Find the first occurrence of a character in a text buffer.
static const char * find (string &object, const char *list)
 Find a character in the string.
static void fix (string &object)
 Fix and reset string object filler.
static unsigned hexdump (const unsigned char *binary, char *string, const char *format)
 Dump hex data to a string buffer.
static unsigned hexpack (unsigned char *binary, const char *string, const char *format)
 Pack hex data from a string buffer.
static unsigned hexsize (const char *format)
static const char * ifind (const char *text, const char *key, const char *optional)
 Find position of case insensitive substring within a string.
static char * left (const char *text, size_t size)
 Duplicate null terminated text of specific size to heap.
static string left (string &object, strsize_t size)
static strsize_t len (string &object)
 Count all characters in the string object (strlen).
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 void paste (char *text, size_t max, size_t offset, const char *data, size_t len=0)
static void paste (string &object, strsize_t offset, const char *text, strsize_t size=0)
static const char * pos (const char *text, ssize_t offset)
 Compute position in string.
static strsize_t printf (string &object, const char *format,...)
 Print formatted items into a string object.
static unsigned replace (string &object, regex &expr, const char *text, unsigned flags=0)
static unsigned replace (string &object, const char *match, const char *text, bool flag=false)
static char * rfind (char *text, const char *list)
 Find the last occurrence of a character in a text buffer.
static const char * rfind (string &object, const char *list)
 Find last character in the string.
static char * right (const char *text, size_t size)
static string right (string &object, strsize_t offset)
static char * rset (char *buffer, size_t size, const char *text)
 Set a field in a null terminated string relative to the end of text.
static char * rskip (char *text, const char *list)
 Skip before trailing characters in a null terminated string.
static const char * search (string &object, const char *substring, unsigned instance=0, unsigned flags=0)
static const char * search (string &object, regex &expr, unsigned instance=0, unsigned flags=0)
static bool search (regex &expr, const char *text, unsigned flags=0)
static size_t seek (char *text, const char *list)
 Offset until next occurrence of character in a text or length.
static char * set (char *buffer, size_t size, const char *text)
 Safely set a null terminated string buffer in memory.
static char * set (char *buffer, size_t size, const char *text, size_t max)
 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, const char *list)
 Skip after lead characters in a null terminated string.
static char * strip (char *text, const char *list)
 Skip lead and remove trailing characters from a text string.
static void strip (string &object, const char *list)
 Strip lead and trailing characters from the string.
static void swap (string &object1, string &object2)
 Swap the cstring references between two strings.
static double tod (string &object, char **pointer=((void *) 0))
 Convert string to a double value.
static double tod (const char *text, char **pointer=((void *) 0))
 Convert text to a double value.
static char * token (char *text, char **last, const char *list, const char *quote=((void *) 0), const char *end=((void *) 0))
 A thread-safe token parsing routine for null terminated strings.
static char * token (string &object, char **last, const char *list, const char *quote=((void *) 0), const char *end=((void *) 0))
 A thread-safe token parsing routine for strings objects.
static long tol (string &object, char **pointer=((void *) 0))
 Convert string to a long value.
static long tol (const char *text, char **pointer=((void *) 0))
 Convert text to a long value.
static char * trim (char *text, const char *list)
 Return start of string after characters to trim from beginning.
static void trim (string &object, const char *list)
 Trim lead characters from the string.
static void trim (string &object, strsize_t count=1)
 Trim first character(s) from the string.
static char * unquote (char *text, const char *quote)
 Unquote a quoted null terminated string.
static bool unquote (string &object, const char *quote)
 Unquote a quoted string.
static void upper (char *text)
 Convert null terminated text to upper case.
static void upper (string &object)
 Convert string object to upper case.
static strsize_t vprintf (string &object, const char *format, va_list args)
 Print items into a string object.

Static Public Attributes

static const strsize_t npos
 A constant for an invalid position value.

Protected Member Functions

virtual cstring * c_copy (void) const
 Return cstring to use in copy constructors.
virtual void cow (strsize_t size=0)
 Copy on write operation for cstring.
cstring * create (strsize_t size, char fill=0) const
 Factory create a cstring object of specified size.
bool equal (const char *string) const
 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

cstring * str
 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.nosp@m.@gnu.nosp@m.telep.nosp@m.hony.nosp@m..org

Definition at line 82 of file string.h.

Member Enumeration Documentation

anonymous enum

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

The string can be either NULL terminated or filled like a Pascal-style string, but with a user selected fill character. The cstring object is an overdraft object, as the actual string text which is of unknown size follows immediately after the class control data. This class is primarily for internal use.

Author
David Sugar dyfet.nosp@m.@gnu.nosp@m.telep.nosp@m.hony.nosp@m..org

Definition at line 97 of file string.h.

Constructor & Destructor Documentation

ucommon::string::string ( long  value)

Create a string from a long integer.

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

Create a string from a floating point.

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

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

Parameters
sizeof buffer to allocate.
ucommon::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.
ucommon::string::string ( strsize_t  size,
const 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.
ucommon::string::string ( const char *  text)

Create a string from null terminated text.

Parameters
textto use for string.
ucommon::string::string ( const 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.
ucommon::string::string ( const char *  text,
const 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.
ucommon::string::string ( const 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 ucommon::string::~string ( )
virtual

Destroy string.

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

Member Function Documentation

int ucommon::string::__isoc99_scanf ( const char *  format,
  ... 
)

Scan input items from a string object.

Parameters
formatstring of input to scan.
Returns
number of items scanned.
static int ucommon::string::__isoc99_scanf ( string object,
const 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 ucommon::string::__isoc99_vscanf ( const 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.
static int ucommon::string::__isoc99_vscanf ( string object,
const char *  format,
va_list  args 
)
inlinestatic

Scan input items from a string object.

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

Definition at line 1326 of file string.h.

void ucommon::string::add ( const char *  text)

Append null terminated text to our string buffer.

Parameters
textto append.
void ucommon::string::add ( char  character)

Append a single character to our string buffer.

Parameters
characterto append.
static char* ucommon::string::add ( char *  buffer,
size_t  size,
const 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.
static char* ucommon::string::add ( char *  buffer,
size_t  size,
const 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.
char ucommon::string::at ( int  position) const

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.

Reimplemented in ucommon::UString.

static size_t ucommon::string::b64decode ( uint8_t *  binary,
const char *  string,
size_t  size 
)
static

Standard radix 64 decoding.

Parameters
binarydata to save.
stringof encoded text.
sizeof destination buffer.
Returns
number of bytes actually decoded.
static size_t ucommon::string::b64encode ( char *  string,
const uint8_t *  binary,
size_t  size,
size_t  width = 0 
)
static

Standard radix 64 encoding.

Parameters
stringof encoded text save into.
binarydata to encode.
sizeof binary data to encode.
widthof string buffer for data if partial supported.
Returns
number of bytes encoded.
const char* ucommon::string::begin ( void  ) const

Get pointer to first character in string for iteration.

Returns
first character pointer or NULL if empty.
virtual cstring* ucommon::string::c_copy ( void  ) const
protectedvirtual

Return cstring to use in copy constructors.

Is virtual for memstring.

Returns
cstring for copy constructor.

Reimplemented in ucommon::memstring.

char* ucommon::string::c_mem ( void  ) const

Get memory text buffer of string object.

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

Get character text buffer of string object.

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

Depreciated case insensitive string comparison function.

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

Depreciated 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 ucommon::string::case_equal ( const char *  text1,
const char *  text2 
)
static

Simple case insensitive equal test for strings.

Parameters
text1to test.
text2to test.
Returns
true if equal.
static bool ucommon::string::case_equal ( const char *  text1,
const 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 ucommon::string::ccount ( const char *  list) const

Count number of occurrences of characters in string.

Parameters
listof characters to find.
Returns
count of instances of characters in string.
static unsigned ucommon::string::ccount ( const char *  text,
const 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 ucommon::string::ccount ( string object,
const char *  list 
)
inlinestatic

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 1376 of file string.h.

void ucommon::string::chop ( const char *  list)

Chop trailing characters from the string.

Parameters
listof characters to remove.
void ucommon::string::chop ( strsize_t  count = 1)
inline

Chop trailing characters from text.

Parameters
countof characters to remove.

Definition at line 491 of file string.h.

static char* ucommon::string::chop ( char *  text,
const 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.
static void ucommon::string::chop ( string object,
const char *  list 
)
inlinestatic

Chop trailing characters from the string.

Parameters
objectto chop.
listof characters to remove.

Definition at line 1446 of file string.h.

static void ucommon::string::chop ( string object,
strsize_t  count = 1 
)
inlinestatic

Chop last character(s) from the string.

Parameters
objectto chop.
countof characters to remove.

Definition at line 1454 of file string.h.

const char* ucommon::string::chr ( char  character) const

Find pointer in string where specified character appears.

Parameters
characterto find.
Returns
string pointer for character if found, NULL if not.
void ucommon::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 ucommon::string::clear ( string object)
inlinestatic

Clear a string object.

Parameters
objectto clear.

Definition at line 1367 of file string.h.

virtual int ucommon::string::compare ( const char *  string) const
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.
static int ucommon::string::compare ( const char *  text1,
const char *  text2 
)
static

Safe string collation function.

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

Depreciated 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.
string ucommon::string::copy ( strsize_t  offset,
strsize_t  size 
) const
inline

Convenience method for substring extraction.

Parameters
offsetinto string.
sizeof string to return.
Returns
string object holding substring.

Reimplemented in ucommon::UString.

Definition at line 744 of file string.h.

strsize_t ucommon::string::count ( void  ) const

Count all characters in the string (strlen).

Returns
count of characters.

Reimplemented in ucommon::UString.

static size_t ucommon::string::count ( const char *  text)
static

Safe version of strlen function.

Accepts NULL as 0 length strings.

Parameters
textstring.
Returns
length of string.
static size_t ucommon::string::count ( string object)
inlinestatic

Count all characters in the string object (strlen).

Parameters
objectto count.
Returns
count of characters.

Definition at line 1384 of file string.h.

virtual void ucommon::string::cow ( strsize_t  size = 0)
protectedvirtual

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.
static uint16_t ucommon::string::crc16 ( uint8_t *  binary,
size_t  size 
)
static

ccitt 16 bit crc for binary data.

Parameters
binarydata to sum.
sizeof binary data to sum.
Returns
16 bit crc.
static uint32_t ucommon::string::crc24 ( uint8_t *  binary,
size_t  size 
)
static

24 bit crc as used in openpgp.

Parameters
binarydata to sum.
sizeof binary data to sum.
Returns
24 bit crc of data.
cstring* ucommon::string::create ( strsize_t  size,
char  fill = 0 
) const
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.
void ucommon::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.

Reimplemented in ucommon::UString.

static char* ucommon::string::dup ( const char *  text)
static

Duplicate null terminated text into the heap.

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

Get pointer to last character in string for iteration.

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

Test if two string values are equal.

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

Simple equal test for strings.

Parameters
text1to test.
text2to test.
Returns
true if equal and case is same.
static bool ucommon::string::equal ( const char *  text1,
const 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 ucommon::string::fill ( void  )

Get filler character used for field array strings.

Returns
filler character or 0 if none.
static char* ucommon::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.
const char* ucommon::string::find ( const char *  list,
strsize_t  offset = 0 
) const

Find a character in the string.

Parameters
listof characters to search for.
offsetto start of search.
Returns
pointer to first occurrence of character.
static const char* ucommon::string::find ( const char *  text,
const char *  key,
const 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* ucommon::string::find ( char *  text,
const 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 const char* ucommon::string::find ( string object,
const char *  list 
)
inlinestatic

Find a character in the string.

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

Definition at line 1471 of file string.h.

static void ucommon::string::fix ( string object)
static

Fix and reset string object filler.

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

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

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

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.

Reimplemented in ucommon::UString.

static unsigned ucommon::string::hexdump ( const unsigned char *  binary,
char *  string,
const 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.
static unsigned ucommon::string::hexpack ( unsigned char *  binary,
const char *  string,
const 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.
static const char* ucommon::string::ifind ( const char *  text,
const char *  key,
const 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.
string ucommon::string::left ( strsize_t  size) const
inline

Convenience method for left of string.

Parameters
sizeof substring to gather.
Returns
string object holding substring.

Reimplemented in ucommon::UString.

Definition at line 727 of file string.h.

static char* ucommon::string::left ( const char *  text,
size_t  size 
)
static

Duplicate null terminated text of specific size to heap.

Parameters
textto duplicate.
sizeof text, maximum space allocated.
Returns
duplicate copy of text allocated on heap.
strsize_t ucommon::string::len ( void  )

Get length of string.

Returns
length of string.
static strsize_t ucommon::string::len ( string object)
inlinestatic

Count all characters in the string object (strlen).

Parameters
objectto count.
Returns
count of characters.

Definition at line 1344 of file string.h.

static void ucommon::string::lower ( char *  text)
static

Convert null terminated text to lower case.

Parameters
textto convert.
static void ucommon::string::lower ( string object)
inlinestatic

Convert string object to lower case.

Parameters
objectto modify.

Definition at line 1413 of file string.h.

static char* ucommon::string::mem ( string object)
inlinestatic

Get memory text buffer of string object.

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

Definition at line 1352 of file string.h.

strsize_t ucommon::string::offset ( const char *  pointer) const

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.
ucommon::string::operator bool ( ) const

Test if string has data.

Returns
true if string has data.
ucommon::string::operator const char * ( ) const
inline

Casting reference to raw text string.

Returns
null terminated text of string.

Definition at line 698 of file string.h.

bool ucommon::string::operator! ( ) const

Test if string is empty.

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

Compare our object with null terminated text.

Compare method is used.

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

Parse short integer value from a string.

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

Parse long integer value from a string.

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

Parse long integer value from a string.

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

Parse long integer value from a string.

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

Parse double value from a string.

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

Parse text from a string in a scan expression.

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

Get a new substring through object expression.

Parameters
offsetof substring.
sizeof substring or 0 if to end.
Returns
string object holding substring.

Reimplemented in ucommon::UString.

const char* ucommon::string::operator() ( int  offset) const

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.

Reimplemented in ucommon::UString.

const char* ucommon::string::operator* ( ) const
inline

Reference raw text buffer by pointer operator.

Returns
null terminated text of string.

Definition at line 705 of file string.h.

string& ucommon::string::operator*= ( strsize_t  number)

Delete a specified number of characters from start of string.

Parameters
numberof characters to delete.
string& ucommon::string::operator+ ( const char *  text)

Concatenate null terminated text to our object.

This creates a new copy-on-write instance to hold the concatenated string. This will eventually become same as new ^ operator in 6.0.

Parameters
textto concatenate.
string& ucommon::string::operator+= ( const char *  text)

Concatenate text to an existing string object.

Parameters
textto add.
Returns
our object for expression use.
string& ucommon::string::operator+= ( strsize_t  number)

Delete a specified number of characters from start of string.

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

Delete a specified number of characters from end of string.

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

Compare our object with null terminated text.

Compare method is used.

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

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& ucommon::string::operator= ( const 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.
string& ucommon::string::operator= ( const char *  text)

Assign text to our existing buffer.

This performs a set method.

Parameters
textto assign from.

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

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

Compare our object with null terminated text.

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

Compare our object with null terminated text.

Compare method is used.

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

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.
const char ucommon::string::operator[] ( int  offset) const

Reference a single character in string object by array offset.

Parameters
offsetto character.
Returns
character value at offset.

Reimplemented in ucommon::UString.

string ucommon::string::operator^ ( const char *  text)

Transitional concat operator until abi can be changed.

Parameters
textto concatenate.
string& ucommon::string::operator^= ( const string object)

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

Parameters
objectto assign from.
Returns
our object for expression use.
string& ucommon::string::operator^= ( const char *  text)

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

Parameters
textto assign from.
Returns
our object for expression use.
string& ucommon::string::operator| ( const char *  text)

Concatenate null terminated text to our object.

This creates a new copy-on-write instance to hold the concatenated string. This will eventually replace '+' when + creates a new string instance instead.

Parameters
textto concatenate.
string& ucommon::string::operator|= ( const char *  text)

Concatenate text to an existing string object.

This will use the old behavior when +/= updated.

void ucommon::string::paste ( strsize_t  offset,
const char *  text,
strsize_t  size = 0 
)

Insert (paste) text into string.

Parameters
offsetto start paste.
textto paste.
sizeof text to paste.

Reimplemented in ucommon::UString.

static const char* ucommon::string::pos ( const char *  text,
ssize_t  offset 
)
static

Compute position in string.

Parameters
textof string.
offsetfrom start, negative values from end.
Returns
pointer to string position.
strsize_t ucommon::string::printf ( const char *  format,
  ... 
)

Print items into a string object.

Parameters
formatstring of print format.
Returns
number of bytes written to string.
static strsize_t ucommon::string::printf ( string object,
const 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.
const char* ucommon::string::rchr ( char  character) const

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 ucommon::string::release ( void  )
protectedvirtual

Decrease retention of our reference counted cstring.

May be overridden for memstring which has fixed cstring object.

Implements ucommon::ObjectProtocol.

virtual bool ucommon::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 ucommon::string::retain ( void  )
protectedvirtual

Increase retention of our reference counted cstring.

May be overridden for memstring which has fixed cstring object.

Implements ucommon::ObjectProtocol.

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

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* ucommon::string::rfind ( char *  text,
const 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.
static const char* ucommon::string::rfind ( string object,
const char *  list 
)
inlinestatic

Find last character in the string.

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

Definition at line 1495 of file string.h.

string ucommon::string::right ( strsize_t  offset) const
inline

Convenience method for right of string.

Parameters
offsetof substring from right.
Returns
string object holding substring.

Reimplemented in ucommon::UString.

Definition at line 735 of file string.h.

void ucommon::string::rset ( const 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* ucommon::string::rset ( char *  buffer,
size_t  size,
const 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.
const char* ucommon::string::rskip ( const char *  list,
strsize_t  offset = npos 
) const

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* ucommon::string::rskip ( char *  text,
const 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 ucommon::string::rsplit ( const char *  pointer)

Split the string by a pointer position.

Everything before the pointer is removed.

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

Split the string at a specific offset.

Everything before the offset is removed.

Parameters
offsetto split position in string.
const char* ucommon::string::search ( const char *  string,
unsigned  instance = 0,
unsigned  flags = 0 
) const

Search for a substring in the string.

Parameters
substringto search for.
flagsfor case insensitive search.
static size_t ucommon::string::seek ( char *  text,
const char *  list 
)
static

Offset until next occurrence of character in a text or length.

Parameters
textbuffer to examine.
listof characters to search for.
Returns
offset to next occurrence or length of string.
void ucommon::string::set ( const char *  text)

Set string object to text of a null terminated string.

Parameters
textstring to set.
void ucommon::string::set ( strsize_t  offset,
const 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.
void ucommon::string::set ( const 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.
static char* ucommon::string::set ( char *  buffer,
size_t  size,
const 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 char* ucommon::string::set ( char *  buffer,
size_t  size,
const 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.
strsize_t ucommon::string::size ( void  ) const

Get the size of currently allocated space for string.

Returns
size allocated for text.
static strsize_t ucommon::string::size ( string object)
inlinestatic

Get the size of currently allocated space for string.

Parameters
objectto examine.
Returns
size allocated for text.

Definition at line 1360 of file string.h.

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

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.
static char* ucommon::string::skip ( char *  text,
const 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.
void ucommon::string::split ( const char *  pointer)

Split the string by a pointer position.

Everything after the pointer is removed.

Parameters
pointerto split position in string.
void ucommon::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 ucommon::string::strip ( const char *  list)

Strip lead and trailing characters from the string.

Parameters
listof characters to remove.
static char* ucommon::string::strip ( char *  text,
const 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 void ucommon::string::strip ( string object,
const char *  list 
)
inlinestatic

Strip lead and trailing characters from the string.

Parameters
objectto strip.
listof characters to remove.

Definition at line 1462 of file string.h.

static void ucommon::string::swap ( string object1,
string object2 
)
static

Swap the cstring references between two strings.

Parameters
object1to swap.
object2to swap.
static double ucommon::string::tod ( string object,
char **  pointer = ((void*)0) 
)
inlinestatic

Convert string to a double value.

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

Definition at line 1504 of file string.h.

static double ucommon::string::tod ( const char *  text,
char **  pointer = ((void*)0) 
)
inlinestatic

Convert text to a double value.

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

Definition at line 1522 of file string.h.

static char* ucommon::string::token ( char *  text,
char **  last,
const char *  list,
const char *  quote = ((void *) 0),
const 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 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.
static char* ucommon::string::token ( string object,
char **  last,
const char *  list,
const char *  quote = ((void*)0),
const char *  end = ((void*)0) 
)
inlinestatic

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 1316 of file string.h.

Here is the call graph for this function:

static long ucommon::string::tol ( string object,
char **  pointer = ((void*)0) 
)
inlinestatic

Convert string to a long value.

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

Definition at line 1513 of file string.h.

static long ucommon::string::tol ( const char *  text,
char **  pointer = ((void*)0) 
)
inlinestatic

Convert text to a long value.

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

Definition at line 1531 of file string.h.

void ucommon::string::trim ( const char *  list)

Trim lead characters from the string.

Parameters
listof characters to remove.
void ucommon::string::trim ( strsize_t  count = 1)
inline

Trim lead characters from text.

Parameters
countof characters to remove.

Definition at line 478 of file string.h.

static char* ucommon::string::trim ( char *  text,
const 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 void ucommon::string::trim ( string object,
const char *  list 
)
inlinestatic

Trim lead characters from the string.

Parameters
objectto trim.
listof characters to remove.

Definition at line 1430 of file string.h.

static void ucommon::string::trim ( string object,
strsize_t  count = 1 
)
inlinestatic

Trim first character(s) from the string.

Parameters
objectto chop.
countof characters to remove.

Definition at line 1438 of file string.h.

bool ucommon::string::unquote ( const 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 char* ucommon::string::unquote ( char *  text,
const 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 ucommon::string::unquote ( string object,
const char *  quote 
)
inlinestatic

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 1422 of file string.h.

static void ucommon::string::upper ( char *  text)
static

Convert null terminated text to upper case.

Parameters
textto convert.
static void ucommon::string::upper ( string object)
inlinestatic

Convert string object to upper case.

Parameters
objectto modify.

Definition at line 1406 of file string.h.

strsize_t ucommon::string::vprintf ( const 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.
static strsize_t ucommon::string::vprintf ( string object,
const char *  format,
va_list  args 
)
inlinestatic

Print items into a string object.

Parameters
objectto print into.
formatstring of print format.
argslist to print.
Returns
number of bytes written to string.

Definition at line 1336 of file string.h.

Field Documentation

cstring* ucommon::string::str
protected

cstring instance our object references.

Definition at line 221 of file string.h.


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