Mercurial > hg > ucx / file revision

 /*

  * 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

 #ifndef CX_STORE_POINTERS

 /**

  * Special constant used for creating collections that are storing pointers.

  */

 #define CX_STORE_POINTERS 0

 #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 const *cl;

     /**

      * The actual implementation in case the list class is delegating.

      */

     cx_list_class const *climpl;

     /**

      * The allocator to use.

      */

     CxAllocator const *allocator;

     /**

      * 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;

     union {

         /**

          * An optional simple destructor for the list contents that admits the free() interface.

          *

          * @remark Set content_destructor_type to #CX_DESTRUCTOR_SIMPLE.

          *

          * @attention Read the documentation of the particular list implementation

          * whether this destructor shall only destroy the contents or also free the memory.

          */

         cx_destructor_func simple_destructor;

         /**

          * An optional advanced destructor for the list contents providing additional data.

          *

          * @remark Set content_destructor_type to #CX_DESTRUCTOR_ADVANCED.

          *

          * @attention Read the documentation of the particular list implementation

          * whether this destructor shall only destroy the contents or also free the memory.

          */

         cx_advanced_destructor advanced_destructor;

     };

     /**

      * The type of destructor to use.

      */

     enum cx_destructor_type content_destructor_type;

 };

 /**

  * The class definition for arbitrary lists.

  */

 struct cx_list_class_s {

     /**

      * Destructor function.

      */

     void (*destructor)(struct cx_list_s *list);

     /**

      * Member function for inserting a single elements.

      * Implementors SHOULD see to performant implementations for corner cases.

      */

     int (*insert_element)(

             struct cx_list_s *list,

             size_t index,

             void const *data

     );

     /**

      * Member function for inserting multiple elements.

      * Implementors SHOULD see to performant implementations for corner cases.

      */

     size_t (*insert_array)(

             struct cx_list_s *list,

             size_t index,

             void const *data,

             size_t n

     );

     /**

      * Member function for inserting an element relative to an iterator position.

      */

     int (*insert_iter)(

             struct cx_mut_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 removing all elements.

      */

     void (*clear)(struct cx_list_s *list);

     /**

      * Member function for swapping two elements.

      */

     int (*swap)(

             struct cx_list_s *list,

             size_t i,

             size_t j

     );

     /**

      * 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);

     /**

      * Member function for returning an iterator pointing to the specified index.

      */

     struct cx_iterator_s (*iterator)(

             struct cx_list_s const *list,

             size_t index,

             bool backward

     );

 };

 /**

  * Common type for all list implementations.

  */

 typedef struct cx_list_s CxList;

 /**

  * Invokes the configured destructor function for a specific element.

  *

  * Usually only used by list implementations. There should be no need

  * to invoke this function manually.

  *

  * @param list the list

  * @param elem the element

  */

 __attribute__((__nonnull__))

 void cx_list_invoke_destructor(

         struct cx_list_s const *list,

         void *elem

 );

 /**

  * Invokes the simple destructor function for a specific element.

  *

  * Usually only used by list implementations. There should be no need

  * to invoke this function manually.

  *

  * @param list the list

  * @param elem the element

  */

 __attribute__((__nonnull__))

 void cx_list_invoke_simple_destructor(

         struct cx_list_s const *list,

         void *elem

 );

 /**

  * Invokes the advanced destructor function for a specific element.

  *

  * Usually only used by list implementations. There should be no need

  * to invoke this function manually.

  *

  * @param list the list

  * @param elem the element

  */

 __attribute__((__nonnull__))

 void cx_list_invoke_advanced_destructor(

         struct cx_list_s const *list,

         void *elem

 );

 /**

  * Advises the list to store copies of the objects (default mode of operation).

  *

  * Retrieving objects from this list will yield pointers to the copies stored

  * within this list.

  *

  * @param list the list

  * @see cxListStorePointers()

  */

 __attribute__((__nonnull__))

 void cxListStoreObjects(CxList *list);

 /**

  * Advises the list to only store pointers to the objects.

  *

  * Retrieving objects from this list will yield the original pointers stored.

  *

  * @note This function forcibly sets the element size to the size of a pointer.

  * Invoking this function on a non-empty list that already stores copies of

  * objects is undefined.

  *

  * @param list the list

  * @see cxListStoreObjects()

  */

 __attribute__((__nonnull__))

 void cxListStorePointers(CxList *list);

 /**

  * Returns true, if this list is storing pointers instead of the actual data.

  *

  * @param list

  * @return

  * @see cxListStorePointers()

  */

 __attribute__((__nonnull__))

 bool cxListIsStoringPointers(CxList const *list);

 /**

  * 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

  * @see cxListAddArray()

  */

 __attribute__((__nonnull__))

 static inline int cxListAdd(

         CxList *list,

         void const *elem

 ) {

     return list->cl->insert_element(list, list->size, elem);

 }

 /**

  * Adds multiple items to the end of the list.

  *

  * This method is more efficient than invoking cxListAdd() multiple times.

  *

  * If there is not enough memory to add all elements, the returned value is

  * less than \p n.

  *

  * If this list is storing pointers instead of objects \p array is expected to

  * be an array of pointers.

  *

  * @param list the list

  * @param array a pointer to the elements to add

  * @param n the number of elements to add

  * @return the number of added elements

  */

 __attribute__((__nonnull__))

 static inline size_t cxListAddArray(

         CxList *list,

         void const *array,

         size_t n

 ) {

     return list->cl->insert_array(list, list->size, array, n);

 }

 /**

  * 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()

  */

 __attribute__((__nonnull__))

 static inline int cxListInsert(

         CxList *list,

         size_t index,

         void const *elem

 ) {

     return list->cl->insert_element(list, index, elem);

 }

 /**

  * Inserts multiple items to the list at the specified index.

  * If \p index equals the list size, this is effectively cxListAddArray().

  *

  * This method is usually more efficient than invoking cxListInsert()

  * multiple times.

  *

  * If there is not enough memory to add all elements, the returned value is

  * less than \p n.

  *

  * If this list is storing pointers instead of objects \p array is expected to

  * be an array of pointers.

  *

  * @param list the list

  * @param index the index where to add the elements

  * @param array a pointer to the elements to add

  * @param n the number of elements to add

  * @return the number of added elements

  */

 __attribute__((__nonnull__))

 static inline size_t cxListInsertArray(

         CxList *list,

         size_t index,

         void const *array,

         size_t n

 ) {

     return list->cl->insert_array(list, index, array, n);

 }

 /**

  * 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()

  */

 __attribute__((__nonnull__))

 static inline int cxListInsertAfter(

         CxMutIterator *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()

  */

 __attribute__((__nonnull__))

 static inline int cxListInsertBefore(

         CxMutIterator *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.

  *

  * If an element destructor function is specified, it is called before

  * removing the element.

  *

  * @param list the list

  * @param index the index of the element

  * @return zero on success, non-zero if the index is out of bounds

  */

 __attribute__((__nonnull__))

 static inline int cxListRemove(

         CxList *list,

         size_t index

 ) {

     return list->cl->remove(list, index);

 }

 /**

  * Removes all elements from this list.

  *

  * If an element destructor function is specified, it is called for each

  * element before removing them.

  *

  * @param list the list

  */

 __attribute__((__nonnull__))

 static inline void cxListClear(CxList *list) {

     list->cl->clear(list);

 }

 /**

  * Swaps two items in the list.

  *

  * Implementations should only allocate temporary memory for the swap, if

  * it is necessary.

  *

  * @param list the list

  * @param i the index of the first element

  * @param j the index of the second element

  * @return zero on success, non-zero if one of the indices is out of bounds

  */

 __attribute__((__nonnull__))

 static inline int cxListSwap(

         CxList *list,

         size_t i,

         size_t j

 ) {

     return list->cl->swap(list, i, j);

 }

 /**

  * 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

  */

 __attribute__((__nonnull__))

 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

  */

 __attribute__((__nonnull__, __warn_unused_result__))

 static inline CxIterator cxListIteratorAt(

         CxList const *list,

         size_t index

 ) {

     return list->cl->iterator(list, index, false);

 }

 /**

  * Returns a backwards 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

  */

 __attribute__((__nonnull__, __warn_unused_result__))

 static inline CxIterator cxListBackwardsIteratorAt(

         CxList const *list,

         size_t index

 ) {

     return list->cl->iterator(list, index, true);

 }

 /**

  * Returns a mutating 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

  */

 __attribute__((__nonnull__, __warn_unused_result__))

 CxMutIterator cxListMutIteratorAt(

         CxList *list,

         size_t index

 );

 /**

  * Returns a mutating backwards 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

  */

 __attribute__((__nonnull__, __warn_unused_result__))

 CxMutIterator cxListMutBackwardsIteratorAt(

         CxList *list,

         size_t 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

  */

 __attribute__((__nonnull__, __warn_unused_result__))

 static inline CxIterator cxListIterator(CxList const *list) {

     return list->cl->iterator(list, 0, false);

 }

 /**

  * Returns a mutating 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

  */

 __attribute__((__nonnull__, __warn_unused_result__))

 static inline CxMutIterator cxListMutIterator(CxList *list) {

     return cxListMutIteratorAt(list, 0);

 }

 /**

  * Returns a backwards iterator pointing to the last 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

  */

 __attribute__((__nonnull__, __warn_unused_result__))

 static inline CxIterator cxListBackwardsIterator(CxList const *list) {

     return list->cl->iterator(list, list->size - 1, true);

 }

 /**

  * Returns a mutating backwards iterator pointing to the last 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

  */

 __attribute__((__nonnull__, __warn_unused_result__))

 static inline CxMutIterator cxListMutBackwardsIterator(CxList *list) {

     return cxListMutBackwardsIteratorAt(list, list->size - 1);

 }

 /**

  * 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

  */

 __attribute__((__nonnull__))

 static inline size_t cxListFind(

         CxList const *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

  */

 __attribute__((__nonnull__))

 static inline void cxListSort(CxList *list) {

     list->cl->sort(list);

 }

 /**

  * Reverses the order of the items.

  *

  * @param list the list

  */

 __attribute__((__nonnull__))

 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, positive if the first list is larger

  */

 __attribute__((__nonnull__))

 int cxListCompare(

         CxList const *list,

         CxList const *other

 );

 /**

  * Deallocates the memory of the specified list structure.

  *

  * Also calls content a destructor function, depending on the configuration

  * in CxList.content_destructor_type.

  *

  * This function itself is a destructor function for the CxList.

  *

  * @param list the list which shall be destroyed

  */

 __attribute__((__nonnull__))

 void cxListDestroy(CxList *list);

 #ifdef __cplusplus

 } // extern "C"

 #endif

 #endif // UCX_LIST_H