Derived from: None
Declared in: PString.h
The PString class are used everywhere in the PolyKit package where it handles strings. You should also use this string instead of using a char *. One reason for that, is because this class stores the string in UTF-8 unicode format. All operations in the class are created to handle this format. The UTF-8 stands for "UCS Transformation Format, 8-bit form" and UCS stands for "Universal Multiple-Octet Character Set" which is another name for Unicode. The UTF-8 characters can be from 1 to 3 bytes long.
This class has been heavy inspired from Microsoft Foundation Classes, but improved a lot, like adding some extra functions or improved some of the existing ones.
Instead of having the string inside the object, it have a pointer to a structure which includes the string + some other information, including a reference counter. When one PString assigns another PString, only the pointer will be copied and the reference counter will count one up. This will speed up the string assignment, e.g. in function calls.
You can use string resources if you want to place all your strings the same place. It will then be easier to translate them to another language. You don't need to look in all the sources to find your strings. You know that all of them are the same place. To use the string resource, you need to use the macros defined in the header file. The name of the macros are: STRINGRESOURCE_BEGIN, STRINGRESOURCE_END and STRINGRESOURCE_ITEM.
These macros just create an array with all the strings you have. To start the array, you use the STRINGRESOURCE_BEGIN macro. It requires one argument, and that is the name of the array. This name is also used in the AddStringResource() function.
For each string you have, you use the STRINGRESOURCE_ITEM macro. This macro needs a number of the string and the string itself. The number is used in the Format() or LoadString() functions to get the string. The number has to be in increment order. You don't have to start from 1 and count upwards, but the next string number has to be higher than the previous one. This is because the functions use a binary search to find the string and this algorithm requires the number to be sorted. If you forgot this when you create your strings, the worse thing that can happend, is the class can't find your string and a PResourceException will be thrown.
When you're done with all the strings, end the array with the STRINGRESOURCE_END macro. This will end the array and you should be ready to use it. Let's take an example so you can see how to use them:
STRINGRESOURCE_BEGIN(myStrings) STRINGRESOURCE_ITEM(1, "This is a string") STRINGRESOURCE_ITEM(2, "Hello, what's your name") STRINGRESOURCE_ITEM(10, "Oh my god!") STRINGRESOURCE_ITEM(214, "It works!") STRINGRESOURCE_END;
To use the array, you need to add the array to the global string resource table. This is done with the AddStringResource() function. When you're done, you need to call the RemoveStringResource() function.
PString(void); PString(const PString &string); PString(const char *string);
The first version constructs a PString object with an empty string.
The second version initialize the PString object with another PString. It won't copy the context of the string, only a pointer to the string + it will count the reference counter up.
The third version initialize the PString object with the string you give as the argument. The string can be in UTF-8 format. The string you give has to be null terminated.
~PString()
~PString(void);
Frees allocated memory or count down the reference counter from another string.
int32 CompareNoCase(const char *string) const;
This function will compare the string you give with the string in the current object. It will return a value < 0 if the object string is below the argument string, 0 if they are equal or > 0 if the object string is above the argument string.
Find()
int32 Find(char ch, int32 startPos = -1) const; int32 Find(const char *str, int32 startPos = -1) const;
The first version of this function will search after a character in the current string and return the position where the character is in the string. The second version will search after a substring instead of a character.
You can give a position from where you want to begin the search. Notice that this position has to be one lower than the current position, because the function will automatic add one before it start the search. The reason for this is, you can then give the returned position to a new call to continue the search. The default start position is -1 which means it will start the search from the beginning of the string.
Because of the UTF8 encoding, the start position has to begin on a character - 1 and not in the middle of a character.
If the function couldn't find the character/substring in the string, -1 will be returned, else it will be the position in the string starting from 0.
void Format(const char *formatString, ...); void Format(uint32 resID, int32 strNum, ...); throw (PResourceException);
This function is the same as the sprintf() string function, except that it works on the current PString object. It will format the string given with the '%' arguments so the resulting string will have the formatted version of the string. See the documentation for the sprintf() function to see which '%' arguments you can use.
The second version of this function will take a string resource number instead of a string. The resID argument is the resource id you got from the AddStringResource() function.
FreeExtra()
void FreeExtra(void);
This function will reallocate the string buffer so it have the exact length as the string itself.
GetAt()
char GetAt(int32 index) const;
A string is an array of bytes which can be accessed one by one. This function will return the byte stored at the index given. The index starts with zero and upto the string length - 1. Notice that the index is the byte number, not the character number.
char *GetBuffer(int32 minBufLength);
Returns a pointer to the internal string buffer. Notice that the buffer isn't a const, so you can modify it if you want. After you're done with the buffer, you should call the ReleaseBuffer() member function. The argument is the minimum length of the buffer in bytes, not characters, the returned buffer will have.
char *GetBufferSetLength(int32 newLength);
Returns a pointer to the internal string buffer. Notice that the buffer isn't a const, so you can modify it if you want. After you is done with the buffer, you should call the ReleaseBuffer() member function. The argument is the exact length of the buffer in bytes, not characters, the returned buffer will have.
GetByteLength()
int32 GetByteLength(void) const;
This function will return the length of the string in bytes not including the null terminator.
GetLength()
int32 GetLength(void) const;
This function will return the length of the string in characters not including the null terminator.
IsEmpty()
bool IsEmpty(void) const;
If you want to test the string to see if it's empty, you can use this function. It will return true if it's empty, else it will return false.
Left()
PString Left(int32 count) const;
This is the same as the LEFT$ function in basic. It will clip some of the left part of the this string and return it as a new string. The argument is the number of bytes you want to clip.
void LoadString(uint32 resID, int32 strNum); throw(PResourceException);
This function will set the PString object to the string in the string resource which have the id number given as the strNum argument. If it couldn't find the string, a PResourceException exception will be thrown. The resID argument is the resource id you got from the AddStringResource() function.
MakeEmpty()
void MakeEmpty(void);
This function forces the string to be empty. It will free the string from the memory or count down a reference counter in another string if necessary.
MakeLower()
void MakeLower(void);
This function convert the string to lower case.
MakeNumber()
PString MakeNumber(void) const;
This function will insert commas for each third character counting backwards and return the new string. As input string it takes the current string. It will e.g. convert the string 12345 to 12,345. It doesn't check to see if there is a number stored in the string, it will just convert it. This mean e.g. the string abcdef will be converted to abc,def.
MakeUpper()
void MakeUpper(void);
This function convert the string to upper case.
Mid()
PString Mid(int32 first) const; PString Mid(int32 first, int32 count) const;
This is the same as the MID$ function in basic. It will clip some part of the this string and return it as a new string. The first argument is the byte number from where you want to start the clipping and the count is the number of bytes. If you don't give the count, the rest of the string will be copied.
void ReleaseBuffer(int32 newLength = -1);
When you're done with the buffer returned by the GetBuffer() or GetBufferSetLength() functions, you should call this function. If the string in the buffer is null terminated, you can call this function with the argument -1, which is the default. This means it will count the length of the string and set the string length to this value. You can also give the string length by yourself. The length is the number of bytes, not characters, stored in the buffer and should not include a null terminator if any.
The pointer returned by the GetBuffer() or GetBufferSetLength() functions is invalid when calling this function or any other PString operations.
ReverseFind()
int32 ReverseFind(char ch) const;
This function will search after a character in the current string starting from the end of the string and return the position where the character is in the string.
This function take notice about UTF8 encoding, so it skip the right number of bytes when it searching.
If the function couldn't find the character in the string, -1 will be returned, else it will be the position in the string starting from 0.
Right()
PString Right(int32 count) const;
This is the same as the RIGHT$ function in basic. It will clip some of the right part of the this string and return it as a new string. The argument is the number of bytes you want to clip.
StringReplace()
PString StringReplace(const char *search, const char *replace) const;
The function will search the current string after the search argument. If it find one or more instances of it in the string, they will be replaced with the replace string. This is the same as the good old "search-and-replace" function is most text editors. The new string will be returned or if nothing is changed, the current string will be returned.
TrimLeft()
void TrimLeft(void);
Call this function to trim leading whitespace characters from the string. It removes newline, space and tab characters.
TrimRight()
void TrimRight(void);
Call this function to trim trailing whitespace characters from the string. It removes newline, space and tab characters.
operator const char *()
operator const char * () const;
Returns a pointer to the PString buffer where the string is stored. The pointer is returned as a read only, so you can't change the buffer. If you want to change the buffer, use the GetBuffer() or GetBufferSetLength() functions.
operator []
char operator [](int32 index) const;
A string is an array of bytes which can be accessed one by one. This operator will return the byte stored at the index given. The index starts with zero and upto the string length - 1. Notice that the index is the byte number, not the character number.
operator =
const PString & operator = (const PString &string); const PString & operator = (const char *string);
Assigns the string with a new value. If the current buffer is large enough to hold the new string, no new buffer will be allocated.
operator +
friend PString operator +(const PString &string1, const PString &string2); friend PString operator +(const PString &string1, const char *string2); friend PString operator +(const char *string1, const char *string2);
Will concate the string1 and string2 together and return the concated result.
operator +=
const PString & operator += (PString &string); const PString & operator += (const char *string);
Concate the current string with the string given. If the current buffer is large enough to hold the new string, no new buffer will be allocated.
operator ==
friend bool operator == (const PString &string1, const PString &string2); friend bool operator == (const PString &string1, const char *string2); friend bool operator == (const char *string1, const char *string2);
Will compare the two strings and return true if they are equal to each other, else it will return false. This compare is case sentitive. If you want a non-case sentitive compare, use the CompareNoCase() function instead.
operator !=
friend bool operator != (const PString &string1, const PString &string2); friend bool operator != (const PString &string1, const char *string2); friend bool operator != (const char *string1, const char *string2);
Will compare the two strings and return true if they are different from each other, else it will return false. This compare is case sentitive. If you want a non-case sentitive compare, use the CompareNoCase() function instead.
operator <
friend bool operator < (const PString &string1, const PString &string2); friend bool operator < (const PString &string1, const char *string2); friend bool operator < (const char *string1, const char *string2);
Will compare the two strings and return true if the first string is below the second string, else it will return false. This compare is case sentitive. If you want a non-case sentitive compare, use the CompareNoCase() function instead.
operator >
friend bool operator > (const PString &string1, const PString &string2); friend bool operator > (const PString &string1, const char *string2); friend bool operator > (const char *string1, const char *string2);
Will compare the two strings and return true if the first string is above the second string, else it will return false. This compare is case sentitive. If you want a non-case sentitive compare, use the CompareNoCase() function instead.
operator <=
friend bool operator <= (const PString &string1, const PString &string2); friend bool operator <= (const PString &string1, const char *string2); friend bool operator <= (const char *string1, const char *string2);
Will compare the two strings and return true if the first string is below or equal to the second string, else it will return false. This compare is case sentitive. If you want a non-case sentitive compare, use the CompareNoCase() function instead.
operator >=
friend bool operator >= (const PString &string1, const PString &string2); friend bool operator >= (const PString &string1, const char *string2); friend bool operator >= (const char *string1, const char *string2);
Will compare the two strings and return true if the first string is above or equal to the second string, else it will return false. This compare is case sentitive. If you want a non-case sentitive compare, use the CompareNoCase() function instead.
uint32 AddStringResource(PStringResource *resource);
This function will add an resource array you have created to the global resource array so it can be used. The argument is the name of your array. This is the same name as you give the STRINGRESOURCE_BEGIN macro. The function will return a resource id number. This number is unique and you use it when you get a string from the array together with the string number. When you don't need to use the string resource anymore, remove it with the RemoveStringResource() function.
void RemoveStringResource(uint32 resID);
This function will remove an resource array from the global resource array. When a resource is removed, it can't be used anymore until you add it again. The argument is the resource id number you got from the AddStringResource() function.