<?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>
<desc><xref href="GUID-E3DD768F-752F-5414-9E9A-86E046806903.dita">Space management
and granularity</xref></desc>
</link>
</related-links></concept>