How to +use standard buffer operations

Dynamic buffers have the expected standard buffer operations.

InsertL() example

You can insert data into a buffer +using InsertL(). In the following example code fragment, +data is inserted into the buffer initially, and then some more data inserted +into the middle of the first data.

// insert text into buffer + _LIT8(KTxtHello,"Hello!"); + _LIT8(KWorld," world"); + ... + aBuf->InsertL(0,KTxtHello); + writeBuf(aBuf); // gives “Hello!” + aBuf->InsertL(5,KWorld); + writeBuf(aBuf); // gives “Hello world!”

In common with all +functions that expand the size of the buffer, InsertL() may +fail, by leaving. When you program with dynamic buffers, you must ensure that +all potential leaves are handled correctly.

InsertL(), +and the entire dynamic buffer API, deals only with 8-bit byte data. When interfacing +with descriptors which contain text, you should take special precautions to +ensure that UNICODE is handled correctly.

Read() example

Data can be read from a buffer by +specifying a start position and a target descriptor. The number of bytes to +be read may be specified explicitly, as here, or by the descriptor length. +Another Read() variant, specifying the target as a TAny*, +is provided.

The following code fragment follows from the previous +one:

// read from buffer into descriptor + TBuf8<10> des; + aBuf->Read(3,des,5); // puts "lo wo" into des.

Write() example

Write() overwrites +existing data in the buffer. Because the buffer is not expanded, Write() cannot +leave. You must ensure that the region you select in the buffer already exists: +if Write() attempts to write beyond the end of the data already +in the buffer, a panic occurs.

// [over]write some stuff in buffer + _LIT8(KFolks,"folks"); + aBuf->Write(6,KFolks); + writeBuf(aBuf); // gives “Hello folks!”

Delete() example

Delete() deletes +data in the buffer. It can never fail.

// delete stuff + aBuf->Delete(5,6); + writeBuf(aBuf); // gives “Hello!”

Compress() example

Compress() ensures +that the buffer data occupies the minimum space. In the case of flat buffers, +this re-allocates the cell to the size of the data in the buffer. In the case +of segmented buffers, it may shuffle data so as to occupy the minimum number +of segments.

// compress + aBuf->Compress(); + writeBuf(aBuf);