Mercurial > hg > ucx / file comparison

comparison: src/cx/list.h

src/cx/list.h

changeset 1675
36c0fb2b60b2
parent 1662
527ac061b247
equal deleted inserted replaced
1674:8b0f162ac88e 1675:36c0fb2b60b2
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_arg(1) 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.
317 * @param list the list to initialize 313 * @param list the list to initialize
318 * @param cl the list class 314 * @param cl the list class
319 * @param allocator the allocator for the elements 315 * @param allocator the allocator for the elements
320 * @param elem_size the size of one element 316 * @param elem_size the size of one element
321 */ 317 */
322 cx_attr_nonnull_arg(1, 2, 3) 318 CX_EXTERN CX_NONNULL_ARG(1, 2, 3)
323 CX_EXPORT void cx_list_init(struct cx_list_s *list, 319 void cx_list_init(struct cx_list_s *list,
324 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,
325 size_t elem_size); 321 size_t elem_size);
326 322
327 /** 323 /**
328 * 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.
330 * @param left first element 326 * @param left first element
331 * @param right second element 327 * @param right second element
332 * @param list the list which is comparing the elements 328 * @param list the list which is comparing the elements
333 * @return the comparison result 329 * @return the comparison result
334 */ 330 */
335 cx_attr_nonnull 331 CX_EXTERN CX_NONNULL
336 CX_EXPORT int cx_list_compare_wrapper( 332 int cx_list_compare_wrapper(
337 const void *left, const void *right, void *list); 333 const void *left, const void *right, void *list);
338 334
339 /** 335 /**
340 * Returns the number of elements currently stored in the list. 336 * Returns the number of elements currently stored in the list.
341 * 337 *
342 * @param list the list 338 * @param list the list
343 * @return the number of currently stored elements 339 * @return the number of currently stored elements
344 */ 340 */
345 cx_attr_nonnull 341 CX_EXTERN CX_NONNULL
346 CX_EXPORT size_t cxListSize(const CxList *list); 342 size_t cxListSize(const CxList *list);
347 343
348 /** 344 /**
349 * Adds an item to the end of the list. 345 * Adds an item to the end of the list.
350 * 346 *
351 * @param list the list 347 * @param list the list
353 * @retval zero success 349 * @retval zero success
354 * @retval non-zero memory allocation failure 350 * @retval non-zero memory allocation failure
355 * @see cxListAddArray() 351 * @see cxListAddArray()
356 * @see cxListEmplace() 352 * @see cxListEmplace()
357 */ 353 */
358 cx_attr_nonnull 354 CX_EXTERN CX_NONNULL
359 CX_EXPORT int cxListAdd(CxList *list, const void *elem); 355 int cxListAdd(CxList *list, const void *elem);
360 356
361 /** 357 /**
362 * Adds multiple items to the end of the list. 358 * Adds multiple items to the end of the list.
363 * 359 *
364 * This method is more efficient than invoking cxListAdd() multiple times. 360 * This method is more efficient than invoking cxListAdd() multiple times.
373 * @param array a pointer to the elements to add 369 * @param array a pointer to the elements to add
374 * @param n the number of elements to add 370 * @param n the number of elements to add
375 * @return the number of added elements 371 * @return the number of added elements
376 * @see cxListEmplaceArray() 372 * @see cxListEmplaceArray()
377 */ 373 */
378 cx_attr_nonnull 374 CX_EXTERN CX_NONNULL
379 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);
380 376
381 /** 377 /**
382 * Inserts an item at the specified index. 378 * Inserts an item at the specified index.
383 * 379 *
384 * 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().
390 * @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
391 * @see cxListInsertAfter() 387 * @see cxListInsertAfter()
392 * @see cxListInsertBefore() 388 * @see cxListInsertBefore()
393 * @see cxListEmplaceAt() 389 * @see cxListEmplaceAt()
394 */ 390 */
395 cx_attr_nonnull 391 CX_EXTERN CX_NONNULL
396 CX_EXPORT int cxListInsert(CxList *list, size_t index, const void *elem); 392 int cxListInsert(CxList *list, size_t index, const void *elem);
397 393
398 /** 394 /**
399 * 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.
400 * 396 *
401 * @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**.
405 * @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
406 * @see cxListEmplace() 402 * @see cxListEmplace()
407 * @see cxListEmplaceArrayAt() 403 * @see cxListEmplaceArrayAt()
408 * @see cxListInsert() 404 * @see cxListInsert()
409 */ 405 */
410 cx_attr_nonnull 406 CX_EXTERN CX_NONNULL CX_NODISCARD
411 CX_EXPORT void *cxListEmplaceAt(CxList *list, size_t index); 407 void *cxListEmplaceAt(CxList *list, size_t index);
412 408
413 /** 409 /**
414 * 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.
415 * 411 *
416 * @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**.
418 * @param list the list 414 * @param list the list
419 * @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
420 * @see cxListEmplaceAt() 416 * @see cxListEmplaceAt()
421 * @see cxListAdd() 417 * @see cxListAdd()
422 */ 418 */
423 cx_attr_nonnull 419 CX_EXTERN CX_NONNULL CX_NODISCARD
424 CX_EXPORT void *cxListEmplace(CxList *list); 420 void *cxListEmplace(CxList *list);
425 421
426 /** 422 /**
427 * Allocates memory for multiple elements and returns an iterator. 423 * Allocates memory for multiple elements and returns an iterator.
428 * 424 *
429 * The iterator will only iterate over the successfully allocated elements. 425 * The iterator will only iterate over the successfully allocated elements.
438 * @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
439 * @return an iterator, iterating over the new memory 435 * @return an iterator, iterating over the new memory
440 * @see cxListEmplaceAt() 436 * @see cxListEmplaceAt()
441 * @see cxListInsertArray() 437 * @see cxListInsertArray()
442 */ 438 */
443 cx_attr_nonnull 439 CX_EXTERN CX_NONNULL CX_NODISCARD
444 CX_EXPORT CxIterator cxListEmplaceArrayAt(CxList *list, size_t index, size_t n); 440 CxIterator cxListEmplaceArrayAt(CxList *list, size_t index, size_t n);
445 441
446 /** 442 /**
447 * Allocates memory for multiple elements and returns an iterator. 443 * Allocates memory for multiple elements and returns an iterator.
448 * 444 *
449 * The iterator will only iterate over the successfully allocated elements. 445 * The iterator will only iterate over the successfully allocated elements.
457 * @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
458 * @return an iterator, iterating over the new memory 454 * @return an iterator, iterating over the new memory
459 * @see cxListEmplace() 455 * @see cxListEmplace()
460 * @see cxListAddArray() 456 * @see cxListAddArray()
461 */ 457 */
462 cx_attr_nonnull 458 CX_EXTERN CX_NONNULL CX_NODISCARD
463 CX_EXPORT CxIterator cxListEmplaceArray(CxList *list, size_t n); 459 CxIterator cxListEmplaceArray(CxList *list, size_t n);
464 460
465 /** 461 /**
466 * Inserts an item into a sorted list. 462 * Inserts an item into a sorted list.
467 * 463 *
468 * If the list is not sorted already, the behavior is undefined. 464 * If the list is not sorted already, the behavior is undefined.
470 * @param list the list 466 * @param list the list
471 * @param elem a pointer to the element to add 467 * @param elem a pointer to the element to add
472 * @retval zero success 468 * @retval zero success
473 * @retval non-zero memory allocation failure 469 * @retval non-zero memory allocation failure
474 */ 470 */
475 cx_attr_nonnull 471 CX_EXTERN CX_NONNULL
476 CX_EXPORT int cxListInsertSorted(CxList *list, const void *elem); 472 int cxListInsertSorted(CxList *list, const void *elem);
477 473
478 /** 474 /**
479 * Inserts an item into a list if it does not exist. 475 * Inserts an item into a list if it does not exist.
480 * 476 *
481 * 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
486 * @param list the list 482 * @param list the list
487 * @param elem a pointer to the element to add 483 * @param elem a pointer to the element to add
488 * @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)
489 * @retval non-zero memory allocation failure 485 * @retval non-zero memory allocation failure
490 */ 486 */
491 cx_attr_nonnull 487 CX_EXTERN CX_NONNULL
492 CX_EXPORT int cxListInsertUnique(CxList *list, const void *elem); 488 int cxListInsertUnique(CxList *list, const void *elem);
493 489
494 /** 490 /**
495 * Inserts multiple items to the list at the specified index. 491 * Inserts multiple items to the list at the specified index.
496 * 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().
497 * 493 *
509 * @param array a pointer to the elements to add 505 * @param array a pointer to the elements to add
510 * @param n the number of elements to add 506 * @param n the number of elements to add
511 * @return the number of added elements 507 * @return the number of added elements
512 * @see cxListEmplaceArrayAt() 508 * @see cxListEmplaceArrayAt()
513 */ 509 */
514 cx_attr_nonnull 510 CX_EXTERN CX_NONNULL
515 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);
516 512
517 /** 513 /**
518 * Inserts a sorted array into a sorted list. 514 * Inserts a sorted array into a sorted list.
519 * 515 *
520 * This method is usually more efficient than inserting each element separately 516 * This method is usually more efficient than inserting each element separately
531 * @param list the list 527 * @param list the list
532 * @param array a pointer to the elements to add 528 * @param array a pointer to the elements to add
533 * @param n the number of elements to add 529 * @param n the number of elements to add
534 * @return the number of added elements 530 * @return the number of added elements
535 */ 531 */
536 cx_attr_nonnull 532 CX_EXTERN CX_NONNULL
537 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);
538 534
539 /** 535 /**
540 * Inserts an array into a list, skipping duplicates. 536 * Inserts an array into a list, skipping duplicates.
541 * 537 *
542 * 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()).
566 * @param n the number of elements to add 562 * @param n the number of elements to add
567 * @return the number of added elements 563 * @return the number of added elements
568 * 564 *
569 * @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
570 */ 566 */
571 cx_attr_nonnull 567 CX_EXTERN CX_NONNULL
572 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);
573 569
574 /** 570 /**
575 * Inserts an element after the current location of the specified iterator. 571 * Inserts an element after the current location of the specified iterator.
576 * 572 *
577 * The used iterator remains operational, but all other active iterators should 573 * The used iterator remains operational, but all other active iterators should
585 * @retval zero success 581 * @retval zero success
586 * @retval non-zero memory allocation failure 582 * @retval non-zero memory allocation failure
587 * @see cxListInsert() 583 * @see cxListInsert()
588 * @see cxListInsertBefore() 584 * @see cxListInsertBefore()
589 */ 585 */
590 cx_attr_nonnull 586 CX_EXTERN CX_NONNULL
591 CX_EXPORT int cxListInsertAfter(CxIterator *iter, const void *elem); 587 int cxListInsertAfter(CxIterator *iter, const void *elem);
592 588
593 /** 589 /**
594 * Inserts an element before the current location of the specified iterator. 590 * Inserts an element before the current location of the specified iterator.
595 * 591 *
596 * The used iterator remains operational, but all other active iterators should 592 * The used iterator remains operational, but all other active iterators should
604 * @retval zero success 600 * @retval zero success
605 * @retval non-zero memory allocation failure 601 * @retval non-zero memory allocation failure
606 * @see cxListInsert() 602 * @see cxListInsert()
607 * @see cxListInsertAfter() 603 * @see cxListInsertAfter()
608 */ 604 */
609 cx_attr_nonnull 605 CX_EXTERN CX_NONNULL
610 CX_EXPORT int cxListInsertBefore(CxIterator *iter, const void *elem); 606 int cxListInsertBefore(CxIterator *iter, const void *elem);
611 607
612 /** 608 /**
613 * Removes the element at the specified index. 609 * Removes the element at the specified index.
614 * 610 *
615 * If an element destructor function is specified, it is called before 611 * If an element destructor function is specified, it is called before
618 * @param list the list 614 * @param list the list
619 * @param index the index of the element 615 * @param index the index of the element
620 * @retval zero success 616 * @retval zero success
621 * @retval non-zero index out of bounds 617 * @retval non-zero index out of bounds
622 */ 618 */
623 cx_attr_nonnull 619 CX_EXTERN CX_NONNULL
624 CX_EXPORT int cxListRemove(CxList *list, size_t index); 620 int cxListRemove(CxList *list, size_t index);
625 621
626 /** 622 /**
627 * Removes and returns the element at the specified index. 623 * Removes and returns the element at the specified index.
628 * 624 *
629 * 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
634 * @param index the index of the element 630 * @param index the index of the element
635 * @param targetbuf a buffer where to copy the element 631 * @param targetbuf a buffer where to copy the element
636 * @retval zero success 632 * @retval zero success
637 * @retval non-zero index out of bounds 633 * @retval non-zero index out of bounds
638 */ 634 */
639 cx_attr_nonnull cx_attr_access_w(3) 635 CX_EXTERN CX_NONNULL CX_ACCESS_W(3)
640 CX_EXPORT int cxListRemoveAndGet(CxList *list, size_t index, void *targetbuf); 636 int cxListRemoveAndGet(CxList *list, size_t index, void *targetbuf);
641 637
642 /** 638 /**
643 * Removes and returns the first element of the list. 639 * Removes and returns the first element of the list.
644 * 640 *
645 * 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
651 * @retval zero success 647 * @retval zero success
652 * @retval non-zero the list is empty 648 * @retval non-zero the list is empty
653 * @see cxListPopFront() 649 * @see cxListPopFront()
654 * @see cxListRemoveAndGetLast() 650 * @see cxListRemoveAndGetLast()
655 */ 651 */
656 cx_attr_nonnull cx_attr_access_w(2) 652 CX_EXTERN CX_NONNULL CX_ACCESS_W(2)
657 CX_EXPORT int cxListRemoveAndGetFirst(CxList *list, void *targetbuf); 653 int cxListRemoveAndGetFirst(CxList *list, void *targetbuf);
658 654
659 /** 655 /**
660 * Removes and returns the first element of the list. 656 * Removes and returns the first element of the list.
661 * 657 *
662 * Alias for cxListRemoveAndGetFirst(). 658 * Alias for cxListRemoveAndGetFirst().
685 * @param list the list 681 * @param list the list
686 * @param targetbuf a buffer where to copy the element 682 * @param targetbuf a buffer where to copy the element
687 * @retval zero success 683 * @retval zero success
688 * @retval non-zero the list is empty 684 * @retval non-zero the list is empty
689 */ 685 */
690 cx_attr_nonnull cx_attr_access_w(2) 686 CX_EXTERN CX_NONNULL CX_ACCESS_W(2)
691 CX_EXPORT int cxListRemoveAndGetLast(CxList *list, void *targetbuf); 687 int cxListRemoveAndGetLast(CxList *list, void *targetbuf);
692 688
693 /** 689 /**
694 * Removes and returns the last element of the list. 690 * Removes and returns the last element of the list.
695 * 691 *
696 * Alias for cxListRemoveAndGetLast(). 692 * Alias for cxListRemoveAndGetLast().
721 * @param list the list 717 * @param list the list
722 * @param index the index of the element 718 * @param index the index of the element
723 * @param num the number of elements to remove 719 * @param num the number of elements to remove
724 * @return the actual number of removed elements 720 * @return the actual number of removed elements
725 */ 721 */
726 cx_attr_nonnull 722 CX_EXTERN CX_NONNULL
727 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);
728 724
729 /** 725 /**
730 * Removes and returns multiple elements starting at the specified index. 726 * Removes and returns multiple elements starting at the specified index.
731 * 727 *
732 * 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
737 * @param index the index of the element 733 * @param index the index of the element
738 * @param num the number of elements to remove 734 * @param num the number of elements to remove
739 * @param targetbuf a buffer where to copy the elements 735 * @param targetbuf a buffer where to copy the elements
740 * @return the actual number of removed elements 736 * @return the actual number of removed elements
741 */ 737 */
742 cx_attr_nonnull cx_attr_access_w(4) 738 CX_EXTERN CX_NONNULL CX_ACCESS_W(4)
743 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);
744 740
745 /** 741 /**
746 * Removes all elements from this list. 742 * Removes all elements from this list.
747 * 743 *
748 * If element destructor functions are specified, they are called for each 744 * If element destructor functions are specified, they are called for each
749 * element before removing them. 745 * element before removing them.
750 * 746 *
751 * @param list the list 747 * @param list the list
752 */ 748 */
753 cx_attr_nonnull 749 CX_EXTERN CX_NONNULL
754 CX_EXPORT void cxListClear(CxList *list); 750 void cxListClear(CxList *list);
755 751
756 /** 752 /**
757 * Swaps two items in the list. 753 * Swaps two items in the list.
758 * 754 *
759 * Implementations should only allocate temporary memory for the swap if 755 * Implementations should only allocate temporary memory for the swap if
764 * @param j the index of the second element 760 * @param j the index of the second element
765 * @retval zero success 761 * @retval zero success
766 * @retval non-zero one of the indices is out of bounds, 762 * @retval non-zero one of the indices is out of bounds,
767 * or the swap needed extra memory, but allocation failed 763 * or the swap needed extra memory, but allocation failed
768 */ 764 */
769 cx_attr_nonnull 765 CX_EXTERN CX_NONNULL
770 CX_EXPORT int cxListSwap(CxList *list, size_t i, size_t j); 766 int cxListSwap(CxList *list, size_t i, size_t j);
771 767
772 /** 768 /**
773 * Returns a pointer to the element at the specified index. 769 * Returns a pointer to the element at the specified index.
774 * 770 *
775 * 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.
776 * 772 *
777 * @param list the list 773 * @param list the list
778 * @param index the index of the element 774 * @param index the index of the element
779 * @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
780 */ 776 */
781 cx_attr_nonnull 777 CX_EXTERN CX_NONNULL
782 CX_EXPORT void *cxListAt(const CxList *list, size_t index); 778 void *cxListAt(const CxList *list, size_t index);
783 779
784 /** 780 /**
785 * Returns a pointer to the first element. 781 * Returns a pointer to the first element.
786 * 782 *
787 * 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.
788 * 784 *
789 * @param list the list 785 * @param list the list
790 * @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
791 */ 787 */
792 cx_attr_nonnull 788 CX_EXTERN CX_NONNULL
793 CX_EXPORT void *cxListFirst(const CxList *list); 789 void *cxListFirst(const CxList *list);
794 790
795 /** 791 /**
796 * Returns a pointer to the last element. 792 * Returns a pointer to the last element.
797 * 793 *
798 * 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.
799 * 795 *
800 * @param list the list 796 * @param list the list
801 * @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
802 */ 798 */
803 cx_attr_nonnull 799 CX_EXTERN CX_NONNULL
804 CX_EXPORT void *cxListLast(const CxList *list); 800 void *cxListLast(const CxList *list);
805 801
806 /** 802 /**
807 * Sets the element at the specified index in the list. 803 * Sets the element at the specified index in the list.
808 * 804 *
809 * This overwrites the element in-place without calling any destructor 805 * This overwrites the element in-place without calling any destructor
813 * @param index the index to set the element at 809 * @param index the index to set the element at
814 * @param elem element to set 810 * @param elem element to set
815 * @retval zero on success 811 * @retval zero on success
816 * @retval non-zero when index is out of bounds 812 * @retval non-zero when index is out of bounds
817 */ 813 */
818 cx_attr_nonnull 814 CX_EXTERN CX_NONNULL
819 CX_EXPORT int cxListSet(CxList *list, size_t index, const void *elem); 815 int cxListSet(CxList *list, size_t index, const void *elem);
820 816
821 /** 817 /**
822 * Returns an iterator pointing to the item at the specified index. 818 * Returns an iterator pointing to the item at the specified index.
823 * 819 *
824 * The returned iterator is position-aware. 820 * The returned iterator is position-aware.
827 * 823 *
828 * @param list the list 824 * @param list the list
829 * @param index the index where the iterator shall point at 825 * @param index the index where the iterator shall point at
830 * @return a new iterator 826 * @return a new iterator
831 */ 827 */
832 cx_attr_nodiscard 828 CX_EXTERN CX_NODISCARD
833 CX_EXPORT CxIterator cxListIteratorAt(const CxList *list, size_t index); 829 CxIterator cxListIteratorAt(const CxList *list, size_t index);
834 830
835 /** 831 /**
836 * 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.
837 * 833 *
838 * The returned iterator is position-aware. 834 * The returned iterator is position-aware.
841 * 837 *
842 * @param list the list 838 * @param list the list
843 * @param index the index where the iterator shall point at 839 * @param index the index where the iterator shall point at
844 * @return a new iterator 840 * @return a new iterator
845 */ 841 */
846 cx_attr_nodiscard 842 CX_EXTERN CX_NODISCARD
847 CX_EXPORT CxIterator cxListBackwardsIteratorAt(const CxList *list, size_t index); 843 CxIterator cxListBackwardsIteratorAt(const CxList *list, size_t index);
848 844
849 /** 845 /**
850 * Returns an iterator pointing to the first item of the list. 846 * Returns an iterator pointing to the first item of the list.
851 * 847 *
852 * The returned iterator is position-aware. 848 * The returned iterator is position-aware.
854 * 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.
855 * 851 *
856 * @param list the list 852 * @param list the list
857 * @return a new iterator 853 * @return a new iterator
858 */ 854 */
859 cx_attr_nodiscard 855 CX_EXTERN CX_NODISCARD
860 CX_EXPORT CxIterator cxListIterator(const CxList *list); 856 CxIterator cxListIterator(const CxList *list);
861 857
862 /** 858 /**
863 * 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.
864 * 860 *
865 * The returned iterator is position-aware. 861 * The returned iterator is position-aware.
867 * 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.
868 * 864 *
869 * @param list the list 865 * @param list the list
870 * @return a new iterator 866 * @return a new iterator
871 */ 867 */
872 cx_attr_nodiscard 868 CX_EXTERN CX_NODISCARD
873 CX_EXPORT CxIterator cxListBackwardsIterator(const CxList *list); 869 CxIterator cxListBackwardsIterator(const CxList *list);
874 870
875 /** 871 /**
876 * Returns the index of the first element that equals @p elem. 872 * Returns the index of the first element that equals @p elem.
877 * 873 *
878 * Determining equality is performed by the list's comparator function. 874 * Determining equality is performed by the list's comparator function.
881 * @param elem the element to find 877 * @param elem the element to find
882 * @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
883 * @see cxListIndexValid() 879 * @see cxListIndexValid()
884 * @see cxListContains() 880 * @see cxListContains()
885 */ 881 */
886 cx_attr_nonnull cx_attr_nodiscard 882 CX_EXTERN CX_NONNULL CX_NODISCARD
887 CX_EXPORT size_t cxListFind(const CxList *list, const void *elem); 883 size_t cxListFind(const CxList *list, const void *elem);
888 884
889 /** 885 /**
890 * Checks if the list contains the specified element. 886 * Checks if the list contains the specified element.
891 * 887 *
892 * The elements are compared with the list's comparator function. 888 * The elements are compared with the list's comparator function.
895 * @param elem the element to find 891 * @param elem the element to find
896 * @retval true if the element is contained 892 * @retval true if the element is contained
897 * @retval false if the element is not contained 893 * @retval false if the element is not contained
898 * @see cxListFind() 894 * @see cxListFind()
899 */ 895 */
900 cx_attr_nonnull cx_attr_nodiscard 896 CX_EXTERN CX_NONNULL CX_NODISCARD
901 CX_EXPORT bool cxListContains(const CxList* list, const void* elem); 897 bool cxListContains(const CxList* list, const void* elem);
902 898
903 /** 899 /**
904 * Checks if the specified index is within bounds. 900 * Checks if the specified index is within bounds.
905 * 901 *
906 * @param list the list 902 * @param list the list
907 * @param index the index 903 * @param index the index
908 * @retval true if the index is within bounds 904 * @retval true if the index is within bounds
909 * @retval false if the index is out of bounds 905 * @retval false if the index is out of bounds
910 */ 906 */
911 cx_attr_nonnull cx_attr_nodiscard 907 CX_EXTERN CX_NONNULL CX_NODISCARD
912 CX_EXPORT bool cxListIndexValid(const CxList *list, size_t index); 908 bool cxListIndexValid(const CxList *list, size_t index);
913 909
914 /** 910 /**
915 * 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.
916 * 912 *
917 * Determining equality is performed by the list's comparator function. 913 * Determining equality is performed by the list's comparator function.
920 * @param elem the element to find and remove 916 * @param elem the element to find and remove
921 * @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
922 * when the element is not found or could not be removed 918 * when the element is not found or could not be removed
923 * @see cxListIndexValid() 919 * @see cxListIndexValid()
924 */ 920 */
925 cx_attr_nonnull 921 CX_EXTERN CX_NONNULL
926 CX_EXPORT size_t cxListFindRemove(CxList *list, const void *elem); 922 size_t cxListFindRemove(CxList *list, const void *elem);
927 923
928 /** 924 /**
929 * Sorts the list. 925 * Sorts the list.
930 * 926 *
931 * @remark The underlying sort algorithm is implementation defined. 927 * @remark The underlying sort algorithm is implementation defined.
932 * 928 *
933 * @param list the list 929 * @param list the list
934 */ 930 */
935 cx_attr_nonnull 931 CX_EXTERN CX_NONNULL
936 CX_EXPORT void cxListSort(CxList *list); 932 void cxListSort(CxList *list);
937 933
938 /** 934 /**
939 * Reverses the order of the items. 935 * Reverses the order of the items.
940 * 936 *
941 * @param list the list 937 * @param list the list
942 */ 938 */
943 cx_attr_nonnull 939 CX_EXTERN CX_NONNULL
944 CX_EXPORT void cxListReverse(CxList *list); 940 void cxListReverse(CxList *list);
945 941
946 /** 942 /**
947 * Compares a list to another list of the same type. 943 * Compares a list to another list of the same type.
948 * 944 *
949 * First, the list sizes are compared. 945 * First, the list sizes are compared.
955 * @retval negative the first list is smaller, 951 * @retval negative the first list is smaller,
956 * 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
957 * @retval positive the first list is larger 953 * @retval positive the first list is larger
958 * 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
959 */ 955 */
960 cx_attr_nonnull cx_attr_nodiscard 956 CX_EXTERN CX_NONNULL CX_NODISCARD
961 CX_EXPORT int cxListCompare(const CxList *list, const CxList *other); 957 int cxListCompare(const CxList *list, const CxList *other);
962 958
963 /** 959 /**
964 * Deallocates the memory of the specified list structure. 960 * Deallocates the memory of the specified list structure.
965 * 961 *
966 * Also calls the content destructor functions for each element, if specified. 962 * Also calls the content destructor functions for each element, if specified.
967 * 963 *
968 * @param list the list that shall be freed 964 * @param list the list that shall be freed
969 */ 965 */
970 CX_EXPORT void cxListFree(CxList *list); 966 CX_EXTERN
967 void cxListFree(CxList *list);
971 968
972 969
973 /** 970 /**
974 * Performs a deep clone of one list into another. 971 * Performs a deep clone of one list into another.
975 * 972 *
987 * @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
988 * @retval zero when all elements were successfully cloned 985 * @retval zero when all elements were successfully cloned
989 * @retval non-zero when an allocation error occurred 986 * @retval non-zero when an allocation error occurred
990 * @see cxListCloneShallow() 987 * @see cxListCloneShallow()
991 */ 988 */
992 cx_attr_nonnull_arg(1, 2, 3) 989 CX_EXTERN CX_NONNULL_ARG(1, 2, 3)
993 CX_EXPORT int cxListClone(CxList *dst, const CxList *src, 990 int cxListClone(CxList *dst, const CxList *src,
994 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data); 991 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data);
995 992
996 /** 993 /**
997 * 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.
998 * 995 *
1010 * @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
1011 * @retval zero when the elements were successfully cloned 1008 * @retval zero when the elements were successfully cloned
1012 * @retval non-zero when an allocation error occurred 1009 * @retval non-zero when an allocation error occurred
1013 * @see cxListDifferenceShallow() 1010 * @see cxListDifferenceShallow()
1014 */ 1011 */
1015 cx_attr_nonnull_arg(1, 2, 3, 4) 1012 CX_EXTERN CX_NONNULL_ARG(1, 2, 3, 4)
1016 CX_EXPORT int cxListDifference(CxList *dst, 1013 int cxListDifference(CxList *dst,
1017 const CxList *minuend, const CxList *subtrahend, 1014 const CxList *minuend, const CxList *subtrahend,
1018 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data); 1015 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data);
1019 1016
1020 /** 1017 /**
1021 * 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.
1034 * @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
1035 * @retval zero when the elements were successfully cloned 1032 * @retval zero when the elements were successfully cloned
1036 * @retval non-zero when an allocation error occurred 1033 * @retval non-zero when an allocation error occurred
1037 * @see cxListIntersectionShallow() 1034 * @see cxListIntersectionShallow()
1038 */ 1035 */
1039 cx_attr_nonnull_arg(1, 2, 3, 4) 1036 CX_EXTERN CX_NONNULL_ARG(1, 2, 3, 4)
1040 CX_EXPORT int cxListIntersection(CxList *dst, const CxList *src, const CxList *other, 1037 int cxListIntersection(CxList *dst, const CxList *src, const CxList *other,
1041 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data); 1038 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data);
1042 1039
1043 /** 1040 /**
1044 * Performs a deep clone of one list into another, skipping duplicates. 1041 * Performs a deep clone of one list into another, skipping duplicates.
1045 * 1042 *
1059 * @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
1060 * @retval zero when the elements were successfully cloned 1057 * @retval zero when the elements were successfully cloned
1061 * @retval non-zero when an allocation error occurred 1058 * @retval non-zero when an allocation error occurred
1062 * @see cxListUnionShallow() 1059 * @see cxListUnionShallow()
1063 */ 1060 */
1064 cx_attr_nonnull_arg(1, 2, 3, 4) 1061 CX_EXTERN CX_NONNULL_ARG(1, 2, 3, 4)
1065 CX_EXPORT int cxListUnion(CxList *dst, const CxList *src, const CxList *other, 1062 int cxListUnion(CxList *dst, const CxList *src, const CxList *other,
1066 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data); 1063 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data);
1067 1064
1068 /** 1065 /**
1069 * Performs a shallow clone of one list into another. 1066 * Performs a shallow clone of one list into another.
1070 * 1067 *
1082 * @param src the source list 1079 * @param src the source list
1083 * @retval zero when all elements were successfully cloned 1080 * @retval zero when all elements were successfully cloned
1084 * @retval non-zero when an allocation error occurred 1081 * @retval non-zero when an allocation error occurred
1085 * @see cxListClone() 1082 * @see cxListClone()
1086 */ 1083 */
1087 cx_attr_nonnull 1084 CX_EXTERN CX_NONNULL
1088 CX_EXPORT int cxListCloneShallow(CxList *dst, const CxList *src); 1085 int cxListCloneShallow(CxList *dst, const CxList *src);
1089 1086
1090 /** 1087 /**
1091 * 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.
1092 * 1089 *
1093 * This function uses the default allocator, if needed, and performs 1090 * This function uses the default allocator, if needed, and performs
1104 * @param subtrahend the elements that shall be subtracted 1101 * @param subtrahend the elements that shall be subtracted
1105 * @retval zero when the elements were successfully cloned 1102 * @retval zero when the elements were successfully cloned
1106 * @retval non-zero when an allocation error occurred 1103 * @retval non-zero when an allocation error occurred
1107 * @see cxListDifference() 1104 * @see cxListDifference()
1108 */ 1105 */
1109 cx_attr_nonnull 1106 CX_EXTERN CX_NONNULL
1110 CX_EXPORT int cxListDifferenceShallow(CxList *dst, 1107 int cxListDifferenceShallow(CxList *dst,
1111 const CxList *minuend, const CxList *subtrahend); 1108 const CxList *minuend, const CxList *subtrahend);
1112 1109
1113 /** 1110 /**
1114 * 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.
1115 * 1112 *
1127 * @param other the list to check the elements for existence 1124 * @param other the list to check the elements for existence
1128 * @retval zero when the elements were successfully cloned 1125 * @retval zero when the elements were successfully cloned
1129 * @retval non-zero when an allocation error occurred 1126 * @retval non-zero when an allocation error occurred
1130 * @see cxListIntersection() 1127 * @see cxListIntersection()
1131 */ 1128 */
1132 cx_attr_nonnull 1129 CX_EXTERN CX_NONNULL
1133 CX_EXPORT int cxListIntersectionShallow(CxList *dst, const CxList *src, const CxList *other); 1130 int cxListIntersectionShallow(CxList *dst, const CxList *src, const CxList *other);
1134 1131
1135 /** 1132 /**
1136 * Performs a deep clone of one list into another, skipping duplicates. 1133 * Performs a deep clone of one list into another, skipping duplicates.
1137 * 1134 *
1138 * This function uses the default allocator, if needed, and performs 1135 * This function uses the default allocator, if needed, and performs
1151 * when they are not in @p src 1148 * when they are not in @p src
1152 * @retval zero when the elements were successfully cloned 1149 * @retval zero when the elements were successfully cloned
1153 * @retval non-zero when an allocation error occurred 1150 * @retval non-zero when an allocation error occurred
1154 * @see cxListUnion() 1151 * @see cxListUnion()
1155 */ 1152 */
1156 cx_attr_nonnull 1153 CX_EXTERN CX_NONNULL
1157 CX_EXPORT int cxListUnionShallow(CxList *dst, const CxList *src, const CxList *other); 1154 int cxListUnionShallow(CxList *dst, const CxList *src, const CxList *other);
1158 1155
1159 /** 1156 /**
1160 * 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.
1161 * 1158 *
1162 * List implementations are free to choose if reserving memory upfront makes 1159 * List implementations are free to choose if reserving memory upfront makes
1171 * @param capacity the expected total number of elements 1168 * @param capacity the expected total number of elements
1172 * @retval zero on success or when overallocation is not supported 1169 * @retval zero on success or when overallocation is not supported
1173 * @retval non-zero when an allocation error occurred 1170 * @retval non-zero when an allocation error occurred
1174 * @see cxListShrink() 1171 * @see cxListShrink()
1175 */ 1172 */
1176 cx_attr_nonnull 1173 CX_EXTERN CX_NONNULL
1177 CX_EXPORT int cxListReserve(CxList *list, size_t capacity); 1174 int cxListReserve(CxList *list, size_t capacity);
1178 1175
1179 /** 1176 /**
1180 * Advises the list to free any overallocated memory. 1177 * Advises the list to free any overallocated memory.
1181 * 1178 *
1182 * Lists that do not support overallocation simply return zero. 1179 * Lists that do not support overallocation simply return zero.
1185 * list and/or allocator implementations where freeing memory can fail. 1182 * list and/or allocator implementations where freeing memory can fail.
1186 * 1183 *
1187 * @param list the list 1184 * @param list the list
1188 * @return usually zero 1185 * @return usually zero
1189 */ 1186 */
1190 cx_attr_nonnull 1187 CX_EXTERN CX_NONNULL
1191 CX_EXPORT int cxListShrink(CxList *list); 1188 int cxListShrink(CxList *list);
1192
1193 #ifdef __cplusplus
1194 } // extern "C"
1195 #endif
1196 1189
1197 #endif // UCX_LIST_H 1190 #endif // UCX_LIST_H

Mercurial Repository: ucx

mercurial