Explains how to use the Expand() function in buffers.
The InsertL() function provides a means of writing data
into a buffer, and expanding it as necessary. When the kind of data to be
inserted cannot be predicted in advance, this is the best technique to use.
An example of this situation would be entering characters into a word processor
document in response to user keystrokes.
In cases where the data to be inserted into a buffer is known in advance
— typically, when restoring from a file or stream store — it is better to
pre-expand the buffer to be able to contain the data, and then Write() into
the expanded region of the buffer:
In the following example the buffer is allocated and primed with some data.
Then ExpandL() is used to insert 16 uninitialised bytes into
the buffer after position 6. The buffer is now 28 bytes long. Then, data is
written into this gap using Write(), which cannot leave.
//
// Allocate buffer
//
CBufBase* buf=CBufSeg::NewL(4);
CleanupStack::PushL(buf);
//
// Put some text in
//
_LIT8(KHelloWorld,"Hello world!");
buf->InsertL(0,KHelloWorld);
//
// Reserve space for 16 X 8-bit chars
//
buf->ExpandL(6,16); // <- this can fail
writeBuf(buf);
//
// Now insert only 16 characters
//
TText8 c='a'; // character to insert
for (TInt i=0; i<16; i++, c++)
{
buf->Write(i+6, &c, 1); // write a char in - cannot fail
}
writeBuf(buf);
//
// Now adjust size down to 18
//
buf->ResizeL(18);
writeBuf(buf);
//
// Destroy buffer
//
CleanupStack::PopAndDestroy();
There are two advantages to replacing a large number of InsertL() operations
with a single ExpandL() followed by many Write() operations:
each InsertL() may
call the allocator to expand the dynamic buffer, and may cause data beyond
the insertion point to be shuffled up: using a single ExpandL() results
in minimal calls to the allocator, and only a single shuffle
the Write() operations
cannot leave: therefore, once a buffer has been successfully expanded to the
right size, the writes are guaranteed to work: this is useful in some circumstances.