120 * Destructor function. |
124 * Destructor function. |
121 */ |
125 */ |
122 void (*destructor)(struct cx_list_s *list); |
126 void (*destructor)(struct cx_list_s *list); |
123 |
127 |
124 /** |
128 /** |
|
129 * Member function for inserting a single elements. |
|
130 * Implementors SHOULD see to performant implementations for corner cases. |
|
131 */ |
|
132 int (*insert_element)( |
|
133 struct cx_list_s *list, |
|
134 size_t index, |
|
135 void const *data |
|
136 ); |
|
137 |
|
138 /** |
125 * Member function for inserting multiple elements. |
139 * Member function for inserting multiple elements. |
126 * Implementors SHOULD see to performant implementations for corner cases. |
140 * Implementors SHOULD see to performant implementations for corner cases. |
127 */ |
141 */ |
128 size_t (*insert_array)( |
142 size_t (*insert_array)( |
129 struct cx_list_s *list, |
143 struct cx_list_s *list, |
196 * Common type for all list implementations. |
210 * Common type for all list implementations. |
197 */ |
211 */ |
198 typedef struct cx_list_s CxList; |
212 typedef struct cx_list_s CxList; |
199 |
213 |
200 /** |
214 /** |
|
215 * Advises the list to store copies of the objects (default mode of operation). |
|
216 * |
|
217 * Retrieving objects from this list will yield pointers to the copies stored |
|
218 * within this list. |
|
219 * |
|
220 * @param list the list |
|
221 * @see cxListStorePointers() |
|
222 */ |
|
223 __attribute__((__nonnull__)) |
|
224 void cxListStoreObjects(CxList *list); |
|
225 |
|
226 /** |
|
227 * Advises the list to only store pointers to the objects. |
|
228 * |
|
229 * Retrieving objects from this list will yield the original pointers stored. |
|
230 * |
|
231 * @note This function forcibly sets the element size to the size of a pointer. |
|
232 * Invoking this function on a non-empty list that already stores copies of |
|
233 * objects is undefined. |
|
234 * |
|
235 * @param list the list |
|
236 * @see cxListStoreObjects() |
|
237 */ |
|
238 __attribute__((__nonnull__)) |
|
239 void cxListStorePointers(CxList *list); |
|
240 |
|
241 /** |
|
242 * Returns true, if this list is storing pointers instead of the actual data. |
|
243 * |
|
244 * @param list |
|
245 * @return |
|
246 * @see cxListStorePointers() |
|
247 */ |
|
248 __attribute__((__nonnull__)) |
|
249 bool cxListIsStoringPointers(CxList *list); |
|
250 |
|
251 /** |
201 * Adds an item to the end of the list. |
252 * Adds an item to the end of the list. |
202 * |
253 * |
203 * @param list the list |
254 * @param list the list |
204 * @param elem a pointer to the element to add |
255 * @param elem a pointer to the element to add |
205 * @return zero on success, non-zero on memory allocation failure |
256 * @return zero on success, non-zero on memory allocation failure |
208 __attribute__((__nonnull__)) |
259 __attribute__((__nonnull__)) |
209 static inline int cxListAdd( |
260 static inline int cxListAdd( |
210 CxList *list, |
261 CxList *list, |
211 void const *elem |
262 void const *elem |
212 ) { |
263 ) { |
213 return list->cl->insert_array(list, list->size, elem, 1) != 1; |
264 return list->cl->insert_element(list, list->size, elem); |
214 } |
265 } |
215 |
266 |
216 /** |
267 /** |
217 * Adds multiple items to the end of the list. |
268 * Adds multiple items to the end of the list. |
218 * |
269 * |
219 * This method is more efficient than invoking cxListAdd() multiple times. |
270 * This method is more efficient than invoking cxListAdd() multiple times. |
220 * |
271 * |
221 * If there is not enough memory to add all elements, the returned value is |
272 * If there is not enough memory to add all elements, the returned value is |
222 * less than \p n. |
273 * less than \p n. |
|
274 * |
|
275 * If this list is storing pointers instead of objects \p array is expected to |
|
276 * be an array of pointers. |
223 * |
277 * |
224 * @param list the list |
278 * @param list the list |
225 * @param array a pointer to the elements to add |
279 * @param array a pointer to the elements to add |
226 * @param n the number of elements to add |
280 * @param n the number of elements to add |
227 * @return the number of added elements |
281 * @return the number of added elements |
252 static inline int cxListInsert( |
306 static inline int cxListInsert( |
253 CxList *list, |
307 CxList *list, |
254 size_t index, |
308 size_t index, |
255 void const *elem |
309 void const *elem |
256 ) { |
310 ) { |
257 return list->cl->insert_array(list, index, elem, 1) != 1; |
311 return list->cl->insert_element(list, index, elem); |
258 } |
312 } |
259 |
313 |
260 /** |
314 /** |
261 * Inserts multiple items to the list at the specified index. |
315 * Inserts multiple items to the list at the specified index. |
262 * If \p index equals the list size, this is effectively cxListAddArray(). |
316 * If \p index equals the list size, this is effectively cxListAddArray(). |
264 * This method is usually more efficient than invoking cxListInsert() |
318 * This method is usually more efficient than invoking cxListInsert() |
265 * multiple times. |
319 * multiple times. |
266 * |
320 * |
267 * If there is not enough memory to add all elements, the returned value is |
321 * If there is not enough memory to add all elements, the returned value is |
268 * less than \p n. |
322 * less than \p n. |
|
323 * |
|
324 * If this list is storing pointers instead of objects \p array is expected to |
|
325 * be an array of pointers. |
269 * |
326 * |
270 * @param list the list |
327 * @param list the list |
271 * @param index the index where to add the elements |
328 * @param index the index where to add the elements |
272 * @param array a pointer to the elements to add |
329 * @param array a pointer to the elements to add |
273 * @param n the number of elements to add |
330 * @param n the number of elements to add |