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 tranformations 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 asssigned 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) const
 Compare this String against the supplied C-style string.
virtual bool equals (const wchar_t *ach) const
 Compare this String against the supplied C-style wide char string.
virtual bool equalsStd (const std::string &s) const
 Compare this String against the supplied STL string.
virtual bool equalsStd (const std::wstring &ws) const
 Compare this String against the supplied STL 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 Strng.
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 unerlying UTF-8 BMP NUL terminated Array<octet_t>.
virtual operator std::string () const
 Return an STL string containing the same contents as this String.
virtual operator std::wstring () const
 Return an STL wstring containing the same contents as this String.
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 manged 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 overiding this method, as well as making use of MemberHandles to reference child Objects.

A typicial derived implementaiton 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 deap 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 comparision.

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 dymacic memory allocated during construction.

Returns:
the approximate shallow byte size of the object


Static Public Member Functions

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
String::Handle 
NULL_STRING
 String referncing NULL.

Protected Attributes

size32_t m_ccp
 The number of unicode code points (characters) in the String.

Classes

class  StringHandle
 StringHandle provides standard TypedHandle feaures 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

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  )  const [virtual]

Compare this String against the supplied C-style string.

Parameters:
ach the NUL terminated C-style string to compare to this String
Returns:
true iff the two strings are identical

virtual bool equals ( const wchar_t *  ach  )  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
Returns:
true iff the two strings are identical
Exceptions:
UnsupportedOperationException if sizeof(wchar_t) < sizeof(char16_t)

virtual bool equalsStd ( const std::string &  s  )  const [virtual]

Compare this String against the supplied STL string.

Parameters:
s the STL string to compare to this String
Returns:
true iff the two strings are identical

virtual bool equalsStd ( const std::wstring &  ws  )  const [virtual]

Compare this String against the supplied STL wstring.

Parameters:
ws the STL wstring to compare to this String
Returns:
true iff the two strings are identical
Exceptions:
UnsupportedOperationException if sizeof(wchar_t) < sizeof(char16_t)

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

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 unerlying UTF-8 BMP NUL terminated Array<octet_t>.

For performance reasons the returned Array may not support cloneing. 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>

virtual operator std::string (  )  const [virtual]

Return an STL string containing the same contents as this String.

Returns:
a new STL string.

virtual operator std::wstring (  )  const [virtual]

Return an STL wstring containing the same contents as this String.

Returns:
a new STL wstring.
Exceptions:
UnsupportedOperationException if sizeof(wchar_t) < sizeof(char16_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


The documentation for this class was generated from the following file: Copyright (c) 2000-2008 Oracle. All rights reserved.