The character string class.
New functions for class
Common functions for containers
Run Time Type functions
Comparison functions
I/O functions
Miscellaneous functions
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.The PSTRING_ANCESTOR_CLASS is dependent on whether UNICODE support is selected. The entire library and application must be compiled with or without UNICODE or undefined results will occur. PSTRING_ANCESTOR_CLASS macro is normally set to PCharArray.
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 stringsat 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.
If UNICODE is used then each char from the char pointer is mapped to a
single UNICODE character.
If UNICODE is used then each char from the char pointer is mapped to a
single UNICODE 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.
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.
If UNICODE is used then the char is mapped to a single UNICODE
character.
PINLINE PString( const PString & str )
PString( const char * cstr )
PString( const WORD * ustr )
PString( const char * cstr, PINDEX len )
len - Length of the string in bytes. PString( const WORD * cstr, PINDEX len )
len - Length of the string in bytes. PString( char ch )
PString& operator=( const PString & str )
PString& operator=( const char * cstr )
myStr = "fred";
PString& operator=( char ch )
myStr = 'A';
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.
virtual Comparison Compare( const PObject & obj ) const
virtual void PrintOn( ostream & strm ) const
virtual void ReadFrom( istream & strm )
virtual PINDEX HashFunction() const
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.
virtual BOOL IsEmpty() const
virtual BOOL MakeUnique()
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.
PINLINE PINDEX GetLength() const
BOOL operator!() const
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.
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.
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.
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.
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.
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.
PString operator+( const char * cstr ) const
myStr = aStr + "fred";
PString operator+( char ch ) const
myStr = aStr + '!';
friend PString operator+( const char * cstr, const PString & str )
myStr = "fred" + aStr;
str - String to concatenate.friend PString operator+( char c, const PString & str )
myStr = '!' + aStr;
str - String to concatenate.PString& operator+=( const PString & str )
PString& operator+=( const char * cstr )
myStr += "fred";
PString& operator+=( char ch )
myStr += '!';
PString operator&( const PString & str ) const
PString operator&( const char * cstr ) const
myStr = aStr & "fred";
PString operator&( char ch ) const
myStr = aStr & '!';
friend PString operator&( const char * cstr, const PString & str )
myStr = "fred" & aStr;
str - String to concatenate.friend PString operator&( char ch, const PString & str )
myStr = '!' & aStr;
str - String to concatenate.PString& operator&=( const PString & str )
PString& operator&=( const char * cstr )
myStr &= "fred";
PString& operator&=( char ch )
myStr &= '!';
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
if (myStr == "fred")
BOOL operator==( const char * cstr ) const
if (myStr == "fred")
BOOL operator!=( const char * cstr ) const
if (myStr != "fred")
BOOL operator<( const char * cstr ) const
if (myStr < "fred")
BOOL operator>( const char * cstr ) const
if (myStr > "fred")
BOOL operator<=( const char * cstr ) const
if (myStr <= "fred")
BOOL operator>=( const char * cstr ) const
if (myStr >= "fred")
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.
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.
If offset is beyond the length of the string, then the
function will always return P_MAX_INDEX.
If offset is beyond the length of the string, then the
function will always return P_MAX_INDEX.
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.
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.
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.
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.
PINDEX Find( const PString & str, PINDEX offset = 0 ) const
offset - Offset into string to begin search.PINDEX FindLast( char ch, PINDEX offset = P_MAX_INDEX ) const
offset - Offset into string to begin search.PINDEX FindLast( const PString & str, PINDEX offset = P_MAX_INDEX ) const
offset - Offset into string to begin search.PINDEX FindLast( const char * cstr, PINDEX offset = P_MAX_INDEX ) const
offset - Offset into string to begin search.PINDEX FindOneOf( const PString & set, PINDEX offset = 0 ) const
offset - Offset into string to begin search.PINDEX FindOneOf( const char * cset, PINDEX offset = 0 ) const
offset - Offset into string to begin search.PINDEX FindRegEx( const PRegularExpression & regex, PINDEX offset = 0 ) const
offset - Offset into string to begin search.BOOL FindRegEx( const PRegularExpression & regex, PINDEX & pos, PINDEX & len, PINDEX offset = 0, PINDEX maxPos = P_MAX_INDEX ) const
pos - Position of matched expression
len - Length of matched expression
offset - Offset into string to begin search.
maxPos - Maximum offset into stringvoid Replace( const PString & target, const PString & subs, BOOL all = FALSE, PINDEX offset = 0 )
subs - String to do replace in string.
all - Replace all occurrences of string.
offset - Offset into string to begin search.void Splice( const PString & str, PINDEX pos, PINDEX len = 0 )
pos - Position in string to insert the substring.
len - Length of section to remove.void Splice( const char * cstr, PINDEX pos, PINDEX len = 0 )
pos - Position in string to insert the substring.
len - Length of section to remove.void Delete( PINDEX start, PINDEX len )
len - Number of characters to delete.
The substring is returned inclusive of the characters at the start and
If 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
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.
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.
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.
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;
ä", "list", öf" 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.
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.
PString Left( PINDEX len ) const
PString Right( PINDEX len ) const
PString Mid( PINDEX start, PINDEX len = P_MAX_INDEX ) const
len - Number of characters to extract.PString LeftTrim() const
PString RightTrim() const
PString Trim() const
PString ToLower() const
PString ToUpper() const
PStringArray Tokenise( const PString & separators, BOOL onePerSeparator = TRUE ) const
onePerSeparator - Flag for if there are empty tokens between consecutive separators.PStringArray Tokenise( const char * cseparators, BOOL onePerSeparator = TRUE ) const
onePerSeparator - Flag for if there are empty tokens between consecutive separators.PStringArray Lines() const
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.
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.
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.
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.
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.
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.
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.
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.
This function uses the standard C library strtod()
function.
This function will assert if the string is greater than 255 characters
in length.
friend PString psprintf( const char * cfmt, ... Extra parameters for #sprintf()# call. )
PString& vsprintf( const PString & fmt, va_list args )
args - Extra parameters for sprintf() call.PString& vsprintf( const char * cfmt, va_list args )
args - Extra parameters for sprintf() call.friend PString pvsprintf( const char * cfmt, va_list args )
args - Extra parameters for sprintf() call.friend PString pvsprintf( const PString & fmt, va_list args )
args - Extra parameters for sprintf() call.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
PBYTEArray ToPascal() const
PString ToLiteral() const
operator const unsigned char *() const
Alphabetic index HTML hierarchy of classes or Java