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:
- List and describe all dictionary "methods".
- List and describe all dictionary "attributes".
Compile and link the module to your source code. For example, using gfortran
:
gfortran -c fhdict.f90
gfortran -o my_executable fhdict.o
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.
- 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:
- 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.
- 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()
-
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.
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)
- Now computes the hash in a completely different manner.
- Now uses integer keys, rather than strings.
- Now permits a variety of value types, including: integers, arbitrary-length integer arrays, and arbitrary-length real arrays.
- 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).