Class RPointerArray

RPointerArray<class T>

Support

Supported from 5.0

Description

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

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

Derivation

RPointerArray A simple and efficient array of pointers to objects RPointerArrayBase Base class used in the derivation of RPointerArray, RArray<TInt> and RArray<TUint>

Defined in RPointerArray:
Append(), Array(), Close(), Compress(), Count(), Find(), FindInAddressOrder(), FindInOrder(), GranularCompress(), Insert(), InsertInAddressOrder(), InsertInAddressOrderAllowRepeats(), InsertInOrder(), InsertInOrderAllowRepeats(), RPointerArray(), Remove(), Reset(), ResetAndDestroy(), Sort(), SortIntoAddressOrder(), operator[]()

Notes:

• Derivation from RPointerArrayBase is private.

RPointerArray();

Description

Default C++ constructor.

This constructs an array object for an array of pointers with default granularity, which is 8.

RPointerArray(TInt aGranularity);

Description

C++ constructor with granularity.

This constructs an array object for an array of pointers with the specified granularity.

Parameters

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

void Close();

Description

Closes the array and frees all memory allocated to it.

The function must be called before this array object goes out of scope.

Notes:

• The function does not delete the objects whose pointers are contained in the array.

void Reset();

Description

Empties the array.

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

Notes:

• The function does not delete the objects whose pointers are contained in the array.

void ResetAndDestroy();

Description

Empties the array and deletes the referenced objects.

It frees all memory allocated to the array and resets the internal state so that it is ready to be reused. The function also deletes all of the objects whose pointers are contained by the array.

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 object pointers. Adding a new object pointer 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 object pointers. Adding new object pointers to the array does not result in a re-allocation of memory until the the total number of pointers reaches a multiple of the granularity.

TInt Count() const;

Description

Gets the number of object pointers in the array.

Return value

TInt The number of object pointers in the array

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

Description

Inserts an object pointer into the array at a specified position.

Parameters

const T* anEntry The object pointer to be inserted. TInt aPos The position within the array where the object pointer is to be inserted. The position is relative to zero, i.e. zero implies that a pointer is inserted at the beginning of the array. This value must not be negative and must not be greater than the number of object pointers 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 InsertInAddressOrder(const T* anEntry);

Description

Inserts an object pointer into the array in address order.

No duplicate entries are permitted.

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

Parameters

const T* anEntry The object pointer to be inserted.

Return value

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

TInt InsertInAddressOrderAllowRepeats(const T* anEntry);

Description

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

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

Parameters

const T* anEntry The object pointer to be inserted

Return value

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

Notes:

• The function assumes that existing object pointers within the array are in address order.

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

Description

Inserts an object pointer into the array so that the object itself is in object order.

The algorithm for determining the order of two classTobjects is provided by a function supplied by the caller.

No duplicate entries are permitted.

Parameters

const T* anEntry The object pointer 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

Notes:

• The function assumes that the array is ordered so that the referenced objects are in object order.

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

Description

Inserts an object pointer into the array so that the object itself is in object order, allowing duplicates

The algorithm for determining the order of two classTobjects is provided by a function supplied by the caller.

If the specified object is a duplicate of an existing object, then the new pointer is inserted after the pointer to the existing object. If more than one duplicate object already exists, then the new pointer is inserted after the pointer to the last one.

Parameters

const T* anEntry The object pointer 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 Append(const T* anEntry);

Description

Appends an object pointer onto the array.

Parameters

const T* anEntry The object pointer 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 pointer at the specified position from the array.

Parameters

TInt anIndex The position within the array from where the object pointer is to be removed. The position is relative to zero, i.e. zero implies that a pointer 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.

Notes:

• The function does not delete the object whose pointer is removed.

TInt Find(const T* anEntry) const;

Description

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

Matching is based on the comparison of pointers.

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 The object pointer to be found.

Return value

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

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

Description

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

The algorithm for determining whether two class T 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 The object pointer to be found. TIdentityRelation<T> anIdentity A package encapsulating the function which determines whether two classT objects match.

Return value

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

TInt FindInAddressOrder(const T* anEntry) const;
TInt FindInAddressOrder(const T* anEntry, TInt& anIndex) const;

Description

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

The functions assume that existing object pointers within the array are in address order.

Parameters

const T* anEntry The object pointer to be found. 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 pointer within the array. If the function returnsKErrNotFound, this is the index of the last object pointer within the array which logically precedes anEntry.

Return value

TInt For the one argument function this is either: the index of the matching object pointer within the array or KErrNotFound, if no suitable object pointer can be found. For the two argument function this is either: KErrNone, if a matching object pointer is found. KErrNotFound, if no suitable object pointer 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 pointer in the array whose object matches the specified object, using a binary search technique and an ordering algorithm.

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

Parameters

const T* anEntry The object pointer to be found. 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 pointer within the array. If the function returnsKErrNotFound, this is the index of the last object pointer 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 pointer within the array or KErrNotFound, if no suitable object pointer can be found. For the three argument function this is either:KErrNone, if a matching object pointer is found.KErrNotFound, if no suitable object pointer can be found.

void Sort(TLinearOrder<T> anOrder);

Description

Sorts the object pointers within the array.

The sort order of the pointers is based on the order of the referenced objects. The referenced object 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 objects.

void SortIntoAddressOrder();

Description

Sorts the object pointers within the array into address order.

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

Description

Indexing operator.

This operator returns reference to the object pointer located at the 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 pointer within the array. The position is relative to zero, i.e. zero implies the object pointer 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 pointer at positionanIndexwithin the array T*& A non-const reference to the object pointer at positionanIndex within 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