<?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-81C1F6BE-B2CE-5A2B-A6D4-DC1ABBBED0DE" xml:lang="en"><title>How to
pre-expand a buffer</title><shortdesc>Explains how to use the <codeph>Expand()</codeph> function in buffers.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>The <codeph>InsertL()</codeph> function provides a means of writing data
into a buffer, and expanding it as necessary. When the kind of data to be
inserted cannot be predicted in advance, this is the best technique to use.
An example of this situation would be entering characters into a word processor
document in response to user keystrokes.</p>
<p>In cases where the data to be inserted into a buffer is known in advance
— typically, when restoring from a file or stream store — it is better to
pre-expand the buffer to be able to contain the data, and then <codeph>Write()</codeph> into
the expanded region of the buffer:</p>
<p>In the following example the buffer is allocated and primed with some data.
Then <codeph>ExpandL()</codeph> is used to insert 16 uninitialised bytes into
the buffer after position 6. The buffer is now 28 bytes long. Then, data is
written into this gap using <codeph>Write()</codeph>, which cannot leave.</p>
<codeblock id="GUID-70600A2B-F559-5F5C-99C7-0EFA79047571" xml:space="preserve">//
// Allocate buffer
//
CBufBase* buf=CBufSeg::NewL(4);
CleanupStack::PushL(buf);

//
// Put some text in
//
_LIT8(KHelloWorld,"Hello world!");
buf-&gt;InsertL(0,KHelloWorld);

//
// Reserve space for 16 X 8-bit chars
//
buf-&gt;ExpandL(6,16);            // &lt;- this can fail
writeBuf(buf);

//
// Now insert only 16 characters
//
TText8 c='a';                  // character to insert
for (TInt i=0; i&lt;16; i++, c++)
 {
 buf-&gt;Write(i+6, &amp;c, 1);   // write a char in - cannot fail
 }
writeBuf(buf);

//
// Now adjust size down to 18
//
buf-&gt;ResizeL(18);
writeBuf(buf);

//
// Destroy buffer
//
CleanupStack::PopAndDestroy();</codeblock>
<p>There are two advantages to replacing a large number of <codeph>InsertL()</codeph> operations
with a single <codeph>ExpandL()</codeph> followed by many <codeph>Write()</codeph> operations:</p>
<ul>
<li id="GUID-E8B09B4A-FB3C-52E2-B1DE-AD96DF175081"><p>each <codeph>InsertL()</codeph> may
call the allocator to expand the dynamic buffer, and may cause data beyond
the insertion point to be shuffled up: using a single <codeph>ExpandL()</codeph> results
in minimal calls to the allocator, and only a single shuffle</p> </li>
<li id="GUID-A35ECB22-A81E-547C-9D55-2DF23785E5AE"><p>the <codeph>Write()</codeph> operations
cannot leave: therefore, once a buffer has been successfully expanded to the
right size, the writes are guaranteed to work: this is useful in some circumstances.</p> </li>
</ul>
</conbody></concept>