collection.h File Reference

Common definitions for various collection implementations. More...

#include "allocator.h"
#include "iterator.h"
#include "compare.h"

Go to the source code of this file.

Data Structures
struct	cx_collection_s
	Base attributes of a collection. More...

Macros
#define	CX_STORE_POINTERS   0
	Special constant used for creating collections that are storing pointers.
#define	CX_COLLECTION_BASE   struct cx_collection_s collection
	Use this macro to declare common members for a collection structure.
#define	cxCollectionSize(c)
	Returns the number of elements currently stored.
#define	cxCollectionElementSize(c)
	Returns the size of one element.
#define	cxCollectionStoresPointers(c)
	Indicates whether this collection only stores pointers instead of the actual data.
#define	cx_ref(c, elem)
	Convenience macro for adding indirection to an element if the collection is storing pointers.
#define	cx_deref(c, elem)
	Convenience macro for dereferencing an element if the collection is storing pointers.
#define	cxCollectionSorted(c)
	Indicates whether the collection can guarantee that the stored elements are currently sorted.
#define	cxSetCompareFunc(c, func)
	Sets a simple compare function for a collection.
#define	cxSetAdvancedCompareFunc(c, func, data)
	Sets an advanced compare function that supports custom data for a collection.
#define	cx_invoke_simple_compare_func(c, left, right)
	Invokes the simple comparator function for two elements.
#define	cx_invoke_advanced_compare_func(c, left, right)
	Invokes the advanced comparator function for two elements.
#define	cx_invoke_compare_func(c, left, right)
	Invokes the configured comparator function for two elements.
#define	cxSetDestructor(c, destr)
	Sets a simple destructor function for this collection.
#define	cxSetAdvancedDestructor(c, destr, data)
	Sets an advanced destructor function for this collection.
#define	cx_invoke_simple_destructor(c, e)
	Invokes the simple destructor function for a specific element.
#define	cx_invoke_advanced_destructor(c, e)
	Invokes the advanced destructor function for a specific element.
#define	cx_invoke_destructor(c, e)
	Invokes all available destructor functions for a specific element.
#define	cx_invoke_destructor_raw(c, e)
	Invokes all available destructor functions for a specific element.

Detailed Description

Common definitions for various collection implementations.

Author

Mike Becker

Olaf Wintermann

Copyright

2-Clause BSD License

Macro Definition Documentation

CX_COLLECTION_BASE

#define CX_COLLECTION_BASE   struct cx_collection_s collection

Use this macro to declare common members for a collection structure.

Example Use

struct MyCustomSet {
    CX_COLLECTION_BASE;
    MySetElements *data;
}

cx_deref

#define cx_deref	(		c,
			elem )

Value:

(cxCollectionStoresPointers(c) ? *((void**)(elem)) : (elem))

Convenience macro for dereferencing an element if the collection is storing pointers.

Parameters

c	a pointer to a struct that contains CX_COLLECTION_BASE
elem	a pointer to the collection element

Returns

if the collection is storing pointers, dereferences elem, otherwise returns elem

cx_invoke_advanced_compare_func

#define cx_invoke_advanced_compare_func	(		c,
			left,
			right )

Value:

    (c)->collection.advanced_cmp(left, right, (c)->collection.cmp_data)

Invokes the advanced comparator function for two elements.

Usually only used by collection implementations. There should be no need to invoke this macro manually.

Parameters

c	a pointer to a struct that contains CX_COLLECTION_BASE
left	(void*) pointer to data
right	(void*) pointer to data

cx_invoke_advanced_destructor

#define cx_invoke_advanced_destructor	(		c,
			e )

Value:

    (c)->collection.advanced_destructor((c)->collection.destructor_data, \
    (c)->collection.store_pointer ? (*((void **) (e))) : (e))

Invokes the advanced destructor function for a specific element.

Usually only used by collection implementations. There should be no need to invoke this macro manually.

When the collection stores pointers, those pointers are directly passed to the destructor. Otherwise, a pointer to the element is passed.

Parameters

c	a pointer to a struct that contains CX_COLLECTION_BASE
e	the element (the type is void* or void** depending on context)

cx_invoke_compare_func

#define cx_invoke_compare_func	(		c,
			left,
			right )

Value:

    (((c)->collection.advanced_cmp) ? \
    cx_invoke_advanced_compare_func(c,left,right) : \
    cx_invoke_simple_compare_func(c,left,right))

Invokes the configured comparator function for two elements.

Usually only used by collection implementations. There should be no need to invoke this macro manually.

Parameters

c	a pointer to a struct that contains CX_COLLECTION_BASE
left	(void*) pointer to data
right	(void*) pointer to data

cx_invoke_destructor

#define cx_invoke_destructor	(		c,
			e )

Value:

    if ((c)->collection.simple_destructor) cx_invoke_simple_destructor(c,e); \
    if ((c)->collection.advanced_destructor) cx_invoke_advanced_destructor(c,e)

Invokes all available destructor functions for a specific element.

Usually only used by collection implementations. There should be no need to invoke this macro manually.

When the collection stores pointers, those pointers are directly passed to the destructor. Otherwise, a pointer to the element is passed.

Parameters

c	a pointer to a struct that contains CX_COLLECTION_BASE
e	the element (the type is void* or void** depending on context)

cx_invoke_destructor_raw

#define cx_invoke_destructor_raw	(		c,
			e )

Value:

    if ((c)->collection.simple_destructor) (c)->collection.simple_destructor(e); \
    if ((c)->collection.advanced_destructor) (c)->collection.advanced_destructor((c)->collection.destructor_data, e)

Invokes all available destructor functions for a specific element.

Usually only used by collection implementations. There should be no need to invoke this macro manually.

In contrast to cx_invoke_destructor(), this macro does not automatically dereference pointers to the elements when cxCollectionStoresPointers() returns true.

Parameters

c	a pointer to a struct that contains CX_COLLECTION_BASE
e	pointer to the element

cx_invoke_simple_compare_func

#define cx_invoke_simple_compare_func	(		c,
			left,
			right )

Value:

    (c)->collection.simple_cmp(left, right)

Invokes the simple comparator function for two elements.

Usually only used by collection implementations. There should be no need to invoke this macro manually.

Parameters

c	a pointer to a struct that contains CX_COLLECTION_BASE
left	(void*) pointer to data
right	(void*) pointer to data

cx_invoke_simple_destructor

#define cx_invoke_simple_destructor	(		c,
			e )

Value:

    (c)->collection.simple_destructor((c)->collection.store_pointer ? (*((void **) (e))) : (e))

Invokes the simple destructor function for a specific element.

Usually only used by collection implementations. There should be no need to invoke this macro manually.

When the collection stores pointers, those pointers are directly passed to the destructor. Otherwise, a pointer to the element is passed.

Parameters

c	a pointer to a struct that contains CX_COLLECTION_BASE
e	the element (the type is void* or void** depending on context)

cx_ref

#define cx_ref	(		c,
			elem )

Value:

(cxCollectionStoresPointers(c) ? ((void*)&(elem)) : (elem))

Convenience macro for adding indirection to an element if the collection is storing pointers.

Parameters

c	a pointer to a struct that contains CX_COLLECTION_BASE
elem	the pointer that shall be taken the address from, if the collection is storing pointers

Returns

if the collection is storing pointers, takes the address of elem, otherwise returns elem

cxCollectionElementSize

#define cxCollectionElementSize

(

c

)

Value:

((c)->collection.elem_size)

Returns the size of one element.

If cxCollectionStoresPointers() returns true, this is the size of a pointer.

Parameters

c	a pointer to a struct that contains CX_COLLECTION_BASE

Returns

(size_t) the size of one element in bytes

cxCollectionSize

#define cxCollectionSize

(

c

)

Value:

((c)->collection.size)

Returns the number of elements currently stored.

Parameters

c	a pointer to a struct that contains CX_COLLECTION_BASE

Returns

(size_t) the number of currently stored elements

cxCollectionSorted

#define cxCollectionSorted

(

c

)

Value:

((c)->collection.sorted || (c)->collection.size == 0)

Indicates whether the collection can guarantee that the stored elements are currently sorted.

This may return false even when the elements are sorted. It is totally up to the implementation of the collection when to check if the elements are sorted. It is usually a good practice to establish this property as an invariant that does not need to be re-checked on certain operations.

Parameters

c	a pointer to a struct that contains CX_COLLECTION_BASE

Return values

true	if the elements are currently sorted wrt. the collection's compare function
false	if the order of elements is unknown

cxCollectionStoresPointers

#define cxCollectionStoresPointers

(

c

)

Value:

((c)->collection.store_pointer)

Indicates whether this collection only stores pointers instead of the actual data.

Parameters

c	a pointer to a struct that contains CX_COLLECTION_BASE

Return values

true	if this collection stores only pointers to data
false	if this collection stores the actual element's data

cxSetAdvancedCompareFunc

#define cxSetAdvancedCompareFunc	(		c,
			func,
			data )

Value:

    (c)->collection.advanced_cmp = (cx_compare_func2) func; \
    (c)->collection.cmp_data = data

Sets an advanced compare function that supports custom data for a collection.

Parameters

c	a pointer to a struct that contains CX_COLLECTION_BASE
func	(cx_compare_func2) the compare function
data	(void*) the pointer to custom data that is passed to the compare function

cxSetAdvancedDestructor

#define cxSetAdvancedDestructor	(		c,
			destr,
			data )

Value:

    (c)->collection.advanced_destructor = (cx_destructor_func2) destr; \
    (c)->collection.destructor_data = data

Sets an advanced destructor function for this collection.

Parameters

c	a pointer to a struct that contains CX_COLLECTION_BASE
destr	(cx_destructor_func2) the destructor function
data	(void*) the additional data the advanced destructor is invoked with

cxSetCompareFunc

#define cxSetCompareFunc	(		c,
			func )

Value:

    (c)->collection.simple_cmp = (cx_compare_func)(func); \
    (c)->collection.advanced_cmp = NULL

Sets a simple compare function for a collection.

Erases a possible advanced compare function. If you want to set both, because you want to access the simple function in your advanced function, you must set the simple function first.

Parameters

c	a pointer to a struct that contains CX_COLLECTION_BASE
func	(cx_compare_func) the compare function

cxSetDestructor

#define cxSetDestructor	(		c,
			destr )

Value:

    (c)->collection.simple_destructor = (cx_destructor_func) destr

Sets a simple destructor function for this collection.

Parameters

c	a pointer to a struct that contains CX_COLLECTION_BASE
destr	(cx_destructor_func) the destructor function