String Class Reference

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

#include <yateclass.h>

Inheritance diagram for String:

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
String &	trimBlanks ()
String &	trimSpaces ()
virtual const String &	toString () 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
String &	toUpper ()
String &	toLower ()
char	operator[] (signed int index) const
char	operator[] (unsigned int index) const
	operator const char * () const
String &	assign (const char *value, int len=-1)
String &	assign (char value, unsigned int repeat=1)
String &	hexify (void *data, unsigned int len, char sep=0, bool upCase=false)
String &	operator= (const String &value)
String &	operator= (const String *value)
String &	operator= (const char *value)
String &	operator= (char value)
String &	operator= (int value)
String &	operator= (unsigned int value)
String &	operator= (bool value)
String &	operator+= (const char *value)
String &	operator+= (char value)
String &	operator+= (int value)
String &	operator+= (unsigned int value)
String &	operator+= (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
String &	operator<< (const char *value)
String &	operator<< (char value)
String &	operator<< (int value)
String &	operator<< (unsigned int value)
String &	operator<< (bool value)
String &	operator>> (const char *skip)
String &	operator>> (char &store)
String &	operator>> (int &store)
String &	operator>> (unsigned int &store)
String &	operator>> (bool &store)
String &	append (const char value, const char separator=0, bool force=false)
String &	append (const ObjList list, const char separator=0, bool force=false)
String &	append (const ObjList &list, const char *separator=0, bool force=false)
String &	append (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
ObjList *	split (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 String &	empty ()
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]

Get the value of the stored string.

Returns:: The stored C string which may be NULL.

Referenced by ISDNQ931Message::appendIEValue(), IAXIEList::appendString(), TelEngine::c_str(), ISDNQ931Message::getIEValue(), String::operator=(), TelEngine::strcat(), TelEngine::strcpy(), SHA1::update(), MD5::update(), and Stream::writeData().

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]

Assignment operator.

Reimplemented in URI, Configuration, and SIPDialog.

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

Referenced by DataFormat::operator=(), Message::operator=(), Configuration::operator=(), URI::operator=(), NamedString::operator=(), Regexp::operator=(), and String::operator=().

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