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

Class TExAbstractDictHash

Unit

rjExDictHash

Declaration

type TExAbstractDictHash = class(TExContainer)

Description

Abstract base class for Dictionary and Hash containers. Do not create instances of TExAbstractDictHash. Instead, use it as a base for descendant classes which set FHashNodeSize and override the virtual procedures ClearVector and RebuildHash.

Important properties: OnHashKey, OnSameKeys.

Descendant containers: TExHash, TExAnsiDict, TExAnsiCSDict, TExAnsiCIDict.

Hierarchy

TExContainer > TErrorObject

Fields

NameDescription
FFirstDeleted Index of the first deleted Item. Used to recover deleted Items the next time a new Item is inserted. Negative value indicates no items are deleted.
FHash Pointer to array of Integers storing the hash values. Negative values indicate empty slots.
FHashCount See HashCount.
FHashNodeSize Overall size of a hash node, i.e. its Next index, Key and Elements. Must be set by descendant classes.
FOnHashKey See OnHashKey.
FOnSameKeys See OnSameKey.
FVector See Vector.
FVectorCount See VectorCount

Methods

Overview

constructor Create; override;
destructor Destroy; override;
procedure AdjustCapacity(const NewCount: Integer);
procedure Clear; virtual;
procedure ClearVector; virtual; abstract;
function IsDeleted(const Index: Integer): Boolean;
procedure Pack;
procedure RebuildHash; virtual; abstract;
procedure ResetHash;
procedure SetCountNoInit(const NewCount: Integer);
procedure SetHashCount(const NewHashCount: Integer);

Description

constructor Create; override;

Creates an instance of TExAbstractDictHash.

destructor Destroy; override;

Destroys an instance of TExAbstractDictHash.

procedure AdjustCapacity(const NewCount: Integer);

 

procedure Clear; virtual;

Deletes all Items from a hash container and sets the Hash vector to its initial size. Clear calls the virtual method ClearVector to clear Keys and Items.

procedure ClearVector; virtual; abstract;

Abstract procedure. Descendant classes must override ClearVector to clear all Keys and Items stored in the container before finally freeing the vector itself and setting VectorCount to 0 (zero).

function IsDeleted(const Index: Integer): Boolean;

Returns True if the Item at Index position has been deleted. Deleted Items are not accessible to the application. So before accesssing Items by Index, check if they are not deleted.

procedure Pack;

Removes all Items marked as deleted from the hash container. Excess memory will be freed.

procedure RebuildHash; virtual; abstract;

Abstract procedure. Descendant classes must override RebuildHash to rebuild tje hash vector, i.e. after the hash vector count has changed or the hash vector has been packed using Pack.

procedure ResetHash;

Resets all values in the hash vector to their uninitialized state (HASH_END).

procedure SetCountNoInit(const NewCount: Integer);

 

procedure SetHashCount(const NewHashCount: Integer);

See HashCount.

Properties

Overview

HashCount: Integer;
OnHashKey: TExHashKeyFunc;
OnSameKeys: TExSameKeysFunc;
Vector: Pointer;
VectorCount: Integer;

Description

HashCount: Integer;

The current number of slots in the hash vector. Default is MIN_HASH_SIZE.

The hash vector is automatically grown each time it is full by increasing its count by 1/3. The hash vector is shrunk automatically when is reaches 1/3 full by approximately halving its size.

HashCount is always prime. Prime numbers greatly improve the efficiency of the hash containers. Whenever you write to HashCount, the container will force HashCount to the nearest prime. So if you set HashCount to 100, the HashCount's write method will adjust it to 101, the nearest prime.

If you set HashCount, the hash container will automatically reorganize its hash vector to use the new value.

Hint: If you know that you'll be adding quite a lot of items, it will be more efficient to set HashCount right at the start, rather than letting the hash vector grow incrementally. Since there won't be any items in the hash table, this will be very fast, and you've ensured that the container won't need to grow the hash vector.

OnHashKey: TExHashKeyFunc;

OnHashKey is a function variable of the type TExHashKeyFunc. It will be called each time a hash value needs to be calculated for a Key, i.e. when inserting, deleting or looking up Items by their Keys.

The OnHashKey function must return a hash value appropriate for the Key type of the hash container. It must always correspond with the OnSameKey function.

Two parameters are passed into the function: An untyped pointer to the Key and the Key's size as the second parameter. The pointer may be typecast to the appropriate Key type or the KeySize parameter used to control the calculation.

A OnHashKey function must be assigned for any Dictionary or Hash container to function. TExAbstractDictHash does not not assigned OnHashKey by default, leaving this task for the application or descendant containers.

See also: OnSameKeys.

OnSameKeys: TExSameKeysFunc;

OnSameKeys is a function variable of the type TExSameKeysFunc. It will be called each time two keys need to be compared in terms of equality, i.e. when inserting, deleting or looking up Items by their Keys.

The OnSameKeys function must return True if the two keys are equal and False otherwise. It must always correspond with the OnHashKey function: For example, if the OnHashKey calculation is case-insensitive, OnSameKeys must also be case-insensitive.

Three parameters are passed into the function: Two pointers to the keys to compare, and the length of the keys as a third parameter. The pointers may be typecast to the appropriate Key type or the KeySize parameter used to control the comparison.

A OnSameKeys function must be assigned for any Dictionary or Hash container to function. TExAbstractDictHash does not not assigned OnSameKeys by default, leaving this task for the application or descendant containers.

See also: OnHashKey.

Vector: Pointer;

Pointer to array storing Items with their keys and index to possible next Item.

VectorCount: Integer;

Indicates the number all Items, deleted and undeleted, in the hash container. VectorCount is opposed to Count / FCount, which returns the number of undeleted Items in the container. Thus, VectorCount is always greater than or equal to Count.

Use VectorCount when iterating over all Items in the container and check IsDeleted to see if an Item is deleted or not.

See also: Pack.


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