»
Symbian OS v6.1 Edition for C++ »
API Reference »
Dynamic Arrays »
CArrayVar
Location:
e32base.h
Link against: euser.lib
CArrayVar<class T>
Support
Supported from 5.0
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
CArrayVar | A thin templated base class for variable length arrays |
CArrayVarBase | An implementation base class for variable length arrays |
CBase | Base class for all classes to be instantiated on the heap |
|
Defined in CArrayVar:
AppendL(), Array(), At(), ExpandL(), ExtendL(), Find(), FindIsq(), InsertIsqAllowDuplicatesL(), InsertIsqL(), InsertL(), operator[]
Inherited from CArrayVarBase:
Compress(),
Count(),
Delete(),
Length(),
Reset(),
Sort()
Inherited from CBase:
operator new()
Inserting elements
void InsertL(TInt anIndex,const T& aRef,TInt aLength);
Description
Inserts an element of a specified length into the array at
the specified position.
Notes
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. This value must not be negative and
must not be greater than the number of objects currently in the array,
otherwise the function raises an E32USER-CBase 21 panic. |
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. The
value must not be negative otherwise the function raises an E32USER-CBase 30
panic. |
|
Leave codes
|
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. The leave code is one of
the system wide error codes. If the function leaves, the array is left in the
state it was in before the call. |
|
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 should already be in key sequence, otherwise the
position of the new element is unpredictable.
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
|
The function leaves with a KErrAlreadyExists
error code if an element with the same key already exists within the array. 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. The leave code is one of the system wide error
codes. If the function leaves, the array is left in the state it was in before
the call. |
|
InsertIsqAllowDuplicatesL()
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 should 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
|
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. The leave code is one of
the system wide error codes. If the function leaves, the array is left in the
state it was in before the call. |
|
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. The value must not be
negative otherwise the function raises an E32USER-CBase 30 panic. |
|
Leave codes
|
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. The leave code is one of
the system wide error codes. If the function leaves, the array is left in the
state it was in before the call. |
|
T& ExpandL(TInt anIndex,TInt aLength);
Description
Expands the array by one element of specified length at the specified
position. It:
-
expands the array by one element position
anIndex
-
constructs a new element of specified length at that
position
-
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 that class’s default constructor.
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. This
value must not be negative and must not be greater than the number of elements
currently in the array, otherwise the function raises an E32USER-CBase 21
panic. |
TInt aLength |
The length of the new element. This value must not be negative
otherwise the function raises an E32USER-CBase 30 panic. |
|
Return value
T& |
A reference to the newly constructed
<class T> object at position anIndex
within the array. |
|
Leave codes
|
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. The leave code is one of
the system wide error codes. If the function leaves, the array is left in the
state it was in before the call. |
|
T& ExtendL(TInt aLength);
Description
Expands the array by one element of specified length at the end of the
array. It:
-
expands the array by one element at the end of the array, i.e. at
position CArrayVarBase::Count()
-
constructs a new element of specified length at that
position
-
returns a reference to the new element.
The new element of type <class T> is
constructed at the end of the array, using that class’s default
constructor.
Parameters
TInt aLength |
The length of the new element. This value must not be negative
otherwise the function raises an E32USER-CBase 30 panic. |
|
Return value
T& |
A reference to the newly constructed
<class T> object at the end of the array. |
|
Leave codes
|
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. The leave code is one of
the system wide error codes. If the function leaves, the array is left in the
state it was in before the call. |
|
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.
Notes
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 |
If the element is found, the reference 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 the reference 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. |
|
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.
Notes
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 |
If the element is found, the reference 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 the reference is set to the position of the first
element in the array with a key which is greater than the key of the
objectaRef. If the element is not found and the array is empty,
then the reference 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. |
|
const TArray<T> Array() const;
Description
Constructs and returns a TArray<T> object.
Return value
TArray<T> |
A TArray<T> object for this array. |
|
const T& At(TInt anIndex) const;
T& At(TInt anIndex);
Description
Returns a a reference to the element located at the specified position
within the array.
Two versions of the function 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 that reference can be
modified, then the non-const version is chosen.
Parameters
TInt anIndex |
The position of the element within the array. The position is relative
to zero; i.e. zero implies the first element in the array. This value must be
non-negative and less than the number of objects currently within the array
otherwise the function raise an E32USER-CBase 21 panic. |
|
Return value
T& |
A non-const reference to the element located at
positionanIndex within the array. |
const T& |
A const reference to the element located at positionanIndex
within the array. |
|
const T& operator[](TInt anIndex) const;
T& operator[](TInt anIndex);
Description
Returns a reference to the element 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 referenced. If the
returned reference is used in an expression where the reference is modified,
then the non-const version is chosen by the compiler.
Parameters
TInt anIndex |
The position of the element within the array. The position is relative
to zero; i.e. zero implies the first element in the array. This value must be
non-negative and less than the number of objects currently within the array
otherwise the operation raises an E32USER-CBase 21 panic. |
|
Return value
T& |
A non-const reference to the element located at
positionanIndex within the array. |
const T& |
A const reference to the element located at positionanIndex
within the array. |
|
![[Index]](../../../stock/btn_index.gif){kind=small}
![[Glossary]](../../../stock/btn_glossary.gif){kind=small}
![[Previous]](../../../stock/btn_prev.gif){kind=small}
![[Next]](../../../stock/btn_next.gif){kind=small}
![[Top]](../../../stock/arrow_up_2.gif){kind=icon}
![[Top]](../../../stock/arrow_up.gif){kind=icon}