<?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-5B2D6FE7-A09A-5DB1-A0B6-D1A1397D845F" xml:lang="en"><title>How

to append and insert elements</title><shortdesc>Elements can be added into an array or added to the end by specifying

the insertion position.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>Elements can be added into an array by inserting them into a specified

position.</p>

<p>Adding elements into an array may cause memory to be allocated and this

can fail, causing these functions to leave. User code must always be prepared

to handle this.</p>

<section id="GUID-8C3AADE0-E234-456F-9A3C-FE27B7F3FC8F"><title>Appending an element</title> <p>The following code fragment

appends three <codeph>TElement</codeph> objects to a <codeph>CArrayFixFlat&lt;class T&gt;</codeph> constructed

with a granularity of four, each successive element containing the characters

“X0”, “X1” etc. </p> <codeblock id="GUID-B4357E74-3284-5433-92E7-298E185A8A19" xml:space="preserve">_LIT(KFormatTxt,"X%u");</codeblock> <codeblock id="GUID-77691399-A80A-5BDA-94F3-ECC687D3A233" xml:space="preserve">class TElement

 {

public :

 TElement();

public :

 TBuf<4> iData;

 };</codeblock> <codeblock id="GUID-0ECAFAD0-76F0-598C-93DC-4E62889D1831" xml:space="preserve">CArrayFixFlat&lt;TElement&gt;* fixflat;

fixflat = new (ELeave) CArrayFixFlat&lt;TElement&gt;(3);</codeblock> <codeblock id="GUID-C856566B-0EE5-5B43-880B-2473FD338C84" xml:space="preserve">TElement theElement;</codeblock> <codeblock id="GUID-5E0B0032-EA52-5C3B-AA48-D12F94274D36" xml:space="preserve">for (TInt value = 0; value &lt; 3; value++)

 {

 theElement.iData.Format(KFormatTxt,value);

 fixflat->AppendL(theElement);

 }</codeblock> <p><b>Notes</b> </p> <ul>

<li id="GUID-8A3A6363-9F76-5640-8F99-9B5D2020DE75"><p>Adding the first element

into this array causes an array buffer with a capacity of 3 elements to be

constructed. Attempting to add a 4th element causes the array buffer to be

re-allocated so that it has a capacity of 6 elements.</p> </li>

<li id="GUID-30EC3B13-981F-5F6E-A538-B34F52A8083E"><p>In general, the granularity

should be carefully chosen to minimise the number of calls to the memory allocator

and to avoid wasted space within the array buffer.</p> </li>

</ul> </section>

<section id="GUID-49AC8560-DE23-453F-8608-301937D0E044"><title>Inserting an element</title> <p>The following code fragment

uses <codeph>InsertL()</codeph> to insert a new element into a definite position

in a <codeph>CArrayFixFlat&lt;class T&gt;</codeph> array. For example, to insert

a <codeph>TElement</codeph> object at the <i>beginning</i> of the array (position

zero in the array) :</p> <codeblock id="GUID-791DCCF9-86EC-561B-A470-432782D91002" xml:space="preserve">CArrayFixFlat&lt;TElement&gt;* fixflat;

fixflat = new (ELeave) CArrayFixFlat&lt;TElement&gt;(3);</codeblock> <codeblock id="GUID-F3F8EE8B-030C-50C3-A31A-34194C63A407" xml:space="preserve">TElement theElement;</codeblock> <codeblock id="GUID-2949231C-D96A-54BC-B2D6-FB16EF3CC266" xml:space="preserve">_LIT(KTxtBeg,"BEG");

theElement.iData = KTxtBeg;

fixflat-&gt;InsertL(0,theElement);</codeblock> <p>To insert a new element at

(what is now) position 2 of the array:</p> <codeblock id="GUID-0FFDE613-1044-5251-B09E-DD353B56472C" xml:space="preserve">_LIT(KTxtMid,"MID");

theElement.iData = KTxtMid;

fixflat-&gt;InsertL(2,theElement);</codeblock> <p>To insert a new element at

the back of the array:</p> <codeblock id="GUID-C642EE09-BDF7-55BD-B499-E721FA1E56D8" xml:space="preserve">_LIT(KTxtEnd,"END");

theElement.iData = KTxtEnd;

fixflat-&gt;InsertL(fixflat-&gt;Count(),theElement);</codeblock> <p>Elements can

also be inserted into the array at a position determined by a key (i.e. inserted

in key sequence) using the <codeph>InsertIsqL()</codeph> member function.</p> </section>

<section id="GUID-B7EDDA8C-007F-41F4-994D-8B2A02372054"><title>Adding and inserting a pointer to an array of pointers</title> <p>The

following code fragment uses the <codeph>AppendL()</codeph> and <codeph>InsertL()</codeph> functions

to append and insert a pointer into a <codeph>CArrayPtrFlat</codeph> array.

The pointer being added is a pointer to a <codeph>CBase</codeph> derived objects:</p> <codeblock id="GUID-68264D50-746D-5EC3-90A8-7B89D911794E" xml:space="preserve">CArrayPtrFlat&lt;TElement&gt;* ptrflat;

ptrflat = new (ELeave) CArrayPtrFlat&lt;TElement&gt;(3);</codeblock> <codeblock id="GUID-C150C0F3-F2CD-5B46-A3AF-349BD6515DF3" xml:space="preserve">ptr = new (ELeave) CElement;

...

ptrflat->AppendL(ptr);

...

ptr = new (ELeave) CElement;

...

ptrflat-&gt;InsertL(0,ptr);</codeblock> </section>

</conbody></concept>