# `./fio-stl/210 map.h`

30 public symbols.

### Macros

#### `FIO_MAP_INIT`

```c
#define FIO_MAP_INIT   \
  { 0 }
```



_Symbol type:_ `macro`

#### `FIO_MAP_EACH`

```c
#define FIO_MAP_EACH(map_name, map_ptr, i)   \
  for (FIO_NAME(map_name, iterator_s)   \
           i = FIO_NAME(map_name, get_next)(map_ptr, NULL);   \
       FIO_NAME(map_name, iterator_is_valid)(&i);   \
       i = FIO_NAME(map_name, get_next)(map_ptr, &i))
```

Iterates through the map using an iterator object.

_Symbol type:_ `macro`

#### `FIO_MAP_EACH_REVERSED`

```c
#define FIO_MAP_EACH_REVERSED(map_name, map_ptr, i)   \
  for (FIO_NAME(map_name, iterator_s)   \
           i = FIO_NAME(map_name, get_prev)(map_ptr, NULL);   \
       FIO_NAME(map_name, iterator_is_valid)(&i);   \
       i = FIO_NAME(map_name, get_prev)(map_ptr, &i))
```

Iterates through the map using an iterator object.

_Symbol type:_ `macro`

### Types

#### `fiobj_hash_node_s`

```c
struct fiobj_hash_node_s
```

internal object data representation

_Symbol type:_ `type`

#### `fiobj_hash_s`

```c
struct fiobj_hash_s {
uint32_t bits;
uint32_t count;
FIO_NAME(FIO_MAP_NAME, node_s) * map;
#if FIO_MAP_ORDERED
FIO_INDEXED_LIST32_HEAD head;
#endif
}
```

A Hash Map / Set type

_Symbol type:_ `type`

#### `fiobj_hash_iterator_s`

```c
typedef struct {
/** the node in the internal map */
fiobj_hash_iterator_s * node;
/** the key in the current position */
FIO_MAP_KEY key;
#ifdef FIO_MAP_VALUE
/** the value in the current position */
FIO_MAP_VALUE value;
#endif
#if !FIO_MAP_RECALC_HASH
/** the hash for the current position */
uint64_t hash;
#endif
struct { /* internal usage, do not access */
uint32_t index; /* the index in the internal map */
uint32_t pos; /* the position in the ordering scheme */
uintptr_t map_validator; /* map mutation guard */
} private_;
} fiobj_hash_iterator_s
```

Map iterator type

_Symbol type:_ `type`

#### `fiobj_hash_each_s`

```c
struct fiobj_hash_each_s {
/** The being iterated. Once set, cannot be safely changed. */
FIO_MAP_PTR const parent;
/** The current object's index */
uint64_t index;
/** The callback / task called for each index, may be updated mid-cycle. */
int (*task)(struct FIO_NAME(FIO_MAP_NAME, each_s) * info);
/** Opaque user data. */
void *udata;
#ifdef FIO_MAP_VALUE
/** The object's value at the current index. */
FIO_MAP_VALUE value;
#endif
/** The object's key the current index. */
FIO_MAP_KEY key;
}
```

Iteration information structure passed to the callback.

_Symbol type:_ `type`

### Functions

#### `fiobj_hash_destroy`

```c
void fiobj_hash_destroy(FIO_MAP_PTR map)
```

Destroys the object, re-initializing its container.

_Symbol type:_ `function`

#### `fiobj_hash_capa`

```c
inline uint32_t fiobj_hash_capa(FIO_MAP_PTR map)
```

Theoretical map capacity.

_Symbol type:_ `function`

#### `fiobj_hash_count`

```c
inline uint32_t fiobj_hash_count(FIO_MAP_PTR map)
```

The number of objects in the map capacity.

_Symbol type:_ `function`

#### `fiobj_hash_reserve`

```c
void fiobj_hash_reserve(FIO_MAP_PTR map, size_t capa)
```

Reserves at minimum the capacity requested.

_Symbol type:_ `function`

#### `fiobj_hash_node2key`

```c
inline FIO_MAP_KEY fiobj_hash_node2key(FIO_NAME(FIO_MAP_NAME, node_s) * node)
```

Returns the key value associated with the node's pointer (see set_ptr).

_Symbol type:_ `function`

#### `fiobj_hash_node2hash`

```c
inline uint64_t fiobj_hash_node2hash(FIO_NAME(FIO_MAP_NAME, node_s) * node)
```

Returns the hash value associated with the node's pointer (see set_ptr).

_Symbol type:_ `function`

#### `fiobj_hash_node2val`

```c
inline FIO_MAP_VALUE fiobj_hash_node2val(FIO_NAME(FIO_MAP_NAME, node_s) * node)
```

Returns the value associated with the node's pointer (see set_ptr).

_Symbol type:_ `function`

#### `fiobj_hash_node2key_ptr`

```c
inline FIO_MAP_KEY_INTERNAL *fiobj_hash_node2key_ptr( FIO_NAME(FIO_MAP_NAME, node_s) * node)
```

Returns the key value associated with the node's pointer (see set_ptr).

_Symbol type:_ `function`

#### `fiobj_hash_node2val_ptr`

```c
inline FIO_MAP_VALUE_INTERNAL *fiobj_hash_node2val_ptr( FIO_NAME(FIO_MAP_NAME, node_s) * node)
```

Returns the value associated with the node's pointer (see set_ptr).

_Symbol type:_ `function`

#### `fiobj_hash_remove`

```c
int fiobj_hash_remove(FIO_MAP_PTR map, #if !defined(FIO_MAP_HASH_FN) uint64_t hash, #endif FIO_MAP_KEY key, #if defined(FIO_MAP_VALUE) FIO_MAP_VALUE_INTERNAL *old #else FIO_MAP_KEY_INTERNAL *old #endif )
```

Removes an object in the map, returning a pointer to the map data.

_Symbol type:_ `function`

#### `fiobj_hash_evict`

```c
void fiobj_hash_evict(FIO_MAP_PTR map, size_t number_of_elements)
```

Evicts elements in order least recently used (LRU), FIFO or undefined.

_Symbol type:_ `function`

#### `fiobj_hash_clear`

```c
void fiobj_hash_clear(FIO_MAP_PTR map)
```

Removes all objects from the map, without releasing the map's resources.

_Symbol type:_ `function`

#### `fiobj_hash_compact`

```c
void fiobj_hash_compact(FIO_MAP_PTR map)
```

Attempts to minimize memory use.

_Symbol type:_ `function`

#### `fiobj_hash_get`

```c
inline FIO_MAP_GET_T fiobj_hash_get(FIO_MAP_PTR map, #if !defined(FIO_MAP_HASH_FN) uint64_t hash, #endif FIO_MAP_KEY key)
```

Gets a value from the map, if exists.

_Symbol type:_ `function`

#### `fiobj_hash_set`

```c
inline FIO_MAP_GET_T fiobj_hash_set(FIO_MAP_PTR map, #if !defined(FIO_MAP_HASH_FN) uint64_t hash, #endif #ifdef FIO_MAP_VALUE FIO_MAP_KEY key, FIO_MAP_VALUE obj, FIO_MAP_VALUE_INTERNAL *old #else FIO_MAP_KEY key #endif )
```

Sets a value in the map, hash maps will overwrite existing data if any.

_Symbol type:_ `function`

#### `fiobj_hash_set_if_missing`

```c
inline FIO_MAP_GET_T fiobj_hash_set_if_missing(FIO_MAP_PTR map, #if !defined(FIO_MAP_HASH_FN) uint64_t hash, #endif FIO_MAP_KEY key #ifdef FIO_MAP_VALUE , FIO_MAP_VALUE obj #endif )
```

Sets a value in the map if not set previously.

_Symbol type:_ `function`

#### `fiobj_hash_set_ptr`

```c
fiobj_hash_set_ptr * FIO_NAME(FIO_MAP_NAME, set_ptr)(FIO_MAP_PTR map, #if !defined(FIO_MAP_HASH_FN) uint64_t hash, #endif #ifdef FIO_MAP_VALUE FIO_MAP_KEY key, FIO_MAP_VALUE val, FIO_MAP_VALUE_INTERNAL *old, int overwrite #else FIO_MAP_KEY key #endif )
```

The core set function.

This function returns `NULL` on error (errors are logged).

If the map is a hash map, overwriting the value (while keeping the key) is
possible. In this case the `old` pointer is optional, and if set than the old
data will be copied to over during an overwrite.

NOTE: the function returns a pointer to the map's internal storage.

_Symbol type:_ `function`

#### `fiobj_hash_get_ptr`

```c
fiobj_hash_get_ptr * FIO_NAME(FIO_MAP_NAME, get_ptr)(FIO_MAP_PTR map, #if !defined(FIO_MAP_HASH_FN) uint64_t hash, #endif FIO_MAP_KEY key)
```

The core get function. This function returns NULL if item is missing.

NOTE: the function returns a pointer to the map's internal storage.

_Symbol type:_ `function`

#### `fiobj_hash_each`

```c
uint32_t fiobj_hash_each(FIO_MAP_PTR map, int (*task)(FIO_NAME(FIO_MAP_NAME, each_s) *), void *udata, ssize_t start_at)
```

Iteration using a callback for each element in the map.

The callback task function must accept an each_s pointer, see above.

If the callback returns -1, the loop is broken. Any other value is ignored.

Returns the relative "stop" position, i.e., the number of items processed +
the starting point.

_Symbol type:_ `function`

#### `fiobj_hash_get_next`

```c
fiobj_hash_get_next FIO_NAME(FIO_MAP_NAME, get_next)(FIO_MAP_PTR map, FIO_NAME(FIO_MAP_NAME, iterator_s) * current_pos)
```

Returns the next iterator object after `current_pos` or the first if `NULL`.

Note that adding objects to the map or rehashing between iterations could
incur performance penalties when re-setting and re-seeking the previous
iterator position.

Adding objects to, or rehashing, an unordered maps could invalidate the
iterator object completely as the ordering may have changed and so the "next"
object might be any object in the map.

_Symbol type:_ `function`

#### `fiobj_hash_get_prev`

```c
fiobj_hash_get_prev FIO_NAME(FIO_MAP_NAME, get_prev)(FIO_MAP_PTR map, FIO_NAME(FIO_MAP_NAME, iterator_s) * current_pos)
```

Returns the next iterator object after `current_pos` or the last if `NULL`.

See notes in `get_next`.

_Symbol type:_ `function`

#### `fiobj_hash_iterator_is_valid`

```c
inline int fiobj_hash_iterator_is_valid(FIO_NAME(FIO_MAP_NAME, iterator_s) * iterator)
```

Returns 1 if the iterator is out of bounds, otherwise returns 0.

_Symbol type:_ `function`

#### `fiobj_hash_iterator2node`

```c
inline fiobj_hash_iterator2node * FIO_NAME(FIO_MAP_NAME, iterator2node)(FIO_MAP_PTR map, FIO_NAME(FIO_MAP_NAME, iterator_s) * iterator)
```

Returns a pointer to the node object in the internal map.

_Symbol type:_ `function`

-----------------------------------------------------