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

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

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

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

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

    17 provide dynamic arrays that are suitable for different circumstances. Unlike

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

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

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

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

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

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

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

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

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

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

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

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

    30 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

    31 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

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

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

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

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

    36 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

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

    38 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

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

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

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

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

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

    44 <thead>

    45 <row>

    46 <entry>Flat</entry>

    47 <entry> Segmented</entry>

    48 <entry> Packed</entry>

    49 </row>

    50 <row>

    51 <entry> Fixed-length element</entry>

    52 </row>

    53 <row>

    54 <entry> Variable-length element</entry>

    55 </row>

    56 <row>

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

    58 </row>

    59 <row>

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

    61 </row>

    62 <row>

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

    64 </row>

    65 </thead>

    66 <tbody>

    67 <row>

    68 <entry/>

    69 </row>

    70 <row>

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

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

    73 <entry/>

    74 </row>

    75 <row>

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

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

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

    79 </row>

    80 <row>

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

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

    83 <entry/>

    84 </row>

    85 <row>

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

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

    88 <entry/>

    89 </row>

    90 <row>

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

    92 <entry/>

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

    94 </row>

    95 </tbody>

    96 </tgroup>

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

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

    99 

   100 

   101 

   102 

   103 

   104 </conbody></concept>