# String Class Reference

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

`#include <yateclass.h>`

Inheritance diagram for String:

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
unsigned int | length () const
bool | null () const
unsigned int | hash () const
void | clear ()
char | at (int index) const
String | substr (int offs, int len=-1) const
String & | trimBlanks ()
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[] (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
String | uriUnescape (int *errptr=0) const

## Static Public Member Functions

static const String & | empty ()
static const char * | boolText (bool value)
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)
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` |
| ) |  |  |

Creates a new initialized string.

Parameters:

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

String | ( | int | value | ) |

Creates a new initialized string from an integer.

Parameters:

  | value | Value to convert to string

String | ( | unsigned int | value | ) |

Creates a new initialized string from an unsigned int.

Parameters:

  | value | Value to convert to string

String | ( | bool | value | ) |

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

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 NamedList, and Message.

static const String& empty | ( |  | ) | `[static]`

A static null String

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

const char* c_str | ( |  | ) | const`[inline]`

Get the value of the stored string.

Returns:
  The stored C string which may be NULL.

const char* safe | ( |  | ) | const`[inline]`

Get a valid non-NULL C string.

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

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.

bool null | ( |  | ) | const`[inline]`

Checks if the string holds a NULL pointer.

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

unsigned int hash | ( |  | ) | const

Get the hash of the contained string.

Returns:
  The hash of the string.

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

Get the hash of an arbitrary string.

Returns:
  The hash of the string.

void clear | ( |  | ) |

Clear the string and free the memory

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

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

String& trimBlanks | ( |  | ) |

Strip off leading and trailing blank characters

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.

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.

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.

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.

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.

bool isBoolean | ( |  | ) | const

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

Returns:
  True if the string is a valid boolean.

String& toUpper | ( |  | ) |

Turn the string to an all-uppercase string

Returns:
  A reference to this String

String& toLower | ( |  | ) |

Turn the string to an all-lowercase string

Returns:
  A reference to this String

char operator[] | ( | int | index | ) | const`[inline]`

Indexing operator

Parameters:

  | index | Index of character in string

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

operator const char * | ( |  | ) | const`[inline]`

Conversion to "const char *" operator.

Returns:
  Pointer to the internally stored 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

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& 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

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

Assignment operator.

Reimplemented in URI, and Configuration.

String& operator= | ( | const String * | value | ) | `[inline]`

Assignment from String* operator.

See also:
  TelEngine::strcpy

String& operator= | ( | const char * | value | ) |

Assignment from char* operator.

See also:
  TelEngine::strcpy

Reimplemented in Regexp, NamedString, URI, and Message.

String& operator= | ( | char | value | ) |

Assignment operator for single characters.

String& operator= | ( | int | value | ) |

Assignment operator for integers.

String& operator= | ( | unsigned int | value | ) |

Assignment operator for unsigned integers.

String& operator= | ( | bool | value | ) | `[inline]`

Assignment operator for booleans.

String& operator+= | ( | const char * | value | ) |

Appending operator for strings.

See also:
  TelEngine::strcat

String& operator+= | ( | char | value | ) |

Appending operator for single characters.

String& operator+= | ( | int | value | ) |

Appending operator for integers.

String& operator+= | ( | unsigned int | value | ) |

Appending operator for unsigned integers.

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

Appending operator for booleans.

bool operator== | ( | const char * | value | ) | const

Equality operator.

bool operator!= | ( | const char * | value | ) | const

Inequality operator.

bool operator== | ( | const String & | value | ) | const

Fast equality operator.

bool operator!= | ( | const String & | value | ) | const

Fast inequality operator.

bool operator &= | ( | const char * | value | ) | const

Case-insensitive equality operator.

bool operator|= | ( | const char * | value | ) | const

Case-insensitive inequality operator.

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

Stream style appending operator for C strings

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

Stream style appending operator for single characters

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

Stream style appending operator for integers

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

Stream style appending operator for unsigned integers

String& operator<< | ( | bool | value | ) | `[inline]`

Stream style appending operator for booleans

String& operator>> | ( | const char * | skip | ) |

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

String& operator>> | ( | char & | store | ) |

Stream style extraction operator for single characters

String& operator>> | ( | int & | store | ) |

Stream style extraction operator for integers

String& operator>> | ( | unsigned int & | store | ) |

Stream style extraction operator for unsigned integers

String& operator>> | ( | bool & | store | ) |

Stream style extraction operator for booleans

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

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

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

Explicit double append

Parameters:

  | value | Value to append
  | decimals | Number of decimals

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

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

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

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

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

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.

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

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

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

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 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 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` |
| ) |  |  | 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

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

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

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

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

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

static String uriEscape | ( | const char * | str,
|  | char | extraEsc = `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

Returns:
  The string with special characters escaped

String uriEscape | ( | char | extraEsc = `0` | ) | const`[inline]`

Create an escaped string suitable for use in URI

Parameters:

  | extraEsc | Character to escape other than the default ones

Returns:
  The string with special characters escaped

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

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

virtual void changed | ( |  | ) | `[protected, virtual]`

Called whenever the value changed (except in constructors).

Reimplemented in Regexp, URI, and DataFormat.

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

- yateclass.h