Mercurial > hg > toolkit / file comparison

comparison: ucx/cx/list.h

ucx/cx/list.h

changeset 1040
473d8cb58a6c
parent 1016
ccde46662db7
equal deleted inserted replaced
1039:6691e007cef7 1040:473d8cb58a6c
37 #define UCX_LIST_H 37 #define UCX_LIST_H
38 38
39 #include "common.h" 39 #include "common.h"
40 #include "collection.h" 40 #include "collection.h"
41 41
42 #ifdef __cplusplus
43 extern "C" {
44 #endif
45
46 /** 42 /**
47 * List class type. 43 * List class type.
48 */ 44 */
49 typedef struct cx_list_class_s cx_list_class; 45 typedef struct cx_list_class_s cx_list_class;
50 46
204 * @param index the index where to insert the data 200 * @param index the index where to insert the data
205 * @param data a pointer to the array of data to insert 201 * @param data a pointer to the array of data to insert
206 * @param n the number of elements to insert 202 * @param n the number of elements to insert
207 * @return the number of elements actually inserted 203 * @return the number of elements actually inserted
208 */ 204 */
209 cx_attr_nonnull 205 CX_EXTERN CX_NONNULL_ARG(1)
210 CX_EXPORT size_t cx_list_default_insert_array(struct cx_list_s *list, 206 size_t cx_list_default_insert_array(struct cx_list_s *list,
211 size_t index, const void *data, size_t n); 207 size_t index, const void *data, size_t n);
212 208
213 /** 209 /**
214 * Default implementation of a sorted insert. 210 * Default implementation of a sorted insert.
215 * 211 *
224 * @param list the list 220 * @param list the list
225 * @param sorted_data a pointer to the array of pre-sorted data to insert 221 * @param sorted_data a pointer to the array of pre-sorted data to insert
226 * @param n the number of elements to insert 222 * @param n the number of elements to insert
227 * @return the number of elements actually inserted 223 * @return the number of elements actually inserted
228 */ 224 */
229 cx_attr_nonnull 225 CX_EXTERN CX_NONNULL
230 CX_EXPORT size_t cx_list_default_insert_sorted(struct cx_list_s *list, 226 size_t cx_list_default_insert_sorted(struct cx_list_s *list,
231 const void *sorted_data, size_t n); 227 const void *sorted_data, size_t n);
232 228
233 /** 229 /**
234 * Default implementation of an array insert where only elements are inserted when they don't exist in the list. 230 * Default implementation of an array insert where only elements are inserted when they don't exist in the list.
235 * 231 *
244 * @param list the list 240 * @param list the list
245 * @param sorted_data a pointer to the array of pre-sorted data to insert 241 * @param sorted_data a pointer to the array of pre-sorted data to insert
246 * @param n the number of elements to insert 242 * @param n the number of elements to insert
247 * @return the number of elements from the @p sorted_data that are definitely present in the list after this call 243 * @return the number of elements from the @p sorted_data that are definitely present in the list after this call
248 */ 244 */
249 cx_attr_nonnull 245 CX_EXTERN CX_NONNULL
250 CX_EXPORT size_t cx_list_default_insert_unique(struct cx_list_s *list, 246 size_t cx_list_default_insert_unique(struct cx_list_s *list,
251 const void *sorted_data, size_t n); 247 const void *sorted_data, size_t n);
252 248
253 /** 249 /**
254 * Default unoptimized sort implementation. 250 * Default unoptimized sort implementation.
255 * 251 *
259 * Use this in your own list class if you do not want to implement an optimized 255 * Use this in your own list class if you do not want to implement an optimized
260 * version for your list. 256 * version for your list.
261 * 257 *
262 * @param list the list that shall be sorted 258 * @param list the list that shall be sorted
263 */ 259 */
264 cx_attr_nonnull 260 CX_EXTERN CX_NONNULL
265 CX_EXPORT void cx_list_default_sort(struct cx_list_s *list); 261 void cx_list_default_sort(struct cx_list_s *list);
266 262
267 /** 263 /**
268 * Default unoptimized swap implementation. 264 * Default unoptimized swap implementation.
269 * 265 *
270 * Use this in your own list class if you do not want to implement an optimized 266 * Use this in your own list class if you do not want to implement an optimized
275 * @param j index of the other element 271 * @param j index of the other element
276 * @retval zero success 272 * @retval zero success
277 * @retval non-zero when indices are out of bounds or memory 273 * @retval non-zero when indices are out of bounds or memory
278 * allocation for the temporary buffer fails 274 * allocation for the temporary buffer fails
279 */ 275 */
280 cx_attr_nonnull 276 CX_EXTERN CX_NONNULL
281 CX_EXPORT int cx_list_default_swap(struct cx_list_s *list, size_t i, size_t j); 277 int cx_list_default_swap(struct cx_list_s *list, size_t i, size_t j);
282 278
283 /** 279 /**
284 * Initializes a list struct. 280 * Initializes a list struct.
285 * 281 *
286 * Only use this function if you are creating your own list implementation. 282 * Only use this function if you are creating your own list implementation.
287 * The purpose of this function is to be called in the initialization code 283 * The purpose of this function is to be called in the initialization code
288 * of your list to set certain members correctly. 284 * of your list to set certain members correctly.
289 * 285 *
290 * This is particularly important when you want your list to support 286 * This is particularly useful when you want your list to support
291 * #CX_STORE_POINTERS as @p elem_size. This function will wrap the list 287 * #CX_STORE_POINTERS as @p elem_size.
292 * class accordingly and make sure that you can implement your list as if
293 * it was only storing objects, and the wrapper will automatically enable
294 * the feature of storing pointers.
295 * 288 *
296 * @par Example 289 * @par Example
297 * 290 *
298 * @code 291 * @code
299 * CxList *myCustomListCreate( 292 * CxList *myCustomListCreate(
320 * @param list the list to initialize 313 * @param list the list to initialize
321 * @param cl the list class 314 * @param cl the list class
322 * @param allocator the allocator for the elements 315 * @param allocator the allocator for the elements
323 * @param elem_size the size of one element 316 * @param elem_size the size of one element
324 */ 317 */
325 cx_attr_nonnull_arg(1, 2, 3) 318 CX_EXTERN CX_NONNULL_ARG(1, 2, 3)
326 CX_EXPORT void cx_list_init(struct cx_list_s *list, 319 void cx_list_init(struct cx_list_s *list,
327 struct cx_list_class_s *cl, const struct cx_allocator_s *allocator, 320 struct cx_list_class_s *cl, const struct cx_allocator_s *allocator,
328 size_t elem_size); 321 size_t elem_size);
329 322
330 /** 323 /**
331 * A @c cx_compare_func2 compatible wrapper for the compare functions of a list. 324 * A @c cx_compare_func2 compatible wrapper for the compare functions of a list.
333 * @param left first element 326 * @param left first element
334 * @param right second element 327 * @param right second element
335 * @param list the list which is comparing the elements 328 * @param list the list which is comparing the elements
336 * @return the comparison result 329 * @return the comparison result
337 */ 330 */
338 cx_attr_nonnull 331 CX_EXTERN CX_NONNULL
339 CX_EXPORT int cx_list_compare_wrapper( 332 int cx_list_compare_wrapper(
340 const void *left, const void *right, void *list); 333 const void *left, const void *right, void *list);
341 334
342 /** 335 /**
343 * Returns the number of elements currently stored in the list. 336 * Returns the number of elements currently stored in the list.
344 * 337 *
345 * @param list the list 338 * @param list the list
346 * @return the number of currently stored elements 339 * @return the number of currently stored elements
347 */ 340 */
348 cx_attr_nonnull 341 CX_EXTERN CX_NONNULL
349 CX_EXPORT size_t cxListSize(const CxList *list); 342 size_t cxListSize(const CxList *list);
350 343
351 /** 344 /**
352 * Adds an item to the end of the list. 345 * Adds an item to the end of the list.
353 * 346 *
354 * @param list the list 347 * @param list the list
356 * @retval zero success 349 * @retval zero success
357 * @retval non-zero memory allocation failure 350 * @retval non-zero memory allocation failure
358 * @see cxListAddArray() 351 * @see cxListAddArray()
359 * @see cxListEmplace() 352 * @see cxListEmplace()
360 */ 353 */
361 cx_attr_nonnull 354 CX_EXTERN CX_NONNULL
362 CX_EXPORT int cxListAdd(CxList *list, const void *elem); 355 int cxListAdd(CxList *list, const void *elem);
363 356
364 /** 357 /**
365 * Adds multiple items to the end of the list. 358 * Adds multiple items to the end of the list.
366 * 359 *
367 * This method is more efficient than invoking cxListAdd() multiple times. 360 * This method is more efficient than invoking cxListAdd() multiple times.
376 * @param array a pointer to the elements to add 369 * @param array a pointer to the elements to add
377 * @param n the number of elements to add 370 * @param n the number of elements to add
378 * @return the number of added elements 371 * @return the number of added elements
379 * @see cxListEmplaceArray() 372 * @see cxListEmplaceArray()
380 */ 373 */
381 cx_attr_nonnull 374 CX_EXTERN CX_NONNULL
382 CX_EXPORT size_t cxListAddArray(CxList *list, const void *array, size_t n); 375 size_t cxListAddArray(CxList *list, const void *array, size_t n);
383 376
384 /** 377 /**
385 * Inserts an item at the specified index. 378 * Inserts an item at the specified index.
386 * 379 *
387 * If the @p index equals the list @c size, this is effectively cxListAdd(). 380 * If the @p index equals the list @c size, this is effectively cxListAdd().
393 * @retval non-zero memory allocation failure or the index is out of bounds 386 * @retval non-zero memory allocation failure or the index is out of bounds
394 * @see cxListInsertAfter() 387 * @see cxListInsertAfter()
395 * @see cxListInsertBefore() 388 * @see cxListInsertBefore()
396 * @see cxListEmplaceAt() 389 * @see cxListEmplaceAt()
397 */ 390 */
398 cx_attr_nonnull 391 CX_EXTERN CX_NONNULL
399 CX_EXPORT int cxListInsert(CxList *list, size_t index, const void *elem); 392 int cxListInsert(CxList *list, size_t index, const void *elem);
400 393
401 /** 394 /**
402 * Allocates memory for an element at the specified index and returns a pointer to that memory. 395 * Allocates memory for an element at the specified index and returns a pointer to that memory.
403 * 396 *
404 * @remark When the list is storing pointers, this will return a @c void**. 397 * @remark When the list is storing pointers, this will return a @c void**.
408 * @return a pointer to the allocated memory; @c NULL when the operation fails, or the index is out-of-bounds 401 * @return a pointer to the allocated memory; @c NULL when the operation fails, or the index is out-of-bounds
409 * @see cxListEmplace() 402 * @see cxListEmplace()
410 * @see cxListEmplaceArrayAt() 403 * @see cxListEmplaceArrayAt()
411 * @see cxListInsert() 404 * @see cxListInsert()
412 */ 405 */
413 cx_attr_nonnull 406 CX_EXTERN CX_NONNULL CX_NODISCARD
414 CX_EXPORT void *cxListEmplaceAt(CxList *list, size_t index); 407 void *cxListEmplaceAt(CxList *list, size_t index);
415 408
416 /** 409 /**
417 * Allocates memory for an element at the end of the list and returns a pointer to that memory. 410 * Allocates memory for an element at the end of the list and returns a pointer to that memory.
418 * 411 *
419 * @remark When the list is storing pointers, this will return a @c void**. 412 * @remark When the list is storing pointers, this will return a @c void**.
421 * @param list the list 414 * @param list the list
422 * @return a pointer to the allocated memory; @c NULL when the operation fails, or the index is out-of-bounds 415 * @return a pointer to the allocated memory; @c NULL when the operation fails, or the index is out-of-bounds
423 * @see cxListEmplaceAt() 416 * @see cxListEmplaceAt()
424 * @see cxListAdd() 417 * @see cxListAdd()
425 */ 418 */
426 cx_attr_nonnull 419 CX_EXTERN CX_NONNULL CX_NODISCARD
427 CX_EXPORT void *cxListEmplace(CxList *list); 420 void *cxListEmplace(CxList *list);
428 421
429 /** 422 /**
430 * Allocates memory for multiple elements and returns an iterator. 423 * Allocates memory for multiple elements and returns an iterator.
431 * 424 *
432 * The iterator will only iterate over the successfully allocated elements. 425 * The iterator will only iterate over the successfully allocated elements.
441 * @param n the number of elements for which to allocate the memory 434 * @param n the number of elements for which to allocate the memory
442 * @return an iterator, iterating over the new memory 435 * @return an iterator, iterating over the new memory
443 * @see cxListEmplaceAt() 436 * @see cxListEmplaceAt()
444 * @see cxListInsertArray() 437 * @see cxListInsertArray()
445 */ 438 */
446 cx_attr_nonnull 439 CX_EXTERN CX_NONNULL CX_NODISCARD
447 CX_EXPORT CxIterator cxListEmplaceArrayAt(CxList *list, size_t index, size_t n); 440 CxIterator cxListEmplaceArrayAt(CxList *list, size_t index, size_t n);
448 441
449 /** 442 /**
450 * Allocates memory for multiple elements and returns an iterator. 443 * Allocates memory for multiple elements and returns an iterator.
451 * 444 *
452 * The iterator will only iterate over the successfully allocated elements. 445 * The iterator will only iterate over the successfully allocated elements.
460 * @param n the number of elements for which to allocate the memory 453 * @param n the number of elements for which to allocate the memory
461 * @return an iterator, iterating over the new memory 454 * @return an iterator, iterating over the new memory
462 * @see cxListEmplace() 455 * @see cxListEmplace()
463 * @see cxListAddArray() 456 * @see cxListAddArray()
464 */ 457 */
465 cx_attr_nonnull 458 CX_EXTERN CX_NONNULL CX_NODISCARD
466 CX_EXPORT CxIterator cxListEmplaceArray(CxList *list, size_t n); 459 CxIterator cxListEmplaceArray(CxList *list, size_t n);
467 460
468 /** 461 /**
469 * Inserts an item into a sorted list. 462 * Inserts an item into a sorted list.
470 * 463 *
471 * If the list is not sorted already, the behavior is undefined. 464 * If the list is not sorted already, the behavior is undefined.
473 * @param list the list 466 * @param list the list
474 * @param elem a pointer to the element to add 467 * @param elem a pointer to the element to add
475 * @retval zero success 468 * @retval zero success
476 * @retval non-zero memory allocation failure 469 * @retval non-zero memory allocation failure
477 */ 470 */
478 cx_attr_nonnull 471 CX_EXTERN CX_NONNULL
479 CX_EXPORT int cxListInsertSorted(CxList *list, const void *elem); 472 int cxListInsertSorted(CxList *list, const void *elem);
480 473
481 /** 474 /**
482 * Inserts an item into a list if it does not exist. 475 * Inserts an item into a list if it does not exist.
483 * 476 *
484 * If the list is not sorted already, this function will check all elements 477 * If the list is not sorted already, this function will check all elements
489 * @param list the list 482 * @param list the list
490 * @param elem a pointer to the element to add 483 * @param elem a pointer to the element to add
491 * @retval zero success (also when the element was already in the list) 484 * @retval zero success (also when the element was already in the list)
492 * @retval non-zero memory allocation failure 485 * @retval non-zero memory allocation failure
493 */ 486 */
494 cx_attr_nonnull 487 CX_EXTERN CX_NONNULL
495 CX_EXPORT int cxListInsertUnique(CxList *list, const void *elem); 488 int cxListInsertUnique(CxList *list, const void *elem);
496 489
497 /** 490 /**
498 * Inserts multiple items to the list at the specified index. 491 * Inserts multiple items to the list at the specified index.
499 * If the @p index equals the list size, this is effectively cxListAddArray(). 492 * If the @p index equals the list size, this is effectively cxListAddArray().
500 * 493 *
512 * @param array a pointer to the elements to add 505 * @param array a pointer to the elements to add
513 * @param n the number of elements to add 506 * @param n the number of elements to add
514 * @return the number of added elements 507 * @return the number of added elements
515 * @see cxListEmplaceArrayAt() 508 * @see cxListEmplaceArrayAt()
516 */ 509 */
517 cx_attr_nonnull 510 CX_EXTERN CX_NONNULL
518 CX_EXPORT size_t cxListInsertArray(CxList *list, size_t index, const void *array, size_t n); 511 size_t cxListInsertArray(CxList *list, size_t index, const void *array, size_t n);
519 512
520 /** 513 /**
521 * Inserts a sorted array into a sorted list. 514 * Inserts a sorted array into a sorted list.
522 * 515 *
523 * This method is usually more efficient than inserting each element separately 516 * This method is usually more efficient than inserting each element separately
534 * @param list the list 527 * @param list the list
535 * @param array a pointer to the elements to add 528 * @param array a pointer to the elements to add
536 * @param n the number of elements to add 529 * @param n the number of elements to add
537 * @return the number of added elements 530 * @return the number of added elements
538 */ 531 */
539 cx_attr_nonnull 532 CX_EXTERN CX_NONNULL
540 CX_EXPORT size_t cxListInsertSortedArray(CxList *list, const void *array, size_t n); 533 size_t cxListInsertSortedArray(CxList *list, const void *array, size_t n);
541 534
542 /** 535 /**
543 * Inserts an array into a list, skipping duplicates. 536 * Inserts an array into a list, skipping duplicates.
544 * 537 *
545 * The @p list does not need to be sorted (in contrast to cxListInsertSortedArray()). 538 * The @p list does not need to be sorted (in contrast to cxListInsertSortedArray()).
569 * @param n the number of elements to add 562 * @param n the number of elements to add
570 * @return the number of added elements 563 * @return the number of added elements
571 * 564 *
572 * @return the number of elements from the @p sorted_data that are definitely present in the list after this call 565 * @return the number of elements from the @p sorted_data that are definitely present in the list after this call
573 */ 566 */
574 cx_attr_nonnull 567 CX_EXTERN CX_NONNULL
575 CX_EXPORT size_t cxListInsertUniqueArray(CxList *list, const void *array, size_t n); 568 size_t cxListInsertUniqueArray(CxList *list, const void *array, size_t n);
576 569
577 /** 570 /**
578 * Inserts an element after the current location of the specified iterator. 571 * Inserts an element after the current location of the specified iterator.
579 * 572 *
580 * The used iterator remains operational, but all other active iterators should 573 * The used iterator remains operational, but all other active iterators should
588 * @retval zero success 581 * @retval zero success
589 * @retval non-zero memory allocation failure 582 * @retval non-zero memory allocation failure
590 * @see cxListInsert() 583 * @see cxListInsert()
591 * @see cxListInsertBefore() 584 * @see cxListInsertBefore()
592 */ 585 */
593 cx_attr_nonnull 586 CX_EXTERN CX_NONNULL
594 CX_EXPORT int cxListInsertAfter(CxIterator *iter, const void *elem); 587 int cxListInsertAfter(CxIterator *iter, const void *elem);
595 588
596 /** 589 /**
597 * Inserts an element before the current location of the specified iterator. 590 * Inserts an element before the current location of the specified iterator.
598 * 591 *
599 * The used iterator remains operational, but all other active iterators should 592 * The used iterator remains operational, but all other active iterators should
607 * @retval zero success 600 * @retval zero success
608 * @retval non-zero memory allocation failure 601 * @retval non-zero memory allocation failure
609 * @see cxListInsert() 602 * @see cxListInsert()
610 * @see cxListInsertAfter() 603 * @see cxListInsertAfter()
611 */ 604 */
612 cx_attr_nonnull 605 CX_EXTERN CX_NONNULL
613 CX_EXPORT int cxListInsertBefore(CxIterator *iter, const void *elem); 606 int cxListInsertBefore(CxIterator *iter, const void *elem);
614 607
615 /** 608 /**
616 * Removes the element at the specified index. 609 * Removes the element at the specified index.
617 * 610 *
618 * If an element destructor function is specified, it is called before 611 * If an element destructor function is specified, it is called before
621 * @param list the list 614 * @param list the list
622 * @param index the index of the element 615 * @param index the index of the element
623 * @retval zero success 616 * @retval zero success
624 * @retval non-zero index out of bounds 617 * @retval non-zero index out of bounds
625 */ 618 */
626 cx_attr_nonnull 619 CX_EXTERN CX_NONNULL
627 CX_EXPORT int cxListRemove(CxList *list, size_t index); 620 int cxListRemove(CxList *list, size_t index);
628 621
629 /** 622 /**
630 * Removes and returns the element at the specified index. 623 * Removes and returns the element at the specified index.
631 * 624 *
632 * No destructor is called, and instead the element is copied to the 625 * No destructor is called, and instead the element is copied to the
637 * @param index the index of the element 630 * @param index the index of the element
638 * @param targetbuf a buffer where to copy the element 631 * @param targetbuf a buffer where to copy the element
639 * @retval zero success 632 * @retval zero success
640 * @retval non-zero index out of bounds 633 * @retval non-zero index out of bounds
641 */ 634 */
642 cx_attr_nonnull cx_attr_access_w(3) 635 CX_EXTERN CX_NONNULL CX_ACCESS_W(3)
643 CX_EXPORT int cxListRemoveAndGet(CxList *list, size_t index, void *targetbuf); 636 int cxListRemoveAndGet(CxList *list, size_t index, void *targetbuf);
644 637
645 /** 638 /**
646 * Removes and returns the first element of the list. 639 * Removes and returns the first element of the list.
647 * 640 *
648 * No destructor is called, and instead the element is copied to the 641 * No destructor is called, and instead the element is copied to the
654 * @retval zero success 647 * @retval zero success
655 * @retval non-zero the list is empty 648 * @retval non-zero the list is empty
656 * @see cxListPopFront() 649 * @see cxListPopFront()
657 * @see cxListRemoveAndGetLast() 650 * @see cxListRemoveAndGetLast()
658 */ 651 */
659 cx_attr_nonnull cx_attr_access_w(2) 652 CX_EXTERN CX_NONNULL CX_ACCESS_W(2)
660 CX_EXPORT int cxListRemoveAndGetFirst(CxList *list, void *targetbuf); 653 int cxListRemoveAndGetFirst(CxList *list, void *targetbuf);
661 654
662 /** 655 /**
663 * Removes and returns the first element of the list. 656 * Removes and returns the first element of the list.
664 * 657 *
665 * Alias for cxListRemoveAndGetFirst(). 658 * Alias for cxListRemoveAndGetFirst().
688 * @param list the list 681 * @param list the list
689 * @param targetbuf a buffer where to copy the element 682 * @param targetbuf a buffer where to copy the element
690 * @retval zero success 683 * @retval zero success
691 * @retval non-zero the list is empty 684 * @retval non-zero the list is empty
692 */ 685 */
693 cx_attr_nonnull cx_attr_access_w(2) 686 CX_EXTERN CX_NONNULL CX_ACCESS_W(2)
694 CX_EXPORT int cxListRemoveAndGetLast(CxList *list, void *targetbuf); 687 int cxListRemoveAndGetLast(CxList *list, void *targetbuf);
695 688
696 /** 689 /**
697 * Removes and returns the last element of the list. 690 * Removes and returns the last element of the list.
698 * 691 *
699 * Alias for cxListRemoveAndGetLast(). 692 * Alias for cxListRemoveAndGetLast().
724 * @param list the list 717 * @param list the list
725 * @param index the index of the element 718 * @param index the index of the element
726 * @param num the number of elements to remove 719 * @param num the number of elements to remove
727 * @return the actual number of removed elements 720 * @return the actual number of removed elements
728 */ 721 */
729 cx_attr_nonnull 722 CX_EXTERN CX_NONNULL
730 CX_EXPORT size_t cxListRemoveArray(CxList *list, size_t index, size_t num); 723 size_t cxListRemoveArray(CxList *list, size_t index, size_t num);
731 724
732 /** 725 /**
733 * Removes and returns multiple elements starting at the specified index. 726 * Removes and returns multiple elements starting at the specified index.
734 * 727 *
735 * No destructor is called, and instead the elements are copied to the 728 * No destructor is called, and instead the elements are copied to the
740 * @param index the index of the element 733 * @param index the index of the element
741 * @param num the number of elements to remove 734 * @param num the number of elements to remove
742 * @param targetbuf a buffer where to copy the elements 735 * @param targetbuf a buffer where to copy the elements
743 * @return the actual number of removed elements 736 * @return the actual number of removed elements
744 */ 737 */
745 cx_attr_nonnull cx_attr_access_w(4) 738 CX_EXTERN CX_NONNULL CX_ACCESS_W(4)
746 CX_EXPORT size_t cxListRemoveArrayAndGet(CxList *list, size_t index, size_t num, void *targetbuf); 739 size_t cxListRemoveArrayAndGet(CxList *list, size_t index, size_t num, void *targetbuf);
747 740
748 /** 741 /**
749 * Removes all elements from this list. 742 * Removes all elements from this list.
750 * 743 *
751 * If element destructor functions are specified, they are called for each 744 * If element destructor functions are specified, they are called for each
752 * element before removing them. 745 * element before removing them.
753 * 746 *
754 * @param list the list 747 * @param list the list
755 */ 748 */
756 cx_attr_nonnull 749 CX_EXTERN CX_NONNULL
757 CX_EXPORT void cxListClear(CxList *list); 750 void cxListClear(CxList *list);
758 751
759 /** 752 /**
760 * Swaps two items in the list. 753 * Swaps two items in the list.
761 * 754 *
762 * Implementations should only allocate temporary memory for the swap if 755 * Implementations should only allocate temporary memory for the swap if
767 * @param j the index of the second element 760 * @param j the index of the second element
768 * @retval zero success 761 * @retval zero success
769 * @retval non-zero one of the indices is out of bounds, 762 * @retval non-zero one of the indices is out of bounds,
770 * or the swap needed extra memory, but allocation failed 763 * or the swap needed extra memory, but allocation failed
771 */ 764 */
772 cx_attr_nonnull 765 CX_EXTERN CX_NONNULL
773 CX_EXPORT int cxListSwap(CxList *list, size_t i, size_t j); 766 int cxListSwap(CxList *list, size_t i, size_t j);
774 767
775 /** 768 /**
776 * Returns a pointer to the element at the specified index. 769 * Returns a pointer to the element at the specified index.
777 * 770 *
778 * If the list is storing pointers, returns the pointer stored at the specified index. 771 * If the list is storing pointers, returns the pointer stored at the specified index.
779 * 772 *
780 * @param list the list 773 * @param list the list
781 * @param index the index of the element 774 * @param index the index of the element
782 * @return a pointer to the element or @c NULL if the index is out of bounds 775 * @return a pointer to the element or @c NULL if the index is out of bounds
783 */ 776 */
784 cx_attr_nonnull 777 CX_EXTERN CX_NONNULL
785 CX_EXPORT void *cxListAt(const CxList *list, size_t index); 778 void *cxListAt(const CxList *list, size_t index);
786 779
787 /** 780 /**
788 * Returns a pointer to the first element. 781 * Returns a pointer to the first element.
789 * 782 *
790 * If the list is storing pointers, returns the first pointer stored in the list. 783 * If the list is storing pointers, returns the first pointer stored in the list.
791 * 784 *
792 * @param list the list 785 * @param list the list
793 * @return a pointer to the first element or @c NULL if the list is empty 786 * @return a pointer to the first element or @c NULL if the list is empty
794 */ 787 */
795 cx_attr_nonnull 788 CX_EXTERN CX_NONNULL
796 CX_EXPORT void *cxListFirst(const CxList *list); 789 void *cxListFirst(const CxList *list);
797 790
798 /** 791 /**
799 * Returns a pointer to the last element. 792 * Returns a pointer to the last element.
800 * 793 *
801 * If the list is storing pointers, returns the last pointer stored in the list. 794 * If the list is storing pointers, returns the last pointer stored in the list.
802 * 795 *
803 * @param list the list 796 * @param list the list
804 * @return a pointer to the last element or @c NULL if the list is empty 797 * @return a pointer to the last element or @c NULL if the list is empty
805 */ 798 */
806 cx_attr_nonnull 799 CX_EXTERN CX_NONNULL
807 CX_EXPORT void *cxListLast(const CxList *list); 800 void *cxListLast(const CxList *list);
808 801
809 /** 802 /**
810 * Sets the element at the specified index in the list. 803 * Sets the element at the specified index in the list.
811 * 804 *
812 * This overwrites the element in-place without calling any destructor 805 * This overwrites the element in-place without calling any destructor
816 * @param index the index to set the element at 809 * @param index the index to set the element at
817 * @param elem element to set 810 * @param elem element to set
818 * @retval zero on success 811 * @retval zero on success
819 * @retval non-zero when index is out of bounds 812 * @retval non-zero when index is out of bounds
820 */ 813 */
821 cx_attr_nonnull 814 CX_EXTERN CX_NONNULL
822 CX_EXPORT int cxListSet(CxList *list, size_t index, const void *elem); 815 int cxListSet(CxList *list, size_t index, const void *elem);
823 816
824 /** 817 /**
825 * Returns an iterator pointing to the item at the specified index. 818 * Returns an iterator pointing to the item at the specified index.
826 * 819 *
827 * The returned iterator is position-aware. 820 * The returned iterator is position-aware.
830 * 823 *
831 * @param list the list 824 * @param list the list
832 * @param index the index where the iterator shall point at 825 * @param index the index where the iterator shall point at
833 * @return a new iterator 826 * @return a new iterator
834 */ 827 */
835 cx_attr_nodiscard 828 CX_EXTERN CX_NODISCARD
836 CX_EXPORT CxIterator cxListIteratorAt(const CxList *list, size_t index); 829 CxIterator cxListIteratorAt(const CxList *list, size_t index);
837 830
838 /** 831 /**
839 * Returns a backwards iterator pointing to the item at the specified index. 832 * Returns a backwards iterator pointing to the item at the specified index.
840 * 833 *
841 * The returned iterator is position-aware. 834 * The returned iterator is position-aware.
844 * 837 *
845 * @param list the list 838 * @param list the list
846 * @param index the index where the iterator shall point at 839 * @param index the index where the iterator shall point at
847 * @return a new iterator 840 * @return a new iterator
848 */ 841 */
849 cx_attr_nodiscard 842 CX_EXTERN CX_NODISCARD
850 CX_EXPORT CxIterator cxListBackwardsIteratorAt(const CxList *list, size_t index); 843 CxIterator cxListBackwardsIteratorAt(const CxList *list, size_t index);
851 844
852 /** 845 /**
853 * Returns an iterator pointing to the first item of the list. 846 * Returns an iterator pointing to the first item of the list.
854 * 847 *
855 * The returned iterator is position-aware. 848 * The returned iterator is position-aware.
857 * If the list is empty or @c NULL, a past-the-end iterator will be returned. 850 * If the list is empty or @c NULL, a past-the-end iterator will be returned.
858 * 851 *
859 * @param list the list 852 * @param list the list
860 * @return a new iterator 853 * @return a new iterator
861 */ 854 */
862 cx_attr_nodiscard 855 CX_EXTERN CX_NODISCARD
863 CX_EXPORT CxIterator cxListIterator(const CxList *list); 856 CxIterator cxListIterator(const CxList *list);
864 857
865 /** 858 /**
866 * Returns a backwards iterator pointing to the last item of the list. 859 * Returns a backwards iterator pointing to the last item of the list.
867 * 860 *
868 * The returned iterator is position-aware. 861 * The returned iterator is position-aware.
870 * If the list is empty or @c NULL, a past-the-end iterator will be returned. 863 * If the list is empty or @c NULL, a past-the-end iterator will be returned.
871 * 864 *
872 * @param list the list 865 * @param list the list
873 * @return a new iterator 866 * @return a new iterator
874 */ 867 */
875 cx_attr_nodiscard 868 CX_EXTERN CX_NODISCARD
876 CX_EXPORT CxIterator cxListBackwardsIterator(const CxList *list); 869 CxIterator cxListBackwardsIterator(const CxList *list);
877 870
878 /** 871 /**
879 * Returns the index of the first element that equals @p elem. 872 * Returns the index of the first element that equals @p elem.
880 * 873 *
881 * Determining equality is performed by the list's comparator function. 874 * Determining equality is performed by the list's comparator function.
884 * @param elem the element to find 877 * @param elem the element to find
885 * @return the index of the element or the size of the list when the element is not found 878 * @return the index of the element or the size of the list when the element is not found
886 * @see cxListIndexValid() 879 * @see cxListIndexValid()
887 * @see cxListContains() 880 * @see cxListContains()
888 */ 881 */
889 cx_attr_nonnull cx_attr_nodiscard 882 CX_EXTERN CX_NONNULL CX_NODISCARD
890 CX_EXPORT size_t cxListFind(const CxList *list, const void *elem); 883 size_t cxListFind(const CxList *list, const void *elem);
891 884
892 /** 885 /**
893 * Checks if the list contains the specified element. 886 * Checks if the list contains the specified element.
894 * 887 *
895 * The elements are compared with the list's comparator function. 888 * The elements are compared with the list's comparator function.
898 * @param elem the element to find 891 * @param elem the element to find
899 * @retval true if the element is contained 892 * @retval true if the element is contained
900 * @retval false if the element is not contained 893 * @retval false if the element is not contained
901 * @see cxListFind() 894 * @see cxListFind()
902 */ 895 */
903 cx_attr_nonnull cx_attr_nodiscard 896 CX_EXTERN CX_NONNULL CX_NODISCARD
904 CX_EXPORT bool cxListContains(const CxList* list, const void* elem); 897 bool cxListContains(const CxList* list, const void* elem);
905 898
906 /** 899 /**
907 * Checks if the specified index is within bounds. 900 * Checks if the specified index is within bounds.
908 * 901 *
909 * @param list the list 902 * @param list the list
910 * @param index the index 903 * @param index the index
911 * @retval true if the index is within bounds 904 * @retval true if the index is within bounds
912 * @retval false if the index is out of bounds 905 * @retval false if the index is out of bounds
913 */ 906 */
914 cx_attr_nonnull cx_attr_nodiscard 907 CX_EXTERN CX_NONNULL CX_NODISCARD
915 CX_EXPORT bool cxListIndexValid(const CxList *list, size_t index); 908 bool cxListIndexValid(const CxList *list, size_t index);
916 909
917 /** 910 /**
918 * Removes and returns the index of the first element that equals @p elem. 911 * Removes and returns the index of the first element that equals @p elem.
919 * 912 *
920 * Determining equality is performed by the list's comparator function. 913 * Determining equality is performed by the list's comparator function.
923 * @param elem the element to find and remove 916 * @param elem the element to find and remove
924 * @return the index of the now removed element or the list size 917 * @return the index of the now removed element or the list size
925 * when the element is not found or could not be removed 918 * when the element is not found or could not be removed
926 * @see cxListIndexValid() 919 * @see cxListIndexValid()
927 */ 920 */
928 cx_attr_nonnull 921 CX_EXTERN CX_NONNULL
929 CX_EXPORT size_t cxListFindRemove(CxList *list, const void *elem); 922 size_t cxListFindRemove(CxList *list, const void *elem);
930 923
931 /** 924 /**
932 * Sorts the list. 925 * Sorts the list.
933 * 926 *
934 * @remark The underlying sort algorithm is implementation defined. 927 * @remark The underlying sort algorithm is implementation defined.
935 * 928 *
936 * @param list the list 929 * @param list the list
937 */ 930 */
938 cx_attr_nonnull 931 CX_EXTERN CX_NONNULL
939 CX_EXPORT void cxListSort(CxList *list); 932 void cxListSort(CxList *list);
940 933
941 /** 934 /**
942 * Reverses the order of the items. 935 * Reverses the order of the items.
943 * 936 *
944 * @param list the list 937 * @param list the list
945 */ 938 */
946 cx_attr_nonnull 939 CX_EXTERN CX_NONNULL
947 CX_EXPORT void cxListReverse(CxList *list); 940 void cxListReverse(CxList *list);
948 941
949 /** 942 /**
950 * Compares a list to another list of the same type. 943 * Compares a list to another list of the same type.
951 * 944 *
952 * First, the list sizes are compared. 945 * First, the list sizes are compared.
958 * @retval negative the first list is smaller, 951 * @retval negative the first list is smaller,
959 * or the first non-equal element in the first list is smaller 952 * or the first non-equal element in the first list is smaller
960 * @retval positive the first list is larger 953 * @retval positive the first list is larger
961 * or the first non-equal element in the first list is larger 954 * or the first non-equal element in the first list is larger
962 */ 955 */
963 cx_attr_nonnull cx_attr_nodiscard 956 CX_EXTERN CX_NONNULL CX_NODISCARD
964 CX_EXPORT int cxListCompare(const CxList *list, const CxList *other); 957 int cxListCompare(const CxList *list, const CxList *other);
965 958
966 /** 959 /**
967 * Deallocates the memory of the specified list structure. 960 * Deallocates the memory of the specified list structure.
968 * 961 *
969 * Also calls the content destructor functions for each element, if specified. 962 * Also calls the content destructor functions for each element, if specified.
970 * 963 *
971 * @param list the list that shall be freed 964 * @param list the list that shall be freed
972 */ 965 */
973 CX_EXPORT void cxListFree(CxList *list); 966 CX_EXTERN
967 void cxListFree(CxList *list);
974 968
975 969
976 /** 970 /**
977 * Performs a deep clone of one list into another. 971 * Performs a deep clone of one list into another.
978 * 972 *
990 * @param data optional additional data that is passed to the clone function 984 * @param data optional additional data that is passed to the clone function
991 * @retval zero when all elements were successfully cloned 985 * @retval zero when all elements were successfully cloned
992 * @retval non-zero when an allocation error occurred 986 * @retval non-zero when an allocation error occurred
993 * @see cxListCloneShallow() 987 * @see cxListCloneShallow()
994 */ 988 */
995 cx_attr_nonnull_arg(1, 2, 3) 989 CX_EXTERN CX_NONNULL_ARG(1, 2, 3)
996 CX_EXPORT int cxListClone(CxList *dst, const CxList *src, 990 int cxListClone(CxList *dst, const CxList *src,
997 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data); 991 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data);
998 992
999 /** 993 /**
1000 * Clones elements from a list only if they are not present in another list. 994 * Clones elements from a list only if they are not present in another list.
1001 * 995 *
1013 * @param data optional additional data that is passed to the clone function 1007 * @param data optional additional data that is passed to the clone function
1014 * @retval zero when the elements were successfully cloned 1008 * @retval zero when the elements were successfully cloned
1015 * @retval non-zero when an allocation error occurred 1009 * @retval non-zero when an allocation error occurred
1016 * @see cxListDifferenceShallow() 1010 * @see cxListDifferenceShallow()
1017 */ 1011 */
1018 cx_attr_nonnull_arg(1, 2, 3, 4) 1012 CX_EXTERN CX_NONNULL_ARG(1, 2, 3, 4)
1019 CX_EXPORT int cxListDifference(CxList *dst, 1013 int cxListDifference(CxList *dst,
1020 const CxList *minuend, const CxList *subtrahend, 1014 const CxList *minuend, const CxList *subtrahend,
1021 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data); 1015 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data);
1022 1016
1023 /** 1017 /**
1024 * Clones elements from a list only if they are also present in another list. 1018 * Clones elements from a list only if they are also present in another list.
1037 * @param data optional additional data that is passed to the clone function 1031 * @param data optional additional data that is passed to the clone function
1038 * @retval zero when the elements were successfully cloned 1032 * @retval zero when the elements were successfully cloned
1039 * @retval non-zero when an allocation error occurred 1033 * @retval non-zero when an allocation error occurred
1040 * @see cxListIntersectionShallow() 1034 * @see cxListIntersectionShallow()
1041 */ 1035 */
1042 cx_attr_nonnull_arg(1, 2, 3, 4) 1036 CX_EXTERN CX_NONNULL_ARG(1, 2, 3, 4)
1043 CX_EXPORT int cxListIntersection(CxList *dst, const CxList *src, const CxList *other, 1037 int cxListIntersection(CxList *dst, const CxList *src, const CxList *other,
1044 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data); 1038 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data);
1045 1039
1046 /** 1040 /**
1047 * Performs a deep clone of one list into another, skipping duplicates. 1041 * Performs a deep clone of one list into another, skipping duplicates.
1048 * 1042 *
1062 * @param data optional additional data that is passed to the clone function 1056 * @param data optional additional data that is passed to the clone function
1063 * @retval zero when the elements were successfully cloned 1057 * @retval zero when the elements were successfully cloned
1064 * @retval non-zero when an allocation error occurred 1058 * @retval non-zero when an allocation error occurred
1065 * @see cxListUnionShallow() 1059 * @see cxListUnionShallow()
1066 */ 1060 */
1067 cx_attr_nonnull_arg(1, 2, 3, 4) 1061 CX_EXTERN CX_NONNULL_ARG(1, 2, 3, 4)
1068 CX_EXPORT int cxListUnion(CxList *dst, const CxList *src, const CxList *other, 1062 int cxListUnion(CxList *dst, const CxList *src, const CxList *other,
1069 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data); 1063 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data);
1070 1064
1071 /** 1065 /**
1072 * Performs a shallow clone of one list into another. 1066 * Performs a shallow clone of one list into another.
1073 * 1067 *
1085 * @param src the source list 1079 * @param src the source list
1086 * @retval zero when all elements were successfully cloned 1080 * @retval zero when all elements were successfully cloned
1087 * @retval non-zero when an allocation error occurred 1081 * @retval non-zero when an allocation error occurred
1088 * @see cxListClone() 1082 * @see cxListClone()
1089 */ 1083 */
1090 cx_attr_nonnull 1084 CX_EXTERN CX_NONNULL
1091 CX_EXPORT int cxListCloneShallow(CxList *dst, const CxList *src); 1085 int cxListCloneShallow(CxList *dst, const CxList *src);
1092 1086
1093 /** 1087 /**
1094 * Clones elements from a list only if they are not present in another list. 1088 * Clones elements from a list only if they are not present in another list.
1095 * 1089 *
1096 * This function uses the default allocator, if needed, and performs 1090 * This function uses the default allocator, if needed, and performs
1107 * @param subtrahend the elements that shall be subtracted 1101 * @param subtrahend the elements that shall be subtracted
1108 * @retval zero when the elements were successfully cloned 1102 * @retval zero when the elements were successfully cloned
1109 * @retval non-zero when an allocation error occurred 1103 * @retval non-zero when an allocation error occurred
1110 * @see cxListDifference() 1104 * @see cxListDifference()
1111 */ 1105 */
1112 cx_attr_nonnull 1106 CX_EXTERN CX_NONNULL
1113 CX_EXPORT int cxListDifferenceShallow(CxList *dst, 1107 int cxListDifferenceShallow(CxList *dst,
1114 const CxList *minuend, const CxList *subtrahend); 1108 const CxList *minuend, const CxList *subtrahend);
1115 1109
1116 /** 1110 /**
1117 * Clones elements from a list only if they are also present in another list. 1111 * Clones elements from a list only if they are also present in another list.
1118 * 1112 *
1130 * @param other the list to check the elements for existence 1124 * @param other the list to check the elements for existence
1131 * @retval zero when the elements were successfully cloned 1125 * @retval zero when the elements were successfully cloned
1132 * @retval non-zero when an allocation error occurred 1126 * @retval non-zero when an allocation error occurred
1133 * @see cxListIntersection() 1127 * @see cxListIntersection()
1134 */ 1128 */
1135 cx_attr_nonnull 1129 CX_EXTERN CX_NONNULL
1136 CX_EXPORT int cxListIntersectionShallow(CxList *dst, const CxList *src, const CxList *other); 1130 int cxListIntersectionShallow(CxList *dst, const CxList *src, const CxList *other);
1137 1131
1138 /** 1132 /**
1139 * Performs a deep clone of one list into another, skipping duplicates. 1133 * Performs a deep clone of one list into another, skipping duplicates.
1140 * 1134 *
1141 * This function uses the default allocator, if needed, and performs 1135 * This function uses the default allocator, if needed, and performs
1154 * when they are not in @p src 1148 * when they are not in @p src
1155 * @retval zero when the elements were successfully cloned 1149 * @retval zero when the elements were successfully cloned
1156 * @retval non-zero when an allocation error occurred 1150 * @retval non-zero when an allocation error occurred
1157 * @see cxListUnion() 1151 * @see cxListUnion()
1158 */ 1152 */
1159 cx_attr_nonnull 1153 CX_EXTERN CX_NONNULL
1160 CX_EXPORT int cxListUnionShallow(CxList *dst, const CxList *src, const CxList *other); 1154 int cxListUnionShallow(CxList *dst, const CxList *src, const CxList *other);
1161 1155
1162 /** 1156 /**
1163 * Asks the list to reserve enough memory for a given total number of elements. 1157 * Asks the list to reserve enough memory for a given total number of elements.
1164 * 1158 *
1165 * List implementations are free to choose if reserving memory upfront makes 1159 * List implementations are free to choose if reserving memory upfront makes
1174 * @param capacity the expected total number of elements 1168 * @param capacity the expected total number of elements
1175 * @retval zero on success or when overallocation is not supported 1169 * @retval zero on success or when overallocation is not supported
1176 * @retval non-zero when an allocation error occurred 1170 * @retval non-zero when an allocation error occurred
1177 * @see cxListShrink() 1171 * @see cxListShrink()
1178 */ 1172 */
1179 cx_attr_nonnull 1173 CX_EXTERN CX_NONNULL
1180 CX_EXPORT int cxListReserve(CxList *list, size_t capacity); 1174 int cxListReserve(CxList *list, size_t capacity);
1181 1175
1182 /** 1176 /**
1183 * Advises the list to free any overallocated memory. 1177 * Advises the list to free any overallocated memory.
1184 * 1178 *
1185 * Lists that do not support overallocation simply return zero. 1179 * Lists that do not support overallocation simply return zero.
1188 * list and/or allocator implementations where freeing memory can fail. 1182 * list and/or allocator implementations where freeing memory can fail.
1189 * 1183 *
1190 * @param list the list 1184 * @param list the list
1191 * @return usually zero 1185 * @return usually zero
1192 */ 1186 */
1193 cx_attr_nonnull 1187 CX_EXTERN CX_NONNULL
1194 CX_EXPORT int cxListShrink(CxList *list); 1188 int cxListShrink(CxList *list);
1195
1196 #ifdef __cplusplus
1197 } // extern "C"
1198 #endif
1199 1189
1200 #endif // UCX_LIST_H 1190 #endif // UCX_LIST_H

Mercurial Repository: toolkit

mercurial