--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-1F1A6FCD-DA06-5F8B-8F2C-0BAA08DE0041.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,56 @@
+<?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>
\ No newline at end of file