comparison: src/cx/list.h
src/cx/list.h
- changeset 1111
- 78eeeb950883
- parent 1109
- 89ec23988b88
- child 1162
- e3bb67b72d33
equal
deleted
inserted
replaced
| 1110:a0e9be7ed131 | 1111:78eeeb950883 |
|---|---|
| 278 */ | 278 */ |
| 279 cx_attr_nonnull | 279 cx_attr_nonnull |
| 280 int cx_list_default_swap(struct cx_list_s *list, size_t i, size_t j); | 280 int cx_list_default_swap(struct cx_list_s *list, size_t i, size_t j); |
| 281 | 281 |
| 282 /** | 282 /** |
| 283 * Initializes a list struct. | |
| 284 * | |
| 285 * Only use this function if you are creating your own list implementation. | |
| 286 * The purpose of this function is to be called in the initialization code | |
| 287 * of your list, to set certain members correctly. | |
| 288 * | |
| 289 * This is particularly important when you want your list to support | |
| 290 * #CX_STORE_POINTERS as @p elem_size. This function will wrap the list | |
| 291 * class accordingly and make sure that you can implement your list as if | |
| 292 * it was only storing objects and the wrapper will automatically enable | |
| 293 * the feature of storing pointers. | |
| 294 * | |
| 295 * @par Example | |
| 296 * | |
| 297 * @code | |
| 298 * CxList *myCustomListCreate( | |
| 299 * const CxAllocator *allocator, | |
| 300 * cx_compare_func comparator, | |
| 301 * size_t elem_size | |
| 302 * ) { | |
| 303 * if (allocator == NULL) { | |
| 304 * allocator = cxDefaultAllocator; | |
| 305 * } | |
| 306 * | |
| 307 * MyCustomList *list = cxCalloc(allocator, 1, sizeof(MyCustomList)); | |
| 308 * if (list == NULL) return NULL; | |
| 309 * | |
| 310 * // initialize | |
| 311 * cx_list_init((CxList*)list, &my_custom_list_class, | |
| 312 * allocator, comparator, elem_size); | |
| 313 * | |
| 314 * // ... some more custom stuff ... | |
| 315 * | |
| 316 * return (CxList *) list; | |
| 317 * } | |
| 318 * @endcode | |
| 319 * | |
| 320 * @param list the list to initialize | |
| 321 * @param cl the list class | |
| 322 * @param allocator the allocator for the elements | |
| 323 * @param comparator a compare function for the elements | |
| 324 * @param elem_size the size of one element | |
| 325 */ | |
| 326 cx_attr_nonnull_arg(1, 2, 3) | |
| 327 void cx_list_init( | |
| 328 struct cx_list_s *list, | |
| 329 struct cx_list_class_s *cl, | |
| 330 const struct cx_allocator_s *allocator, | |
| 331 cx_compare_func comparator, | |
| 332 size_t elem_size | |
| 333 ); | |
| 334 | |
| 335 /** | |
| 283 * Common type for all list implementations. | 336 * Common type for all list implementations. |
| 284 */ | 337 */ |
| 285 typedef struct cx_list_s CxList; | 338 typedef struct cx_list_s CxList; |
| 286 | |
| 287 /** | |
| 288 * Advises the list to store copies of the objects (default mode of operation). | |
| 289 * | |
| 290 * Retrieving objects from this list will yield pointers to the copies stored | |
| 291 * within this list. | |
| 292 * | |
| 293 * @param list the list | |
| 294 * @see cxListStorePointers() | |
| 295 */ | |
| 296 cx_attr_nonnull | |
| 297 void cxListStoreObjects(CxList *list); | |
| 298 | |
| 299 /** | |
| 300 * Advises the list to only store pointers to the objects. | |
| 301 * | |
| 302 * Retrieving objects from this list will yield the original pointers stored. | |
| 303 * | |
| 304 * @note This function forcibly sets the element size to the size of a pointer. | |
| 305 * Invoking this function on a non-empty list that already stores copies of | |
| 306 * objects is undefined. | |
| 307 * | |
| 308 * @param list the list | |
| 309 * @see cxListStoreObjects() | |
| 310 */ | |
| 311 cx_attr_nonnull | |
| 312 void cxListStorePointers(CxList *list); | |
| 313 | |
| 314 /** | |
| 315 * Returns true, if this list is storing pointers instead of the actual data. | |
| 316 * | |
| 317 * @param list | |
| 318 * @return true, if this list is storing pointers | |
| 319 * @see cxListStorePointers() | |
| 320 */ | |
| 321 cx_attr_nonnull | |
| 322 static inline bool cxListIsStoringPointers(const CxList *list) { | |
| 323 return list->collection.store_pointer; | |
| 324 } | |
| 325 | 339 |
| 326 /** | 340 /** |
| 327 * Returns the number of elements currently stored in the list. | 341 * Returns the number of elements currently stored in the list. |
| 328 * | 342 * |
| 329 * @param list the list | 343 * @param list the list |
