PString Class Reference

The character string class. More...

`#include <pstring.h>`

Inheritance diagram for PString:

## Public Types

typedef const char * | Initialiser
Public Types inherited from PObject
enum | Comparison { LessThan = -1, EqualTo = 0, GreaterThan = 1 }
| Result of the comparison operation performed by the `Compare()` function. More...

## Public Member Functions

Overrides from class PObject
virtual PObject * | Clone () const
| Make a complete duplicate of the string. More...
virtual Comparison | Compare (const PObject &obj) const
| Get the relative rank of the two strings. More...
virtual void | PrintOn (ostream &strm) const
| Output the string to the specified stream. More...
virtual void | ReadFrom (istream &strm)
| Input the string from the specified stream. More...
virtual PINDEX | HashFunction () const
| Calculate a hash value for use in sets and dictionaries. More...
Overrides from class PContainer
virtual PBoolean | SetSize (PINDEX newSize)
| Set the size of the string. More...
virtual PBoolean | IsEmpty () const
| Determine if the string is empty. More...
virtual PBoolean | MakeUnique ()
| Make this instance to be the one and only reference to the container contents. More...
Size/Length functions
PBoolean | MakeMinimumSize ()
| Set the actual memory block array size to the minimum required to hold the current string contents. More...
PINLINE PINDEX | GetLength () const
| Determine the length of the null terminated string. More...
bool | operator! () const
| Determine if the string is NOT empty. More...
Comparison operators
bool | operator*= (const PString &str) const
| Compare two strings using case insensitive comparison. More...
bool | operator== (const PObject &str) const
| Compare two strings using the `PObject::Compare()` function. More...
bool | operator!= (const PObject &str) const
| Compare two strings using the `PObject::Compare()` function. More...
bool | operator< (const PObject &str) const
| Compare two strings using the `PObject::Compare()` function. More...
bool | operator> (const PObject &str) const
| Compare two strings using the `PObject::Compare()` function. More...
bool | operator<= (const PObject &str) const
| Compare two strings using the `PObject::Compare()` function. More...
bool | operator>= (const PObject &str) const
| Compare two strings using the `PObject::Compare()` function. More...
bool | operator*= (const char *cstr) const
| Compare a PString to a C string using a case insensitive compare function. More...
bool | operator== (const char *cstr) const
| Compare a PString to a C string using the `Compare()` function. More...
bool | operator!= (const char *cstr) const
| Compare a PString to a C string using the `PObject::Compare()` function. More...
bool | operator< (const char *cstr) const
| Compare a PString to a C string using the `PObject::Compare()` function. More...
bool | operator> (const char *cstr) const
| Compare a PString to a C string using the `PObject::Compare()` function. More...
bool | operator<= (const char *cstr) const
| Compare a PString to a C string using the `PObject::Compare()` function. More...
bool | operator>= (const char *cstr) const
| Compare a PString to a C string using the `PObject::Compare()` function. More...
Comparison | NumCompare (const PString &str, PINDEX count=P_MAX_INDEX, PINDEX offset=0) const
| Compare a string against a substring of the object. More...
Comparison | NumCompare (const char *cstr, PINDEX count=P_MAX_INDEX, PINDEX offset=0) const
| Compare a string against a substring of the object. More...
Search & replace functions
PINDEX | Find (char ch, PINDEX offset=0) const
| Locate the position within the string of the character. More...
PINDEX | Find (const PString &str, PINDEX offset=0) const
| Locate the position within the string of the substring. More...
PINDEX | Find (const char *cstr, PINDEX offset=0) const
PINDEX | FindLast (char ch, PINDEX offset=P_MAX_INDEX) const
| Locate the position of the last matching character. More...
PINDEX | FindLast (const PString &str, PINDEX offset=P_MAX_INDEX) const
| Locate the position of the last matching substring. More...
PINDEX | FindLast (const char *cstr, PINDEX offset=P_MAX_INDEX) const
| Locate the position of the last matching substring. More...
PINDEX | FindOneOf (const PString &set, PINDEX offset=0) const
| Locate the position of one of the characters in the set. More...
PINDEX | FindOneOf (const char *cset, PINDEX offset=0) const
| Locate the position of one of the characters in the set. More...
PINDEX | FindSpan (const PString &set, PINDEX offset=0) const
| Locate the position of character not in the set. More...
PINDEX | FindSpan (const char *cset, PINDEX offset=0) const
| Locate the position of character not in the set. More...
PINDEX | FindRegEx (const PRegularExpression &regex, PINDEX offset=0) const
| Locate the position within the string of one of the regular expression. More...
PBoolean | FindRegEx (const PRegularExpression &regex, PINDEX &pos, PINDEX &len, PINDEX offset=0, PINDEX maxPos=P_MAX_INDEX) const
| Locate the position within the string of one of the regular expression. More...
PBoolean | MatchesRegEx (const PRegularExpression &regex) const
| Return true if the entire string matches the regular expression. More...
void | Replace (const PString &target, const PString &subs, PBoolean all=false, PINDEX offset=0)
| Locate the substring within the string and replace it with the specifed substring. More...
void | Splice (const PString &str, PINDEX pos, PINDEX len=0)
| Splice the string into the current string at the specified position. More...
void | Splice (const char *cstr, PINDEX pos, PINDEX len=0)
| Splice the string into the current string at the specified position. More...
void | Delete (PINDEX start, PINDEX len)
| Remove the substring from the string. More...
Sub-string functions
PString | operator() (PINDEX start, PINDEX end) const
| Extract a portion of the string into a new string. More...
PString | Left (PINDEX len) const
| Extract a portion of the string into a new string. More...
PString | Right (PINDEX len) const
| Extract a portion of the string into a new string. More...
PString | Mid (PINDEX start, PINDEX len=P_MAX_INDEX) const
| Extract a portion of the string into a new string. More...
PString | LeftTrim () const
| Create a string consisting of all characters from the source string except all spaces at the beginning of the string. More...
PString | RightTrim () const
| Create a string consisting of all characters from the source string except all spaces at the end of the string. More...
PString | Trim () const
| Create a string consisting of all characters from the source string except all spaces at the beginning and end of the string. More...
PString | ToLower () const
| Create a string consisting of all characters from the source string with all upper case letters converted to lower case. More...
PString | ToUpper () const
| Create a string consisting of all characters from the source string with all lower case letters converted to upper case. More...
PStringArray | Tokenise (const PString &separators, PBoolean onePerSeparator=true) const
| Split the string into an array of substrings. More...
PStringArray | Tokenise (const char *cseparators, PBoolean onePerSeparator=true) const
| Split the string into an array of substrings. More...
PStringArray | Lines () const
| Split the string into individual lines. More...
Public Member Functions inherited from PCharArray
| PCharArray (PINDEX initialSize=0)
| Construct a new dynamic array of char. More...
| PCharArray (char const *buffer, PINDEX length, PBoolean dynamic=true)
| Construct a new dynamic array of char. More...
Public Member Functions inherited from PBaseArray< T >
| PBaseArray (PINDEX initialSize=0)
| Construct a new dynamic array of elements of the specified type. More...
| PBaseArray (T const *buffer, PINDEX length, PBoolean dynamic=true)
| Construct a new dynamic array of elements of the specified type. More...
PBoolean | SetAt (PINDEX index, T val)
| Set the specific element in the array. More...
T | GetAt (PINDEX index) const
| Get a value from the array. More...
void | Attach (const T *buffer, PINDEX bufferSize)
| Attach a pointer to a static block to the base array type. More...
T * | GetPointer (PINDEX minSize=0)
| Get a pointer to the internal array and assure that it is of at least the specified size. More...
T | operator[] (PINDEX index) const
| Get a value from the array. More...
T & | operator[] (PINDEX index)
| Get a reference to value from the array. More...
| operator T const * () const
| Get a pointer to the internal array. More...
PBoolean | Concatenate (const PBaseArray &array)
| Concatenate one array to the end of this array. More...
Public Member Functions inherited from PAbstractArray
| PAbstractArray (PINDEX elementSizeInBytes, PINDEX initialSize=0)
| Create a new dynamic array of `initalSize` elements of `elementSizeInBytes` bytes each. More...
| PAbstractArray (PINDEX elementSizeInBytes, const void *buffer, PINDEX bufferSizeInElements, PBoolean dynamicAllocation)
| Create a new dynamic array of `bufferSizeInElements` elements of `elementSizeInBytes` bytes each. More...
void | Attach (const void *buffer, PINDEX bufferSize)
| Attach a pointer to a static block to the base array type. More...
void * | GetPointer (PINDEX minSize=1)
| Get a pointer to the internal array and assure that it is of at least the specified size. More...
PBoolean | Concatenate (const PAbstractArray &array)
| Concatenate one array to the end of this array. More...
Public Member Functions inherited from PContainer
| PContainer (PINDEX initialSize=0)
| Create a new unique container. More...
| PContainer (const PContainer &cont)
| Create a new refernce to container. More...
PContainer & | operator= (const PContainer &cont)
| Assign one container reference to another. More...
virtual | ~PContainer ()
| Destroy the container class. More...
virtual PINDEX | GetSize () const
| Get the current size of the container. More...
PBoolean | SetMinSize (PINDEX minSize)
| Set the minimum size of container. More...
PBoolean | IsUnique () const
| Determine if container is unique reference. More...
Public Member Functions inherited from PObject
virtual | ~PObject ()
virtual const char * | GetClass (unsigned ancestor=0) const
| Get the current dynamic type of the object instance. More...
PBoolean | IsClass (const char *cls) const
virtual PBoolean | InternalIsDescendant (const char *clsName) const
| Determine if the dynamic type of the current instance is a descendent of the specified class. More...
virtual Comparison | CompareObjectMemoryDirect (const PObject &obj) const
| Determine the byte wise comparison of two objects. More...
bool | operator== (const PObject &obj) const
| Compare the two objects. More...
bool | operator!= (const PObject &obj) const
| Compare the two objects. More...
bool | operator< (const PObject &obj) const
| Compare the two objects. More...
bool | operator> (const PObject &obj) const
| Compare the two objects. More...
bool | operator<= (const PObject &obj) const
| Compare the two objects. More...
bool | operator>= (const PObject &obj) const
| Compare the two objects. More...

## Protected Member Functions

void | InternalFromUCS2 (const wchar_t *ptr, PINDEX len)
virtual Comparison | InternalCompare (PINDEX offset, char c) const
virtual Comparison | InternalCompare (PINDEX offset, PINDEX length, const char *cstr) const
| PString (int dummy, const PString *str)
| PString (PContainerReference &reference)
Protected Member Functions inherited from PBaseArray< T >
virtual void | PrintElementOn (ostream &stream, PINDEX index) const
| PBaseArray (PContainerReference &reference)
Protected Member Functions inherited from PAbstractArray
PBoolean | InternalSetSize (PINDEX newSize, PBoolean force)
virtual void | ReadElementFrom (istream &stream, PINDEX index)
| PAbstractArray (PContainerReference &reference, PINDEX elementSizeInBytes)
Protected Member Functions inherited from PContainer
| PContainer (int dummy, const PContainer *cont)
| Constructor used in support of the Clone() function. More...
| PContainer (PContainerReference &reference)
| Construct using static PContainerReference. More...
virtual void | DestroyContents ()=0
| Destroy the container contents. More...
virtual void | AssignContents (const PContainer &c)
| Copy the container contents. More...
void | CopyContents (const PContainer &c)
| Copy the container contents. More...
void | CloneContents (const PContainer *src)
| Create a duplicate of the container contents. More...
void | Destruct ()
| Internal function called from container destructors. More...
virtual void | DestroyReference ()
| Destroy the PContainerReference instance. More...
Protected Member Functions inherited from PObject
| PObject ()
| Constructor for PObject, made protected so cannot ever create one on its own. More...

## Construction

enum | ConversionType { Pascal, Basic, Literal, Signed, Unsigned, Decimal, Exponent, Printf, NumConversionTypes }
PINLINE | PString ()
| Construct an empty string. More...
PINLINE | PString (const PString &str)
| Create a new reference to the specified string. More...
PINLINE | PString (const std::string &str)
| Create a new string from the specified std::string. More...
| PString (const char *cstr)
| Create a string from the C string array. More...
| PString (const wchar_t *ustr)
| Create a string from the UCS-2 string array. More...
| PString (const char *cstr, PINDEX len)
| Create a string from the array. More...
| PString (const wchar_t *ustr, PINDEX len)
| Create a string from the UCS-2 array. More...
| PString (const PWCharArray &ustr)
| Create a string from the UCS-2 array. More...
| PString (char ch)
| Create a string from the single character. More...
| PString (short n)
| Create a string from the integer type. More...
| PString (unsigned short n)
| Create a string from the integer type. More...
| PString (int n)
| Create a string from the integer type. More...
| PString (unsigned int n)
| Create a string from the integer type. More...
| PString (long n)
| Create a string from the integer type. More...
| PString (unsigned long n)
| Create a string from the integer type. More...
| PString (PInt64 n)
| Create a string from the integer type. More...
| PString (PUInt64 n)
| Create a string from the integer type. More...
| PString (ConversionType type, const char *str,...)
| PString (ConversionType type, long value, unsigned base=10)
| PString (ConversionType type, double value, unsigned places)
PString & | operator= (const PString &str)
| Assign the string to the current object. More...
PString & | operator= (const std::string &str)
| Assign the string to the current object. More...
PString & | operator= (const char *cstr)
| Assign the C string to the current object. More...
PString & | operator= (char ch)
| Assign the character to the current object. More...
PString & | operator= (short n)
| Assign a string from the integer type. More...
PString & | operator= (unsigned short n)
| Assign a string from the integer type. More...
PString & | operator= (int n)
| Assign a string from the integer type. More...
PString & | operator= (unsigned int n)
| Assign a string from the integer type. More...
PString & | operator= (long n)
| Assign a string from the integer type. More...
PString & | operator= (unsigned long n)
| Assign a string from the integer type. More...
PString & | operator= (PInt64 n)
| Assign a string from the integer type. More...
PString & | operator= (PUInt64 n)
| Assign a string from the integer type. More...
virtual PString & | MakeEmpty ()
| Make the current string empty. More...
static PString | Empty ()
| Return an empty string. More...

## Concatenation operators

PString | operator+ (const PString &str) const
| Concatenate two strings to produce a third. More...
PString | operator+ (const char *cstr) const
| Concatenate a C string to a PString to produce a third. More...
PString | operator+ (char ch) const
| Concatenate a single character to a PString to produce a third. More...
PString & | operator+= (const PString &str)
| Concatenate a string to another string, modifiying that string. More...
PString & | operator+= (const char *cstr)
| Concatenate a C string to a PString, modifiying that string. More...
PString & | operator+= (char ch)
| Concatenate a single character to a PString. More...
PString | operator & (const PString &str) const
| Concatenate two strings to produce a third. More...
PString | operator & (const char *cstr) const
| Concatenate a C string to a PString to produce a third. More...
PString | operator & (char ch) const
| Concatenate a single character to a PString to produce a third. More...
PString & | operator &= (const PString &str)
| Concatenate a string to another string, modifiying that string. More...
PString & | operator &= (const char *cstr)
| Concatenate a C string to a PString, modifiying that string. More...
PString & | operator &= (char ch)
| Concatenate a character to a PString, modifiying that string. More...
PString | operator+ (const char *cstr, const PString &str)
| Concatenate a PString to a C string to produce a third. More...
PString | operator+ (char ch, const PString &str)
| Concatenate a PString to a single character to produce a third. More...
PString | operator & (const char *cstr, const PString &str)
| Concatenate a PString to a C string to produce a third. More...
PString | operator & (char ch, const PString &str)
| Concatenate a PString to a single character to produce a third. More...

## Conversion functions

PString & | sprintf (const char *cfmt,...)
| Concatenate a formatted output to the string. More...
PString & | vsprintf (const PString &fmt, va_list args)
| Concatenate a formatted output to the string. More...
PString & | vsprintf (const char *cfmt, va_list args)
| Concatenate a formatted output to the string. More...
long | AsInteger (unsigned base=10) const
| Convert the string to an integer value using the specified number base. More...
DWORD | AsUnsigned (unsigned base=10) const
| Convert the string to an integer value using the specified number base. More...
PInt64 | AsInt64 (unsigned base=10) const
| Convert the string to an integer value using the specified number base. More...
PUInt64 | AsUnsigned64 (unsigned base=10) const
| Convert the string to an integer value using the specified number base. More...
double | AsReal () const
| Convert the string to a floating point number. More...
PWCharArray | AsUCS2 () const
| Convert UTF-8 string to UCS-2. More...
PBYTEArray | ToPascal () const
| Convert a standard null terminated string to a "pascal" style string. More...
PString | ToLiteral () const
| Convert the string to C literal string format. More...
| operator const unsigned char * () const
| Get the internal buffer as a pointer to unsigned characters. More...
| operator std::string () const
| Cast the PString to a std::string. More...
PString | psprintf (const char *cfmt,...)
| Produce formatted output as a string. More...
PString | pvsprintf (const char *cfmt, va_list args)
| Produce formatted output as a string. More...
PString | pvsprintf (const PString &fmt, va_list args)
| Produce formatted output as a string. More...

## Additional Inherited Members

Static Public Member Functions inherited from PObject
static const char * | Class ()
| Get the name of the class as a C string. More...
static Comparison | InternalCompareObjectMemoryDirect (const PObject *obj1, const PObject *obj2, PINDEX size)
| Internal function caled from CompareObjectMemoryDirect() More...
Protected Attributes inherited from PAbstractArray
PINDEX | elementSize
| Size of an element in bytes. More...
char * | theArray
| Pointer to the allocated block of memory. More...
PBoolean | allocatedDynamically
| Flag indicating the array was allocated on the heap. More...
Protected Attributes inherited from PContainer
PContainerReference * | reference

## Detailed Description

The character string class.

It supports a wealth of additional functions for string processing and conversion. Operators are provided so that strings can virtually be treated as a basic type.

An important feature of the string class, which is not present in other container classes, is that when the string contents is changed, that is resized or elements set, the string is "dereferenced", and a duplicate made of its contents. That is this instance of the array is disconnected from all other references to the string data, if any, and a new string array contents created. For example consider the following:

              PString s1 = "String"; // New array allocated and set to "String"
              PString s2 = s1;       // s2 has pointer to same array as s1
    and reference count is 2 for both
              s1[0] = 's';           // Breaks references into different strings

at the end s1 is "string" and s2 is "String" both with reference count of 1.

The functions that will "break" a reference are `SetSize()`, `SetMinSize()`, `GetPointer()`, `SetAt()` and `operator[]`.

Note that the array is a '\0' terminated string as in C strings. Thus the memory allocated, and the length of the string may be different values.

Also note that the PString is inherently an 8 bit string. The character set is not defined for most operations and it may be any 8 bit character set. However when conversions are being made to or from 2 byte formats then the PString is assumed to be the UTF-8 format. The 2 byte format is nominally UCS-2 (aka BMP string) and while it is not exactly the same as UNICODE they are compatible enough for them to be treated the same for most real world usage.

## Member Typedef Documentation

## Initialiser

typedef const char* PString::Initialiser

## Member Enumeration Documentation

## ConversionType

enum PString::ConversionType

Enumerator
Pascal |
Basic |
Literal |
Signed |
Unsigned |
Decimal |
Exponent |
Printf |
NumConversionTypes |

## Constructor & Destructor Documentation

## PString() [1/22]

PINLINE PString::PString | ( |  | ) |

Construct an empty string.

This will have one character in it which is the '\0' character.

Referenced by operator std::string(), PStringDictionary< K >::operator()(), operator<<(), PHTML::operator=(), PStringArray::PStringArray(), PStringDictionary< K >::SetAt(), and PStringDictionary< K >::SetDataAt().

## PString() [2/22]

PINLINE PString::PString | ( | const PString & | str | ) |

Create a new reference to the specified string.

The string memory is not copied, only the pointer to the data.

Parameters

  str | String to create new reference to.

## PString() [3/22]

PINLINE PString::PString | ( | const std::string & | str | ) |

Create a new string from the specified std::string.

## PString() [4/22]

PString::PString | ( | const char * | cstr | ) |

Create a string from the C string array.

This is most commonly used with a literal string, eg "hello". A new memory block is allocated of a size sufficient to take the length of the string and its terminating '\0' character.

If UCS-2 is used then each char from the char pointer is mapped to a single UCS-2 character.

Parameters

  cstr | Standard '\0' terminated C string.

## PString() [5/22]

PString::PString | ( | const wchar_t * | ustr | ) |

Create a string from the UCS-2 string array.

A new memory block is allocated of a size sufficient to take the length of the string and its terminating '\0' character.

Parameters

  ustr | UCS-2 null terminated string.

## PString() [6/22]

PString::PString | ( | const char * | cstr,
|  | PINDEX | len
| ) |  |

Create a string from the array.

A new memory block is allocated of a size equal to `len` plus one which is sufficient to take the string and a terminating '\0' character.

If UCS-2 is used then each char from the char pointer is mapped to a single UCS-2 character.

Note that this function will allow a string with embedded '\0' characters to be created, but most of the functions here will be unable to access characters beyond the first '\0'. Furthermore, if the `MakeMinimumSize()` function is called, all data beyond that first '\0' character will be lost.

Parameters

  cstr | Pointer to a string of characters.
  len | Length of the string in bytes.

## PString() [7/22]

PString::PString | ( | const wchar_t * | ustr,
|  | PINDEX | len
| ) |  |

Create a string from the UCS-2 array.

A new memory block is allocated of a size equal to `len` plus one which is sufficient to take the string and a terminating '\0' character.

Note that this function will allow a string with embedded '\0' characters to be created, but most of the functions here will be unable to access characters beyond the first '\0'. Furthermore, if the `MakeMinimumSize()` function is called, all data beyond that first '\0' character will be lost.

Parameters

  ustr | Pointer to a string of UCS-2 characters.
  len | Length of the string in bytes.

## PString() [8/22]

PString::PString | ( | const PWCharArray & | ustr | ) |

Create a string from the UCS-2 array.

A new memory block is allocated of a size equal to `len` plus one which is sufficient to take the string and a terminating '\0' character.

Note that this function will allow a string with embedded '\0' characters to be created, but most of the functions here will be unable to access characters beyond the first '\0'. Furthermore, if the `MakeMinimumSize()` function is called, all data beyond that first '\0' character will be lost.

Parameters

  ustr | UCS-2 null terminated string.

## PString() [9/22]

PString::PString | ( | char | ch | ) |

Create a string from the single character.

This is most commonly used as a type conversion constructor when a literal character, eg 'A' is used in a string expression. A new memory block is allocated of two characters to take the char and its terminating '\0' character.

If UCS-2 is used then the char is mapped to a single UCS-2 character.

Parameters

  ch | Single character to initialise string.

## PString() [10/22]

PString::PString | ( | short | n | ) |

Create a string from the integer type.

This will create a simple base 10, shortest length conversion of the integer (with sign character if appropriate) into the string.

Parameters

  n | Integer to convert

## PString() [11/22]

PString::PString | ( | unsigned short | n | ) |

Create a string from the integer type.

This will create a simple base 10, shortest length conversion of the integer (with sign character if appropriate) into the string.

Parameters

  n | Integer to convert

## PString() [12/22]

PString::PString | ( | int | n | ) |

Create a string from the integer type.

This will create a simple base 10, shortest length conversion of the integer (with sign character if appropriate) into the string.

Parameters

  n | Integer to convert

## PString() [13/22]

PString::PString | ( | unsigned int | n | ) |

Create a string from the integer type.

This will create a simple base 10, shortest length conversion of the integer (with sign character if appropriate) into the string.

Parameters

  n | Integer to convert

## PString() [14/22]

PString::PString | ( | long | n | ) |

Create a string from the integer type.

This will create a simple base 10, shortest length conversion of the integer (with sign character if appropriate) into the string.

Parameters

  n | Integer to convert

## PString() [15/22]

PString::PString | ( | unsigned long | n | ) |

Create a string from the integer type.

This will create a simple base 10, shortest length conversion of the integer (with sign character if appropriate) into the string.

Parameters

  n | Integer to convert

## PString() [16/22]

PString::PString | ( | PInt64 | n | ) |

Create a string from the integer type.

This will create a simple base 10, shortest length conversion of the integer (with sign character if appropriate) into the string.

Parameters

  n | Integer to convert

## PString() [17/22]

PString::PString | ( | PUInt64 | n | ) |

Create a string from the integer type.

This will create a simple base 10, shortest length conversion of the integer (with sign character if appropriate) into the string.

Parameters

  n | Integer to convert

## PString() [18/22]

PString::PString | ( | ConversionType | type,
|  | const char * | str,
|  |  | ...
| ) |  |

Parameters

  type | Type of data source for conversion.
  str | String to convert.

## PString() [19/22]

PString::PString | ( | ConversionType | type,
|  | long | value,
|  | unsigned | base = `10`
| ) |  |

Parameters

  type | Type of data source for conversion.
  value | Integer value to convert.
  base | Number base to use for the integer conversion.

## PString() [20/22]

PString::PString | ( | ConversionType | type,
|  | double | value,
|  | unsigned | places
| ) |  |

Parameters

  type | Type of data source for conversion.
  value | Floating point value to convert.
  places | Number of decimals in real number output.

## PString() [21/22]

PString::PString | ( | int | dummy,
|  | const PString * | str
| ) |  |

protected

## PString() [22/22]

PString::PString | ( | PContainerReference & | reference | ) |

inline protected

## Member Function Documentation

## AsInt64()

PInt64 PString::AsInt64 | ( | unsigned | base = `10` | ) | const

Convert the string to an integer value using the specified number base.

All characters up to the first illegal character for the number base are converted. Case is not significant for bases greater than 10.

The number base may only be from 2 to 36 and the function will assert if it is not in this range.

This function uses the standard C library `strtoq()` or `strtoul()` function.

Returns
  integer value for the string.

Parameters

  base | Number base to convert the string in.

Referenced by operator=().

## AsInteger()

long PString::AsInteger | ( | unsigned | base = `10` | ) | const

Convert the string to an integer value using the specified number base.

All characters up to the first illegal character for the number base are converted. Case is not significant for bases greater than 10.

The number base may only be from 2 to 36 and the function will assert if it is not in this range.

This function uses the standard C library `strtol()` function.

Returns
  integer value for the string.

Parameters

  base | Number base to convert the string in.

Referenced by operator=().

## AsReal()

double PString::AsReal | ( |  | ) | const

Convert the string to a floating point number.

This number may be in decimal or exponential form. All characters up to the first illegal character for a floting point number are converted.

This function uses the standard C library `strtod()` function.

Returns
  floating point value for the string.

Referenced by operator=().

## AsUCS2()

PWCharArray PString::AsUCS2 | ( |  | ) | const

Convert UTF-8 string to UCS-2.

Note the resultant PWCharArray will have the trailing null included.

Referenced by operator<<(), operator=(), PASN_BMPString::operator=(), and PASN_BMPString::SetValue().

## AsUnsigned()

DWORD PString::AsUnsigned | ( | unsigned | base = `10` | ) | const

Convert the string to an integer value using the specified number base.

All characters up to the first illegal character for the number base are converted. Case is not significant for bases greater than 10.

The number base may only be from 2 to 36 and the function will assert if it is not in this range.

This function uses the standard C library `strtoul()` function.

Returns
  integer value for the string.

Parameters

  base | Number base to convert the string in.

Referenced by operator=().

## AsUnsigned64()

PUInt64 PString::AsUnsigned64 | ( | unsigned | base = `10` | ) | const

Convert the string to an integer value using the specified number base.

All characters up to the first illegal character for the number base are converted. Case is not significant for bases greater than 10.

The number base may only be from 2 to 36 and the function will assert if it is not in this range.

This function uses the standard C library `strtouq()` or `strtoul()` function.

Returns
  integer value for the string.

Parameters

  base | Number base to convert the string in.

Referenced by operator=().

## Clone()

virtual PObject* PString::Clone | ( |  | ) | const

virtual

Make a complete duplicate of the string.

Note that the data in the array of characters is duplicated as well and the new object is a unique reference to that data.

Reimplemented from PBaseArray< T >.

Reimplemented in PCaselessString.

Referenced by operator=(), and PCaselessString::operator=().

## Compare()

virtual Comparison PString::Compare | ( | const PObject & | obj | ) | const

virtual

Get the relative rank of the two strings.

The system standard function, eg strcmp(), is used.

Returns
  comparison of the two objects, `EqualTo` for same, `LessThan` for `obj` logically less than the object and `GreaterThan` for `obj` logically greater than the object.

Parameters

  obj | Other PString to compare against.

Reimplemented from PAbstractArray.

Referenced by operator=(), and PHTTPClientAuthentication::AuthObject::~AuthObject().

## Delete()

void PString::Delete | ( | PINDEX | start,
|  | PINDEX | len
| ) |  |

Remove the substring from the string.

Note that this function will break the current instance from multiple references to the string. A new string buffer is allocated and the data from the old string buffer copied to it.

Parameters

  start | Position in string to remove.
  len | Number of characters to delete.

Referenced by operator=().

## Empty()

static PString PString::Empty | ( |  | ) |

static

Return an empty string.

Referenced by PHTTPClientAuthentication::GetAuthRealm(), XMPP::BareJID::GetResource(), PVXMLSession::GetTextToSpeech(), XMPP::C2S::StreamHandler::IQHandlers(), PURL::IsEmpty(), operator=(), PVideoInputDevice::~PVideoInputDevice(), and PVideoOutputDevice::~PVideoOutputDevice().

## Find() [1/3]

PINDEX PString::Find | ( | char | ch,
|  | PINDEX | offset = `0`
| ) |  | const

Locate the position within the string of the character.

Parameters

  ch | Character to search for in string.
  offset | Offset into string to begin search.

Referenced by operator=().

## Find() [2/3]

PINDEX PString::Find | ( | const PString & | str,
|  | PINDEX | offset = `0`
| ) |  | const

Locate the position within the string of the substring.

Parameters

  str | String to search for in string.
  offset | Offset into string to begin search.

## Find() [3/3]

PINDEX PString::Find | ( | const char * | cstr,
|  | PINDEX | offset = `0`
| ) |  | const

Parameters

  cstr | C string to search for in string.
  offset | Offset into string to begin search.

## FindLast() [1/3]

PINDEX PString::FindLast | ( | char | ch,
|  | PINDEX | offset = `P_MAX_INDEX`
| ) |  | const

Locate the position of the last matching character.

Parameters

  ch | Character to search for in string.
  offset | Offset into string to begin search.

Referenced by operator=().

## FindLast() [2/3]

PINDEX PString::FindLast | ( | const PString & | str,
|  | PINDEX | offset = `P_MAX_INDEX`
| ) |  | const

Locate the position of the last matching substring.

Parameters

  str | String to search for in string.
  offset | Offset into string to begin search.

## FindLast() [3/3]

PINDEX PString::FindLast | ( | const char * | cstr,
|  | PINDEX | offset = `P_MAX_INDEX`
| ) |  | const

Locate the position of the last matching substring.

Locate the position within the string of the last matching character or substring. The search will begin at the character offset provided, moving backward through the string.

If `offset` is beyond the length of the string, then the search begins at the end of the string. If `offset` is zero then the function always returns P_MAX_INDEX.

The matching will be for identical character or string. If a search ignoring case is required then the string should be converted to a PCaselessString before the search is made.

Returns
  position of character or substring in the string, or P_MAX_INDEX if the character or substring is not in the string.

Parameters

  cstr | C string to search for in string.
  offset | Offset into string to begin search.

## FindOneOf() [1/2]

PINDEX PString::FindOneOf | ( | const PString & | set,
|  | PINDEX | offset = `0`
| ) |  | const

Locate the position of one of the characters in the set.

Parameters

  set | String of characters to search for in string.
  offset | Offset into string to begin search.

Referenced by operator=().

## FindOneOf() [2/2]

PINDEX PString::FindOneOf | ( | const char * | cset,
|  | PINDEX | offset = `0`
| ) |  | const

Locate the position of one of the characters in the set.

The search will begin at the character offset provided.

If `offset` is beyond the length of the string, then the function will always return P_MAX_INDEX.

The matching will be for identical character or string. If a search ignoring case is required then the string should be converted to a PCaselessString before the search is made.

Returns
  position of character in the string, or P_MAX_INDEX if no characters from the set are in the string.

Parameters

  cset | C string of characters to search for in string.
  offset | Offset into string to begin search.

## FindRegEx() [1/2]

PINDEX PString::FindRegEx | ( | const PRegularExpression & | regex,
|  | PINDEX | offset = `0`
| ) |  | const

Locate the position within the string of one of the regular expression.

The search will begin at the character offset provided.

If `offset` is beyond the length of the string, then the function will always return P_MAX_INDEX.

Returns
  position of regular expression in the string, or P_MAX_INDEX if no characters from the set are in the string.

Parameters

  regex | regular expression to find
  offset | Offset into string to begin search.

Referenced by operator=().

## FindRegEx() [2/2]

PBoolean PString::FindRegEx | ( | const PRegularExpression & | regex,
|  | PINDEX & | pos,
|  | PINDEX & | len,
|  | PINDEX | offset = `0`,
|  | PINDEX | maxPos = `P_MAX_INDEX`
| ) |  | const

Locate the position within the string of one of the regular expression.

The search will begin at the character offset provided.

If `offset` is beyond the length of the string, then the function will always return P_MAX_INDEX.

Returns
  position of regular expression in the string, or P_MAX_INDEX if no characters from the set are in the string.

Parameters

  regex | regular expression to find
  pos | Position of matched expression
  len | Length of matched expression
  offset | Offset into string to begin search.
  maxPos | Maximum offset into string

## FindSpan() [1/2]

PINDEX PString::FindSpan | ( | const PString & | set,
|  | PINDEX | offset = `0`
| ) |  | const

Locate the position of character not in the set.

Parameters

  set | String of characters to search for in string.
  offset | Offset into string to begin search.

Referenced by operator=().

## FindSpan() [2/2]

PINDEX PString::FindSpan | ( | const char * | cset,
|  | PINDEX | offset = `0`
| ) |  | const

Locate the position of character not in the set.

The search will begin at the character offset provided.

If `offset` is beyond the length of the string, or every character in the string is a member of the set, then the function will always return P_MAX_INDEX.

The matching will be for identical character or string. If a search ignoring case is required then the string should be converted to a PCaselessString before the search is made.

Returns
  position of character not in the set, or P_MAX_INDEX if all characters from the string are in the set.

Parameters

  cset | C string of characters to search for in string.
  offset | Offset into string to begin search.

## GetLength()

PINLINE PINDEX PString::GetLength | ( |  | ) | const

Determine the length of the null terminated string.

This is different from `PContainer::GetSize()` which returns the amount of memory allocated to the string. This is often, though no necessarily, one larger than the length of the string.

Returns
  length of the null terminated string.

Referenced by operator=().

## HashFunction()

virtual PINDEX PString::HashFunction | ( |  | ) | const

virtual

Calculate a hash value for use in sets and dictionaries.

The hash function for strings will produce a value based on the sum of the first three characters of the string. This is a fairly basic function and make no assumptions about the string contents. A user may descend from PString and override the hash function if they can take advantage of the types of strings being used, eg if all strings start with the letter 'A' followed by 'B or 'C' then the current hash function will not perform very well.

Returns
  hash value for string.

Reimplemented from PObject.

Referenced by operator=().

## InternalCompare() [1/2]

virtual Comparison PString::InternalCompare | ( | PINDEX | offset,
|  | char | c
| ) |  | const

protected virtual

Reimplemented in PCaselessString.

Referenced by operator std::string(), and PCaselessString::operator=().

## InternalCompare() [2/2]

virtual Comparison PString::InternalCompare | ( | PINDEX | offset,
|  | PINDEX | length,
|  | const char * | cstr
| ) |  | const

protected virtual

Reimplemented in PCaselessString.

## InternalFromUCS2()

void PString::InternalFromUCS2 | ( | const wchar_t * | ptr,
|  | PINDEX | len
| ) |  |

protected

Referenced by operator std::string().

## IsEmpty()

virtual PBoolean PString::IsEmpty | ( |  | ) | const

virtual

Determine if the string is empty.

This is semantically slightly different from the usual `PContainer::IsEmpty()` function. It does not test for `PContainer::GetSize()` equal to zero, it tests for `GetLength()` equal to zero.

Returns
  true if no non-null characters in string.

Reimplemented from PContainer.

Referenced by XMPP::JID::IsBare(), PURL::IsEmpty(), PDNS::Lookup(), and operator=().

## Left()

PString PString::Left | ( | PINDEX | len | ) | const

Extract a portion of the string into a new string.

The original string is not changed and a new unique reference to a string is returned.

A substring from the beginning of the string for the number of characters specified is extracted.

If `len` is greater than the length of the string then all characters to the end of the string are returned.

If `len` is zero then an empty string is returned.

Returns
  substring of the source string.

Parameters

  len | Number of characters to extract.

Referenced by operator=().

## LeftTrim()

PString PString::LeftTrim | ( |  | ) | const

Create a string consisting of all characters from the source string except all spaces at the beginning of the string.

The original string is not changed and a new unique reference to a string is returned.

Returns
  string with leading spaces removed.

Referenced by operator=().

## Lines()

PStringArray PString::Lines | ( |  | ) | const

Split the string into individual lines.

The line delimiters may be a carriage return ('\r'), a line feed ('\n') or a carriage return and line feed pair ("\\r\\n"). A line feed and carriage return pair ("\\n\\r") would yield a blank line. between the characters.

The `Tokenise()` function should not be used to split a string into lines as a #"\\r\\n"# pair consitutes a single line ending. The `Tokenise()` function would produce a blank line in between them.

Returns
  string array with a substring for each line in the string.

Referenced by operator=().

## MakeEmpty()

virtual PString& PString::MakeEmpty | ( |  | ) |

virtual

Make the current string empty.

Reimplemented in PStringStream.

Referenced by operator=().

## MakeMinimumSize()

PBoolean PString::MakeMinimumSize | ( |  | ) |

Set the actual memory block array size to the minimum required to hold the current string contents.

Note that this function will break the current instance from multiple references to the string. A new string buffer is allocated and the data from the old string buffer copied to it.

Returns
  true if new memory block successfully allocated.

Referenced by operator=().

## MakeUnique()

virtual PBoolean PString::MakeUnique | ( |  | ) |

virtual

Make this instance to be the one and only reference to the container contents.

This implicitly does a clone of the contents of the container to make a unique reference. If the instance was already unique then the function does nothing.

Returns
  true if the instance was already unique.

Reimplemented from PContainer.

Referenced by operator=(), PStringOptions::RemoveAt(), and PStringOptions::SetAt().

## MatchesRegEx()

PBoolean PString::MatchesRegEx | ( | const PRegularExpression & | regex | ) | const

Return true if the entire string matches the regular expression.

Parameters

  regex | regular expression to match

Referenced by operator=().

## Mid()

PString PString::Mid | ( | PINDEX | start,
|  | PINDEX | len = `P_MAX_INDEX`
| ) |  | const

Extract a portion of the string into a new string.

The original string is not changed and a new unique reference to a string is returned.

A substring from the `start` position for the number of characters specified is extracted.

If `len` is greater than the length of the string from the `start` position then all characters to the end of the string are returned.

If `start` is greater than the length of the string or `len` is zero then an empty string is returned.

Returns
  substring of the source string.

Parameters

  start | Starting position of the substring.
  len | Number of characters to extract.

Referenced by operator=().

## NumCompare() [1/2]

Comparison PString::NumCompare | ( | const PString & | str,
|  | PINDEX | count = `P_MAX_INDEX`,
|  | PINDEX | offset = `0`
| ) |  | const

Compare a string against a substring of the object.

This will compare at most `count` characters of the string, starting at the specified `offset`, against that many characters of the `str` parameter. If `count` greater than the length of the `str` parameter then the actual length of `str` is used. If `count` and the length of `str` are greater than the length of the string remaining from the `offset` then false is returned.

Returns
  true if str is a substring of .

Parameters

  str | PString object to compare against.
  count | Number of chacracters in str to compare
  offset | Offset into string to compare

Referenced by operator=().

## NumCompare() [2/2]

Comparison PString::NumCompare | ( | const char * | cstr,
|  | PINDEX | count = `P_MAX_INDEX`,
|  | PINDEX | offset = `0`
| ) |  | const

Compare a string against a substring of the object.

This will compare at most `count` characters of the string, starting at the specified `offset`, against that many characters of the `str` parameter. If `count` greater than the length of the `str` parameter then the actual length of `str` is used. If `count` and the length of `str` are greater than the length of the string remaining from the `offset` then false is returned.

Returns
  true if str is a substring of .

Parameters

  cstr | C string object to compare against.
  count | Number of chacracters in str to compare
  offset | Offset into string to compare

## operator &() [1/3]

PString PString::operator& | ( | const PString & | str | ) | const

Concatenate two strings to produce a third.

The original strings are not modified, an entirely new unique reference to a string is created.

Returns
  new string with concatenation of the object and parameter.

Parameters

  str | String to concatenate.

Referenced by operator=().

## operator &() [2/3]

PString PString::operator& | ( | const char * | cstr | ) | const

Concatenate a C string to a PString to produce a third.

The original string is not modified, an entirely new unique reference to a string is created. The `cstr` parameter is typically a literal string, eg:

              myStr = aStr & "fred";

       This function differes from operator+ in that it assures there is at
       least one space between the strings. Exactly one space is added if
       there is not a space at the end of the first or beggining of the last
       string.

       @return
       new string with concatenation of the object and parameter.

Parameters

  cstr | C string to concatenate.

## operator &() [3/3]

PString PString::operator& | ( | char | ch | ) | const

Concatenate a single character to a PString to produce a third.

The original string is not modified, an entirely new unique reference to a string is created. The `ch` parameter is typically a literal, eg:

              myStr = aStr & '!';

       This function differes from operator+ in that it assures there is at
       least one space between the strings. Exactly one space is added if
       there is not a space at the end of the first or beggining of the last
       string.

       @return
       new string with concatenation of the object and parameter.

Parameters

  ch | Character to concatenate.

## operator &=() [1/3]

PString& PString::operator&= | ( | const PString & | str | ) |

Concatenate a string to another string, modifiying that string.

Returns
  reference to string that was concatenated to.

Parameters

  str | String to concatenate.

Referenced by operator=().

## operator &=() [2/3]

PString& PString::operator&= | ( | const char * | cstr | ) |

Concatenate a C string to a PString, modifiying that string.

The `cstr` parameter is typically a literal string, eg:

              myStr &= "fred";

       This function differes from operator+ in that it assures there is at
       least one space between the strings. Exactly one space is added if
       there is not a space at the end of the first or beggining of the last
       string.

       @return
       reference to string that was concatenated to.

Parameters

  cstr | C string to concatenate.

## operator &=() [3/3]

PString& PString::operator&= | ( | char | ch | ) |

Concatenate a character to a PString, modifiying that string.

The `ch` parameter is typically a literal string, eg:

              myStr &= '!';

       This function differes from operator+ in that it assures there is at
       least one space between the strings. Exactly one space is added if
       there is not a space at the end of the first or beggining of the last
       string.

       @return
       reference to string that was concatenated to.

Parameters

  ch | Character to concatenate.

## operator const unsigned char *()

PString::operator const unsigned char * | ( |  | ) | const

Get the internal buffer as a pointer to unsigned characters.

The standard "operator const char *" function is provided by the `PCharArray` ancestor class.

Returns
  pointer to character buffer.

## operator std::string()

PString::operator std::string | ( |  | ) | const

inline

Cast the PString to a std::string.

References InternalCompare(), InternalFromUCS2(), PString(), and PAbstractArray::theArray.

## operator!()

bool PString::operator! | ( |  | ) | const

Determine if the string is NOT empty.

This is semantically identical to executing !IsEmpty() on the string.

Returns
  true if non-null characters in string.

Referenced by operator=().

## operator!=() [1/2]

bool PString::operator!= | ( | const PObject & | str | ) | const

Compare two strings using the `PObject::Compare()` function.

This is identical to the `PObject` class function but is necessary due to other overloaded versions.

Returns
  true if not equal.

Parameters

  str | PString object to compare against.

Referenced by operator=().

## operator!=() [2/2]

bool PString::operator!= | ( | const char * | cstr | ) | const

Compare a PString to a C string using the `PObject::Compare()` function.

The `cstr` parameter is typically a literal string, eg:

              if (myStr != "fred")

       @return
       true if not equal.

Parameters

  cstr | C string to compare against.

## operator()()

PString PString::operator() | ( | PINDEX | start,
|  | PINDEX | end
| ) |  | const

Extract a portion of the string into a new string.

The original string is not changed and a new unique reference to a string is returned.

The substring is returned inclusive of the characters at the `start` and `end` positions.

If the `end` position is greater than the length of the string then all characters from the `start` up to the end of the string are returned.

If `start` is greater than the length of the string or `end` is before `start` then an empty string is returned.

Returns
  substring of the source string.

Parameters

  start | Starting position of the substring.
  end | Ending position of the substring.

Referenced by operator=().

## operator*=() [1/2]

bool PString::operator*= | ( | const PString & | str | ) | const

Compare two strings using case insensitive comparison.

Returns
  true if equal.

Parameters

  str | PString object to compare against.

Referenced by operator=().

## operator*=() [2/2]

bool PString::operator*= | ( | const char * | cstr | ) | const

Compare a PString to a C string using a case insensitive compare function.

The `cstr` parameter is typically a literal string, eg:

              if (myStr == "fred")

       @return
       true if equal.

Parameters

  cstr | C string to compare against.

## operator+() [1/3]

PString PString::operator+ | ( | const PString & | str | ) | const

Concatenate two strings to produce a third.

The original strings are not modified, an entirely new unique reference to a string is created.

Returns
  new string with concatenation of the object and parameter.

Parameters

  str | String to concatenate.

Referenced by PStringArray::container(), and operator=().

## operator+() [2/3]

PString PString::operator+ | ( | const char * | cstr | ) | const

Concatenate a C string to a PString to produce a third.

The original string is not modified, an entirely new unique reference to a string is created. The `cstr` parameter is typically a literal string, eg:

              myStr = aStr + "fred";

       @return
       new string with concatenation of the object and parameter.

Parameters

  cstr | C string to concatenate.

## operator+() [3/3]

PString PString::operator+ | ( | char | ch | ) | const

Concatenate a single character to a PString to produce a third.

The original string is not modified, an entirely new unique reference to a string is created. The `ch` parameter is typically a literal, eg:

              myStr = aStr + '!';

       @return
       new string with concatenation of the object and parameter.

Parameters

  ch | Character to concatenate.

## operator+=() [1/3]

PString& PString::operator+= | ( | const PString & | str | ) |

Concatenate a string to another string, modifiying that string.

Returns
  reference to string that was concatenated to.

Parameters

  str | String to concatenate.

Referenced by PStringArray::container(), and operator=().

## operator+=() [2/3]

PString& PString::operator+= | ( | const char * | cstr | ) |

Concatenate a C string to a PString, modifiying that string.

The `cstr` parameter is typically a literal string, eg:

              myStr += "fred";

       @return
       reference to string that was concatenated to.

Parameters

  cstr | C string to concatenate.

## operator+=() [3/3]

PString& PString::operator+= | ( | char | ch | ) |

Concatenate a single character to a PString.

The `ch` parameter is typically a literal, eg:

              myStr += '!';

       @return
       new string with concatenation of the object and parameter.

Parameters

  ch | Character to concatenate.

## operator<() [1/2]

bool PString::operator< | ( | const PObject & | str | ) | const

Compare two strings using the `PObject::Compare()` function.

This is identical to the `PObject` class function but is necessary due to other overloaded versions.

Returns
  true if less than.

Parameters

  str | PString object to compare against.

Referenced by operator=().

## operator<() [2/2]

bool PString::operator< | ( | const char * | cstr | ) | const

Compare a PString to a C string using the `PObject::Compare()` function.

The `cstr` parameter is typically a literal string, eg:

              if (myStr < "fred")

       @return
       true if less than.

Parameters

  cstr | C string to compare against.

## operator<=() [1/2]

bool PString::operator<= | ( | const PObject & | str | ) | const

Compare two strings using the `PObject::Compare()` function.

This is identical to the `PObject` class function but is necessary due to other overloaded versions.

Returns
  true if less than or equal.

Parameters

  str | PString object to compare against.

Referenced by operator=().

## operator<=() [2/2]

bool PString::operator<= | ( | const char * | cstr | ) | const

Compare a PString to a C string using the `PObject::Compare()` function.

The `cstr` parameter is typically a literal string, eg:

              if (myStr <= "fred")

       @return
       true if less than or equal.

Parameters

  cstr | C string to compare against.

## operator=() [1/12]

PString& PString::operator= | ( | const PString & | str | ) |

Assign the string to the current object.

The current instance then becomes another reference to the same string in the `str` parameter.

Returns
  reference to the current PString object.

Parameters

  str | New string to assign.

Referenced by PConstantString< ParentString >::DestroyReference(), operator<<(), operator=(), PCaselessString::operator=(), and PCaselessString::PCaselessString().

## operator=() [2/12]

PString& PString::operator= | ( | const std::string & | str | ) |

inline

Assign the string to the current object.

The current instance then becomes another reference to the same string in the `str` parameter.

Returns
  reference to the current PString object.

Parameters

  str | New string to assign.

References AsInt64(), AsInteger(), AsReal(), AsUCS2(), AsUnsigned(), AsUnsigned64(), Clone(), Compare(), Delete(), Empty(), Find(), FindLast(), FindOneOf(), FindRegEx(), FindSpan(), GetLength(), HashFunction(), IsEmpty(), Left(), LeftTrim(), Lines(), MakeEmpty(), MakeMinimumSize(), MakeUnique(), MatchesRegEx(), Mid(), NumCompare(), operator &(), operator &=(), operator!(), operator!=(), operator()(), operator*=(), operator+(), operator+=(), operator<(), operator<=(), operator=(), operator==(), operator>(), operator>=(), PINLINE, PrintOn(), psprintf, pvsprintf, ReadFrom(), Replace(), Right(), RightTrim(), SetSize(), Splice(), sprintf(), Tokenise(), ToLiteral(), ToLower(), ToPascal(), ToUpper(), Trim(), and vsprintf().

## operator=() [3/12]

PString& PString::operator= | ( | const char * | cstr | ) |

Assign the C string to the current object.

The current instance then becomes a unique reference to a copy of the `cstr` parameter. The `cstr` parameter is typically a literal string, eg:

              myStr = "fred";

Returns
  reference to the current PString object.

Parameters

  cstr | C string to assign.

## operator=() [4/12]

PString& PString::operator= | ( | char | ch | ) |

Assign the character to the current object.

The current instance then becomes a unique reference to a copy of the character parameter. eg:

              myStr = 'A';

Returns
  reference to the current PString object.

Parameters

  ch | Character to assign.

## operator=() [5/12]

PString& PString::operator= | ( | short | n | ) |

Assign a string from the integer type.

This will create a simple base 10, shortest length conversion of the integer (with sign character if appropriate) into the string.

Parameters

  n | Integer to convert

## operator=() [6/12]

PString& PString::operator= | ( | unsigned short | n | ) |

Assign a string from the integer type.

This will create a simple base 10, shortest length conversion of the integer (with sign character if appropriate) into the string.

Parameters

  n | Integer to convert

## operator=() [7/12]

PString& PString::operator= | ( | int | n | ) |

Assign a string from the integer type.

This will create a simple base 10, shortest length conversion of the integer (with sign character if appropriate) into the string.

Parameters

  n | Integer to convert

## operator=() [8/12]

PString& PString::operator= | ( | unsigned int | n | ) |

Assign a string from the integer type.

This will create a simple base 10, shortest length conversion of the integer (with sign character if appropriate) into the string.

Parameters

  n | Integer to convert

## operator=() [9/12]

PString& PString::operator= | ( | long | n | ) |

Assign a string from the integer type.

This will create a simple base 10, shortest length conversion of the integer (with sign character if appropriate) into the string.

Parameters

  n | Integer to convert

## operator=() [10/12]

PString& PString::operator= | ( | unsigned long | n | ) |

Assign a string from the integer type.

This will create a simple base 10, shortest length conversion of the integer (with sign character if appropriate) into the string.

Parameters

  n | Integer to convert

## operator=() [11/12]

PString& PString::operator= | ( | PInt64 | n | ) |

Assign a string from the integer type.

This will create a simple base 10, shortest length conversion of the integer (with sign character if appropriate) into the string.

Parameters

  n | Integer to convert

## operator=() [12/12]

PString& PString::operator= | ( | PUInt64 | n | ) |

Assign a string from the integer type.

This will create a simple base 10, shortest length conversion of the integer (with sign character if appropriate) into the string.

Parameters

  n | Integer to convert

## operator==() [1/2]

bool PString::operator== | ( | const PObject & | str | ) | const

Compare two strings using the `PObject::Compare()` function.

This is identical to the `PObject` class function but is necessary due to other overloaded versions.

Returns
  true if equal.

Parameters

  str | PString object to compare against.

Referenced by operator=().

## operator==() [2/2]

bool PString::operator== | ( | const char * | cstr | ) | const

Compare a PString to a C string using the `Compare()` function.

The `cstr` parameter is typically a literal string, eg:

              if (myStr == "fred")

       @return
       true if equal.

Parameters

  cstr | C string to compare against.

## operator>() [1/2]

bool PString::operator> | ( | const PObject & | str | ) | const

Compare two strings using the `PObject::Compare()` function.

This is identical to the `PObject` class function but is necessary due to other overloaded versions.

Returns
  true if greater than.

Parameters

  str | PString object to compare against.

Referenced by operator=().

## operator>() [2/2]

bool PString::operator> | ( | const char * | cstr | ) | const

Compare a PString to a C string using the `PObject::Compare()` function.

The `cstr` parameter is typically a literal string, eg:

              if (myStr > "fred")

       @return
       true if greater than.

Parameters

  cstr | C string to compare against.

## operator>=() [1/2]

bool PString::operator>= | ( | const PObject & | str | ) | const

Compare two strings using the `PObject::Compare()` function.

This is identical to the `PObject` class function but is necessary due to other overloaded versions.

Returns
  true if greater than or equal.

Parameters

  str | PString object to compare against.

Referenced by operator=().

## operator>=() [2/2]

bool PString::operator>= | ( | const char * | cstr | ) | const

Compare a PString to a C string using the `PObject::Compare()` function.

The `cstr` parameter is typically a literal string, eg:

              if (myStr >= "fred")

       @return
       true if greater than or equal.

Parameters

  cstr | C string to compare against.

## PrintOn()

virtual void PString::PrintOn | ( | ostream & | strm | ) | const

virtual

Output the string to the specified stream.

Parameters

  strm | I/O stream to output to.

Reimplemented from PCharArray.

Reimplemented in PvCard::TextValue, PvCard::ParamValue, and PvCard::Token.

Referenced by operator=().

## ReadFrom()

virtual void PString::ReadFrom | ( | istream & | strm | ) |

virtual

Input the string from the specified stream.

This will read all characters until a end of line is reached. The end of line itself is not placed in the string, however it is removed from the stream.

Parameters

  strm | I/O stream to input from.

Reimplemented from PCharArray.

Reimplemented in PvCard::TextValue, PvCard::ParamValue, and PvCard::Token.

Referenced by PStringArray::container(), and operator=().

## Replace()

void PString::Replace | ( | const PString & | target,
|  | const PString & | subs,
|  | PBoolean | all = `false`,
|  | PINDEX | offset = `0`
| ) |  |

Locate the substring within the string and replace it with the specifed substring.

The search will begin at the character offset provided.

If `offset` is beyond the length of the string, then the function will do nothing.

The matching will be for identical character or string. If a search ignoring case is required then the string should be converted to a PCaselessString before the search is made.

Parameters

  target | Text to be removed.
  subs | String to be inserted into the gaps created
  all | Replace all occurrences of target text.
  offset | Offset into string to begin search.

Referenced by operator=().

## Right()

PString PString::Right | ( | PINDEX | len | ) | const

Extract a portion of the string into a new string.

The original string is not changed and a new unique reference to a string is returned.

A substring from the end of the string for the number of characters specified is extracted.

If `len` is greater than the length of the string then all characters to the beginning of the string are returned.

If `len` is zero then an empty string is returned.

Returns
  substring of the source string.

Parameters

  len | Number of characters to extract.

Referenced by operator=(), and PLoadPluginDirectory().

## RightTrim()

PString PString::RightTrim | ( |  | ) | const

Create a string consisting of all characters from the source string except all spaces at the end of the string.

The original string is not changed and a new unique reference to a string is returned.

Returns
  string with trailing spaces removed.

Referenced by operator=().

## SetSize()

virtual PBoolean PString::SetSize | ( | PINDEX | newSize | ) |

virtual

Set the size of the string.

A new string may be allocated to accomodate the new number of characters. If the string increases in size then the new characters are initialised to zero. If the string is made smaller then the data beyond the new size is lost.

Note that this function will break the current instance from multiple references to an array. A new array is allocated and the data from the old array copied to it.

Returns
  true if the memory for the array was allocated successfully.

Parameters

  newSize | New size of the array in elements.

Reimplemented from PAbstractArray.

Referenced by operator=().

## Splice() [1/2]

void PString::Splice | ( | const PString & | str,
|  | PINDEX | pos,
|  | PINDEX | len = `0`
| ) |  |

Splice the string into the current string at the specified position.

The specified number of bytes are removed from the string.

Note that this function will break the current instance from multiple references to the string. A new string buffer is allocated and the data from the old string buffer copied to it.

Parameters

  str | Substring to insert.
  pos | Position in string to insert the substring.
  len | Length of section to remove.

Referenced by operator=().

## Splice() [2/2]

void PString::Splice | ( | const char * | cstr,
|  | PINDEX | pos,
|  | PINDEX | len = `0`
| ) |  |

Splice the string into the current string at the specified position.

The specified number of bytes are removed from the string.

Note that this function will break the current instance from multiple references to the string. A new string buffer is allocated and the data from the old string buffer copied to it.

Parameters

  cstr | Substring to insert.
  pos | Position in string to insert the substring.
  len | Length of section to remove.

## sprintf()

PString& PString::sprintf | ( | const char * | cfmt,
|  |  | ...
| ) |  |

Concatenate a formatted output to the string.

This is identical to the standard C library `sprintf()` function, but appends its output to the string.

This function makes the assumption that there is less the 1000 characters of formatted output. The function will assert if this occurs.

Note that this function will break the current instance from multiple references to the string. A new string buffer is allocated and the data from the old string buffer copied to it.

Returns
  reference to the current string object.

Parameters

  cfmt | C string for output format.

Referenced by operator=().

## Tokenise() [1/2]

PStringArray PString::Tokenise | ( | const PString & | separators,
|  | PBoolean | onePerSeparator = `true`
| ) |  | const

Split the string into an array of substrings.

Parameters

  separators | A string for the set of separator characters that delimit tokens.
  onePerSeparator | Flag for if there are empty tokens between consecutive separators.

Referenced by operator=().

## Tokenise() [2/2]

PStringArray PString::Tokenise | ( | const char * | cseparators,
|  | PBoolean | onePerSeparator = `true`
| ) |  | const

Split the string into an array of substrings.

Divide the string into an array of substrings delimited by characters from the specified set.

There are two options for the tokenisation, the first is where the `onePerSeparator` is true. This form will produce a token for each delimiter found in the set. Thus the string ",two,three,,five" would be split into 5 substrings; "", "two", "three", "" and "five".

The second form where `onePerSeparator` is false is used where consecutive delimiters do not constitute a empty token. In this case the string " a list of words " would be split into 5 substrings; "a", "list", "of", "words" and "".

There is an important distinction when there are delimiters at the beginning or end of the source string. In the first case there will be empty strings at the end of the array. In the second case delimeters at the beginning of the source string are ignored and if there are one or more trailing delimeters, they will yeild a single empty string at the end of the array.

Returns
  an array of substring for each token in the string.

Parameters

  cseparators | A C string for the set of separator characters that delimit tokens.
  onePerSeparator | Flag for if there are empty tokens between consecutive separators.

## ToLiteral()

PString PString::ToLiteral | ( |  | ) | const

Convert the string to C literal string format.

This will convert non printable characters to the \nnn form or for standard control characters such as line feed, to \n form. Any '"' characters are also escaped with a \ character and the entire string is enclosed in '"' characters.

Returns
  string converted to a C language literal form.

Referenced by operator=().

## ToLower()

PString PString::ToLower | ( |  | ) | const

Create a string consisting of all characters from the source string with all upper case letters converted to lower case.

The original string is not changed and a new unique reference to a string is returned.

Returns
  string with upper case converted to lower case.

Referenced by operator=().

## ToPascal()

PBYTEArray PString::ToPascal | ( |  | ) | const

Convert a standard null terminated string to a "pascal" style string.

This consists of a songle byte for the length of the string and then the string characters following it.

This function will assert if the string is greater than 255 characters in length.

Returns
  byte array containing the "pascal" style string.

Referenced by operator=().

## ToUpper()

PString PString::ToUpper | ( |  | ) | const

Create a string consisting of all characters from the source string with all lower case letters converted to upper case.

The original string is not changed and a new unique reference to a string is returned.

Returns
  string with lower case converted to upper case.

Referenced by operator=().

## Trim()

PString PString::Trim | ( |  | ) | const

Create a string consisting of all characters from the source string except all spaces at the beginning and end of the string.

The original string is not changed and a new unique reference to a string is returned.

Returns
  string with leading and trailing spaces removed.

Referenced by operator=().

## vsprintf() [1/2]

PString& PString::vsprintf | ( | const PString & | fmt,
|  | va_list | args
| ) |  |

Concatenate a formatted output to the string.

Parameters

  fmt | String for output format.
  args | Extra parameters for `sprintf()` call.

Referenced by operator=().

## vsprintf() [2/2]

PString& PString::vsprintf | ( | const char * | cfmt,
|  | va_list | args
| ) |  |

Concatenate a formatted output to the string.

This is identical to the standard C library `vsprintf()` function, but appends its output to the string.

This function makes the assumption that there is less the 1000 characters of formatted output. The function will assert if this occurs.

Note that this function will break the current instance from multiple references to the string. A new string buffer is allocated and the data from the old string buffer copied to it.

Returns
  reference to the current string object.

Parameters

  cfmt | C string for output format.
  args | Extra parameters for `sprintf()` call.

## Friends And Related Function Documentation

## operator & [1/2]

PString operator& | ( | const char * | cstr,
|  | const PString & | str
| ) |  |

friend

Concatenate a PString to a C string to produce a third.

The original string is not modified, an entirely new unique reference to a string is created. The `cstr` parameter is typically a literal string, eg:

              myStr = "fred" & aStr;

       This function differes from operator+ in that it assures there is at
       least one space between the strings. Exactly one space is added if
       there is not a space at the end of the first or beggining of the last
       string.

       @return
       new string with concatenation of the object and parameter.

Parameters

  cstr | C string to be concatenated to.
  str | String to concatenate.

## operator & [2/2]

PString operator& | ( | char | ch,
|  | const PString & | str
| ) |  |

friend

Concatenate a PString to a single character to produce a third.

The original string is not modified, an entirely new unique reference to a string is created. The `c` parameter is typically a literal, eg:

              myStr = '!' & aStr;

       This function differs from <code>operator+</code> in that it assures there is at
       least one space between the strings. Exactly one space is added if
       there is not a space at the end of the first or beggining of the last
       string.

       @return
       new string with concatenation of the object and parameter.

Parameters

  ch | Character to be concatenated to.
  str | String to concatenate.

## operator+ [1/2]

PString operator+ | ( | const char * | cstr,
|  | const PString & | str
| ) |  |

friend

Concatenate a PString to a C string to produce a third.

The original string is not modified, an entirely new unique reference to a string is created. The `cstr` parameter is typically a literal string, eg:

              myStr = "fred" + aStr;

       @return
       new string with concatenation of the object and parameter.

Parameters

  cstr | C string to be concatenated to.
  str | String to concatenate.

## operator+ [2/2]

PString operator+ | ( | char | ch,
|  | const PString & | str
| ) |  |

friend

Concatenate a PString to a single character to produce a third.

The original string is not modified, an entirely new unique reference to a string is created. The `ch` parameter is typically a literal, eg:

              myStr = '!' + aStr;

       @return
       new string with concatenation of the object and parameter.

Parameters

  ch | Character to be concatenated to.
  str | String to concatenate.

## psprintf

PString psprintf | ( | const char * | cfmt,
|  |  | ...
| ) |  |

friend

Produce formatted output as a string.

This is identical to the standard C library `sprintf()` function, but sends its output to a `PString`.

This function makes the assumption that there is less the 1000 characters of formatted output. The function will assert if this occurs.

Note that this function will break the current instance from multiple references to the string. A new string buffer is allocated and the data from the old string buffer copied to it.

Returns
  reference to the current string object.

Parameters

  cfmt | C string for output format.

Referenced by operator=().

## pvsprintf [1/2]

PString pvsprintf | ( | const char * | cfmt,
|  | va_list | args
| ) |  |

friend

Produce formatted output as a string.

Parameters

  cfmt | C string for output format.
  args | Extra parameters for `sprintf()` call.

Referenced by operator=().

## pvsprintf [2/2]

PString pvsprintf | ( | const PString & | fmt,
|  | va_list | args
| ) |  |

friend

Produce formatted output as a string.

This is identical to the standard C library `vsprintf()` function, but sends its output to a `PString`.

This function makes the assumption that there is less the 1000 characters of formatted output. The function will assert if this occurs.

Note that this function will break the current instance from multiple references to the string. A new string buffer is allocated and the data from the old string buffer copied to it.

Returns
  reference to the current string object.

Parameters

  fmt | String for output format.
  args | Extra parameters for `sprintf()` call.

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

- pstring.h