|
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-82074583-C3A3-5168-8225-C60D52F403F0" xml:lang="en"><title>Using |
|
13 RArray<class T></title><shortdesc>This document covers the important issues involved in using an |
|
14 RArray.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <section id="GUID-A36E4483-1962-5672-9665-32CD941222A8"><title>Freeing all |
|
16 memory before the array goes out of scope</title> <p>By convention, class |
|
17 names starting with the letter <codeph>R</codeph> do not allocate memory on |
|
18 the heap. <xref href="GUID-FAEBF321-6B08-3041-A01F-B1E7282D0707.dita"><apiname>RArray</apiname></xref> <codeph><class T></codeph> is an <i>exception</i> and |
|
19 this should be remembered when using the class. </p> <p>If an array is declared |
|
20 on the program stack, then its <codeph>Close()</codeph> or <codeph>Reset()</codeph> member |
|
21 function must be called to ensure that allocated memory is freed. </p> <p>Similarly, |
|
22 if <codeph>RArray<class T></codeph> is a data member of another class, |
|
23 then the destructor of that class must call <codeph>Close()</codeph> or <codeph>Reset()</codeph>. </p> </section> |
|
24 <section id="GUID-B3466F0B-3A94-502D-897D-D83D76CF9EE8"><title>Packaging the |
|
25 algorithm for ordering array objects</title> <p>A <codeph>RArray<class |
|
26 T></codeph> array allows its contained objects to be ordered. The array provides |
|
27 the behaviour for inserting and sorting instances of the template class <codeph>T</codeph>. |
|
28 To help with this, the template class <codeph>T</codeph> must provide an algorithm |
|
29 for deciding how two class <codeph>T</codeph> objects are ordered. This algorithm |
|
30 is implemented by a function which must be wrapped in a <codeph>TLinearOrder<class |
|
31 T></codeph> package. </p> <p>The function implementing the algorithm can be |
|
32 a static member of the class <codeph>T</codeph> but need not necessarily be |
|
33 so. </p> <p>Here, we aim to build an array of <codeph>TMyTest</codeph> objects |
|
34 ordered in a way which makes sense for the <codeph>TMyTest</codeph> class. </p> <codeblock id="GUID-51D0BA13-BA84-5755-8613-D7A94428B8D2" xml:space="preserve">class TMyTest |
|
35 { |
|
36 public : |
|
37 TMyTest(TInt anAint,TInt aBint); |
|
38 static TInt Compare(const TMyTest& aFirst, const TMyTest& Second); |
|
39 public: |
|
40 TInt a; |
|
41 TInt b; |
|
42 };</codeblock> <p>In this example , the algorithm is implemented by a static |
|
43 function called <codeph>Compare()</codeph>. It takes const references to two <codeph>TMyTest</codeph> objects |
|
44 and returns zero if the objects are equal, a negative value if <codeph>aFirst</codeph> is |
|
45 less than <codeph>aSecond</codeph> and a positive value if <codeph>aFirst</codeph> is |
|
46 greater than <codeph>aSecond</codeph>. </p> <codeblock id="GUID-689AED96-53FB-54EE-899F-75C166C37E60" xml:space="preserve">TInt TMyTest::Compare(const TMyTest& aFirst,const TMyTest& aSecond) |
|
47 { |
|
48 if (aFirst.b < aSecond.b) |
|
49 return -1; |
|
50 if (aFirst.b > aSecond.b) |
|
51 return 1; |
|
52 return 0; |
|
53 }</codeblock> <p>Construct three <codeph>TMyTest</codeph> objects and then |
|
54 construct an array object for an array of <codeph>TMyTest</codeph> objects; |
|
55 the array has default granularity. </p> <codeblock id="GUID-67915074-D6FC-5202-A58E-5C0E45A8EA5B" xml:space="preserve">TMyTest one(1,1); |
|
56 TMyTest two(2,2); |
|
57 TMyTest three(3,3); |
|
58 ... |
|
59 RArray<TMyTest> x;</codeblock> <p>There are at least three ways of proceeding, |
|
60 some of which are more efficient than others. </p> <ul> |
|
61 <li id="GUID-DF5A7FF9-C75A-5A65-8236-700E73F5B451"><p>Explicitly build a <codeph>TLinearOrder<TMyTest></codeph> and |
|
62 pass this as a parameter to <codeph>InsertInOrder()</codeph>. </p> </li> |
|
63 </ul> <codeblock id="GUID-C5B7721F-82E3-5097-9BBF-E0005BD9A372" xml:space="preserve">... |
|
64 TLinearOrder<TMyTest> order(TMyTest::Compare); |
|
65 ... |
|
66 x.InsertInOrder(one,order); |
|
67 ...</codeblock> <ul> |
|
68 <li id="GUID-DB2CF898-C7EE-5366-B0EB-85576DB47C85"><p>Construct a temporary <codeph>TLinearOrder<TMyTest></codeph> on |
|
69 the call to <codeph>InsertInOrder()</codeph>. </p> </li> |
|
70 </ul> <codeblock id="GUID-5E7E3500-B821-5F52-AC3D-7DAF82A0C367" xml:space="preserve">... |
|
71 x.InsertInOrder(one,TLinearOrder<TMyTest>(TMyTest::Compare)); |
|
72 ...</codeblock> <ul> |
|
73 <li id="GUID-FC47BB50-FE67-572E-8119-6646312B0ABF"><p>Implicitly construct |
|
74 a temporary <codeph>TLinearOrder<TMyTest></codeph> on the call to <codeph>InsertOrder()</codeph>. </p> </li> |
|
75 </ul> <codeblock id="GUID-0BA2C45D-F02C-5DEF-BC50-3F31883F8913" xml:space="preserve">... |
|
76 x.InsertInOrder(one,TMyTest::Compare); |
|
77 ...</codeblock> <p>This applies to all member functions of <codeph>RArray<class |
|
78 T></codeph> which take a <codeph>TLinearOrder<class T></codeph> argument. </p> </section> |
|
79 <section id="GUID-749DF0B3-7548-55DF-B769-EDFE830B66A6"><title>Packaging the |
|
80 algorithm for matching array objects</title> <p>One of the <codeph>Find()</codeph> member |
|
81 functions of <codeph>RArray<class T></codeph> takes a <codeph>TIdentityRelation<class |
|
82 T></codeph> as an argument. This packages a function which implements |
|
83 an algorithm for deciding whether two class <codeph>T</codeph> objects match. </p> <p>The |
|
84 packaging technique is the same as for the previous section. As an example, |
|
85 we can extend the class <codeph>TMyTest</codeph> used in <xref href="GUID-82074583-C3A3-5168-8225-C60D52F403F0.dita#GUID-82074583-C3A3-5168-8225-C60D52F403F0/GUID-B3466F0B-3A94-502D-897D-D83D76CF9EE8">Packaging the algorithm for ordering array objects</xref> by adding another |
|
86 static function called <codeph>Match()</codeph>. </p> <codeblock id="GUID-ACFE8660-E906-5B84-B5F9-2F319F60B28D" xml:space="preserve">class TMyTest |
|
87 { |
|
88 public : |
|
89 TMyTest(TInt anAint,TInt aBint); |
|
90 static TInt Compare(const TMyTest& aFirst, const TMyTest& Second); |
|
91 static TBool Match(const TMyTest& aFirst, const TMyTest& Second); |
|
92 public: |
|
93 TInt a; |
|
94 TInt b; |
|
95 };</codeblock> <p>A typical implementation for <codeph>Match()</codeph> might |
|
96 be: </p> <codeblock id="GUID-1A664DA1-08B4-55A3-ACA0-17AA9B572546" xml:space="preserve">TBool TMyTest::Match(const TMyTest& aFirst,const TMyTest& aSecond) |
|
97 { |
|
98 if ((aFirst.a == aSecond.a) && (aFirst.b == aSecond.b)) |
|
99 return ETrue; |
|
100 return EFalse; |
|
101 }</codeblock> <p>So, given an array: </p> <codeblock id="GUID-D198D6D0-6F76-5437-9D73-A2A4D2FA9675" xml:space="preserve">RArray<TMyTest> x;RArray<TMyTest> x;</codeblock> <p>populated with a number <codeph>TMyTest</codeph> objects, we can package<codeph>TMyTest</codeph>'s |
|
102 matching function in at least three ways. </p> <ul> |
|
103 <li id="GUID-47125BDD-30B7-549F-BFF8-368F0CE5E9DB"><p>Explicitly build a <codeph>TIdentityRelation<TMyTest></codeph> and |
|
104 pass this as a parameter to <codeph>Find()</codeph>; for example: </p> </li> |
|
105 </ul> <codeblock id="GUID-3AA00C63-32A4-534C-8A75-327DE3550B03" xml:space="preserve">... |
|
106 TIdentityRelation<TMyTest> matcher(TMyTest::Match); |
|
107 ... |
|
108 TMyTest hunter(9,9); |
|
109 TInt index = x.Find(hunter,order); |
|
110 if (index == KErrNotFound) |
|
111 { |
|
112 ... |
|
113 } |
|
114 ...</codeblock> <ul> |
|
115 <li id="GUID-9D164434-FFF7-5113-84C8-69E3E83FEAFB"><p>Construct a temporary <codeph>TIdentityRelation<TMyTest></codeph> on |
|
116 the call to <codeph>Find()</codeph>. </p> </li> |
|
117 </ul> <codeblock id="GUID-B379AF07-031F-5B84-9504-84378B39121D" xml:space="preserve">... |
|
118 TMyTest hunter(9,9); |
|
119 TInt index = x.Find(hunter,TIdentityRelation<TMyTest>(TMyTest::Match)); |
|
120 if (index == KErrNotFound) |
|
121 { |
|
122 ... |
|
123 } |
|
124 ...</codeblock> <ul> |
|
125 <li id="GUID-244AEE08-0F77-5171-9697-A4CCDB00435D"><p>Implicitly construct |
|
126 a temporary <codeph>TIdentityRelation<TMyTest></codeph> on the call to <codeph>Find()</codeph>. </p> </li> |
|
127 </ul> <codeblock id="GUID-FF8525B6-047C-561D-9E5B-C4F81D341389" xml:space="preserve">... |
|
128 TMyTest hunter(9,9); |
|
129 TInt index = x.Find(hunter,TMyTest::Match); |
|
130 if (index == KErrNotFound) |
|
131 { |
|
132 ... |
|
133 } |
|
134 ...</codeblock> </section> |
|
135 </conbody></concept> |