#include <coherence/lang/Array.hpp>
Inherits Object.
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, wchar16_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.
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 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 TypedHandle < const String > | toString () const | |||
| Output a human-readable description of this Object to the given stream. Note that when overriding this method the return type must be TypedHandle<const String> rather then String::View. These two types are assignment compatible but not equivalent and declaring the override with String::View will not be a compatible override. coherence::lang::operator<<(std::ostream, Object::View) is defined and will call into the toString 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 and is generally how toString() will be implemented.
Object::View vKey = ... Object::View vValue = ... std::cout << vKey << " = " << vValue << std::endl; String::View vs = COH_TO_STRING(vKey << " = " << vValue); The COH_TO_STRING macro is also the most common way to implement the toString method. For example:
virtual TypedHandle<const String> Person::toString() const { return COH_TO_STRING("Name: " << f_sName << " SSN: " << f_nSSN); }
| ||||
| 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 size64_t | sizeOf (bool fDeep=false) 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.
| ||||
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.
| ||||
| 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.
| ||||
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... | ||||
| static Handle create | ( | size32_t | cValue = 0 |
) | [static] |
| ElementType& operator[] | ( | size32_t | i | ) | [inline] |
Return the element stored at the specified index.
| i | the index into the Array |
| IndexOutOfBoundsException | if i is not a valid index |
| const ElementType& operator[] | ( | size32_t | i | ) | const [inline] |
Return the element stored at the specified index.
| i | the index into the Array |
| 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.
| 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) |
| IndexOutOfBoundsException | if ofSource + c or ofOther + c are out of their respective Array's bounds |
| 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.
| iFrom | the starting index (inclusive) | |
| iTo | the ending index (exclusive), or npos |
| 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.
| iFrom | the starting index (inclusive) | |
| iTo | the ending index (exclusive), or npos |
| IndexOutOfBoundsException | if either index is out of the Array's bounds |
| virtual size32_t hashCode | ( | ) | const [virtual] |
| 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.
| v | view to the Array to compare for equality |
Reimplemented from Object.
| virtual bool isImmutable | ( | ) | const [virtual] |
| virtual size64_t sizeOf | ( | bool | fDeep = false |
) | const [virtual] |
| 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.
| 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 |
| 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.
| aValue | the array to hash | |
| c | the number of elements to hash |
size32_t m_nHashCode [mutable, protected] |
MemberHolder<Array<T> > m_ohDelegate [protected] |