Class TKey

class TKey;

Description

Defines the characteristics of a key used to access the elements of an array.

The class is abstract and cannot be instantiated. A derived class must be defined and implemented.

The classes TKeyArrayFix, TKeyArrayVar and TKeyArrayPak, derived from TKey, are already supplied to implement keys for the fixed length element, variable length element and packed arrays.

A derived class would normally be written to define the characteristics of a key for a non standard array.

Members

Defined in TKey:

• At(TInt)constGets a pointer to the key of a specified array element.
• Compare(TInt,TInt)constCompares the keys of two array elements.
• SetPtr(const TAny *)Sets the pointer to a sample element whose key is to be used for comparison.
• TKey()Protected default constructor.
• TKey(TInt,TKeyCmpNumeric)Constructs the characteristics of a numeric key.
• TKey(TInt,TKeyCmpText)Constructs the characteristics of a descriptor type key.
• TKey(TInt,TKeyCmpText,TInt)Constructs the characteristics of a text key.
• iCmpType
• iKeyLength
• iKeyOffset
• iPtr

See also:

• TKeyArrayFix...
• TKeyArrayVar...
• TKeyArrayPak...

protected: IMPORT_C TKey();

Description

Protected default constructor.

This constructor prevents TKey objects from being constructed directly.

protected: IMPORT_C TKey(TInt aOffset, TKeyCmpText aType);

Description

Constructs the characteristics of a descriptor type key.

This constructor should be called by the corresponding derived class constructor that takes the same arguments. Typically, the derived class constructor calls this constructor in its constructor initialization list.

No length value is passed as this is implied by the type of key.

Note that the constructor sets the offset value into the protected data member iKeyOffset.

Parameters

TInt aOffset The offset of the key from the start of an array element. TKeyCmpText aType An enumeration which defines the type of comparison to be made between two descriptor keys.

Panic codes

USER 98, if anOffset is negative.

See also:

• TKeyCmpText...

protected: IMPORT_C TKey(TInt aOffset, TKeyCmpText aType, TInt aLength);

Description

Constructs the characteristics of a text key.

This constructor should be called by the corresponding derived class constructor that takes the same arguments. Typically, the derived class constructor calls this constructor in its constructor initialization list.

Note that the constructor sets the offset value into the protected data member iKeyOffset.

Parameters

TInt aOffset The offset of the key from the start of an array element. TKeyCmpText aType An enumeration which defines the type of comparison to be made between two text keys. TInt aLength The length of the text key.

Panic codes

USER 98, if anOffset is negative.

See also:

• TKeyCmpText...

protected: IMPORT_C TKey(TInt aOffset, TKeyCmpNumeric aType);

Description

Constructs the characteristics of a numeric key.

This constructor should be called by the corresponding derived class constructor that takes the same arguments. Typically, the derived class constructor calls this constructor in its constructor initialization list.

No length value is passed as this is implied by the type of key.

Note that the constructor sets the offset value into the protected data member iKeyOffset.

Parameters

TInt aOffset The offset of the key from the start of an array element. TKeyCmpNumeric aType An enumeration which defines the type of the numeric key.

Panic codes

USER 98, if anOffset is negative.

inline void SetPtr(const TAny *aPtr);

Description

Sets the pointer to a sample element whose key is to be used for comparison.

The element can be in an existing array or it can be located anywhere in addressable memory.

The TKey::At(TInt)const member function supplied by a derived class must return a pointer to this sample element's key when passed an index value of KIndexPtr.

TKey::SetPtr(const TAny *) must be called before calling User::BinarySearch(TInt,const TKey &,TInt &) because this algorithm uses the key of this sample element as the basis for searching the array.

Parameters

const TAny *aPtr A pointer to a sample element.

IMPORT_C virtual TInt Compare(TInt aLeft, TInt aRight) const;

Description

Compares the keys of two array elements.

This function is called by User::BinarySearch(TInt,const TKey &,TInt &) and User::QuickSort(TInt,const TKey &,const TSwap &).

The position of the elements are identified by the specified index values. The default implementation uses the TKey::At(TInt)const virtual function to convert the index values into pointers to the elements themselves.

The default implementation also uses:

1. the TDesC comparison functions to compare descriptor type keys

2. the Mem functions to compare text type keys

3. numeric comparison for numeric type keys.

Parameters

TInt aLeft The index of an array element participating in the comparison, designated the left element. TInt aRight The index of an array element participating in the comparison, designated the right element.

Return value

TInt Zero, if the two keys are equal; negative, if the left key is less than the right key; positive, if the left key is greater than the right key.

See also:

• User::BinarySearch(TInt,const TKey &,TInt &)Performs a binary search for an array element containing a specified key.
• User::QuickSort(TInt,const TKey &,const TSwap &)Quick sorts array elements.
• Mem...

IMPORT_C virtual TAny* At(TInt anIndex) const;

Description

Gets a pointer to the key of a specified array element.

The default implementation raises a USER 35 panic.

The function is called by TKey::Compare(TInt,TInt)const to compare the keys of two elements.

The implementation provided by a derived class must convert the index to a pointer to the key within the corresponding element. The implementation depends on the design of the array but, as general rule, use the index value to get a pointer to the corresponding element and then add the TKey protected data member iKeyOffset to this pointer to get a pointer to the key itself.

By convention, the index value is relative to zero; i.e. a zero value refers to the first element in the array. By this convention, the index can take any value between zero and the number of elements within the array minus one.

The function must also handle the special index value KIndexPtr. When this value is passed, the function should return a pointer to the key within the sample element. A pointer to the sample element is held in the protected data member iPtr and can be set up using TKey::SetPtr(const TAny *).

The implementation of this function also assumes that the derived class has a pointer to the array itself or has a function for finding it.

Parameters

TInt anIndex The index of the array element or the special index value KIndexPtr.

Return value

TAny * An untyped pointer to the key within the specified array element or an untyped pointer to the key within the sample element, if KIndexPtr is passed as an argument.

Panic codes

USER 35, if no replacement function has been provided by a derived class.

See also:

• TKey::Compare(TInt,TInt)constCompares the keys of two array elements.
• TKey::SetPtr(const TAny *)Sets the pointer to a sample element whose key is to be used for comparison.
• KIndexPtr...

protected: TInt iKeyOffset;

Description

protected: TInt iKeyLength;

Description

protected: TInt iCmpType;

Description

protected: const TAny * iPtr;

Description