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

src/cx/list.h@03e9151bea32 (annotated)

src/cx/list.h

Tue, 15 Feb 2022 20:01:59 +0100

author: Mike Becker <universe@uap-core.de>
date: Tue, 15 Feb 2022 20:01:59 +0100
changeset 505: 03e9151bea32
parent 504: aaf89ce0cbf6
child 508: 8aea65ae1eaf
permissions: -rw-r--r--

fix typo in documentation

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

Mercurial > hg > ucx / annotate

src/cx/list.h@03e9151bea32 (annotated)

src/cx/list.h