ucx: comparison src/cx/collection.h

-:d4385f35f8b0
+:ef7cab6eb131
 /**
 * The allocator to use.
 */
 const CxAllocator *allocator;
 /**
-* The comparator function for the elements.
-*/
-cx_compare_func cmpfunc;
-/**
 * The size of each element.
 */
 size_t elem_size;
 /**
 * The number of currently stored elements.
 */
 size_t size;
+/**
+* A two-argument comparator function for the elements.
+*/
+cx_compare_func simple_cmp;
+/**
+* A three-argument comparator function for the elements.
+* If specified, this function has precedence over the @c simple_cmp function.
+*/
+cx_compare_func2 advanced_cmp;
+/**
+* A pointer to custom data for the @c advanced_cmp function
+*/
+void *cmp_data;
 /**
 * An optional simple destructor for the collection's elements.
 *
 * @attention Read the documentation of the particular collection implementation
 * whether this destructor shall only destroy the contents or also free the memory.
 * @retval true if this collection stores only pointers to data
 * @retval false if this collection stores the actual element's data
 */
 #define cxCollectionStoresPointers(c) ((c)->collection.store_pointer)
+/**
+* Convenience macro for adding indirection to an element if the collection is storing pointers.
+*
+* @param c a pointer to a struct that contains #CX_COLLECTION_BASE
+* @param elem the pointer that shall be taken the address from, if the collection is storing pointers
+* @return if the collection is storing pointers, takes the address of @p elem, otherwise returns @p elem
+*/
+#define cx_ref(c, elem) (cxCollectionStoresPointers(c) ? ((void*)&(elem)) : (elem))
+/**
+* Convenience macro for dereferencing an element if the collection is storing pointers.
+*
+* @param c a pointer to a struct that contains #CX_COLLECTION_BASE
+* @param elem a pointer to the collection element
+* @return if the collection is storing pointers, dereferences @p elem, otherwise returns @p elem
+*/
+#define cx_deref(c, elem) (cxCollectionStoresPointers(c) ? *((void**)(elem)) : (elem))
 /**
 * Indicates whether the collection can guarantee that the stored elements are currently sorted.
 *
 * This may return @c 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.
 * @retval false if the order of elements is unknown
 */
 #define cxCollectionSorted(c) ((c)->collection.sorted || (c)->collection.size == 0)
 /**
-* Sets the compare function for a collection.
+* Sets a simple compare function for a collection.
 *
-* @param c a pointer to a struct that contains #CX_COLLECTION_BASE
+* Erases a possible advanced compare function.
-* @param func (@c cx_compare_func) the compare function that shall be used by @c c
+* 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.
-#define cxSetCompareFunc(c, func) (c)->collection.cmpfunc = (cx_compare_func)(func)
+*
+* @param c a pointer to a struct that contains #CX_COLLECTION_BASE
+* @param func (@c cx_compare_func) the compare function
+*/
+#define cxSetCompareFunc(c, func) \
+(c)->collection.simple_cmp = (cx_compare_func)(func); \
+(c)->collection.advanced_cmp = NULL
+/**
+* Sets an advanced compare function that supports custom data for a collection.
+*
+* @param c a pointer to a struct that contains #CX_COLLECTION_BASE
+* @param func (@c cx_compare_func2) the compare function
+* @param data (@c void*) the pointer to custom data that is passed to the compare function
+*/
+#define cxSetAdvancedCompareFunc(c, func, data) \
+(c)->collection.advanced_cmp = (cx_compare_func2) func; \
+(c)->collection.destructor_data = data
+/**
+* Invokes the simple comparator function for two elements.
+*
+* Usually only used by collection implementations. There should be no need
+* to invoke this macro manually.
+*
+* @param c a pointer to a struct that contains #CX_COLLECTION_BASE
+* @param left (@c void*) pointer to data
+* @param right (@c void*) pointer to data
+*/
+#define cx_invoke_simple_compare_func(c, left, right) \
+(c)->collection.simple_cmp(left, right)
+/**
+* Invokes the advanced comparator function for two elements.
+*
+* Usually only used by collection implementations. There should be no need
+* to invoke this macro manually.
+*
+* @param c a pointer to a struct that contains #CX_COLLECTION_BASE
+* @param left (@c void*) pointer to data
+* @param right (@c void*) pointer to data
+*/
+#define cx_invoke_advanced_compare_func(c, left, right) \
+(c)->collection.advanced_cmp(left, right, (c)->collection.cmp_data)
+/**
+* Invokes the configured comparator function for two elements.
+*
+* Usually only used by collection implementations. There should be no need
+* to invoke this macro manually.
+*
+* @param c a pointer to a struct that contains #CX_COLLECTION_BASE
+* @param left (@c void*) pointer to data
+* @param right (@c void*) pointer to data
+*/
+#define cx_invoke_compare_func(c, left, right) \
+(((c)->collection.advanced_cmp) ? \
+cx_invoke_advanced_compare_func(c,left,right) : \
+cx_invoke_simple_compare_func(c,left,right))
 /**
 * Sets a simple destructor function for this collection.
 *
 * @param c a pointer to a struct that contains #CX_COLLECTION_BASE
-* @param destr the destructor function
+* @param destr (@c cx_destructor_func) the destructor function
 */
 #define cxSetDestructor(c, destr) \
 (c)->collection.simple_destructor = (cx_destructor_func) destr
 /**
-* Sets a simple destructor function for this collection.
+* Sets an advanced destructor function for this collection.
 *
 * @param c a pointer to a struct that contains #CX_COLLECTION_BASE
-* @param destr the destructor function
+* @param destr (@c cx_destructor_func2) the destructor function
+* @param data (@c void*) the additional data the advanced destructor is invoked with
 */
 #define cxSetAdvancedDestructor(c, destr, data) \
 (c)->collection.advanced_destructor = (cx_destructor_func2) destr; \
 (c)->collection.destructor_data = data

Mercurial > hg > ucx / file comparison

comparison: src/cx/collection.h

src/cx/collection.h