Interface for map implementations. More...

#include "common.h"
#include "collection.h"
#include "string.h"
#include "hash_key.h"

Data Structures
struct	cx_map_s
	Structure for the UCX map. More...

struct	cx_map_entry_s
	A map entry. More...

struct	cx_map_iterator_s
	Internal iterator struct - use CxMapIterator. More...

struct	cx_map_class_s
	The class definition for arbitrary maps. More...

Macros
#define	cxMapPut(map, key, value)
	Puts a key/value-pair into the map.

#define	cxMapGet(map, key)
	Retrieves a value by using a key.

#define	cxMapRemove(map, key)
	Removes a key/value-pair from the map by using the key.

#define	cxMapRemoveAndGet(map, key, targetbuf)
	Removes a key/value-pair from the map by using the key.

Typedefs
typedef struct cx_map_s	CxMap
	Type for the UCX map.

typedef struct cx_map_entry_s	CxMapEntry
	Type for a map entry.

typedef struct cx_map_iterator_s	CxMapIterator
	Type for a map iterator.

typedef struct cx_map_class_s	cx_map_class
	Type for map class definitions.

Enumerations
enum	cx_map_iterator_type { CX_MAP_ITERATOR_PAIRS , CX_MAP_ITERATOR_KEYS , CX_MAP_ITERATOR_VALUES }
	The type of iterator for a map. More...

Functions
void	cxMapFree (CxMap *map)
	Deallocates the memory of the specified map.

static void	cxMapClear (CxMap *map)
	Clears a map by removing all elements.

static size_t	cxMapSize (const CxMap *map)
	Returns the number of elements in this map.

static CxMapIterator	cxMapIteratorValues (const CxMap *map)
	Creates a value iterator for a map.

static CxMapIterator	cxMapIteratorKeys (const CxMap *map)
	Creates a key iterator for a map.

static CxMapIterator	cxMapIterator (const CxMap *map)
	Creates an iterator for a map.

CxMapIterator	cxMapMutIteratorValues (CxMap *map)
	Creates a mutating iterator over the values of a map.

CxMapIterator	cxMapMutIteratorKeys (CxMap *map)
	Creates a mutating iterator over the keys of a map.

CxMapIterator	cxMapMutIterator (CxMap *map)
	Creates a mutating iterator for a map.

static int	cx_map_put (CxMap map, CxHashKey key, void value)
	Puts a key/value-pair into the map.

static int	cx_map_put_cxstr (CxMap map, cxstring key, void value)
	Puts a key/value-pair into the map.

static int	cx_map_put_mustr (CxMap map, cxmutstr key, void value)
	Puts a key/value-pair into the map.

static int	cx_map_put_str (CxMap map, const char key, void *value)
	Puts a key/value-pair into the map.

static void *	cx_map_get (const CxMap *map, CxHashKey key)
	Retrieves a value by using a key.

static void *	cx_map_get_cxstr (const CxMap *map, cxstring key)
	Retrieves a value by using a key.

static void *	cx_map_get_mustr (const CxMap *map, cxmutstr key)
	Retrieves a value by using a key.

static void *	cx_map_get_str (const CxMap map, const char key)
	Retrieves a value by using a key.

static int	cx_map_remove (CxMap *map, CxHashKey key)
	Removes a key/value-pair from the map by using the key.

static int	cx_map_remove_cxstr (CxMap *map, cxstring key)
	Removes a key/value-pair from the map by using the key.

static int	cx_map_remove_mustr (CxMap *map, cxmutstr key)
	Removes a key/value-pair from the map by using the key.

static int	cx_map_remove_str (CxMap map, const char key)
	Removes a key/value-pair from the map by using the key.

static int	cx_map_remove_and_get (CxMap map, CxHashKey key, void targetbuf)
	Removes a key/value-pair from the map by using the key.

static int	cx_map_remove_and_get_cxstr (CxMap map, cxstring key, void targetbuf)
	Removes a key/value-pair from the map by using the key.

static int	cx_map_remove_and_get_mustr (CxMap map, cxmutstr key, void targetbuf)
	Removes a key/value-pair from the map by using the key.

static int	cx_map_remove_and_get_str (CxMap map, const char key, void *targetbuf)
	Removes a key/value-pair from the map by using the key.

Variables
CxMap *const	cxEmptyMap
	A shared instance of an empty map.

Detailed Description

Interface for map implementations.

Author: Mike Becker; Olaf Wintermann

Copyright: 2-Clause BSD License

Macro Definition Documentation

◆ cxMapGet

#define cxMapGet	(		map,
			key )

Value:

    _Generic((key), \
    CxHashKey: cx_map_get,                 \
    cxstring: cx_map_get_cxstr,            \
    cxmutstr: cx_map_get_mustr,            \
    char*: cx_map_get_str,                 \
    const char*: cx_map_get_str)           \
    (map, key)

Retrieves a value by using a key.

If this map is storing pointers, the stored pointer is returned. Otherwise, a pointer to the element within the map's memory is returned (which is valid as long as the element stays in the map).

Parameters

map	(`CxMap*`) the map
key	(`CxHashKey`, `char*`, `cxstring`, or `cxmutstr`) the key

Returns: (void*) the value

◆ cxMapPut

#define cxMapPut	(	map,
		key,
		value )

Value:

    _Generic((key), \
    CxHashKey: cx_map_put,                        \
    cxstring: cx_map_put_cxstr,                   \
    cxmutstr: cx_map_put_mustr,                   \
    char*: cx_map_put_str,                        \
    const char*: cx_map_put_str)                  \
    (map, key, value)

Puts a key/value-pair into the map.

A possible existing value will be overwritten. If destructor functions are specified, they are called for the overwritten element.

If this map is storing pointers, the value pointer is written to the map. Otherwise, the memory is copied from value with memcpy().

The key is always copied.

Parameters

map	(`CxMap*`) the map
key	(`CxHashKey`, `char*`, `cxstring`, or `cxmutstr`) the key
value	(`void*`) the value

Return values

zero	success
non-zero	value on memory allocation failure

◆ cxMapRemove

#define cxMapRemove	(		map,
			key )

Value:

    _Generic((key), \
    CxHashKey: cx_map_remove,                 \
    cxstring: cx_map_remove_cxstr,            \
    cxmutstr: cx_map_remove_mustr,            \
    char*: cx_map_remove_str,                 \
    const char*: cx_map_remove_str)           \
    (map, key)

Removes a key/value-pair from the map by using the key.

Always invokes the destructors functions, if any, on the removed element.

Parameters

map	(`CxMap*`) the map
key	(`CxHashKey`, `char*`, `cxstring`, or `cxmutstr`) the key

Return values

zero	success
non-zero	the key was not found

See also: cxMapRemoveAndGet()

◆ cxMapRemoveAndGet

#define cxMapRemoveAndGet	(	map,
		key,
		targetbuf )

Value:

    _Generic((key), \
    CxHashKey: cx_map_remove_and_get,               \
    cxstring: cx_map_remove_and_get_cxstr,          \
    cxmutstr: cx_map_remove_and_get_mustr,          \
    char*: cx_map_remove_and_get_str,               \
    const char*: cx_map_remove_and_get_str)         \
    (map, key, targetbuf)

Removes a key/value-pair from the map by using the key.

This function will copy the contents of the removed element to the target buffer, which must be guaranteed to be large enough to hold the element (the map's element size). The destructor functions, if any, will not be called.

If this map is storing pointers, the element is the pointer itself and not the object it points to.

Parameters

map	(`CxMap*`) the map
key	(`CxHashKey`, `char*`, `cxstring`, or `cxmutstr`) the key
targetbuf	(`void*`) the buffer where the element shall be copied to

Return values

zero	success
non-zero	the key was not found

See also: cxMapRemove()

Enumeration Type Documentation

◆ cx_map_iterator_type

enum cx_map_iterator_type

The type of iterator for a map.

Enumerator
CX_MAP_ITERATOR_PAIRS	Iterates over key/value pairs.
CX_MAP_ITERATOR_KEYS	Iterates over keys only.
CX_MAP_ITERATOR_VALUES	Iterates over values only.

Function Documentation

◆ cx_map_get()

static void * cx_map_get	(	const CxMap *	map,
		CxHashKey	key )

inlinestatic

Retrieves a value by using a key.

If this map is storing pointers, the stored pointer is returned. Otherwise, a pointer to the element within the map's memory is returned (which is valid as long as the element stays in the map).

Parameters

map	(`CxMap*`) the map
key	(`CxHashKey`, `char*`, `cxstring`, or `cxmutstr`) the key

Returns: (void*) the value

◆ cx_map_get_cxstr()

static void * cx_map_get_cxstr	(	const CxMap *	map,
		cxstring	key )

inlinestatic

Retrieves a value by using a key.

If this map is storing pointers, the stored pointer is returned. Otherwise, a pointer to the element within the map's memory is returned (which is valid as long as the element stays in the map).

Parameters

map	(`CxMap*`) the map
key	(`CxHashKey`, `char*`, `cxstring`, or `cxmutstr`) the key

Returns: (void*) the value

◆ cx_map_get_mustr()

static void * cx_map_get_mustr	(	const CxMap *	map,
		cxmutstr	key )

inlinestatic

Retrieves a value by using a key.

If this map is storing pointers, the stored pointer is returned. Otherwise, a pointer to the element within the map's memory is returned (which is valid as long as the element stays in the map).

Parameters

map	(`CxMap*`) the map
key	(`CxHashKey`, `char*`, `cxstring`, or `cxmutstr`) the key

Returns: (void*) the value

◆ cx_map_get_str()

static void * cx_map_get_str	(	const CxMap *	map,
		const char *	key )

inlinestatic

Retrieves a value by using a key.

If this map is storing pointers, the stored pointer is returned. Otherwise, a pointer to the element within the map's memory is returned (which is valid as long as the element stays in the map).

Parameters

map	(`CxMap*`) the map
key	(`CxHashKey`, `char*`, `cxstring`, or `cxmutstr`) the key

Returns: (void*) the value

◆ cx_map_put()

static int cx_map_put	(	CxMap *	map,
		CxHashKey	key,
		void *	value )

inlinestatic

Puts a key/value-pair into the map.

A possible existing value will be overwritten. If destructor functions are specified, they are called for the overwritten element.

If this map is storing pointers, the value pointer is written to the map. Otherwise, the memory is copied from value with memcpy().

The key is always copied.

Parameters

map	(`CxMap*`) the map
key	(`CxHashKey`, `char*`, `cxstring`, or `cxmutstr`) the key
value	(`void*`) the value

Return values

zero	success
non-zero	value on memory allocation failure

◆ cx_map_put_cxstr()

static int cx_map_put_cxstr	(	CxMap *	map,
		cxstring	key,
		void *	value )

inlinestatic

Puts a key/value-pair into the map.

A possible existing value will be overwritten. If destructor functions are specified, they are called for the overwritten element.

If this map is storing pointers, the value pointer is written to the map. Otherwise, the memory is copied from value with memcpy().

The key is always copied.

Parameters

map	(`CxMap*`) the map
key	(`CxHashKey`, `char*`, `cxstring`, or `cxmutstr`) the key
value	(`void*`) the value

Return values

zero	success
non-zero	value on memory allocation failure

◆ cx_map_put_mustr()

static int cx_map_put_mustr	(	CxMap *	map,
		cxmutstr	key,
		void *	value )

inlinestatic

Puts a key/value-pair into the map.

A possible existing value will be overwritten. If destructor functions are specified, they are called for the overwritten element.

If this map is storing pointers, the value pointer is written to the map. Otherwise, the memory is copied from value with memcpy().

The key is always copied.

Parameters

map	(`CxMap*`) the map
key	(`CxHashKey`, `char*`, `cxstring`, or `cxmutstr`) the key
value	(`void*`) the value

Return values

zero	success
non-zero	value on memory allocation failure

◆ cx_map_put_str()

static int cx_map_put_str	(	CxMap *	map,
		const char *	key,
		void *	value )

inlinestatic

Puts a key/value-pair into the map.

A possible existing value will be overwritten. If destructor functions are specified, they are called for the overwritten element.

If this map is storing pointers, the value pointer is written to the map. Otherwise, the memory is copied from value with memcpy().

The key is always copied.

Parameters

map	(`CxMap*`) the map
key	(`CxHashKey`, `char*`, `cxstring`, or `cxmutstr`) the key
value	(`void*`) the value

Return values

zero	success
non-zero	value on memory allocation failure

◆ cx_map_remove()

static int cx_map_remove	(	CxMap *	map,
		CxHashKey	key )

inlinestatic

Removes a key/value-pair from the map by using the key.

Always invokes the destructors functions, if any, on the removed element.

Parameters

map	(`CxMap*`) the map
key	(`CxHashKey`, `char*`, `cxstring`, or `cxmutstr`) the key

Return values

zero	success
non-zero	the key was not found

See also: cxMapRemoveAndGet()

◆ cx_map_remove_and_get()

static int cx_map_remove_and_get	(	CxMap *	map,
		CxHashKey	key,
		void *	targetbuf )

inlinestatic

Removes a key/value-pair from the map by using the key.

This function will copy the contents of the removed element to the target buffer, which must be guaranteed to be large enough to hold the element (the map's element size). The destructor functions, if any, will not be called.

If this map is storing pointers, the element is the pointer itself and not the object it points to.

Parameters

map	(`CxMap*`) the map
key	(`CxHashKey`, `char*`, `cxstring`, or `cxmutstr`) the key
targetbuf	(`void*`) the buffer where the element shall be copied to

Return values

zero	success
non-zero	the key was not found

See also: cxMapRemove()

◆ cx_map_remove_and_get_cxstr()

static int cx_map_remove_and_get_cxstr	(	CxMap *	map,
		cxstring	key,
		void *	targetbuf )

inlinestatic

Removes a key/value-pair from the map by using the key.

This function will copy the contents of the removed element to the target buffer, which must be guaranteed to be large enough to hold the element (the map's element size). The destructor functions, if any, will not be called.

If this map is storing pointers, the element is the pointer itself and not the object it points to.

Parameters

map	(`CxMap*`) the map
key	(`CxHashKey`, `char*`, `cxstring`, or `cxmutstr`) the key
targetbuf	(`void*`) the buffer where the element shall be copied to

Return values

zero	success
non-zero	the key was not found

See also: cxMapRemove()

◆ cx_map_remove_and_get_mustr()

static int cx_map_remove_and_get_mustr	(	CxMap *	map,
		cxmutstr	key,
		void *	targetbuf )

inlinestatic

Removes a key/value-pair from the map by using the key.

This function will copy the contents of the removed element to the target buffer, which must be guaranteed to be large enough to hold the element (the map's element size). The destructor functions, if any, will not be called.

If this map is storing pointers, the element is the pointer itself and not the object it points to.

Parameters

map	(`CxMap*`) the map
key	(`CxHashKey`, `char*`, `cxstring`, or `cxmutstr`) the key
targetbuf	(`void*`) the buffer where the element shall be copied to

Return values

zero	success
non-zero	the key was not found

See also: cxMapRemove()

◆ cx_map_remove_and_get_str()

static int cx_map_remove_and_get_str	(	CxMap *	map,
		const char *	key,
		void *	targetbuf )

inlinestatic

Removes a key/value-pair from the map by using the key.

This function will copy the contents of the removed element to the target buffer, which must be guaranteed to be large enough to hold the element (the map's element size). The destructor functions, if any, will not be called.

If this map is storing pointers, the element is the pointer itself and not the object it points to.

Parameters

map	(`CxMap*`) the map
key	(`CxHashKey`, `char*`, `cxstring`, or `cxmutstr`) the key
targetbuf	(`void*`) the buffer where the element shall be copied to

Return values

zero	success
non-zero	the key was not found

See also: cxMapRemove()

◆ cx_map_remove_cxstr()

static int cx_map_remove_cxstr	(	CxMap *	map,
		cxstring	key )

inlinestatic

Removes a key/value-pair from the map by using the key.

Always invokes the destructors functions, if any, on the removed element.

Parameters

map	(`CxMap*`) the map
key	(`CxHashKey`, `char*`, `cxstring`, or `cxmutstr`) the key

Return values

zero	success
non-zero	the key was not found

See also: cxMapRemoveAndGet()

◆ cx_map_remove_mustr()

static int cx_map_remove_mustr	(	CxMap *	map,
		cxmutstr	key )

inlinestatic

Removes a key/value-pair from the map by using the key.

Always invokes the destructors functions, if any, on the removed element.

Parameters

map	(`CxMap*`) the map
key	(`CxHashKey`, `char*`, `cxstring`, or `cxmutstr`) the key

Return values

zero	success
non-zero	the key was not found

See also: cxMapRemoveAndGet()

◆ cx_map_remove_str()

static int cx_map_remove_str	(	CxMap *	map,
		const char *	key )

inlinestatic

Removes a key/value-pair from the map by using the key.

Always invokes the destructors functions, if any, on the removed element.

Parameters

map	(`CxMap*`) the map
key	(`CxHashKey`, `char*`, `cxstring`, or `cxmutstr`) the key

Return values

zero	success
non-zero	the key was not found

See also: cxMapRemoveAndGet()

◆ cxMapClear()

static void cxMapClear ( CxMap * map )

inlinestatic

Clears a map by removing all elements.

Also calls the content destructor functions for each element, if specified.

Parameters

map	the map to be cleared

◆ cxMapFree()

void cxMapFree ( CxMap * map )

Deallocates the memory of the specified map.

Also calls the content destructor functions for each element, if specified.

Parameters

map	the map to be freed

◆ cxMapIterator()

static CxMapIterator cxMapIterator ( const CxMap * map )

inlinestatic

Creates an iterator for a map.

The elements of the iterator are key/value pairs of type CxMapEntry and the pointer returned during iterator shall be treated as const CxMapEntry* .

Note: An iterator iterates over all elements successively. Therefore, the order highly depends on the map implementation and may change arbitrarily when the contents change.

Parameters

map	the map to create the iterator for

Returns: an iterator for the currently stored entries

See also: cxMapIteratorKeys(); cxMapIteratorValues()

◆ cxMapIteratorKeys()

static CxMapIterator cxMapIteratorKeys ( const CxMap * map )

inlinestatic

Creates a key iterator for a map.

The elements of the iterator are keys of type CxHashKey and the pointer returned during iterator shall be treated as const CxHashKey* .

Note: An iterator iterates over all elements successively. Therefore, the order highly depends on the map implementation and may change arbitrarily when the contents change.

Parameters

map	the map to create the iterator for

Returns: an iterator for the currently stored keys

◆ cxMapIteratorValues()

static CxMapIterator cxMapIteratorValues ( const CxMap * map )

inlinestatic

Creates a value iterator for a map.

When the map is storing pointers, those pointers are returned. Otherwise, the iterator iterates over pointers to the memory within the map where the respective elements are stored.

Note: An iterator iterates over all elements successively. Therefore, the order highly depends on the map implementation and may change arbitrarily when the contents change.

Parameters

map	the map to create the iterator for

Returns: an iterator for the currently stored values

◆ cxMapMutIterator()

CxMapIterator cxMapMutIterator ( CxMap * map )

Creates a mutating iterator for a map.

The elements of the iterator are key/value pairs of type CxMapEntry and the pointer returned during iterator shall be treated as const CxMapEntry* .

Note: An iterator iterates over all elements successively. Therefore, the order highly depends on the map implementation and may change arbitrarily when the contents change.

Parameters

map	the map to create the iterator for

Returns: an iterator for the currently stored entries

See also: cxMapMutIteratorKeys(); cxMapMutIteratorValues()

◆ cxMapMutIteratorKeys()

CxMapIterator cxMapMutIteratorKeys ( CxMap * map )

Creates a mutating iterator over the keys of a map.

The elements of the iterator are keys of type CxHashKey and the pointer returned during iterator shall be treated as const CxHashKey* .

Note: An iterator iterates over all elements successively. Therefore, the order highly depends on the map implementation and may change arbitrarily when the contents change.

Parameters

map	the map to create the iterator for

Returns: an iterator for the currently stored keys

◆ cxMapMutIteratorValues()

CxMapIterator cxMapMutIteratorValues ( CxMap * map )

Creates a mutating iterator over the values of a map.

When the map is storing pointers, those pointers are returned. Otherwise, the iterator iterates over pointers to the memory within the map where the respective elements are stored.

Note: An iterator iterates over all elements successively. Therefore, the order highly depends on the map implementation and may change arbitrarily when the contents change.

Parameters

map	the map to create the iterator for

Returns: an iterator for the currently stored values

◆ cxMapSize()

static size_t cxMapSize ( const CxMap * map )

inlinestatic

Returns the number of elements in this map.

Parameters

map the map

Returns: the number of stored elements

Variable Documentation

◆ cxEmptyMap

CxMap* const cxEmptyMap

extern

A shared instance of an empty map.

Writing to that map is not allowed.

You can use this is a placeholder for initializing CxMap pointers for which you do not want to reserve memory right from the beginning.

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ cxMapGet

◆ cxMapPut

◆ cxMapRemove

◆ cxMapRemoveAndGet

Enumeration Type Documentation

◆ cx_map_iterator_type

Function Documentation

◆ cx_map_get()

◆ cx_map_get_cxstr()

◆ cx_map_get_mustr()

◆ cx_map_get_str()

◆ cx_map_put()

◆ cx_map_put_cxstr()

◆ cx_map_put_mustr()

◆ cx_map_put_str()

◆ cx_map_remove()

◆ cx_map_remove_and_get()

◆ cx_map_remove_and_get_cxstr()

◆ cx_map_remove_and_get_mustr()

◆ cx_map_remove_and_get_str()

◆ cx_map_remove_cxstr()

◆ cx_map_remove_mustr()

◆ cx_map_remove_str()

◆ cxMapClear()

◆ cxMapFree()

◆ cxMapIterator()

◆ cxMapIteratorKeys()

◆ cxMapIteratorValues()

◆ cxMapMutIterator()

◆ cxMapMutIteratorKeys()

◆ cxMapMutIteratorValues()

◆ cxMapSize()

Variable Documentation

◆ cxEmptyMap