<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-59FFCA8F-5F2C-55F9-B864-AFA1CC18722D" xml:lang="en"><title>Buffer

position</title><shortdesc>How to use buffer position with other functions.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>All operations are specified in terms of a <i>buffer position</i>, 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.</p>

<p>The <codeph>InsertL()</codeph> and <codeph>DeleteL()</codeph> functions

cause data after the inserted or deleted region to be shuffled up or down

the buffer as appropriate; also, <codeph>InsertL()</codeph> 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.</p>

<p>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.</p>

<p>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 <i>discarded</i> after any update, and that adjustments to pointer

references always use the <codeph>CBufBase</codeph> programming interface,

rather than user program calculations.</p>

</conbody></concept>