Oracle Coherence for C++ API
Release 3.7.1.0

E22845-01

Array Class Template Reference

#include <coherence/lang/Array.hpp>

Inherits Object.

List of all members.


Detailed Description

template<class T>
class coherence::lang::Array< T >

A fixed size collection of values, indexed by integer position.

Array is a wrapper around standard C++ arrays, adding thread-safety and memory management. Array provides a "length" field which can be used to safely determine the last index of the array.

Array's handle type supports direct subscripting:

 for (size32_t i = 0, c = hArr->length; i < c; ++i)
   {
   std::cout << hArr[i] << std::endl;
   }

Only a limited number of element types are supported, including: bool, octect_t, char, wchar_t, char16_t, int8_t, uint8_t, int16_t, uint16_t, int32_t, uint32_t, int64_t, uint64_t, float32_t, and float64_t.

Arrays of Handles and Views to Objects are supported via ObjectArray.

See also:
ObjectArray
Author:
mf 2007.07.05
 

Public Types

typedef spec::Handle Handle
 Array<T> Handle definition.
typedef spec::View View
 Array<T> View definition.
typedef spec::Holder Holder
 Array<T> Holder definition.
typedef
SubscriptHandle
< Array< T >, T > 
Handle
 Handle definition.
typedef
SubscriptHandle
< const Array< T >,
const T > 
View
 View definition.
typedef
SubscriptHolder
< Array< T >, const
T > 
Holder
 Holder definition.
typedef T ElementType
 Element type.

Public Member Functions

ElementTypeoperator[] (size32_t i)
 Return the element stored at the specified index.
const ElementTypeoperator[] (size32_t i) const
 Return the element stored at the specified index.
virtual bool regionMatches (size32_t ofSource, typename Array< T >::View vaOther, size32_t ofOther=0, size32_t c=npos) const
 A region of this Array is compared to a region of a supplied Array.
virtual Handle subArray (size32_t iFrom, size32_t iTo)
 Return an Array over a subset of the elements in this Array.
virtual View subArray (size32_t iFrom, size32_t iTo) const
 Return an Array over a subset of the elements in this Array.
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 size32_t hashCode () const
 Return a hash of all the values in the Array.
virtual bool equals (Object::View v) const
 Test two Arrays for equality.
virtual bool isImmutable () const
 Return true iff the Array and all of its elements are immutable.
virtual size32_t sizeOf () const
 Return the size in bytes of the Array.
virtual Object::Handle clone () const
 Return a handle to a deep copy of the original Object.

The returned clone should be sufficient decoupled from the original such that further modifications to the original Object will not be visible within the cloned object. More specifically, the following is expected to hold true.

 h->clone() != h &&
 h->clone()->equals(h) &&
 typeid(*h) == typeid(*(h->clone()))

Note that this suggests that data members of a cloned object are expected to cloned if they are tested for equality (via a call to equals) within the cloned object's equals method. If a data member is compared via reference equality, or not even considered within equals, then it does not necessarily need to be deeply cloned.

Object is cloneable, but it's derived classes are not automatically cloneable, and CloneNotSupportedExceptions are thrown. To be made cloneable the derived class should use the cloneable_spec<> helper template in its declaration, and define a protected copy constructor. The derived class does not need to override this method, as that is done by the cloneable_spec<> template.

Returns:
a copy of the original Object
Exceptions:
 CloneNotSupportedException if the object cannot be deep cloned
See also:
isImmutable()

Static Public Member Functions

static Handle create (size32_t cValue=0)
 Create a new Array instance.
static Array< T >::Handle copy (typename Array< T >::View vaSrc, size32_t iSrc, typename Array< T >::Handle haDes, size32_t iDes=0, size32_t ce=npos)
 Perform a shallow copy of the elements from one Array to another.
static size32_t hashCode (const T *aValue, size32_t c)
 Compute the hashCode for the supplied raw array.

Public Attributes

const size32_t length
 The number of elements in the Array.
class
coherence::lang::Array::MemberArray 
raw
 The underlying Array of values.

Static Public Attributes

static const size32_t npos
 The largest possible value of type size32_t.

Protected Member Functions

virtual void onConst ()
 Event called when the Object becomes only referenced via const pointers (Views).

Assuming a const-correct class, once this method returns no further visible changes can be made to the object.

As with all event methods any derived implementation should include a call to the super class's implementation.

The default implementation calls the onConst() method of each of the Object's SmartMembers.

See also:
isImmutable
virtual void onEscape (bool fEscaped) const
 Event called when the guarding Object's escape state changes.

As with all event methods any derived implementation should include a call to the super class's implementation. Ultimately delegation must reach Object::onEscape() which will perform the actual act of preparing the object for multi/single-threaded access.

Throughout the call it is guaranteed that the object remains visible to only a single thread, and as such it is not allowable to perform an action from within this method which would attempt to escape this object.

Parameters:
 fEscaped true if the object is escaping, false if it is being captured

Protected Attributes

size32_t m_nHashCode
 The cached hash of all the Array elements.
MemberHolder< Array
< T > > 
m_ohDelegate
 The super Array in the case that this Array was produced by a call to subArray.

Classes

class  MemberArray
 The underlying Array of values. More...

Member Function Documentation

static Handle create ( size32_t  cValue = 0  )  [static]

Create a new Array instance.

Parameters:
 cValue the length of the returned Array

ElementType& operator[] ( size32_t  i  )  [inline]

Return the element stored at the specified index.

Parameters:
 i the index into the Array
Returns:
the element stored at the specified index
Exceptions:
 IndexOutOfBoundsException if i is not a valid index

const ElementType& operator[] ( size32_t  i  )  const [inline]

Return the element stored at the specified index.

Parameters:
 i the index into the Array
Returns:
the element stored at the specified index
Exceptions:
 IndexOutOfBoundsException if i is not a valid index

virtual bool regionMatches ( size32_t  ofSource,
    typename Array< T >::View  vaOther,
    size32_t  ofOther = 0,
    size32_t  c = npos 
  )    const [virtual]

A region of this Array is compared to a region of a supplied Array.

The Array regions are considered equal if each element of the Array region is equal to the corresponding element in the other Array region.

In the case of Arrays of Objects this is a deep equality test, that is each element in the supplied Array must reference an Object which compares equal to the Object referenced from the same element within this Array.

Parameters:
 ofSource the starting index in this Array where the comparison begins
 vaOther view to the Array to compare for equality
 ofOther the starting index in the other Array where the comparison begins
 c the count of elements to compare, or npos for (vaOther->length - ofOther)
Returns:
true iff the two Array regions are identical
Exceptions:
 IndexOutOfBoundsException if ofSource + c or ofOther + c are out of their respective Array's bounds
Since:
Coherence 3.7.1

virtual Handle subArray ( size32_t  iFrom,
    size32_t  iTo 
  )    [virtual]

Return an Array over a subset of the elements in this Array.

The returned Array is backed by this Array, and changes in one will be reflected in the other.

Parameters:
 iFrom the starting index (inclusive)
 iTo the ending index (exclusive), or npos
Returns:
the sub Array
Exceptions:
 IndexOutOfBoundsException if either index is out of the Array's bounds

virtual View subArray ( size32_t  iFrom,
    size32_t  iTo 
  )    const [virtual]

Return an Array over a subset of the elements in this Array.

The returned Array is backed by this Array, and changes in one will be reflected in the other.

Parameters:
 iFrom the starting index (inclusive)
 iTo the ending index (exclusive), or npos
Returns:
the sub Array
Exceptions:
 IndexOutOfBoundsException if either index is out of the Array's bounds

virtual size32_t hashCode (  )  const [virtual]

Return a hash of all the values in the Array.

Returns:
a hash of all the values in the Array

Reimplemented from Object.

virtual bool equals ( Object::View  v  )  const [virtual]

Test two Arrays for equality.

The Arrays are considered equal if they are of the same type and length, and each element of the Array is equal to corresponding element in the other Array.

In the case of Arrays of Objects this is a deep equality test, that is each element in the supplied Array must reference an Object which compares equal to the Object referenced from the same element within this Array.

Parameters:
 v view to the Array to compare for equality
Returns:
true iff the Arrays are identical

Reimplemented from Object.

virtual bool isImmutable (  )  const [virtual]

Return true iff the Array and all of its elements are immutable.

Returns:
true iff the Array and all of its elements are immutable

Reimplemented from Object.

virtual size32_t sizeOf (  )  const [virtual]

Return the size in bytes of the Array.

Returns:
the size in bytes of the Array

Reimplemented from Object.

static Array<T>::Handle copy ( typename Array< T >::View  vaSrc,
    size32_t  iSrc,
    typename Array< T >::Handle  haDes,
    size32_t  iDes = 0,
    size32_t  ce = npos 
  )    [static]

Perform a shallow copy of the elements from one Array to another.

If the source and destination Arrays are the same, it is allowable to have the source and destination ranges overlap, though an intermediate copy may be performed internally.

Parameters:
 vaSrc the source Array
 iSrc the source offset
 haDes the destination Array
 iDes the destination offset
 ce the number of elements to copy; if npos then copy all that is available without stepping out of bounds
Returns:
haDes
Exceptions:
 IndexOutOfBoundsException if either index is out of the Array's bounds, or if haDes is too small

static size32_t hashCode ( const T *  aValue,
    size32_t  c 
  )    [static]

Compute the hashCode for the supplied raw array.

Parameters:
 aValue the array to hash
 c the number of elements to hash


Member Data Documentation

size32_t m_nHashCode [mutable, protected]

The cached hash of all the Array elements.

The hash code is not cached until the Array becomes immutable. A value of zero indicates that a hash has not been cached.

MemberHolder<Array<T> > m_ohDelegate [protected]

The super Array in the case that this Array was produced by a call to subArray.

If non-NULL then this Array does not own the memory associated with raw. This data member is here solely for the purpose of ensuring that the Array which "owns" the raw array is kept alive and potentially mutable.

class coherence::lang::Array::MemberArray raw

The underlying Array of values.

This inner class allows the raw array to inherit the Array Object's constness. Direct usage of this data member is discouraged as it does not provide any bounds checking safety.


The documentation for this class was generated from the following file:
Copyright © 2000, 2011, Oracle and/or its affiliates. All rights reserved.