Mercurial > hg > ucx / changeset

     1.1 --- a/src/cx/list.h	Tue Oct 05 12:19:19 2021 +0200
     1.2 +++ b/src/cx/list.h	Tue Oct 05 12:23:46 2021 +0200
     1.3 @@ -44,45 +44,156 @@
     1.4  extern "C" {
     1.5  #endif
     1.6  
     1.7 +/**
     1.8 + * A comparator function comparing two list elements.
     1.9 + */
    1.10  typedef int(*CxListComparator)(void const *left, void const *right);
    1.11  
    1.12 +/**
    1.13 + * Internal type for the list structure - use CxList instead.
    1.14 + */
    1.15  typedef struct cx_list_s cx_list_s;
    1.16  
    1.17 +/**
    1.18 + * The class definition for arbitrary lists.
    1.19 + */
    1.20  typedef struct {
    1.21 +    /**
    1.22 +     * Member function for adding an element.
    1.23 +     */
    1.24      int (*add)(cx_list_s *list, void *elem);
    1.25  
    1.26 +    /**
    1.27 +     * Member function for inserting an element.
    1.28 +     */
    1.29      int (*insert)(cx_list_s *list, size_t index, void *elem);
    1.30  
    1.31 +    /**
    1.32 +     * Member function for removing an element.
    1.33 +     */
    1.34      int (*remove)(cx_list_s *list, size_t index);
    1.35  
    1.36 +    /**
    1.37 +     * Member function for element lookup.
    1.38 +     */
    1.39      void *(*at)(cx_list_s *list, size_t index);
    1.40  
    1.41 +    /**
    1.42 +     * Member function for finding an element.
    1.43 +     */
    1.44      size_t (*find)(cx_list_s *list, void *elem);
    1.45  
    1.46 +    /**
    1.47 +     * Member function for retrieving the last element.
    1.48 +     */
    1.49      void *(*last)(cx_list_s *list);
    1.50  } cx_list_class;
    1.51  
    1.52 +/**
    1.53 + * Structure for holding the base data of a list.
    1.54 + */
    1.55  struct cx_list_s {
    1.56 +    /**
    1.57 +     * The list class definition.
    1.58 +     */
    1.59      cx_list_class *cl;
    1.60 +    /**
    1.61 +     * The allocator to use.
    1.62 +     */
    1.63      CxAllocator allocator;
    1.64 +    /**
    1.65 +     * The comparator function for the elements.
    1.66 +     */
    1.67      CxListComparator cmpfunc;
    1.68 +    /**
    1.69 +     * The size of each element (payload only).
    1.70 +     */
    1.71      size_t itemsize;
    1.72 +    /**
    1.73 +     * The size of the list (number of currently stored elements).
    1.74 +     */
    1.75      size_t size;
    1.76 +    /**
    1.77 +     * The capacity of the list (maximum number of elements).
    1.78 +     */
    1.79      size_t capacity;
    1.80  };
    1.81  
    1.82 +/**
    1.83 + * Common type for all list implementations.
    1.84 + */
    1.85  typedef cx_list_s *CxList;
    1.86  
    1.87 +/**
    1.88 + * Adds an item to the end of the list.
    1.89 + *
    1.90 + * \remark It is implementation defined whether
    1.91 + * the contents of the element are copied or the
    1.92 + * pointer is added to the list. In the latter case
    1.93 + * the \c itemsize of the list SHALL be \c sizeof(void*).
    1.94 + *
    1.95 + * @param list the list
    1.96 + * @param elem a pointer to the element to add
    1.97 + * @return zero on success, non-zero on memory allocation failure
    1.98 + */
    1.99  int cxListAdd(CxList list, void *elem);
   1.100  
   1.101 +/**
   1.102 + * Inserts an item at the specified index.
   1.103 + *
   1.104 + * If \p index equals the list \c size, this is effectively cxListAdd().
   1.105 + *
   1.106 + * \remark It is implementation defined whether
   1.107 + * the contents of the element are copied or the
   1.108 + * pointer is added to the list. In the latter case
   1.109 + * the \c itemsize of the list SHALL be \c sizeof(void*).
   1.110 + *
   1.111 + * @param list the list
   1.112 + * @param index the index the element shall have
   1.113 + * @param elem a pointer to the element to add
   1.114 + * @return zero on success, non-zero on memory allocation failure
   1.115 + * or when the index is out of bounds
   1.116 + */
   1.117  int cxListInsert(CxList list, size_t index, void *elem);
   1.118  
   1.119 +/**
   1.120 + * Removes the element at the specified index.
   1.121 + * @param list the list
   1.122 + * @param index the index of the element
   1.123 + * @return zero on success, non-zero if the index is out of bounds
   1.124 + */
   1.125  int cxListRemove(CxList list, size_t index);
   1.126  
   1.127 +/**
   1.128 + * Returns a pointer to the element at the specified index.
   1.129 + *
   1.130 + * @param list the list
   1.131 + * @param index the index of the element
   1.132 + * @return a pointer to the element or \c NULL if the index is out of bounds
   1.133 + */
   1.134  void *cxListAt(CxList list, size_t index);
   1.135  
   1.136 +/**
   1.137 + * Returns the index of the first element that equals \p elem.
   1.138 + *
   1.139 + * Determining equality is performed by the list's comparator function.
   1.140 + *
   1.141 + * @param list the list
   1.142 + * @param elem the element to find
   1.143 + * @return the index of the element or \c (size+1) if the element is not found
   1.144 + */
   1.145  size_t cxListFind(CxList list, void *elem);
   1.146  
   1.147 +/**
   1.148 + * Returns a pointer to the last element of the list.
   1.149 + *
   1.150 + * This is effectively the same as cxListAt() with \c index=size-1, but
   1.151 + * this implementation may be more efficient depending on the list structure
   1.152 + * and the conrecte implementation of cxListAt().
   1.153 + *
   1.154 + * @param list the list
   1.155 + * @return a pointer to the last element or \c NULL if the list is empty
   1.156 + */
   1.157  void *cxListLast(CxList list);
   1.158  
   1.159  #ifdef __cplusplus