PTLib  Version 2.10.10
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
PString Class Reference

The character string class. More...

#include <pstring.h>

Inheritance diagram for PString:
PCharArray PBaseArray< T > PAbstractArray PContainer PObject PCaselessString PFilePathString PHTTPSpace::Node PSOAPServerMethod PStringStream PvCard::ParamValue PvCard::TextValue PXMLRPCServerMethod

Public Types

typedef const char * Initialiser
 

Public Member Functions

Overrides from class PObject
virtual PObjectClone () 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...
 
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...
 
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...
 
PContaineroperator= (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)
 

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)
 
PStringoperator= (const PString &str)
 Assign the string to the current object. More...
 
PStringoperator= (const std::string &str)
 Assign the string to the current object. More...
 
PStringoperator= (const char *cstr)
 Assign the C string to the current object. More...
 
PStringoperator= (char ch)
 Assign the character to the current object. More...
 
PStringoperator= (short n)
 Assign a string from the integer type. More...
 
PStringoperator= (unsigned short n)
 Assign a string from the integer type. More...
 
PStringoperator= (int n)
 Assign a string from the integer type. More...
 
PStringoperator= (unsigned int n)
 Assign a string from the integer type. More...
 
PStringoperator= (long n)
 Assign a string from the integer type. More...
 
PStringoperator= (unsigned long n)
 Assign a string from the integer type. More...
 
PStringoperator= (PInt64 n)
 Assign a string from the integer type. More...
 
PStringoperator= (PUInt64 n)
 Assign a string from the integer type. More...
 
virtual PStringMakeEmpty ()
 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...
 
PStringoperator+= (const PString &str)
 Concatenate a string to another string, modifiying that string. More...
 
PStringoperator+= (const char *cstr)
 Concatenate a C string to a PString, modifiying that string. More...
 
PStringoperator+= (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...
 
PStringoperator&= (const PString &str)
 Concatenate a string to another string, modifiying that string. More...
 
PStringoperator&= (const char *cstr)
 Concatenate a C string to a PString, modifiying that string. More...
 
PStringoperator&= (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

PStringsprintf (const char *cfmt,...)
 Concatenate a formatted output to the string. More...
 
PStringvsprintf (const PString &fmt, va_list args)
 Concatenate a formatted output to the string. More...
 
PStringvsprintf (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...
 
- Friends inherited from PObject

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

typedef const char* PString::Initialiser

Member Enumeration Documentation

Enumerator
Pascal 
Basic 
Literal 
Signed 
Unsigned 
Decimal 
Exponent 
Printf 
NumConversionTypes 

Constructor & Destructor Documentation

PINLINE PString::PString ( )

Construct an empty string.

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

Referenced by PHTML::operator=().

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
strString to create new reference to.
PINLINE PString::PString ( const std::string &  str)

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

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
cstrStandard '\0' terminated C string.
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
ustrUCS-2 null terminated string.
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
cstrPointer to a string of characters.
lenLength of the string in bytes.
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
ustrPointer to a string of UCS-2 characters.
lenLength of the string in bytes.
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
ustrUCS-2 null terminated string.
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
chSingle character to initialise string.
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
nInteger to convert
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
nInteger to convert
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
nInteger to convert
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
nInteger to convert
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
nInteger to convert
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
nInteger to convert
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
nInteger to convert
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
nInteger to convert
PString::PString ( ConversionType  type,
const char *  str,
  ... 
)
Parameters
typeType of data source for conversion.
strString to convert.
PString::PString ( ConversionType  type,
long  value,
unsigned  base = 10 
)
Parameters
typeType of data source for conversion.
valueInteger value to convert.
baseNumber base to use for the integer conversion.
PString::PString ( ConversionType  type,
double  value,
unsigned  places 
)
Parameters
typeType of data source for conversion.
valueFloating point value to convert.
placesNumber of decimals in real number output.
PString::PString ( int  dummy,
const PString str 
)
protected
PString::PString ( PContainerReference reference)
inlineprotected

Member Function Documentation

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
baseNumber base to convert the string in.
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
baseNumber base to convert the string in.
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.
PWCharArray PString::AsUCS2 ( ) const

Convert UTF-8 string to UCS-2.

Note the resultant PWCharArray will have the trailing null included.

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

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
baseNumber base to convert the string in.
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
baseNumber base to convert the string in.
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.

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
objOther PString to compare against.

Reimplemented from PAbstractArray.

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
startPosition in string to remove.
lenNumber of characters to delete.
static PString PString::Empty ( )
static

Return an empty string.

Referenced by PHTTPClientAuthentication::GetAuthRealm(), and XMPP::BareJID::GetResource().

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

Locate the position within the string of the character.

Parameters
chCharacter to search for in string.
offsetOffset into string to begin search.
PINDEX PString::Find ( const PString str,
PINDEX  offset = 0 
) const

Locate the position within the string of the substring.

Parameters
strString to search for in string.
offsetOffset into string to begin search.
PINDEX PString::Find ( const char *  cstr,
PINDEX  offset = 0 
) const
Parameters
cstrC string to search for in string.
offsetOffset into string to begin search.
PINDEX PString::FindLast ( char  ch,
PINDEX  offset = P_MAX_INDEX 
) const

Locate the position of the last matching character.

Parameters
chCharacter to search for in string.
offsetOffset into string to begin search.
PINDEX PString::FindLast ( const PString str,
PINDEX  offset = P_MAX_INDEX 
) const

Locate the position of the last matching substring.

Parameters
strString to search for in string.
offsetOffset into string to begin search.
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
cstrC string to search for in string.
offsetOffset into string to begin search.
PINDEX PString::FindOneOf ( const PString set,
PINDEX  offset = 0 
) const

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

Parameters
setString of characters to search for in string.
offsetOffset into string to begin search.
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
csetC string of characters to search for in string.
offsetOffset into string to begin search.
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
regexregular expression to find
offsetOffset into string to begin search.
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
regexregular expression to find
posPosition of matched expression
lenLength of matched expression
offsetOffset into string to begin search.
maxPosMaximum offset into string
PINDEX PString::FindSpan ( const PString set,
PINDEX  offset = 0 
) const

Locate the position of character not in the set.

Parameters
setString of characters to search for in string.
offsetOffset into string to begin search.
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
csetC string of characters to search for in string.
offsetOffset into string to begin search.
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.
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.

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

Reimplemented in PCaselessString.

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

Reimplemented in PCaselessString.

void PString::InternalFromUCS2 ( const wchar_t *  ptr,
PINDEX  len 
)
protected
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(), and PDNS::Lookup().

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
lenNumber of characters to extract.
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.
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.
virtual PString& PString::MakeEmpty ( )
virtual

Make the current string empty.

Reimplemented in PStringStream.

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

PBoolean PString::MatchesRegEx ( const PRegularExpression regex) const

Return true if the entire string matches the regular expression.

Parameters
regexregular expression to match
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
startStarting position of the substring.
lenNumber of characters to extract.
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
strPString object to compare against.
countNumber of chacracters in str to compare
offsetOffset into string to compare
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
cstrC string object to compare against.
countNumber of chacracters in str to compare
offsetOffset into string to compare
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.
PString::operator std::string ( ) const
inline

Cast the PString to a std::string.

References PAbstractArray::theArray.

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.
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
strPString object to compare against.
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")
Returns
true if not equal.
Parameters
cstrC string to compare against.
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
strString to concatenate.
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.
Returns
new string with concatenation of the object and parameter.
Parameters
cstrC string to concatenate.
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.
Returns
new string with concatenation of the object and parameter.
Parameters
chCharacter to concatenate.
PString& PString::operator&= ( const PString str)

Concatenate a string to another string, modifiying that string.

Returns
reference to string that was concatenated to.
Parameters
strString to concatenate.
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.
Returns
reference to string that was concatenated to.
Parameters
cstrC string to concatenate.
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.
Returns
reference to string that was concatenated to.
Parameters
chCharacter to concatenate.
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
startStarting position of the substring.
endEnding position of the substring.
bool PString::operator*= ( const PString str) const

Compare two strings using case insensitive comparison.

Returns
true if equal.
Parameters
strPString object to compare against.
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")
Returns
true if equal.
Parameters
cstrC string to compare against.
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
strString to concatenate.
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";
Returns
new string with concatenation of the object and parameter.
Parameters
cstrC string to concatenate.
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 + '!';
Returns
new string with concatenation of the object and parameter.
Parameters
chCharacter to concatenate.
PString& PString::operator+= ( const PString str)

Concatenate a string to another string, modifiying that string.

Returns
reference to string that was concatenated to.
Parameters
strString to concatenate.
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";
Returns
reference to string that was concatenated to.
Parameters
cstrC string to concatenate.
PString& PString::operator+= ( char  ch)

Concatenate a single character to a PString.

The ch parameter is typically a literal, eg:


          myStr += '!';
Returns
new string with concatenation of the object and parameter.
Parameters
chCharacter to concatenate.
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
strPString object to compare against.
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")
Returns
true if less than.
Parameters
cstrC string to compare against.
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
strPString object to compare against.
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")
Returns
true if less than or equal.
Parameters
cstrC string to compare against.
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
strNew string to assign.
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
strNew string to assign.

References operator=().

Referenced by operator=().

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
cstrC string to assign.
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
chCharacter to assign.
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
nInteger to convert
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
nInteger to convert
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
nInteger to convert
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
nInteger to convert
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
nInteger to convert
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
nInteger to convert
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
nInteger to convert
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
nInteger to convert
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
strPString object to compare against.
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")
Returns
true if equal.
Parameters
cstrC string to compare against.
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
strPString object to compare against.
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")
Returns
true if greater than.
Parameters
cstrC string to compare against.
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
strPString object to compare against.
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")
Returns
true if greater than or equal.
Parameters
cstrC string to compare against.
virtual void PString::PrintOn ( ostream &  strm) const
virtual

Output the string to the specified stream.

Parameters
strmI/O stream to output to.

Reimplemented from PCharArray.

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

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
strmI/O stream to input from.

Reimplemented from PCharArray.

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

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
targetText to be removed.
subsString to be inserted into the gaps created
allReplace all occurrences of target text.
offsetOffset into string to begin search.
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
lenNumber of characters to extract.

Referenced by PLoadPluginDirectory().

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.
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
newSizeNew size of the array in elements.

Reimplemented from PAbstractArray.

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
strSubstring to insert.
posPosition in string to insert the substring.
lenLength of section to remove.
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
cstrSubstring to insert.
posPosition in string to insert the substring.
lenLength of section to remove.
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
cfmtC string for output format.
PStringArray PString::Tokenise ( const PString separators,
PBoolean  onePerSeparator = true 
) const

Split the string into an array of substrings.

Parameters
separatorsA string for the set of separator characters that delimit tokens.
onePerSeparatorFlag for if there are empty tokens between consecutive separators.
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
cseparatorsA C string for the set of separator characters that delimit tokens.
onePerSeparatorFlag for if there are empty tokens between consecutive separators.
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.
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.
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.
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.
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.
PString& PString::vsprintf ( const PString fmt,
va_list  args 
)

Concatenate a formatted output to the string.

Parameters
fmtString for output format.
argsExtra parameters for sprintf() call.
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
cfmtC string for output format.
argsExtra parameters for sprintf() call.

Friends And Related Function Documentation

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.
Returns
new string with concatenation of the object and parameter.
Parameters
cstrC string to be concatenated to.
strString to concatenate.
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.
Returns
new string with concatenation of the object and parameter.
Parameters
chCharacter to be concatenated to.
strString to concatenate.
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;
Returns
new string with concatenation of the object and parameter.
Parameters
cstrC string to be concatenated to.
strString to concatenate.
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;
Returns
new string with concatenation of the object and parameter.
Parameters
chCharacter to be concatenated to.
strString to concatenate.
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
cfmtC string for output format.
PString pvsprintf ( const char *  cfmt,
va_list  args 
)
friend

Produce formatted output as a string.

Parameters
cfmtC string for output format.
argsExtra parameters for sprintf() call.
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
fmtString for output format.
argsExtra parameters for sprintf() call.

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