<?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-F50003D0-402A-59E1-8F6F-8C999DC81735" xml:lang="en"><title>When

to choose the RArray and RPointerArray types</title><shortdesc>Describes the occasions to use the RArray and RPointerArray types.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The classes <xref href="GUID-FAEBF321-6B08-3041-A01F-B1E7282D0707.dita"><apiname>RArray</apiname></xref>, <xref href="GUID-AAA13D1F-1BD7-3331-BB8C-11FA2795B53F.dita"><apiname>RPointerArray</apiname></xref> and

the specialisation classes for arrays of 32-bit integers, <xref href="GUID-6FCD6EC2-7293-37A9-8292-3FA05CCEE50B.dita"><apiname>RArray&lt;TInt&gt;</apiname></xref> and <xref href="GUID-97995D22-5A1C-3271-8D63-22D8703B676B.dita"><apiname>RArray&lt;TUint&gt;</apiname></xref>,

provide behaviour equivalent to the <xref href="GUID-12C65B99-553E-35CA-B36F-2F77BFC972B3.dita"><apiname>CArrayFixFlat</apiname></xref> and<xref href="GUID-FCE7D958-96AA-346D-8D22-0EF24B9DB7CC.dita"><apiname>CArrayPtrFlat</apiname></xref> classes.</p>

<p>In general, the implementation of the <codeph>CArray...</codeph> classes

reuses the <xref href="GUID-33BEE1B4-20A1-392B-89B3-DA5D4F46418E.dita"><apiname>CBufBase</apiname></xref> framework to provide two alternative

storage structures for the array data with very little <codeph>CArray...</codeph> specific

code. There are two assertions for every array access, one in the <codeph>CArray...</codeph> code

and one in the <codeph>CBufBase</codeph> code.</p>

<p>In addition, the <codeph>CBufBase</codeph> code operates in terms of byte

buffers, and these appear in the API as descriptors. In the implementation,

this requires a <xref href="GUID-C0D29B11-1535-3D11-B318-B18D30A6120B.dita"><apiname>TPtr8</apiname></xref> to be constructed, returned and inspected

for every array access.</p>

<p>Also, a number of TRAP harnesses are used to catch allocation failure.</p>

<p>This means that, although very powerful, the implementation of the <codeph>CArray...</codeph> classes

can add considerable overhead for simple vector-like flat arrays of fixed

length objects.</p>

<p>The <codeph>RArray...</codeph> classes were developed to overcome these

problems. In addition, the generic searching and ordering capabilities are

faster and easier to use. These classes should be used whenever an array of

fixed length objects or an array of pointers is required, and the array has

the following characteristics:</p>

<ul>

<li id="GUID-5A46A34C-F255-51C8-9777-6BCFA1D1F027"><p>the size of an array

element is bounded (the current implementation imposes an upper limit of 640)</p> </li>

<li id="GUID-04E4B892-AD03-5F72-ACCF-80D4B9874181"><p>insertions into the

array are infrequent</p> </li>

</ul>

<p>In contrast, the main benefit to be derived from the <codeph>CArray...</codeph> classes

is their support for segmented storage and their ability to handle arrays

of variable length objects. However, the latter is a rare requirement.</p>

<p>Note that for performance reasons, <codeph>RArray</codeph> stores objects

in the array as word (4 byte) aligned quantities. This means that some member

functions do not work when <codeph>RArray</codeph> is instantiated for classes

of less than 4 bytes in size, or when the class's alignment requirement is

not 4. Be aware that it is possible to get an unhandled exception on hardware

that enforces strict alignment.</p>

<p>The affected functions are:</p>

<ul>

<li id="GUID-485BFD16-FF55-573B-A831-F706BD9C1B70"><p>the constructor: RArray(TInt,

T*, TInt)</p> </li>

<li id="GUID-65C548C2-D048-5FA4-9990-BFF141962BA5"><p>Append(const T&amp;)</p> </li>

<li id="GUID-C907314E-1884-51D5-98F4-2AD0953DE4C4"><p>Insert(const T&amp;,

TInt)</p> </li>

<li id="GUID-C4C989EF-67EE-5561-B53E-BA76FE91FE80"><p>the [] operator, and

then using the pointer to iterate through the array as you would with a C

array.</p> </li>

</ul>