ucx: src/cx/list.h@dce9b8450656 (annotated)

src/cx/list.h@dce9b8450656 (annotated)

src/cx/list.h

Tue, 28 Mar 2023 19:13:33 +0200

author: Mike Becker <universe@uap-core.de>
date: Tue, 28 Mar 2023 19:13:33 +0200
changeset 669: dce9b8450656
parent 667: 2f88a7c13a28
child 677: b09aae58bba4
permissions: -rw-r--r--

add docs for CX_STORE_POINTERS and remove cxHashMapCreateForPointers()

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

Mercurial > hg > ucx / annotate

src/cx/list.h@dce9b8450656 (annotated)

src/cx/list.h