FortranHashDict

A fast, easy to use Key-Value Dictionary data structure implemented with a hashtable and singly-linked lists, for Fortran 2003+.

The Key-Value Dictionary is implemented with object-oriented techniques as a derived type with user-accessible "methods" and "attributes". Currently, FortranHashDict supports the Key-Value mappings:

Key | Value --------|-------------------- Integer | Integer Integer | Arbitrary-length 1D array of Integers Integer | Arbitrary-length 1D array of double-precision Reals

DOCUMENTATION TODO:

• [x] List and describe all dictionary "methods".
• [x] List and describe all dictionary "attributes".

Compile and Link

Compile and link the module to your source code. For example, using gfortran:

gfortran -c fhdict.f90
gfortran -o my_executable fhdict.o

Basic Usage

Type Declaration and Initialization

In your source code, import the FHDICT module with a USE statement:

use fhdict

Declare variables using the hashtable dictionary type from FHDICT:

type(hashtable) :: dict_1, dict_2

Initialize the dictionary:

dict_1%init()                              !! Using default settings.
dict_2%init(nitems=1000, is_mutable=.false.) !! Specify max # items and is_mutable attributes.

Methods and Attributes

Methods

• INIT: (Subroutine) Initialize the dictionary.

call dict%init([nitems=N] [,] [is_mutable=.true.|.false])
!! or
call dict%init()
!! or
call dict%init(N)

Arguments | Desc | Default ----------------------|------------------------------------------|------------------------ nitems (optional) | Expected Max # of key-value pairs | nitems=101 is_mutable (optional) | Allow/Prevent overwriting existing keys | is_mutable=.true.

Notes:

1. The hash computed for a key will use a prime number P not less than the specified nuber of items N such that N<=P.
2. The is_mutable attribute may be updated/changed at any time.

• PUT: (Subroutine) Places a key-value pair into the dictionary. The key (key) and one of the mutually-exclusive values (ival, val, rvals) are required.

call dict%put(key=mykey, val=myvals [, rc=r]) 

Arguments | Desc | Example ---------------- |------------------------------------------|------------------------ key (required) | Must be a single-precision integer "key" | key=5 ival (optional) | A single-precision integer "value" | ival=99 val (optional) | A 1D array of single-precision integers | val=[1,2,3] rvals (optional) | A 1D array of double-precision reals | rvals=[1.d0, 2.d0, 3.d0] rc (optional) | Return code (success=0, error=1) | rc=r

• GET: (Subroutine) Given a key, get the value from the dictionary and return it in the supplied (ival, val, rvals) variable.

call dict%get(key=mykey, val=myvals [, rc=r]) 

Arguments | Desc | Example ---------------- |------------------------------------------|------------------------ key (required) | Must be a single-precision integer "key" | key=5 ival (optional) | A single-precision integer | ival=v val (optional) | A 1D allocatable array of single-precision integers | val=v1 rvals (optional) | A 1D allocatable array of double-precision reals | rvals=v2 rc (optional) | Return code (success=0, error=1) | rc=r

• DEL: (Subroutine) Deletes a key-value pair from the dictionary.

call dict%del(key=mykey [, rc=r]) 
!! or
call dict%del(mykey)

• KEYS: (Subroutine) Returns an array of keys in the dictionary.

call dict%keys(k=mykeys [, rc=r])  !! mykeys is an allocatable integer array
!! or
call dict%keys(mykeys)

• HAS_KEY: (Logical Function) Checks if a specified key exists in the dictionary. Returns logical true/false.

TF = dict%has_key(key=mykey)
!! or 
TF = dict%has_key(mykey)

• HASH: (Integer Function) Computes the hash for a specified integer key. Returns integer.

myhash = dict%hash(key=mykey)
!! or
myhash = dict%hash(mykey)

• FREE: Deletes all key-value pairs and deallocates the dictionary.

call dict%free()

Attributes

• CAPACITY: The max number of items specified when the dictionary was initialized.

• COUNT: Current number of key-value pairs in dictionary.

• IS_INIT: True if dictionary has been initialized.

• IS_MUTABLE: True if the value for an existing key may be overwritten. This attribute may be changed to lock/unlock the dictionary at any time.

---

Attribution

FortHashDict has been modified from the LGPLv3-licensed work by Izaak Beekman found at:
http://fortranwiki.org/fortran/show/hash+table+example

Changes include:
(March 8, 2018)

1. Now computes the hash in a completely different manner.
2. Now uses integer keys, rather than strings.
3. Now permits a variety of value types, including: integers, arbitrary-length integer arrays, and arbitrary-length real arrays.
4. Now adds several subroutine "methods" and "attributes" to the original hashtable derived type, including added functionality to the original methods of (init, put, get, free).