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-E2CB0826-FC44-5AC9-BBB1-B449073484F3" xml:lang="en"><title>Array

    13 capacity and granularity</title><shortdesc>Describes the granularity and capacity of a dynamic array.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <p>The <i>capacity</i> of an array is the number of elements which the array

    15 can hold or represent within the space currently allocated to its array buffer.</p>

    16 <p>For a flat array buffer, the increase in capacity of a buffer, when the

    17 insertion of an additional element causes the buffer to be re-allocated, is

    18 termed the <i>granularity</i> of the array. For example, adding a fifth element

    19 to a fixed flat array constructed with a granularity of four, causes the array

    20 buffer to be re-allocated so that its capacity increases from four to eight

    21 elements.</p>

    22 <fig id="GUID-B752C5C8-FFA3-5F27-8D75-C951EE2D1432">

    23 <image href="GUID-4922D80F-009D-56CE-B255-FDAF9C247667_d0e219038_href.png" placement="inline"/>

    24 </fig>

    25 <p>For a segmented array buffer, the granularity defines the capacity of a

    26 single segment. A segmented array buffer is always expanded by allocating

    27 additional segments.</p>

    28 <p>The granularity of an array is defined at construction time.

    29 The choice of value depends on the use to be made of the array and needs careful

    30 consideration. Too small a value for an array with a high turnover of elements

    31 can incur considerable overhead from the process of allocating memory. Too

    32 large a value can result in wasted space if insufficient new elements are

    33 subsequently added.</p>

    34 <section id="GUID-33BD77F1-C787-49D9-87C0-011900038A64"><title>See also</title> <p><xref href="GUID-112AAFA5-B4C9-5B62-A106-FB5097C13A0E.dita">Using

    35 Dynamic Buffers</xref>.</p> </section>

    36 </conbody></concept>