Week 23 contribution of PDK documentation content. See release notes for details. Fixes bugs Bug 2714, Bug 462.
<?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-82074583-C3A3-5168-8225-C60D52F403F0" xml:lang="en"><title>Using
RArray<class T></title><shortdesc>This document covers the important issues involved in using an
RArray.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-A36E4483-1962-5672-9665-32CD941222A8"><title>Freeing all
memory before the array goes out of scope</title> <p>By convention, class
names starting with the letter <codeph>R</codeph> do not allocate memory on
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
this should be remembered when using the class. </p> <p>If an array is declared
on the program stack, then its <codeph>Close()</codeph> or <codeph>Reset()</codeph> member
function must be called to ensure that allocated memory is freed. </p> <p>Similarly,
if <codeph>RArray<class T></codeph> is a data member of another class,
then the destructor of that class must call <codeph>Close()</codeph> or <codeph>Reset()</codeph>. </p> </section>
<section id="GUID-B3466F0B-3A94-502D-897D-D83D76CF9EE8"><title>Packaging the
algorithm for ordering array objects</title> <p>A <codeph>RArray<class
T></codeph> array allows its contained objects to be ordered. The array provides
the behaviour for inserting and sorting instances of the template class <codeph>T</codeph>.
To help with this, the template class <codeph>T</codeph> must provide an algorithm
for deciding how two class <codeph>T</codeph> objects are ordered. This algorithm
is implemented by a function which must be wrapped in a <codeph>TLinearOrder<class
T></codeph> package. </p> <p>The function implementing the algorithm can be
a static member of the class <codeph>T</codeph> but need not necessarily be
so. </p> <p>Here, we aim to build an array of <codeph>TMyTest</codeph> objects
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
{
public :
TMyTest(TInt anAint,TInt aBint);
static TInt Compare(const TMyTest& aFirst, const TMyTest& Second);
public:
TInt a;
TInt b;
};</codeblock> <p>In this example , the algorithm is implemented by a static
function called <codeph>Compare()</codeph>. It takes const references to two <codeph>TMyTest</codeph> objects
and returns zero if the objects are equal, a negative value if <codeph>aFirst</codeph> is
less than <codeph>aSecond</codeph> and a positive value if <codeph>aFirst</codeph> is
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)
{
if (aFirst.b < aSecond.b)
return -1;
if (aFirst.b > aSecond.b)
return 1;
return 0;
}</codeblock> <p>Construct three <codeph>TMyTest</codeph> objects and then
construct an array object for an array of <codeph>TMyTest</codeph> objects;
the array has default granularity. </p> <codeblock id="GUID-67915074-D6FC-5202-A58E-5C0E45A8EA5B" xml:space="preserve">TMyTest one(1,1);
TMyTest two(2,2);
TMyTest three(3,3);
...
RArray<TMyTest> x;</codeblock> <p>There are at least three ways of proceeding,
some of which are more efficient than others. </p> <ul>
<li id="GUID-DF5A7FF9-C75A-5A65-8236-700E73F5B451"><p>Explicitly build a <codeph>TLinearOrder<TMyTest></codeph> and
pass this as a parameter to <codeph>InsertInOrder()</codeph>. </p> </li>
</ul> <codeblock id="GUID-C5B7721F-82E3-5097-9BBF-E0005BD9A372" xml:space="preserve">...
TLinearOrder<TMyTest> order(TMyTest::Compare);
...
x.InsertInOrder(one,order);
...</codeblock> <ul>
<li id="GUID-DB2CF898-C7EE-5366-B0EB-85576DB47C85"><p>Construct a temporary <codeph>TLinearOrder<TMyTest></codeph> on
the call to <codeph>InsertInOrder()</codeph>. </p> </li>
</ul> <codeblock id="GUID-5E7E3500-B821-5F52-AC3D-7DAF82A0C367" xml:space="preserve">...
x.InsertInOrder(one,TLinearOrder<TMyTest>(TMyTest::Compare));
...</codeblock> <ul>
<li id="GUID-FC47BB50-FE67-572E-8119-6646312B0ABF"><p>Implicitly construct
a temporary <codeph>TLinearOrder<TMyTest></codeph> on the call to <codeph>InsertOrder()</codeph>. </p> </li>
</ul> <codeblock id="GUID-0BA2C45D-F02C-5DEF-BC50-3F31883F8913" xml:space="preserve">...
x.InsertInOrder(one,TMyTest::Compare);
...</codeblock> <p>This applies to all member functions of <codeph>RArray<class
T></codeph> which take a <codeph>TLinearOrder<class T></codeph> argument. </p> </section>
<section id="GUID-749DF0B3-7548-55DF-B769-EDFE830B66A6"><title>Packaging the
algorithm for matching array objects</title> <p>One of the <codeph>Find()</codeph> member
functions of <codeph>RArray<class T></codeph> takes a <codeph>TIdentityRelation<class
T></codeph> as an argument. This packages a function which implements
an algorithm for deciding whether two class <codeph>T</codeph> objects match. </p> <p>The
packaging technique is the same as for the previous section. As an example,
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
static function called <codeph>Match()</codeph>. </p> <codeblock id="GUID-ACFE8660-E906-5B84-B5F9-2F319F60B28D" xml:space="preserve">class TMyTest
{
public :
TMyTest(TInt anAint,TInt aBint);
static TInt Compare(const TMyTest& aFirst, const TMyTest& Second);
static TBool Match(const TMyTest& aFirst, const TMyTest& Second);
public:
TInt a;
TInt b;
};</codeblock> <p>A typical implementation for <codeph>Match()</codeph> might
be: </p> <codeblock id="GUID-1A664DA1-08B4-55A3-ACA0-17AA9B572546" xml:space="preserve">TBool TMyTest::Match(const TMyTest& aFirst,const TMyTest& aSecond)
{
if ((aFirst.a == aSecond.a) && (aFirst.b == aSecond.b))
return ETrue;
return EFalse;
}</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
matching function in at least three ways. </p> <ul>
<li id="GUID-47125BDD-30B7-549F-BFF8-368F0CE5E9DB"><p>Explicitly build a <codeph>TIdentityRelation<TMyTest></codeph> and
pass this as a parameter to <codeph>Find()</codeph>; for example: </p> </li>
</ul> <codeblock id="GUID-3AA00C63-32A4-534C-8A75-327DE3550B03" xml:space="preserve">...
TIdentityRelation<TMyTest> matcher(TMyTest::Match);
...
TMyTest hunter(9,9);
TInt index = x.Find(hunter,order);
if (index == KErrNotFound)
{
...
}
...</codeblock> <ul>
<li id="GUID-9D164434-FFF7-5113-84C8-69E3E83FEAFB"><p>Construct a temporary <codeph>TIdentityRelation<TMyTest></codeph> on
the call to <codeph>Find()</codeph>. </p> </li>
</ul> <codeblock id="GUID-B379AF07-031F-5B84-9504-84378B39121D" xml:space="preserve">...
TMyTest hunter(9,9);
TInt index = x.Find(hunter,TIdentityRelation<TMyTest>(TMyTest::Match));
if (index == KErrNotFound)
{
...
}
...</codeblock> <ul>
<li id="GUID-244AEE08-0F77-5171-9697-A4CCDB00435D"><p>Implicitly construct
a temporary <codeph>TIdentityRelation<TMyTest></codeph> on the call to <codeph>Find()</codeph>. </p> </li>
</ul> <codeblock id="GUID-FF8525B6-047C-561D-9E5B-C4F81D341389" xml:space="preserve">...
TMyTest hunter(9,9);
TInt index = x.Find(hunter,TMyTest::Match);
if (index == KErrNotFound)
{
...
}
...</codeblock> </section>
</conbody></concept>