Unit PasDoc_Hashes

Description

This unit implements an associative array. Before writing this unit, I've always missed Perl commands like $h{abc}='def' in Pascal.

Version 0.9.1 (works fine, don't know a bug, but 1.0? No, error checks are missing!)

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details.

You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA

Thanks to:

• Larry Wall for perl! And because I found a way how to implement a hash in perl's source code (hv.c and hv.h). This is not a direct translation from C to Pascal, but the algortithms are more or less the same.

Be warned:

• There is NOT a single ERROR CHECK in this unit. So expect anything! Especially there are NO checks on NEW and GETMEM functions — this might be dangerous on machines with low memory.

Programmer's information:

• you need Freepascal (http://www.freepascal.org) or Delphi (http://www.borland.com) to compile this unit

• I recommend that you use Ansistrings {$H+} to be able to use keys longer than 255 chars

How to use this unit:

Simply put this unit in your uses line. You can use a new class - THash.

Initialize a hash (assuming "var h: THash;"):
h:=THash.Create;

Save a String:
h.SetString('key','value');          //perl: $h{key}='value'

Get the String back:
string_var:=h.GetString('key');      //perl: $string_var=$h{key}
returns '' if 'key' is not set

Test if a key has been set:
if h.KeyExists('key') then...        //perl: if (exists $h{key}) ...
returns a boolean

Delete a key
h.DeleteKey('key');                  //perl: delete $h{key};

Which keys do exist?
stringlist:=h.Keys;                  //perl: @list=keys %h;
returns a TStringList

Which keys do exist beginning with a special string?
stinglist:=h.Keys('abc');
returns all keys beginning with 'abc'  //perl: @list=grep /ˆabc/, keys %h;

How many keys are there?
number_of_keys:=h.Count;             //perl: $number=scalar keys %hash;

How many keys fit in memory allocated by THash?
c:=h.Capacity; (property)
THash automatically increases h.Capacity if needed.
This property is similar to Delphi's TList.Capacity property.
Note #1: You can't decrease h.Capacity.
Note #2: Capacity must be 2**n -- Create sets Capacity:=8;
         The same: Capacity:=17; , Capacity:=32;

I know there will be 4097 key/values in my hash. I don't want
the hash's capacity to be 8192 (wasting 50% ram). What to do?
h.MaxCapacity:=4096; => Capacity will never be > 4096.
Note: You can store more than MaxCapacity key/values in the
      hash (as many as you want) but Count should be >= Capacity
      for best performance.
MaxCapacity is -1 by default, meaning no limit.

Delete the hash
h.Free;    OR
h.Destroy;

Instead of just strings you can also save objects in my hash -
anything that is a pointer can be saved. Similar to SetString
and GetString  there are SetObject  and GetObject. The latter
returns nil if the key is unknown.
You can use both Set/GetString and Set/GetObject for a single
key string - no problem. But if DeleteKey is called, both the
string and the pointer are lost.
If you want to store a pointer  and a string, it is faster to
call  SetStringObject(key,string,pointer)  than SetString and
SetObject. The same is true getting the data back - GetString
and GetObject are  significantly slower  then a singe call to
GetStringObject(key, var string, var pointer).

Happy programming!

Uses

• SysUtils
• Classes

Overview

Classes, Interfaces, Objects and Records

Name	Description
Record THashEntry
Class THash
Class TObjectHash

Types

PPHashEntry=ˆPHashEntry;

PHashEntry=ˆTHashEntry;

TFakeArray=array[0..0] of PHashEntry;

PFakeArray=ˆTFakeArray;

Description

Types

PPHashEntry=ˆPHashEntry;

PHashEntry=ˆTHashEntry;

TFakeArray=array[0..0] of PHashEntry;

in FPC, I can simply use PPHashEntry as an array of PHashEntry - Delphi doesn't allow that. I need this stupid array[0..0] definition! From Delphi4, I could use a dynamic array.

PFakeArray=ˆTFakeArray;

Author

• Copyright (C) 2001-2014 Wolf Behrenhoff <wolf@behrenhoff.de> and PasDoc developers

---

Generated by PasDoc 0.16.0.