»
Developer Library »
API Reference »
C++ API reference »
Dynamic Arrays »
CArrayFix
Location:
e32base.h
Link against: euser.lib
CArrayFix<class T>
Support
Supported from 5.0
Description
A thin templated base class for arrays of fixed length objects. The
public functions provide standard array behaviour.
The class is always derived from and is never instantiated
explicitly.
Derivation
CArrayFix | A thin templated base class for arrays of fixed length objects |
CArrayFixBase | Base class for arrays of fixed length objects |
CBase | Base class for all classes to be instantiated on the heap |
|
Defined in CArrayFix:
AppendL(), AppendL()Append, AppendL()Append, Array(), At(), Back(), End(), ExpandL(), ExtendL(), Find(), FindIsq(), InsertIsqAllowDuplicatesL(), InsertIsqL(), InsertL(), InsertL(), InsertL(), ResizeL(), operator[]
Inherited from CArrayFixBase:
Compress(),
Count(),
Delete(),
Length(),
Reset(),
Sort()
Inherited from CBase:
operator new()
Inserting elements
void InsertL(TInt anIndex,const T& aRef);
Description
Inserts an element into the array at the specified
position.
Notes:
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 elements 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 at position anIndex. |
|
Leave codes
|
The function may 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 InsertL(TInt anIndex,const T* aPtr,TInt aCount);
Description
Inserts one or more elements into the array at the specified
position. The objects to be added must all be contiguous.
Notes:
Parameters
TInt anIndex |
The position within the array where the elements are 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 elements currently in the array,
otherwise the function raises an E32USER-CBase 21 panic. |
const T* aPtr |
A pointer to the first of the contiguous elements of type
<class T> to be inserted into the array at position
anIndex. |
TInt aCount |
The number of contiguous elements of type <class
T> located at aPtr to be inserted into the array. The
value must not be negative otherwise the function raises an E32USER-CBase 23
panic. |
|
Leave codes
|
The function may 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 InsertL(TInt anIndex,const T& aRef,TInt aReplicas);
Description
Inserts replicated copies of an element into the array at the
specified position.
Notes:
Parameters
TInt anIndex |
The position within the array where elements are 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 elements 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
replicated and inserted into the array at position anIndex.
|
TInt aReplicas |
The number of copies of the aRef element to be
inserted into the array. This value must not be negative otherwise the function
raises an E32USER-CBase 28 panic. |
|
Leave codes
|
The function may 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,TKeyArrayFix& aKey);
Description
Inserts a single element into the array at a position
determined by a key.
The array should already be in key sequence (as defined by the
key), 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. |
TKeyArrayFix& 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 may 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,TKeyArrayFix& aKey);
Description
Inserts a single element 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.
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. |
TKeyArrayFix& 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 may 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. |
|
Extending/shrinking the array
void ResizeL(TInt aCount);
void ResizeL(TInt aCount, const T& aRef);
Description
Changes the size of the array so that it contains the specified
number of elements.
The following list describes the effects of calling this
function:
-
If aCount is less than the current number of
elements in the array, then the array is shrunk. The elements at positions
aCount and above are discarded. The array buffer is not
compressed.
-
If aCount is greater than the current number
of elements in the array, then the array is extended.
-
If an object of type <class T>
is passed through the reference aRef, then the new elements are
replicated copies of aRef.
-
If the reference aRef is not passed, then the
new elements are replicated copies of an object of type
<class T>, constructed using that class’s
default constructor.
The new elements are positioned after the existing elements in
the array.
Parameters
TInt aCount |
The number of elements the array is to contain after the
resizing operation. The value must not be negative otherwise the functions
raise an E32USER-CBase 24 panic. |
const T& aRef |
If specified, a reference to an object of type
<class T>, copies of which are used as the new
elements of the array, if the array is extended. |
|
Leave codes
|
The function may 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);
Description
Appends a single element onto the end of the array.
Parameters
const T& aRef |
A reference to the <class T> element
to be appended. |
|
Leave codes
|
The function may 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* aPtr,TInt aCount);
Description
Appends one or more elements onto the end of the array.
Parameters
const T* aPtr |
A pointer to a contiguous set of type
<class T> objects to be appended. |
TInt aCount |
The number of contiguous objects of type
<class T> located at aPtr to be
appended. The value must not be negative otherwise the function raises an
E32USER-CBase 23 panic. |
|
Leave codes
|
The function may 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 aReplicas);
Description
Appends replicated copies of an element onto the end of the
array at the specified position.
Parameters
const T& aRef |
A reference to the <class T> object
to be replicated and appended. |
TInt aReplicas |
The number of copies of the aRef element to be
appended. The value must not be negative otherwise the function raises an
E32USER-CBase 28 panic. |
|
Leave codes
|
The function may 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);
Description
Expands the array by one element at the specified position.
It:
-
expands the array by one element at the specified
position
-
constructs a new element 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> 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. |
|
Return value
T& |
A reference to the newly constructed
<class T> object at position anIndex
within the array. |
|
Leave codes
|
The function may 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();
Description
Expands the array by one element at the end of the array.
It:
-
expands the array by one element at the end of the array,
i.e. at position CArrayFixBase::Count()
-
constructs a new element 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.
Return value
T& |
A reference to the newly constructed
<class T> object at the end of the array. |
|
Leave codes
|
The function may 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,TKeyArrayFix& 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 <class T> object.
The search starts with the first element in the array.
Notes:
Parameters
const T& aPtr |
A reference to an object of type
<class T> whose key is used for comparison. |
TKeyArrayFix& 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 and
the array is not empty, then the value of the reference is set to the number of
elements in the array. If the element is not found and the array is empty, then
the reference is set to zero. |
|
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,TKeyArrayFix& 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. |
TKeyArrayFix& 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 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 object
aRef. If the element is not found and the array is empty, then the
reference is set to zero. |
|
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. |
|
const TArray<T> Array() const;
Description
Constructs and returns a TArray<T>
object.
Return value
TArray<T>
|
A TArray<T> object representing 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.
Notes:
-
If a pointer to the returned referenced
<class T> object is taken, be aware that the pointer
value becomes invalid once elements have been added to, or removed from the
array. Always refresh the pointer.
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 functions raise an E32USER-CBase 21 panic. |
|
Return value
T& |
A non-const reference to the element located at position
anIndex within the array. |
const T& |
A const reference to the element located at position
anIndex 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 reference. If the
returned reference is used in an expression where the reference can be
modified, then the non-const version is chosen.
Notes:
-
If a pointer to the returned referenced
<class T> object is taken, be aware that the pointer
value becomes invalid once elements have been added to, or removed from the
array. Always refresh the pointer.
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 operators raise an E32USER-CBase 21 panic. |
|
Return value
T& |
A non-const reference to the element located at position
anIndex within the array. |
const T& |
A const reference to the element located at position
anIndex within the array. |
|
const T* End(TInt anIndex) const;
T* End(TInt anIndex);
Description
Returns a pointer to the first byte following the end of the
contiguous region containing the element at the specified position within the
array.
For arrays implemented using flat buffers, the pointer always
points to the first byte following the end of the buffer.
For arrays implemented using segmented buffers, the pointer
always points to the first byte following the end of the segment which contains
the element.
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 operators raise an E32USER-CBase 21 panic. |
|
Return value
T* |
A non-const pointer to the byte following the end of the
contiguous region. |
const T* |
A const pointer to the byte following the end of the contiguous
region. |
|
const T* Back(TInt anIndex) const;
T* Back(TInt anIndex);
Description
Returns a pointer to the beginning of a contiguous
region.
For arrays implemented using flat buffers, the function always
returns a pointer to the beginning of the buffer.
For arrays implemented using segmented buffers, the function
returns a pointer to the beginning of the segment for all elements in that
segment except the first. If the element at position anIndex is
the first in a segment, then the function returns a pointer the beginning of
the previous segment.
For the first element in the array, the function returns a NULL
pointer.
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 operators raise an E32USER-CBase 21 panic. |
|
Return value
T* |
A non-const pointer to the beginning of the contiguous
region. |
const T* |
A const pointer to the beginning ofd the contiguous
region. |
|
![[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}