|
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-81C1F6BE-B2CE-5A2B-A6D4-DC1ABBBED0DE" xml:lang="en"><title>How to |
|
13 pre-expand a buffer</title><shortdesc>Explains how to use the <codeph>Expand()</codeph> function in buffers.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>The <codeph>InsertL()</codeph> function provides a means of writing data |
|
15 into a buffer, and expanding it as necessary. When the kind of data to be |
|
16 inserted cannot be predicted in advance, this is the best technique to use. |
|
17 An example of this situation would be entering characters into a word processor |
|
18 document in response to user keystrokes.</p> |
|
19 <p>In cases where the data to be inserted into a buffer is known in advance |
|
20 — typically, when restoring from a file or stream store — it is better to |
|
21 pre-expand the buffer to be able to contain the data, and then <codeph>Write()</codeph> into |
|
22 the expanded region of the buffer:</p> |
|
23 <p>In the following example the buffer is allocated and primed with some data. |
|
24 Then <codeph>ExpandL()</codeph> is used to insert 16 uninitialised bytes into |
|
25 the buffer after position 6. The buffer is now 28 bytes long. Then, data is |
|
26 written into this gap using <codeph>Write()</codeph>, which cannot leave.</p> |
|
27 <codeblock id="GUID-70600A2B-F559-5F5C-99C7-0EFA79047571" xml:space="preserve">// |
|
28 // Allocate buffer |
|
29 // |
|
30 CBufBase* buf=CBufSeg::NewL(4); |
|
31 CleanupStack::PushL(buf); |
|
32 |
|
33 // |
|
34 // Put some text in |
|
35 // |
|
36 _LIT8(KHelloWorld,"Hello world!"); |
|
37 buf->InsertL(0,KHelloWorld); |
|
38 |
|
39 // |
|
40 // Reserve space for 16 X 8-bit chars |
|
41 // |
|
42 buf->ExpandL(6,16); // <- this can fail |
|
43 writeBuf(buf); |
|
44 |
|
45 // |
|
46 // Now insert only 16 characters |
|
47 // |
|
48 TText8 c='a'; // character to insert |
|
49 for (TInt i=0; i<16; i++, c++) |
|
50 { |
|
51 buf->Write(i+6, &c, 1); // write a char in - cannot fail |
|
52 } |
|
53 writeBuf(buf); |
|
54 |
|
55 // |
|
56 // Now adjust size down to 18 |
|
57 // |
|
58 buf->ResizeL(18); |
|
59 writeBuf(buf); |
|
60 |
|
61 // |
|
62 // Destroy buffer |
|
63 // |
|
64 CleanupStack::PopAndDestroy();</codeblock> |
|
65 <p>There are two advantages to replacing a large number of <codeph>InsertL()</codeph> operations |
|
66 with a single <codeph>ExpandL()</codeph> followed by many <codeph>Write()</codeph> operations:</p> |
|
67 <ul> |
|
68 <li id="GUID-E8B09B4A-FB3C-52E2-B1DE-AD96DF175081"><p>each <codeph>InsertL()</codeph> may |
|
69 call the allocator to expand the dynamic buffer, and may cause data beyond |
|
70 the insertion point to be shuffled up: using a single <codeph>ExpandL()</codeph> results |
|
71 in minimal calls to the allocator, and only a single shuffle</p> </li> |
|
72 <li id="GUID-A35ECB22-A81E-547C-9D55-2DF23785E5AE"><p>the <codeph>Write()</codeph> operations |
|
73 cannot leave: therefore, once a buffer has been successfully expanded to the |
|
74 right size, the writes are guaranteed to work: this is useful in some circumstances.</p> </li> |
|
75 </ul> |
|
76 </conbody></concept> |