Buffer position

How to use buffer position with other functions.

All operations are specified in terms of a buffer position, which is an integer whose valid range is zero to the size of the buffer. The buffer position is a byte offset into the buffer’s data.

The InsertL() and DeleteL() functions cause data after the inserted or deleted region to be shuffled up or down the buffer as appropriate; also, InsertL() even at the end of a flat buffer may cause re-allocation which may move the cell’s position in memory. Because of this, the memory address corresponding to a buffer position may change. Therefore, any pointer references to data in a buffer — including pointers inside descriptors — must be updated (or discarded) after the buffer is updated in any way.

It is recommended that all references to data in buffers be maintained in terms of the buffer position. When data is inserted or deleted, buffer positions after the beginning of the insertion or deletion position must be adjusted (or, in the case of positions inside a deleted region, discarded). The amount of the adjustment is the length of the inserted or deleted data.

Pointers cannot be maintained as simply as buffer positions. In the case of flat buffers, re-allocation may cause the entire buffer’s address to change. In the case of segmented buffers, data is discontiguous and the segmentation algorithm is not straightforward. Therefore, it is recommended that pointer references be discarded after any update, and that adjustments to pointer references always use the CBufBase programming interface, rather than user program calculations.