PString Class Reference

#include <pstring.h>

Inheritance diagram for PString:

List of all members.

Construction
enum	ConversionType {   Pascal, Basic, Literal, Signed,   Unsigned, Decimal, Exponent, Printf,   NumConversionTypes }
PINLINE	PString ()
PINLINE	PString (const PString &str)
PINLINE	PString (const std::string &str)
	PString (const char *cstr)
	PString (const wchar_t *ustr)
	PString (const char *cstr, PINDEX len)
	PString (const wchar_t *ustr, PINDEX len)
	PString (const PWCharArray &ustr)
	PString (char ch)
	PString (short n)
	PString (unsigned short n)
	PString (int n)
	PString (unsigned int n)
	PString (long n)
	PString (unsigned long n)
	PString (PInt64 n)
	PString (PUInt64 n)
	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)
PString &	operator= (const char *cstr)
PString &	operator= (char ch)
PString &	operator= (short n)
PString &	operator= (unsigned short n)
PString &	operator= (int n)
PString &	operator= (unsigned int n)
PString &	operator= (long n)
PString &	operator= (unsigned long n)
PString &	operator= (PInt64 n)
PString &	operator= (PUInt64 n)
virtual PString &	MakeEmpty ()
static PString	Empty ()
Concatenation operators
PString	operator+ (const PString &str) const
PString	operator+ (const char *cstr) const
PString	operator+ (char ch) const
PString &	operator+= (const PString &str)
PString &	operator+= (const char *cstr)
PString &	operator+= (char ch)
PString	operator & (const PString &str) const
PString	operator & (const char *cstr) const
PString	operator & (char ch) const
PString &	operator &= (const PString &str)
PString &	operator &= (const char *cstr)
PString &	operator &= (char ch)
PString	operator+ (const char *cstr, const PString &str)
PString	operator+ (char c, const PString &str)
PString	operator & (const char *cstr, const PString &str)
PString	operator & (char ch, const PString &str)
Conversion functions
PString &	sprintf (const char *cfmt,...)
PString &	vsprintf (const PString &fmt, va_list args)
PString &	vsprintf (const char *cfmt, va_list args)
long	AsInteger (unsigned base=10) const
DWORD	AsUnsigned (unsigned base=10) const
PInt64	AsInt64 (unsigned base=10) const
PUInt64	AsUnsigned64 (unsigned base=10) const
double	AsReal () const
PWCharArray	AsUCS2 () const
PBYTEArray	ToPascal () const
PString	ToLiteral () const
	operator const unsigned char * () const
	operator std::string () const
PString	psprintf (const char *cfmt,...)
PString	pvsprintf (const char *cfmt, va_list args)
PString	pvsprintf (const PString &fmt, va_list args)
Public Member Functions
Overrides from class PObject
virtual PObject *	Clone () const
virtual Comparison	Compare (const PObject &obj) const
virtual void	PrintOn (ostream &strm) const
virtual void	ReadFrom (istream &strm)
virtual PINDEX	HashFunction () const
Overrides from class PContainer
virtual PBoolean	SetSize (PINDEX newSize)
virtual PBoolean	IsEmpty () const
virtual PBoolean	MakeUnique ()
Size/Length functions
PBoolean	MakeMinimumSize ()
PINLINE PINDEX	GetLength () const
bool	operator! () const
Comparison operators
bool	operator *= (const PString &str) const
bool	operator== (const PObject &str) const
bool	operator!= (const PObject &str) const
bool	operator< (const PObject &str) const
bool	operator> (const PObject &str) const
bool	operator<= (const PObject &str) const
bool	operator>= (const PObject &str) const
bool	operator *= (const char *cstr) const
bool	operator== (const char *cstr) const
bool	operator!= (const char *cstr) const
bool	operator< (const char *cstr) const
bool	operator> (const char *cstr) const
bool	operator<= (const char *cstr) const
bool	operator>= (const char *cstr) const
Comparison	NumCompare (const PString &str, PINDEX count=P_MAX_INDEX, PINDEX offset=0) const
Comparison	NumCompare (const char *cstr, PINDEX count=P_MAX_INDEX, PINDEX offset=0) const
Search & replace functions
PINDEX	Find (char ch, PINDEX offset=0) const
PINDEX	Find (const PString &str, PINDEX offset=0) const
PINDEX	Find (const char *cstr, PINDEX offset=0) const
PINDEX	FindLast (char ch, PINDEX offset=P_MAX_INDEX) const
PINDEX	FindLast (const PString &str, PINDEX offset=P_MAX_INDEX) const
PINDEX	FindLast (const char *cstr, PINDEX offset=P_MAX_INDEX) const
PINDEX	FindOneOf (const PString &set, PINDEX offset=0) const
PINDEX	FindOneOf (const char *cset, PINDEX offset=0) const
PINDEX	FindSpan (const PString &set, PINDEX offset=0) const
PINDEX	FindSpan (const char *cset, PINDEX offset=0) const
PINDEX	FindRegEx (const PRegularExpression &regex, PINDEX offset=0) const
PBoolean	FindRegEx (const PRegularExpression &regex, PINDEX &pos, PINDEX &len, PINDEX offset=0, PINDEX maxPos=P_MAX_INDEX) const
void	Replace (const PString &target, const PString &subs, PBoolean all=PFalse, PINDEX offset=0)
void	Splice (const PString &str, PINDEX pos, PINDEX len=0)
void	Splice (const char *cstr, PINDEX pos, PINDEX len=0)
void	Delete (PINDEX start, PINDEX len)
Sub-string functions
PString	operator() (PINDEX start, PINDEX end) const
PString	Left (PINDEX len) const
PString	Right (PINDEX len) const
PString	Mid (PINDEX start, PINDEX len=P_MAX_INDEX) const
PString	LeftTrim () const
PString	RightTrim () const
PString	Trim () const
PString	ToLower () const
PString	ToUpper () const
PStringArray	Tokenise (const PString &separators, PBoolean onePerSeparator=PTrue) const
PStringArray	Tokenise (const char *cseparators, PBoolean onePerSeparator=PTrue) const
PStringArray	Lines () const
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)

---

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: {verbatim} 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 {verbatim} 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 '' 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 Enumeration Documentation

enum PString::ConversionType

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

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.

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

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

Parameters:

cstr	Standard '' 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 '' character.

Parameters:

ustr	UCS-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 '' 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 '' characters to be created, but most of the functions here will be unable to access characters beyond the first ''. Furthermore, if the MakeMinimumSize()# function is called, all data beyond that first #''# character will be lost.

Parameters:

cstr	Pointer to a string of characters.
len	Length 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 '' character.

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

Parameters:

ustr	Pointer to a string of UCS-2 characters.
len	Length 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 '' character.

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

Parameters:

ustr	UCS-2 null terminated string.

PINLINE 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 '' 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::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::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::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::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::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::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::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::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::PString	(	ConversionType	type,
		const char *	str,
			...
	)

Parameters:

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

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

PINLINE PString::PString	(	int	dummy,
		const PString *	str
	)			[protected]

---

Member Function Documentation

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

Reimplemented in PFilePath, PDirectory, PCaselessString, PStringStream, and PHTML.

PINLINE 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: {verbatim} myStr = "fred"; {verbatim}

Returns:

reference to the current PString object.

Parameters:

cstr	C string to assign.

Reimplemented in PFilePath, PDirectory, PCaselessString, PStringStream, and PHTML.

PINLINE 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: {verbatim} myStr = 'A'; {verbatim}

Returns:

reference to the current PString object.

Parameters:

ch	Character to assign.

Reimplemented in PCaselessString, PStringStream, and PHTML.

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

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

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

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

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

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

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

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

virtual PString& PString::MakeEmpty

(

)

[virtual]

Make the current string empty

Reimplemented in PStringStream.

PINLINE PString PString::Empty

(

)

[static]

Return an empty string.

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:

obj	Other PString to compare against.

Reimplemented from PAbstractArray.

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.

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.

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

PTrue if the memory for the array was allocated successfully.

Parameters:

newSize

New size of the array in elements.

Reimplemented from PAbstractArray.

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:

PTrue if no non-null characters in string.

Reimplemented from PContainer.

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:

PTrue if the instance was already unique.

Reimplemented from PContainer.

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

PTrue if new memory block successfully allocated.

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.

PINLINE bool PString::operator!

(

)

const

Determine if the string is NOT empty. This is semantically identical to executing !IsEmpty() on the string.

Returns:

PTrue if non-null characters in string.

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

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: {verbatim} myStr = aStr + "fred"; {verbatim}

Returns:

new string with concatenation of the object and parameter.

Parameters:

cstr	C 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: {verbatim} myStr = aStr + '!'; {verbatim}

Returns:

new string with concatenation of the object and parameter.

Parameters:

ch	Character to concatenate.

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

Reimplemented in PFilePath.

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: {verbatim} myStr += "fred"; {verbatim}

Returns:

reference to string that was concatenated to.

Parameters:

cstr	C string to concatenate.

Reimplemented in PFilePath.

PString& PString::operator+=

(

char

ch

)

Concatenate a single character to a PString. The ch# parameter is typically a literal, eg: {verbatim} myStr += '!'; {verbatim}

Returns:

new string with concatenation of the object and parameter.

Parameters:

ch	Character to concatenate.

Reimplemented in PFilePath.

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

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: {verbatim} myStr = aStr & "fred"; {verbatim}

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:

cstr	C 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: {verbatim} myStr = aStr & '!'; {verbatim}

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:

ch	Character to concatenate.

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

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: {verbatim} myStr &= "fred"; {verbatim}

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:

cstr	C 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: {verbatim} myStr &= '!'; {verbatim}

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:

ch	Character to concatenate.

PINLINE bool PString::operator *=

(

const PString &

str

)

const

Compare two strings using case insensitive comparison.

Returns:

PTrue if equal.

Parameters:

str	PString object to compare against.

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

PTrue if equal.

Parameters:

str	PString object to compare against.

Reimplemented from PObject.

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

PTrue if not equal.

Parameters:

str	PString object to compare against.

Reimplemented from PObject.

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

PTrue if less than.

Parameters:

str	PString object to compare against.

Reimplemented from PObject.

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

PTrue if greater than.

Parameters:

str	PString object to compare against.

Reimplemented from PObject.

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

PTrue if less than or equal.

Parameters:

str	PString object to compare against.

Reimplemented from PObject.

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

PTrue if greater than or equal.

Parameters:

str	PString object to compare against.

Reimplemented from PObject.

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: {verbatim} if (myStr == "fred") {verbatim}

Returns:

PTrue if equal.

Parameters:

cstr	C string to compare against.

PINLINE 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: {verbatim} if (myStr == "fred") {verbatim}

Returns:

PTrue if equal.

Parameters:

cstr	C string to compare against.

PINLINE 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: {verbatim} if (myStr != "fred") {verbatim}

Returns:

PTrue if not equal.

Parameters:

cstr	C string to compare against.

PINLINE 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: {verbatim} if (myStr < "fred") {verbatim}

Returns:

PTrue if less than.

Parameters:

cstr	C string to compare against.

PINLINE 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: {verbatim} if (myStr > "fred") {verbatim}

Returns:

PTrue if greater than.

Parameters:

cstr	C string to compare against.

PINLINE 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: {verbatim} if (myStr <= "fred") {verbatim}

Returns:

PTrue if less than or equal.

Parameters:

cstr	C string to compare against.

PINLINE 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: {verbatim} if (myStr >= "fred") {verbatim}

Returns:

PTrue if greater than or equal.

Parameters:

cstr	C string to compare against.

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 PFalse is returned.

Returns:

PTrue 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

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 PFalse is returned.

Returns:

PTrue 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

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.

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

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.

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.

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

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.

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

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.

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

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.

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.

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

void PString::Replace	(	const PString &	target,
		const PString &	subs,
		PBoolean	all = PFalse,
		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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

PINLINE PStringArray PString::Tokenise	(	const PString &	separators,
		PBoolean	onePerSeparator = PTrue
	)			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.

PStringArray PString::Tokenise	(	const char *	cseparators,
		PBoolean	onePerSeparator = PTrue
	)			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 PTrue. 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 PFalse 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.

PStringArray PString::Lines

(

)

const

Split the string into individual lines. The line delimiters may be a carriage return (''), a line feed ('
') 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.

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.

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

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.

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.

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.

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.

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.

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.

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

(

)

const

Convert the string to C literal string format. This will convert non printable characters to the form or for standard control characters such as line feed, to
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.

PINLINE 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

void PString::InternalFromUCS2	(	const wchar_t *	ptr,
		PINDEX	len
	)			[protected]

virtual Comparison PString::InternalCompare	(	PINDEX	offset,
		char	c
	)			const [protected, virtual]

Reimplemented in PCaselessString.

virtual Comparison PString::InternalCompare	(	PINDEX	offset,
		PINDEX	length,
		const char *	cstr
	)			const [protected, virtual]

Reimplemented in PCaselessString.

---

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: {verbatim} myStr = "fred" + aStr; {verbatim}

Returns:

new string with concatenation of the object and parameter.

Parameters:

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

PString operator+	(	char	c,
		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: {verbatim} myStr = '!' + aStr; {verbatim}

Returns:

new string with concatenation of the object and parameter.

Parameters:

c	Character to be concatenated to.
str	String 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: {verbatim} myStr = "fred" & aStr; {verbatim}

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:

cstr	C string to be concatenated to.
str	String 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: {verbatim} myStr = '!' & aStr; {verbatim}

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:

ch	Character to be concatenated to.
str	String 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:

cfmt	C string for output format.

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.

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

• pstring.h
• contain.inl

---