Class CArrayVar

class CArrayVar : public CArrayVarBase;

Description

A thin templated base class for variable length arrays.

The public functions provide standard array behaviour.

The class is always derived from and is never instantiated explicitly.

Derivation

• CBase - Base class for all classes to be instantiated on the heap.

• CArrayVarBase - An implementation base class for variable length arrays.

• CArrayVar - A thin templated base class for variable length arrays.

Members

Defined in CArrayVar:

• AppendL(const T &,TInt)Appends an element of a specified length onto the array.
• Array()constConstructs and returns a TArray<T> object.
• At(TInt)Gets a reference to the element located at the specified position within the arr...
• At(TInt)constGets a reference to the const element located at the specified position within t...
• ExpandL(TInt,TInt)Expands the array by one element of specified length at the specified position.
• ExtendL(TInt)Expands the array by one element of specified length at the end of the array.
• Find(const T &,TKeyArrayVar &,TInt &)constFinds the position of an element within the array, based on the matching of keys...
• FindIsq(const T &,TKeyArrayVar &,TInt &)constFinds the position of an element within the array, based on the matching of keys...
• InsertIsqAllowDuplicatesL(const T &,TInt,TKeyArrayVar &)Inserts a single element of a specified length into the array at a position dete...
• InsertIsqL(const T &,TInt,TKeyArrayVar &)Inserts a single element of a specified length into the array at a position dete...
• InsertL(TInt,const T &,TInt)Inserts an element of a specified length into the array at the specified positio...
• operator[](TInt)Gets a reference to the element located at the specified position within the arr...
• operator[](TInt)constGets a reference to the const element located at the specified position within t...

Inherited from CArrayVarBase:

• Compress()Removes excess space from the array buffer.
• Count()constGets the number of elements held in the array.
• Delete(TInt)Removes one element from the array.
• Delete(TInt,TInt)Removes one or more contiguous elements from the array, starting at the specifie...
• Length(TInt)constGets the length of a specific element.
• Reset()Deletes all elements from the array and frees the memory allocated to the array ...
• Sort(TKeyArrayVar &)Sorts the elements of the array into key sequence.

Inherited from CBase:

• Delete(CBase *)Deletes the specified object.
• Extension_(TUint,TAny *&,TAny *)Extension function
• operator new(TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TAny *)Initialises the object to binary zeroes.
• operator new(TUint,TLeave)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TLeave,TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TUint)Allocates the object from the heap and then initialises its contents to binary z...

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

Description

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

The compiler uses this variant of the function if the returned reference is used in an expression where it cannot be modified.

Parameters

TInt anIndex The position of the element within the array, relative to zero; i.e. zero implies the first element.

Return value

const T & A const reference to the element located at position anIndex within the array.

Panic codes

E32USER-CBase 21, if anIndex is negative or greater than or equal to the number of objects currently within the array.

inline T& operator[](TInt anIndex);

Description

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

The compiler uses this variant of the function if the returned reference is used in an expression where it can be modified.

Parameters

TInt anIndex The position of the element within the array, relative to zero; i.e. zero implies the first element.

Return value

T & A reference to the non-const element located at position anIndex within the array.

Panic codes

E32USER-CBase 21, if anIndex is negative or greater than or equal to the number of objects currently within the array.

inline const T& At(TInt anIndex) const;

Description

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

The compiler uses this variant of the function if the returned reference is used in an expression where it cannot be modified.

Parameters

TInt anIndex The position of the element within the array, relative to zero; i.e. zero implies the first element.

Return value

const T & A const reference to the element located at position anIndex within the array.

Panic codes

E32USER-CBase 21, if anIndex is negative or greater than or equal to the number of objects currently within the array.

inline T& At(TInt anIndex);

Description

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

The compiler uses this variant of the function if the returned reference is used in an expression where it can be modified.

Parameters

TInt anIndex The position of the element within the array, relative to zero; i.e. zero implies the first element.

Return value

T & A reference to the non-const element located at position anIndex within the array.

Panic codes

E32USER-CBase 21, if anIndex is negative or greater than or equal to the number of objects currently within the array.

inline void AppendL(const T &aRef, TInt aLength);

Description

Appends an element of a specified length onto the array.

Parameters

const T &aRef A reference to the <class T> element to be appended. TInt aLength The length of the element to be appended.

Leave codes

KErrNoMemory The function always attempts to allocate a cell to contain the new element and may also attempt to expand the array buffer. If there is insufficient memory available, the function leaves, in which case, the array is left in the state it was in before the call.

Panic codes

E32USER-CBase 30, if aLength is negative.

inline T& ExpandL(TInt anIndex, TInt aLength);

Description

Expands the array by one element of specified length at the specified position.

It:

1. expands the array by one element position anIndex

2. constructs a new element of specified length at that position

3. returns a reference to the new element.

All existing elements from position anIndex to the end of the array are moved up, so that the element originally at position anIndex is now at position anIndex + 1 etc.

The new element of type <class T> and length aLength is constructed at position anIndex, using the default constructor of that class.

Parameters

TInt anIndex The position within the array where the array is to be expanded and the new <class T> object is to be constructed. TInt aLength The length of the new element.

Return value

T & A reference to the newly constructed <class T> object at position anIndex within the array.

Leave codes

KErrNoMemory The function always attempts to allocate a cell to contain the new element and may also attempt to expand the array buffer. If there is insufficient memory available, the function leaves, in which case, the array is left in the state it was in before the call.

Panic codes

E32USER-CBase 21, if anIndex is negative or is greater than the number of elements currently in the array. E32USER-CBase 30, if aLength is negative.

inline T& ExtendL(TInt aLength);

Description

Expands the array by one element of specified length at the end of the array.

It:

1. expands the array by one element at the end of the array, i.e. at position CArrayVarBase::Count()const

2. constructs a new element of specified length at that position.

3. returns a reference to the new element.

The new element of type <class T> is constructed at the end of the array, using the default constructor of that class.

Parameters

TInt aLength The length of the new element.

Return value

T & A reference to the newly constructed <class T> object at the end of the array.

Leave codes

KErrNoMemory The function always attempts to allocate a cell to contain the new element and may also attempt to expand the array buffer. If there is insufficient memory available, the function leaves, in which case, the array is left in the state it was in before the call.

Panic codes

E32USER-CBase 30, if aLength is negative.

inline TInt Find(const T &aRef, TKeyArrayVar &aKey, TInt &anIndex) const;

Description

Finds the position of an element within the array, based on the matching of keys, using a sequential search.

The array is searched sequentially for an element whose key matches the key of the supplied object. The search starts with the first element in the array.

Note that where an array has elements with duplicate keys, the function only supplies the position of the first element in the array with that key.

Parameters

const T &aRef A reference to an object of type <class T> whose key is used for comparison. TKeyArrayVar &aKey A reference to a key object defining the properties of the key. TInt &anIndex A TInt supplied by the caller. On return, if the element is found, this is set to the position of that element within the array. The position is relative to zero, (i.e. the first element in the array is at position 0). If the element is not found or the array is empty, then this is undefined.

Return value

TInt Zero, if the element with the specified key is found. Non-zero, if the element with the specified key is not found.

inline TInt FindIsq(const T &aRef, TKeyArrayVar &aKey, TInt &anIndex) const;

Description

Finds the position of an element within the array, based on the matching of keys, using a binary search technique.

The array is searched, using a binary search technique, for an element whose key matches the key of the supplied <class T> object.

The array must be in key order.

Note that where an array has elements with duplicate keys, the function cannot guarantee which element, with the given key value, it will return, except that it will find one of them.

Parameters

const T &aRef A reference to an object of type <class T> whose key is used for comparison. TKeyArrayVar &aKey A reference to a key object defining the properties of the key. TInt &anIndex A TInt supplied by the caller. On return, if the element is found, this is set to the position of that element within the array. The position is relative to zero, (i.e. the first element in the array is at position zero). If the element is not found and the array is not empty, then this is set to the position of the first element in the array with a key which is greater than the key of the object aRef. If the element is not found and the array is empty, then this is undefined.

Return value

TInt Zero, if the element with the specified key is found or the array is empty. Non-zero, if the element with the specified key is not found.

inline void InsertL(TInt anIndex, const T &aRef, TInt aLength);

Description

Inserts an element of a specified length into the array at the specified position.

Note that passing a value of anIndex which is the same as the current number of elements in the array, has the effect of appending that element.

Parameters

TInt anIndex The position within the array where the element is to be inserted. The position is relative to zero, i.e. zero implies that elements are inserted at the beginning of the array. const T &aRef A reference to the <class T> object to be inserted into the array. TInt aLength The length of the element to be inserted into the array.

Leave codes

KErrNoMemory The function always attempts to allocate a cell to contain the new element and may also attempt to expand the array buffer. If there is insufficient memory available, the function leaves, in which case, the array is left in the state it was in before the call.

Panic codes

E32USER-CBase 21, if anIndex is negative or is greater than the number of objects currently in the array. E32USER-CBase 30, if aLength is is negative.

inline TInt InsertIsqL(const T &aRef, TInt aLength, TKeyArrayVar &aKey);

Description

Inserts a single element of a specified length into the array at a position determined by a key.

The array MUST already be in key sequence (as defined by the key), otherwise the position of the new element is unpredictable, or duplicates may occur.

Elements with duplicate keys are not permitted.

Parameters

const T &aRef A reference to the element of type <class T> to be inserted into the array. TInt aLength The length of the new element of type <class T> to be inserted into the array. TKeyArrayVar &aKey A reference to a key object defining the properties of the key.

Return value

TInt The position within the array of the newly inserted element.

Leave codes

KErrAlreadyExists An element with the same key already exists within the array. NB the array MUST already be in key sequence, otherwise the function may insert a duplicate and fail to leave with this value. KErrNoMemory The function always attempts to allocate a cell to contain the new element and may also attempt to expand the array buffer. If there is insufficient memory available, the function leaves, in which case, the array is left in the state it was in before the call.

inline TInt InsertIsqAllowDuplicatesL(const T &aRef, TInt aLength, TKeyArrayVar &aKey);

Description

Inserts a single element of a specified length into the array at a position determined by a key, allowing duplicates.

The array MUST already be in key sequence, otherwise the position of the new element is unpredictable.

Elements with duplicate keys are permitted. If the new element's key is a duplicate of an existing element's key, then the new element is positioned after the existing element.

Parameters

const T &aRef A reference to the element of type <class T> to be inserted into the array. TInt aLength The length of the new element to be inserted into the array. TKeyArrayVar &aKey A reference to a key object defining the properties of the key.

Return value

TInt The position within the array of the newly inserted element.

Leave codes

KErrNoMemory The function always attempts to allocate a cell to contain the new element and may also attempt to expand the array buffer. If there is insufficient memory available, the function leaves, in which case, the array is left in the state it was in before the call.

inline const TArray< T > Array() const;

Description

Constructs and returns a TArray<T> object.

Return value

const TArray< T > A TArray<T> object for this array.