--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-81C1F6BE-B2CE-5A2B-A6D4-DC1ABBBED0DE.dita	Wed Mar 31 11:11:55 2010 +0100
@@ -0,0 +1,76 @@
+<?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>
\ No newline at end of file