<?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-807B5CEE-CC1E-5A40-911F-3C5D5FA3633A" xml:lang="en"><title>How to
use standard buffer operations</title><shortdesc>Explains the functions to read, write, insert, delete and compress
data in buffers.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>Dynamic buffers have the expected standard buffer operations.</p>
<section id="GUID-7AC34BEB-0BAB-462D-A170-B42446625805"><title>InsertL() example</title> <p>You can insert data into a buffer
using <codeph>InsertL()</codeph>. In the following example code fragment,
data is inserted into the buffer initially, and then some more data inserted
into the middle of the first data.</p> <codeblock id="GUID-0237C066-1F66-5D54-BA06-5FBFC8C0F1F4" xml:space="preserve"> // insert text into buffer
 _LIT8(KTxtHello,"Hello!");
 _LIT8(KWorld," world");
 ...
 aBuf-&gt;InsertL(0,KTxtHello);
 writeBuf(aBuf); // gives “Hello!”
 aBuf-&gt;InsertL(5,KWorld);
 writeBuf(aBuf); // gives “Hello world!”</codeblock> <p>In common with all
functions that expand the size of the buffer, <codeph>InsertL()</codeph> may
fail, by leaving. When you program with dynamic buffers, you must ensure that
all potential leaves are handled correctly.</p> <p><codeph>InsertL()</codeph>,
and the entire dynamic buffer API, deals only with 8-bit byte data. When interfacing
with descriptors which contain text, you should take special precautions to
ensure that UNICODE is handled correctly.</p> </section>
<section id="GUID-9C234566-872B-44E0-BBB4-8892FB58E1DD"><title>Read() example</title> <p>Data can be read from a buffer by
specifying a start position and a target descriptor. The number of bytes to
be read may be specified explicitly, as here, or by the descriptor length.
Another <codeph>Read()</codeph> variant, specifying the target as a <codeph>TAny*</codeph>,
is provided.</p> <p>The following code fragment follows from the previous
one:</p> <codeblock id="GUID-33E8D519-72DB-5BFA-8904-BC63B3F13820" xml:space="preserve"> // read from buffer into descriptor
 TBuf8&lt;10&gt; des;
 aBuf-&gt;Read(3,des,5); // puts "lo wo" into des.</codeblock> </section>
<section id="GUID-DB7447A4-FA97-4727-B92D-E61556EA4AF5"><title>Write() example</title> <p><codeph>Write()</codeph> overwrites
existing data in the buffer. Because the buffer is not expanded, <codeph>Write()</codeph> cannot
leave. You must ensure that the region you select in the buffer already exists:
if <codeph>Write()</codeph> attempts to write beyond the end of the data already
in the buffer, a panic occurs.</p> <codeblock id="GUID-F5A86813-3C56-58B1-AAB0-E888E61BF736" xml:space="preserve"> // [over]write some stuff in buffer
 _LIT8(KFolks,"folks");
 aBuf-&gt;Write(6,KFolks);
 writeBuf(aBuf); // gives “Hello folks!”</codeblock> </section>
<section id="GUID-53F96FF4-38D1-4F4B-93DD-AA6B85FF8C99"><title>Delete() example</title> <p><codeph>Delete()</codeph> deletes
data in the buffer. It can never fail.</p> <codeblock id="GUID-AA268BA8-CF54-5D93-A869-0EB291F5CE5A" xml:space="preserve"> // delete stuff
 aBuf-&gt;Delete(5,6);
 writeBuf(aBuf); // gives “Hello!”</codeblock> </section>
<section id="GUID-D06541B3-1FA0-4511-91AA-8F8F33CBD273"><title>Compress() example</title> <p><codeph>Compress()</codeph> ensures
that the buffer data occupies the minimum space. In the case of flat buffers,
this re-allocates the cell to the size of the data in the buffer. In the case
of segmented buffers, it may shuffle data so as to occupy the minimum number
of segments.</p> <codeblock id="GUID-4F22F39C-756E-5665-AE58-816237D771C6" xml:space="preserve">// compress
 aBuf-&gt;Compress();
 writeBuf(aBuf);</codeblock> </section>
</conbody></concept>