Generic associative array. More...

#include <stdbool.h>
#include <sys/types.h>
#include "datatypes.h"

Data Structures
struct	AssocArray
	Array containing associations between keys and values. More...

struct	AssocArray::_AssocArrayPair
	A key-value pair. More...

Macros
#define	ASSOC_ARRAY_MAX_SIZE (SSIZE_MAX / sizeof(void *))

#define	assoc_array_pair_key(p) p->array->keys[p->offset]

#define	assoc_array_pair_value(p) p->array->values[p->offset]

#define	assoc_array_iter_key(iter) iter.array->keys[iter.offset]

#define	assoc_array_iter_value(iter) iter.array->values[iter.offset]

Typedefs
typedef struct _AssocArrayPair	AssocArrayPair

typedef struct _AssocArrayPair	AssocArrayIter

Enumerations
enum	AssocArrayInsertResult { ASSOCARRAY_INSERT_RESULT_NEW , ASSOCARRAY_INSERT_RESULT_REPLACED , ASSOCARRAY_INSERT_RESULT_FAILED }
	result of assoc_array_set() method. More...

Functions
AssocArray *	assoc_array_new (CompareFunc compare_keys, FreeFunc free_key, FreeFunc free_value)

void	assoc_array_init (AssocArray *array, CompareFunc compare_keys, FreeFunc free_key, FreeFunc free_value)

void	assoc_array_destroy (AssocArray *array)

void	assoc_array_free (AssocArray *array)

void	assoc_array_clear (AssocArray *array)

AssocArrayInsertResult	assoc_array_set (AssocArray array, void key, void *value, bool overwrite_key)

void	assoc_array_remove (AssocArray array, const void key)

AssocArrayPair *	assoc_array_lookup (AssocArray array, const void key)

void *	assoc_array_pair_get_key (const AssocArrayPair *pair)

void *	assoc_array_pair_get_value (const AssocArrayPair *pair)

void	assoc_array_pair_set_value (AssocArrayPair pair, void value)

bool	assoc_array_key_exists (const AssocArray array, const void key)

size_t	assoc_array_count (const AssocArray *array)

size_t	assoc_array_size (const AssocArray *array)

void	assoc_array_iter_init (const AssocArray array, AssocArrayIter iter)

bool	assoc_array_iter_next (AssocArrayIter *iter)

void *	assoc_array_iter_get_key (const AssocArrayIter *iter)

void *	assoc_array_iter_get_value (const AssocArrayIter *iter)

Detailed Description

Generic associative array.

Author: Sebastian Fedrau sebas.nosp@m.tian.nosp@m..fedr.nosp@m.au@g.nosp@m.mail..nosp@m.com

Definition in file assocarray.h.

Data Structure Documentation

◆ AssocArray

struct AssocArray

Array containing associations between keys and values.

Definition at line 37 of file assocarray.h.

Data Fields
CompareFunc	compare_keys	Function to compare two keys.
size_t	count	Number of inserted values.
FreeFunc	free_key	Function to free keys.
FreeFunc	free_value	Function to free values.
void **	keys	Sorted array containing keys.
struct _AssocArrayPair	pair	Last found key-value pair.
size_t	size	Size of the array.
void **	values	Array containing values.

◆ AssocArray::_AssocArrayPair

struct AssocArray::_AssocArrayPair

A key-value pair.

Definition at line 60 of file assocarray.h.

Data Fields
const struct _AssocArray *	array	Reference to the array.
ssize_t	offset	Index of the found key-value pair.

Macro Definition Documentation

◆ assoc_array_iter_key

#define assoc_array_iter_key ( iter ) iter.array->keys[iter.offset]

Accesses the key of the current element directly.

Definition at line 240 of file assocarray.h.

◆ assoc_array_iter_value

#define assoc_array_iter_value ( iter ) iter.array->values[iter.offset]

Accesses the value of the current element directly.

Definition at line 251 of file assocarray.h.

◆ ASSOC_ARRAY_MAX_SIZE

#define ASSOC_ARRAY_MAX_SIZE (SSIZE_MAX / sizeof(void *))

Supported maximum size.

Definition at line 31 of file assocarray.h.

◆ assoc_array_pair_key

#define assoc_array_pair_key ( p ) p->array->keys[p->offset]

Accesses the key of a key-value pair directly.

Definition at line 168 of file assocarray.h.

◆ assoc_array_pair_value

#define assoc_array_pair_value ( p ) p->array->values[p->offset]

Accesses the value of a key-value pair directly.

Definition at line 179 of file assocarray.h.

Typedef Documentation

◆ AssocArrayIter

typedef struct _AssocArrayPair AssocArrayIter

A structure to iterate over the elements of an AssocArray.

Definition at line 73 of file assocarray.h.

◆ AssocArrayPair

typedef struct _AssocArrayPair AssocArrayPair

A found key-value pair.

Definition at line 70 of file assocarray.h.

Enumeration Type Documentation

◆ AssocArrayInsertResult

enum AssocArrayInsertResult

result of assoc_array_set() method.

Enumerator
ASSOCARRAY_INSERT_RESULT_NEW	Item has been inserted.
ASSOCARRAY_INSERT_RESULT_REPLACED	Item has been replaced.
ASSOCARRAY_INSERT_RESULT_FAILED	Item insertion failed.

Definition at line 79 of file assocarray.h.

Function Documentation

◆ assoc_array_clear()

void assoc_array_clear ( AssocArray * array )

Parameters

array an AssocArray

Removes all elements from the AssocArray.

Definition at line 170 of file assocarray.c.

◆ assoc_array_count()

size_t assoc_array_count ( const AssocArray * array )

Parameters

array an AssocArray

Returns: number of stored elements

Gets the number of stored elements.

Definition at line 437 of file assocarray.c.

◆ assoc_array_destroy()

void assoc_array_destroy ( AssocArray * array )

Parameters

array an AssocArray

Frees all keys, values and the array pointer.

Definition at line 128 of file assocarray.c.

◆ assoc_array_free()

void assoc_array_free ( AssocArray * array )

Parameters

array an AssocArray

Frees all keys and values without freeing the array pointer.

Definition at line 159 of file assocarray.c.

◆ assoc_array_init()

void assoc_array_init	(	AssocArray *	array,
		CompareFunc	compare_keys,
		FreeFunc	free_key,
		FreeFunc	free_value
	)

Parameters

array	an AssocArray
compare_keys	function to compare two keys
free_key	function to free keys or NULL
free_value	function to free values or NULL

Initializes an AssocArray.

Definition at line 97 of file assocarray.c.

◆ assoc_array_iter_get_key()

void * assoc_array_iter_get_key ( const AssocArrayIter * iter )

Parameters

iter	an AssocArrayIter

Returns: key of current element

Retrieves the key of the current element.

Definition at line 473 of file assocarray.c.

◆ assoc_array_iter_get_value()

void * assoc_array_iter_get_value ( const AssocArrayIter * iter )

Parameters

iter	an AssocArrayIter

Returns: value of current element

Retrieves the value of the current element.

Definition at line 481 of file assocarray.c.

◆ assoc_array_iter_init()

void assoc_array_iter_init	(	const AssocArray *	array,
		AssocArrayIter *	iter
	)

Parameters

array	an AssocArray
iter	an uninitialized AssocArrayIter

Initializes a key/value pair iterator and associates it with the array. Modifying the array while using the iterator might lead to undefined behaviour.

Definition at line 453 of file assocarray.c.

◆ assoc_array_iter_next()

bool assoc_array_iter_next ( AssocArrayIter * iter )

Parameters

iter	an AssocArrayIter

Returns: false if end of the AssocArray has been reached

Goes to next element of an AssocArray.

Definition at line 463 of file assocarray.c.

◆ assoc_array_key_exists()

bool assoc_array_key_exists	(	const AssocArray *	array,
		const void *	key
	)

Parameters

array	an AssocArray
key	key to test

Returns: true if given key does exist

Checks if a key does exist.

Definition at line 421 of file assocarray.c.

◆ assoc_array_lookup()

AssocArrayPair * assoc_array_lookup	(	AssocArray *	array,
		const void *	key
	)

Parameters

array	an AssocArray
key	key to lookup

Returns: the found key-value pair or NULL.

Looks up a key-value pair in the AssocArray.

Definition at line 368 of file assocarray.c.

◆ assoc_array_new()

AssocArray * assoc_array_new	(	CompareFunc	compare_keys,
		FreeFunc	free_key,
		FreeFunc	free_value
	)

Parameters

compare_keys	function to compare two keys
free_key	function to free keys or NULL
free_value	function to free values or NULL

Returns: a new AssocArray

Creates a new AssocArray.

Definition at line 79 of file assocarray.c.

◆ assoc_array_pair_get_key()

void * assoc_array_pair_get_key ( const AssocArrayPair * pair )

Parameters

pair	a key-value pair

Returns: key of the pair

Retrieves the key of a key-value pair.

Definition at line 389 of file assocarray.c.

◆ assoc_array_pair_get_value()

void * assoc_array_pair_get_value ( const AssocArrayPair * pair )

Parameters

pair	a key-value pair

Returns: value of the pair

Retrieves the value of a key-value pair.

Definition at line 398 of file assocarray.c.

◆ assoc_array_pair_set_value()

void assoc_array_pair_set_value	(	AssocArrayPair *	pair,
		void *	value
	)

Parameters

pair	a AssocArrayPair
value	new value to set

Overwrites the value of a key-value pair.

Definition at line 407 of file assocarray.c.

◆ assoc_array_remove()

void assoc_array_remove	(	AssocArray *	array,
		const void *	key
	)

Parameters

array	an AssocArray
key	key of the element to remove

Removes an element from the AssocArray.

Definition at line 335 of file assocarray.c.

◆ assoc_array_set()

AssocArrayInsertResult assoc_array_set	(	AssocArray *	array,
		void *	key,
		void *	value,
		bool	overwrite_key
	)

Parameters

array	an AssocArray
key	key to insert
value	the value to associate with the key
overwrite_key	true to overwrite already exisiting keys

Returns: type of the performed insert operation

Inserts a new key and value in the AssocArray. If overwrite_key is set an existing key is freed using the specified free_key function before it gets replaced.

Definition at line 288 of file assocarray.c.

◆ assoc_array_size()

size_t assoc_array_size ( const AssocArray * array )

Parameters

array an AssocArray

Returns: size of the array

Gets the size of the array.

Definition at line 445 of file assocarray.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ AssocArray

◆ AssocArray::_AssocArrayPair

Macro Definition Documentation

◆ assoc_array_iter_key

◆ assoc_array_iter_value

◆ ASSOC_ARRAY_MAX_SIZE

◆ assoc_array_pair_key

◆ assoc_array_pair_value

Typedef Documentation

◆ AssocArrayIter

◆ AssocArrayPair

Enumeration Type Documentation

◆ AssocArrayInsertResult

Function Documentation

◆ assoc_array_clear()

◆ assoc_array_count()

◆ assoc_array_destroy()

◆ assoc_array_free()

◆ assoc_array_init()

◆ assoc_array_iter_get_key()

◆ assoc_array_iter_get_value()

◆ assoc_array_iter_init()

◆ assoc_array_iter_next()

◆ assoc_array_key_exists()

◆ assoc_array_lookup()

◆ assoc_array_new()

◆ assoc_array_pair_get_key()

◆ assoc_array_pair_get_value()

◆ assoc_array_pair_set_value()

◆ assoc_array_remove()

◆ assoc_array_set()

◆ assoc_array_size()