--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-82074583-C3A3-5168-8225-C60D52F403F0.dita Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,135 @@
+<?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>
\ No newline at end of file