class PString |
The character string class.
New functions for class
Common functions for containers
Run Time Type functions
I/O functions
Miscellaneous functions
Comparison 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.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.
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.
If UCS-2 is used then each char from the char pointer is mapped to a single UCS-2 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.
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 UCS-2 is used then the char is mapped to a single UCS-2 character.
myStr = "fred";
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.
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.
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.
myStr = aStr + "fred";
myStr = aStr + '!';
myStr += "fred";
myStr += '!';
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.
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.
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.
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.
if (myStr == "fred")
if (myStr == "fred")
if (myStr != "fred")
if (myStr < "fred")
if (myStr > "fred")
if (myStr <= "fred")
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.
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.
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; "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.
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.
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.
Alphabetic index HTML hierarchy of classes or Java