map.h File Reference

Interface for map implementations. More...

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

Go to the source code of this file.

Data Structures
struct	cx_map_s
	Structure for the UCX map. More...
struct	cx_map_class_s
	The class definition for arbitrary maps. More...
struct	cx_map_entry_s
	A map entry. 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	cxMapDetach(map, key)
	Detaches a key/value-pair from the map by using the key without invoking the destructor.
#define	cxMapRemoveAndGet(map, key)
	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_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
static void	cxMapStoreObjects (CxMap *map)
	Advises the map to store copies of the objects (default mode of operation).
static void	cxMapStorePointers (CxMap *map)
	Advises the map to only store pointers to the objects.
static void	cxMapDestroy (CxMap *map)
	Deallocates the memory of the specified map.
static void	cxMapClear (CxMap *map)
	Clears a map by removing all elements.
static CxIterator	cxMapIteratorValues (CxMap const *map)
	Creates a value iterator for a map.
static CxIterator	cxMapIteratorKeys (CxMap const *map)
	Creates a key iterator for a map.
static CxIterator	cxMapIterator (CxMap const *map)
	Creates an iterator for a map.
CxMutIterator	cxMapMutIteratorValues (CxMap *map)
	Creates a mutating iterator over the values of a map.
CxMutIterator	cxMapMutIteratorKeys (CxMap *map)
	Creates a mutating iterator over the keys of a map.
CxMutIterator	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, char const *key, void *value)
	Puts a key/value-pair into the map.
static void *	cx_map_get (CxMap const *map, CxHashKey key)
	Retrieves a value by using a key.
static void *	cx_map_get_cxstr (CxMap const *map, cxstring key)
	Retrieves a value by using a key.
static void *	cx_map_get_mustr (CxMap const *map, cxmutstr key)
	Retrieves a value by using a key.
static void *	cx_map_get_str (CxMap const *map, char const *key)
	Retrieves a value by using a key.
static void	cx_map_remove (CxMap *map, CxHashKey key)
	Removes a key/value-pair from the map by using the key.
static void	cx_map_remove_cxstr (CxMap *map, cxstring key)
	Removes a key/value-pair from the map by using the key.
static void	cx_map_remove_mustr (CxMap *map, cxmutstr key)
	Removes a key/value-pair from the map by using the key.
static void	cx_map_remove_str (CxMap *map, char const *key)
	Removes a key/value-pair from the map by using the key.
static void	cx_map_detach (CxMap *map, CxHashKey key)
	Detaches a key/value-pair from the map by using the key without invoking the destructor.
static void	cx_map_detach_cxstr (CxMap *map, cxstring key)
	Detaches a key/value-pair from the map by using the key without invoking the destructor.
static void	cx_map_detach_mustr (CxMap *map, cxmutstr key)
	Detaches a key/value-pair from the map by using the key without invoking the destructor.
static void	cx_map_detach_str (CxMap *map, char const *key)
	Detaches a key/value-pair from the map by using the key without invoking the destructor.
static void *	cx_map_remove_and_get (CxMap *map, CxHashKey key)
	Removes a key/value-pair from the map by using the key.
static void *	cx_map_remove_and_get_cxstr (CxMap *map, cxstring key)
	Removes a key/value-pair from the map by using the key.
static void *	cx_map_remove_and_get_mustr (CxMap *map, cxmutstr key)
	Removes a key/value-pair from the map by using the key.
static void *	cx_map_remove_and_get_str (CxMap *map, char const *key)
	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

Version

3.0

Copyright

2-Clause BSD License

Macro Definition Documentation

cxMapDetach

#define cxMapDetach	(		map,
			key
	)

Value:

    _Generic((key), \
    CxHashKey: cx_map_detach,                 \
    cxstring: cx_map_detach_cxstr,            \
    cxmutstr: cx_map_detach_mustr,            \
    char*: cx_map_detach_str,                 \
    char const*: cx_map_detach_str)           \
    (map, key)

Detaches a key/value-pair from the map by using the key without invoking the destructor.

In general, you should only use this function if the map does not own the data and there is a valid reference to the data somewhere else in the program. In all other cases it is preferable to use cxMapRemove() or cxMapRemoveAndGet().

Parameters

map	the map
key	the key

See also

cxMapRemove()

cxMapRemoveAndGet()

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,                 \
    char const*: cx_map_get_str)           \
    (map, key)

Retrieves a value by using a key.

Parameters

map	the map
key	the key

Returns

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,                        \
    char const*: cx_map_put_str)                  \
    (map, key, value)

Puts a key/value-pair into the map.

Parameters

map	the map
key	the key
value	the value

Returns

0 on success, non-zero value on 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,                 \
    char const*: cx_map_remove_str)           \
    (map, key)

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

Always invokes the destructor function, if any, on the removed element. If this map is storing pointers and you just want to retrieve the pointer without invoking the destructor, use cxMapRemoveAndGet(). If you just want to detach the element from the map without invoking the destructor or returning the element, use cxMapDetach().

Parameters

map	the map
key	the key

See also

cxMapRemoveAndGet()

cxMapDetach()

cxMapRemoveAndGet

#define cxMapRemoveAndGet	(		map,
			key
	)

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,               \
    char const*: cx_map_remove_and_get_str)         \
    (map, key)

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

This function can be used when the map is storing pointers, in order to retrieve the pointer from the map without invoking any destructor function. Sometimes you do not want the pointer to be returned - in that case (instead of suppressing the "unused result" warning) you can use cxMapDetach().

If this map is not storing pointers, this function behaves like cxMapRemove() and returns NULL.

Parameters

map	the map
key	the key

Returns

the stored pointer or NULL if either the key is not present in the map or the map is not storing pointers

See also

cxMapStorePointers()

cxMapDetach()

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_detach()

static void cx_map_detach ( CxMap *  map, CxHashKey  key  )

inlinestatic

Detaches a key/value-pair from the map by using the key without invoking the destructor.

Parameters

map	the map
key	the key

cx_map_detach_cxstr()

static void cx_map_detach_cxstr ( CxMap *  map, cxstring  key  )

inlinestatic

Detaches a key/value-pair from the map by using the key without invoking the destructor.

Parameters

map	the map
key	the key

cx_map_detach_mustr()

static void cx_map_detach_mustr ( CxMap *  map, cxmutstr  key  )

inlinestatic

Detaches a key/value-pair from the map by using the key without invoking the destructor.

Parameters

map	the map
key	the key

cx_map_detach_str()

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

inlinestatic

Detaches a key/value-pair from the map by using the key without invoking the destructor.

Parameters

map	the map
key	the key

cx_map_get()

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

inlinestatic

Retrieves a value by using a key.

Parameters

map	the map
key	the key

Returns

the value

cx_map_get_cxstr()

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

inlinestatic

Retrieves a value by using a key.

Parameters

map	the map
key	the key

Returns

the value

cx_map_get_mustr()

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

inlinestatic

Retrieves a value by using a key.

Parameters

map	the map
key	the key

Returns

the value

cx_map_get_str()

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

inlinestatic

Retrieves a value by using a key.

Parameters

map	the map
key	the key

Returns

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.

Parameters

map	the map
key	the key
value	the value

Returns

0 on success, non-zero value on 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.

Parameters

map	the map
key	the key
value	the value

Returns

0 on success, non-zero value on 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.

Parameters

map	the map
key	the key
value	the value

Returns

0 on success, non-zero value on failure

cx_map_put_str()

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

inlinestatic

Puts a key/value-pair into the map.

Parameters

map	the map
key	the key
value	the value

Returns

0 on success, non-zero value on failure

cx_map_remove()

static void cx_map_remove ( CxMap *  map, CxHashKey  key  )

inlinestatic

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

Parameters

map	the map
key	the key

cx_map_remove_and_get()

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

inlinestatic

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

Parameters

map	the map
key	the key

Returns

the stored pointer or NULL if either the key is not present in the map or the map is not storing pointers

cx_map_remove_and_get_cxstr()

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

inlinestatic

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

Parameters

map	the map
key	the key

Returns

the stored pointer or NULL if either the key is not present in the map or the map is not storing pointers

cx_map_remove_and_get_mustr()

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

inlinestatic

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

Parameters

map	the map
key	the key

Returns

the stored pointer or NULL if either the key is not present in the map or the map is not storing pointers

cx_map_remove_and_get_str()

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

inlinestatic

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

Parameters

map	the map
key	the key

Returns

the stored pointer or NULL if either the key is not present in the map or the map is not storing pointers

cx_map_remove_cxstr()

static void cx_map_remove_cxstr ( CxMap *  map, cxstring  key  )

inlinestatic

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

Parameters

map	the map
key	the key

cx_map_remove_mustr()

static void cx_map_remove_mustr ( CxMap *  map, cxmutstr  key  )

inlinestatic

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

Parameters

map	the map
key	the key

cx_map_remove_str()

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

inlinestatic

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

Parameters

map	the map
key	the key

cxMapClear()

static void cxMapClear ( CxMap *  map )

inlinestatic

Clears a map by removing all elements.

Parameters

map	the map to be cleared

cxMapDestroy()

static void cxMapDestroy ( CxMap *  map )

inlinestatic

Deallocates the memory of the specified map.

Parameters

map	the map to be destroyed

cxMapIterator()

static CxIterator cxMapIterator ( CxMap const *  map )

inlinestatic

Creates an iterator for a map.

The elements of the iterator are key/value pairs of type 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 CxIterator cxMapIteratorKeys ( CxMap const *  map )

inlinestatic

Creates a key iterator for a map.

The elements of the iterator are keys of type 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 CxIterator cxMapIteratorValues ( CxMap const *  map )

inlinestatic

Creates a value iterator for a map.

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()

CxMutIterator cxMapMutIterator

(

CxMap *

map

)

Creates a mutating iterator for a map.

The elements of the iterator are key/value pairs of type 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()

CxMutIterator cxMapMutIteratorKeys

(

CxMap *

map

)

Creates a mutating iterator over the keys of a map.

The elements of the iterator are keys of type 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()

CxMutIterator cxMapMutIteratorValues

(

CxMap *

map

)

Creates a mutating iterator over the values of a map.

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

cxMapStoreObjects()

static void cxMapStoreObjects ( CxMap *  map )

inlinestatic

Advises the map to store copies of the objects (default mode of operation).

Retrieving objects from this map will yield pointers to the copies stored within this list.

Parameters

map

the map

See also

cxMapStorePointers()

cxMapStorePointers()

static void cxMapStorePointers ( CxMap *  map )

inlinestatic

Advises the map to only store pointers to the objects.

Retrieving objects from this list will yield the original pointers stored.

Note

This function forcibly sets the element size to the size of a pointer. Invoking this function on a non-empty map that already stores copies of objects is undefined.

Parameters

map

the map

See also

cxMapStoreObjects()

Variable Documentation

cxEmptyMap

CxMap* const cxEmptyMap

extern

A shared instance of an empty map.

Writing to that map is undefined.