<?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&lt;class T&gt;</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>&lt;class T&gt;</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&lt;class T&gt;</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&lt;class

T&gt;</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&lt;class

T&gt;</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&amp; aFirst,const TMyTest&amp; 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&lt;TMyTest&gt; 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&lt;TMyTest&gt;</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&lt;TMyTest&gt;</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&lt;TMyTest&gt;</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&lt;class

          T&gt;</codeph> which take a <codeph>TLinearOrder&lt;class T&gt;</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&lt;class T&gt;</codeph> takes a <codeph>TIdentityRelation&lt;class

          T&gt;</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&amp; aFirst,const TMyTest&amp; 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&lt;TMyTest&gt; x;RArray&lt;TMyTest&gt; 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&lt;TMyTest&gt;</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&lt;TMyTest&gt;</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&lt;TMyTest&gt;</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>