How to use array keys

This document describes how to use array keys.

To access an array by key construct a TKeyArrayFix, TKeyArrayVar or TKeyArrayPak object. The choice depends on the array type used and the member function accessed.

The following code fragments show how this is done. They construct and manipulate an array of TBankAct objects that contain data members representing typical bank account details.

The TBankAct class is defined as:

class TBankAct
    {
public :
    TBuf<32> iActName;
    TUint    iActNum;
    TUint    iActValue;
    }

The following code builds a CArrayFixFlat containing three elements of type TBankAct, as follows:

CArrayFixFlat<TBankAct> *anArray;

anArray = new CArrayFixFlat<TBankAct>(3);
TBankAct bankact;
...
_LIT(KName1,"A.Bloggs");
_LIT(KName2,"F.B.Wittering");
_LIT(KName3,"Z.Makepeace");
...
bankact.iActName  = KName1;
bankact.iActNum   = 3;
bankact.iActValue = 300;
anArray->AppendL(bankact);
...
bankact.iActName  = KName2;
bankact.iActNum   = 1;
bankact.iActValue = 6000;
anArray->AppendL(bankact);
...
bankact.iActName  = KName3;
bankact.iActNum   = 2;
bankact.iActValue = 32;
anArray->AppendL(bankact);
...

Sorting the array

To sort the array into account number order, first construct a TKeyArrayFix object to define the location and type of key on which to sort the array:

TKeyArrayFix actNumKey(_FOFF(TBankAct,iActNum),ECmpTUint);

In practice, a data member like iActNum may be private, in which case this statement may not be permitted by the compiler. Two solutions are:

Make the class in which actNumKey is declared a friend of TBankAct
Declare a public const static TInt data member iOffset (for example) in the TBankAct class and include a line of code:

const TInt TBankAct::iOffset = _FOFF(TBankAct,iActNum);

actNumKey can then be constructed:

TKeyArrayFix actNumKey(bankact.iOffset,ECmpTUint);

ECmpTUint is an enumerator of the TKeyCmpNumeric enumeration; this constructor defines a numeric key.

Now use the key definition to do the sort:

...
anArray->Sort(actNumKey);
...

Re-sort the array

Re-sort the array into account name order, ignoring the case of the name, and then insert another element into the array maintaining the same order.

First, construct another TKeyArrayFix object:

TKeyArrayFix actNameKey(_FOFF(TBankAct,iActName),ECmpFolded);

ECmpFolded is an enumerator of the TKeyCmpText enumeration; this constructor defines a descriptor key.

Now use the key definition to re-sort the array and insert a new element into the correct place:

...
anArray->Sort(actNameKey);
...
_LIT(KNewName,"W.B.NewPerson");
...
bankact.iActName  = KNewName;
bankact.iActNum   = 69;
bankact.iActValue = 24;
...
anArray->InsertIsqL(bankact,actNameKey);
...

Note that the function InsertIsqL() does not permit duplicates. If there is already an element with the same account name in the array, then the call to the function leaves withKErrAlreadyExists.

Use the key definition to find an array element with a specific name and change the iActValue data member of that element:

...
_LIT(KFindName,"A.Bloggs");
bankact.iActName = KFindName;
...
TInt position;
if (anArray->FindIsq(bankact,actNameKey,position))
    {
    //  array element NOT found
    ...
    }
else
    {
    (*anArray)[position].iActValue = 40,000,000;
    ...
    }

Notes

Sorting a packed array is achieved using the SortL() member function.
Although the example uses an array of fixed length objects and a TKeyArrayFix object, the same techniques apply to variable length and packed arrays.