|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-4F5E644B-B2DD-5CD3-B763-E134F1916E62" xml:lang="en"><title>How |
|
13 to use array keys</title><shortdesc>This document describes how to use array keys.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>To access an array by key construct a <codeph>TKeyArrayFix</codeph>, <codeph>TKeyArrayVar</codeph> or <codeph>TKeyArrayPak</codeph> object. |
|
15 The choice depends on the array type used and the member function accessed.</p> |
|
16 <p>The following code fragments show how this is done. They construct and |
|
17 manipulate an array of <codeph>TBankAct</codeph> objects that contain data |
|
18 members representing typical bank account details.</p> |
|
19 <p>The <codeph>TBankAct</codeph> class is defined as:</p> |
|
20 <codeblock id="GUID-CC1F2475-EAF1-5BCC-AAB4-D3A37E3AA253" xml:space="preserve">class TBankAct |
|
21 { |
|
22 public : |
|
23 TBuf<32> iActName; |
|
24 TUint iActNum; |
|
25 TUint iActValue; |
|
26 }</codeblock> |
|
27 <p>The following code builds a <codeph>CArrayFixFlat</codeph> containing three |
|
28 elements of type <codeph>TBankAct</codeph>, as follows:</p> |
|
29 <codeblock id="GUID-4B5F544E-0EF3-570C-A1AC-33F37050B955" xml:space="preserve">CArrayFixFlat<TBankAct> *anArray;</codeblock> |
|
30 <codeblock id="GUID-409208B3-6AEC-59A4-B934-8FF4E6E7BBC6" xml:space="preserve">anArray = new CArrayFixFlat<TBankAct>(3); |
|
31 TBankAct bankact; |
|
32 ... |
|
33 _LIT(KName1,"A.Bloggs"); |
|
34 _LIT(KName2,"F.B.Wittering"); |
|
35 _LIT(KName3,"Z.Makepeace"); |
|
36 ... |
|
37 bankact.iActName = KName1; |
|
38 bankact.iActNum = 3; |
|
39 bankact.iActValue = 300; |
|
40 anArray->AppendL(bankact); |
|
41 ... |
|
42 bankact.iActName = KName2; |
|
43 bankact.iActNum = 1; |
|
44 bankact.iActValue = 6000; |
|
45 anArray->AppendL(bankact); |
|
46 ... |
|
47 bankact.iActName = KName3; |
|
48 bankact.iActNum = 2; |
|
49 bankact.iActValue = 32; |
|
50 anArray->AppendL(bankact); |
|
51 ...</codeblock> |
|
52 <section id="GUID-BFC4A425-65CC-4DC0-B7F8-C2FAAB10714D"><title>Sorting the array</title> <p>To sort the array into account |
|
53 number order, first construct a <codeph>TKeyArrayFix</codeph> object to define |
|
54 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, |
|
55 in which case this statement may not be permitted by the compiler. Two solutions |
|
56 are:</p> <ol id="GUID-21F6AC95-7A84-5B65-8D59-03F96064B53A"> |
|
57 <li id="GUID-8478D06F-A5B4-598D-B022-5D3D1032F082"><p>Make the class in which <codeph>actNumKey</codeph> is |
|
58 declared a friend of <codeph>TBankAct</codeph> </p> </li> |
|
59 <li id="GUID-A733C432-A117-5DD0-9715-E38673428E9E"><p>Declare a public <codeph>const</codeph> <codeph>static</codeph> <codeph>TInt</codeph> data |
|
60 member <codeph>iOffset</codeph> (for example) in the <codeph>TBankAct</codeph> class |
|
61 and include a line of code:</p> </li> |
|
62 </ol> <ul> |
|
63 <li id="GUID-99C1E792-0BD4-5C13-A793-30B8D48E195D"><p><codeph>const TInt TBankAct::iOffset |
|
64 = _FOFF(TBankAct,iActNum);</codeph> </p> </li> |
|
65 </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 |
|
66 an enumerator of the <codeph>TKeyCmpNumeric</codeph> enumeration; this constructor |
|
67 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">... |
|
68 anArray->Sort(actNumKey); |
|
69 ...</codeblock> <p>See also:</p> <ul> |
|
70 <li id="GUID-B6FD456A-0968-5850-8685-5C4CEAC0789C"><p><xref href="GUID-D057148C-4D11-39D1-859C-695D2176CFDE.dita"><apiname>_FOFF</apiname></xref> </p> </li> |
|
71 </ul> </section> |
|
72 <section id="GUID-648B5871-3FFE-42D4-BC64-0DDEEDF851C5"><title>Re-sort the array</title> <p>Re-sort the array into account |
|
73 name order, ignoring the case of the name, and then insert another element |
|
74 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 |
|
75 defines a descriptor key.</p> <p>Now use the key definition to re-sort the |
|
76 array and insert a new element into the correct place:</p> <codeblock id="GUID-871411F9-6EA9-5166-ACB7-138FF677E971" xml:space="preserve">... |
|
77 anArray->Sort(actNameKey); |
|
78 ... |
|
79 _LIT(KNewName,"W.B.NewPerson"); |
|
80 ... |
|
81 bankact.iActName = KNewName; |
|
82 bankact.iActNum = 69; |
|
83 bankact.iActValue = 24; |
|
84 ... |
|
85 anArray->InsertIsqL(bankact,actNameKey); |
|
86 ...</codeblock> <p>Note that the function <codeph>InsertIsqL()</codeph> does |
|
87 not permit duplicates. If there is already an element with the same account |
|
88 name in the array, then the call to the function leaves with<codeph>KErrAlreadyExists</codeph>.</p> <p>Use |
|
89 the key definition to find an array element with a specific name and change |
|
90 the <codeph>iActValue</codeph> data member of that element:</p> <codeblock id="GUID-44814C03-AAC5-5380-9D6E-1B89D5F371C9" xml:space="preserve"> |
|
91 ... |
|
92 _LIT(KFindName,"A.Bloggs"); |
|
93 bankact.iActName = KFindName; |
|
94 ... |
|
95 TInt position; |
|
96 if (anArray->FindIsq(bankact,actNameKey,position)) |
|
97 { |
|
98 // array element NOT found |
|
99 ... |
|
100 } |
|
101 else |
|
102 { |
|
103 (*anArray)[position].iActValue = 40,000,000; |
|
104 ... |
|
105 }</codeblock> <p><b>Notes</b> </p> <ul> |
|
106 <li id="GUID-7BF21EA6-9138-53D9-A4E1-854CBC11D307"><p>Sorting a packed array |
|
107 is achieved using the <codeph>SortL()</codeph> member function.</p> </li> |
|
108 <li id="GUID-FCB18138-3B8E-545E-AA18-99ED50D697C9"><p>Although the example |
|
109 uses an array of fixed length objects and a <codeph>TKeyArrayFix</codeph> object, |
|
110 the same techniques apply to variable length and packed arrays.</p> </li> |
|
111 </ul> </section> |
|
112 </conbody></concept> |