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

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

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

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

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

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

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

    12 <concept id="GUID-E161AB84-1B24-53AF-B313-D68CF9F8EE60" xml:lang="en"><title>Pointers

    13 to the start and end of contiguous regions</title><shortdesc>The <codeph>Back()</codeph> and <codeph>End()</codeph> functions

    14 point to locations in memory for flat and segmented arrays.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    15 <p>For those arrays of same length elements which are derived from <codeph>CArrayFix&lt;class T&gt;</codeph>,

    16 the elements are contained within an array buffer which can be implemented

    17 as a flat buffer or as a segmented buffer. A flat buffer is implemented as

    18 a single contiguous region of memory while a segmented buffer is implemented

    19 as a set of separate but linked regions of memory </p>

    20 <p>Given the position of an element within an array, it can be useful to fetch

    21 a pointer to the first byte following the end of the contiguous region of

    22 memory containing that element (the <i>end</i> pointer). Similarly, it can

    23 be useful to fetch a pointer to the <i>beginning</i> of a contiguous region

    24 of memory (the <i>back</i> pointer).</p>

    25 <section id="GUID-DB6D5E2F-CFEE-47EC-B38D-9D0DC13B994D"><title>Array of same length elements</title> <p>An array of same

    26 length elements uses the <codeph>End()</codeph> function to fetch the end

    27 pointer and the <codeph>Back()</codeph> function to fetch the back pointer.

    28 The implementation of these two functions differs between a fixed flat array

    29 and a fixed segmented array.</p> </section>

    30 <section id="GUID-48756A91-9B8F-4BA8-A0CF-52970F8B41CC"><title>Flat array</title> <p>For a flat array — i.e. an array whose

    31 buffer is implemented using a flat buffer — the end pointer simply points

    32 to the first byte following the single region of memory containing the array

    33 buffer. The back pointer simply points to the first byte of the single region

    34 of memory (as illustrated below); <codeph>End()</codeph> always returns a

    35 pointer to the first byte following the end of the buffer, while <codeph>Back()</codeph> always

    36 returns a pointer to the beginning of the buffer.</p> <fig id="GUID-D4084F4C-B928-5779-A58F-CB495A74EE68">

    37 <title>End() and Back() in fixed flat arrays</title>

    38 <image href="GUID-81A5784D-A0C6-5108-9E7B-5D39C6743B1A_d0e308796_href.png" placement="inline"/>

    39 </fig> </section>

    40 <section id="GUID-27F85346-3B08-4E06-A80D-A5B708105659"><title>Segmented array</title> <p>For a segmented array, the situation

    41 is different (as illustrated below). Looking at the segment containing elements <codeph>n</codeph> and <codeph>n+1</codeph>, <codeph>End()</codeph> returns a pointer to the first byte following the end of that segment. In

    42 fact, <codeph>End()</codeph> returns the same pointer value for all elements

    43 in that segment. <codeph>Back()</codeph> returns a pointer to the beginning

    44 of that segment for element <codeph>n+1</codeph> and for all <i>subsequent</i> elements

    45 in that segment. However, for the <i>first</i> element in that segment, <codeph>Back()</codeph> returns

    46 a pointer to the beginning of the <i>previous</i> segment. For the very first

    47 element in the array, <codeph>Back()</codeph> returns a pointer with a NULL

    48 value.</p> <fig id="GUID-90C05AF9-9048-557E-95DD-49A19F856EF0">

    49 <title>End() and Back() in fixed segmented arrays</title>

    50 <image href="GUID-C0CFFE13-579C-5A93-9B63-DC2DCF98EC61_d0e308845_href.png" placement="inline"/>

    51 </fig> </section>

    52 <section id="GUID-165D9F3E-3948-4DC0-9632-FF70480C495C"><title>See also</title> <p><xref href="GUID-112AAFA5-B4C9-5B62-A106-FB5097C13A0E.dita">Dynamic

    53 Buffers Guide</xref>.</p> </section>

    54 </conbody></concept>