dbutils: comparison ucx/cx/collection.h

-:862ab606ee06
+:04c9f8d8f03b
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */
 /**
-* \file collection.h
+* @file collection.h
-* \brief Common definitions for various collection implementations.
+* @brief Common definitions for various collection implementations.
-* \author Mike Becker
+* @author Mike Becker
-* \author Olaf Wintermann
+* @author Olaf Wintermann
-* \copyright 2-Clause BSD License
+* @copyright 2-Clause BSD License
 */
 #ifndef UCX_COLLECTION_H
 #define UCX_COLLECTION_H
 /**
 * Indicates if this list is supposed to store pointers
 * instead of copies of the actual objects.
 */
 bool store_pointer;
+/**
+* Indicates if this collection is guaranteed to be sorted.
+* Note that the elements can still be sorted, even when the collection is not aware of that.
+*/
+bool sorted;
 };
 /**
 * Use this macro to declare common members for a collection structure.
+*
+* @par Example Use
+* @code
+* struct MyCustomSet {
+*     CX_COLLECTION_BASE;
+*     MySetElements *data;
+* }
+* @endcode
 */
 #define CX_COLLECTION_BASE struct cx_collection_s collection
 /**
+* Returns the number of elements currently stored.
+*
+* @param c a pointer to a struct that contains #CX_COLLECTION_BASE
+* @return (@c size_t) the number of currently stored elements
+*/
+#define cxCollectionSize(c) ((c)->collection.size)
+/**
+* Returns the size of one element.
+*
+* If #cxCollectionStoresPointers() returns true, this is the size of a pointer.
+*
+* @param c a pointer to a struct that contains #CX_COLLECTION_BASE
+* @return (@c size_t) the size of one element in bytes
+*/
+#define cxCollectionElementSize(c) ((c)->collection.elem_size)
+/**
+* Indicates whether this collection only stores pointers instead of the actual data.
+*
+* @param c a pointer to a struct that contains #CX_COLLECTION_BASE
+* @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)
+/**
+* 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 whether it keeps track of the order of its elements.
+*
+* @param c a pointer to a struct that contains #CX_COLLECTION_BASE
+* @retval true if the elements are currently sorted wrt. the collection's compare function
+* @retval false if the order of elements is unknown
+*/
+#define cxCollectionSorted(c) ((c)->collection.sorted)
+/**
 * Sets a simple destructor function for this collection.
 *
-* @param c the collection
+* @param c a pointer to a struct that contains #CX_COLLECTION_BASE
 * @param destr the destructor function
 */
 #define cxDefineDestructor(c, destr) \
 (c)->collection.simple_destructor = (cx_destructor_func) destr
 /**
 * Sets a simple destructor function for this collection.
 *
-* @param c the collection
+* @param c a pointer to a struct that contains #CX_COLLECTION_BASE
 * @param destr the destructor function
 */
 #define cxDefineAdvancedDestructor(c, destr, data) \
 (c)->collection.advanced_destructor = (cx_destructor_func2) destr; \
 (c)->collection.destructor_data = data
 * 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.
 *
-* @param c the collection
+* When the collection stores pointers, those pointers are directly passed
-* @param e the element
+* to the destructor. Otherwise, a pointer to the element is passed.
+*
+* @param c a pointer to a struct that contains #CX_COLLECTION_BASE
+* @param e the element (the type is @c void* or @c void** depending on context)
 */
 #define cx_invoke_simple_destructor(c, e) \
 (c)->collection.simple_destructor((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.
 *
-* @param c the collection
+* When the collection stores pointers, those pointers are directly passed
-* @param e the element
+* to the destructor. Otherwise, a pointer to the element is passed.
+*
+* @param c a pointer to a struct that contains #CX_COLLECTION_BASE
+* @param e the element (the type is @c void* or @c void** depending on context)
 */
 #define cx_invoke_advanced_destructor(c, e) \
 (c)->collection.advanced_destructor((c)->collection.destructor_data, \
 (c)->collection.store_pointer ? (*((void **) (e))) : (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.
 *
-* @param c the collection
+* When the collection stores pointers, those pointers are directly passed
-* @param e the element
+* to the destructor. Otherwise, a pointer to the element is passed.
+*
+* @param c a pointer to a struct that contains #CX_COLLECTION_BASE
+* @param e the element (the type is @c void* or @c void** depending on context)
 */
 #define cx_invoke_destructor(c, e) \
 if ((c)->collection.simple_destructor) cx_invoke_simple_destructor(c,e); \
 if ((c)->collection.advanced_destructor) cx_invoke_advanced_destructor(c,e)

Mercurial > hg > dbutils / file comparison

comparison: ucx/cx/collection.h

ucx/cx/collection.h