# Map Words

Maps in zeptoforth are implemented as fixed-sized hash tables. They have fixed-sized keys and values; it is recommended that these be either addresses or indices into some other data structure, for sake of economy of space. For the sake of alignment, the amount of space taken up by a key and a value together is internally rounded up to the nearest cell.

### `map`

The following words are in `map`:

##### `map-size`
( count key-size value-size -- map-bytes )

Get the size in bytes of a map with an entry count *count*, a key size *key-size* in bytes, and a value size *value-size* in bytes.

##### `init-map`
( hash-xt equals-xt remove-xt count key-size value-size addr -- )

Initialize a map at *addr* with a key size *key-size* in bytes, a value size *value-size* in bytes, an entry count *count*, an entry removal handler *remove-xt* with the signature ( value-addr key-addr -- ) which can be 0, an equals function *equals-xt* with the signature ( key-addr key-addr -- equals? ), and a hash function *hash-xt* with the signature ( key-addr -- hash ).

##### `find-map`
( key-addr map -- value-addr | 0 )

Find a the value of a key at *key-addr* in a map *map* and return the address of its value *value-addr*, or if the key is not found, return 0.

##### `insert-map`
( value-addr key-addr map -- )

Insert a value at *value-addr* at the key at *key-addr* in a map *map*. If the key is already present in the map, call the entry removal handler for the key and value already in the map (if set) and then replace the key and value in the map with those provided. If the key is not already present in the map and there is room for another entry in the map, add the value to the map at the specified key, otherwise raise `x-map-full`.

##### `remove-map`
( key-addr map -- )

Remove a value with a key at *key-addr* from a map *map* if it is present; if this is the case, first call the entry removal handler for the key and value already in the map (if set).

##### `first-map`
( map -- index | -1 )

Get the index *index* of the first entry in a map *map* or return -1 if the map is empty.

##### `next-map`
( index map -- index' | -1 )

Get the next index *index'* of an entry in a map *map* after the entry at the index *index*; if there is no following entry, return -1.

##### `at-map`
( index map -- value-addr key-addr )

Get the value and key at *value-addr* and *key-addr* of the entry in map *map* at index *index*; if *index* is out of range, raise `x-map-index-out-of-range`, and if *index* does not correspond to a valid entry, raise `x-map-index-no-entry`.

##### `clear-map`
( map -- )

Clear map *map* of all entries, calling the entry removal handler for each cleared entry if set.

##### `copy-map`
( src-map dest-map -- )

Copy each entry in the source map *src-map* into the destination map *dest-map*, overwriting existing entries with identical keys (and calling the entry removal handler for them, if set for the destination map). If insufficient room is available to copy further entries into the destination map, `x-map-full` is raised. If the key size, value size, hash function, or equals function differ between the two maps, `x-dest-map-not-match` is raised.

##### `map-entry-count`
( map -- entry-count )

Get the total entry count of a map *map*.

##### `map-used-entry-count`
( map -- used-entry-count )

Get the used entry count of a map *map*.

##### `map-key-size`
( map -- key-size )

Get the key size in bytes of a map *map*.

##### `map-value-size`
( map -- value-size )

Get the value size in bytes of a map *map*.

##### `map-hash-xt`
( map -- hash-xt )

Get the hash function of a map *map*.

##### `map-equals-xt`
( map -- equals-xt )

Get the equals function of a map *map*.

##### `map-remove-xt` )
( map -- remove-xt )

Get the entry removal handler of a map *map*.

##### `x-map-full`
( -- )

Map is full exception.

##### `x-map-index-out-of-range`
( -- )

Map index is out of range exception.

##### `x-map-index-no-entry`
( -- )

Map index has no entry exception.

##### `x-dest-map-not-match`
( -- )

Destination map does not match source map with regard to key size, value size, hash function, or equals function exception.

## Counted String Maps

Counted string maps are a subset of maps that have keys that are implemented as counted strings allocated (aside from an address) outside of the map data structure.

### `cstr-map`

The following words are in `cstr-map`:

##### `cstr-map-size`
( count value-size -- map-bytes )

Get the size in bytes of a counted string map with an entry count *count* and a value size *value-size* in bytes.

##### `init-cstr-map`
( hash-xt equals-xt remove-xt count key-size value-size addr -- )

Initialize a counted string map at *addr* with a value size *value-size* in bytes, an entry count *count*, and an entry removal handler *remove-xt* with the signature ( value-addr key-addr -- ) which can be 0.

##### `find-cstr-map`
( key-cstr cstr-map -- value-addr | 0 )

Find a the value of a counted string key *key-cstr* in a counted string map *cstr-map* and return the address of its value *value-addr*, or if the key is not found, return 0.

##### `insert-cstr-map`
( value-addr key-cstr cstr-map -- )

Insert a value at *value-addr* at the counted string key *key-cstr* in a counted string map *cstr-map*. If the key is already present in the map, call the entry removal handler for the key and value already in the map (if set) and then replace the key and value in the map with those provided. If the key is not already present in the map and there is room for another entry in the map, add the value to the map at the specified key, otherwise raise `x-map-full`.

##### `remove-cstr-map`
( key-cstr cstr-map -- )

Remove a value with a counted string key *key-cstr* from a counted string map *cstr-map* if it is present; if this is the case, first call the entry removal handler for the key and value already in the map (if set).

##### `at-cstr-map`
( index cstr-map -- value-addr key-cstr )

Get the value at *value-addr* and counted string key *key-cstr* of the entry in a counted string map *cstr-map* at index *index*; if *index* is out of range, raise `x-map-index-out-of-range`, and if *index* does not correspond to a valid entry, raise `x-map-index-no-entry`.

## Integer Maps

Integer maps are a subset of maps that have keys that are cell-sized integers.

### `int-map`

The following words are in `int-map`:

##### `int-map-size`
( count value-size -- map-bytes )

Get the size in bytes of a integer map with an entry count *count* and a value size *value-size* in bytes.

##### `init-int-map`
( hash-xt equals-xt remove-xt count key-size value-size addr -- )

Initialize a integer map at *addr* with a value size *value-size* in bytes, an entry count *count*, and an entry removal handler *remove-xt* with the signature ( value-addr key-addr -- ) which can be 0.

##### `find-int-map`
( key-int int-map -- value-addr | 0 )

Find a the value of a integer key *key-int* in a map *int-map* and return the address of its value *value-addr*, or if the key is not found, return 0.

##### `insert-int-map`
( value-addr key-int int-map -- )

Insert a value at *value-addr* at the integer key *key-int* in an integer map *int-map*. If the key is already present in the map, call the entry removal handler for the key and value already in the map (if set) and then replace the key and value in the map with those provided. If the key is not already present in the map and there is room for another entry in the map, add the value to the map at the specified key, otherwise raise `x-map-full`.

##### `remove-int-map`
( key-int int-map -- )

Remove a value with a integer key *key-int* from an integer map *int-map* if it is present; if this is the case, first call the entry removal handler for the key and value already in the map (if set).

##### `at-int-map`
( index int-map -- value-addr key-int )

Get the value at *value-addr* and integer key *key-int* of the entry in an integer map *int-map* at index *index*; if *index* is out of range, raise `x-map-index-out-of-range`, and if *index* does not correspond to a valid entry, raise `x-map-index-no-entry`.