#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 bool | isCString () const |
| Return true if the String is ASCII and does not contain embedded nuls. | |
| virtual size32_t | length () const |
| Return the number of unicode code points (characters) in this String. | |
| virtual bool | isEmpty () const |
| Returns true if, and only if, length() is 0. | |
| 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> | |
| __attribute__ ((always_inline)) inline bool equalsStd(const std | |
| Compare this String against the supplied STL string or wstring. | |
| template<class C, class R, class A> | |
| __attribute__ ((always_inline)) inline operator std | |
| 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 (wchar16_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 (wchar16_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 that is a substring of this string. | |
| 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>. | |
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 | __attribute__ ((always_inline)) inline String |
| 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< wchar16_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 Public Attributes | |
| static const size32_t | npos |
| The largest possible value of type size32_t. | |
| static const char *const | null_string |
| Returns the string representation of the {. | |
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 __attribute__ | ( | (always_inline) | ) | [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(wchar16_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< wchar16_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 bool isCString | ( | ) | const [virtual] |
| virtual size32_t length | ( | ) | const [virtual] |
| virtual bool isEmpty | ( | ) | 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 wchar16_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(wchar16_t) |
| __attribute__ | ( | (always_inline) | ) | const [inline] |
| __attribute__ | ( | (always_inline) | ) | [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 | ( | wchar16_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 | ( | wchar16_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 that is a substring of this string.
The substring begins at the specified iBegin and extends to the character at index iEnd - 1. Thus the length of the substring is iEnd-iBegin.
| 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 |
| IndexOutOfBoundsException | if iEnd is larger than the length of this String object, or if iBegin is larger than iEnd. |
| 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>.
const char* const null_string [static] |
Returns the string representation of the {.
v} argument. @param v an Object. @return if the argument is {@code NULL}, then a string equal to {@code "NULL"}; otherwise, the value of {@code v->toString()} is returned @see Object#toString() @since 12.2.1 */ static String::View valueOf(Object::View v); // ----- Array interface ------------------------------------------------ protected: using Array<octet_t>::regionMatches; // ----- Comparable interface ------------------------------------------- public: /** {@inheritDoc} */ virtual int32_t compareTo(Object::View v) const; // ----- Object interface ----------------------------------------------- public: /** {@inheritDoc} */ virtual size32_t hashCode() const; /** {@inheritDoc} */ virtual TypedHandle<const String> toString() const; /** {@inheritDoc} */ virtual bool isImmutable() const; /** {@inheritDoc} */ virtual bool equals(Object::View v) const; /** {@inheritDoc} */ virtual size64_t sizeOf(bool fDeep = false) const; // ----- static helpers ------------------------------------------------- public: /** 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. @param ach pointer to the start of the next UTF-8 code point. @return the next Unicode character @throws IllegalArgumentException if a non UTF-8 BMP sequence is encountered */ static wchar16_t next(const char*& ach); // ----- data members --------------------------------------------------- protected: /** The number of unicode code points (characters) in the String. */ size32_t m_ccp; /** True iff the String is a C string. */ bool m_fCString; // ----- constants ------------------------------------------------------ public: /** String referencing NULL. This constant is generally only needed for defining a default value for a function parameter: @code 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.