110 lines
3.0 KiB
Markdown
110 lines
3.0 KiB
Markdown
|
# map
|
||
|
|
A type-safe generic hashmap implementation for C.
|
||
|
|
|
||
|
|
## Installation
|
||
|
|
The [map.c](src/map.c?raw=1) and [map.h](src/map.h?raw=1) files can be dropped
|
||
|
|
into an existing C project and compiled along with it.
|
||
|
|
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
Before using a map it should first be initialised using the `map_init()`
|
||
|
|
function.
|
||
|
|
```c
|
||
|
|
map_int_t m;
|
||
|
|
map_init(&m);
|
||
|
|
```
|
||
|
|
|
||
|
|
Values can added to a map using the `map_set()` function.
|
||
|
|
```c
|
||
|
|
map_set(&m, "testkey", 123);
|
||
|
|
```
|
||
|
|
|
||
|
|
To retrieve a value from a map, the `map_get()` function can be used.
|
||
|
|
`map_get()` will return a pointer to the key's value, or `NULL` if no mapping
|
||
|
|
for that key exists.
|
||
|
|
```c
|
||
|
|
int *val = map_get(&m, "testkey");
|
||
|
|
if (val) {
|
||
|
|
printf("value: %d\n", *val);
|
||
|
|
} else {
|
||
|
|
printf("value not found\n");
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
When you are done with a map the `map_deinit()` function should be called on
|
||
|
|
it. This will free any memory the map allocated during use.
|
||
|
|
```c
|
||
|
|
map_deinit(&m);
|
||
|
|
```
|
||
|
|
|
||
|
|
|
||
|
|
## Types
|
||
|
|
map.h provides the following predefined map types:
|
||
|
|
|
||
|
|
Contained Type | Type name
|
||
|
|
----------------|----------------------------------
|
||
|
|
void* | map_void_t
|
||
|
|
char* | map_str_t
|
||
|
|
int | map_int_t
|
||
|
|
char | map_char_t
|
||
|
|
float | map_float_t
|
||
|
|
double | map_double_t
|
||
|
|
|
||
|
|
To define a new map type the `map_t()` macro should be used:
|
||
|
|
```c
|
||
|
|
/* Creates the type uint_map_t for storing unsigned ints */
|
||
|
|
typedef map_t(unsigned int) uint_map_t;
|
||
|
|
```
|
||
|
|
|
||
|
|
## Functions
|
||
|
|
All map functions are macro functions. The parameter `m` in each function
|
||
|
|
should be a pointer to the map struct which the operation is to be performed
|
||
|
|
on. The `key` parameter should always be a string value.
|
||
|
|
|
||
|
|
### map\_t(T)
|
||
|
|
Creates a map struct for containing values of type `T`.
|
||
|
|
```c
|
||
|
|
/* Typedefs the struct `fp_map_t` as a container for type FILE* */
|
||
|
|
typedef map_t(FILE*) fp_map_t;
|
||
|
|
```
|
||
|
|
|
||
|
|
### map\_init(m)
|
||
|
|
Initialises the map, this must be called before the map can be used.
|
||
|
|
|
||
|
|
### map\_deinit(m)
|
||
|
|
Deinitialises the map, freeing the memory the map allocated during use;
|
||
|
|
this should be called when we're finished with a map.
|
||
|
|
|
||
|
|
### map\_get(m, key)
|
||
|
|
Returns a pointer to the value of the given `key`. If no mapping for the `key`
|
||
|
|
exists then `NULL` will be returned.
|
||
|
|
|
||
|
|
### map\_set(m, key, value)
|
||
|
|
Sets the given `key` to the given `value`. Returns `0` on success, otherwise
|
||
|
|
`-1` is returned and the map remains unchanged.
|
||
|
|
|
||
|
|
### map\_remove(m, key)
|
||
|
|
Removes the mapping of the given `key` from the map. If the `key` does not
|
||
|
|
exist in the map then the function has no effect.
|
||
|
|
|
||
|
|
### map\_iter(m)
|
||
|
|
Returns a `map_iter_t` which can be used with `map_next()` to iterate all the
|
||
|
|
keys in the map.
|
||
|
|
|
||
|
|
### map\_next(m, iter)
|
||
|
|
Uses the `map_iter_t` returned by `map_iter()` to iterate all the keys in the
|
||
|
|
map. `map_next()` returns a key with each call and returns `NULL` when there
|
||
|
|
are no more keys.
|
||
|
|
```c
|
||
|
|
const char *key;
|
||
|
|
map_iter_t iter = map_iter(&m);
|
||
|
|
|
||
|
|
while ((key = map_next(&m, &iter))) {
|
||
|
|
printf("%s -> %d", key, *map_get(&m, key));
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## License
|
||
|
|
This library is free software; you can redistribute it and/or modify it under
|
||
|
|
the terms of the MIT license. See [LICENSE](LICENSE) for details.
|