How to +allocate buffers

Allocating buffers is simple: use the desired class’s static NewL() function. +You must specify a granularity, whose meaning is particular to the +buffer type.

Flat buffer

To allocate a flat buffer, use CFlatBuf::NewL(). +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.

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.

The function StandardBufferStuffL() is +one which takes a CBufBase type.

// do flat buffer tests + CBufFlat* flatBuf=CBufFlat::NewL(4); + CleanupStack::PushL(flatBuf); + StandardBufferStuffL(flatBuf); + CleanupStack::PopAndDestroy();

Segmented buffer

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.

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 standardBufferStuffL() with +both a flat and a segmented buffer pointer. The argument to this function +is a CBufBase*.

The granularities chosen for these +examples are much smaller than would be used in most real applications.

// do segmented buffer tests + CBufSeg* segBuf=CBufSeg::NewL(4); + CleanupStack::PushL(segBuf); + standardBufferStuffL(segBuf); + CleanupStack::PopAndDestroy();