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