How to +pre-expand a buffer

diff -r 43e37759235e -r 51a74ef9ed63 Symbian3/SDK/Source/GUID-81C1F6BE-B2CE-5A2B-A6D4-DC1ABBBED0DE.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-81C1F6BE-B2CE-5A2B-A6D4-DC1ABBBED0DE.dita Wed Mar 31 11:11:55 2010 +0100 @@ -0,0 +1,76 @@ + + + + + +How to +pre-expand a bufferExplains 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.

+ \ No newline at end of file