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

src/cx/list.h@0458bff0b1cd (annotated)

src/cx/list.h

Wed, 06 Oct 2021 14:10:19 +0200

author: Mike Becker <universe@uap-core.de>
date: Wed, 06 Oct 2021 14:10:19 +0200
changeset 469: 0458bff0b1cd
parent 464: 7fafc95968fc
child 474: 9c1fccda16bc
permissions: -rw-r--r--

add high level list sort and inlines method invocation functions

 /*
  * 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 <stdlib.h>
 #include "allocator.h"
 #ifdef __cplusplus
 extern "C" {
 #endif
 /**
  * A comparator function comparing two list elements.
  */
 typedef int(*CxListComparator)(void const *left, void const *right);
 /**
  * Internal type for the list structure - use CxList instead.
  */
 typedef struct cx_list_s cx_list_s;
 /**
  * The class definition for arbitrary lists.
  */
 typedef struct {
     /**
      * Member function for adding an element.
      */
     int (*add)(cx_list_s *list, void *elem);
     /**
      * Member function for inserting an element.
      */
     int (*insert)(cx_list_s *list, size_t index, void *elem);
     /**
      * Member function for removing an element.
      */
     int (*remove)(cx_list_s *list, size_t index);
     /**
      * Member function for element lookup.
      */
     void *(*at)(cx_list_s *list, size_t index);
     /**
      * Member function for finding an element.
      */
     size_t (*find)(cx_list_s *list, void *elem);
     /**
      * Member function for retrieving the last element.
      */
     void *(*last)(cx_list_s *list);
     /**
      * Member function for sorting the list in place.
      */
     void (*sort)(cx_list_s *list);
 } 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;
     /**
      * 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;
 };
 /**
  * Common type for all list implementations.
  */
 typedef cx_list_s *CxList;
 /**
  * Adds an item to the end of the list.
  *
  * \remark It is implementation defined whether
  * the contents of the element are copied or the
  * pointer is added to the list. In the latter case
  * the \c itemsize of the list SHALL be \c sizeof(void*).
  *
  * @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 *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().
  *
  * \remark It is implementation defined whether
  * the contents of the element are copied or the
  * pointer is added to the list. In the latter case
  * the \c itemsize of the list SHALL be \c sizeof(void*).
  *
  * @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
  */
 static inline int cxListInsert(CxList list, size_t index, void *elem) {
     return list->cl->insert(list, index, elem);
 }
 /**
  * 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 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 *elem) {
     return list->cl->find(list, elem);
 }
 /**
  * Returns a pointer to the last element of the list.
  *
  * This is effectively the same as cxListAt() with \c index=size-1, but
  * this implementation may be more efficient depending on the list structure
  * and the conrecte implementation of cxListAt().
  *
  * @param list the list
  * @return a pointer to the last element or \c NULL if the list is empty
  */
 static inline void *cxListLast(CxList list) {
     return list->cl->last(list);
 }
 /**
  * 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);
 }
 #ifdef __cplusplus
 } /* extern "C" */
 #endif
 #endif /* UCX_LIST_H */

Mercurial > hg > ucx / annotate

src/cx/list.h@0458bff0b1cd (annotated)

src/cx/list.h