<?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>
</conbody></concept>