Fri, 25 Feb 2022 14:35:18 +0100
add setup and teardown functions to test_list.c
/* * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. * * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are met: * * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN * 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 list.h * \brief Interface for list implementations. * \author Mike Becker * \author Olaf Wintermann * \version 3.0 * \copyright 2-Clause BSD License */ #ifndef UCX_LIST_H #define UCX_LIST_H #include "common.h" #include "allocator.h" #include "iterator.h" #ifdef __cplusplus extern "C" { #endif /** * A comparator function comparing two list elements. */ typedef int(*CxListComparator)( void const *left, void const *right ); /** * List class type. */ typedef struct cx_list_class_s cx_list_class; /** * Structure for holding the base data of a list. */ struct cx_list_s { /** * The list class definition. */ cx_list_class *cl; /** * The allocator to use. */ CxAllocator *allocator; /** * A mandatory destructor for the list structure. */ cx_destructor_func list_destructor; /** * An optional destructor for the list contents. */ cx_destructor_func content_destructor; /** * The comparator function for the elements. */ CxListComparator cmpfunc; /** * The size of each element (payload only). */ size_t itemsize; /** * The size of the list (number of currently stored elements). */ size_t size; /** * The capacity of the list (maximum number of elements). */ size_t capacity; /** * Flag indicating whether cxListDestroy() shall free the list structure, * even if cx_list_s.list_destructor did not do that. */ bool autofree; /** * Flag indicating whether cxListDestroy() shall free each list element, * even if cx_list_s.content_destructor did not do that. */ bool autofree_contents; }; /** * The class definition for arbitrary lists. */ struct cx_list_class_s { /** * Member function for adding an element. */ int (*add)( struct cx_list_s *list, void const *elem ); /** * Member function for inserting an element. */ int (*insert)( struct cx_list_s *list, size_t index, void const *elem ); /** * Member function for inserting an element relative to an iterator position. */ int (*insert_iter)( struct cx_iterator_s *iter, void const *elem, int prepend ); /** * Member function for removing an element. */ int (*remove)( struct cx_list_s *list, size_t index ); /** * Member function for element lookup. */ void *(*at)( struct cx_list_s const *list, size_t index ); /** * Member function for finding an element. */ size_t (*find)( struct cx_list_s const *list, void const *elem ); /** * Member function for sorting the list in place. */ void (*sort)(struct cx_list_s *list); /** * Member function for comparing this list to another list of the same type. */ int (*compare)( struct cx_list_s const *list, struct cx_list_s const *other ); /** * Member function for reversing the order of the items. */ void (*reverse)(struct cx_list_s *list); /** * Returns an iterator pointing to the specified index. */ struct cx_iterator_s (*iterator)( struct cx_list_s *list, size_t index ); }; /** * Common type for all list implementations. */ typedef struct cx_list_s CxList; /** * Convenience function to configure the memory management for this list. * * @param list the list to configure * @param list_destructor an alternative list destructor to use (if \c NULL, the current destructor remains unchanged) * @param content_destructor the content destructor to use (if \c NULL, no content destructor is used) * @param list_autofree a flag indicating, if the list allocator shall free the list, if the destructor did not do that * @param content_autofree a flag indicating, if the list allocator shall free an element, * if the content destructor did not do that or no content destructor exists */ static inline void cxListMemoryMgmt( CxList *list, cx_destructor_func list_destructor, cx_destructor_func content_destructor, bool list_autofree, bool content_autofree ) { if (list_destructor != NULL) list->list_destructor = list_destructor; list->content_destructor = content_destructor; list->autofree = list_autofree; list->autofree_contents = content_autofree; } /** * Adds an item to the end of the list. * * @param list the list * @param elem a pointer to the element to add * @return zero on success, non-zero on memory allocation failure */ static inline int cxListAdd( CxList *list, void const *elem ) { return list->cl->add(list, elem); } /** * Inserts an item at the specified index. * * If \p index equals the list \c size, this is effectively cxListAdd(). * * @param list the list * @param index the index the element shall have * @param elem a pointer to the element to add * @return zero on success, non-zero on memory allocation failure * or when the index is out of bounds * @see cxListInsertAfter() * @see cxListInsertBefore() */ static inline int cxListInsert( CxList *list, size_t index, void const *elem ) { return list->cl->insert(list, index, elem); } /** * Inserts an element after the current location of the specified iterator. * * The used iterator remains operational, but all other active iterators should * be considered invalidated. * * If \p iter is not a list iterator, the behavior is undefined. * If \p iter is a past-the-end iterator, the new element gets appended to the list. * * @param iter an iterator * @param elem the element to insert * @return zero on success, non-zero on memory allocation failure * @see cxListInsert() * @see cxListInsertBefore() */ static inline int cxListInsertAfter( CxIterator *iter, void const *elem ) { return ((struct cx_list_s *) iter->src_handle)->cl->insert_iter(iter, elem, 0); } /** * Inserts an element before the current location of the specified iterator. * * The used iterator remains operational, but all other active iterators should * be considered invalidated. * * If \p iter is not a list iterator, the behavior is undefined. * If \p iter is a past-the-end iterator, the new element gets appended to the list. * * @param iter an iterator * @param elem the element to insert * @return zero on success, non-zero on memory allocation failure * @see cxListInsert() * @see cxListInsertAfter() */ static inline int cxListInsertBefore( CxIterator *iter, void const *elem ) { return ((struct cx_list_s *) iter->src_handle)->cl->insert_iter(iter, elem, 1); } /** * Removes the element at the specified index. * @param list the list * @param index the index of the element * @return zero on success, non-zero if the index is out of bounds */ static inline int cxListRemove( CxList *list, size_t index ) { return list->cl->remove(list, index); } /** * Returns a pointer to the element at the specified index. * * @param list the list * @param index the index of the element * @return a pointer to the element or \c NULL if the index is out of bounds */ static inline void *cxListAt( CxList *list, size_t index ) { return list->cl->at(list, index); } /** * Returns an iterator pointing to the item at the specified index. * * The returned iterator is position-aware. * * If the index is out of range, a past-the-end iterator will be returned. * * @param list the list * @param index the index where the iterator shall point at * @return a new iterator */ static inline CxIterator cxListIterator( CxList *list, size_t index ) { return list->cl->iterator(list, index); } /** * Returns an iterator pointing to the first item of the list. * * The returned iterator is position-aware. * * If the list is empty, a past-the-end iterator will be returned. * * @param list the list * @return a new iterator */ static inline CxIterator cxListBegin(CxList *list) { return list->cl->iterator(list, 0); } /** * Returns the index of the first element that equals \p elem. * * Determining equality is performed by the list's comparator function. * * @param list the list * @param elem the element to find * @return the index of the element or \c (size+1) if the element is not found */ static inline size_t cxListFind( CxList *list, void const *elem ) { return list->cl->find(list, elem); } /** * Sorts the list in place. * * \remark The underlying sort algorithm is implementation defined. * * @param list the list */ static inline void cxListSort(CxList *list) { list->cl->sort(list); } /** * Reverses the order of the items. * * @param list the list */ static inline void cxListReverse(CxList *list) { list->cl->reverse(list); } /** * Compares a list to another list of the same type. * * First, the list sizes are compared. If they match, the lists are compared element-wise. * * @param list the list * @param other the list to compare to * @return zero, if both lists are equal element wise, negative if the first list is smaller, zero if the first list is larger */ static inline int cxListCompare( CxList *list, CxList *other ) { return list->cl->compare(list, other); } /** * Calls the list's destructor function for every element. * If CxList.autofree_content is \c true, the elements are automatically free'd * unless the content destructor function did not already do that. * Similarly, if CxList.autofree is \c true, the list structure is free'd, unless * the list destructor function did not already do that. * * This function itself is a destructor function for the CxList. * * @param list the list which contents shall be destroyed * @return \p list if the list structure has been free'd during the process */ __attribute__((__nonnull__)) CxList *cxListDestroy(CxList *list); #ifdef __cplusplus } /* extern "C" */ #endif #endif /* UCX_LIST_H */