#include <coherence/lang/String.hpp>
Inherits Comparable.
In addition to exposing the underlying char array, the String class supports transformations to and from Unicode code points within the Basic Multilingual Plane (BMP):
Note: the ASCII character set is a subset of UTF-8 BMP.
Unlike most managed types in the Coherence class hierarchy, Strings are auto-boxable by default. That is a String::Handle or String::View can be directly assigned from or to common string representations. For example the following code is legal:
String::Handle hs = "hello world";
void someFunction(String::View vs); someFunction("some value");
Public Types | |||||||
typedef spec::Handle | Handle | ||||||
String Handle definition. | |||||||
typedef spec::View | View | ||||||
String View definition. | |||||||
typedef spec::Holder | Holder | ||||||
String Holder definition. | |||||||
typedef std::string | BoxedType | ||||||
While StringHandle boxes a number of common string types, String is still compatible with BoxHandle, and when used with it can box to only one type. | |||||||
typedef StringHandle < String > | Handle | ||||||
Handle definition. | |||||||
typedef StringHandle < const String > | View | ||||||
View definition. | |||||||
Public Member Functions | |||||||
virtual bool | isASCII () const | ||||||
Return true iff the String contains only ASCII (ISO-8859-1) characters. | |||||||
virtual size32_t | length () const | ||||||
Return the number of unicode code points (characters) in this String. | |||||||
virtual const char * | getCString () const | ||||||
Return the String as a C-style NUL terminated char array. | |||||||
virtual bool | equals (const char *ach, size32_t cch=npos) const | ||||||
Compare this String against the supplied C-style string. | |||||||
virtual bool | equals (const wchar_t *ach, size32_t cch=npos) const | ||||||
Compare this String against the supplied C-style wide char string. | |||||||
template<class C, class R, class A> | |||||||
bool | equalsStd (const std::basic_string< C, R, A > &s) const | ||||||
Compare this String against the supplied STL string or wstring. | |||||||
template<class C, class R, class A> | |||||||
o () const | |||||||
Convert the String to any of the types supported by StringHandle, namely an STL string or wstring. | |||||||
virtual size32_t | indexOf (String::View vsSearch, size32_t iBegin=0) const | ||||||
Return the index of a substring within this String. | |||||||
virtual size32_t | indexOf (char16_t chSearch, size32_t iBegin=0) const | ||||||
Return the index of a character within this String. | |||||||
virtual size32_t | lastIndexOf (String::View vsSearch, size32_t iBegin=npos) const | ||||||
Return the index of a substring within this String by searching backward from the given beginning index. | |||||||
virtual size32_t | lastIndexOf (char16_t chSearch, size32_t iBegin=npos) const | ||||||
Return the index of a substring within this String by searching backward from the given beginning index. | |||||||
virtual String::View | substring (size32_t iBegin, size32_t iEnd=npos) const | ||||||
Return a new String comprised of the substring of this string from iBegin (inclusive) to iEnd (exclusive). | |||||||
virtual bool | startsWith (String::View vsSearch) const | ||||||
Return true if this String starts with the supplied String. | |||||||
virtual bool | endsWith (String::View vsSearch) const | ||||||
Return true if this String ends with the supplied String. | |||||||
virtual bool | regionMatches (size32_t ofSourse, String::View vsOther, size32_t ofOther=0, size32_t cch=npos) const | ||||||
A substring of this String is compared to a substring of a supplied String. | |||||||
String::View | trim () const | ||||||
Return a String that is the result of removing all leading and trailing white space. | |||||||
virtual Array < octet_t >::View | getOctets () const | ||||||
Return the underlying UTF-8 BMP NUL terminated Array<octet_t>. | |||||||
virtual int32_t | compareTo (Object::View v) const | ||||||
Compare this object with the specified object for order. Return a negative integer, zero, or a positive integer if this object is less than, equal to, or greater than the specified object.
It is strongly recommended, but not strictly required, that
| |||||||
virtual size32_t | hashCode () const | ||||||
Return a hash code value for the Object. This method is supported for the benefit of hash-based containers.
The general contract of
The default implementation is identity based.
| |||||||
virtual void | toStream (std::ostream &out) const | ||||||
Output a human-readable description of this Object to the given stream. coherence::lang::operator<<(std::ostream, Object::View) is defined and will call into the toStream method, to output Objects. If a managed String object is desired, the COH_TO_STRING macro can be used to build up a String from streamable contents.
Object::View vKey = ... Object::View vValue = ... std::cout << vKey << " = " << vValue << std::endl; String::Handle hs = COH_TO_STRING(vKey << " = " << vValue);
| |||||||
virtual bool | isImmutable () const | ||||||
Return true iff no further changes can be made to the Object, that would effect the outcome of a call to its equals method.Except for Objects which are naturally immutable (such as String), being immutable generally implies that the Object is only referenced via const pointers or views. Objects which hold references to child Objects, may need to take the immutability of their children into account when determining their own immutability. This extended check is not performed by the default implementation, but can be integrated into the immutability checks by overriding this method, as well as making use of MemberHandles to reference child Objects. A typical derived implementation may look as follows:
bool isImmutable() const { if (m_fImmutable) // check recorded state { return true; // already marked as immutable, avoid calculation } else if (Object::isImmutable()) // ensure shallow immutability { // ensure deep immutability if (m_child1->isImmutable() && m_child2->isImmutable() ... && m_childN->isImmutable()) { // record and return immutability return m_fImmutable = true; } // some Objects which comprise this Object are still mutable } return false; } The default implementation return true iff the Object is only referenced via const pointers and or views.
| |||||||
virtual bool | equals (Object::View v) const | ||||||
Return true iff the specified Object is "equal" to this Object. This method implements an equivalence relation on Objects:
The default implementation is a reference equality comparison.
| |||||||
virtual size64_t | sizeOf (bool fDeep=false) const | ||||||
Return an estimate as to the byte size of the object. The shallow size should not include the cost of referenced managed objects, or non-fixed dynamically allocated memory. That for a given object it is assumed that a call to this method will always return the same value when the shallow size is requested. The deep size should be the shallow size plus the size of any referenced objects. Unlike the shallow size the deep size may change over time. The default implementation provided by Object will traverse the object graph of all managed objects which it references and include their sizes in the computed deep size. In general it is sufficient to simply delegate to super::sizeOf(true) for deep calculations. For classes implemented via class_spec, a variant of this method will be automatically produced which will utilize sizeof(*this) to compute the shallow size, and super::sizeOf(true) to compute the deep size. As such it is generally not necessary to provide custom implmenetations of this method.
| |||||||
Static Public Member Functions | |||||||
static String::Handle | create (const char *achSrc="", size32_t cch=npos) | ||||||
Create a String from a C-style NUL terminated char array. | |||||||
static String::Handle | create (const wchar_t *achSrc, size32_t cch=npos) | ||||||
Create a String from a C-style NUL terminated wide char array. | |||||||
template<class C, class R, class A> | |||||||
static String::Handle | create (const std::basic_string< C, R, A > &s) | ||||||
Create a String from an STL string. | |||||||
static String::Handle | create (Array< char >::View vachSrc, size32_t of=0, size32_t cch=npos) | ||||||
Create a String from a char array. | |||||||
static String::Handle | create (Array< wchar_t >::View vachSrc, size32_t of=0, size32_t cch=npos) | ||||||
Create a String from a wide char array. | |||||||
static String::Handle | create (Array< octet_t >::View vabSrc, size32_t of=0, size32_t cb=npos) | ||||||
Create a String from an octet array. | |||||||
static String::Handle | create (Array< char16_t >::View vachSrc, size32_t of=0, size32_t cch=npos) | ||||||
Create a String from a 16-bit char array. | |||||||
static String::Handle | create (const String &that) | ||||||
Create a String from another String. | |||||||
static char16_t | next (const char *&ach) | ||||||
Return the Unicode character as UTF-16 from the char array, and increment the pointer such that it references the start of the next Unicode character. | |||||||
Static Public Attributes | |||||||
static const size32_t | npos | ||||||
The largest possible value of type size32_t. | |||||||
static const char *const | null_string | ||||||
String referencing NULL. | |||||||
Protected Attributes | |||||||
size32_t | m_ccp | ||||||
The number of unicode code points (characters) in the String. | |||||||
Classes | |||||||
class | StringHandle | ||||||
StringHandle provides standard TypedHandle features as well as auto-boxing support for standard string types including:. More... |
typedef std::string BoxedType |
While StringHandle boxes a number of common string types, String is still compatible with BoxHandle, and when used with it can box to only one type.
By default Strings are boxable from a number of types, see StringHandle for details.
static String::Handle create | ( | const char * | achSrc = "" , |
|
size32_t | cch = npos | |||
) | [static] |
Create a String from a C-style NUL terminated char array.
ach | the NUL terminated string of chars to copy | |
cch | the number of chars to copy; if npos, until NUL |
IllegalArgumentException | if any of the elements in the array are not UTF-8 BMP |
static String::Handle create | ( | const wchar_t * | achSrc, | |
size32_t | cch = npos | |||
) | [static] |
Create a String from a C-style NUL terminated wide char array.
ach | the NUL terminated string of wide chars to copy | |
cch | the number of chars to copy; if npos, copy until NUL |
IllegalArgumentException | if any of the elements in the array are not UTF-16 BMP |
static String::Handle create | ( | const std::basic_string< C, R, A > & | s | ) | [inline, static] |
Create a String from an STL string.
s | the STL string to copy |
IllegalArgumentException | if any of the elements in the array are not UTF-8 BMP |
static String::Handle create | ( | Array< char >::View | vachSrc, | |
size32_t | of = 0 , |
|||
size32_t | cch = npos | |||
) | [static] |
Create a String from a char array.
vach | the array of chars to copy | |
of | the offset at which to start copying | |
cch | the number of chars to copy; if npos, copy all subsequent chars in the array |
IndexOutOfBoundsException | if of > vach->length or if cch < npos and of + cch > vach->length | |
IllegalArgumentException | if any of the elements in the array are not UTF-8 BMP |
static String::Handle create | ( | Array< wchar_t >::View | vachSrc, | |
size32_t | of = 0 , |
|||
size32_t | cch = npos | |||
) | [static] |
Create a String from a wide char array.
vach | the array of chars to copy | |
of | the offset at which to start copying | |
cch | the number of chars to copy; if npos, copy all subsequent chars in the array |
IndexOutOfBoundsException | if of > vach->length or if cch < npos and of + cch > vach->length | |
IllegalArgumentException | if any of the elements in the array are not UTF-16 BMP | |
UnsupportedOperationException | if sizeof(wchar_t) < sizeof(char16_t) |
static String::Handle create | ( | Array< octet_t >::View | vabSrc, | |
size32_t | of = 0 , |
|||
size32_t | cb = npos | |||
) | [static] |
Create a String from an octet array.
vab | the array of octets to copy | |
of | the offset at which to start copying | |
cb | the number of octets to copy; if npos, copy all subsequent octets in the array |
IndexOutOfBoundsException | if of > vab->length or if cb < npos and of + cb > vab->length | |
IllegalArgumentException | if any of the elements in the array are not UTF-8 BMP |
static String::Handle create | ( | Array< char16_t >::View | vachSrc, | |
size32_t | of = 0 , |
|||
size32_t | cch = npos | |||
) | [static] |
Create a String from a 16-bit char array.
vach | the array of chars to copy | |
of | the offset at which to start copying | |
cch | the number of chars to copy; if npos, copy all subsequent chars in the array |
IndexOutOfBoundsException | if of > vach->length or if cch < npos and of + cch > vach->length | |
IllegalArgumentException | if any of the elements in the array are not UTF-16 BMP |
static String::Handle create | ( | const String & | that | ) | [static] |
virtual bool isASCII | ( | ) | const [virtual] |
virtual size32_t length | ( | ) | const [virtual] |
virtual const char* getCString | ( | ) | const [virtual] |
Return the String as a C-style NUL terminated char array.
If the String is non-ASCII then the String::next() method may be used to expand the char array into a sequence of char16_t unicode characters.
The returned array's lifetime is bound to the lifetime of the String which it was returned from. Specifically it is unsafe to use the returned char* while not holding a handle to the String.
virtual bool equals | ( | const char * | ach, | |
size32_t | cch = npos | |||
) | const [virtual] |
virtual bool equals | ( | const wchar_t * | ach, | |
size32_t | cch = npos | |||
) | const [virtual] |
Compare this String against the supplied C-style wide char string.
ach | the NUL terminated C-style string to compare to this String | |
cch | the length of the supplied string, or npos to rely on NUL terminator |
UnsupportedOperationException | if sizeof(wchar_t) < sizeof(char16_t) |
bool equalsStd | ( | const std::basic_string< C, R, A > & | s | ) | const [inline] |
o | ( | ) | const [inline] |
Convert the String to any of the types supported by StringHandle, namely an STL string or wstring.
virtual size32_t indexOf | ( | String::View | vsSearch, | |
size32_t | iBegin = 0 | |||
) | const [virtual] |
virtual size32_t indexOf | ( | char16_t | chSearch, | |
size32_t | iBegin = 0 | |||
) | const [virtual] |
virtual size32_t lastIndexOf | ( | String::View | vsSearch, | |
size32_t | iBegin = npos | |||
) | const [virtual] |
virtual size32_t lastIndexOf | ( | char16_t | chSearch, | |
size32_t | iBegin = npos | |||
) | const [virtual] |
virtual String::View substring | ( | size32_t | iBegin, | |
size32_t | iEnd = npos | |||
) | const [virtual] |
Return a new String comprised of the substring of this string from iBegin (inclusive) to iEnd (exclusive).
iBegin | the starting index from which to create the string | |
iEnd | the index of where the substring should stop in this String or npos for end of string |
virtual bool startsWith | ( | String::View | vsSearch | ) | const [virtual] |
virtual bool endsWith | ( | String::View | vsSearch | ) | const [virtual] |
virtual bool regionMatches | ( | size32_t | ofSourse, | |
String::View | vsOther, | |||
size32_t | ofOther = 0 , |
|||
size32_t | cch = npos | |||
) | const [virtual] |
A substring of this String is compared to a substring of a supplied String.
ofSource | the offset in this String where comparison begins | |
vsOther | the String whose substring is compared against this String | |
ofOther | the offset in vsOther where comparison begins | |
cch | the count of characters to compare, or npos for (vsOther->length - ofOther) |
String::View trim | ( | ) | const |
Return the underlying UTF-8 BMP NUL terminated Array<octet_t>.
For performance reasons the returned Array may not support cloning. If clone() is called the result will a String, which depending on the compiler's handling of dynamic_cast to a private super class may fail to be castable to an Array<octet_t>.
static char16_t next | ( | const char *& | ach | ) | [static] |
Return the Unicode character as UTF-16 from the char array, and increment the pointer such that it references the start of the next Unicode character.
ach | pointer to the start of the next UTF-8 code point. |
IllegalArgumentException | if a non UTF-8 BMP sequence is encountered |
const char* const null_string [static] |
String referencing NULL.
This constant is generally only needed for defining a default value for a function parameter:
void function(String::View vs = String::null_string)
Simply passing NULL as a default is not allowable for Strings as due to auto-boxing the compiler is unable to determine if NULL indicates a String* or a char*. For all other uses of NULL with String the literal NULL is preferred.