|
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-5B2D6FE7-A09A-5DB1-A0B6-D1A1397D845F" xml:lang="en"><title>How |
|
13 to append and insert elements</title><shortdesc>Elements can be added into an array or added to the end by specifying |
|
14 the insertion position.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <p>Elements can be added into an array by inserting them into a specified |
|
16 position.</p> |
|
17 <p>Adding elements into an array may cause memory to be allocated and this |
|
18 can fail, causing these functions to leave. User code must always be prepared |
|
19 to handle this.</p> |
|
20 <section id="GUID-8C3AADE0-E234-456F-9A3C-FE27B7F3FC8F"><title>Appending an element</title> <p>The following code fragment |
|
21 appends three <codeph>TElement</codeph> objects to a <codeph>CArrayFixFlat<class T></codeph> constructed |
|
22 with a granularity of four, each successive element containing the characters |
|
23 “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 |
|
24 { |
|
25 public : |
|
26 TElement(); |
|
27 public : |
|
28 TBuf<4> iData; |
|
29 };</codeblock> <codeblock id="GUID-0ECAFAD0-76F0-598C-93DC-4E62889D1831" xml:space="preserve">CArrayFixFlat<TElement>* fixflat; |
|
30 fixflat = new (ELeave) CArrayFixFlat<TElement>(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 < 3; value++) |
|
31 { |
|
32 theElement.iData.Format(KFormatTxt,value); |
|
33 fixflat->AppendL(theElement); |
|
34 }</codeblock> <p><b>Notes</b> </p> <ul> |
|
35 <li id="GUID-8A3A6363-9F76-5640-8F99-9B5D2020DE75"><p>Adding the first element |
|
36 into this array causes an array buffer with a capacity of 3 elements to be |
|
37 constructed. Attempting to add a 4th element causes the array buffer to be |
|
38 re-allocated so that it has a capacity of 6 elements.</p> </li> |
|
39 <li id="GUID-30EC3B13-981F-5F6E-A538-B34F52A8083E"><p>In general, the granularity |
|
40 should be carefully chosen to minimise the number of calls to the memory allocator |
|
41 and to avoid wasted space within the array buffer.</p> </li> |
|
42 </ul> </section> |
|
43 <section id="GUID-49AC8560-DE23-453F-8608-301937D0E044"><title>Inserting an element</title> <p>The following code fragment |
|
44 uses <codeph>InsertL()</codeph> to insert a new element into a definite position |
|
45 in a <codeph>CArrayFixFlat<class T></codeph> array. For example, to insert |
|
46 a <codeph>TElement</codeph> object at the <i>beginning</i> of the array (position |
|
47 zero in the array) :</p> <codeblock id="GUID-791DCCF9-86EC-561B-A470-432782D91002" xml:space="preserve">CArrayFixFlat<TElement>* fixflat; |
|
48 fixflat = new (ELeave) CArrayFixFlat<TElement>(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"); |
|
49 theElement.iData = KTxtBeg; |
|
50 fixflat->InsertL(0,theElement);</codeblock> <p>To insert a new element at |
|
51 (what is now) position 2 of the array:</p> <codeblock id="GUID-0FFDE613-1044-5251-B09E-DD353B56472C" xml:space="preserve">_LIT(KTxtMid,"MID"); |
|
52 theElement.iData = KTxtMid; |
|
53 fixflat->InsertL(2,theElement);</codeblock> <p>To insert a new element at |
|
54 the back of the array:</p> <codeblock id="GUID-C642EE09-BDF7-55BD-B499-E721FA1E56D8" xml:space="preserve">_LIT(KTxtEnd,"END"); |
|
55 theElement.iData = KTxtEnd; |
|
56 fixflat->InsertL(fixflat->Count(),theElement);</codeblock> <p>Elements can |
|
57 also be inserted into the array at a position determined by a key (i.e. inserted |
|
58 in key sequence) using the <codeph>InsertIsqL()</codeph> member function.</p> </section> |
|
59 <section id="GUID-B7EDDA8C-007F-41F4-994D-8B2A02372054"><title>Adding and inserting a pointer to an array of pointers</title> <p>The |
|
60 following code fragment uses the <codeph>AppendL()</codeph> and <codeph>InsertL()</codeph> functions |
|
61 to append and insert a pointer into a <codeph>CArrayPtrFlat</codeph> array. |
|
62 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<TElement>* ptrflat; |
|
63 ptrflat = new (ELeave) CArrayPtrFlat<TElement>(3);</codeblock> <codeblock id="GUID-C150C0F3-F2CD-5B46-A3AF-349BD6515DF3" xml:space="preserve">ptr = new (ELeave) CElement; |
|
64 ... |
|
65 ptrflat->AppendL(ptr); |
|
66 ... |
|
67 ptr = new (ELeave) CElement; |
|
68 ... |
|
69 ptrflat->InsertL(0,ptr);</codeblock> </section> |
|
70 </conbody></concept> |