<?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&lt;4&gt; 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-&gt;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-&gt;AppendL(ptr);
...
ptr = new (ELeave) CElement;
...
ptrflat-&gt;InsertL(0,ptr);</codeblock> </section>
</conbody></concept>