Array Keys Overview

The document provides an overview of array keys.

Purpose

Defines a property of an array element by which a heap based array can sorted and searched.

Architectural relationships

Keys are declared by client programs, and used in conjunction with the heap based array classes defined by the Dynamic Arrays API.

Keys are also used by the low-level sorting functions supplied by the System Static Functions API.

Description

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.

General properties

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.

Concrete classes are defined for each of the basic Symbian platform array types, fixed length, variable length, and packed.

Abstract key base

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:

  • location: defines which data member of the array element type should be used for sorting, etc.

  • type: whether the data member is a descriptor, text (NULL terminated string), or a number.

The abstract key base interface is provided by TKey.

Fixed-length array key

The fixed-length element array key specifies the key to be used with fixed-length element (CArrayFix -based) arrays.

The abstract key base interface is provided by TKeyArrayFix.

Variable-length array key

The variable-length element array key specifies the key to be used with variable-length element (CArrayVar -based) arrays, and for sorting packed (CArrayPakFlat -based) arrays.

The variable length array key interface is provided by TKeyArrayVar.

Packed array key

The packed array key specifies the key to be used for searching and inserting elements by key with packed (CArrayPakFlat -based) arrays.

The packed array key interface is provided by TKeyArrayPak.

Array element swap operation base

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.

The array element swap operation base interface is provided by TSwap.