<?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&lt;32&gt; 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-&gt;AppendL(bankact);
...
bankact.iActName  = KName2;
bankact.iActNum   = 1;
bankact.iActValue = 6000;
anArray-&gt;AppendL(bankact);
...
bankact.iActName  = KName3;
bankact.iActNum   = 2;
bankact.iActValue = 32;
anArray-&gt;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-&gt;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-&gt;Sort(actNameKey);
...
_LIT(KNewName,"W.B.NewPerson");
...
bankact.iActName  = KNewName;
bankact.iActNum   = 69;
bankact.iActValue = 24;
...
anArray-&gt;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-&gt;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>
</conbody></concept>