Skip to content

Commit 5053777

Browse files
committed
Changed the function "valid_key" to the subroutine "key_test"
In implementing the API described in "stdlib_hashmaps.md" I discovered that the function "key_test" had to be implemented as a subroutine, and that the map argument to "get_other_data" had to have intent inout and not in. [ticket: X]
1 parent f4c8c1c commit 5053777

File tree

1 file changed

+68
-72
lines changed

1 file changed

+68
-72
lines changed

doc/specs/stdlib_hashmaps.md

Lines changed: 68 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -951,7 +951,7 @@ procedures to manipulate the structure of a hash map object:
951951
`init`, `map_entry`, `rehash`, `remove`, and
952952
`set_other_data`. They also provide procedures to inquire about
953953
entries in the hash map: `get_other_data`, and
954-
`valid_key`. Finally they provide procedures to inquire about the
954+
`key_test`. Finally they provide procedures to inquire about the
955955
overall structure and performance of the hash map object:`calls`,
956956
`entries`, `get_other_data`, `loading`, `slots`, and
957957
`total_depth`. The module also defines a number of public constants:
@@ -1050,8 +1050,10 @@ It also defines five non-overridable procedures:
10501050
* `num_slots` - returns the number of slots in the map; and
10511051
* `slots_bits` - returns the number of bits used to address the slots;
10521052
and eleven deferred procedures:
1053-
* `get_other_data` - gets the other data associated with the key;
1053+
* `get_other_data` - gets the other map data associated with the key;
10541054
* `init` - initializes the hash map;
1055+
* `key_test` - returns a logical flag indicating whether the key is
1056+
defined in the map.
10551057
* `loading` - returns the ratio of the number of entries to the number
10561058
of slots;
10571059
* `map_entry` - inserts a key and its other associated data into the
@@ -1061,8 +1063,6 @@ and eleven deferred procedures:
10611063
* `set_other_data` - replaces the other data associated with the key;
10621064
* `total_depth` - returns the number of probes needed to address all
10631065
the entries in the map;
1064-
* `valid_key` - returns a logical flag indicating whether the key is
1065-
defined in the map.
10661066

10671067
The type's definition is below:
10681068

@@ -1084,13 +1084,13 @@ The type's definition is below:
10841084
procedure, non_overridable, pass(map) :: num_slots
10851085
procedure(get_other), deferred, pass(map) :: get_other_data
10861086
procedure(init_map), deferred, pass(map) :: init
1087+
procedure(key_test), deferred, pass(map) :: key_test
10871088
procedure(loading), deferred, pass(map) :: loading
10881089
procedure(map_entry), deferred, pass(map) :: map_entry
10891090
procedure(rehash_map), deferred, pass(map) :: rehash
10901091
procedure(remove_entry), deferred, pass(map) :: remove
10911092
procedure(set_other), deferred, pass(map) :: set_other_data
10921093
procedure(total_depth), deferred, pass(map) :: total_depth
1093-
procedure(valid_key), deferred, pass(map) :: valid_key
10941094
end type hashmap_type
10951095
```
10961096

@@ -1173,13 +1173,13 @@ as follows:
11731173
contains
11741174
procedure :: get_other_data => get_other_chaining_data
11751175
procedure :: init => init_chaining_map
1176+
procedure :: key => chaining_key_test
11761177
procedure :: loading => chaining_loading
11771178
procedure :: map_entry => map_chain_entry
11781179
procedure :: rehash => rehash_chaining_map
11791180
procedure :: remove => remove_chaining_entry
11801181
procedure :: set_other_data => set_other_chaining_data
11811182
procedure :: total_depth => total_chaining_depth
1182-
procedure :: valid_key => valid_chaining_key
11831183
final :: free_chaining_map
11841184
end type chaining_hashmap_type
11851185
```
@@ -1244,13 +1244,13 @@ as follows:
12441244
contains
12451245
procedure :: get_other_data => get_other_open_data
12461246
procedure :: init => init_open_map
1247+
procedure :: key_test => open_key_test
12471248
procedure :: loading => open_loading
12481249
procedure :: map_entry => map_open_entry
12491250
procedure :: rehash => rehash_open_map
12501251
procedure :: remove => remove_open_entry
12511252
procedure :: set_other_data => set_other_open_data
12521253
procedure :: total_depth => total_open_depth
1253-
procedure :: valid_key => valid_open_key
12541254
final :: free_open_map
12551255
end type open_hashmap_type
12561256
```
@@ -1290,8 +1290,8 @@ Procedures to report the content of a map:
12901290
* `map 5 get_other_data( key, other, exists )` - Returns the other data
12911291
associated with the `key`;
12921292

1293-
* `map % valid_key( key)` - Returns a flag indicating whether the `key`
1294-
is present in the map.
1293+
* `map % key_test( key, present)` - Returns a flag indicating whether
1294+
the `key` is present in the map.
12951295

12961296
Procedures to report on the structure of the map:
12971297

@@ -1428,9 +1428,9 @@ Subroutine
14281428

14291429
##### Arguments
14301430

1431-
`map` (pass): shall be a scalar expression of class
1431+
`map` (pass): shall be a scalar variable of class
14321432
`chaining_hashmap_type` or `open_hashmap_type`. It is an
1433-
`intent(in)` argument. It will be
1433+
`intent(inout)` argument. It will be
14341434
the hash map used to store and access the other data.
14351435

14361436
`key`: shall be a scalar expression of type `key_type`. It
@@ -1557,6 +1557,60 @@ has the value `alloc_fault`.
15571557
```
15581558

15591559

1560+
#### `key_test` - indicates whether `key` is present
1561+
1562+
##### Status
1563+
1564+
Experimental
1565+
1566+
##### Description
1567+
1568+
Returns a logical flag indicating whether `key` is present for an
1569+
entry in the map.
1570+
1571+
##### Syntax
1572+
1573+
`result = call [[stdlib_hashmaps:map % valid_key]]( key, present )`
1574+
1575+
##### Class
1576+
1577+
Subroutine.
1578+
1579+
##### Arguments
1580+
1581+
`map` (pass): shall be a scalar variable of class
1582+
`chaining_hashmap_type` or `open_hashmap_type`.
1583+
It is an `intent(inout)` argument. It is the hash map whose entries
1584+
are examined.
1585+
1586+
`key`: shall be a scalar expression of type `key_type`. It
1587+
is an `intent(in)` argument. It is a `key` whose presence in the `map`
1588+
is being examined.
1589+
1590+
`present` (optional): shall be a scalar variable of type default
1591+
`logical`. It is an intent(out) argument. It is a logical flag where
1592+
`.true.` indicates that an entry with that `key` is present in the
1593+
`map` and `.false.` indicates that no such entry is present.
1594+
1595+
##### Example
1596+
1597+
```fortran
1598+
program demo_key_test
1599+
use stdlib_kinds, only: int8
1600+
use stdlib_hashmaps, only: chaining_hashmap_type
1601+
use stdlib_hashmap_wrappers, only: fnv_1_hasher, key_type
1602+
implicit none
1603+
type(chaining_hashmap_type) :: map
1604+
type(key_type) :: key
1605+
logocal :: present
1606+
call map % init( fnv_1_hasher )
1607+
call set_key(key, [0_int8, 1_int8] )
1608+
call map % key_test ( key, present )
1609+
print *, "Initial key of 10 present for empty map = ", present
1610+
end program demo_key_test
1611+
```
1612+
1613+
15601614
#### `loading` - Returns the ratio of entries to slots
15611615

15621616
##### Status
@@ -1845,9 +1899,9 @@ to be removed.
18451899

18461900
`existed` (optional): shall be a scalar variable of type default
18471901
logical. It is an `intent(out)` argument. If present with the value
1848-
`.true.` the entry existed
1849-
in the map before removal, if `.false.` the entry was not present to be
1850-
removed and the map is unchanged.
1902+
`.true.` the entry existed in the map before removal, if `.false.` the
1903+
entry was not present to be removed and the map is unchanged. If
1904+
absent, the procedure returns with no entry with the given key.
18511905

18521906
##### Example
18531907

@@ -2032,61 +2086,3 @@ from their slot index the map.
20322086
print *, "Initial total depth = ", initial_depth
20332087
end program demo_total_depth
20342088
```
2035-
2036-
2037-
#### `valid_key` - indicates whether `key` is present
2038-
2039-
##### Status
2040-
2041-
Experimental
2042-
2043-
##### Description
2044-
2045-
Returns a logical flag indicating whether `key` exists for an entry in
2046-
the map.
2047-
2048-
##### Syntax
2049-
2050-
`result = [[stdlib_hashmaps:map % valid_key]]( key )`
2051-
2052-
##### Class
2053-
2054-
Pure function.
2055-
2056-
##### Arguments
2057-
2058-
`map` (pass): shall be a scalar expression of class
2059-
`chaining_hashmap_type` or `open_hashmap_type`.
2060-
It is an `intent(in)` argument. It is the hash map whose entries are
2061-
examined.
2062-
2063-
`key`: shall be a scalar expression a of type `key_type`. It
2064-
is an `intent(in)` argument. It is a `key` whose presence in the `map`
2065-
is being examined.
2066-
2067-
##### Result character
2068-
2069-
The result is a default logical scalar.
2070-
2071-
##### Result value
2072-
2073-
The result is `.true.` if `key` is present in `map` and `.false.`
2074-
otherwise.
2075-
2076-
##### Example
2077-
2078-
```fortran
2079-
program demo_valid_key
2080-
use stdlib_kinds, only: int8
2081-
use stdlib_hashmaps, only: chaining_hashmap_type
2082-
use stdlib_hashmap_wrappers, only: fnv_1_hasher, key_type
2083-
implicit none
2084-
type(chaining_hashmap_type) :: map
2085-
type(key_type) :: key
2086-
logocal :: valid
2087-
call map % init( fnv_1_hasher )
2088-
call set_key(key, [0_int8, 1_int8] )
2089-
valid = map % valid_key ( key )
2090-
print *, "Initial key of 10 valid for empty map = ", valid
2091-
end program demo_valid_index
2092-
```

0 commit comments

Comments
 (0)