# class String

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

Full name | `TelEngine::String`
Definition | `#include <yateclass.h>`
Inherits | TelEngine::GenObject [public ]
Inherited by | CapturedEvent, ClientAccountList, ClientSound, Compressor, Configuration, DataFormat, Message, MessageHandler, MessageRelay, MimeAuthLine, MimeHeaderLine, NamedList, NamedPointer, NamedString, Regexp, UIFactory, UIWidget, URI
List of all Methods

Annotated List
Files
Globals
Hierarchy
Index

#### Public Methods

- String ()
- String (const char* value, int len = -1)
- explicit String (char value, unsigned int repeat = 1)
- explicit String (int value)
- explicit String (unsigned int value)
- explicit String (bool value)
- String (const String& value)
- String (const String* value)
- virtual ~String ()
- virtual void* getObject (const String& name) const
- inline const char* c_str () const
- inline const char* safe () const
- inline const char* safe (const char* defStr) const
- inline unsigned int length () const
- inline bool null () const
- inline 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, int minvalue = INT_MIN, int maxvalue = INT_MAX, bool clamp = true) const
- int toInteger (const TokenDict* tokens, int defvalue = 0, int base = 0) const
- long int toLong (long int defvalue = 0, int base = 0, long int minvalue = LONG_MIN, long int maxvalue = LONG_MAX, bool clamp = true) const
- double toDouble (double defvalue = 0.0) const
- bool toBoolean (bool defvalue = false) const
- bool isBoolean () const
- String& toUpper ()
- String& toLower ()
- inline char operator[] (signed int index) const
- inline char operator[] (unsigned int index) const
- inline 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)
- inline String& operator= (const String& value)
- inline String& operator= (const String* value)
- String& operator= (const char* value)
- String& operator= (char value)
- String& operator= (int value)
- String& operator= (unsigned int value)
- inline String& operator= (bool value)
- String& operator+= (const char* value)
- String& operator+= (char value)
- String& operator+= (int value)
- String& operator+= (unsigned int value)
- inline 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
- inline String& operator<< (const char* value)
- inline String& operator<< (char value)
- inline String& operator<< (int value)
- inline String& operator<< (unsigned int value)
- inline 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)
- inline 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)
- String& extractTo (const char* sep, String& store)
- String& extractTo (const char* sep, bool& store)
- String& extractTo (const char* sep, int& store, int base = 0)
- String& extractTo (const char* sep, int& store, const TokenDict* tokens, int base = 0)
- String& extractTo (const char* sep, double& store)
- virtual bool matches (const String& value) const
- bool matches (const Regexp& rexp)
- int matchOffset (int index = 0) const
- int matchLength (int index = 0) const
- inline String matchString (int index = 0) const
- String replaceMatches (const String& templ) const
- int matchCount () const
- ObjList* split (char separator, bool emptyOK = true) const
- inline String msgEscape (char extraEsc = 0) const
- inline String msgUnescape (int* errptr = 0, char extraEsc = 0) const
- inline String sqlEscape (char extraEsc = 0) const
- inline String uriEscape (char extraEsc = 0, const char* noEsc = 0) const
- inline String uriUnescape (int* errptr = 0) const

#### Public Static Methods

- static const String& empty ()
- static inline 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 Methods

- virtual void changed ()

## Detailed Description

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.

String ()

### String

Creates a new, empty string.

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

### String

Creates a new initialized string.

Parameters:

value | Initial value of the string
len | Length of the data to copy, -1 for full string

explicit String (char value, unsigned int repeat = 1)

### String

Creates a new initialized string.

Parameters:

value | Character to fill the string
repeat | How many copies of the character to use

explicit String (int value)

### String

Creates a new initialized string from an integer.

Parameters:

value | Value to convert to string

explicit String (unsigned int value)

### String

Creates a new initialized string from an unsigned int.

Parameters:

value | Value to convert to string

explicit String (bool value)

### String

Creates a new initialized string from a boolean.

Parameters:

value | Value to convert to string

String (const String& value)

### String

Copy constructor.

Parameters:

value | Initial value of the string

String (const String* value)

### String

Constructor from String pointer.

Parameters:

value | Initial value of the string

~String ()

### ~String

[virtual]

Destroys the string, disposes the memory.

void* getObject (const String& name)

### getObject

[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.

const String& empty ()

### empty

[static]

A static null String

Returns: Reference to a static empty String

inline const char* boolText (bool value)

### boolText

[static]

A standard text representation of boolean values

Parameters:

value | Boolean value to convert

Returns: Pointer to a text representation of the value

inline const char* c_str ()

### c_str

[const]

Get the value of the stored string.

Returns: The stored C string which may be NULL.

inline const char* safe ()

### safe

[const]

Get a valid non-NULL C string.

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

inline const char* safe (const char* defStr)

### safe

[const]

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 "".

inline unsigned int length ()

### length

[const]

Get the length of the stored string.

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

inline bool null ()

### null

[const]

Checks if the string holds a NULL pointer.

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

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

### lenUtf8

[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

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

### lenUtf8

[const]

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

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

### fixUtf8

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

unsigned int hash ()

### hash

[const]

Get the hash of the contained string.

Returns: The hash of the string.

unsigned int hash (const char* value)

### hash

[static]

Get the hash of an arbitrary string.

Parameters:

value | C string to hash

Returns: The hash of the string.

void clear ()

### clear

Clear the string and free the memory

char at (int index)

### at

[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

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

### substr

[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

String& trimBlanks ()

### trimBlanks

Strip off leading and trailing blank characters

String& trimSpaces ()

### trimSpaces

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

const String& toString ()

### toString

[const virtual]

Override GenObject's method to return this String

Returns: A reference to this String

Reimplemented from GenObject.

int toInteger (int defvalue = 0, int base = 0, int minvalue = INT_MIN, int maxvalue = INT_MAX, bool clamp = true)

### toInteger

[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
minvalue | Minimum value allowed
maxvalue | Maximum value allowed
clamp | Control the out of bound values: true to adjust to the nearest bound, false to return the default value

Returns: The integer interpretation or defvalue.

int toInteger (const TokenDict* tokens, int defvalue = 0, int base = 0)

### toInteger

[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.

long int toLong (long int defvalue = 0, int base = 0, long int minvalue = LONG_MIN, long int maxvalue = LONG_MAX, bool clamp = true)

### toLong

[const]

Convert the string to an long integer value.

Parameters:

defvalue | Default to return if the string is not a number
base | Numeration base, 0 to autodetect
minvalue | Minimum value allowed
maxvalue | Maximum value allowed
clamp | Control the out of bound values: true to adjust to the nearest bound, false to return the default value

Returns: The long integer interpretation or defvalue.

double toDouble (double defvalue = 0.0)

### toDouble

[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.

bool toBoolean (bool defvalue = false)

### toBoolean

[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.

bool isBoolean ()

### isBoolean

[const]

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

Returns: True if the string is a valid boolean.

String& toUpper ()

### toUpper

Turn the string to an all-uppercase string

Returns: A reference to this String

String& toLower ()

### toLower

Turn the string to an all-lowercase string

Returns: A reference to this String

inline char operator[] (signed int index)

### operator[]

[const]

Indexing operator with signed int

Parameters:

index | Index of character in string

Returns: Character at given index or 0 if out of range

inline char operator[] (unsigned int index)

### operator[]

[const]

Indexing operator with unsigned int

Parameters:

index | Index of character in string

Returns: Character at given index or 0 if out of range

inline operator const char* ()

### operator const char*

[const]

Conversion to "const char *" operator.

Returns: Pointer to the internally stored string

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

### assign

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

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

### assign

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& hexify (void* data, unsigned int len, char sep = 0, bool upCase = false)

### hexify

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

inline String& operator= (const String& value)

### operator=

Assignment operator.

inline String& operator= (const String* value)

### operator=

Assignment from String* operator.

See also: strcpy

String& operator= (const char* value)

### operator=

Assignment from char* operator.

See also: strcpy

String& operator= (char value)

### operator=

Assignment operator for single characters.

String& operator= (int value)

### operator=

Assignment operator for integers.

String& operator= (unsigned int value)

### operator=

Assignment operator for unsigned integers.

inline String& operator= (bool value)

### operator=

Assignment operator for booleans.

String& operator+= (const char* value)

### operator+=

Appending operator for strings.

See also: strcat

String& operator+= (char value)

### operator+=

Appending operator for single characters.

String& operator+= (int value)

### operator+=

Appending operator for integers.

String& operator+= (unsigned int value)

### operator+=

Appending operator for unsigned integers.

inline String& operator+= (bool value)

### operator+=

Appending operator for booleans.

bool operator== (const char* value)

### operator==

[const]

Equality operator.

bool operator!= (const char* value)

### operator!=

[const]

Inequality operator.

bool operator== (const String& value)

### operator==

[const]

Fast equality operator.

bool operator!= (const String& value)

### operator!=

[const]

Fast inequality operator.

bool operator&= (const char* value)

### operator&=

[const]

Case-insensitive equality operator.

bool operator|= (const char* value)

### operator|=

[const]

Case-insensitive inequality operator.

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

### operator<<

Stream style appending operator for C strings

inline String& operator<< (char value)

### operator<<

Stream style appending operator for single characters

inline String& operator<< (int value)

### operator<<

Stream style appending operator for integers

inline String& operator<< (unsigned int value)

### operator<<

Stream style appending operator for unsigned integers

inline String& operator<< (bool value)

### operator<<

Stream style appending operator for booleans

String& operator>> (const char* skip)

### operator>>

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

String& operator>> (char& store)

### operator>>

Stream style extraction operator for single characters

String& operator>> (int& store)

### operator>>

Stream style extraction operator for integers

String& operator>> (unsigned int& store)

### operator>>

Stream style extraction operator for unsigned integers

String& operator>> (bool& store)

### operator>>

Stream style extraction operator for booleans

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

### append

Conditional appending with a separator

Parameters:

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

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

### append

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

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

### append

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

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

### append

Explicit double append

Parameters:

value | Value to append
decimals | Number of decimals

int find (char what, unsigned int offs = 0)

### find

[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

int find (const char* what, unsigned int offs = 0)

### find

[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 rfind (char what)

### rfind

[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

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

### startsWith

[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

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

### endsWith

[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

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

### startSkip

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

String& extractTo (const char* sep, String& store)

### extractTo

Extract a substring up to a separator

Parameters:

sep | Separator string to match after extracted fragment
store | Reference to String variable to store extracted fragment

Returns: Reference to this string

String& extractTo (const char* sep, bool& store)

### extractTo

Extract a boolean substring up to a separator

Parameters:

sep | Separator string to match after extracted fragment
store | Reference to boolean variable to store extracted fragment

Returns: Reference to this string

String& extractTo (const char* sep, int& store, int base = 0)

### extractTo

Extract an integer value substring up to a separator

Parameters:

sep | Separator string to match after extracted fragment
store | Reference to integer variable to store extracted fragment
base | Numeration base, 0 to autodetect

Returns: Reference to this string

String& extractTo (const char* sep, int& store, const TokenDict* tokens, int base = 0)

### extractTo

Extract an integer or token value substring up to a separator

Parameters:

sep | Separator string to match after extracted fragment
store | Reference to integer variable to store extracted fragment
tokens | Pointer to an array of tokens to lookup first
base | Numeration base, 0 to autodetect

Returns: Reference to this string

String& extractTo (const char* sep, double& store)

### extractTo

Extract a double value substring up to a separator

Parameters:

sep | Separator string to match after extracted fragment
store | Reference to double variable to store extracted fragment

Returns: Reference to this string

bool matches (const String& value)

### matches

[const virtual]

Checks if matches another string

Parameters:

value | String to check for match

Returns: True if matches, false otherwise

bool matches (const Regexp& rexp)

### matches

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

int matchOffset (int index = 0)

### matchOffset

[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

int matchLength (int index = 0)

### matchLength

[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

inline String matchString (int index = 0)

### matchString

[const]

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 replaceMatches (const String& templ)

### replaceMatches

[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 matchCount ()

### matchCount

[const]

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

Returns: Number of matching subexpressions

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

### split

[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 msgEscape (const char* str, char extraEsc = 0)

### msgEscape

[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

inline String msgEscape (char extraEsc = 0)

### msgEscape

[const]

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

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

### msgUnescape

[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

inline String msgUnescape (int* errptr = 0, char extraEsc = 0)

### msgUnescape

[const]

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

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

### sqlEscape

[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

inline String sqlEscape (char extraEsc = 0)

### sqlEscape

[const]

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

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

### uriEscape

[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

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

### uriEscape

[const]

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

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

### uriUnescape

[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

inline String uriUnescape (int* errptr = 0)

### uriUnescape

[const]

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

void changed ()

### changed

[protected virtual]

Called whenever the value changed (except in constructors).

Generated by: paulc on bussard on Fri Dec 21 16:28:34 2012, using kdoc 2.0a54.