<?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-1F1A6FCD-DA06-5F8B-8F2C-0BAA08DE0041" xml:lang="en"><title>How to allocate buffers</title><shortdesc>Explains the functions to create and allocate flat and
segmented buffers.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>Allocating buffers is simple: use the desired class’s static <codeph>NewL()</codeph> function. You must specify a <i>granularity</i>,
whose meaning is particular to the buffer type.</p>
<section id="GUID-35823578-F609-41ED-B4A3-00BAE20C4AAC"><title>Flat
buffer</title> <p>To allocate a flat buffer, use <codeph>CFlatBuf::NewL()</codeph>. The granularity in this case means the number of bytes by which
the buffer will be re-allocated, whenever expansion is necessary.
If expansion by a greater amount than this is required, the next highest
multiple of the granularity will be used.</p> <p>In this example,
the buffer pointer is pushed to the cleanup stack for the lifetime
of the buffer. If any operation involving the buffer should leave,
the buffer will be destroyed. In real use, the buffer pointer would
be stored as member data, and care should be taken to ensure that
the consequences of a leave are not fatal to the application. For
example, if the buffer is being used to store a word processor document,
an attempt to add a character may fail due to lack of memory. This
should never cause the entire document to be destroyed! Instead, the
editing code should function in such a way that the update is either
implemented successfully, or no change is made to the document.</p> <p>The function <codeph>StandardBufferStuffL()</codeph> is one which
takes a <codeph>CBufBase</codeph> type.</p> <codeblock id="GUID-EF6F9CDB-0D9A-5AB8-9BBC-958DEE5C382E" xml:space="preserve"> // do flat buffer tests
 CBufFlat* flatBuf=CBufFlat::NewL(4);
 CleanupStack::PushL(flatBuf);
 StandardBufferStuffL(flatBuf);
 CleanupStack::PopAndDestroy();</codeblock> </section>
<section id="GUID-0E671A5E-99A9-4ED6-9CA1-519BA5E3A8D9"><title>Segmented
buffer</title> <p>A segmented buffer is allocated in a similar way
to a flat buffer. The granularity in this case specifies the size
of each segment. During buffer operations, each segment may contain
less data than the granularity. After a compress, data is optimally
distributed to segments, so that all segments except possibly the
last one are full.</p> <p>During their lifetime, all standard buffer
operations can be performed on either flat or segmented buffers. This
is shown in the examples above by calling <codeph>standardBufferStuffL()</codeph> with both a flat and a segmented buffer pointer. The argument to
this function is a <codeph>CBufBase*</codeph>.</p> <p>The granularities
chosen for these examples are much smaller than would be used in most
real applications. </p> <codeblock id="GUID-70676BB5-F806-5860-A96D-77EF0897FFA7" xml:space="preserve"> // do segmented buffer tests
 CBufSeg* segBuf=CBufSeg::NewL(4);
 CleanupStack::PushL(segBuf);
 standardBufferStuffL(segBuf);
 CleanupStack::PopAndDestroy();</codeblock> </section>
</conbody><related-links>
<link href="GUID-E3DD768F-752F-5414-9E9A-86E046806903.dita">
<linktext>Space management and granularity</linktext></link>
</related-links></concept>