map.h File Reference

#include "_bk_defines.h"

Include dependency graph for map.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef struct internal_map *	map

Functions
map	map_init (size_t key_size, size_t value_size, int(*comparator)(const void *const one, const void *const two))
size_t	map_size (map me)
bk_bool	map_is_empty (map me)
bk_err	map_put (map me, void *key, void *value)
bk_bool	map_get (void *value, map me, void *key)
bk_bool	map_contains (map me, void *key)
bk_bool	map_remove (map me, void *key)
void *	map_first (map me)
void *	map_last (map me)
void *	map_lower (map me, void *key)
void *	map_higher (map me, void *key)
void *	map_floor (map me, void *key)
void *	map_ceiling (map me, void *key)
void	map_clear (map me)
map	map_destroy (map me)

Typedef Documentation

map

typedef struct internal_map* map

The map data structure, which is a collection of key-value pairs, sorted by keys, keys are unique.

Function Documentation

map_ceiling()

void* map_ceiling	(	map	me,
		void *const	key
	)

Returns the key which is the ceiling of the comparison key. Meaning that the the lowest key which is higher or equal to the key used for comparison is returned.

Parameters

me	the map to get the ceiling key from
key	the key to use for comparison

Returns

the key which is the ceiling, or NULL if it does not exist

map_clear()

void map_clear

(

map

me

)

Clears the key-value pairs from the map.

Parameters

me	the map to clear

map_contains()

bk_bool map_contains	(	map	me,
		void *const	key
	)

Determines if the map contains the specified key. The pointer to the key being passed in should point to the key type which this map holds. For example, if this map holds key integers, the key pointer should be a pointer to an integer. Since the key is being copied, the pointer only has to be valid when this function is called.

Parameters

me	the map to check for the element
key	the key to check

Returns

BK_TRUE if the map contained the element, otherwise BK_FALSE

map_destroy()

map map_destroy

(

map

me

)

Frees the map memory. Performing further operations after calling this function results in undefined behavior. Freeing NULL is legal, and causes no operation to be performed.

Parameters

me	the map to free from memory

Returns

NULL

map_first()

void* map_first

(

map

me

)

Returns the first (lowest) key in this map. The returned key is a pointer to the internally stored key, which should not be modified. Modifying it results in undefined behaviour.

Parameters

me	the map to get the key from

Returns

the lowest key in this map, or NULL if it is empty

map_floor()

void* map_floor	(	map	me,
		void *const	key
	)

Returns the key which is the floor of the comparison key. Meaning that the the highest key which is lower or equal to the key used for comparison is returned.

Parameters

me	the map to get the floor key from
key	the key to use for comparison

Returns

the key which is the floor, or NULL if it does not exist

map_get()

bk_bool map_get	(	void *const	value,
		map	me,
		void *const	key
	)

Gets the value associated with a key in the map. The pointer to the key being passed in and the value being obtained should point to the key and value types which this map holds. For example, if this map holds integer keys and values, the key and value pointers should be a pointer to an integer. Since the key and value are being copied, the pointer only has to be valid when this function is called.

Parameters

value	the value to copy to
me	the map to get from
key	the key to search for

Returns

BK_TRUE if the map contained the key-value pair, otherwise BK_FALSE

map_higher()

void* map_higher	(	map	me,
		void *const	key
	)

Returns the key which is strictly higher than the comparison key. Meaning that the lowest key which is higher than the key used for comparison is returned.

Parameters

me	the map to get the higher key from
key	the key to use for comparison

Returns

the key which is strictly higher, or NULL if it does not exist

map_init()

map map_init	(	size_t	key_size,
		size_t	value_size,
		int(*)(const void *const one, const void *const two)	comparator
	)

map_is_empty()

bk_bool map_is_empty

(

map

me

)

Determines whether or not the map is empty.

Parameters

me	the map to check

Returns

BK_TRUE if the map is empty, otherwise BK_FALSE

map_last()

void* map_last

(

map

me

)

Returns the last (highest) key in this map. The returned key is a pointer to the internally stored key, which should not be modified. Modifying it results in undefined behaviour.

Parameters

me	the map to get the key from

Returns

the highest key in this map, or NULL if it is empty

map_lower()

void* map_lower	(	map	me,
		void *const	key
	)

Returns the key which is strictly lower than the comparison key. Meaning that the highest key which is lower than the key used for comparison is returned.

Parameters

me	the map to get the lower key from
key	the key to use for comparison

Returns

the key which is strictly lower, or NULL if it does not exist

map_put()

bk_err map_put	(	map	me,
		void *const	key,
		void *const	value
	)

Adds a key-value pair to the map. If the map already contains the key, the value is updated to the new value. The pointer to the key and value being passed in should point to the key and value type which this map holds. For example, if this map holds integer keys and values, the key and value pointer should be a pointer to an integer. Since the key and value are being copied, the pointer only has to be valid when this function is called.

Parameters

me	the map to add to
key	the key to add
value	the value to add

Returns

BK_OK if no error

-BK_ENOMEM if out of memory

map_remove()

bk_bool map_remove	(	map	me,
		void *const	key
	)

Removes the key-value pair from the map if it contains it. The pointer to the key being passed in should point to the key type which this map holds. For example, if this map holds key integers, the key pointer should be a pointer to an integer. Since the key is being copied, the pointer only has to be valid when this function is called.

Parameters

me	the map to remove an element from
key	the key to remove

Returns

BK_TRUE if the map contained the key-value pair, otherwise BK_FALSE

map_size()

size_t map_size

(

map

me

)

Gets the size of the map.

Parameters

me	the map to check

Returns

the size of the map