<?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->InsertL(0,KHelloWorld);

//

// Reserve space for 16 X 8-bit chars

//

buf->ExpandL(6,16);            // <- this can fail

writeBuf(buf);

//

// Now insert only 16 characters

//

TText8 c='a';                  // character to insert

for (TInt i=0; i<16; i++, c++)

 {

 buf->Write(i+6, &c, 1);   // write a char in - cannot fail

 }

writeBuf(buf);

//

// Now adjust size down to 18

//

buf->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>