universe@677: /* universe@677: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. universe@677: * universe@677: * Copyright 2023 Mike Becker, Olaf Wintermann All rights reserved. universe@677: * universe@677: * Redistribution and use in source and binary forms, with or without universe@677: * modification, are permitted provided that the following conditions are met: universe@677: * universe@677: * 1. Redistributions of source code must retain the above copyright universe@677: * notice, this list of conditions and the following disclaimer. universe@677: * universe@677: * 2. Redistributions in binary form must reproduce the above copyright universe@677: * notice, this list of conditions and the following disclaimer in the universe@677: * documentation and/or other materials provided with the distribution. universe@677: * universe@677: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" universe@677: * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE universe@677: * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE universe@677: * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE universe@677: * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR universe@677: * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF universe@677: * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS universe@677: * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN universe@677: * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) universe@677: * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE universe@677: * POSSIBILITY OF SUCH DAMAGE. universe@677: */ universe@677: /** universe@677: * \file collection.h universe@677: * \brief Common definitions for various collection implementations. universe@677: * \author Mike Becker universe@677: * \author Olaf Wintermann universe@677: * \copyright 2-Clause BSD License universe@677: */ universe@677: universe@677: #ifndef UCX_COLLECTION_H universe@677: #define UCX_COLLECTION_H universe@677: universe@677: #include "allocator.h" universe@677: #include "iterator.h" universe@854: #include "compare.h" universe@677: universe@677: #ifdef __cplusplus universe@677: extern "C" { universe@677: #endif universe@677: universe@677: /** universe@677: * Special constant used for creating collections that are storing pointers. universe@677: */ universe@677: #define CX_STORE_POINTERS 0 universe@677: universe@677: /** universe@854: * Base attributes of a collection. universe@677: */ universe@854: struct cx_collection_s { universe@854: /** universe@854: * The allocator to use. universe@854: */ universe@854: CxAllocator const *allocator; universe@854: /** universe@854: * The comparator function for the elements. universe@854: */ universe@854: cx_compare_func cmpfunc; universe@854: /** universe@854: * The size of each element. universe@854: */ universe@855: size_t elem_size; universe@854: /** universe@854: * The number of currently stored elements. universe@854: */ universe@854: size_t size; universe@854: /** universe@854: * An optional simple destructor for the collection's elements. universe@854: * universe@854: * @attention Read the documentation of the particular collection implementation universe@854: * whether this destructor shall only destroy the contents or also free the memory. universe@854: */ universe@854: cx_destructor_func simple_destructor; universe@854: /** universe@854: * An optional advanced destructor for the collection's elements. universe@854: * universe@854: * @attention Read the documentation of the particular collection implementation universe@854: * whether this destructor shall only destroy the contents or also free the memory. universe@854: */ universe@854: cx_destructor_func2 advanced_destructor; universe@854: /** universe@854: * The pointer to additional data that is passed to the advanced destructor. universe@854: */ universe@854: void *destructor_data; universe@854: /** universe@854: * Indicates if this list is supposed to store pointers universe@854: * instead of copies of the actual objects. universe@854: */ universe@854: bool store_pointer; universe@854: }; universe@677: universe@677: /** universe@677: * Use this macro to declare common members for a collection structure. universe@677: */ universe@856: #define CX_COLLECTION_BASE struct cx_collection_s collection universe@677: universe@677: /** universe@857: * Sets a simple destructor function for this collection. universe@857: * universe@857: * @param c the collection universe@857: * @param destr the destructor function universe@857: */ universe@857: #define cxDefineDestructor(c, destr) \ universe@857: (c)->collection.simple_destructor = (cx_destructor_func) destr universe@857: universe@857: /** universe@857: * Sets a simple destructor function for this collection. universe@857: * universe@857: * @param c the collection universe@857: * @param destr the destructor function universe@857: */ universe@857: #define cxDefineAdvancedDestructor(c, destr, data) \ universe@857: (c)->collection.advanced_destructor = (cx_destructor_func2) destr; \ universe@857: (c)->collection.destructor_data = data universe@857: universe@857: /** universe@677: * Invokes the simple destructor function for a specific element. universe@677: * universe@677: * Usually only used by collection implementations. There should be no need universe@677: * to invoke this macro manually. universe@677: * universe@677: * @param c the collection universe@677: * @param e the element universe@677: */ universe@677: #define cx_invoke_simple_destructor(c, e) \ universe@856: (c)->collection.simple_destructor((c)->collection.store_pointer ? (*((void **) (e))) : (e)) universe@677: universe@677: /** universe@677: * Invokes the advanced destructor function for a specific element. universe@677: * universe@677: * Usually only used by collection implementations. There should be no need universe@677: * to invoke this macro manually. universe@677: * universe@677: * @param c the collection universe@677: * @param e the element universe@677: */ universe@677: #define cx_invoke_advanced_destructor(c, e) \ universe@856: (c)->collection.advanced_destructor((c)->collection.destructor_data, \ universe@856: (c)->collection.store_pointer ? (*((void **) (e))) : (e)) universe@677: universe@677: universe@712: /** universe@712: * Invokes all available destructor functions for a specific element. universe@712: * universe@712: * Usually only used by collection implementations. There should be no need universe@712: * to invoke this macro manually. universe@712: * universe@712: * @param c the collection universe@712: * @param e the element universe@712: */ universe@677: #define cx_invoke_destructor(c, e) \ universe@856: if ((c)->collection.simple_destructor) cx_invoke_simple_destructor(c,e); \ universe@856: if ((c)->collection.advanced_destructor) cx_invoke_advanced_destructor(c,e) universe@677: universe@677: #ifdef __cplusplus universe@677: } // extern "C" universe@677: #endif universe@677: universe@677: #endif // UCX_COLLECTION_H