How to -pre-expand a buffer

diff -r ebc84c812384 -r 46218c8b8afa Symbian3/PDK/Source/GUID-81C1F6BE-B2CE-5A2B-A6D4-DC1ABBBED0DE.dita --- a/Symbian3/PDK/Source/GUID-81C1F6BE-B2CE-5A2B-A6D4-DC1ABBBED0DE.dita Thu Mar 11 15:24:26 2010 +0000 +++ b/Symbian3/PDK/Source/GUID-81C1F6BE-B2CE-5A2B-A6D4-DC1ABBBED0DE.dita Thu Mar 11 18:02:22 2010 +0000 @@ -1,76 +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.

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