<?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-BC32CC7C-99BA-59E8-A268-42F411CF336F" xml:lang="en"><title>Array

Keys Overview</title><shortdesc>The document provides an overview of array keys.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-E936A40A-CE40-400A-A534-B06F0339871D"><title>Purpose</title> <p>Defines a property of an array element

by which a heap based array can sorted and searched.</p> </section>

<section id="GUID-5550159B-8E50-4FF4-A7D4-EAB1E325CF8F"><title>Architectural relationships</title> <p>Keys are declared by

client programs, and used in conjunction with the heap based array classes

defined by the Dynamic Arrays API.</p> <p>Keys are also used by the low-level

sorting functions supplied by the System Static Functions API.</p> </section>

<section id="GUID-9A7E535D-A289-4B43-B04E-B9F76E66242D"><title>Description</title> <p>The API has four key concepts: abstract

key base, fixed-length element array key, variable-length element array key,

packed array key, and array element swap operation base. </p> <p><b>General

properties</b> </p> <p>A key specifies a data member within a type. It allows

the caller to manipulate an array of elements of this type. The Symbian platform

array classes have member functions for sorting, finding, and inserting elements

by key.</p> <p>Concrete classes are defined for each of the basic Symbian

platform array types, fixed length, variable length, and packed.</p> <p><b>Abstract key base</b> </p> <p>The abstract key base defines the characteristics

of a key and defines the basic behaviour of keys. The most important properties

of a key are:</p> <ul>

<li id="GUID-77B18DD9-C54C-59E2-94D5-4ECF30615D5A"><p>location: defines which

data member of the array element type should be used for sorting, etc.</p> </li>

<li id="GUID-9B2CEF3B-026E-5A3E-A9E7-629BFC2D8A21"><p>type: whether the data

member is a descriptor, text (NULL terminated string), or a number.</p> </li>

</ul> <p>The abstract key base interface is provided by <codeph>TKey</codeph>.</p> <p><b>Fixed-length array key</b> </p> <p>The fixed-length element array key

specifies the key to be used with fixed-length element (<codeph>CArrayFix</codeph> -based)

arrays.</p> <p>The abstract key base interface is provided by <codeph>TKeyArrayFix</codeph>.</p> <p><b>Variable-length array key</b> </p> <p>The variable-length element array

key specifies the key to be used with variable-length element (<codeph>CArrayVar</codeph> -based)

arrays, and for sorting packed (<codeph>CArrayPakFlat</codeph> -based) arrays.</p> <p>The

variable length array key interface is provided by <codeph>TKeyArrayVar</codeph>.<codeph> </codeph> </p> <p><b>Packed array key</b> </p> <p>The packed array key specifies the key to

be used for searching and inserting elements by key with packed (<xref href="GUID-4D6E6B46-32B5-34AD-BD8A-84BF6B2B7C81.dita"><apiname>CArrayPakFlat</apiname></xref> -based)

arrays.</p> <p>The packed array key interface is provided by <codeph>TKeyArrayPak</codeph>.</p> <p><b>Array element swap operation base</b> </p> <p>If a client uses the sort

function provided by the System Static Functions API, instead of sorting through

the Symbian platform array classes, it must define a class able to swap elements. </p> <p>The

array element swap operation base interface is provided by <codeph>TSwap</codeph>.</p> </section>

<section id="GUID-8A098367-CCDF-4E35-86C6-13F5824B8153"><title>See also</title> <p><xref href="GUID-56EE13F0-CAEE-5E1C-99CD-2FEC8C3BCA6B.dita">Dynamic

Arrays Overview</xref> </p> <p><xref href="GUID-FF8F5D97-7D37-5F6B-84A3-C064E2FD53E0.dita">System

Static Functions Overview</xref> </p> </section>