Map

A container of key/value pairs with unique keys. More...

Data Structures
struct	cstl_map_t
	The map object. More...
struct	cstl_map_iterator_t
	A pointer to an element within the map. More...

Functions
void	cstl_map_init (cstl_map_t *map, cstl_compare_func_t *cmp, void *priv)
	Initialize a map.
static size_t	cstl_map_size (const cstl_map_t *const map)
	Return the number of elements in the map.
int	cstl_map_insert (cstl_map_t *map, const void *key, void *val, cstl_map_iterator_t *i)
	Insert a key/value pair into the map.
void	cstl_map_find (const cstl_map_t *map, const void *key, cstl_map_iterator_t *i)
	Find an element in the map with a matching key.
int	cstl_map_erase (cstl_map_t *map, const void *key, cstl_map_iterator_t *i)
	Erase the element with the supplied key from the map.
void	cstl_map_erase_iterator (cstl_map_t *map, cstl_map_iterator_t *i)
	Erase the element pointed to by the iterator.
void	cstl_map_clear (cstl_map_t *map, cstl_xtor_func_t *clr, void *priv)
	Remove all elements from the map.

Iterators
const cstl_map_iterator_t *	cstl_map_iterator_end (const cstl_map_t *map)
	Return an iterator that refers to the end of the map.
static bool	cstl_map_iterator_eq (const cstl_map_iterator_t *const a, const cstl_map_iterator_t *const b)
	Compare two iterators for equality.

Detailed Description

A container of key/value pairs with unique keys.

Function Documentation

cstl_map_clear()

void cstl_map_clear	(	cstl_map_t *	map,
		cstl_xtor_func_t *	clr,
		void *	priv
	)

Remove all elements from the map.

Parameters

[in]	map	A pointer to the map to be cleared
[in]	clr	A function to call for each element as it is removed
[in]	priv	A pointer to be passed to each invocation of clr

The first argument to the clr function will be an iterator containing pointers to the key and value associated with the removed element. It is undefined whether the element is still in the tree at the time that the clr function is called, and the callee must not do anything with the iterator except retrieve the key and value pointers.

Definition at line 102 of file map.c.

cstl_map_erase()

int cstl_map_erase	(	cstl_map_t *	map,
		const void *	key,
		cstl_map_iterator_t *	i
	)

Erase the element with the supplied key from the map.

Parameters

[in]	map	A pointer to the map in which to search for the key
[in]	key	A pointer to the key to be removed
[out]	i	A pointer to an iterator in which to return a pointer to the sought element. This parameter may be NULL

The i parameter will compare as equal with "end" upon return; however, if an element with a matching key existed, the key and val members will point to the key and value, respectively that we contained in the element.

Return values

0	The element was found and removed
-1	No matching element was found

Definition at line 144 of file map.c.

cstl_map_erase_iterator()

void cstl_map_erase_iterator	(	cstl_map_t *	map,
		cstl_map_iterator_t *	i
	)

Erase the element pointed to by the iterator.

Parameters

[in]	map	The map into which the iterator points
[in]	i	A pointer to the iterator indicating which element to removed

Definition at line 165 of file map.c.

cstl_map_find()

void cstl_map_find	(	const cstl_map_t *	map,
		const void *	key,
		cstl_map_iterator_t *	i
	)

Find an element in the map with a matching key.

Parameters

[in]	map	A pointer to the map to be searched
[in]	key	A pointer to the key that is sought
[out]	i	A pointer to an iterator in which to return a pointer to the sought element. This parameter may not be NULL

The i parameter will be "end" if the element is not found

Definition at line 136 of file map.c.

cstl_map_init()

void cstl_map_init	(	cstl_map_t *	map,
		cstl_compare_func_t *	cmp,
		void *	priv
	)

Initialize a map.

Initializing a previously initialized map that has not been cleared may cause the loss/leaking of memory.

Parameters

[out]	map	The map to be initialized
[in]	cmp	A function to be used to compare keys
[in]	priv	A pointer to be passed to each invocation of cmp

Definition at line 114 of file map.c.

cstl_map_insert()

int cstl_map_insert	(	cstl_map_t *	map,
		const void *	key,
		void *	val,
		cstl_map_iterator_t *	i
	)

Insert a key/value pair into the map.

Parameters

[in]	map	The map into which to insert the pair
[in]	key	A pointer to the key
[in]	val	A pointer to the value
[out]	i	A pointer to an iterator in which to return a pointer to the new or existing element in the map. This parameter may be NULL

Return values

-1	The function failed to allocate memory
0	The function successfully inserted the pair, and i points to the inserted element
1	An element with the same key already exists in the map. The new pair was not inserted, i points to the existing element in the map

Definition at line 173 of file map.c.

cstl_map_iterator_end()

const cstl_map_iterator_t * cstl_map_iterator_end

(

const cstl_map_t *

map

)

Return an iterator that refers to the end of the map.

Iterators for functions like cstl_map_find() and cstl_map_erase() that do not find a corresponding entry in the map will return an iterator that will compare equal with this value.

Parameters

[in]

map

A pointer to the map associated with the iterator

Returns

A pointer to an iterator referring to the end of the map

Definition at line 17 of file map.c.

cstl_map_iterator_eq()

static bool cstl_map_iterator_eq ( const cstl_map_iterator_t *const  a, const cstl_map_iterator_t *const  b  )

inlinestatic

Compare two iterators for equality.

Parameters

[in]	a	A pointer to a map iterator
[in]	b	A pointer to a map iterator

Return values

true	The iterators are equal
false	The iterators are not equal

Definition at line 82 of file map.h.

cstl_map_size()

static size_t cstl_map_size ( const cstl_map_t *const  map )

inlinestatic

Return the number of elements in the map.

Parameters

[in]

map

A pointer to the map

Returns

The number of elements in the map

Definition at line 111 of file map.h.