src/cx/list.h@9138acaa494b
src/cx/list.h
Tue, 28 Dec 2021 17:24:18 +0100
- author
- Mike Becker <universe@uap-core.de>
- date
- Tue, 28 Dec 2021 17:24:18 +0100
- changeset 488
- 9138acaa494b
- parent 484
- 9e6900b1cf9d
- child 489
- af6be1e123aa
- permissions
- -rw-r--r--
add cxLinkedListFromArray() and cxListCompare()
1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are met:
8 *
9 * 1. Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * 2. Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26 * POSSIBILITY OF SUCH DAMAGE.
27 */
28 /**
29 * \file list.h
30 * \brief Interface for list implementations.
31 * \author Mike Becker
32 * \author Olaf Wintermann
33 * \version 3.0
34 * \copyright 2-Clause BSD License
35 */
37 #ifndef UCX_LIST_H
38 #define UCX_LIST_H
40 #include "common.h"
41 #include "allocator.h"
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
47 /**
48 * A comparator function comparing two list elements.
49 */
50 typedef int(*CxListComparator)(void const *left, void const *right);
52 /**
53 * Internal type for the list structure - use CxList instead.
54 */
55 typedef struct cx_list_s cx_list_s;
57 /**
58 * The class definition for arbitrary lists.
59 */
60 typedef struct {
61 /**
62 * Member function for adding an element.
63 */
64 int (*add)(cx_list_s *list, void *elem);
66 /**
67 * Member function for inserting an element.
68 */
69 int (*insert)(cx_list_s *list, size_t index, void *elem);
71 /**
72 * Member function for removing an element.
73 */
74 int (*remove)(cx_list_s *list, size_t index);
76 /**
77 * Member function for element lookup.
78 */
79 void *(*at)(cx_list_s *list, size_t index);
81 /**
82 * Member function for finding an element.
83 */
84 size_t (*find)(
85 cx_list_s *list,
86 void *elem
87 );
89 /**
90 * Member function for sorting the list in place.
91 */
92 void (*sort)(cx_list_s *list);
94 /**
95 * Member function for comparing this list to another list of the same type.
96 */
97 int (*compare)(
98 cx_list_s *list,
99 cx_list_s *other
100 );
101 } cx_list_class;
103 /**
104 * Structure for holding the base data of a list.
105 */
106 struct cx_list_s {
107 /**
108 * The list class definition.
109 */
110 cx_list_class *cl;
111 /**
112 * The allocator to use.
113 */
114 CxAllocator allocator;
115 /**
116 * The comparator function for the elements.
117 */
118 CxListComparator cmpfunc;
119 /**
120 * The size of each element (payload only).
121 */
122 size_t itemsize;
123 /**
124 * The size of the list (number of currently stored elements).
125 */
126 size_t size;
127 /**
128 * The capacity of the list (maximum number of elements).
129 */
130 size_t capacity;
131 };
133 /**
134 * Common type for all list implementations.
135 */
136 typedef cx_list_s *CxList;
138 /**
139 * Adds an item to the end of the list.
140 *
141 * \remark It is implementation defined whether
142 * the contents of the element are copied or the
143 * pointer is added to the list. In the latter case
144 * the \c itemsize of the list SHALL be \c sizeof(void*).
145 *
146 * @param list the list
147 * @param elem a pointer to the element to add
148 * @return zero on success, non-zero on memory allocation failure
149 */
150 static inline int cxListAdd(CxList list, void *elem) {
151 return list->cl->add(list, elem);
152 }
154 /**
155 * Inserts an item at the specified index.
156 *
157 * If \p index equals the list \c size, this is effectively cxListAdd().
158 *
159 * \remark It is implementation defined whether
160 * the contents of the element are copied or the
161 * pointer is added to the list. In the latter case
162 * the \c itemsize of the list SHALL be \c sizeof(void*).
163 *
164 * @param list the list
165 * @param index the index the element shall have
166 * @param elem a pointer to the element to add
167 * @return zero on success, non-zero on memory allocation failure
168 * or when the index is out of bounds
169 */
170 static inline int cxListInsert(CxList list, size_t index, void *elem) {
171 return list->cl->insert(list, index, elem);
172 }
174 /**
175 * Removes the element at the specified index.
176 * @param list the list
177 * @param index the index of the element
178 * @return zero on success, non-zero if the index is out of bounds
179 */
180 static inline int cxListRemove(CxList list, size_t index) {
181 return list->cl->remove(list, index);
182 }
184 /**
185 * Returns a pointer to the element at the specified index.
186 *
187 * @param list the list
188 * @param index the index of the element
189 * @return a pointer to the element or \c NULL if the index is out of bounds
190 */
191 static inline void *cxListAt(CxList list, size_t index) {
192 return list->cl->at(list, index);
193 }
195 /**
196 * Returns the index of the first element that equals \p elem.
197 *
198 * Determining equality is performed by the list's comparator function.
199 *
200 * @param list the list
201 * @param elem the element to find
202 * @return the index of the element or \c (size+1) if the element is not found
203 */
204 static inline size_t cxListFind(CxList list, void *elem) {
205 return list->cl->find(list, elem);
206 }
208 /**
209 * Sorts the list in place.
210 *
211 * \remark The underlying sort algorithm is implementation defined.
212 *
213 * @param list the list
214 */
215 static inline void cxListSort(CxList list) {
216 list->cl->sort(list);
217 }
219 /**
220 * Compares a list to another list of the same type.
221 *
222 * First, the list sizes are compared. If they match, the lists are compared element-wise.
223 *
224 * @param list the list
225 * @param other the list to compare to
226 * @return zero, if both lists are equal element wise, negative if the first list is smaller, zero if the first list is larger
227 */
228 static inline int cxListCompare(
229 CxList list,
230 CxList other
231 ) {
232 return list->cl->compare(list, other);
233 }
235 #ifdef __cplusplus
236 } /* extern "C" */
237 #endif
239 #endif /* UCX_LIST_H */
