Class RArray

RArray<class T>

Support

Supported from 5.0

Description

A simple and efficient array of fixed length objects. The elements of the array are instances of the template class T.

The array offers standard array behaviour which includes insertion, appending and sorting of elements.

Note:

Where possible, this class should be used in preference to CArrayFixFlat<class T>.

Note also that derivation from RArrayBase is private.

Derivation

RArray A simple and efficient array of fixed length objects RArrayBase Base class used in the derivation of RArray

Defined in RArray:
Append(), Array(), Close(), Compress(), Count(), Find(), FindInOrder(), FindInSignedKeyOrder(), FindInUnsignedKeyOrder(), GranularCompress(), Insert(), InsertInOrder(), InsertInOrderAllowRepeats(), InsertInSignedKeyOrder(), InsertInSignedKeyOrderAllowRepeats(), InsertInUnsignedKeyOrder(), InsertInUnsignedKeyOrderAllowRepeats(), RArray(), Remove(), Reset(), Sort(), SortSigned(), SortUnsigned(), operator[]()

RArray();

Description

Default C++ constructor.

This constructs an array object for an array of type class T objects with default granularity and key offset value. The default granularity is 8 and the defaul key offset value is zero.

The size of class T must be positive and must be less than 640 otherwise the constructor raises a USER-129 panic.

RArray(TInt aGranularity);

Description

C++ constructor with granularity.

This constructs an array object for an array of type class T objects with a specified granularity and default key offset value. The default key offset value is zero.

The size of class T must be positive and must be less than 640, otherwise the constructor raises a USER-129 panic.

Parameters

TInt aGranularity The granularity of the array. This value must be positive and the product of this value and the size of class T must be less than 0x10000000, otherwise the constructor raises a USER-127 panic.

RArray(TInt aGranularity, TInt aKeyOffset);

Description

C++ constructor with granularity and key offset.

This constructs an array object for an array of type class T objects with a specified granularity and a specified key offset value.

The size of class T must be positive and must be less than 640, otherwise the constructor raises a USER-129 panic.

Parameters

TInt aGranularity The granularity of the array. This value must be positive and the product of this value and the size of class T must be less than 0x10000000, otherwise the constructor raises a USER-127 panic. TInt aKeyOffset The key offset. This value must be: positive, less than the size of class T, and a multipe of 4. Otherwise the constructor raises a USER-128 panic.

void Close();

Description

Closes the array and frees all memory allocated to the array.

The function must be called before this array object is destroyed.

void Reset();

Description

Empties the array, so that it is ready to be reused.

The function frees all memory allocated to the array and resets the internal state so that it is ready to be reused.

This array object can be allowed to go out of scope after a call to this function.

void Compress();

Description

Compresses the array down to a minimum.

After a call to this function, the memory allocated to the array is just sufficient for its contained objects. Adding a new object to the array always results in a re-allocation of memory.

void GranularCompress();

Description

Compresses the array down to a granular boundary.

After a call to this function, the memory allocated to the array is sufficient for its contained objects. Adding new objects to the array does not result in a re-allocation of memory until the the total number of objects reaches a multiple of the granularity.

TInt Count() const;

Description

Gets the number of objects in the array.

Return value

TInt The number of objects in the array

TInt Insert(const T& anEntry, TInt aPos);

Description

Inserts an object into the array at a specified position.

Parameters

const T& anEntry The class T object to be inserted. TInt aPos The position within the array where the object is to be inserted. The position is relative to zero, i.e. zero implies that an object is inserted at the beginning of the array. This value must not be negative and must not be greater than the number of objects currently in the array, otherwise the function raises a USER-131 panic.

Return value

TInt KErrNone, if the insertion is successful, otherwise one of the system wide error codes.

TInt InsertInOrder(const T& anEntry, TLinearOrder<T> anOrder);

Description

Inserts an object of into the array in object order.

The algorithm for determining the order of two class T type objects is provided by a function supplied by the caller.

No duplicate entries are permitted.

The function assumes that existing objects within the array are in object order.

Parameters

const T& anEntry A reference to the object of type class T to be inserted. TLinearOrder<T> anOrder A package encapsulating the function which determines the order of two class T objects.

Return value

TInt KErrNone, if the insertion is successful, otherwise one of the system wide error codes.

TInt InsertInOrderAllowRepeats(const T& anEntry, TLinearOrder<T> anOrder);

Description

Inserts an object into the array in object order, allowing duplicates.

The algorithm for determining the order of two class T type objects is provided by a function supplied by the caller.

If anEntry is a duplicate of an existing object in the array, then the new object is inserted after the existing object. If more than one duplicate object already exists in the array, then anEntry is inserted after the last one.

The function assumes that existing objects within the array are in object order.

Parameters

const T& anEntry A reference to the object of type class T to be inserted. TLinearOrder<T> anOrder A package encapsulating the function which determines the order of two class T objects.

Return value

TInt KErrNone, if the insertion is successful, otherwise one of the system wide error codes.

TInt InsertInSignedKeyOrder(const T& anEntry);

Description

Inserts an object into the array in ascending signed key order.

The order of two class T type objects is based on comparing a TInt value located at the key offset position within the classT object.

No duplicate entries are permitted.

Parameters

const T& anEntry A reference to the object of type class T to be inserted.

Return value

TInt KErrNone, if the insertion is successful, otherwise one of the system wide error codes.

TInt InsertInSignedKeyOrderAllowRepeats(const T& anEntry);

Description

Inserts an object into the array in ascending signed key order, allowing duplicates.

The order of two class T type objects is based on comparing a TInt value located at the key offset position within the classT object.

If anEntry is a duplicate of an existing object in the array, then the new object is inserted after the existing object. If more than one duplicate object already exists in the array, then any new duplicate object is inserted after the last one.

Parameters

const T& anEntry A reference to the object of type class T to be inserted.

Return value

TInt KErrNone, if the insertion is successful, otherwise one of the system wide error codes.

TInt InsertInUnsignedKeyOrder(const T& anEntry);

Description

Inserts an object into the array in ascending unsigned key order, not alloing duplicate entries.

The order of two class T type objects is based on comparing a TUint value located at the key offset position within the classT object.

Parameters

const T& anEntry A reference to the object of type class T to be inserted.

Return value

TInt KErrNone, if the insertion is successful, otherwise one of the system wide error codes.

TInt InsertInUnsignedKeyOrderAllowRepeats(const T& anEntry);

Description

Inserts an object into the array in ascending unsigned key order, allowing duplicates.

The order of two class T type objects is based on comparing a TUint value located at the key offset position within the classT object.

If anEntry is a duplicate of an existing object in the array, then the new object is inserted after the existing object. If more than one duplicate object already exists in the array, then any new duplicate object is inserted after the last one.

Parameters

const T& anEntry A reference to the object of type class T to be inserted.

Return value

TInt KErrNone, if the insertion is successful, otherwise one of the system wide error codes.

TInt Append(const T& anEntry);

Description

Apends an object onto the array.

Parameters

const T& anEntry A reference to the object of type class T to be appended.

Return value

TInt KErrNone, if the insertion is successful, otherwise one of the system wide error codes.

void Remove(TInt anIndex);

Description

Removes the object at a specified position from the array.

Parameters

TInt anIndex The position within the array from where the object is to be removed. The position is relative to zero, i.e. zero implies that an object at the beginning of the array is to be removed. This value must not be negative and must not be greater than the number of objects currently in the array, otherwise the function raises a USER-130 panic.

TInt Find(const T& anEntry) const;

Description

Finds the first object in the array which matches the specified object using a sequential search.

Matching is based on the comparison of a TInt value at the key offset position within the objects.

The find operation always starts at the low index end of the array. There is no assumption about the order of objects in the array.

Parameters

const T& anEntry A reference to an object of type class T to be used for matching.

Return value

TInt The index of the first matching object within the array.KErrNotFound, if no matching object can be found.

TInt Find(const T& anEntry, TIdentityRelation<T> anIdentity) const;

Description

Finds the first object in the array which matches the specified object using a sequential search and a matching algorithm.

The algorithm for determining whether two class T type objects match is provided by a function supplied by the caller.

The find operation always starts at the low index end of the array. There is no assumption about the order of objects in the array.

Parameters

const T& anEntry A reference to an object of type class T to be used for matching. TIdentityRelation<T> anIdentity A package encapsulating the function which determines whether two classT type objects match.

Return value

TInt The index of the first matching object within the array.KErrNotFound, if no matching object can be found.

TInt FindInOrder(const T& anEntry, TLinearOrder<T> anOrder) const;
TInt FindInOrder(const T& anEntry, TInt& anIndex, TLinearOrder<T> anOrder) const;

Description

Finds the object in the array which matches the specified object using a binary search technique and an ordering algorithm.

The functions assume that existing objects within the array are in object order as determined by an algorithm supplied by the caller and packaged as aTLinearOrder<T>.

Parameters

const T& anEntry A reference to an object of type class T to be used for matching. TInt& anIndex If supplied, a reference to a TInt into which the function puts an index value: If the function returns KErrNone, this is the index of the matching object within the array. If the function returnsKErrNotFound, this is the index of the last object within the array which logically precedes anEntry. TLinearOrder<T> anOrder A package encapsulating the function which determines the order of two class T objects.

Return value

TInt For the two argument function this is either: the index of the matching object within the array or KErrNotFound, if no matching object can be found. For the three argument function this is either:KErrNone, if a matching object is found.KErrNotFound, if no matching object can be found.

TInt FindInSignedKeyOrder(const T& anEntry) const;
TInt FindInSignedKeyOrder(const T& anEntry, TInt& anIndex) const;

Description

Finds the object in the array which matches the specified object using a binary search technique.

The functions assume that existing objects within the array are in signed key order.

Parameters

const T& anEntry A reference to an object of type class T to be used for matching. TInt& anIndex If supplied, a reference to a TInt into which the function puts an index value. If the function returns KErrNone, this is the index of the matching object within the array. If the function returns KErrNotFound, this is the index of the last object within the array which logically precedes anEntry.

Return value

TInt For the single argument function this is either: the index of the matching object within the array, or KErrNotFound if no matching object can be found. For the two argument function this is either: KErrNoneif a matching object is found, or KErrNotFound if no matching object can be found.

TInt FindInUnsignedKeyOrder(const T& anEntry) const;
TInt FindInUnsignedKeyOrder(const T& anEntry, TInt& anIndex) const;

Description

Finds the object in the array which matches the specified object using a binary search technique.

The functions assume that existing objects within the array are in unsigned key order.

Parameters

const T& anEntry A reference to an object of type class T to be used for matching. TInt& anIndex If supplied, a reference to a TInt into which the function puts an index value. If the function returns KErrNone, this is the index of the matching object within the array. If the function returns KErrNotFound, this is the index of the last object within the array which logically precedes anEntry.

Return value

TInt For the single argument function this is either: the index of the matching object within the array, or KErrNotFound if no matching object can be found. For the two argument function this is either: KErrNoneif a matching object is found, orKErrNotFound if no matching object can be found.

void Sort(TLinearOrder<T> anOrder);

Description

Sorts the objects within the array using the specified TLinearOrder.

The sort order is determined by an algorithm supplied by the caller and packaged as aTLinerOrder<T>.

Parameters

TLinearOrder<T> anOrder A package encapsulating the function which determines the order of two class T type objects.

void SortSigned();

Description

Sorts the objects within the array — the sort order is assumed to be in signed integer order.

void SortUnsigned();

Description

Sorts the objects within the array — the sort order is assumed to be in signed integer order.

const T& operator[](TInt anIndex) const;
T& operator[](TInt anIndex);

Description

Gets a reference to an object located at a specified position within the array.

Two versions of the operator are supplied. The compiler chooses the appropriate version based on the use made of the returned reference. If the returned reference is used in an expression where the reference can be modified, then the non-const version is chosen.

Parameters

TInt anIndex The position of the object within the array. The position is relative to zero, i.e. zero implies the object at the beginning of the array. This value must not be negative and must not be greater than the number of objects currently in the array, otherwise the operator raises a USER-130 panic.

Return value

const T& A const reference to the object at position anIndex within the array. T& A non-const reference to the object at positionanIndexwithin the array.

TArray<T> Array() const;

Support

Supported from 6.0

Description

Constructs and returns a generic array.

Return value

TArray<T> A generic array representing this array.

See also:

• TArray