Oracle Coherence for C++ API
Release 3.6.1.0

E18813-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 provide 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

ElementType operator[] (size32_t i)
  Return the element stored at the specified index.
const ElementType operator[] (size32_t i) const
  Return the element stored at the specified index.
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 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.

The 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, of 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, 2010, Oracle and/or its affiliates. All rights reserved.