<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-4F5E644B-B2DD-5CD3-B763-E134F1916E62" xml:lang="en"><title>How

to use array keys</title><shortdesc>This document describes how to use array keys.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>To access an array by key construct a <codeph>TKeyArrayFix</codeph>, <codeph>TKeyArrayVar</codeph> or <codeph>TKeyArrayPak</codeph> object.

The choice depends on the array type used and the member function accessed.</p>

<p>The following code fragments show how this is done. They construct and

manipulate an array of <codeph>TBankAct</codeph> objects that contain data

members representing typical bank account details.</p>

<p>The <codeph>TBankAct</codeph> class is defined as:</p>

<codeblock id="GUID-CC1F2475-EAF1-5BCC-AAB4-D3A37E3AA253" xml:space="preserve">class TBankAct

    {

public :

    TBuf<32> iActName;

    TUint    iActNum;

    TUint    iActValue;

    }</codeblock>

<p>The following code builds a <codeph>CArrayFixFlat</codeph> containing three

elements of type <codeph>TBankAct</codeph>, as follows:</p>

<codeblock id="GUID-4B5F544E-0EF3-570C-A1AC-33F37050B955" xml:space="preserve">CArrayFixFlat&lt;TBankAct&gt; *anArray;</codeblock>

<codeblock id="GUID-409208B3-6AEC-59A4-B934-8FF4E6E7BBC6" xml:space="preserve">anArray = new CArrayFixFlat&lt;TBankAct&gt;(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);

...</codeblock>

<section id="GUID-BFC4A425-65CC-4DC0-B7F8-C2FAAB10714D"><title>Sorting the array</title> <p>To sort the array into account

number order, first construct a <codeph>TKeyArrayFix</codeph> object to define

the location and type of key on which to sort the array:</p> <codeblock id="GUID-6454BA23-88FF-539E-AA0B-E40FEC4196FC" xml:space="preserve">TKeyArrayFix actNumKey(_FOFF(TBankAct,iActNum),ECmpTUint);</codeblock> <p>In practice, a data member like <codeph>iActNum</codeph> may be private,

in which case this statement may not be permitted by the compiler. Two solutions

are:</p> <ol id="GUID-21F6AC95-7A84-5B65-8D59-03F96064B53A">

<li id="GUID-8478D06F-A5B4-598D-B022-5D3D1032F082"><p>Make the class in which <codeph>actNumKey</codeph> is

declared a friend of <codeph>TBankAct</codeph> </p> </li>

<li id="GUID-A733C432-A117-5DD0-9715-E38673428E9E"><p>Declare a public <codeph>const</codeph>  <codeph>static</codeph> <codeph>TInt</codeph> data

member <codeph>iOffset</codeph> (for example) in the <codeph>TBankAct</codeph> class

and include a line of code:</p> </li>

</ol> <ul>

<li id="GUID-99C1E792-0BD4-5C13-A793-30B8D48E195D"><p><codeph>const TInt TBankAct::iOffset

=           _FOFF(TBankAct,iActNum);</codeph> </p> </li>

</ul> <p><codeph>actNumKey</codeph> can then be constructed:</p> <codeblock id="GUID-CF0B8064-39D5-55B0-B10B-D541096F49AF" xml:space="preserve">TKeyArrayFix actNumKey(bankact.iOffset,ECmpTUint);</codeblock> <p><codeph>ECmpTUint</codeph> is

an enumerator of the <codeph>TKeyCmpNumeric</codeph> enumeration; this constructor

defines a numeric key.</p> <p>Now use the key definition to do the sort:</p> <codeblock id="GUID-16D162F9-BC36-5EE3-998D-377010E3CF1B" xml:space="preserve">...

anArray->Sort(actNumKey);

...</codeblock> <p>See also:</p> <ul>

<li id="GUID-B6FD456A-0968-5850-8685-5C4CEAC0789C"><p><xref href="GUID-D057148C-4D11-39D1-859C-695D2176CFDE.dita"><apiname>_FOFF</apiname></xref> </p> </li>

</ul> </section>

<section id="GUID-648B5871-3FFE-42D4-BC64-0DDEEDF851C5"><title>Re-sort the array</title> <p>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.</p> <p>First, construct another <codeph>TKeyArrayFix</codeph> object:</p> <codeblock id="GUID-56394BA1-68FA-5666-BD2B-134ACE0AAAEC" xml:space="preserve">TKeyArrayFix actNameKey(_FOFF(TBankAct,iActName),ECmpFolded);</codeblock> <p><codeph>ECmpFolded</codeph> is an enumerator of the <codeph>TKeyCmpText</codeph> enumeration; this constructor

defines a descriptor key.</p> <p>Now use the key definition to re-sort the

array and insert a new element into the correct place:</p> <codeblock id="GUID-871411F9-6EA9-5166-ACB7-138FF677E971" xml:space="preserve">...

anArray->Sort(actNameKey);

...

_LIT(KNewName,"W.B.NewPerson");

...

bankact.iActName  = KNewName;

bankact.iActNum   = 69;

bankact.iActValue = 24;

...

anArray->InsertIsqL(bankact,actNameKey);

...</codeblock> <p>Note that the function <codeph>InsertIsqL()</codeph> 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 with<codeph>KErrAlreadyExists</codeph>.</p> <p>Use

the key definition to find an array element with a specific name and change

the <codeph>iActValue</codeph> data member of that element:</p> <codeblock id="GUID-44814C03-AAC5-5380-9D6E-1B89D5F371C9" xml:space="preserve">

...

_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;

    ...

    }</codeblock> <p><b>Notes</b> </p> <ul>

<li id="GUID-7BF21EA6-9138-53D9-A4E1-854CBC11D307"><p>Sorting a packed array

is achieved using the <codeph>SortL()</codeph> member function.</p> </li>

<li id="GUID-FCB18138-3B8E-545E-AA18-99ED50D697C9"><p>Although the example

uses an array of fixed length objects and a <codeph>TKeyArrayFix</codeph> object,

the same techniques apply to variable length and packed arrays.</p> </li>

</ul> </section>