Oracle Coherence for C++ API
Release 3.6.0.0

E15728-01

String Class Reference

#include <coherence/lang/String.hpp>

Inherits Comparable.

List of all members.


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

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:
v  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:
s  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:
s  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:
Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.