Table of Contents
Table of Contentsclass PtStringThe class PtString is used to represent strings. Wildcards are supported for all comparison operators, and these operators are registered in the type manager to ensure that wildcard comparisons can be performed in the POET kernel. Wildcards are used by default for queries in the database. They are ignored by default when strings are compared in memory. When wildcards are used, the characters * and ? are expanded for comparisons: * matches any sequence of characters, and ? matches any single character. PtString provides full support for internationalized string operations. By using the appropriate member functions to access the language and code set information which is managed by the class, the user can therefore ensure that comparisons and sort orders are correct in respect to a given cultural context and language. Special comparison operators are also available for ignording case, diacritics (accents), whitespace and/or wild cards when performing comparisons.
Previous versions of POET required that the PtIString and PtCaseIString classes be used when internationalized string functionality was needed. These classes are still supported by POET, but it is now recommended that the more flexible PtString class be used for all strings which are to be stored in the database. The PtIString and PtCaseIString will slowly be phased out and will not be supported in some future version of POET. Note that the methods SpaceToZero() and ZeroToSpace() have been removed from the API. It is now considered illegal to have a PtString which contains a NULL character, since the latter is used to indicate the end of the string.
PtString : class summary| Files to include | Class declaration | Base class |
| poet.hxx | ptstring.hxx | none |
| constructor | PtString(); |
| destructor | ~PtString(); |
| Compare | long Compare(const PtString& rStr, short nLen = PtSTRING_LEN, PtCmpOp = PtCMP_DEFAULT) const; |
| Copy | PtString Copy(PtWord Index = 0, short Count = PtSTRING_LEN); |
| Cut | PtString& Cut(PtWord Index = 0, short Count = PtSTRING_LEN); |
| Expand | PtString& Expand(PtWord nCount, char ExpandChar); PtString& Expand(PtWord nCount, PtWChar cExpandChar = 0x0020); |
| Fill | PtString& Fill(PtWord nCount, char FillChar); PtString& Fill(PtWord nCount, PtWChar cFillChar = 0x0020); |
| Find | short Find(const char c, PtWord nOffset = 0, PtCmpOp nCmpOp = PtCMP_DEFAULT); short Find(const PtWChar c, PtWord nOffset = 0, PtCmpOp nCmpOp = PtCMP_DEFAULT); short Find(const PtString& rStr, PtWord nStart = 0, PtCmpOp nCmpOp = PtCMP_DEFAULT); |
| GetCodeSet | inline PtCodeSetCode GetCodeSet() const; |
| GetDefault16CodeSet | static PtCodeSetCode GetDefault16CodeSet(); |
| GetDefault8CodeSet | static PtCodeSetCode GetDefault8CodeSet(); |
| GetDefaultCmpOp | static PtCmpOp GetDefaultCmpOp(); |
| GetDefaultCodeSet | static PtCodeSetCode GetDefaultCodeSet(); |
| GetDefaultLanguage | static PtLanguageCode GetDefaultLanguage(); |
| GetLanguage | inline PtLanguageCode GetLanguage() const; |
| Insert | PtString& Insert(const PtString& rStr, PtWord Index = 0); |
| IsEmpty | PtBool IsEmpty() const; |
| Left | PtString Left(PtWord Count) const; |
| LeftTrim | PtString& LeftTrim(); |
| Len | PtWord Len() const; |
| Replace | PtString& Replace(const PtString& rStr, PtWord Index = 0); |
| ReplaceAll | PtString& ReplaceAll(const PtString& rStr, const PtString& rNewStr, PtWord Index = 0); PtString& ReplaceAll(char cOld, char cNew, PtWord Index = 0); PtString& ReplaceAll(PtWChar cOld, PtWChar cNew, PtWord Index = 0); |
| Right | PtString Right(PtWord Count); |
| RightTrim | PtString& RightTrim(); |
| SetCodeSet | inline void SetCodeSet(PtCodeSetCode nCodeSet); |
| SetDefaultCmpOp | static void SetDefaultCmpOp(PtCmpOp nCmpOp); |
| SetDefaultCodeSet | static void SetDefaultCodeSet(PtCodeSetCode nCodeSet); |
| SetDefaultLanguage | static void SetDefaultLanguage(PtLanguageCode nLanguage); |
| SetLanguage | inline void SetLanguage(PtLanguageCode nLanguage); |
| StrGet | char* StrGet() const; |
| SubStringPos | int SubStringPos(const PtString& rStr, PtCmpOp nCmpOp); |
| Trim | PtString& Trim(); |
| ToLower | PtString& ToLower(); |
| ToUpper | PtString& ToUpper(); |
| operator ! | PtBool operator ! () const; |
| operator != | PtBool operator != (const PtString& rStr) const; inline PtBool operator != (const char* rStr) const; |
| operator += | void operator += (const PtString& rStr); |
| operator < | PtBool operator < (const PtString& rStr) const; inline PtBool operator < (const char* rStr) const; |
| operator<< | PtString& operator << (char); PtString& operator << (PtWChar); PtString& operator << (const char *); PtString& operator << (const PtString&); PtString& operator << (short); PtString& operator << (int); PtString& operator << (unsigned int); PtString& operator << (long); PtString& operator << (unsigned long); PtString& operator << (float); PtString& operator << (double); |
| operator <= | PtBool operator <= (const PtString& rStr) const; inline PtBool operator <= (const char* rStr) const; |
| operator = | PtString& operator = (const PtString& rStr); PtString& operator = (const char* ); PtString& operator = (const PtWChar *); |
| operator == | PtBool operator == (const PtString& rStr) const; inline PtBool operator == (const char* rStr) const; |
| operator > | PtBool operator > (const PtString& rStr) const; inline PtBool operator > (const char* rStr) const; |
| operator >= | PtBool operator >= (const PtString& rStr) const; inline PtBool operator >= (const char* rStr) const; |
| operator [ ] | PtChar operator [] (int nIndex); |
| operator char* | inline operator char* () const; |
| operator double | operator double() const; |
| operator int | operator int() const; |
| operator long | operator long() const; |
| operator short | operator short() const; |
PtString::PtString() - PtString(PtCodeSetCode nCodeSet, PtLanguageCode nLanguage);
- PtString(const PtString& rStr);
- PtString(const char* pCharStr, word nLen);
- PtString(const PtWChar* pCharStr, word nLen);
- PtString(const char* pCharStr);
- PtString(const PtWChar* pCharStr);
- PtString(char c);
- PtString(PtWChar c);
- PtString(int n);
- PtString(short n);
- PtString(unsigned int n);
- PtString(long n);
- PtString(PtDWord n);
- PtString(double d);
Each of these is documented separately below.
- PtString::PtString()
Empty constructor. Initializes with an empty string.
- PtString::PtString(PtCodeSetCode nCodeSet, PtLanguageContext nLanguage)
Initializes with an empty string. Set the code set and language codes of the string using the parameters provided.
- PtString UnicodeString(PtCODESET_UNICODE,PtLANG_ENGLISH);
- PtString::PtString(const PtString& rStr)
Copy constructor. Sets the string to the value contained in another string.
- PtString First;
- PtString Second(First);
The new string makes a second copy of the data; the two strings do not point to the same buffer.
- PtString::PtString(const char* pCharStr, word nLen)
Constructor. Sets the string to the value in the C character string. The parameter nLen specifies the maximum length for the resulting string; if this length is exceeded, the string will be truncated.
- PtString abcde("abcdefghijklmnopqrstuvwxyz", 5);
- PtString::PtString(const PtWChar* pCharStr, word nLen)
Constructor. Sets the string to the value in the C wide (Unicode) character string. The parameter nLen specifies the maximum length for the resulting string, in 16-bit characters; if this length is exceeded, the string will be truncated.
- PtString::PtString(const char* pCharStr)
Constructor. Sets the string to the value in the C character string:
- PtString Alphabet = "abcdefghijklmnopqrstuvwxyz";
- PtString::PtString(const PtWChar* pCharStr)
Constructor. Sets the string to the value in the C wide character string:
- PtString::PtString(char c)
Constructor. Creates a string with one character in it, the character passed as a parameter.
- PtString AirOnA('g');
- PtString::PtString(PtWChar c)
Constructor. Creates a string with one wide character in it, the character passed as a parameter.
- PtString::PtString(int n)
Constructor. Creates a string with the character representation of the integer passed as a parameter.
- PtString TenSixtySix(1066); // TenSixtySix contains "1066"
- PtString::PtString(unsigned int n)
Constructor. Creates a string with the character representation of the unsigned integer passed as a parameter.
- PtString::PtString(short n)
Constructor. Creates a string with the character representation of the short integer passed as a parameter.
- PtString TenSixtySix((short) 1066); // TenSixtySix contains "1066"
- PtString::PtString(long n)
Constructor. Creates a string with the character representation of the long integer passed as a parameter.
- PtString TenSixtySix((long)1066); // TenSixtySix contains "1066"
- PtString::PtString(PtDWord n)
Constructor. Creates a string with the character representation of the double word (unsigned long) integer passed as a parameter.
- PtString::PtString(double n)
Constructor for PtString. Converts the floating-point number to a string.
- // Create the string "3.141592654"
- PtString pi(3.141592654);
- cout << (char*) pi;
- PtString::~PtString()
Destructor for class PtString.
PtString::Compare() - long PtString::Compare(const PtString& rStr, short nLen = PtSTRING_LEN, PtCmpOp = PtCMP_DEFAULT) const
Performs a comparison with the string passed as an argument. The optional parameters can be used to modify the type of comparison performed. The nLen argument specifies the maximum number of characters to be compared. The PtCmpOp argument specifies the type of comparison to be performed (e.g. ignoring case, diacritics, whitespace and/or wildcards) and can be any combination of the PtCMP_ values.
- PtString upperCase = "Bowling Green";
- PtString lowerCase = "bowling green";
- // String are equal when case is ignored
- long nComparison = upperCase.Compare(lowerCase,PtSTRING_LEN,PtCMP_IGNORECASE);
- PtString PtString::Copy(word Index = 0, word Count = PtSTRING_LEN)
Returns the substring beginning at Index and containing Count characters.
- PtString Alphabet = "abcdefghijklmnopqrstuvwxyz";
- PtString bcd = Alphabet.Copy(1,3); // bcd contains "bcd".
- PtString& PtString::Cut(word Index = 0, word Count = PtSTRING_LEN)
Deletes Count chars beginning at Index. Returns the resulting string.
- PtString Alphabet = "abcdefghijklmnopqrstuvwxyz";
- PtString Noel = Alphabet.Cut(11,1); // Noel contains
- // "abcdefghijkmnopqrstuvwxyz"
- PtString& PtString::Expand(word Count, char ExpandChar)
- PtString& PtString::Expand(word Count, PtWChar ExpandChar = 0x0020)
Adds Count characters to the end of the string using the provided 8-bit or 16-bit character. Space is used by default.
Returns the resulting string.
- PtString Exclamation = "Gee whiz!";
- Exclamation.Expand(3, '!');
- // Exclamation contains "Gee whiz!!!!"
- PtString& PtString::Fill(word Count, char FillChar)
- PtString& PtString::Fill(word Count, PtWChar FillChar = 0x0020)
Resizes PtString to Count chars and initializes it with FillChar. Returns the resulting string.
- PtString Exclamation = "Gee whiz!";
- Exclamation.Fill (10, '!');
- // Exclamation contains "!!!!!!!!!!"
- short PtString::Find(const char c, PtWord nOffset = 0, PtCmpOp nCmpOp = PtCMP_DEFAULT)
- short PtString::Find(const PtWChar c, PtWord nOffset = 0, PtCmpOp nCmpOp = PtCMP_DEFAULT)
- short PtString::Find(const PtString& rStr, PtWord nOffset = 0, PtCmpOp nCmpOp = PtCMP_DEFAULT)
Returns the position of the provided (8-bit or 16-bit) character or string. The nOffset parameter indicates the position at which the search should begin. The nCmpOp parameter can be used to specify how cbaracters should be compared.
- PtString Alphabet = "abcdefghijklmnopqrstuvwxyz";
- short lmnop = Alphabet.Find("lmnop"); // Returns 11
- inline PtCodeSetCode PtString::GetCodeSet() const
Returns the code set used to represent the string.
PtString::GetDefault16CodeSet() - static PtCodeSetCode PtString::GetDefault16CodeSet()
Returns the code set used by default to represent wide (16-bit) character strings. Normally this will be PtCODESET_UNICODE.
PtString::GetDefault8CodeSet() - static PtCodeSetCode PtString::GetDefault8CodeSet()
Returns the code set used by default to represent 8-bit character strings. Normally this will be either PtCODESET_NONE (if code set information is not used by the application) or the native code set of the platform being used (e.g. PtCODESET_ANSI under Windows).
PtString::GetDefaultCmpOp() - static PtCmpOp PtString::GetDefaultCmpOp()
Returns the comparison operator used by default when comparing strings. This is normally set to PtCMP_IGNOREWILDCARDS. The value is only used for string comparisons in memory; comparisons in the database use the comparison operator specified when building the query.
PtString::GetDefaultCodeSet() - static PtCodeSetCode PtString::GetDefaultCodeSet()
Returns the code set used by default to represent character strings. This will normally be either PtCODESET_NONE, PtCODESET_UNICODE or the native code set of the platform being used.
PtString::GetDefaultLanguage() - static PtLanguageCode PtString::GetDefaultLanguage()
Returns the language used by default for character strings. Currently, PtLANG_NONE (when language information is not used) is supported as well as the following Western European languages:
PtLANG_ENGLISH PtLANG_GERMAN PtLANG_FRENCH PtLANG_ITALIAN PtLANG_SPANISH PtLANG_DANISH PtLANG_DUTCH PtLANG_FAROESE PtLANG_FINNISH PtLANG_ICELANDIC PtLANG_IRISH PtLANG_NORWEGIAN PtLANG_PORTUGUESE PtLANG_SWEDISH
PtString::GetLanguage() - inline PtLanguageCode PtString::GetLanguage() const
Returns the language used by the string.
PtString::Insert() - PtString& PtString::Insert(const PtString& rStr, word Index = 0)
Inserts the string rStr at the position indicated by the Index parameter. Returns the resulting string.
- PtString OneTwoThree = "13";
- OneTwoThree.Insert((PtString) "2", 1);
- // OneTwoThree contains "123"
- PtBool PtString::IsEmpty() const
Returns PtTRUE if the string contains no characters, PtFALSE otherwise.
PtString::Left() - PtString Left(PtWord Count) const;
Returns the first Count characters of the string.
- PtString Alphabet = "abcdefghijklmnopqrstuvwxyz";
- PtString abcdef = Alphabet.Left(6); // abcdef contains "abcdef"
- PtString& LeftTrim()
Removes any whitespace characters from the beginning of the string.
- PtString LeadingWhiteSpace = " Hello ";
- PtString NoLeadingWhiteSpace = LeadingWhiteSpace.LeftTrim();
- // NoLeadingWhiteSpace contains "Hello "
- word PtString::Len() const
Returns the length of the string in characters.
PtString::Replace() - PtString& PtString::Replace(const PtString& rStr, word Index = 0)
Replaces the current contents of this string with rStr, starting with the position indicated by Index. If the length of rStr plus Index exceeds the current length of the string, Replace() stops when the end of the current string is reached.
Returns the resulting string.
- PtString Greeting = "Good morning";
- Greeting.Replace(5,"even");
- // Greeting contains "Good evening"
- PtString& PtString::ReplaceAll(const PtString& rStr, const PtString& rNewStr, word Index = 0)
- PtString& PtString::ReplaceAll(char cOld, char cNew, word Index = 0)
- PtString& PtString::ReplaceAll(PtWChar cOld, PtWChar cNew, word Index = 0)
Searches for all occurences of the provided string or character (rStr or cOld) and replaces it with the corresponding new string or character (rNewStr or cNew). If the string or character is not found, no operation is performed. Returns the resulting string.
- PtString Proverb = "When in Crete, do as the Cretans";
- Proverb.ReplaceAll("Cret","Rom");
- // Proverb contains "When in Rome, do as the Romans"
- PtString PtString::Right(PtWord Count)
Returns the last Count characters of the string.
- PtString Alphabet = "abcdefghijklmnopqrstuvwxyz";
- PtString uvwxyz = Alphabet.Right(6); // uvwxyz contains "uvwxyz"
- PtString& PtString::RightTrim()
Removes any whitespace characters from the end of the string.
- PtString TrailingWhiteSpace = " Hello ";
- PtString NoTrailingWhiteSpace = TrailingWhiteSpace.RightTrim();
- // NoTrailingWhiteSpace contains " Hello"
- inline void SetCodeSet(PtCodeSetCode nCodeSet)
Sets the code set used to represent the string. If the string already has a code set and contains data, the data will be converted to the new code set.
- PtString ANSIString;
- ANSIString.SetCodeSet(PtCODESET_ANSI);
- ANSIString = "Hello";
- static void SetDefaultCmpOp(PtCmpOp nCmpOp)
Sets the comparison operator which will be used by default when comparing strings.
PtString::SetDefaultCodeSet() - static void SetDefaultCodeSet(PtCodeSet nCodeSet)
Sets the code set which will be used by default for representing strings.
PtString::SetDefaultLanguage() - static void SetDefaultLanguage(PtLanguage nLanguage)
Sets the language which will be used by default by strings.
PtString::SetLanguage() - inline void PtString::SetLanguage(PtLanguageCode nLanguage)
Sets the language to be used by the string.
PtString::SpaceToZero() - PtString& PtString::SpaceToZero()
No longer supported (see introduction to this section).
PtString::StrGet() - char* PtString::StrGet() const
Returns a character pointer to the string.
PtString::SubStringPos() - int PtString::SubStringPos(const PtString& rStr, PtCmpOp nCmpOp = PtCMP_DEFAULT)
Searches for the first occurrence of rStr in the string. Returns the first position at which this string occurs. If the substring was not found then PtSUBSTRING_NOTFOUND will be returned.
PtString::Trim() - PtString& PtString::Trim()
Removes any whitespace characters from the beginning and the end of the string.
- PtString WhiteSpace = " Hello ";
- PtString NoWhiteSpace = WhiteSpace.Trim();
- // NoWhiteSpace contains "Hello"
- PtString& PtString::ToLower()
Changes uppercase letters to lowercase letters. Returns the resulting string.
PtString::ToUpper() - PtString& PtString::ToUpper()
Changes lowercase letters to uppercase letters. Returns the resulting string.
PtString::ZeroToSpace() - PtString& PtString::ZeroToSpace()
No longer supported (see introduction to this section).
PtString::operator ! () - PtBool PtString::operator ! () const
Returns PtTRUE if the length of the string is 0, PtFALSE otherwise.
PtString::operator != () - PtBool PtString::operator != (const PtString& rStr) const
- inline PtBool operator != (const char* rStr) const
Returns PtTRUE if the strings are not identical, PtFALSE otherwise.
PtString::operator += () - void PtString::operator += (const PtString& rStr)
Concatenation operator. Appends one string to another.
- PtString First = "Good";
- PtString Second = "bye";
- First += Second;
- // First contains "Goodbye"
- PtBool PtString::operator < (const PtString& rStr) const
- inline PtBool PtString::operator < (const char* rStr) const
Returns PtTRUE if the lefthand string if smaller than the righthand string, PtFALSE otherwise.
PtString:: operator << () - PtString&& PtString::operator << (char)
- PtString&& PtString::operator << (PtWChar)
- PtString&& PtString::operator << (const char *)
- PtString&& PtString::operator << (const PtString&)
- PtString&& PtString::operator << (short)
- PtString&& PtString::operator << (int)
- PtString&& PtString::operator << (unsigned int)
- PtString&& PtString::operator << (long)
- PtString&& PtString::operator << (unsigned long)
- PtString&& PtString::operator << (float)
- PtString&& PtString::operator << (double)
Stream operators for concatenating data onto strings. The argument is converted into string format and appended onto the end of the string. This can be used to build up strings from arguments of different data types.
- char Month = 6;
- char Day = 2;
- short Year = 1996;
- float Temperator = 98.6;
- PtString City = "Hamburg";
- PtString Weather;
- Weather << "The temperature in " << City << " on " << Month << "/" << Day << "/" << Year << " is " << Temperature << " degrees";
- // Weather equals "The temperature in Hamburg on 6/2/1996 is 98.6 degrees"
- PtBool PtString::operator <= (const PtString& rStr) const
- inline PtBool PtString::operator <= (const char * rStr) const
Returns PtTRUE if the lefthand string is smaller than or identical to the righthand string, PtFALSE otherwise.
PtString::operator = () - PtString& PtString::operator = (const PtString& rStr)
- PtString& PtString::operator = (const char *)
- PtString& PtString::operator = (const PtWChar *)
Assigns the value of the argument to the string. The argument can be a PtString or a null-terminated 8-bit or 16-bit character array;
- PtString CanterburyIntro = "Whan that Aprille with his shoure soughte...";
- PtString CopyCat;
- CopyCat = CanterburyIntro;
- // The value of CanterburyIntro is assigned to CopyCat
- PtBool PtString::operator == (const PtString& rStr) const
- inline PtBool PtString::operator == (const char* rStr) const
Returns PtTRUE if the strings are identical, PtFALSE otherwise.
PtString::operator > () - PtBool PtString::operator > (const PtString& rStr) const
- inline PtBool PtString::operator > (const char* rStr) const
Returns PtTRUE if the lefthand string is larger than the righthand string, PtFALSE otherwise.
PtString:: operator >= () - PtBool PtString::operator >= (const PtString& rStr) const
- inline PtBool PtString::operator >= (const char* rStr) const
Returns PtTRUE if the lefthand string is larger than or identical to the righthand string, PtFALSE otherwise.
PtString::operator [ ] () - PtChar PtString::operator [] (int nIndex)
- inline PtChar PtString::operator [] (PtWord nIndex)
Returns the character at position nIndex. Standard C indexing is used, so the first character position is zero.
The returned PtChar object is an encapsulation of a single character which can hold either a 8-bit or a 16-bit character. If the return value is used in a context where it is not clear whether a char or a PtWChar is needed, it should be explicitly casted to avoid ambiguity.
- PtString CanterburyIntro = "Whan that Aprille with his shoure soughte...";
- char c = CanterburyIntro[2]; // c is set to 'a' (no ambiguity)
- cout << (char) CanterburyIntro[2]; // prints 'a' (cast to avoid ambiguity)
- inline PtString::operator char* () const
Cast operator. Returns a pointer to the start of the string buffer in the PtString. Since this is guaranteed to be zero terminated, you may use it like any other null-terminated ASCII string.
- // Create the string "3.141592654"
- PtString pi(3.141592654);
- cout << (char*) pi;
- PtString::operator double() const
Conversion operator. Converts the string to a double using the standard C library function atod().
- PtString pi("3.141592654");
- double r = (double) pi;
- PtString::operator int() const
Conversion operator. Converts the string to an integer using the standard C library function atoi().
- PtString one(1);
- int a = (int) one;
- PtString::operator long() const
Conversion operator. Converts the string to a long integer using the standard C library function atol().
- PtString one(1L);
- long a = (long) one;
- PtString::operator short() const
Conversion operator. Converts the string to a short integer using the standard C library function atoi().
- PtString one(1);
- short a = (short) one;
Copyright (c) 1996 POET Software, Inc. All rights reserved. Reproduction in whole or in part in any form or medium without the express permission of POET Software, Inc. is prohibited.