class PString

The character string class.

Inheritance:


Public Methods

[more] Construction
[more] Overrides from class PObject
[more] Overrides from class PContainer
[more] Size/Length functions
[more] Concatenation operators *
[more] Comparison operators
[more] Search & replace functions
[more] Sub-string functions
[more] Conversion functions


Inherited from PCharArray:


Inherited from PBaseArray:

Public Methods

New functions for class


Inherited from PAbstractArray:

Protected Fields

oPINDEX elementSize
ochar* theArray
oBOOL allocatedDynamically


Inherited from PContainer:

Public Methods

Common functions for containers

Protected Methods

ovirtual void DestroyContents()
ovirtual void AssignContents(const PContainer & c)
ovoid CopyContents(const PContainer & c)
ovoid CloneContents(const PContainer* src)
ovoid Destruct()


Inherited from PObject:

Public Methods

Run Time Type functions

I/O functions

Public Members

Comparison functions


Documentation

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.

o Construction

ostatic PString Empty()
Return an empty string

oPString& MakeEmpty()
Make the current string empty

oPINLINE PString()
Construct an empty string. This will have one character in it which is the '\0' character.

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

o PString( const char* cstr )
Create a string from the C string array. This is most commonly used with a literal string, eg "hello". A new memory block is allocated of a size sufficient to take the length of the string and its terminating '\0' character.

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

Parameters:
- cstr Standard '\0' terminated C string.

o PString( const WORD* ustr )
Create a string from the UCS-2 string array. A new memory block is allocated of a size sufficient to take the length of the string and its terminating '\0' character.
Parameters:
ustr - UCS-2 null terminated string.

o PString( const char* cstr, PINDEX len )
Create a string from the array. A new memory block is allocated of a size equal to len plus one which is sufficient to take the string and a terminating '\0' character.

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

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

Parameters:
- cstr Pointer to a string of characters.
len - Length of the string in bytes.

o PString( const WORD* ustr, PINDEX len )
Create a string from the UCS-2 array. A new memory block is allocated of a size equal to len plus one which is sufficient to take the string and a terminating '\0' character.

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

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

o PString( const PWORDArray & ustr )
Create a string from the UCS-2 array. A new memory block is allocated of a size equal to len plus one which is sufficient to take the string and a terminating '\0' character.

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

Parameters:
ustr - UCS-2 null terminated string.

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

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

Parameters:
- ch Single character to initialise string.

o 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

o 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

o 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

o 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

o 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

o 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

o 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

o 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

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

Parameters:
- str New string to assign.
Returns:
reference to the current PString object.

oPString& 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";
Parameters:
- cstr C string to assign.
Returns:
reference to the current PString object.

oPString& 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';
Parameters:
- ch Character to assign.
Returns:
reference to the current PString object.

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

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

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

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

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

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

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

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

o Overrides from class PObject

ovirtual PObject* Clone() const
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.

ovirtual Comparison Compare( const PObject & obj ) const
Get the relative rank of the two strings. The system standard function, eg strcmp(), is used.

Parameters:
obj - Other PString to compare against.
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.

ovirtual void PrintOn( ostream & strm ) const
Output the string to the specified stream.
Parameters:
- strm I/O stream to output to.

ovirtual void ReadFrom( istream & strm )
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.

ovirtual PINDEX HashFunction() const
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.

o Overrides from class PContainer

ovirtual BOOL SetSize( PINDEX newSize )
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.

Parameters:
newSize - New size of the array in elements.
Returns:
TRUE if the memory for the array was allocated successfully.

ovirtual BOOL IsEmpty() const
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.

ovirtual BOOL MakeUnique()
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.

o Size/Length functions

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

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

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

o Concatenation operators *
Friends:
PString operator+(
PString operator+(
PString operator&(
PString operator&(

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

Parameters:
- str String to concatenate.
Returns:
new string with concatenation of the object and parameter.

oPString 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";

Parameters:
- cstr C string to concatenate.
Returns:
new string with concatenation of the object and parameter.

oPString 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 + '!';

Parameters:
- ch Character to concatenate.
Returns:
new string with concatenation of the object and parameter.

ochar c

oPString& operator+=( const PString & str )
Concatenate a string to another string, modifiying that string.

Parameters:
- str String to concatenate.
Returns:
reference to string that was concatenated to.

oPString& 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";

Parameters:
- cstr C string to concatenate.
Returns:
reference to string that was concatenated to.

oPString& operator+=( char ch )
Concatenate a single character to a PString. The ch parameter is typically a literal, eg:
          myStr += '!';

Parameters:
- ch Character to concatenate.
Returns:
new string with concatenation of the object and parameter.

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

Parameters:
- str String to concatenate.
Returns:
new string with concatenation of the object and parameter.

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

Parameters:
- cstr C string to concatenate.
Returns:
new string with concatenation of the object and parameter.

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

Parameters:
- ch Character to concatenate.
Returns:
new string with concatenation of the object and parameter.

oconst char* cstr

ochar ch

oconst PString& str
Character to be concatenated toC string to be concatenated toCharacter to be concatenated toC string to be concatenated to

oPString& operator&=( const PString & str )
Concatenate a string to another string, modifiying that string.

Parameters:
- str String to concatenate.
Returns:
reference to string that was concatenated to.

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

Parameters:
- cstr C string to concatenate.
Returns:
reference to string that was concatenated to.

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

Parameters:
- ch Character to concatenate.
Returns:
reference to string that was concatenated to.

o Comparison operators

oBOOL operator*=( const PString & str ) const
Compare two strings using case insensitive comparison.

Parameters:
- str PString object to compare against.
Returns:
TRUE if equal.

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

Parameters:
- str PString object to compare against.
Returns:
TRUE if equal.

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

Parameters:
- str PString object to compare against.
Returns:
TRUE if not equal.

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

Parameters:
- str PString object to compare against.
Returns:
TRUE if less than.

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

Parameters:
- str PString object to compare against.
Returns:
TRUE if greater than.

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

Parameters:
- str PString object to compare against.
Returns:
TRUE if less than or equal.

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

Parameters:
- str PString object to compare against.
Returns:
TRUE if greater than or equal.

oBOOL 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")

Parameters:
- cstr C string to compare against.
Returns:
TRUE if equal.

oBOOL 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")

Parameters:
- cstr C string to compare against.
Returns:
TRUE if equal.

oBOOL 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")

Parameters:
- cstr C string to compare against.
Returns:
TRUE if not equal.

oBOOL 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")

Parameters:
- cstr C string to compare against.
Returns:
TRUE if less than.

oBOOL 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")

Parameters:
- cstr C string to compare against.
Returns:
TRUE if greater than.

oBOOL 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")

Parameters:
- cstr C string to compare against.
Returns:
TRUE if less than or equal.

oBOOL 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")

Parameters:
- cstr C string to compare against.
Returns:
TRUE if greater than or equal.

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

Parameters:
- str PString object to compare against.
- count Number of chacracters in str to compare
offset - Offset into string to compare
Returns:
TRUE if str is a substring of .

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

Parameters:
- cstr C string object to compare against.
- count Number of chacracters in str to compare
offset - Offset into string to compare
Returns:
TRUE if str is a substring of .

o Search & replace functions

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

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

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

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

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

Parameters:
- cstr C string to search for in string.
offset - Offset into string to begin search.
Returns:
position of character or substring in the string, or P_MAX_INDEX if the character or substring is not in the string.

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

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

Parameters:
cset - C string of characters to search for in string.
offset - Offset into string to begin search.
Returns:
position of character in the string, or P_MAX_INDEX if no characters from the set are in the string.

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

Parameters:
regex - regular expression to find
offset - Offset into string to begin search.
Returns:
position of regular expression in the string, or P_MAX_INDEX if no characters from the set are in the string.

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

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
Returns:
position of regular expression in the string, or P_MAX_INDEX if no characters from the set are in the string.

ovoid Replace( const PString & target, const PString & subs, BOOL all = FALSE, PINDEX offset = 0 )
Locate the substring within the string and replace it with the specifed substring. The search will begin at the character offset provided.

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

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

Parameters:
target - String to be replaced in string.
subs - String to do replace in string.
all - Replace all occurrences of string.
offset - Offset into string to begin search.

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

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

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

o Sub-string functions

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

Parameters:
start - Starting position of the substring.
end - Ending position of the substring.
Returns:
substring of the source string.

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

Parameters:
len - Number of characters to extract.
Returns:
substring of the source string.

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

Parameters:
len - Number of characters to extract.
Returns:
substring of the source string.

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

Parameters:
start - Starting position of the substring.
len - Number of characters to extract.
Returns:
substring of the source string.

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

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

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

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

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

oPStringArray Tokenise( const PString & separators, BOOL onePerSeparator = TRUE ) const
Split the string into an array of substrings.
Parameters:
separators - A string for the set of separator characters that delimit tokens.
onePerSeparator - Flag for if there are empty tokens between consecutive separators.

oPStringArray Tokenise( const char* cseparators, BOOL 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 4 substrings; "a", "list", "of" and "words".

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 and in the second the delimiters are ignored.

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.
Returns:
an array of substring for each token in the string.

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

o Conversion functions
Friends:
PString psprintf(
PString pvsprintf(
PString pvsprintf(

oPString& sprintf( const char* cfmt, ... Extra parameters for #sprintf()# call. )
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.

Parameters:
- cfmt C string for output format.
Returns:
reference to the current string object.

o ...
C string for output format

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

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

Parameters:
- cfmt C string for output format.
- args Extra parameters for sprintf() call.
Returns:
reference to the current string object.

oconst char* cfmt

oconst PString& fmt

ova_list args
String for output formatC string for output format

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

Parameters:
base - Number base to convert the string in.
Returns:
integer value for the string.

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

Parameters:
base - Number base to convert the string in.
Returns:
integer value for the string.

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

Parameters:
base - Number base to convert the string in.
Returns:
integer value for the string.

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

Parameters:
base - Number base to convert the string in.
Returns:
integer value for the string.

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

oPWORDArray AsUCS2() const
Convert UTF-8 string to UCS-2. Note the resultant PWORDArray will have the trailing null included.

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

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

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


Direct child classes:
PFilePathString
PStringStream
PCaselessString

Alphabetic index HTML hierarchy of classes or Java



This page was generated with the help of DOC++.