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	cxCollectionSorted(c)
	Indicates whether the collection can guarantee that the stored elements are currently sorted.
#define	cxCollectionCompareFunc(c, func)
	Sets the compare function for a collection.
#define	cxDefineDestructor(c, destr)
	Sets a simple destructor function for this collection.
#define	cxDefineAdvancedDestructor(c, destr, data)
	Sets a simple 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.

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

cxCollectionCompareFunc

#define cxCollectionCompareFunc	(		c,
			func )

Value:

(c)->collection.cmpfunc = (func)

Sets the compare function for a collection.

Parameters

c	a pointer to a struct that contains CX_COLLECTION_BASE
func	(cx_compare_func) the compare function that shall be used by c

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

cxDefineAdvancedDestructor

#define cxDefineAdvancedDestructor	(		c,
			destr,
			data )

Value:

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

Sets a simple destructor function for this collection.

Parameters

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

cxDefineDestructor

#define cxDefineDestructor	(		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	the destructor function