NAME

MAP, MAP_INIT, MAP_FREE, MAP_INSERT, MAP_INSERT_N, MAP_INSERT_VALUE, MAP_KEY, MAP_FIND, MAP_REMOVE, MAP_ITERATOR, MAP_ITERATE — key value structure

SYNOPSIS

#include <libks/map.h>

struct map *
MAP(key_type, key_ptr, val_type);

int
MAP_INIT(struct map *m);

void
MAP_FREE(struct map *m);

val_type *
MAP_INSERT(struct map *m, key_type key);

val_type *
MAP_INSERT_N(struct map *m, key_type key, size_t key_size);

val_type *
MAP_INSERT_VALUE(struct map *m, key_type key, val_type val);

const key_type *
MAP_KEY(struct map *m, val_type *val);

val_type *
MAP_FIND(struct map *m, key_type key);

val_type *
MAP_FIND_N(struct map *m, key_type key, size_t key_size);

void
MAP_REMOVE(struct map *m, key_type key);

MAP_ITERATOR(struct map *m);

int
MAP_ITERATE(struct map *m, MAP_ITERATOR *it);

DESCRIPTION

The map structure associates keys with values.

The MAP() macro declares a new map which maps key_type to val_type. The key_ptr argument must be used to denote if key_type is a pointer and thus the only recognized value is ‘*’. As key_ptr is optional, it must be omitted if key_type is not a pointer. For any non pointer key type, the map will store a copy of each inserted key. If key_type key_ptr is equal to const char * or char *, the map will store a copy of each inserted string. For any other key pointer type, the caller is responsible for guaranteeing that an inserted key pointer remains valid through the lifetime of the map.

The MAP_INIT() function initializes a map. This function must be called before making use of the map.

The MAP_FREE() function frees all memory associated with the map. If the given pointer is NULL, nothing is done. If each inserted value requires handling before being freed, consider using MAP_ITERATE() and MAP_REMOVE() before calling MAP_FREE().

The MAP_INSERT() function inserts key into the map and returns a pointer to the corresponding value in which the underlying memory is zero initialized.

The MAP_INSERT_N() function act as MAP_INSERT() but allows the length of the key to specified. Indented to be used to insert string keys lacking NUL-terminators.

The MAP_INSERT_VALUE() function act as MAP_INSERT() but initializes the corresponding value with val.

The MAP_KEY() function returns a pointer to the key associated with val. Primarly intended to be used with string keys, allowing each inserted value to access its corresponding key.

The MAP_FIND() function returns the corresponding value for key. If key is not present in the map, NULL is returned.

The MAP_FIND_N() function behaves like MAP_FIND() but allows the length of the key to specified. Indented to be used to lookup string keys lacking NUL-terminators.

The MAP_REMOVE() function removes the value associated with key.

The MAP_ITERATE() function iterates over all elements in insertion order. Once all elements have been iterated over, zero is returned. The current element can be accessed through it which must be declared using MAP_ITERATOR() and zero initialized upon the first invocation. The MAP_ITERATOR() structure is defined as:

struct {
	key_type  key;
	val_type *val;
};

RETURN VALUES

The MAP_INIT() returns zero on success. Otherwise, non-zero is returned and errno is set accordingly.

The MAP_INSERT() and MAP_INSERT_VALUE() returns NULL on error and sets errno accordingly.

EXAMPLES

The following example demonstrates usage of a map with non pointer keys.

MAP(int,, int) m;

if (MAP_INIT(m))
	err(1, NULL);

for (int = 0; i < 100; i++) {
	if (MAP_INSERT_VALUE(m, i, i))
		err(1, NULL);
}

MAP_FREE(m);

The following example demonstrates usage of a map with string keys.

struct record {
	int id;
	char *name;
};

MAP(const char, *, struct record) m;

if (MAP_INIT(m))
	err(1, NULL);

for (int = 0; i < 100; i++) {
	char buf[128];
	struct record *r;

	snprintf(buf, sizeof(buf), "r%d", i);
	r = MAP_INSERT(m, buf);
	if (r == NULL)
		err(1, NULL);
	r->id = i;
	r->name = MAP_KEY(m, r);
}

MAP_ITERATOR(m) it = {0};
while (MAP_ITERATE(m, &it))
	MAP_REMOVE(r, it.key);

MAP_FREE(m);

AUTHORS

Anton Lindqvist <anton@basename.se>