12 <concept id="GUID-1F1A6FCD-DA06-5F8B-8F2C-0BAA08DE0041" xml:lang="en"><title>How to

    12 <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

    13 allocate buffers</title><shortdesc>Explains the functions to create and allocate flat and segmented

    13 segmented buffers.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 buffers.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <p>Allocating buffers is simple: use the desired class’s static <codeph>NewL()</codeph> function. You must specify a <i>granularity</i>,

    15 <p>Allocating buffers is simple: use the desired class’s static <codeph>NewL()</codeph> function.

    15 whose meaning is particular to the buffer type.</p>

    16 You must specify a <i>granularity</i>, whose meaning is particular to the

    16 <section id="GUID-35823578-F609-41ED-B4A3-00BAE20C4AAC"><title>Flat

    17 buffer type.</p>

    17 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

    18 <section id="GUID-35823578-F609-41ED-B4A3-00BAE20C4AAC"><title>Flat buffer</title> <p>To allocate a flat buffer, use <codeph>CFlatBuf::NewL()</codeph>.

    18 the buffer will be re-allocated, whenever expansion is necessary.

    19 The granularity in this case means the number of bytes by which the buffer

    19 If expansion by a greater amount than this is required, the next highest

    20 will be re-allocated, whenever expansion is necessary. If expansion by a greater

    20 multiple of the granularity will be used.</p> <p>In this example,

    21 amount than this is required, the next highest multiple of the granularity

    21 the buffer pointer is pushed to the cleanup stack for the lifetime

    22 will be used.</p> <p>In this example, the buffer pointer is pushed to the

    22 of the buffer. If any operation involving the buffer should leave,

    23 cleanup stack for the lifetime of the buffer. If any operation involving the

    23 the buffer will be destroyed. In real use, the buffer pointer would

    24 buffer should leave, the buffer will be destroyed. In real use, the buffer

    24 be stored as member data, and care should be taken to ensure that

    25 pointer would be stored as member data, and care should be taken to ensure

    25 the consequences of a leave are not fatal to the application. For

    26 that the consequences of a leave are not fatal to the application. For example,

    26 example, if the buffer is being used to store a word processor document,

    27 if the buffer is being used to store a word processor document, an attempt

    27 an attempt to add a character may fail due to lack of memory. This

    28 to add a character may fail due to lack of memory. This should never cause

    28 should never cause the entire document to be destroyed! Instead, the

    29 the entire document to be destroyed! Instead, the editing code should function

    29 editing code should function in such a way that the update is either

    30 in such a way that the update is either implemented successfully, or no change

    30 implemented successfully, or no change is made to the document.</p> <p>The function <codeph>StandardBufferStuffL()</codeph> is one which

    31 is made to the document.</p> <p>The function <codeph>StandardBufferStuffL()</codeph> is

    31 takes a <codeph>CBufBase</codeph> type.</p> <codeblock id="GUID-EF6F9CDB-0D9A-5AB8-9BBC-958DEE5C382E" xml:space="preserve"> // do flat buffer tests

    32 one which takes a <codeph>CBufBase</codeph> type.</p> <codeblock id="GUID-EF6F9CDB-0D9A-5AB8-9BBC-958DEE5C382E" xml:space="preserve"> // do flat buffer tests

    37 <section id="GUID-0E671A5E-99A9-4ED6-9CA1-519BA5E3A8D9"><title>Segmented buffer</title> <p>A segmented buffer is allocated

    36 <section id="GUID-0E671A5E-99A9-4ED6-9CA1-519BA5E3A8D9"><title>Segmented

    38 in a similar way to a flat buffer. The granularity in this case specifies

    37 buffer</title> <p>A segmented buffer is allocated in a similar way

    39 the size of each segment. During buffer operations, each segment may contain

    38 to a flat buffer. The granularity in this case specifies the size

    40 less data than the granularity. After a compress, data is optimally distributed

    39 of each segment. During buffer operations, each segment may contain

    41 to segments, so that all segments except possibly the last one are full.</p> <p>During

    40 less data than the granularity. After a compress, data is optimally

    42 their lifetime, all standard buffer operations can be performed on either

    41 distributed to segments, so that all segments except possibly the

    43 flat or segmented buffers. This is shown in the examples above by calling <codeph>standardBufferStuffL()</codeph> with

    42 last one are full.</p> <p>During their lifetime, all standard buffer

    44 both a flat and a segmented buffer pointer. The argument to this function

    43 operations can be performed on either flat or segmented buffers. This

    45 is a <codeph>CBufBase*</codeph>.</p> <p>The granularities chosen for these

    44 is shown in the examples above by calling <codeph>standardBufferStuffL()</codeph> with both a flat and a segmented buffer pointer. The argument to

    46 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

    45 this function is a <codeph>CBufBase*</codeph>.</p> <p>The granularities

    46 chosen for these examples are much smaller than would be used in most

    47 real applications. </p> <codeblock id="GUID-70676BB5-F806-5860-A96D-77EF0897FFA7" xml:space="preserve"> // do segmented buffer tests

    52 <link>

    53 <link href="GUID-E3DD768F-752F-5414-9E9A-86E046806903.dita">

    53 <desc><xref href="GUID-E3DD768F-752F-5414-9E9A-86E046806903.dita">Space management

    54 <linktext>Space management and granularity</linktext></link>

    54 and granularity</xref></desc>

    55 </link>