hashmap-init-update

Includes code updates, doc, test and example updates for initialize update.

Author: chuckyvt

doc/specs/stdlib_hashmaps.md

@@ -763,7 +763,7 @@ type. Each of these types are described below.
 
 The `hashmap_type` abstract type serves as the parent type for the two
 types `chaining_hashmap_type` and `open_hashmap_type`. It defines
-seven private components:
+eight private components:
 
 * `call_count` - the number of procedure calls on the map;
 
@@ -782,6 +782,8 @@ seven private components:
 
 * `hasher` - a pointer to the hash function used by the map.
 
+* `initialized` - track if map has been initialized
+
 It also defines five non-overridable procedures:
 
 * `calls` - returns the number of procedure calls on the map;
@@ -1074,7 +1076,7 @@ are listed below.
 
 Procedure to initialize a chaining hash map:
 
-* `map % init( hasher[, slots_bits, status] )` - Routine
+* `map % init( [hasher, slots_bits, status] )` - Routine
   to initialize a chaining hash map.
 
 Procedure to modify the structure of a map:
@@ -1295,7 +1297,7 @@ Initializes a `hashmap_type` object.
 
 ##### Syntax
 
-`call map % ` [[hashmap_type(type):init(bound)]] `( hasher [, slots_bits, status ] )`
+`call map % ` [[hashmap_type(type):init(bound)]] `( [hasher, slots_bits, status ] )`
 
 ##### Class
 
@@ -1308,9 +1310,10 @@ Subroutine
   `intent(out)` argument. It will 
   be a hash map used to store and access the entries.
 
-`hasher`: shall be a procedure with interface `hash_fun`.
+`hasher`: (optional): shall be a procedure with interface `hash_fun`.
   It is an `intent(in)` argument. It is the procedure to be used to
-  generate the hashes for the table from the keys of the entries.
+  generate the hashes for the table from the keys of the entries. 
+  Defaults to fnv_1_hasher if not provided.
 
 `slots_bits` (optional): shall be a scalar default integer 
   expression. It is an `intent(in)` argument. The initial number of

example/hashmaps/example_hashmaps_calls.f90

@@ -1,10 +1,9 @@
 program example_calls
   use stdlib_hashmaps, only: chaining_hashmap_type, int_calls
-  use stdlib_hashmap_wrappers, only: fnv_1_hasher
   implicit none
   type(chaining_hashmap_type) :: map
   integer(int_calls) :: initial_calls
-  call map%init(fnv_1_hasher)
+  call map%init()
   initial_calls = map%calls()
   print *, "INITIAL_CALLS =  ", initial_calls
 end program example_calls

example/hashmaps/example_hashmaps_entries.f90

@@ -1,10 +1,9 @@
 program example_entries
   use stdlib_hashmaps, only: open_hashmap_type, int_index
-  use stdlib_hashmap_wrappers, only: fnv_1_hasher
   implicit none
   type(open_hashmap_type) :: map
   integer(int_index) :: initial_entries
-  call map%init(fnv_1_hasher)
+  call map%init()
   initial_entries = map%entries()
   print *, "INITIAL_ENTRIES =  ", initial_entries
 end program example_entries

example/hashmaps/example_hashmaps_get_all_keys.f90

@@ -1,7 +1,7 @@
 program example_hashmaps_get_all_keys
   use stdlib_kinds, only: int32
   use stdlib_hashmaps, only: chaining_hashmap_type
-  use stdlib_hashmap_wrappers, only: fnv_1_hasher, get, &
+  use stdlib_hashmap_wrappers, only: get, &
                                      key_type, set
   implicit none
   type(chaining_hashmap_type) :: map
@@ -12,8 +12,6 @@ program example_hashmaps_get_all_keys
 
   character(:), allocatable :: str
 
-  call map%init(fnv_1_hasher)
-
   ! adding key-value pairs to the map
   call set(key, "initial key")
   call map%map_entry(key, "value 1")

example/hashmaps/example_hashmaps_get_other_data.f90

@@ -1,7 +1,7 @@
 program example_get_other_data
   use stdlib_kinds, only: int8, int64
   use stdlib_hashmaps, only: chaining_hashmap_type, int_index
-  use stdlib_hashmap_wrappers, only: fnv_1_hasher, key_type, set, get
+  use stdlib_hashmap_wrappers, only: key_type, set
   implicit none
   logical                     :: conflict
   type(key_type)              :: key
@@ -14,9 +14,6 @@ program example_get_other_data
   integer(int8), allocatable  :: key_array(:)
   integer                     :: int_scalar
 
-  ! Initialize hashmap
-  call map%init(fnv_1_hasher)
-  
   ! Hashmap functions are setup to store scalar value types (other).  Use a dervied
   ! type wrapper to store arrays.
   dummy%value = [4, 3, 2, 1]

example/hashmaps/example_hashmaps_init.f90

@@ -1,7 +1,26 @@
 program example_init
-  use stdlib_hashmaps, only: chaining_hashmap_type
+  use stdlib_hashmaps, only: chaining_hashmap_type, open_hashmap_type
   use stdlib_hashmap_wrappers, only: fnv_1_hasher
   implicit none
   type(chaining_hashmap_type) :: map
-  call map%init(fnv_1_hasher, slots_bits=10)
+  logical :: present
+  
+  
+  !If default values are used, then init can be typically be skipped as the first map_entry call will initialize the map using default values.  
+  call map%map_entry('key', 'value')
+  call map%key_test('key', present)
+  print *, "Key exists without explicit init call =  ", present
+  
+  ! Init can be called to clear all items in a map. 
+  call map%init()
+  call map%key_test('key', present)
+  print *, "Key exists after re-initalization =  ", present
+  
+  ! User can optional specify hasher type and slots_bits instead of using default values.  
+  ! Number of slots in the hashmap will initially equal 2**slots_bits.   
+  ! The hashmap will autmoatically re-size as needed, however for better performance, a rule of thumb is to size so that number of slots is ~2X expected number of entries.
+  ! In this example with slots_bits=10, there will initially be 1024 slots in the map.  
+  call map%init(hasher=fnv_1_hasher, slots_bits=10)
+  call map%map_entry('key', 'value')
+  
 end program example_init

example/hashmaps/example_hashmaps_key_test.f90

@@ -1,13 +1,15 @@
 program example_key_test
   use stdlib_kinds, only: int8
   use stdlib_hashmaps, only: chaining_hashmap_type
-  use stdlib_hashmap_wrappers, only: fnv_1_hasher, key_type, set
+  use stdlib_hashmap_wrappers, only: key_type, set
   implicit none
   type(chaining_hashmap_type) :: map
   type(key_type) :: key
   logical :: present
-  call map%init(fnv_1_hasher)
+  
+  call map%init()
   call set(key, [0_int8, 1_int8])
   call map%key_test(key, present)
   print *, "Initial key of 10 present for empty map =  ", present
+  
 end program example_key_test

example/hashmaps/example_hashmaps_loading.f90

@@ -1,10 +1,9 @@
 program example_loading
   use stdlib_hashmaps, only: open_hashmap_type
-  use stdlib_hashmap_wrappers, only: fnv_1_hasher
   implicit none
   type(open_hashmap_type) :: map
   real :: ratio
-  call map%init(fnv_1_hasher)
+  call map%init()
   ratio = map%loading()
   print *, "Initial loading =  ", ratio
 end program example_loading

example/hashmaps/example_hashmaps_map_entry.f90

@@ -1,7 +1,7 @@
 program example_map_entry
   use, intrinsic:: iso_fortran_env, only: int8, int64
   use stdlib_hashmaps, only: chaining_hashmap_type
-  use stdlib_hashmap_wrappers, only: fnv_1_hasher, key_type, set
+  use stdlib_hashmap_wrappers, only: key_type, set
   implicit none
   type(chaining_hashmap_type) :: map
   type(key_type)      :: key
@@ -16,7 +16,7 @@ program example_map_entry
 
   ! Initialize hashmap with 2^10 slots.
   ! Hashmap will dynamically increase size if needed.
-  call map%init(fnv_1_hasher, slots_bits=10)
+  call map%init(slots_bits=10)
 
   ! Explicitly set key using set function
   call set(key, [1, 2, 3])

example/hashmaps/example_hashmaps_num_slots.f90

@@ -1,10 +1,9 @@
 program example_num_slots
   use stdlib_hashmaps, only: chaining_hashmap_type, int_index
-  use stdlib_hashmap_wrappers, only: fnv_1_hasher
   implicit none
   type(chaining_hashmap_type) :: map
   integer(int_index) :: initial_slots
-  call map%init(fnv_1_hasher)
+  call map%init()
   initial_slots = map%num_slots()
   print *, "Initial slots =  ", initial_slots
 end program example_num_slots