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

 writeBuf(aBuf); // gives “Hello!”

 aBuf->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<10> 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->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->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->Compress();

 writeBuf(aBuf);</codeblock> </section>