rwsf::CString
Group: General- Local Index
- Header File
- Description
- Enumerations
- Public Constructors
- Destructor
- Assignment Operators
- Conversion Operator
- Indexing Operators
- Public Member Functions
- Static Public Member Functions
- Related Global Functions
- Global Logical Operators
Local Index
Members
Non-Members
|
operator!=() operator>() operator>=() |
operator<() operator<=() operator+() |
operator==() rwsfhash() strXForm() |
toLower() toUpper() |
Header File
#include <rwsf/core/CString.h>
Description
This class is deprecated. Please use std::string instead.
Class rwsf::CString offers powerful and convenient facilities for manipulating strings.
Although the class is primarily intended to be used to handle single-byte character sets (SBCS; such as ASCII or ISO Latin-1), with care it can be used to handle multibyte character sets (MBCS). There are two things that must be kept in mind when working with MBCS:
Because characters can be more than one byte long, the number of bytes in a string can, in general, be greater than the number of characters in the string. Use function rwsf::CString::length() to get the number of bytes in a string, function rwsf::CString::mbLength() to get the number of characters. Note that the latter is much slower because it must determine the number of bytes in every character. Hence, if the string is known to be nothing but SBCS, then rwsf::CString::length() is preferred.
One or more bytes of a multibyte character can be zero. Hence, MBCS cannot be counted on being null terminated. In practice, it is a rare MBCS that uses embedded nulls. Nevertheless, you should be aware of this and program defensively. In any case, class rwsf::CString can handle embedded nulls.
Parameters of type "const char*" must not be passed a value of zero. This is detected in the debug version of the library.
A separate class rwsf::CSubString supports substring extraction and modification operations.
Enumerations
enum stripType {leading = 0x1, trailing = 0x2, both = 0x3};
Used to specify whether characters are stripped from the beginning of the string, the end, or both.
enum caseCompare { exact, ignoreCase }
Used to specify whether comparisons, searches, and hashing functions should use case sensitive (exact) or case-insensitive (ignoreCase) semantics.
Public Constructors
CString();
Creates a string of length zero (the null string).
CString(const char* a);
Conversion from the null-terminated character string a. The created string will copy the data pointed to by a, up to the first terminating null. This function is incompatible with a strings with embedded nulls. This function may be incompatible with a MBCS strings.
CString(const char* a, size_t N);
Constructs a string from the character string a. The created string will copy the data pointed to by a. Exactly N bytes are copied, including any embedded nulls. Hence, the buffer pointed to by a must be at least N bytes long.
CString(size_T ic);
Creates a string of length zero (the null string). The string's capacity (that is, the size it can grow to without resizing) is given by the parameter ic. We recommend creating a size_t value from a numerical constant to pass into this constructor. While size_t knows how to convert size_t's to itself, conforming compilers will chose the conversion to char instead.
CString(const CString& S);
Copy constructor. The created string will copy S's data.
CString(char, size_t N);
Constructs a string, copying exactly N bytes.
CString(const CSubString& SS);
Conversion from sub-string. The created string will copy the substring represented by SS.
CString(const std::string &stdStr);
Constructor. Converts a std::string value to a CString.
Destructor
~CString();
Destructor.
Assignment Operators
CString& operator=(const char* cs);
Assignment operator. Copies the null-terminated character string pointed to by cs into self. Returns a reference to self. This function is incompatible with cs strings with embedded nulls. This function may be incompatible with cs MBCS strings.
CString& operator=(const std::string& str);
Assignment operator. The string will replace the string's data. Returns a reference to self.
CString& operator+=(const char*);
Append the null-terminated character string to self. Returns a reference to self. This function is incompatible with cs strings with embedded nulls. This function may be incompatible with cs MBCS strings.
CString& operator+=(const CString& s); CString& operator+=(char s);
Append the string s to self. Returns a reference to self.
Conversion Operator
operator std::string() const;
Conversion operator. Converts an rwsf::CString instance to a std::string value.
Indexing Operators
char& operator[](short); const; operator[](short); char& operator[](int); const; operator[](int); char& operator[](long) const; operator[](long); char& operator[](unsigned short); const; operator[](unsigned short); char& operator[](unsigned int); const; operator[](unsigned int); char& operator[](unsigned long); const; operator[](unsigned long); char& operator[](rwsflonglong); const; operator[](rwsflonglong); char& operator[](rwsfulonglong); const; operator[](rwsfulonglong); char&
Bounds checking is performed -- if the index is out of range then an exception of type rwsf::OutOfBoundsException will occur.
operator()(size_t i) const; operator()(size_t i);
Returns the ith byte. The first variant can be used as an lvalue. The index i must be between 0 and the length of the string less one. Bounds checking is performed if the pre-processor macro LEIF_BOUNDS_CHECK has been defined before including <rwsf\core/cstring.h>. In this case, if the index is out of range, then an exception of type rwsf::OutOfBoundsException will occur.
CSubString operator()(size_t start, size_t len); CSubString operator()(size_t start, size_t len) const;
Substring operator. Returns an rwsf::CSubString of self with length len, starting at index start. The first variant can be used as an lvalue.
The sum of start plus len must be less than or equal to the string length. If the library was built using the DEBUG flag, and start and len are out of range, then an exception of type rwsf::OutOfBoundsException will occur.
Public Member Functions
CString& append(const char* cs);
Append a copy of the null-terminated character string pointed to by cs to self. Returns a reference to self. This function is incompatible with cs strings with embedded nulls. This function may be incompatible with cs MBCS strings.
CString& append(const char* cs, size_t N);
Append a copy of the character string cs to self. Exactly N bytes are copied, including any embedded nulls. Hence, the buffer pointed to by cs must be at least N bytes long. Returns a reference to self.
CString& append(char c, size_t rep=1);
Append rep copies of the character c to self. The default is 1. Returns a reference to self.
CString& append(const CString& str);
Append a copy of the string str to self. Returns a reference to self.
CString& append(const CString& str, size_t N);
Append the first N bytes or the length of str (whichever is less) to self. Returns a reference to self.
size_t capacity() const;
Return the current capacity of self. This is the number of bytes the string can hold without resizing.
size_t capacity(size_t capac);
Hint to the implementation to change the capacity of self to capac. Returns the actual capacity.
int collate(const char* str) const; int collate(const CString& str) const;
Returns an int less then, greater than, or equal to zero.
int compareTo(const char* str,
caseCompare cmp = exact) const; int compareTo(const CString& str, YES caseCompare cmp = exact) const; int compareTo(const CString* st, caseCompare cmp = exact) const;
Returns an int less than, greater than, or equal to zero. Case sensitivity is according to the caseCompare argument, and may be CString::exact or CString::ignoreCase. If caseCompare is cmp = exact, then this function works for all string types. Otherwise, this function is incompatible with MBCS strings. This function is incompatible with const char* strings with embedded nulls. This function may be incompatible with const char* MBCS strings.
bool
contains(const char* str,
caseCompare cmp = exact) const;
bool
contains(const CString& cs,
caseCompare cmp = exact) const;
Pattern matching. Returns true if str occurs in self. Case sensitivity is according to the caseCompare argument, and may be CString::exact or CString::ignoreCase. If caseCompare is cmp = exact, then this function works for all string types. Otherwise, this function is incompatible with MBCS strings. This function is incompatible with const char* strings with embedded nulls. This function may be incompatible with const char* MBCS strings.
CString copy() const;
Makes a distinct copy. Attaches to and increments the reference count.
const char* data() const;
Access to the rwsf::CString's data as a null terminated string. This datum is owned by the rwsf::CString and may not be deleted or changed. If the rwsf::CString object itself changes or goes out of scope, the pointer value previously returned will become invalid. While the string is null terminated, note that its length is still given by the member function length(). That is, it may contain embedded nulls.
size_t first(char c) const;
Returns the index of the first occurrence of the character c in self. Returns RWSF_NPOS if there is no such character or if there is an embedded null prior to finding c. This function is incompatible with strings with embedded nulls. This function is incompatible with MBCS strings.
size_t first(char c, size_t) const;
Returns the index of the first occurrence of the character c in self. Continues to search past embedded nulls. Returns RWSF_NPOS if there is no such character. This function is incompatible with MBCS strings.
size_t first(const char* str) const;
Returns the index of the first occurrence in self of any character in str. Returns RWSF_NPOS if there is no match or if there is an embedded null prior to finding any character from str. This function is incompatible with strings with embedded nulls. This function may be incompatible with MBCS strings.
size_t first(const char* str, size_t N) const;
Returns the index of the first occurrence in self of any character in str. Exactly N bytes in str are checked including any embedded nulls so str must point to a buffer containing at least N bytes. Returns RWSF_NPOS if there is no match.
unsigned hash(caseCompare cmp = exact) const;
Returns a suitable hash value. If caseCompare is cmp = ignoreCase then this function will be incompatible with MBCS strings.
size_t
index(const char pat,size_t i=0,
caseCompare cmp = exact) const;
size_t
index(const char* pat,size_t i=0,
caseCompare cmp = exact) const;
size_t
index(const CString& s,size_t i=0,
caseCompare cmp = exact) const;
Pattern matching. Starting with index i, searches for the first occurrence of pat in self and returns the index of the start of the match. Returns RWSF_NPOS if there is no such pattern. Case sensitivity is according to the caseCompare argument; it defaults to cmp = exact. If caseCompare is cmp = exact, then this function works for all string types. Otherwise, this function is incompatible with MBCS strings.
size_t
index(const char* pat, size_t patlen,size_t i,
caseCompare cmp) const;
size_t
index(const CString& s, size_t patlen,size_t i,
caseCompare cmp) const;
Pattern matching. Starting with index i, searches for the first occurrence of the first patlen bytes from pat in self and returns the index of the start of the match. Returns RWSF_NPOS if there is no such pattern. Case sensitivity is according to the caseCompare argument. If caseCompare is cmp = exact, then this function works for all string types. Otherwise, this function is incompatible with MBCS strings.
CString& insert(size_t pos, const char* cs);
Insert a copy of the null-terminated string cs into self at byte position pos, thus expanding the string. Returns a reference to self. This function is incompatible with cs strings with embedded nulls. This function may be incompatible with cs MBCS strings.
CString& insert(size_t pos, const char* cs, size_t extent);
Insert a copy of the first N bytes of cs into self at byte position pos, thus expanding the string. Exactly N bytes are copied, including any embedded nulls. Hence, the buffer pointed to by cs must be at least N bytes long. Returns a reference to self.
CString& insert(size_t pos, const CString& str);
Insert a copy of the string str into self at byte position pos. Returns a reference to self.
CString& insert(size_t pos, const CString& str, size_t N);
Insert a copy of the first N bytes or the length of str (whichever is less) of str into self at byte position pos. Returns a reference to self.
bool isAscii() const;
Returns true if self contains no bytes with the high bit set.
bool isNull() const;
Returns true if this is a zero length string (i.e., the null string).
size_t last(char c) const;
Returns the index of the last occurrence in the string of the character c. Returns RWSF_NPOS if there is no such character or if there is an embedded null to the right of c in self. This function is incompatible with strings with embedded nulls. This function may be incompatible with MBCS strings.
size_t last(char c, size_t N) const;
Returns the index of the last occurrence in the string of the character c. Continues to search past embedded nulls. Returns RWSF_NPOS if there is no such character. This function is incompatible with MBCS strings.
size_t length() const;
Return the number of bytes in self. Note that if self contains multibyte characters, then this will not be the number of characters.
size_t mbLength() const;
Return the number of multibyte characters in self, according to the Standard C function ::mblen(). Returns RWSF_NPOS if a bad character is encountered. Note that, in general, mbLength() = length(). Provided only on platforms that provide ::mblen().
CString& prepend(const char* cs);
Prepend a copy of the null-terminated character string pointed to by cs to self. Returns a reference to self. This function is incompatible with cs strings with embedded nulls. This function may be incompatible with cs MBCS strings.
CString& prepend(const char* cs, size_t N);
Prepend a copy of the character string cs to self. Exactly N bytes are copied, including any embedded nulls. Hence, the buffer pointed to by cs must be at least N bytes long. Returns a reference to self.
CString& prepend(char c, size_t N);
Prepend N copies of character c to self. Returns a reference to self.
CString& prepend(const CString& str); CString&
Prepends a copy of the string str to self. Returns a reference to self.
CString& prepend(const CString& cstr, size_t N); CString&
Prepend the first N bytes or the length of cstr (whichever is less) of cstr to self. Returns a reference to self.
CString& remove(size_t pos);
Removes the bytes from the byte position pos, which must be no greater than length(), to the end of string. Returns a reference to self.
CString& remove(size_t pos, size_t N);
Removes N bytes or to the end of string (whichever comes first) starting at the byte position pos, which must be no greater than length(). Returns a reference to self.
CString& replace(size_t pos, size_t N, const char* cs);
Replaces N bytes or to the end of string (whichever comes first) starting at byte position pos, which must be no greater than length(), with a copy of the null-terminated string cs. Returns a reference to self. This function is incompatible with cs strings with embedded nulls. This function may be incompatible with cs MBCS strings.
CString& replace(size_t pos, size_t N1,const char* cs, size_t N2);
Replaces N1 bytes or to the end of string (whichever comes first) starting at byte position pos, which must be no greater than length(), with a copy of the string cs. Exactly N2 bytes are copied, including any embedded nulls. Hence, the buffer pointed to by cs must be at least N2 bytes long. Returns a reference to self.
CString& replace(size_t pos, size_t N, const CString& str);
Replaces N bytes or to the end of string (whichever comes first) starting at byte position pos, which must be no greater than length(), with a copy of the string str. Returns a reference to self.
CString&
replace(size_t pos, size_t N1,const CString& str,
size_t N2);
Replaces N1 bytes or to the end of string (whichever comes first) starting at position pos, which must be no greater than length(), with a copy of the first N2 bytes, or the length of str (whichever is less), from str. Returns a reference to self.
void resize(size_t n);
Changes the length of self to n bytes, adding blanks or truncating as necessary.
CSubString strip(stripType s = trailing, char c = ' ');
Returns a substring of self where the character c has been stripped off the beginning, end, or both ends of the string. The first variant can be used as an lvalue.
The enum stripType can take values:
Table 1: rwsf::CString stripType Values
| stripType | Meaning |
leading | Remove characters at beginning |
trailing | Remove characters at end |
both | Remove characters at both ends |
CSubString stripWhitespace(stripType s = trailing) const; stripWhitespace(stripType s = trailing)
Returns a substring of self stripped of whitespace at beginning and/or end.
void toLower();
Changes all upper-case letters in self to lower-case. This function is incompatible with MBCS strings.
void toUpper();
Changes all lower-case letters in self to upper-case. This function is incompatible with MBCS strings.
Static Public Member Functions
static size_t byteCount(const char *str, size_t nChars = LEIF_NPOS);
Given a multibyte sequence, str, and a number of multibyte characters to consider, nChars, this method calculates the number of bytes required to store the sequence. If nChars is LEIF_NPOS, then the method counts characters up to, but not including, the first NULL character in the sequence. The method returns the number of bytes required to represent the string. If an error occurs during the operation, then RWSF_NPOS is returned.
static unsigned hash(const CString& str);
Returns the hash value of str as returned by str.hash(CString::exact).
static size_t mbLength(const char* str, size_t nBytes = LEIF_NPOS);
Given a multibyte character sequence, str, and a number of bytes to consider, nBytes, this method calculates the number of multibyte characters in the sequence. If nBytes is LEIF_NPOS, then the method counts the characters up to, but not including, the first occurrence of a NULL character. The method returns the length, in characters, of the input multibyte sequence if successful. If an error occurs in the conversion, then RWSF_NPOS is returned.
Related Global Functions
unsigned rwsfhash(const CString& s); unsigned rwsfhash(const CString* s);
Returns a hash value derived from s.
CString strXForm(const CString& str);
Returns the result of applying ::strxfrm() to the argument string, to allow quicker collation than CString::collate(). Provided only on platforms that provide ::strxfrm(). This function is incompatible with strings with embedded nulls.
CString toLower(const CString& str);
Returns a version of str where all upper-case characters have been replaced with lower-case characters. Uses the Standard C Library function tolower(). This function is incompatible with MBCS strings.
CString toUpper(const CString& str);
Returns a version of str where all lower-case characters have been replaced with upper-case characters. Uses the Standard C Library function toupper(). This function is incompatible with MBCS strings.
Global Logical Operators
bool operator==(const CString& s1, const CString& s2); bool operator==(const char* s1, const CString& s2); bool operator==(const CString& str, char c); bool operator==(char c, const CString& str);
Returns true if the string is lexicographically equal to the character string or rwsf::CString argument. Case sensitivity is exact.
CString operator+(const CString& str, char c); CString operator+(char c, const CString& str);
Concatenation operators.
bool operator<(const CString& s1, const CString& s2); bool operator<(const CString& s1, const char* s2); bool operator<(const char* s1, const CString& s2); bool operator<(const CString& str, char c); bool operator< char c, const CString& str);
Returns true if the string is lexicographically less than the character string. Case sensitivity is exact.
bool operator!=(const CString& s1, const CString& s2); bool operator!=(const CString& s1, const char* s2); bool operator!=(const char* s1, const CString& s2); bool operator!=(const CString& str, char c); bool operator!=(char c, const CString& str);
Returns true if the string is lexicographically unequal to the character string. Case sensitivity is exact.
bool operator>(const CString& s1, const CString& s2); bool operator>(const CString& s1, const char* s2); bool operator>(const char* s1, const CString& s2); bool operator>(const CString& str, char c); bool operator>(char c, const CString& str);
Returns true if the string is lexicographically more than the character string. Case sensitivity is exact.
bool operator<=(const CString& s1, const CString& s2); bool operator<=(const CString& s1, const char* s2); bool operator<=(const char* s1, const CString& s2); bool operator<=(const CString& str, char c); bool operator<=(char c, const CString& str);
Returns true if the string is lexicographically less than or equal to the character string. Case sensitivity is exact.
bool operator>=(const CString& s1, const CString& s2); bool operator>=(const CString& s1, const char* s2); bool operator>=(const char* s1, const CString& s2); bool operator>=(const CString& str, char c); bool operator>=(char c, const CString& str);
Returns true if the string is lexicographically more than or equal to the character string. Case sensitivity is exact.
©2004-2007 Copyright Quovadx, Inc. All Rights Reserved.
Quovadx and Rogue Wave are registered trademarks and HydraSDO is a trademark of Quovadx, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.