»
Symbian OS v6.1 Edition for C++ »
API Reference »
Descriptor Arrays »
CDesC16Array
Location:
badesca.h
Link against: bafl.lib
CDesC16Array
Support
Supported from 5.0
Description
An implementation base class for 16 bit descriptor arrays. It
provides some of the behaviour for 16it descriptor arrays.
The class is abstract and cannot be instantiated.
Derivation
CArrayFixBase | Base class for arrays of fixed length objects |
CBase | Base class for all classes to be instantiated on the heap |
CDesC16Array | An implementation base class for 16 bit descriptor arrays |
MDesC16Array | Interface class for 16 bit descriptor arrays |
|
Defined in CDesC16Array:
AppendL(), Delete(), Find(), FindIsq(), InsertIsqAllowDuplicatesL(), InsertIsqL(), InsertL(), MdcaCount(), MdcaPoint(), Reset(), Sort(), operator[], ~CDesC16Array()
Inherited from CArrayFixBase:
Compress(),
Count(),
Length()
Inherited from CBase:
operator new()
Destruction
~CDesC16Array();
Description
Frees all resources owned by the object, prior to its
destruction. In particular, it deletes all descriptors from the array and frees
the memory allocated to the array buffer.
TInt MdcaCount() const;
Description
Returns the number of descriptor elements in the array. The
function implements the function interface
MDesC16Array::MdcaCount().
Return value
TInt |
The number of descriptor elements. |
|
void Reset();
Description
Deletes all descriptors from the array and frees the memory
allocated to the array buffer.
See also:
void Sort(TKeyCmpText aTextComparisonType=ECmpFolded);
Description
Sorts the descriptor elements into sequence.
The sequence is determined by comparing descriptors using one of the
member functions of the descriptor base class TDesC.
Parameters
TKeyCmpText aTextComparisonType |
An enumeration which defines the type of comparison to be made
between descriptors. By default the comparison type is ECmpFolded.
|
|
void Delete(TInt aPos);
void Delete(TInt aPos,TInt aCount);
Description
Deletes one or more logically contiguous descriptor elements from the
array. The deletion starts at the specified position.
Deleting descriptor elements from the array frees the memory occupied
by the associated heap descriptors and removes their pointers from the array
buffer but does not cause the array buffer to be automatically compressed. Call
the Compress() function to return excess space in the array buffer to the
heap.
Parameters
TInt aPos |
The starting position in the array from which descriptor elements are
to be deleted. The position is relative to zero, i.e. zero implies the first
descriptor element. This value must not be negative and must not be greater
than the number of descriptor elements currently in the array, otherwise the
functions raise an E32USER-CBase 21 panic. |
TInt aCount |
If specified, the number of contiguous descriptor elements to be
deleted from the array. This value must not be negative otherwise the function
raises an E32USER-CBase 22 panic. This value must not be negative otherwise the
function raises an E32USER-CBase 22 panic. This value must not be negative
otherwise the function raises an E32USER-CBase 22 panic. This value plus the
value of the starting position must not be greater than the number of
descriptor elements in the array, otherwise the function raises an
E32USER-CBase 29 panic.
If not specified, one element is assumed. |
|
See also:
void InsertL(TInt aPos,const TDesC16& aPtr);
Description
Inserts a descriptor into the array at the specified position.
If the specified position is the same as the current number of descriptor
elements in the array, this has the effect of appending the element.
Parameters
TInt aPos |
The position within the array where the descriptor element is to be
inserted. The position is relative to zero, i.e. zero implies the first
descriptor element. This value must not be negative and must not be greater
than the number of descriptor elements currently in the array, otherwise the
function raises an E32USER-CBase 21 panic. |
const TDesC16& aPtr |
The descriptor to be inserted into the array. |
|
Leave codes
|
The function may leave with KErrNoMemory if there is
insufficient memory available, or with another 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 TDesC16& aPtr,TKeyCmpText aTextComparisonType=ECmpFolded);
Description
Inserts a descriptor into the array at a position which maintains the
sequence of the descriptors.
The sequence is determined by comparing descriptors using one of
theTDesC comparison functions. The
enumerationaTextComparisonType governs how the descriptors are to
be compared.
The array should already be in sequence, otherwise the position of the
new descriptor element is unpredictable. Descriptor elements which are the same
are not permitted.
Parameters
const TDesC16& aPtr |
A reference to the descriptor to be inserted into the array. |
TKeyCmpText aTextComparisonType |
An enumeration which determines the type of comparison to be made
between descriptors for the purpose of choosing the insertion position. If no
parameter is explicitly passed, ECmpFolded is used by
default. |
|
Return value
TInt |
The position within the array of the inserted descriptor. |
|
Leave codes
|
The function leaves with a KErrAlreadyExists error code if a
descriptor with the same data (i.e. the same length and the same content)
already exists within the array. The function may leave
withKErrNoMemory if there is insufficient memory available. If the
function leaves, the array is left in the state it was in before the
call. |
|
InsertIsqAllowDuplicatesL()
TInt InsertIsqAllowDuplicatesL(const TDesC16& aPtr,TKeyCmpText aTextComparisonType=ECmpFolded);
Description
Inserts a descriptor into the array at a position which maintains the
sequence of the descriptors — allows duplicates.
The sequence is determined by comparing descriptors using one of
theTDesC comparison functions. The
enumerationaTextComparisonType governs how the descriptors are to
be compared.
The array should already be in sequence, otherwise the position of the
new descriptor element is unpredictable. Descriptor elements which are the same
are permitted; if the descriptor aPtr is a duplicate of an
existing descriptor within the array, then the new descriptor element is
positioned after the existing descriptor element.
Parameters
const TDes16& aPtr |
A reference to the descriptor to be inserted into the array. |
TKeyCmpText aTextComparisonType |
An enumeration which determines the type of comparison to be made
between descriptors for the purpose of choosing the insertion position. If no
parameter is explicitly passed, ECmpFolded is used by
default. |
|
Return value
TInt |
The position within the array of the inserted descriptor. |
|
Leave codes
|
The function may leave with KErrNoMemory if there is
insufficient memory available. If the function leaves, the array is left in the
state it was in before the call. |
|
void AppendL(const TDesC16& aPtr);
Description
Appends a descriptor onto the end of any existing descriptor elements in
the array.
Parameters
const TDesC16& aPtr |
A reference to the descriptor to be appended to the array. |
|
Leave codes
|
The function may leave with KErrNoMemory if there is
insufficient memory available. If the function leaves, the array is left in the
state it was in before the call. |
|
TInt Find(const TDesC16& aPtr,TInt& aPos,TKeyCmpText aTextComparisonType=ECmpFolded) const;
Description
Finds the position of a descriptor element within the array which matches
the specified descriptor — using a sequential search.
The array is searched sequentially for a matching descriptor element,
starting with the first descriptor element in the array. Descriptors are
compared using one of the TDesC comparison functions. The
enumeration aTextComparisonType governs how the descriptors are to
be compared.
Where an array has duplicate descriptor elements, the function only
supplies the position of the first descriptor element.
Parameters
const TDesC16& aPtr |
A reference to a descriptor to be used for comparison. |
TInt& aPos |
If the descriptor element is found, this reference is set to the
position of that descriptor element within the array. The position is relative
to zero, (i.e. the first descriptor element in the array is at position 0). If
the descriptor element is not found and the array is not empty, then the value
of the reference is set to the number of descriptor elements in the array. If
the descriptor element is not found and the array is empty, then the reference
is set to zero. |
TKeyCmpText aTextComparisonType=ECmpFolded |
An enumeration which determines the type of comparison to be made
between descriptors. If no parameter is explicitly
passed,ECmpFolded is used by default. |
|
Return value
TInt |
Zero, if a matching descriptor element is found. Non-zero, if no
matching descriptor element can be found. |
|
TInt FindIsq(const TDesC16& aPtr,TInt& aPos,TKeyCmpText aTextComparisonType=ECmpFolded) const;
Description
Finds the position of a descriptor element within the array which matches
the specified descriptor — using a binary search technique. The
array must be in sequence, otherwise the outcome is unpredictable.
Descriptors are compared using one of the TDesC comparison
functions. The enumeration aTextComparisonType governs how the
descriptors are to be compared.
Where an array has duplicate descriptor elements, the function cannot
guarantee which matching descriptor element it will return; except that it will
find one of them.
Parameters
const TDesC16& aPtr |
A reference to a descriptor to be used for comparison. |
TInt& aPos |
If the descriptor element is found, the reference is set to the position
of that descriptor element within the array. The position is relative to zero,
(i.e. the first descriptor element in the array is at position 0). If the
descriptor element is not found and the array is not empty, then the reference
is set to the position of the first descriptor element in the array whose
content is greater than the content of aPtr. If the descriptor
element is not found and the array is empty, then the reference is set to
zero. |
TKeyCmpText aTextComparisonType |
An enumeration which determines the type of comparison to be made
between descriptors. If no parameter is explicitly
passed,ECmpFolded is used by default. |
|
Return value
TInt |
Zero, if a matching descriptor element is found. Non-zero, if no
matching descriptor element can be found. |
|
TPtrC16 MdcaPoint(TInt aIndex) const;
Description
Indexes into a descriptor array. The function implements the
interfaceMDesC16Array::MdcaPoint().
Parameters
TInt aIndex |
The position of the descriptor element within the array. The position is
relative to zero; i.e. zero implies the first descriptor element in the array.
This value must be non-negative and less than the number of descriptors
currently within the array otherwise the operator panics
withEArrayIndexOutOfRange. |
|
Return value
TPtrC16 |
A non-modifiable pointer descriptor representing the descriptor element
located at position aIndex within the array. |
|
TPtrC16 operator[](TInt aIndex);
Description
Returns a non-modifiable descriptor to represent the descriptor element
located at the specified index within the array.
Parameters
TInt aIndex |
The position of the descriptor element within the array. The position is
relative to zero; i.e. zero implies the first descriptor element in the array.
This value must be non-negative and less than the number of descriptors
currently within the array otherwise the operator panics
withEArrayIndexOutOfRange. |
|
Return value
TPtrC16 |
A 16 bit non-modifiable pointer descriptor. |
|
![[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}