Oracle Coherence for C++ API
Release 3.6.0.0
E15728-01

String Class Reference

#include <coherence/lang/String.hpp>

Detailed Description

A managed C-style (NUL terminated) string.

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):

UTF-8 BMP char array
UTF-16 BMP wchar_t array (on platforms where wchar_t is >= 16 bits)
UTF-8 BMP octet_t array
UTF-16 BMP char16_t array

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";

as is

 void someFunction(String::View vs);

 someFunction("some value");

See also:: StringHandle for details

Author:: mf/jh/djl 2007.07.05

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 (x->compareTo(y) == 0) == (x->equals(y)).

Parameters:

the Object to be compared

Returns:: a negative integer, zero, or a positive integer if this object is less than, equal to, or greater than the specified object

Exceptions:

ClassCastException

if the specified Object's type prevents it from being compared to this Object

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 hashCode is:

Whenever it is invoked on the same Object more than once during an execution of an application, the hashCode method must consistently return the same value, provided no information used in equals comparisons on the object is modified. This value need not remain consistent from one execution of an application to another execution of the same application.
If two Objects are equal according to the equals method, then calling the hashCode method on each of the two Objects must produce the same value.
It is not required that if two Objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct results. However, the programmer should be aware that producing distinct results for unequal objects may improve the performance of hash-based containers.

The default implementation is identity based.

Returns:: a hash code value for this Object

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);

Parameters:

out

the stream used to output the description

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.

Returns:: true iff the Object is immutable

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:

It is reflexive: for any non-null handle h, h->equals(h) must return true.
It is symmetric: for any non-null handles h1 and h2, h1->equals(h2) should return true if and only if h2->equals(h1) returns true.
It is transitive: for any non-null handles h1, h2, and h3, if h1->equals(h2) returns true and h2->equals(h3) returns true, then h1->equals(h3) should return true.
It is consistent: for any non-null handles h1 and h2, multiple invocations of h1->equals(h2) consistently return true or consistently return false, provided no information used in comparisons on the objects is modified.
If the supplied handle is NULL then false must be returned.

The default implementation is a reference equality comparison.

Parameters:

v the Object::View to compare against, may be NULL

Returns:: true iff the given handle references an Object that is "equal" to this Object

See also:: equals(Object::View v1, Object::View v2)

virtual size32_t sizeOf () const

Return an estimate as to the shallow 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.

For classes defined via the class_spec template an auto-generated implementation is provided which utilizes the standard C sizeof() operator to compute the size. User defined implementations are only needed to account for dynamic memory allocated during construction.

Returns:: the approximate shallow byte size of the object

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 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...

Member Typedef Documentation

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.

Member Function Documentation

static String::Handle create	(	const char *	achSrc = `""`,
		size32_t	cch = `npos`
	)			`[static]`

Create a String from a C-style NUL terminated char array.

Parameters:

	ach	the NUL terminated string of chars to copy
	cch	the number of chars to copy; if npos, until NUL

Exceptions:

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.

Parameters:

	ach	the NUL terminated string of wide chars to copy
	cch	the number of chars to copy; if npos, copy until NUL

Exceptions:

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.

Parameters:

the STL string to copy

Exceptions:

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.

Parameters:

	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

Exceptions:

	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.

Parameters:

	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

Exceptions:

	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.

Parameters:

	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

Exceptions:

	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.

Parameters:

	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

Exceptions:

	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

virtual bool isASCII ( ) const [virtual]

Return true iff the String contains only ASCII (ISO-8859-1) characters.

In this case each character is represented by a single char, otherwise a character can take between one and three chars.

Returns:: true iff the String contains only ASCII characters

virtual size32_t length ( ) const [virtual]

Return the number of unicode code points (characters) in this String.

Returns:: the number of characters in this String

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.

Returns:: the char array representing the String.

virtual bool equals	(	const char *	ach,
		size32_t	cch = `npos`
	)			const `[virtual]`

Compare this String against the supplied C-style string.

Parameters:

	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

Returns:: true iff the two strings are identical

virtual bool equals	(	const wchar_t *	ach,
		size32_t	cch = `npos`
	)			const `[virtual]`

Compare this String against the supplied C-style wide char string.

Parameters:

	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

Returns:: true iff the two strings are identical

Exceptions:

UnsupportedOperationException

if sizeof(wchar_t) < sizeof(char16_t)

bool equalsStd ( const std::basic_string< C, R, A > & s ) const [inline]

Compare this String against the supplied STL string or wstring.

Parameters:

the STL string to compare to this String

Returns:: true iff the two strings are identical

o ( ) const [inline]

Convert the String to any of the types supported by StringHandle, namely an STL string or wstring.

Returns:: the std::string/wstring representation

virtual size32_t indexOf	(	String::View	vsSearch,
		size32_t	iBegin = `0`
	)			const `[virtual]`

Return the index of a substring within this String.

Parameters:

	vsSearch	the substring to search for in vsSource
	iBegin	the location in the string to start searching

Returns:: the index of the substring found within this String or npos

virtual size32_t indexOf	(	char16_t	chSearch,
		size32_t	iBegin = `0`
	)			const `[virtual]`

Return the index of a character within this String.

Parameters:

	chSearch	the character to search for in this String
	iBegin	the location in this String to start searching

Returns:: the index of the character found within this String or npos

virtual size32_t lastIndexOf	(	String::View	vsSearch,
		size32_t	iBegin = `npos`
	)			const `[virtual]`

Return the index of a substring within this String by searching backward from the given beginning index.

Parameters:

	vsSearh	the substring to search for within this String
	iBegin	the location in this String to start searching

Returns:: the index of the substring found within this String or npos

virtual size32_t lastIndexOf	(	char16_t	chSearch,
		size32_t	iBegin = `npos`
	)			const `[virtual]`

Return the index of a substring within this String by searching backward from the given beginning index.

Parameters:

	chSearch	the character to search for in this String
	iBegin	the location in this String to start searching

Returns:: the index of the character found within this String or npos

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).

Parameters:

	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

Returns:: the new substring created from this String

virtual bool startsWith ( String::View vsSearch ) const [virtual]

Return true if this String starts with the supplied String.

Parameters:

vsSearch

the string to search for

Returns:: true if this String starts with vsSearch

virtual bool endsWith ( String::View vsSearch ) const [virtual]

Return true if this String ends with the supplied String.

Parameters:

vsSearch

the string to search for

Returns:: true if this String ends with vsSearch

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.

Parameters:

	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

Returns:: the result of the two substrings

String::View trim ( ) const

Return a String that is the result of removing all leading and trailing white space.

Returns:: a trimmed copy of this String

virtual Array<octet_t>::View getOctets ( ) const [virtual]

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>.

Returns:: the 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.

Parameters:

ach

pointer to the start of the next UTF-8 code point.

Returns:: the next Unicode character

Exceptions:

IllegalArgumentException

if a non UTF-8 BMP sequence is encountered

Member Data Documentation

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.

The documentation for this class was generated from the following file:

coherence/lang/String.hpp