RPointerArray< TAny > in Base Kernel_Architecture

class RPointerArray< TAny > : private RPointerArrayBase;

Description

Array of raw pointers.

The array is a simple and efficient specialized array of TAny pointers offering standard array behaviour.

The derivation from RPointerArrayBase is private.

Derivation

RPointerArrayBase - No description.

RPointerArray< TAny > - Array of raw pointers.

Members

Defined in RPointerArray< TAny >:

Append(const TAny *)Appends an pointer onto the array.
AppendL(const TAny *)Appends an pointer onto the array.
Array()constConstructs and returns a generic array.
Close()Closes the array and frees all memory allocated to it.
Compress()Compresses the array down to a minimum.
Count()constGets the number of pointers in the array.
Find(const TAny *)constFinds the first pointer in the array which matches the specified pointer, using ...
FindInAddressOrder(const TAny *)constFinds the pointer in the array that matches the specified object pointer, using ...
FindInAddressOrder(const TAny *,TInt &)constFinds the pointer in the array that matches the specified object pointer, using ...
FindInAddressOrderL(const TAny *)constFinds the pointer in the array that matches the specified pointer, using a binar...
FindInAddressOrderL(const TAny *,TInt &)constFinds the pointer in the array that matches the specified pointer, using a binar...
FindL(const TAny *)constFinds the first pointer in the array which matches the specified pointer, using ...
FindReverse(const TAny *)constFinds the last pointer in the array which matches the specified pointer, using a...
FindReverseL(const TAny *)constFinds the last pointer in the array which matches the specified pointer, using a...
GranularCompress()Compresses the array down to a granular boundary.
Insert(const TAny *,TInt)Inserts an pointer into the array at the specified position.
InsertInAddressOrder(const TAny *)Inserts an pointer into the array in address order.
InsertInAddressOrderAllowRepeats(const TAny *)Inserts an pointer into the array in address order, allowing duplicates.
InsertInAddressOrderAllowRepeatsL(const TAny *)Inserts an pointer into the array in address order, allowing duplicates.
InsertInAddressOrderL(const TAny *)Inserts an pointer into the array in address order.
InsertL(const TAny *,TInt)Inserts an pointer into the array at the specified position.
RPointerArray()Default C++ constructor.
RPointerArray(TAny **,TInt)C++ constructor with a pointer to the first array entry in a pre-existing array,...
RPointerArray(TInt)C++ constructor with granularity.
RPointerArray(TInt,TInt)C++ constructor with minimum growth step and exponential growth factor.
Remove(TInt)Removes the pointer at the specified position from the array.
Reset()Empties the array.
SortIntoAddressOrder()Sorts the pointers within the array into address order.
SpecificFindInAddressOrder(const TAny *,TInt &,TInt)constFinds the pointer in the array that matches the specified pointer, using a binar...
SpecificFindInAddressOrder(const TAny *,TInt)constFinds the pointer in the array that matches the specified pointer, using a binar...
SpecificFindInAddressOrderL(const TAny *,TInt &,TInt)constFinds the pointer in the array that matches the specified pointer, using a binar...
SpecificFindInAddressOrderL(const TAny *,TInt)constFinds the pointer in the array that matches the specified pointer, using a binar...
operator[](TInt)Gets a reference to the pointer located at the specified position within the arr...
operator[](TInt)constGets a reference to the pointer located at the specified position within the arr...

inline RPointerArray();

Description

Default C++ constructor.

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

Return value

inline RPointerArray(TInt aGranularity);

Description

C++ constructor with granularity.

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

Parameters


                                 						TInt aGranularity

The granularity of the array.

Return value

Panic codes

USER

127, if aGranularity is not positive, or greater than or equal to 0x10000000.

inline RPointerArray(TInt aMinGrowBy, TInt aFactor);

Description

C++ constructor with minimum growth step and exponential growth factor.

This constructs an array object for an array of TAny pointers with the specified minimum growth step and exponential growth factor.

Parameters

`TInt aMinGrowBy`	The minimum growth step of the array. Must be between 1 and 65535 inclusive.
`TInt aFactor`	The factor by which the array grows, multiplied by 256. For example 512 specifies a factor of 2. Must be between 257 and 32767 inclusive.

Return value

Panic codes

`USER`	192, if aMinGrowBy<=0 or aMinGrowBy>65535.
`USER`	193, if aFactor<=257 or aFactor>32767.

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

Note that the function does not delete the objects whose pointers are contained in the array.

inline TInt Count() const;

Description

Gets the number of pointers in the array.

Return value


                                 						TInt

The number of pointers in the array.

inline TAny *const& operator[](TInt anIndex) const;

Description

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

The compiler chooses this option if the returned reference is used in an expression where the reference cannot be modified.

Parameters


                                 						TInt anIndex

The position of the pointer within the array. The position is relative to zero, i.e. zero implies the object pointer at the beginning of the array.

Return value


                                 						TAny *const &

A const reference to the pointer at position anIndex within the array.

Panic codes

USER

130, if anIndex is negative, or is greater than the number of objects currently in the array.

inline TAny *& operator[](TInt anIndex);

Description

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

The compiler chooses this option if the returned reference is used in an expression where the reference can be modified.

Parameters


                                 						TInt anIndex

The position of the pointer within the array. The position is relative to zero, i.e. zero implies the object pointer at the beginning of the array.

Return value


                                 						TAny *&

A non-const reference to the pointer at position anIndex within the array.

Panic codes

USER

130, if anIndex is negative, or is greater than the number of objects currently in the array.

inline TInt Append(const TAny *anEntry);

Description

Appends an pointer onto the array.

Parameters

const TAny *anEntry

The pointer to be appended.

Return value


                                 						TInt

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

inline TInt Insert(const TAny *anEntry, TInt aPos);

Description

Inserts an pointer into the array at the specified position.

Parameters

`const TAny *anEntry`	The pointer to be inserted.
`TInt aPos`	The position within the array where the 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.

Return value


                                 						TInt

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

Panic codes

USER

131, if aPos is negative, or is greater than the number of object pointers currently in the array.

inline void Remove(TInt anIndex);

Description

Removes the pointer at the specified position from the array.

Note that the function does not delete the object whose pointer is removed.

Parameters


                                 						TInt anIndex

The position within the array from where the 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.

Panic codes

USER

130, if anIndex is negative, or is greater than the number of objects currently in the array.

inline 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 pointers. Subsequently adding a new pointer to the array always results in a re-allocation of memory.

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

Note that the function does not delete the objects whose pointers are contained in the array.

inline TInt Find(const TAny *anEntry) const;

Description

Finds the first pointer in the array which matches the specified 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 TAny *anEntry

The pointer to be found.

Return value


                                 						TInt

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

inline TInt FindReverse(const TAny *anEntry) const;

Description

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

Matching is based on the comparison of pointers.

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

Parameters

const TAny *anEntry

The pointer to be found.

Return value


                                 						TInt

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

inline TInt FindInAddressOrder(const TAny *anEntry) const;

Description

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

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

Parameters

const TAny *anEntry

The pointer to be found.

Return value


                                 						TInt

The index of the matching pointer within the array or KErrNotFound if no suitable pointer can be found.

inline TInt FindInAddressOrder(const TAny *anEntry, TInt &anIndex) const;

Description

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

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

Parameters

`const TAny *anEntry`	The pointer to be found.
`TInt &anIndex`	A TInt supplied by the caller. On return, contains an index value: If the function returns KErrNone, this is the index of the matching pointer within the array. If the function returns KErrNotFound, this is the index of the last pointer within the array which logically precedes anEntry.

Return value


                                 						TInt

KErrNone, if a matching pointer is found. KErrNotFound, if no suitable pointer can be found.

inline TInt SpecificFindInAddressOrder(const TAny *anEntry, TInt aMode) const;

Description

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

Where there is more than one matching element, it finds the first, the last or any matching element as specified by the value of aMode.

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

Parameters

`const TAny *anEntry`	The pointer to be found.
`TInt aMode`	Specifies whether to find the first match, the last match or any match, as defined by one of the TArrayFindMode enum values.

Return value


                                 						TInt

KErrNotFound, if there is no matching element, otherwise the array index of a matching element - what the index refers to depends on the value of aMode: if this is EArrayFindMode_First, then the index refers to the first matching element; if this is EArrayFindMode_Any, then the index can refer to any of the matching elements; if this is EArrayFindMode_Last, then the index refers to first element that follows the last matching element - if the last matching element is also the last element of the array, then the index value is the same as the total number of elements in the array.

inline TInt SpecificFindInAddressOrder(const TAny *anEntry, TInt &anIndex, TInt aMode) const;

Description

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

Where there is more than one matching element, it finds the first, the last or any matching element as specified by the value of aMode.

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

Parameters

`const TAny *anEntry`	The pointer to be found.
`TInt &anIndex`	A TInt type supplied by the caller. On return, it contains an index value depending on whether a match is found and on the value of aMode. If there is no matching element in the array, then this is the index of the first element in the array that is bigger than the element being searched for - if no elements in the array are bigger, then the index value is the same as the total number of elements in the array. If there is a matching element, then what the index refers to depends on the value of aMode: if this is EArrayFindMode_First, then the index refers to the first matching element; if this is EArrayFindMode_Any, then the index can refer to any of the matching elements; if this is EArrayFindMode_Last, then the index refers to first element that follows the last matching element - if the last matching element is also the last element of the array, then the index value is the same as the total number of elements in the array.
`TInt aMode`	Specifies whether to find the first match, the last match or any match, as defined by one of the TArrayFindMode enum values.

Return value


                                 						TInt

KErrNone, if a matching pointer is found. KErrNotFound, if no suitable pointer can be found.

inline TInt InsertInAddressOrder(const TAny *anEntry);

Description

Inserts an pointer into the array in address order.

No duplicate entries are permitted. The array remains unchanged following an attempt to insert a duplicate entry.

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

Parameters

const TAny *anEntry

The pointer to be inserted.

Return value


                                 						TInt

KErrNone, if the insertion is successful; KErrAlreadyExists, if an attempt is being made to insert a duplicate entry; otherwise one of the other system wide error codes.

inline TInt InsertInAddressOrderAllowRepeats(const TAny *anEntry);

Description

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

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

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

Parameters

const TAny *anEntry

The pointer to be inserted.

Return value


                                 						TInt

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

inline void AppendL(const TAny *anEntry);

Description

Appends an pointer onto the array.

The function leaves with one of the system wide error codes, if the operation fails.

NOTE: This function is NOT AVAILABLE to code running on the kernel side.

Parameters

const TAny *anEntry

The pointer to be appended.

inline void InsertL(const TAny *anEntry, TInt aPos);

Description

Inserts an pointer into the array at the specified position.

The function leaves with one of the system wide error codes, if the operation fails.

NOTE: This function is NOT AVAILABLE to code running on the kernel side.

Parameters

`const TAny *anEntry`	The pointer to be inserted.
`TInt aPos`	The position within the array where the 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.

Panic codes

USER

131, if aPos is negative, or is greater than the number of object pointers currently in the array.

inline TInt FindL(const TAny *anEntry) const;

Description

Finds the first pointer in the array which matches the specified 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.

NOTE: This function is NOT AVAILABLE to code running on the kernel side.

Parameters

const TAny *anEntry

The pointer to be found.

Return value


                                 						TInt

The index of the first matching pointer within the array.

Leave codes

KErrNotFound,

if no matching pointer can be found.

inline TInt FindReverseL(const TAny *anEntry) const;

Description

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

Matching is based on the comparison of pointers.

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

NOTE: This function is NOT AVAILABLE to code running on the kernel side.

Parameters

const TAny *anEntry

The pointer to be found.

Return value


                                 						TInt

The index of the last matching pointer within the array.

Leave codes

KErrNotFound,

if no matching pointer can be found.

inline TInt FindInAddressOrderL(const TAny *anEntry) const;

Description

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

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

NOTE: This function is NOT AVAILABLE to code running on the kernel side.

Parameters

const TAny *anEntry

The pointer to be found.

Return value


                                 						TInt

The index of the matching pointer within the array

Leave codes

KErrNotFound,

if no suitable pointer can be found.

inline void FindInAddressOrderL(const TAny *anEntry, TInt &anIndex) const;

Description

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

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

NOTE: This function is NOT AVAILABLE to code running on the kernel side.

Parameters

`const TAny *anEntry`	The pointer to be found.
`TInt &anIndex`	A reference to a TInt into which the function puts an index value: If the function does not leave, this is the index of the matching pointer within the array. If the function leaves with KErrNotFound, this is the index of the last pointer within the array which logically precedes anEntry.

Leave codes

KErrNotFound,

if no suitable pointer can be found.

inline TInt SpecificFindInAddressOrderL(const TAny *anEntry, TInt aMode) const;

Description

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

Where there is more than one matching element, it finds the first, the last or any matching element as specified by the value of aMode.

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

NOTE: This function is NOT AVAILABLE to code running on the kernel side.

Parameters

`const TAny *anEntry`	The pointer to be found.
`TInt aMode`	Specifies whether to find the first match, the last match or any match, as defined by one of the TArrayFindMode enum values.

Return value


                                 						TInt

If there is a matching element, the array index of a matching element - what the index refers to depends on the value of aMode: if this is EArrayFindMode_First, then the index refers to the first matching element; if this is EArrayFindMode_Any, then the index can refer to any of the matching elements; if this is EArrayFindMode_Last, then the index refers to first element that follows the last matching element - if the last matching element is also the last element of the array, then the index value is the same as the total number of elements in the array.

Leave codes

KErrNotFound

if no matching entry exists.

inline void SpecificFindInAddressOrderL(const TAny *anEntry, TInt &anIndex, TInt aMode) const;

Description

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

Where there is more than one matching element, it finds the first, the last or any matching element as specified by the value of aMode.

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

NOTE: This function is NOT AVAILABLE to code running on the kernel side.

Parameters

`const TAny *anEntry`	The pointer to be found.
`TInt &anIndex`	A TInt type supplied by the caller. On return, it contains an index value depending on whether a match is found and on the value of aMode. If there is no matching element in the array, then this is the index of the first element in the array that is bigger than the element being searched for - if no elements in the array are bigger, then the index value is the same as the total number of elements in the array. If there is a matching element, then what the index refers to depends on the value of aMode: if this is EArrayFindMode_First, then the index refers to the first matching element; if this is EArrayFindMode_Any, then the index can refer to any of the matching elements; if this is EArrayFindMode_Last, then the index refers to first element that follows the last matching element - if the last matching element is also the last element of the array, then the index value is the same as the total number of elements in the array.
`TInt aMode`	Specifies whether to find the first match, the last match or any match, as defined by one of the TArrayFindMode enum values.

Leave codes

KErrNotFound,

if no suitable pointer can be found.

inline void InsertInAddressOrderL(const TAny *anEntry);

Description

Inserts an pointer into the array in address order.

No duplicate entries are permitted. The function assumes that existing pointers within the array are in address order.

The function leaves with one of the system wide error codes, if the operation fails.

NOTE: This function is NOT AVAILABLE to code running on the kernel side.

Parameters

const TAny *anEntry

The pointer to be inserted.

inline void InsertInAddressOrderAllowRepeatsL(const TAny *anEntry);

Description

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

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

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

The function leaves with one of the system wide error codes, if the operation fails.

NOTE: This function is NOT AVAILABLE to code running on the kernel side.

Parameters

const TAny *anEntry

The pointer to be inserted.

inline RPointerArray(TAny **aEntries, TInt aCount);

Description

C++ constructor with a pointer to the first array entry in a pre-existing array, and the number of entries in that array.

This constructor takes a pointer to a pre-existing set of entries of type TAny*, which is owned by another RPointerArray object. Ownership of the set of entries still resides with the original RPointerArray object.

Parameters

`TAny **aEntries`	A pointer to the first entry of type TAny* in the set of entries belonging to the existing array.
`TInt aCount`	The number of entries in the existing array. The granularity of this array is set to this value.

Return value

Panic codes

USER

156, if aCount is not positive.

inline 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 pointers. Adding new 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.

inline void SortIntoAddressOrder();

Description

Sorts the pointers within the array into address order.

inline TArray< TAny * > Array() const;

Description

Constructs and returns a generic array.

Return value


                                 						TArray< TAny * >

A generic array representing this array.

Class RPointerArray< TAny >

Description

Derivation

Members

Member functions

RPointerArray()

Description

Return value

RPointerArray(TInt)

Description

Parameters

Return value

Panic codes

RPointerArray(TInt,TInt)

Description

Parameters

Return value

Panic codes

Close()

Description

Count()const

Description

Return value

operator[](TInt)const

Description

Parameters

Return value

Panic codes

operator[](TInt)

Description

Parameters

Return value

Panic codes

Append(const TAny *)

Description

Parameters

Return value

Insert(const TAny *,TInt)

Description

Parameters

Return value

Panic codes

Remove(TInt)

Description

Parameters

Panic codes

Compress()

Description

Reset()

Description

Find(const TAny *)const

Description

Parameters

Return value

FindReverse(const TAny *)const

Description

Parameters

Return value

FindInAddressOrder(const TAny *)const

Description

Parameters

Return value

FindInAddressOrder(const TAny *,TInt &)const

Description

Parameters

Return value

SpecificFindInAddressOrder(const TAny *,TInt)const

Description

Parameters

Return value

SpecificFindInAddressOrder(const TAny *,TInt &,TInt)const

Description

Parameters

Return value

InsertInAddressOrder(const TAny *)

Description

Parameters

Return value

InsertInAddressOrderAllowRepeats(const TAny *)

Description

Class `RPointerArray< TAny >`

`RPointerArray()`

`RPointerArray(TInt)`

`RPointerArray(TInt,TInt)`

`Close()`

`Count()const`

`operator[](TInt)const`

`operator[](TInt)`

`Append(const TAny *)`

`Insert(const TAny *,TInt)`

`Remove(TInt)`

`Compress()`

`Reset()`

`Find(const TAny *)const`

`FindReverse(const TAny *)const`

`FindInAddressOrder(const TAny *)const`

`FindInAddressOrder(const TAny *,TInt &)const`

`SpecificFindInAddressOrder(const TAny *,TInt)const`

`SpecificFindInAddressOrder(const TAny *,TInt &,TInt)const`

`InsertInAddressOrder(const TAny *)`

`InsertInAddressOrderAllowRepeats(const TAny *)`

`AppendL(const TAny *)`

`InsertL(const TAny *,TInt)`

`FindL(const TAny *)const`

`FindReverseL(const TAny *)const`

`FindInAddressOrderL(const TAny *)const`

`FindInAddressOrderL(const TAny *,TInt &)const`

`SpecificFindInAddressOrderL(const TAny *,TInt)const`

`SpecificFindInAddressOrderL(const TAny *,TInt &,TInt)const`

`InsertInAddressOrderL(const TAny *)`

`InsertInAddressOrderAllowRepeatsL(const TAny *)`

`RPointerArray(TAny **,TInt)`

`GranularCompress()`

`SortIntoAddressOrder()`

`Array()const`