|
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-B70E22E6-CF28-58A0-9D1E-C9A12D1FBC72" xml:lang="en"><title>Using |
|
13 RPointerArray<class T></title><shortdesc>This document covers the issues involved in using a RPointerArray.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <section id="GUID-F7FD2F4C-A187-5289-B28D-1A7A40A7EF4B"><title>Freeing all |
|
15 memory before the array goes out of scope</title> <p>By convention, class |
|
16 names starting with the letter <codeph>R</codeph> do not allocate memory on |
|
17 the heap. <codeph>RPointerArray<class T></codeph> is an <i>exception</i> and |
|
18 this should be remembered when using the class. </p> <p>If an array is declared |
|
19 on the program stack, then its <codeph>Close()</codeph> or <codeph>Reset()</codeph> member |
|
20 function must be called to ensure that allocated memory is freed. </p> <p>Similarly, |
|
21 if <codeph>RPointerArray<class T></codeph> is a data member of another |
|
22 class, then the destructor of that class must call <codeph>Close()</codeph> or <codeph>Reset()</codeph>. </p> <p>Another |
|
23 issue to remember is the ownership of objects whose pointers are contained |
|
24 within an <codeph>RPointerArray<class T></codeph> array. If ownership of |
|
25 the objects lies elsewhere, then calling <codeph>Close()</codeph> or <codeph>Reset()</codeph> before |
|
26 the array goes out of scope is sufficient. If, however, ownership of these |
|
27 objects is vested in the array, and it is the intention that these objects |
|
28 be destroyed when the array is destroyed, then <codeph>ResetAndDestroy()</codeph> must |
|
29 be called before the array goes out of scope. </p> </section> |
|
30 <section id="GUID-7CBFF894-9704-5018-A062-6EB2DC2D181A"><title>Packaging the |
|
31 algorithm for ordering array objects</title> <p>A <codeph>RPointerArray<class |
|
32 T></codeph> array allows its contained pointers to be ordered so that the |
|
33 objects themselves are in object order. The array provides the behaviour for |
|
34 inserting and sorting instances of pointers to the template class. To help |
|
35 with this, the template class must provide an algorithm for deciding how two |
|
36 template class objects are ordered. This algorithm is implemented by a function |
|
37 which must be wrapped in a <codeph>TLinearOrder<class T></codeph> package. </p> <p>The |
|
38 function implementing the algorithm can be a static member of the class but |
|
39 need not necessarily be so. </p> <p>Here, we aim to build an array of <codeph>CMyTest</codeph> objects |
|
40 ordered in a way which makes sense for the <codeph>CTMyTest</codeph> class. </p> <codeblock id="GUID-46BBDDDA-9AF5-5A1D-80B0-7F9441D1DBF8" xml:space="preserve">class CMyTest |
|
41 { |
|
42 public |
|
43 ~CMyTest(); |
|
44 Static CMytest* NewL(const TDesC& aText); |
|
45 static TInt Compare(const CMyTest& aFirst, const CMyTest& Second); |
|
46 public: |
|
47 HBufC* iText; |
|
48 };</codeblock> <p>In this example, the algorithm is implemented by a static |
|
49 function called <codeph>Compare()</codeph>. It takes const references to two <codeph>CMyTest</codeph> objects |
|
50 and returns zero if the objects are equal, a negative value if <codeph>aFirst</codeph> is |
|
51 less than <codeph>aSecond</codeph> and a positive value if <codeph>aFirst</codeph> is |
|
52 greater than <codeph>aSecond</codeph>. </p> <codeblock id="GUID-FE525095-5A8F-52CB-A56C-6E0148011478" xml:space="preserve">TInt CMyTest::Compare(const CMyTest& aFirst,const CMyTest& aSecond) |
|
53 { |
|
54 TInt ret = (aFirst.iText)->Compare(*aSecond.iText); |
|
55 if (ret > 0) |
|
56 return 1; |
|
57 if (ret < 0) |
|
58 return -1; |
|
59 return 0; |
|
60 }</codeblock> <p>Construct three <codeph>CMyTest</codeph> objects and then |
|
61 construct an array object for an array of pointers to <codeph>CMyTest</codeph> objects; |
|
62 the array has default granularity. </p> <codeblock id="GUID-DA86C3D4-1D9C-5FAD-B418-9EB65DECB045" xml:space="preserve">_LIT(KTextOne,"First Text"); |
|
63 _LIT(KTextTwo,"Second Text"); |
|
64 _LIT(KTextThree,"Third Text"); |
|
65 ... |
|
66 CMyTest* one = CMyTest::NewL(KTextOne); |
|
67 CMyTest* two = CMyTest::NewL(KTextTwo); |
|
68 CMyTest* three = CMyTest::NewL(KTextThree); |
|
69 ... |
|
70 RPointerArray<CMyTest> x;</codeblock> <p>There are at least three ways |
|
71 of proceeding, some of which are more efficient than others. </p> <ul> |
|
72 <li id="GUID-502B71BF-A649-5E1A-90C1-B7822FD61CF8"><p>Explicitly build a <codeph>TLinearOrder<CMyTest></codeph> and |
|
73 pass this as a parameter to <codeph>InsertInOrder()</codeph>. </p> </li> |
|
74 </ul> <codeblock id="GUID-65DCB793-5FE3-59F7-B479-DCEDB2FEC5BC" xml:space="preserve">... |
|
75 TLinearOrder<CMyTest> order(CMyTest::Compare); |
|
76 ... |
|
77 x.InsertInOrder(one,order); |
|
78 ...</codeblock> <ul> |
|
79 <li id="GUID-A9BEE65B-EA73-57C8-8E3A-FCDAF7D7AFD3"><p>Construct a temporary <codeph>TLinearOrder<CMyTest></codeph> on |
|
80 the call to <codeph>InsertInOrder()</codeph>. </p> </li> |
|
81 </ul> <codeblock id="GUID-A61509B0-8473-56BA-B343-3F62A9D54A0B" xml:space="preserve">... |
|
82 x.InsertInOrder(one,TLinearOrder<CMyTest>(CMyTest::Compare)); |
|
83 ...</codeblock> <ul> |
|
84 <li id="GUID-46064641-BA0A-5FE5-93A1-1C2F3981AB1B"><p>Implicitly construct |
|
85 a temporary <codeph>TLinearOrder<CMyTest></codeph> on the call to <codeph>InsertOrder()</codeph>. </p> </li> |
|
86 </ul> <codeblock id="GUID-9B4DA4D7-2DAC-58C6-B958-EDC20ED785B6" xml:space="preserve">... |
|
87 x.InsertInOrder(one,CMyTest::Compare); |
|
88 ...</codeblock> <p>This applies to all member functions of <codeph>RPointerArray<class |
|
89 T></codeph> which take a <codeph>TLinearOrder<class T></codeph> argument. </p> </section> |
|
90 </conbody></concept> |