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

    13 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>

    14 <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

    15 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>,

    16 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>

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

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

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

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

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

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

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

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

    25 for every array access.</p>

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

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

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

    29 length objects.</p>

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

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

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

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

    34 the following characteristics:</p>

    35 <ul>

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

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

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

    39 array are infrequent</p> </li>

    40 </ul>

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

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

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

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

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

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

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

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

    49 that enforces strict alignment.</p>

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

    51 <ul>

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

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

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

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

    56 TInt)</p> </li>

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

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

    59 array.</p> </li>

    60 </ul>

    61 </conbody></concept>