kv_list.h File Reference

Linked list implementation with key/value-lookup. More...

#include "common.h"
#include "list.h"
#include "map.h"

Go to the source code of this file.

Macros
#define	cxKvListCreateSimple(elem_size)
	Allocates a linked list with a lookup-map for storing elements with elem_size bytes each.
#define	cxKvListCreateAsMapSimple(elem_size)
	Allocates a linked list with a lookup-map for storing elements with elem_size bytes each.
#define	cxKvListSetKey(list, index, key)
	Sets or updates the key of a list item.
#define	cxKvListInsert(list, index, key, value)
	Inserts an item into the list at the specified index and associates it with the specified key.
#define	cxKvListAdd(list, key, value)
	Adds an item into the list and associates it with the specified key.

Functions
CxList *	cxKvListCreate (const CxAllocator *allocator, cx_compare_func comparator, size_t elem_size)
	Allocates a linked list with a lookup-map for storing elements with elem_size bytes each.
CxMap *	cxKvListCreateAsMap (const CxAllocator *allocator, cx_compare_func comparator, size_t elem_size)
	Allocates a linked list with a lookup-map for storing elements with elem_size bytes each.
CxList *	cxKvListAsList (CxMap *map)
	Converts a map pointer belonging to a key-value-List back to the original list pointer.
CxMap *	cxKvListAsMap (CxList *list)
	Converts a map pointer belonging to a key-value-List back to the original list pointer.
int	cx_kv_list_set_key (CxList *list, size_t index, CxHashKey key)
	Sets or updates the key of a list item.
int	cx_kv_list_insert (CxList *list, size_t index, CxHashKey key, void *value)
	Inserts an item into the list at the specified index and associates it with the specified key.
int	cxKvListRemoveKey (CxList *list, size_t index)
	Removes the key of a list item.
const CxHashKey *	cxKvListGetKey (CxList *list, size_t index)
	Returns the key of a list item.

Detailed Description

Linked list implementation with key/value-lookup.

Author

Mike Becker

Olaf Wintermann

Copyright

2-Clause BSD License

Macro Definition Documentation

cxKvListAdd

#define cxKvListAdd	(		list,
			key,
			value )

Value:

cxKvListInsert(list, (list)->collection.size, key, value)

Adds an item into the list and associates it with the specified key.

Parameters

list	(CxList*) the list
key	(CxHashKey, char*, cxstring, or cxmutstr) the key
value	(void*) the value

Return values

zero	success
non-zero	memory allocation failure

cxKvListCreateAsMapSimple

#define cxKvListCreateAsMapSimple

(

elem_size

)

Value:

cxKvListCreateAsMap(NULL, NULL, elem_size)

Allocates a linked list with a lookup-map for storing elements with elem_size bytes each.

The list will use cxDefaultAllocator and no comparator function. If you want to call functions that need a comparator, you must either set one immediately after list creation or use cxKvListCreate().

If elem_size is CX_STORE_POINTERS, the created list stores pointers instead of copies of the added elements, and the compare function will be automatically set to cx_cmp_ptr().

This macro behaves as if the list was created with cxKvListCreateSimple() and immediately followed up by cxKvListAsMap(). If you want to use the returned object as a list, you can call cxKvListAsList() later.

Parameters

elem_size

(size_t) the size of each element in bytes

Returns

(CxMap*) the created list wrapped into the CxMap interface

See also

cxKvListAsMap()

cxKvListAsList()

cxKvListCreateSimple

#define cxKvListCreateSimple

(

elem_size

)

Value:

cxKvListCreate(NULL, NULL, elem_size)

Allocates a linked list with a lookup-map for storing elements with elem_size bytes each.

The list will use cxDefaultAllocator and no comparator function. If you want to call functions that need a comparator, you must either set one immediately after list creation or use cxKvListCreate().

If elem_size is CX_STORE_POINTERS, the created list stores pointers instead of copies of the added elements, and the compare function will be automatically set to cx_cmp_ptr().

After creating the list, it can also be used as a map after converting the pointer to a CxMap pointer with cxKvListAsMap(). When you want to use the list interface again, you can also convert the map pointer back with cxKvListAsList().

Parameters

elem_size

(size_t) the size of each element in bytes

Returns

(CxList*) the created list

See also

cxKvListAsMap()

cxKvListAsList()

cxKvListInsert

#define cxKvListInsert	(		list,
			index,
			key,
			value )

Value:

cx_kv_list_insert(list, index, CX_HASH_KEY(key), value)

Inserts an item into the list at the specified index and associates it with the specified key.

Parameters

list	(CxList*) the list
index	(size_t) the index the inserted element shall have
key	(any supported key type) the key
value	(void*) the value

Return values

zero	success
non-zero	memory allocation failure or the index is out of bounds

See also

CX_HASH_KEY()

cxKvListSetKey

#define cxKvListSetKey	(		list,
			index,
			key )

Value:

cx_kv_list_set_key(list, index, CX_HASH_KEY(key))

Sets or updates the key of a list item.

This is, for example, useful when you have inserted an element using the CxList interface, and now you want to associate this element with a key.

Parameters

list	(CxList*) the list
index	(size_t) the index of the element in the list
key	(any supported key type) the key

Return values

zero	success
non-zero	memory allocation failure or the index is out of bounds

See also

CX_HASH_KEY()

Function Documentation

cx_kv_list_insert()

int cx_kv_list_insert	(	CxList *	list,
		size_t	index,
		CxHashKey	key,
		void *	value )

Inserts an item into the list at the specified index and associates it with the specified key.

Parameters

list	the list
index	the index the inserted element shall have
key	the key
value	the value

Return values

zero	success
non-zero	memory allocation failure or the index is out of bounds

See also

cxKvListInsert()

cx_kv_list_set_key()

int cx_kv_list_set_key	(	CxList *	list,
		size_t	index,
		CxHashKey	key )

Sets or updates the key of a list item.

This is, for example, useful when you have inserted an element using the CxList interface, and now you want to associate this element with a key.

Parameters

list	the list
index	the index of the element in the list
key	the key

Return values

zero	success
non-zero	memory allocation failure or the index is out of bounds

See also

cxKvListSetKey()

cxKvListAsList()

CxList * cxKvListAsList

(

CxMap *

map

)

Converts a map pointer belonging to a key-value-List back to the original list pointer.

Parameters

map	a map pointer that was returned by a call to cxKvListAsMap()

Returns

the original list pointer

cxKvListAsMap()

CxMap * cxKvListAsMap

(

CxList *

list

)

Converts a map pointer belonging to a key-value-List back to the original list pointer.

Parameters

list	a list created by cxKvListCreate() or cxKvListCreateSimple()

Returns

a map pointer that lets you use the list as if it was a map

cxKvListCreate()

CxList * cxKvListCreate	(	const CxAllocator *	allocator,
		cx_compare_func	comparator,
		size_t	elem_size )

Allocates a linked list with a lookup-map for storing elements with elem_size bytes each.

If elem_size is CX_STORE_POINTERS, the created list stores pointers instead of copies of the added elements, and the compare function will be automatically set to cx_cmp_ptr() if none is given.

After creating the list, it can also be used as a map after converting the pointer to a CxMap pointer with cxKvListAsMap(). When you want to use the list interface again, you can also convert the map pointer back with cxKvListAsList().

Parameters

allocator	the allocator for allocating the list nodes (if NULL, the cxDefaultAllocator will be used)
comparator	the comparator for the elements (if NULL, and the list is not storing pointers, sort and find functions will not work)
elem_size	the size of each element in bytes

Returns

the created list

See also

cxKvListAsMap()

cxKvListAsList()

cxKvListCreateAsMap()

CxMap * cxKvListCreateAsMap	(	const CxAllocator *	allocator,
		cx_compare_func	comparator,
		size_t	elem_size )

Allocates a linked list with a lookup-map for storing elements with elem_size bytes each.

If elem_size is CX_STORE_POINTERS, the created list stores pointers instead of copies of the added elements, and the compare function will be automatically set to cx_cmp_ptr() if none is given.

This function creates the list with cxKvListCreate() and immediately applies cxKvListAsMap(). If you want to use the returned object as a list, you can call cxKvListAsList() later.

Parameters

allocator	the allocator for allocating the list nodes (if NULL, the cxDefaultAllocator will be used)
comparator	the comparator for the elements (if NULL, and the list is not storing pointers, sort and find functions will not work)
elem_size	the size of each element in bytes

Returns

the created list wrapped into the CxMap interface

See also

cxKvListAsMap()

cxKvListAsList()

cxKvListGetKey()

const CxHashKey * cxKvListGetKey	(	CxList *	list,
		size_t	index )

Returns the key of a list item.

Parameters

list	the list
index	the index of the element in the list

Returns

a pointer to the key or NULL when the index is out of bounds or the item does not have a key

cxKvListRemoveKey()

int cxKvListRemoveKey	(	CxList *	list,
		size_t	index )

Removes the key of a list item.

This can be useful if you want to explicitly remove an item from the lookup map.

If no key is associated with the item, nothing happens, and this function returns zero.

Parameters

list	the list
index	the index of the element in the list

Return values

zero	success
non-zero	the index is out of bounds