<?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-56EE13F0-CAEE-5E1C-99CD-2FEC8C3BCA6B" xml:lang="en"><title>Dynamic

Arrays Overview</title><shortdesc>This document is an overview of dynamic arrays.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-5562FF9A-483E-4145-B07E-1ABF08B8C103"><title>Purpose</title> <p>Provides families of dynamically expandible

heap-based arrays.</p> </section>

<section id="GUID-E5166C8B-0428-4007-A7FA-A2A7CD84B356"><title>Description</title> <p>A large number of concrete classes

provide dynamic arrays that are suitable for different circumstances. Unlike

standard C++ arrays or the Symbian platform Fixed Size Arrays, the number

of elements in a dynamic array can be altered at run-time.</p> <p>The arrays

are divided into two families:</p> <ul>

<li id="GUID-99FEBCD8-0B2C-5E2A-BCF7-AD8762795E0A"><p>the simple dynamic array

family is for use in most cases</p> </li>

<li id="GUID-107EDF8D-27BB-530D-AF81-74F7B78AB666"><p>the extended dynamic

array family allows advanced properties, such as the organisation of the array

storage in memory, to be specified</p> </li>

</ul> <p>The array classes are all templated. The template parameter defines

the type of object which is to form an array element. </p> <p><b>Simple

dynamic array family</b> </p> <p>The simple dynamic array family offers arrays

of objects, integers, and pointers. The array is always stored in a single

memory area.</p> <p>Object arrays are provided by <xref href="GUID-FAEBF321-6B08-3041-A01F-B1E7282D0707.dita"><apiname>RArray</apiname></xref>.</p> <p>Integer

arrays are provided by <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>.</p> <p>Pointer

arrays are provided by <xref href="GUID-AAA13D1F-1BD7-3331-BB8C-11FA2795B53F.dita"><apiname>RPointerArray</apiname></xref>.</p> <p><b>Extended dynamic array family</b> </p> <p>The extended dynamic array family,

derived from <codeph>CBase</codeph>, allows the client to specify explicitly

combinations of element properties and storage type. These terms are explained

below.</p> <p><b>Element

properties</b> </p> <p>Options for element properties are:</p> <p><b>Fixed length</b> </p> <p>All elements are of the same size (<codeph>CArrayFixBase</codeph>).</p> <p><b>Variable length</b> </p> <p>Elements can be of different sizes (<codeph>CArrayVarBase</codeph>).</p> <p><b>Pointer</b> </p> <p>Elements are pointers to <xref href="GUID-8F6FE089-E2A8-30F4-B67E-10F286347681.dita"><apiname>CBase</apiname></xref> -derived

objects.</p> <p><b>Untyped</b> </p> <p>Elements are <xref href="GUID-6D079976-9119-31FA-8E21-C3B815F94648.dita"><apiname>TAny</apiname></xref> objects.</p> <p><b>Storage type</b> </p> <p>Options for storage type are:</p> <p><b>Flat buffer</b> </p> <p>The elements are stored in a single memory area,

and are of fixed length.</p> <p><b>Segmented</b> </p> <p>The elements are stored in multiple memory areas.</p> <p><b>Packed</b> </p> <p>The elements are stored in a single memory area, but

can be of variable length.</p> <p>Different storage types present trade-offs

between efficiency of memory usage and speed.</p> <p><b>Class summary</b> </p> <p>The following matrix demonstrates the concrete

classes that are available. Storage type is shown horizontally, element properties

vertically.</p> <table id="GUID-3CA8DCBC-6A22-56F0-9462-CA1C51D2F286">

<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>

<thead>

<row>

<entry>Flat</entry>

<entry> Segmented</entry>

<entry> Packed</entry>

</row>

<row>

<entry> Fixed-length element</entry>

</row>

<row>

<entry> Variable-length element</entry>

</row>

<row>

<entry> <xref href="GUID-8F6FE089-E2A8-30F4-B67E-10F286347681.dita"><apiname>CBase</apiname></xref> -pointer elements</entry>

</row>

<row>

<entry> Untyped elements (fixed length)</entry>

</row>

<row>

<entry> Untyped elements (variable length)</entry>

</row>

</thead>

<tbody>

<row>

<entry/>

</row>

<row>

<entry><p><xref href="GUID-12C65B99-553E-35CA-B36F-2F77BFC972B3.dita"><apiname>CArrayFixFlat</apiname></xref> </p> </entry>

<entry><p><xref href="GUID-EE7C55C7-9CB2-3EE8-869C-8283B6723D5C.dita"><apiname>CArrayFixSeg</apiname></xref> </p> </entry>

<entry/>

</row>

<row>

<entry><p><xref href="GUID-5BC7EAFE-FC9C-3E86-BFDC-FDE9FE086D53.dita"><apiname>CArrayVarFlat</apiname></xref> </p> </entry>

<entry><p><xref href="GUID-35439B46-B078-3B9F-9199-CC8F8DD4C1DB.dita"><apiname>CArrayVarSeg</apiname></xref> </p> </entry>

<entry><p><xref href="GUID-4D6E6B46-32B5-34AD-BD8A-84BF6B2B7C81.dita"><apiname>CArrayPakFlat</apiname></xref> </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-FCE7D958-96AA-346D-8D22-0EF24B9DB7CC.dita"><apiname>CArrayPtrFlat</apiname></xref> </p> </entry>

<entry><p><xref href="GUID-A9BDCF9A-6A29-3329-898A-13CA8FF26510.dita"><apiname>CArrayPtrSeg</apiname></xref> </p> </entry>

<entry/>

</row>

<row>

<entry><p><xref href="GUID-E9669326-3E63-3E66-BC99-F6BF08F26BA4.dita"><apiname>CArrayFixFlat&lt;TAny&gt;</apiname></xref> </p> </entry>

<entry><p><xref href="GUID-645011B2-5976-34AF-9B39-D68CD9037224.dita"><apiname>CArrayFixSeg&lt;TAny&gt;</apiname></xref> </p> </entry>

<entry/>

</row>

<row>

<entry><p><xref href="GUID-4FFD4229-66A7-3861-8498-9187555EBA66.dita"><apiname>CArrayVar&lt;TAny&gt;</apiname></xref> </p> </entry>

<entry/>

<entry><p><xref href="GUID-C5F51D78-35D2-3477-897C-A45BB0810D99.dita"><apiname>CArrayPak&lt;TAny&gt;</apiname></xref> </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p>Base classes are not shown on the above table. The inheritance

hierarchies are based on the flat, segmented, packed divisions.</p> </section>