version 1.68, 2002/09/20 19:38:14
|
version 1.74.6.2, 2003/08/13 19:39:50
|
|
|
#ifndef Pegasus_String_h | #ifndef Pegasus_String_h |
#define Pegasus_String_h | #define Pegasus_String_h |
| |
#include <cstring> |
#ifdef PEGASUS_OS_HPUX |
|
# ifdef HPUX_IA64_NATIVE_COMPILER |
#include <iostream> | #include <iostream> |
|
# else |
|
# include <iostream.h> |
|
# endif |
|
#else |
|
# include <iostream> |
|
#endif |
#include <Pegasus/Common/Config.h> | #include <Pegasus/Common/Config.h> |
#include <Pegasus/Common/Char16.h> | #include <Pegasus/Common/Char16.h> |
#include <Pegasus/Common/Linkage.h> | #include <Pegasus/Common/Linkage.h> |
| |
|
const char STRING_FLAG_ASCII[] = "ASCII"; |
|
const char STRING_FLAG_UTF8[] = "UTF8"; |
|
|
PEGASUS_NAMESPACE_BEGIN | PEGASUS_NAMESPACE_BEGIN |
| |
class String; | class String; |
|
|
{ | { |
public: | public: |
| |
|
/// |
CString(); | CString(); |
| |
|
/// |
CString(const CString& cstr); | CString(const CString& cstr); |
| |
|
/// |
~CString(); | ~CString(); |
| |
|
/// |
CString& operator=(const CString& cstr); | CString& operator=(const CString& cstr); |
| |
operator const char*() const; | operator const char*() const; |
|
|
| |
/** | /** |
The Pegasus String C++ Class implements the CIM string type. | The Pegasus String C++ Class implements the CIM string type. |
This class is based on the general handle/representation pattern |
|
defined for all the Pegasus objects. However, it differes from |
|
most in that it implements "copy on assign" all of the others implement |
|
"no copy on assign" semantics. The string class uses the Array class and |
|
implements an array of characters. |
|
*/ | */ |
class PEGASUS_COMMON_LINKAGE String | class PEGASUS_COMMON_LINKAGE String |
{ | { |
public: | public: |
| |
/** EMPTY - Represent an empty string. |
/** This member is used to represent an empty string. Using this |
This member is used to represent empty strings. Using this member |
member avoids construction of an empty string (e.g., String()). |
avoids an expensive construction of an empty string (e.g., String()). |
|
*/ | */ |
static const String EMPTY; | static const String EMPTY; |
| |
/** Default constructor without parameters. This constructor creates a | /** Default constructor without parameters. This constructor creates a |
null string |
null string. |
<pre> | <pre> |
String test; | String test; |
</pre> | </pre> |
|
|
String(const Char16* str, Uint32 n); | String(const Char16* str, Uint32 n); |
| |
/// Initialize from a plain old C-String: | /// Initialize from a plain old C-String: |
|
String(const char* str, const char*); |
String(const char* str); | String(const char* str); |
| |
/// Initialize from the first n characters of a plain old C-String: | /// Initialize from the first n characters of a plain old C-String: |
String(const char* str, Uint32 n); | String(const char* str, Uint32 n); |
| |
/// String destructor. Used by the representation of the String object |
/// Destructor. |
~String(); | ~String(); |
| |
/** Assign this string with str. | /** Assign this string with str. |
|
|
*/ | */ |
String& operator=(const String& str); | String& operator=(const String& str); |
| |
/** Assign this string with String str |
/** Assign this string with String str. |
@param str String to assign |
@param str String to assign. |
@return Returns the String |
@return Returns the String. |
*/ | */ |
String& assign(const String& str); | String& assign(const String& str); |
| |
|
|
/// Assign this string with first n characters of the plain old C-String str. | /// Assign this string with first n characters of the plain old C-String str. |
String& assign(const char* str, Uint32 n); | String& assign(const char* str, Uint32 n); |
| |
/** clear - Clear this string. After calling clear(), size() will return 0. |
/** Clear this string. After calling clear(), size() will return 0. |
<pre> | <pre> |
String test = "abc"; | String test = "abc"; |
test.clear(); // String test is now NULL (length == 0) |
test.clear(); |
</pre> | </pre> |
*/ | */ |
void clear(); | void clear(); |
| |
| |
/** reserveCapacity - Reserves memory for capacity characters. Notice |
/** Reserves memory for capacity characters. Notice |
that this does not change the size of the string (size() returns | that this does not change the size of the string (size() returns |
what it did before). If the capacity of the string is already | what it did before). If the capacity of the string is already |
greater or equal to the capacity argument, this method has no | greater or equal to the capacity argument, this method has no |
|
|
*/ | */ |
Uint32 size() const; | Uint32 size() const; |
| |
/** getChar16Data Returns a pointer to the first character in the |
/** Returns a pointer to the first character in the |
null-terminated Char16 buffer of the String object. | null-terminated Char16 buffer of the String object. |
@return Pointer to the first character of the String object |
@return Pointer to the first character of the String object. |
<pre> | <pre> |
String t1 = "abc"; |
String test = "abc"; |
const Char16* q = t1.getChar16Data(); |
const Char16* q = test.getChar16Data(); |
</pre> | </pre> |
*/ | */ |
const Char16* getChar16Data() const; | const Char16* getChar16Data() const; |
| |
/** getCString - Create an 8-bit representation of this String object. |
/** Create an 8-bit representation of this String object. |
|
|
@param truncatedCharacters Output parameter specifying whether any |
|
characters were truncated in the conversion. |
|
| |
@return CString object that provides access to the 8-bit String | @return CString object that provides access to the 8-bit String |
representation |
representation. |
| |
<pre> | <pre> |
String test = "abc"; | String test = "abc"; |
printf("test = %s\n", (const char*)test.getCString()); | printf("test = %s\n", (const char*)test.getCString()); |
|
|
|
NOTE: Do not do the following: |
|
const char * p = (const char *)test.getCString(); |
|
The pointer p will be invalid. This is because |
|
the CString object is destructed, which deletes |
|
the heap space for p. |
</pre> | </pre> |
*/ | */ |
CString getCString() const; | CString getCString() const; |
| |
/** Returns the specified character of the String object. | /** Returns the specified character of the String object. |
@param index Index of the character to access |
@param index Index of the character to access. |
|
@return specified character of the String object. |
@exception IndexOutOfBoundsException if the index | @exception IndexOutOfBoundsException if the index |
is outside the bounds of the String. | is outside the bounds of the String. |
<pre> | <pre> |
String t1 = "abc; |
String test = "abc; |
Char16 c = t1[1]; // character b |
Char16 c = test[1]; |
</pre> | </pre> |
*/ | */ |
Char16& operator[](Uint32 index); | Char16& operator[](Uint32 index); |
| |
/** Returns the specified character of the String object (const version). | /** Returns the specified character of the String object (const version). |
@param index Index of the character to access |
@param index Index of the character to access. |
|
@return specified character of the String object. |
@exception IndexOutOfBoundsException if the index | @exception IndexOutOfBoundsException if the index |
is outside the bounds of the String. | is outside the bounds of the String. |
*/ | */ |
|
|
| |
/** Append the given character to this String. | /** Append the given character to this String. |
@param c Character to append. | @param c Character to append. |
@return This String |
@return This String. |
<pre> | <pre> |
String t1 = "abc"; |
String test = "abc"; |
t1 += Char16('d') |
test.append(Char16('d')); |
assert(t1 == "abcd"); |
assert(test == "abcd"); |
</pre> | </pre> |
*/ | */ |
String& append(const Char16& c); | String& append(const Char16& c); |
|
|
| |
/** Append the given String to this String. | /** Append the given String to this String. |
@param str String to append. | @param str String to append. |
@return This String |
@return This String. |
<pre> | <pre> |
String test = "abc"; | String test = "abc"; |
test.append("def"); | test.append("def"); |
|
|
/** Remove size characters from the string starting at the given | /** Remove size characters from the string starting at the given |
index. If size is PEG_NOT_FOUND, then all characters after index are | index. If size is PEG_NOT_FOUND, then all characters after index are |
removed. | removed. |
@param index Position in string to start remove |
@param index Position in string to start remove. |
@param size Number of characters to remove. Default is PEG_NOT_FOUND | @param size Number of characters to remove. Default is PEG_NOT_FOUND |
which causes all characters after index to be removed |
which causes all characters after index to be removed. |
<pre> | <pre> |
String s; | String s; |
s = "abc"; | s = "abc"; |
|
|
is PEG_NOT_FOUND, then all characters after index are added to the new | is PEG_NOT_FOUND, then all characters after index are added to the new |
string. | string. |
@return String with the defined substring. | @return String with the defined substring. |
<pre> |
|
s = "abcdefg"; |
|
s.remove(3); |
|
assert(String::equal(s, "abc")); |
|
</pre> |
|
*/ | */ |
String subString(Uint32 index, Uint32 length = PEG_NOT_FOUND) const; | String subString(Uint32 index, Uint32 length = PEG_NOT_FOUND) const; |
| |
/** Find the index of the first occurence of the character c. | /** Find the index of the first occurence of the character c. |
If the character is not found, PEG_NOT_FOUND is returned. | If the character is not found, PEG_NOT_FOUND is returned. |
@param c Char to be found in the String |
@param c Char to be found in the String. |
@return Position of the character in the string or PEG_NOT_FOUND if not | @return Position of the character in the string or PEG_NOT_FOUND if not |
found. | found. |
*/ | */ |
Uint32 find(Char16 c) const; | Uint32 find(Char16 c) const; |
| |
/** Same as above but starts searching from the given index. */ |
/** Same as above but starts searching from the given index. |
|
*/ |
Uint32 find(Uint32 index, Char16 c) const; | Uint32 find(Uint32 index, Char16 c) const; |
| |
/** Find the index of the first occurence of the string object. | /** Find the index of the first occurence of the string object. |
This function finds one string inside another |
This function finds one string inside another. |
If the matching substring is not found, PEG_NOT_FOUND is returned. | If the matching substring is not found, PEG_NOT_FOUND is returned. |
@param s String object to be found in the String |
@param s String object to be found in the String. |
@return Position of the substring in the String or PEG_NOT_FOUND if not | @return Position of the substring in the String or PEG_NOT_FOUND if not |
found. | found. |
*/ | */ |
Uint32 find(const String& s) const; | Uint32 find(const String& s) const; |
| |
/** reverseFind - Same as find() but start looking in reverse (last |
/** Same as find() but start looking in reverse (last character first). |
character first). |
|
@param c Char16 character to find in String. | @param c Char16 character to find in String. |
@Seealso find |
|
@return Position of the character in the string or PEG_NOT_FOUND if not | @return Position of the character in the string or PEG_NOT_FOUND if not |
found. | found. |
|
|
NOTE: This function is defined only for char* input, not for |
|
String. |
|
*/ | */ |
Uint32 reverseFind(Char16 c) const; | Uint32 reverseFind(Char16 c) const; |
| |
|
|
@param s1 First null-terminated string for the comparison. | @param s1 First null-terminated string for the comparison. |
@param s2 Second null-terminated string for the comparison. | @param s2 Second null-terminated string for the comparison. |
@param n Number of characters to compare. | @param n Number of characters to compare. |
@return Return -1 if s1 is lexographically less than s2. If they are |
@return Return -1 if s1 is lexographically less than s2; if they are |
equavalent return 0. Otherwise return 1. |
equavalent return 0; otherwise return 1. |
*/ | */ |
static int compare(const String& s1, const String& s2, Uint32 n); | static int compare(const String& s1, const String& s2, Uint32 n); |
| |
/** Compare two null-terminated strings. | /** Compare two null-terminated strings. |
@param s1 First null-terminated string for the comparison. | @param s1 First null-terminated string for the comparison. |
@param s2 Second null-terminated string for the comparison. | @param s2 Second null-terminated string for the comparison. |
@return If s1 is less than s2, return -1; if equal return 0; |
@return Return -1 if s1 is less than s2; if equal return 0; |
otherwise, return 1. |
otherwise return 1. |
| |
NOTE: Use the comparison operators <,<= > >= to compare | NOTE: Use the comparison operators <,<= > >= to compare |
String objects. | String objects. |
*/ | */ |
static int compare(const String& s1, const String& s2); | static int compare(const String& s1, const String& s2); |
| |
/** Just like one above except ignores case differences. |
/** Just like the compare method defined above except that |
|
the compareNoCase ignores case differences. |
*/ | */ |
static int compareNoCase(const String& s1, const String& s2); | static int compareNoCase(const String& s1, const String& s2); |
| |
|
|
@param s1 First <TT>String</TT> for comparison. | @param s1 First <TT>String</TT> for comparison. |
@param s2 Second <TT>String</TT> for comparison. | @param s2 Second <TT>String</TT> for comparison. |
| |
@return Boolean true if the two strings are equal. |
@return true if the two strings are equal, false otherwise. |
<pre> | <pre> |
String s1 = "Hello World"; | String s1 = "Hello World"; |
String s2 = s1; | String s2 = s1; |
|
|
*/ | */ |
static Boolean equal(const String& str1, const String& str2); | static Boolean equal(const String& str1, const String& str2); |
| |
/** equalNoCase - Compares two strings and returuns true if they |
/** Compares two strings and returns true if they |
are equal indpedent of case of the characters. |
are equal indepedent of case of the characters. |
@param str1 First String parameter |
@param str1 First String parameter. |
@param str2 Second String parameter |
@param str2 Second String parameter. |
@return true if strings are equal independent of case. |
@return true if strings are equal independent of case, flase |
|
otherwise. |
*/ | */ |
static Boolean equalNoCase(const String& str1, const String& str2); | static Boolean equalNoCase(const String& str1, const String& str2); |
| |
/** match matches a string against a GLOB style pattern. |
// UTF8 specific code: |
Return trues if the String parameter matches the pattern. C-Shell style |
String& assignUTF8(const char* str); |
glob matching is used. |
CString getCStringUTF8() const; |
@param str String to be matched against the pattern |
static Boolean isUTF8(const char*); |
@param pattern Pattern to use in the match |
|
@return Boolean true if str matches pattern |
|
The pattern definition is as follows: |
|
<pre> |
|
* Matches any number of any characters |
|
? Match exactly one character |
|
[chars] Match any character in chars |
|
[chara-charb] Match any character in the range between chara and charb |
|
</pre> |
|
The literal characters *, ?, [, ] can be included in a string by |
|
escaping them with backslash "\". Ranges of characters can be concatenated. |
|
<pre> |
|
examples: |
|
Boolean result = String::match("This is a test", "*is*"); |
|
Boolean works = String::match("abcdef123", "*[0-9]"); |
|
</pre> |
|
*/ |
|
static Boolean match(const String& str, const String& pattern); |
|
|
|
/** matchNoCase Matches a String against a GLOB style pattern independent |
|
of case. |
|
Returns true if the str parameter matches the pattern. C-Shell style |
|
glob matching is used. Ignore case in all comparisons. Case is |
|
ignored in the match. |
|
@parm str String containing the string to be matched\ |
|
@parm pattern GLOB style patterh to use in the match. |
|
@return Boolean true if str matches patterh |
|
@SeeAlso match |
|
*/ |
|
static Boolean matchNoCase(const String& str, const String& pattern); |
|
| |
private: | private: |
| |
|
|
| |
/** String operator ==. Test for equality between two strings of any of the | /** String operator ==. Test for equality between two strings of any of the |
types String or char*. | types String or char*. |
@return Boolean - True if the strings are equal |
@return true if the strings are equal, false otherwise. |
*/ | */ |
PEGASUS_COMMON_LINKAGE Boolean operator==( | PEGASUS_COMMON_LINKAGE Boolean operator==( |
const String& str1, | const String& str1, |
const String& str2); | const String& str2); |
| |
/** String operator ==. Test for equality between two strings |
/** String operator ==. Test for equality between two strings. |
|
|
*/ | */ |
PEGASUS_COMMON_LINKAGE Boolean operator==(const String& str1, const char* str2); | PEGASUS_COMMON_LINKAGE Boolean operator==(const String& str1, const char* str2); |
| |
/** String operator ==. Test for equality between two strings |
/** String operator ==. Test for equality between two strings. |
|
|
*/ | */ |
PEGASUS_COMMON_LINKAGE Boolean operator==(const char* str1, const String& str2); | PEGASUS_COMMON_LINKAGE Boolean operator==(const char* str1, const String& str2); |
| |
/** String operator ==. Test for equality between two strings |
/** String operator ==. Test for equality between two strings. |
|
|
*/ | */ |
PEGASUS_COMMON_LINKAGE Boolean operator!=( | PEGASUS_COMMON_LINKAGE Boolean operator!=( |
const String& str1, | const String& str1, |
const String& str2); | const String& str2); |
| |
|
/// |
PEGASUS_COMMON_LINKAGE PEGASUS_STD(ostream)& operator<<( | PEGASUS_COMMON_LINKAGE PEGASUS_STD(ostream)& operator<<( |
PEGASUS_STD(ostream)& os, | PEGASUS_STD(ostream)& os, |
const String& str); | const String& str); |
| |
/** overload operator + - Concatenates String objects. | /** overload operator + - Concatenates String objects. |
|
|
<pre> | <pre> |
String t1 = "abc"; | String t1 = "abc"; |
String t2; | String t2; |
|
|
const String& str2); | const String& str2); |
| |
/** overload operator <= compares String objects. | /** overload operator <= compares String objects. |
|
|
*/ | */ |
PEGASUS_COMMON_LINKAGE Boolean operator<=( | PEGASUS_COMMON_LINKAGE Boolean operator<=( |
const String& str1, | const String& str1, |