String Class Reference

A C-style string handling class. More...

#include <yateclass.h>

Inheritance diagram for String:
GenObject ClientAccountList ClientSound Configuration DataFormat JabberID JGCrypto JGRtpCandidate JGSentStanza JGStreamHost MessageHandler NamedList NamedString Regexp SignallingCircuitRange SIPDialog UIFactory UIWidget URI

List of all members.

Public Member Functions

 String ()
 String (const char *value, int len=-1)
 String (char value, unsigned int repeat=1)
 String (int value)
 String (unsigned int value)
 String (bool value)
 String (const String &value)
 String (const String *value)
virtual ~String ()
virtual void * getObject (const String &name) const
const char * c_str () const
const char * safe () const
const char * safe (const char *defStr) const
unsigned int length () const
bool null () const
int lenUtf8 (unsigned int maxSeq=4, bool overlong=false) const
int fixUtf8 (const char *replace=0, unsigned int maxSeq=4, bool overlong=false)
unsigned int hash () const
void clear ()
char at (int index) const
String substr (int offs, int len=-1) const
StringtrimBlanks ()
StringtrimSpaces ()
virtual const StringtoString () const
int toInteger (int defvalue=0, int base=0) const
int toInteger (const TokenDict *tokens, int defvalue=0, int base=0) const
double toDouble (double defvalue=0.0) const
bool toBoolean (bool defvalue=false) const
bool isBoolean () const
StringtoUpper ()
StringtoLower ()
char operator[] (signed int index) const
char operator[] (unsigned int index) const
 operator const char * () const
Stringassign (const char *value, int len=-1)
Stringassign (char value, unsigned int repeat=1)
Stringhexify (void *data, unsigned int len, char sep=0, bool upCase=false)
Stringoperator= (const String &value)
Stringoperator= (const String *value)
Stringoperator= (const char *value)
Stringoperator= (char value)
Stringoperator= (int value)
Stringoperator= (unsigned int value)
Stringoperator= (bool value)
Stringoperator+= (const char *value)
Stringoperator+= (char value)
Stringoperator+= (int value)
Stringoperator+= (unsigned int value)
Stringoperator+= (bool value)
bool operator== (const char *value) const
bool operator!= (const char *value) const
bool operator== (const String &value) const
bool operator!= (const String &value) const
bool operator&= (const char *value) const
bool operator|= (const char *value) const
Stringoperator<< (const char *value)
Stringoperator<< (char value)
Stringoperator<< (int value)
Stringoperator<< (unsigned int value)
Stringoperator<< (bool value)
Stringoperator>> (const char *skip)
Stringoperator>> (char &store)
Stringoperator>> (int &store)
Stringoperator>> (unsigned int &store)
Stringoperator>> (bool &store)
Stringappend (const char *value, const char *separator=0, bool force=false)
Stringappend (const ObjList *list, const char *separator=0, bool force=false)
Stringappend (const ObjList &list, const char *separator=0, bool force=false)
Stringappend (double value, unsigned int decimals=3)
int find (char what, unsigned int offs=0) const
int find (const char *what, unsigned int offs=0) const
int rfind (char what) const
bool startsWith (const char *what, bool wordBreak=false, bool caseInsensitive=false) const
bool endsWith (const char *what, bool wordBreak=false, bool caseInsensitive=false) const
bool startSkip (const char *what, bool wordBreak=true, bool caseInsensitive=false)
virtual bool matches (const String &value) const
bool matches (Regexp &rexp)
int matchOffset (int index=0) const
int matchLength (int index=0) const
String matchString (int index=0) const
String replaceMatches (const String &templ) const
int matchCount () const
ObjListsplit (char separator, bool emptyOK=true) const
String msgEscape (char extraEsc=0) const
String msgUnescape (int *errptr=0, char extraEsc=0) const
String sqlEscape (char extraEsc=0) const
String uriEscape (char extraEsc=0, const char *noEsc=0) const
String uriUnescape (int *errptr=0) const

Static Public Member Functions

static const Stringempty ()
static const char * boolText (bool value)
static int lenUtf8 (const char *value, unsigned int maxSeq=4, bool overlong=false)
static unsigned int hash (const char *value)
static String msgEscape (const char *str, char extraEsc=0)
static String msgUnescape (const char *str, int *errptr=0, char extraEsc=0)
static String sqlEscape (const char *str, char extraEsc=0)
static String uriEscape (const char *str, char extraEsc=0, const char *noEsc=0)
static String uriUnescape (const char *str, int *errptr=0)

Protected Member Functions

virtual void changed ()

Detailed Description

A C-style string handling class.

A simple string handling class for C style (one byte) strings. For simplicity and read speed no copy-on-write is performed. Strings have hash capabilities and comparations are using the hash for fast inequality check.


Constructor & Destructor Documentation

String (  ) 

Creates a new, empty string.

String ( const char *  value,
int  len = -1 
)

Creates a new initialized string.

Parameters:
value Initial value of the string
len Length of the data to copy, -1 for full string
String ( char  value,
unsigned int  repeat = 1 
) [explicit]

Creates a new initialized string.

Parameters:
value Character to fill the string
repeat How many copies of the character to use
String ( int  value  )  [explicit]

Creates a new initialized string from an integer.

Parameters:
value Value to convert to string
String ( unsigned int  value  )  [explicit]

Creates a new initialized string from an unsigned int.

Parameters:
value Value to convert to string
String ( bool  value  )  [explicit]

Creates a new initialized string from a boolean.

Parameters:
value Value to convert to string
String ( const String value  ) 

Copy constructor.

Parameters:
value Initial value of the string
String ( const String value  ) 

Constructor from String pointer.

Parameters:
value Initial value of the string
virtual ~String (  )  [virtual]

Destroys the string, disposes the memory.


Member Function Documentation

String& append ( double  value,
unsigned int  decimals = 3 
)

Explicit double append

Parameters:
value Value to append
decimals Number of decimals
String& append ( const ObjList list,
const char *  separator = 0,
bool  force = false 
) [inline]

List members appending with a separator

Parameters:
list Reference of ObjList whose GenObject::toString() of the items will be appended
separator Separator to insert before each item in list
force True to allow appending empty strings

References String::append().

Referenced by String::append().

String& append ( const ObjList list,
const char *  separator = 0,
bool  force = false 
)

List members appending with a separator

Parameters:
list Pointer to ObjList whose GenObject::toString() of the items will be appended
separator Separator to insert before each item in list
force True to allow appending empty strings
String& append ( const char *  value,
const char *  separator = 0,
bool  force = false 
)

Conditional appending with a separator

Parameters:
value String to append
separator Separator to insert before the value
force True to allow appending empty strings

Referenced by ISDNQ931Message::append().

String& assign ( char  value,
unsigned int  repeat = 1 
)

Assigns a new value by filling with a repeated character

Parameters:
value Character to fill the string
repeat How many copies of the character to use
Returns:
Reference to the String
String& assign ( const char *  value,
int  len = -1 
)

Assigns a new value to the string from a character block.

Parameters:
value New value of the string
len Length of the data to copy, -1 for full string
Returns:
Reference to the String
char at ( int  index  )  const

Extract the caracter at a given index

Parameters:
index Index of character in string
Returns:
Character at given index or 0 if out of range
static const char* boolText ( bool  value  )  [inline, static]

A standard text representation of boolean values

Parameters:
value Boolean value to convert
Returns:
Pointer to a text representation of the value

Referenced by SDPMedia::rfc2833().

const char* c_str (  )  const [inline]
virtual void changed (  )  [protected, virtual]

Called whenever the value changed (except in constructors).

Reimplemented in Regexp, NamedPointer, URI, and DataFormat.

void clear (  ) 

Clear the string and free the memory

Reimplemented in SignallingCircuitRange.

static const String& empty (  )  [static]

A static null String

Returns:
Reference to a static empty String

Reimplemented in NamedList.

Referenced by ClientContact::buildContactId(), SIPTransaction::getMethod(), and SIPTransaction::getURI().

bool endsWith ( const char *  what,
bool  wordBreak = false,
bool  caseInsensitive = false 
) const

Checks if the string ends with a substring

Parameters:
what Substring to search for
wordBreak Check if a word boundary precedes the substring
caseInsensitive Compare case-insensitive if set
Returns:
True if the substring occurs at the end of the string
int find ( const char *  what,
unsigned int  offs = 0 
) const

Locate the first instance of a substring in the string

Parameters:
what Substring to search for
offs Offset in string to start searching from
Returns:
Offset of substring or -1 if not found
int find ( char  what,
unsigned int  offs = 0 
) const

Locate the first instance of a character in the string

Parameters:
what Character to search for
offs Offset in string to start searching from
Returns:
Offset of character or -1 if not found

Referenced by ClientContact::splitContactId().

int fixUtf8 ( const char *  replace = 0,
unsigned int  maxSeq = 4,
bool  overlong = false 
)

Fix an UTF-8 encoded string by replacing invalid sequences

Parameters:
replace String to replace invalid sequences, use U+FFFD if null
maxSeq Maximum accepted UTF-8 sequence length
overlong Accept overlong UTF-8 sequences (dangerous!)
Returns:
Count of invalid UTF-8 sequences that were replaced
virtual void* getObject ( const String name  )  const [virtual]

Get a pointer to a derived class given that class name

Parameters:
name Name of the class we are asking for
Returns:
Pointer to the requested class or NULL if this object doesn't implement it

Reimplemented from GenObject.

Reimplemented in NamedString, NamedPointer, NamedList, MimeHeaderLine, MimeAuthLine, and Message.

static unsigned int hash ( const char *  value  )  [static]

Get the hash of an arbitrary string.

Parameters:
value C string to hash
Returns:
The hash of the string.
unsigned int hash (  )  const

Get the hash of the contained string.

Returns:
The hash of the string.

Referenced by HashList::getHashList().

String& hexify ( void *  data,
unsigned int  len,
char  sep = 0,
bool  upCase = false 
)

Build a hexadecimal representation of a buffer of data

Parameters:
data Pointer to data to dump
len Length of the data buffer
sep Separator character to use between octets
upCase Set to true to use upper case characters in hexa
Returns:
Reference to the String
bool isBoolean (  )  const

Check if the string can be converted to a boolean value.

Returns:
True if the string is a valid boolean.
unsigned int length (  )  const [inline]

Get the length of the stored string.

Returns:
The length of the stored string, zero for NULL.

Reimplemented in NamedList.

Referenced by IAXIEList::appendString(), XMLElement::getAttribute(), SHA1::update(), MD5::update(), and Stream::writeData().

int lenUtf8 ( unsigned int  maxSeq = 4,
bool  overlong = false 
) const [inline]

Get the number of characters in the string assuming UTF-8 encoding

Parameters:
maxSeq Maximum accepted UTF-8 sequence length
overlong Accept overlong UTF-8 sequences (dangerous!)
Returns:
Count of Unicode characters, -1 if not valid UTF-8

References String::lenUtf8().

Referenced by String::lenUtf8().

static int lenUtf8 ( const char *  value,
unsigned int  maxSeq = 4,
bool  overlong = false 
) [static]

Get the number of characters in a string assuming UTF-8 encoding

Parameters:
value C string to compute Unicode length
maxSeq Maximum accepted UTF-8 sequence length
overlong Accept overlong UTF-8 sequences (dangerous!)
Returns:
Count of Unicode characters, -1 if not valid UTF-8
int matchCount (  )  const

Get the total number of submatches from the last match, 0 if no match

Returns:
Number of matching subexpressions
bool matches ( Regexp rexp  ) 

Checks if matches a regular expression and fill the match substrings

Parameters:
rexp Regular expression to check for match
Returns:
True if matches, false otherwise
virtual bool matches ( const String value  )  const [inline, virtual]

Checks if matches another string

Parameters:
value String to check for match
Returns:
True if matches, false otherwise

Reimplemented in Regexp.

int matchLength ( int  index = 0  )  const

Get the length of the last match

Parameters:
index Index of the submatch to return, 0 for full match
Returns:
Length of the last match, 0 if no match or out of range
int matchOffset ( int  index = 0  )  const

Get the offset of the last match

Parameters:
index Index of the submatch to return, 0 for full match
Returns:
Offset of the last match, -1 if no match or not in range
String matchString ( int  index = 0  )  const [inline]

Get a copy of a matched (sub)string

Parameters:
index Index of the submatch to return, 0 for full match
Returns:
Copy of the matched substring
String msgEscape ( char  extraEsc = 0  )  const [inline]

Create an escaped string suitable for use in messages

Parameters:
extraEsc Character to escape other than the default ones
Returns:
The string with special characters escaped

References TelEngine::c_str(), and String::msgEscape().

Referenced by String::msgEscape().

static String msgEscape ( const char *  str,
char  extraEsc = 0 
) [static]

Create an escaped string suitable for use in messages

Parameters:
str String to convert to escaped format
extraEsc Character to escape other than the default ones
Returns:
The string with special characters escaped
String msgUnescape ( int *  errptr = 0,
char  extraEsc = 0 
) const [inline]

Decode an escaped string back to its raw form

Parameters:
errptr Pointer to an integer to receive the place of 1st error
extraEsc Character to unescape other than the default ones
Returns:
The string with special characters unescaped

References TelEngine::c_str(), and String::msgUnescape().

Referenced by String::msgUnescape().

static String msgUnescape ( const char *  str,
int *  errptr = 0,
char  extraEsc = 0 
) [static]

Decode an escaped string back to its raw form

Parameters:
str String to convert to unescaped format
errptr Pointer to an integer to receive the place of 1st error
extraEsc Character to unescape other than the default ones
Returns:
The string with special characters unescaped
bool null (  )  const [inline]

Checks if the string holds a NULL pointer.

Returns:
True if the string holds NULL, false otherwise.

Referenced by JabberID::match(), and TelEngine::null().

operator const char * (  )  const [inline]

Conversion to "const char *" operator.

Returns:
Pointer to the internally stored string
bool operator!= ( const String value  )  const

Fast inequality operator.

Reimplemented in JabberID.

bool operator!= ( const char *  value  )  const

Inequality operator.

bool operator&= ( const char *  value  )  const

Case-insensitive equality operator.

String& operator+= ( bool  value  )  [inline]

Appending operator for booleans.

References String::operator+=().

Referenced by String::operator+=().

String& operator+= ( unsigned int  value  ) 

Appending operator for unsigned integers.

String& operator+= ( int  value  ) 

Appending operator for integers.

String& operator+= ( char  value  ) 

Appending operator for single characters.

String& operator+= ( const char *  value  ) 

Appending operator for strings.

See also:
TelEngine::strcat
String& operator<< ( bool  value  )  [inline]

Stream style appending operator for booleans

String& operator<< ( unsigned int  value  )  [inline]

Stream style appending operator for unsigned integers

String& operator<< ( int  value  )  [inline]

Stream style appending operator for integers

String& operator<< ( char  value  )  [inline]

Stream style appending operator for single characters

String& operator<< ( const char *  value  )  [inline]

Stream style appending operator for C strings

String& operator= ( bool  value  )  [inline]

Assignment operator for booleans.

References String::operator=().

Referenced by String::operator=().

String& operator= ( unsigned int  value  ) 

Assignment operator for unsigned integers.

String& operator= ( int  value  ) 

Assignment operator for integers.

String& operator= ( char  value  ) 

Assignment operator for single characters.

String& operator= ( const char *  value  ) 

Assignment from char* operator.

See also:
TelEngine::strcpy

Reimplemented in Regexp, NamedString, NamedPointer, URI, MimeHeaderLine, and Message.

String& operator= ( const String value  )  [inline]

Assignment from String* operator.

See also:
TelEngine::strcpy

References String::c_str(), and String::operator=().

Referenced by String::operator=().

String& operator= ( const String value  )  [inline]
bool operator== ( const String value  )  const

Fast equality operator.

Reimplemented in JabberID.

bool operator== ( const char *  value  )  const

Equality operator.

String& operator>> ( bool &  store  ) 

Stream style extraction operator for booleans

String& operator>> ( unsigned int &  store  ) 

Stream style extraction operator for unsigned integers

String& operator>> ( int &  store  ) 

Stream style extraction operator for integers

String& operator>> ( char &  store  ) 

Stream style extraction operator for single characters

String& operator>> ( const char *  skip  ) 

Stream style substring skipping operator. It eats all characters up to and including the skip string

char operator[] ( unsigned int  index  )  const [inline]

Indexing operator with unsigned int

Parameters:
index Index of character in string
Returns:
Character at given index or 0 if out of range
char operator[] ( signed int  index  )  const [inline]

Indexing operator with signed int

Parameters:
index Index of character in string
Returns:
Character at given index or 0 if out of range
bool operator|= ( const char *  value  )  const

Case-insensitive inequality operator.

String replaceMatches ( const String templ  )  const

Create a string by replacing matched strings in a template

Parameters:
templ Template of the string to generate
Returns:
Copy of template with "\0" - "\9" replaced with submatches
int rfind ( char  what  )  const

Locate the last instance of a character in the string

Parameters:
what Character to search for
Returns:
Offset of character or -1 if not found
const char* safe ( const char *  defStr  )  const [inline]

Get a valid non-NULL C string with a provided default.

Parameters:
defStr Default C string to return if stored is NULL
Returns:
The stored C string, the default or a static "".
const char* safe (  )  const [inline]

Get a valid non-NULL C string.

Returns:
The stored C string or a static "".

Referenced by TelEngine::c_safe(), and Regexp::matches().

ObjList* split ( char  separator,
bool  emptyOK = true 
) const

Splits the string at a delimiter character

Parameters:
separator Character where to split the string
emptyOK True if empty strings should be inserted in list
Returns:
A newly allocated list of strings, must be deleted after use
String sqlEscape ( char  extraEsc = 0  )  const [inline]

Create an escaped string suitable for use in SQL queries

Parameters:
extraEsc Character to escape other than the default ones
Returns:
The string with special characters escaped

References TelEngine::c_str(), and String::sqlEscape().

Referenced by String::sqlEscape().

static String sqlEscape ( const char *  str,
char  extraEsc = 0 
) [static]

Create an escaped string suitable for use in SQL queries

Parameters:
str String to convert to escaped format
extraEsc Character to escape other than the default ones
Returns:
The string with special characters escaped
bool startSkip ( const char *  what,
bool  wordBreak = true,
bool  caseInsensitive = false 
)

Checks if the string starts with a substring and removes it

Parameters:
what Substring to search for
wordBreak Check if a word boundary follows the substring; this parameter defaults to True because the intended use of this method is to separate commands from their parameters
caseInsensitive Compare case-insensitive if set
Returns:
True if the substring occurs at the beginning of the string and also removes the substring; if wordBreak is True any word breaking characters are also removed
bool startsWith ( const char *  what,
bool  wordBreak = false,
bool  caseInsensitive = false 
) const

Checks if the string starts with a substring

Parameters:
what Substring to search for
wordBreak Check if a word boundary follows the substring
caseInsensitive Compare case-insensitive if set
Returns:
True if the substring occurs at the beginning of the string

Referenced by ClientContact::isChatWndPrefix().

String substr ( int  offs,
int  len = -1 
) const

Substring extraction

Parameters:
offs Offset of the substring, negative to count from end
len Length of the substring, -1 for everything possible
Returns:
A copy of the requested substring

Referenced by ClientContact::splitContactId().

bool toBoolean ( bool  defvalue = false  )  const

Convert the string to a boolean value.

Parameters:
defvalue Default to return if the string is not a bool
Returns:
The boolean interpretation or defvalue.
double toDouble ( double  defvalue = 0.0  )  const

Convert the string to a floating point value.

Parameters:
defvalue Default to return if the string is not a number
Returns:
The floating-point interpretation or defvalue.
int toInteger ( const TokenDict tokens,
int  defvalue = 0,
int  base = 0 
) const

Convert the string to an integer value looking up first a token table.

Parameters:
tokens Pointer to an array of tokens to lookup first
defvalue Default to return if the string is not a token or number
base Numeration base, 0 to autodetect
Returns:
The integer interpretation or defvalue.
int toInteger ( int  defvalue = 0,
int  base = 0 
) const

Convert the string to an integer value.

Parameters:
defvalue Default to return if the string is not a number
base Numeration base, 0 to autodetect
Returns:
The integer interpretation or defvalue.
String& toLower (  ) 

Turn the string to an all-lowercase string

Returns:
A reference to this String

Referenced by ClientAccount::buildAccountId(), and ClientContact::buildContactId().

virtual const String& toString (  )  const [virtual]

Override GenObject's method to return this String

Returns:
A reference to this String

Reimplemented from GenObject.

Reimplemented in NamedString.

Referenced by ClientContact::buildContactId().

String& toUpper (  ) 

Turn the string to an all-uppercase string

Returns:
A reference to this String
String& trimBlanks (  ) 

Strip off leading and trailing blank characters

String& trimSpaces (  ) 

Strip off leading and trailing whitespace characters (blank, tabs, form-feed, newlines)

String uriEscape ( char  extraEsc = 0,
const char *  noEsc = 0 
) const [inline]

Create an escaped string suitable for use in URI

Parameters:
extraEsc Character to escape other than the default ones
noEsc Optional pointer to string of characters that shouldn't be escaped
Returns:
The string with special characters escaped

References TelEngine::c_str(), and String::uriEscape().

Referenced by String::uriEscape().

static String uriEscape ( const char *  str,
char  extraEsc = 0,
const char *  noEsc = 0 
) [static]

Create an escaped string suitable for use in URIs

Parameters:
str String to convert to escaped format
extraEsc Character to escape other than the default ones
noEsc Optional pointer to string of characters that shouldn't be escaped
Returns:
The string with special characters escaped
String uriUnescape ( int *  errptr = 0  )  const [inline]

Decode an URI escaped string back to its raw form

Parameters:
errptr Pointer to an integer to receive the place of 1st error
Returns:
The string with special characters unescaped

References TelEngine::c_str(), and String::uriUnescape().

Referenced by String::uriUnescape().

static String uriUnescape ( const char *  str,
int *  errptr = 0 
) [static]

Decode an URI escaped string back to its raw form

Parameters:
str String to convert to unescaped format
errptr Pointer to an integer to receive the place of 1st error
Returns:
The string with special characters unescaped

The documentation for this class was generated from the following file:
Generated on Thu Apr 8 18:22:35 2010 for Yate by  doxygen 1.6.3