Units
Classes, Interfaces, Objects
Types
Variables
Constants
Functions, Procedures
Identifiers

Class TExHash

Unit

rjExDictHash

Declaration

type TExHash = class(TExAbstractDictHash)

Description

Base class for Hash containers. Hash containers store their Items by reference to a Key. This Hash container implements fixed length keys, where all Keys are of the same size. Keys are passed to the Hash container as untyped variable constants.

To insert or to retrieve Items, the application must always provide the appropriate Key. Duplicated Keys are not allowed.

TExHash is fully functional except that the OnCopyKey, OnHashKey and OnSameKeys properties have not yet been set. Before adding any Items to a TExHash container, they must be set by either the application itself or by descendant classes, preferably within the constructor. KeySize and ItemSize must also be set.

Note: TExHash containers also work with an ItemSize of 0 (zero). In this case, they act like very fast "lookup" containers. They are very powerful if applications only need to test the existance of a particular key and are by far superior to sorted vectors.

Related containers: TExAnsiDict.

Hierarchy

TExAbstractDictHash > TExContainer > TErrorObject

Fields

NameDescription
FKeySize See KeySize.
FOnCopyKey See OnCopyKey.

Methods

Overview

constructor Create; override;
procedure ClearVector; override;
function DeleteByKey(const AKey): Boolean;
function GetIndexOfKey(const AKey): Integer;
function GetIndexOfKeyEx(const AKey; out Hash: Cardinal; out Previous: Integer): Integer;
function GetItemAt(const Index: Integer): Pointer;
function GetPItemOfKey(const AKey): Pointer;
function GetPItemOfKeyEx(const AKey; out Hash: Cardinal; out Previous: Integer): Pointer;
function GetPKeyAt(const Index: Integer): Pointer;
function InsertItemByKey(const AKey): Pointer;
procedure RebuildHash; override;
procedure SetItemSize(const NewItemSize: Integer); override;
procedure SetKeySize(const NewKeySize: Integer);

Description

constructor Create; override;

Creates an instance of TExHash.

procedure ClearVector; override;

 

function DeleteByKey(const AKey): Boolean;

Deletes the Item associated with a key AKey. If the Key could be located and the Item deleted, DeleteByKey returns True, otherwise False.

If the number of undeleted Items in the hash container falls to below 1/3 of VectorCount as a result of calling DeleteByKey, the container is shrunk to roughly half its size.

function GetIndexOfKey(const AKey): Integer;

 

function GetIndexOfKeyEx(const AKey; out Hash: Cardinal; out Previous: Integer): Integer;

 

function GetItemAt(const Index: Integer): Pointer;

 

function GetPItemOfKey(const AKey): Pointer;

 

function GetPItemOfKeyEx(const AKey; out Hash: Cardinal; out Previous: Integer): Pointer;

 

function GetPKeyAt(const Index: Integer): Pointer;

 

function InsertItemByKey(const AKey): Pointer;

Inserts a new Item and returns a pointer to it.

Duplicate Keys are not allowed in hash containers. If the Key already exists, no new Item will be added and InsertItemByKey will return nil.

procedure RebuildHash; override;

 

procedure SetItemSize(const NewItemSize: Integer); override;

See ItemSize.

procedure SetKeySize(const NewKeySize: Integer);

See KeySize.

Properties

Overview

IndexOfKey[const AKey]: Integer;
KeySize: Integer;
OnCopyKey: TExCopyKeyProc;
PItemAt[const Index: Integer]: Pointer;
PItemOfKey[const AKey]: Pointer;
PKeyAt[const Index: Integer]: Pointer;

Description

IndexOfKey[const AKey]: Integer;

Returns the Index of the Item stored under a given Key. If the Key could not be found, IndexOfKey returns a negative number.

KeySize: Integer;

The size in bytes of the TExHash container's Keys. Each time a new Item is inserted, KeySize bytes of memory will be allocated for its Key and be copied from AKey. KeySize must not be 0 (zero) for a TExHash container to function. A KeySize of 0 would prevent the Keys from being stored.

OnCopyKey will be called to actually copy the key to the container, with KeySize as its last parameter.

OnCopyKey: TExCopyKeyProc;

Procedure variable called to copy a Key to the container.

In general, the CopyKey procedure will work fine for most purposes, but to enhance performance it is best to assign a procedure especially fitted for your Hash container's Keys and KeySize.

See also: CopyKey, CopyKey04, CopyKey08.

PItemAt[const Index: Integer]: Pointer;

Returns a pointer to the Item at the specified Index's position in the hash container.

Items may have been deleted in hash containers. It is advisable to Call IsDeleted before retrieving Items, unless it is known that no Items have yet been deleted or Pack has been called.

Index must be in the range zero to VectorCount-1. An exception will be raised if Index is outside of this range and rjExContainer Library was compiled with the directive "RangeChecking" defined (default).

See also: Pack, VectorCount.

PItemOfKey[const AKey]: Pointer;

Returns a pointer to the Item stored under a given Key. If Key could not be found, PItemOfKey returns nil.

PKeyAt[const Index: Integer]: Pointer;

Returns a pointer to the Key of the Item at the specified Index's position in the hash container.

Items may have been deleted in hash containers. It is advisable to Call IsDeleted before retrieving Keys, unless it is known that no Items have yet been deleted or Pack has been called.

Index must be in the range zero to VectorCount-1. An exception will be raised if Index is outside of this range and rjExContainer Library was compiled with the directive "RangeChecking" defined (default).

See also: Pack, VectorCount.


rjExContainer Library Version 0.2.
Copyright Ralf Junker 2000-2001.
http://www.zeitungsjunge.de/delphi/.