How to use standard buffer operations

Dynamic buffers have the expected standard buffer operations.

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.

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() 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() deletes data in the buffer. It can never fail.

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

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);