dav: comparison ucx/cx/array

-:e77ccf1c4bb3
+:4d58cbcc9efa
 * a stack buffer when swapped.
 */
 CX_EXPORT extern const unsigned cx_array_swap_sbo_size;
 /**
-* Declares variables for an array that can be used with the convenience macros.
+* Declares a typed array with size and capacity.
 *
-* @par Examples
+* @param type the type of the elements
-* @code
-* // integer array with at most 255 elements
-* CX_ARRAY_DECLARE_SIZED(int, myarray, uint8_t)
-*
-* // array of MyObject* pointers where size and capacity are stored as unsigned int
-* CX_ARRAY_DECLARE_SIZED(MyObject*, objects, unsigned int)
-*
-* // initializing code
-* cx_array_initialize(myarray, 16); // reserve space for 16
-* cx_array_initialize(objects, 100); // reserve space for 100
-* @endcode
-*
-* @param type the type of the data
 * @param name the name of the array
-* @param size_type the type of the size (should be uint8_t, uint16_t, uint32_t, or size_t)
+*/
-*
+#define CX_ARRAY(type, name) \
-* @see cx_array_initialize()
+struct { \
-* @see cx_array_simple_add()
+type *data; \
-* @see cx_array_simple_copy()
+size_t size; \
-* @see cx_array_simple_add_sorted()
+size_t capacity; \
-* @see cx_array_simple_insert_sorted()
+} name
-*/
-#define CX_ARRAY_DECLARE_SIZED(type, name, size_type) \
+/**
-type * name; \
+* Internal structure for arrays.
-/** Array size. */ size_type name##_size; \
+*
-/** Array capacity. */ size_type name##_capacity
+* A generalization of array structures declared with CX_ARRAY().
+*/
-/**
+typedef struct cx_array_s {
-* Declares variables for an array that can be used with the convenience macros.
+/** The array data. */
-*
+void *data;
-* The size and capacity variables will have type @c size_t.
+/** The number of elements. */
-* Use #CX_ARRAY_DECLARE_SIZED() to specify a different type.
+size_t size;
-*
+/** The maximum number of elements. */
-* @par Examples
+size_t capacity;
-* @code
+} CxArray;
-* // int array
-* CX_ARRAY_DECLARE(int, myarray)
+/**
-*
+* Initializes an array by allocating memory.
-* // initializing code
+*
-* cx_array_initialize(myarray, 32); // reserve space for 32
+* Internal function - do not use manually.
-* @endcode
+*
-*
+* @param allocator the allocator for the array
-* @param type the type of the data
+* @param array a pointer to the array structure
-* @param name the name of the array
+* @param elem_size size of one element
-*
+* @param capacity the initial maximum number of elements
-* @see cx_array_initialize()
+* @retval zero allocation was successful
-* @see cx_array_simple_add()
+* @retval non-zero allocation failed
-* @see cx_array_simple_copy()
+*/
-* @see cx_array_simple_add_sorted()
+cx_attr_nonnull
-* @see cx_array_simple_insert_sorted()
+CX_EXPORT int cx_array_init_(const CxAllocator *allocator, CxArray *array, size_t elem_size, size_t capacity);
-*/
-#define CX_ARRAY_DECLARE(type, name) CX_ARRAY_DECLARE_SIZED(type, name, size_t)
+/**
+* Initializes an array by allocating memory.
-/**
+*
-* Initializes an array with the given capacity.
+* The size is set to zero.
 *
-* The type of the capacity depends on the type used during declaration.
+* @attention If the array was already initialized, this will leak memory.
-*
+* Use cx_array_reserve() to change the capacity of an initialized array.
-* @par Examples
+*
-* @code
+* @param allocator (@c CxAllocator*) the allocator for the array
-* CX_ARRAY_DECLARE_SIZED(int, arr1, uint8_t)
+* @param array the name of the array
-* CX_ARRAY_DECLARE(int, arr2) // size and capacity are implicitly size_t
+* @param capacity (@c size_t) the initial maximum number of elements
-*
+* @retval zero allocation was successful
-* // initializing code
+* @retval non-zero allocation failed
-* cx_array_initialize(arr1, 500); // error: maximum for uint8_t is 255
+*/
-* cx_array_initialize(arr2, 500); // OK
+#define cx_array_init_a(allocator, array, capacity) cx_array_init_(allocator, (CxArray*)&(array), sizeof((array).data[0]), capacity)
-* @endcode
-*
+/**
-*
+* Initializes an array by allocating memory.
-* The memory for the array is allocated with the cxDefaultAllocator.
+*
-*
+* The size is set to zero.
-* @param array the name of the array
+*
-* @param capacity the initial capacity
+* @attention If the array was already initialized, this will leak memory.
-* @see cx_array_initialize_a()
+*
-* @see CX_ARRAY_DECLARE_SIZED()
+* @param array the name of the array
-* @see CX_ARRAY_DECLARE()
+* @param capacity (@c size_t) the initial maximum number of elements
-*/
+* @retval zero allocation was successful
-#define cx_array_initialize(array, capacity) \
+* @retval non-zero allocation failed
-array##_capacity = capacity; \
+*/
-array##_size = 0; \
+#define cx_array_init(array, capacity) cx_array_init_a(cxDefaultAllocator, array, capacity)
-array = cxMallocDefault(sizeof(array[0]) * capacity)
+/**
-/**
+* Initializes an array with fixed size memory.
-* Initializes an array with the given capacity using the specified allocator.
+*
-*
+* Internal function - do not use manually.
-* @par Example
+*
-* @code
+* @param array a pointer to the array structure
-* CX_ARRAY_DECLARE(int, myarray)
+* @param data the fixed size array
-*
+* @param capacity the capacity of the fixed size array
-*
+* @param size the number of initialized elements in the fixed size array
-* const CxAllocator *al = // ...
+*/
-* cx_array_initialize_a(al, myarray, 128);
+cx_attr_nonnull
-* // ...
+CX_EXPORT void cx_array_init_fixed_(CxArray *array, const void *data, size_t capacity, size_t size);
-* cxFree(al, myarray); // remember to free with the same allocator
-* @endcode
+/**
-*
+* Initializes an array with fixed size memory.
-* @param allocator (@c CxAllocator*) the allocator
+*
-* @param array the name of the array
+* This is useful, for example, when you want to work with memory on the stack
-* @param capacity the initial capacity
+* and only want to move to the heap when the stack memory is not enough.
-* @see cx_array_initialize()
+*
-* @see CX_ARRAY_DECLARE_SIZED()
+* With the @p num_initialized argument you can specify how many elements in the
-* @see CX_ARRAY_DECLARE()
+* fixed size array are already correctly initialized, which determines the
-*/
+* initial size of the array.
-#define cx_array_initialize_a(allocator, array, capacity) \
+*
-array##_capacity = capacity; \
+* The capacity is determined automatically by the compiler.
-array##_size = 0; \
+*
-array = cxMalloc(allocator, sizeof(array[0]) * capacity)
+* @attention When you add elements to an array that was initialized with fixed
+* size memory, you MUST check the capacity before adding the element and invoke
-/**
+* cx_array_copy_to_new() when you intend to exceed the capacity.
-* Defines a reallocation mechanism for arrays.
+*
-* You can create your own, use cx_array_reallocator(), or
+* @attention When you pass a pointer to an array that does not have a fixed
-* use the #cx_array_default_reallocator.
+* size, the behavior is unspecified.
-*/
+*
-struct cx_array_reallocator_s {
+* @param array the name of the array to initialize
-/**
+* @param fixed_size_array (@c void*) the fixed size array
-* Reallocates space for the given array.
+* @param num_initialized (@c size_t) the number of already initialized elements in the fixed size array
-*
+* @see cx_array_copy_to_new()
-* Implementations are not required to free the original array.
+*/
-* This allows reallocation of static or stack memory by allocating heap memory
+#define cx_array_init_fixed(array, fixed_size_array, num_initialized) \
-* and copying the array contents; namely when @c stack_ptr in this struct
+cx_array_init_fixed_((CxArray*)&(array), fixed_size_array, cx_nmemb(fixed_size_array), num_initialized)
-* is not @c NULL and @p array equals @c stack_ptr.
-*
+/**
-* @param array the array to reallocate
+* Changes the capacity of an array.
-* @param old_capacity the old number of elements
+*
-* @param new_capacity the new number of elements
+* Internal function - do not use.
-* @param elem_size the size of each element
+*
-* @param alloc a reference to this allocator
+* @param allocator the allocator
-* @return a pointer to the reallocated memory or @c NULL on failure
+* @param array a pointer to the array structure
-*/
+* @param elem_size the size of one element
-void *(*realloc)( void *array, size_t old_capacity, size_t new_capacity,
+* @param capacity the new capacity
-size_t elem_size, struct cx_array_reallocator_s *alloc);
+* @retval zero allocation was successful
+* @retval non-zero allocation failed
-/**
+*/
-* The allocator that shall be used for the reallocations.
+cx_attr_nonnull
-*/
+CX_EXPORT int cx_array_reserve_(const CxAllocator *allocator, CxArray *array, size_t elem_size, size_t capacity);
-const CxAllocator *allocator;
 /**
-* Optional pointer to stack memory
+* Changes the capacity of an array.
-* if the array is originally located on the stack.
+*
-*/
+* If required, the size is reduced to fit into the new capacity.
-const void *stack_ptr;
+*
-};
+* @param allocator (@c CxAllocator*) the allocator for the array
+* @param array the name of the array
-/**
+* @param capacity (@c size_t) the new maximum number of elements
-* Typedef for the array reallocator struct.
+* @retval zero allocation was successful
-*/
+* @retval non-zero allocation failed
-typedef struct cx_array_reallocator_s CxArrayReallocator;
+*/
+#define cx_array_reserve_a(allocator, array, capacity) \
-/**
+cx_array_reserve_(allocator, (CxArray*)&(array), sizeof((array).data[0]), capacity)
-* A default array reallocator that is based on the cxDefaultAllocator.
-*/
+/**
-CX_EXPORT extern CxArrayReallocator *cx_array_default_reallocator;
+* Changes the capacity of an array.
+*
-/**
+* If required, the size is reduced to fit into the new capacity.
-* Creates a new array reallocator.
+*
-*
+* @param array the name of the array
-* When @p allocator is @c NULL, the cxDefaultAllocator will be used.
+* @param capacity (@c size_t) the new maximum number of elements
-*
+* @retval zero allocation was successful
-* When @p stack_ptr is not @c NULL, the reallocator is supposed to be used
+* @retval non-zero allocation failed
-* @em only for the specific array initially located at @p stack_ptr.
+*/
-* When reallocation is needed, the reallocator checks if the array is
+#define cx_array_reserve(array, capacity) \
-* still located at @p stack_ptr and copies the contents to the heap.
+cx_array_reserve_a(cxDefaultAllocator, array, capacity)
-*
-* @note Invoking this function with both arguments being @c NULL will return a
+/**
-* reallocator that behaves like #cx_array_default_reallocator.
+* Copies the array to a new memory region.
 *
-* @param allocator the allocator this reallocator shall be based on
+* Internal function - do not use.
-* @param stack_ptr the address of the array when the array is initially located
+*
-* on the stack or shall not reallocate in place
+* @param allocator the allocator for new new memory
-* @return an array reallocator
+* @param array a pointer to the array structure
-*/
+* @param elem_size the size of one element
-CX_EXPORT CxArrayReallocator cx_array_reallocator(
+* @param capacity the new capacity
-const struct cx_allocator_s *allocator, const void *stack_ptr);
+* @retval zero allocation was successful
+* @retval non-zero allocation failed
-/**
+*/
-* Reserves memory for additional elements.
+cx_attr_nonnull
-*
+CX_EXPORT int cx_array_copy_to_new_(const CxAllocator *allocator, CxArray *array, size_t elem_size, size_t capacity);
-* This function checks if the @p capacity of the array is sufficient to hold
-* at least @p size plus @p elem_count elements. If not, a reallocation is
+/**
-* performed with the specified @p reallocator.
+* Copies the array to a new memory region.
-* You can create your own reallocator by hand, use #cx_array_default_reallocator,
+*
-* or use the convenience function cx_array_reallocator() to create a custom reallocator.
+* This is useful when you have initialized the array with a fixed size memory
-*
+* using cx_array_init_fixed(), and now you want to increase the capacity.
-* This function can be useful to replace subsequent calls to cx_array_copy()
+*
-* with one single cx_array_reserve() and then - after guaranteeing a
+* @attention When the original memory does not belong to stack memory, and
-* sufficient capacity - use simple memmove() or memcpy().
+* you do not have another reference to this memory, it will leak.
 *
-* The @p width in bytes refers to the size and capacity.
+* @param allocator (@c CxAllocator*) the allocator for the new memory
-* Both must have the same width.
+* @param array the name of the array
-* Supported are 0, 1, 2, and 4, as well as 8 if running on a 64-bit
+* @param capacity (@c size_t) the new maximum number of elements
-* architecture. If set to zero, the native word width is used.
+* @retval zero allocation was successful
-*
+* @retval non-zero allocation failed
-* @param array a pointer to the target array
+* @see cx_array_init_fixed()
-* @param size a pointer to the size of the array
+*/
-* @param capacity a pointer to the capacity of the array
+#define cx_array_copy_to_new_a(allocator, array, capacity) \
-* @param width the width in bytes for the @p size and @p capacity or zero for default
+cx_array_copy_to_new_(allocator, (CxArray*)&(array), sizeof((array).data[0]), capacity)
-* @param elem_size the size of one element
-* @param elem_count the number of expected additional elements
+/**
-* @param reallocator the array reallocator to use
+* Copies the array to a new memory region.
-* (@c NULL defaults to #cx_array_default_reallocator)
+*
-* @retval zero success
+* This is useful when you have initialized the array with a fixed size memory
-* @retval non-zero failure
+* using cx_array_init_fixed(), and now you want to increase the capacity.
-* @see cx_array_reallocator()
+*
-*/
+* @attention When the original memory does not belong to stack memory, and
-cx_attr_nonnull_arg(1, 2, 3)
+* you do not have another reference to this memory, it will leak.
-CX_EXPORT int cx_array_reserve(void **array, void *size, void *capacity,
+*
-unsigned width, size_t elem_size, size_t elem_count,
+* @param array the name of the array
-CxArrayReallocator *reallocator);
+* @param capacity (@c size_t) the new maximum number of elements
+* @retval zero allocation was successful
-/**
+* @retval non-zero allocation failed
-* Copies elements from one array to another.
+* @see cx_array_init_fixed()
-*
+*/
-* The elements are copied to the @p target array at the specified @p index,
+#define cx_array_copy_to_new(array, capacity) \
-* overwriting possible elements. The @p index does not need to be in range of
+cx_array_copy_to_new_a(cxDefaultAllocator, array, capacity)
-* the current array @p size. If the new index plus the number of elements added
-* extends the array's size, the remaining @p capacity is used.
+/**
-*
+* Inserts data into an array.
-* If the @p capacity is also insufficient to hold the new data, a reallocation
+*
-* attempt is made with the specified @p reallocator.
+* Internal function - do not use.
-* You can create your own reallocator by hand, use #cx_array_default_reallocator,
+*
-* or use the convenience function cx_array_reallocator() to create a custom reallocator.
+* @param allocator the allocator to use for a possible reallocation
-*
+* @param array a pointer to the array structure
-* The @p width in bytes refers to the size and capacity.
+* @param elem_size the size of one element
-* Both must have the same width.
+* @param index the index where to insert the @p other data
-* Supported are 0, 1, 2, and 4, as well as 8 if running on a 64-bit
+* @param other a pointer to an array of data that shall be inserted
-* architecture. If set to zero, the native word width is used.
+* @param n the number of elements that shall be inserted
-*
+* @retval zero success
-* @param target a pointer to the target array
+* @retval non-zero a re-allocation was necessary but failed
-* @param size a pointer to the size of the target array
+*/
-* @param capacity a pointer to the capacity of the target array
+cx_attr_nonnull_arg(1, 2)
-* @param width the width in bytes for the @p size and @p capacity or zero for default
+CX_EXPORT int cx_array_insert_(const CxAllocator *allocator, CxArray *array,
-* @param index the index where the copied elements shall be placed
+size_t elem_size, size_t index, const void *other, size_t n);
-* @param src the source array
-* @param elem_size the size of one element
+/**
-* @param elem_count the number of elements to copy
+* Appends an element to an array.
-* @param reallocator the array reallocator to use
+*
-* (@c NULL defaults to #cx_array_default_reallocator)
+* When the capacity is not enough to hold the new element, a re-allocation is attempted.
-* @retval zero success
+*
-* @retval non-zero failure
+* @param allocator (@c CxAllocator*) the allocator to use for a possible reallocation
-* @see cx_array_reallocator()
+* @param array the name of the array where the element shall be added
-*/
+* @param element the element that shall be added
-cx_attr_nonnull_arg(1, 2, 3, 6)
+* @retval zero success
-CX_EXPORT int cx_array_copy(void **target, void *size, void *capacity, unsigned width,
+* @retval non-zero a re-allocation was necessary but failed
-size_t index, const void *src, size_t elem_size, size_t elem_count,
+*/
-CxArrayReallocator *reallocator);
+#define cx_array_add_a(allocator, array, element) \
+cx_array_insert_(allocator, (CxArray*)&(array), sizeof((array).data[0]), (array).size, (void*)&(element), 1)
-/**
-* Convenience macro that uses cx_array_copy() with a default layout and
+/**
-* the specified reallocator.
+* Appends an element to an array.
 *
-* @param reallocator (@c CxArrayReallocator*) the array reallocator to use
+* When the capacity is not enough to hold the new element, a re-allocation is attempted.
-* @param array the name of the array (NOT a pointer or alias to the array)
+*
-* @param index (@c size_t) the index where the copied elements shall be placed
+* @param array the name of the array where the element shall be added
-* @param src (@c void*) the source array
+* @param element (@c void*) a pointer to the element that shall be added
-* @param count (@c size_t) the number of elements to copy
+* @retval zero success
-* @retval zero success
+* @retval non-zero a re-allocation was necessary but failed
-* @retval non-zero failure
+*/
-* @see CX_ARRAY_DECLARE()
+#define cx_array_add(array, element) \
-* @see cx_array_simple_copy()
+cx_array_add_a(cxDefaultAllocator, array, element)
-*/
-#define cx_array_simple_copy_a(reallocator, array, index, src, count) \
+/**
-cx_array_copy((void**)&(array), &(array##_size), &(array##_capacity), \
+* Inserts an element into an array.
-sizeof(array##_size), index, src, sizeof((array)[0]), count, \
+*
-reallocator)
+* When the capacity is not enough to hold the new element, a re-allocation is attempted.
+*
-/**
+* @param allocator (@c CxAllocator*) the allocator to use for a possible reallocation
-* Convenience macro that uses cx_array_copy() with a default layout and
+* @param array the name of the array where the element shall be inserted
-* the default reallocator.
+* @param index (@c size_t) the index where to insert the @p element
-*
+* @param element the element that shall be inserted
-* @param array the name of the array (NOT a pointer or alias to the array)
+* @retval zero success
-* @param index (@c size_t) the index where the copied elements shall be placed
+* @retval non-zero a re-allocation was necessary but failed
-* @param src (@c void*) the source array
+*/
-* @param count (@c size_t) the number of elements to copy
+#define cx_array_insert_a(allocator, array, index, element) \
-* @retval zero success
+cx_array_insert_(allocator, (CxArray*)&(array), sizeof((array).data[0]), index, (void*)&(element), 1)
-* @retval non-zero failure
-* @see CX_ARRAY_DECLARE()
+/**
-* @see cx_array_simple_copy_a()
+* Inserts an element into an array.
-*/
+*
-#define cx_array_simple_copy(array, index, src, count) \
+* When the capacity is not enough to hold the new element, a re-allocation is attempted.
-cx_array_simple_copy_a(NULL, array, index, src, count)
+*
+* @param array the name of the array where the element shall be inserted
-/**
+* @param index (@c size_t) the index where to insert the @p element
-* Convenience macro that uses cx_array_reserve() with a default layout and
+* @param element (@c void*) a pointer to the element that shall be inserted
-* the specified reallocator.
+* @retval zero success
-*
+* @retval non-zero a re-allocation was necessary but failed
-* @param reallocator (@c CxArrayReallocator*) the array reallocator to use
+*/
-* @param array the name of the array (NOT a pointer or alias to the array)
+#define cx_array_insert(array, index, element) \
-* @param count (@c size_t) the number of expected @em additional elements
+cx_array_insert_a(cxDefaultAllocator, array, index, element)
-* @retval zero success
-* @retval non-zero failure
+/**
-* @see CX_ARRAY_DECLARE()
+* Inserts data into an array.
-* @see cx_array_simple_reserve()
+*
-*/
+* When the capacity is not enough to hold the new elements, a re-allocation is attempted.
-#define cx_array_simple_reserve_a(reallocator, array, count) \
+*
-cx_array_reserve((void**)&(array), &(array##_size), &(array##_capacity), \
+* @param allocator (@c CxAllocator*) the allocator to use for a possible reallocation
-sizeof(array##_size), sizeof((array)[0]), count, \
+* @param array the name of the array where the elements shall be inserted
-reallocator)
+* @param index (@c size_t) the index where to insert the @p other data
+* @param other (@c void*) a pointer to an array of data that shall be inserted
-/**
+* @param n (@c size_t) the number of elements that shall be inserted
-* Convenience macro that uses cx_array_reserve() with a default layout and
+* @retval zero success
-* the default reallocator.
+* @retval non-zero a re-allocation was necessary but failed
-*
+*/
-* @param array the name of the array (NOT a pointer or alias to the array)
+#define cx_array_insert_array_a(allocator, array, index, other, n) \
-* @param count (@c size_t) the number of expected additional elements
+cx_array_insert_(allocator, (CxArray*)&(array), sizeof((array).data[0]), index, other, n)
-* @retval zero success
-* @retval non-zero failure
+/**
-* @see CX_ARRAY_DECLARE()
+* Inserts data into an array.
-* @see cx_array_simple_reserve_a()
+*
-*/
+* When the capacity is not enough to hold the new elements, a re-allocation is attempted.
-#define cx_array_simple_reserve(array, count) \
+*
-cx_array_simple_reserve_a(NULL, array, count)
+* @param array the name of the array where the elements shall be inserted
+* @param index (@c size_t) the index where to insert the @p other data
-/**
+* @param other (@c void*) a pointer to an array of data that shall be inserted
-* Adds an element to an array with the possibility of allocating more space.
+* @param n (@c size_t) the number of elements that shall be inserted
-*
+* @retval zero success
-* The element @p elem is added to the end of the @p target array which contains
+* @retval non-zero a re-allocation was necessary but failed
-* @p size elements, already. The @p capacity must point to a variable denoting
+*/
-* the current maximum number of elements the array can hold.
+#define cx_array_insert_array(array, index, other, n) \
-*
+cx_array_insert_array_a(cxDefaultAllocator, array, index, other, n)
-* If the capacity is insufficient to hold the new element, an attempt to
-* increase the @p capacity is made and the new capacity is written back.
+/**
-*
+* Appends data to an array.
-* The \@ SIZE_TYPE is flexible and can be any unsigned integer type.
+*
-* It is important, however, that @p size and @p capacity are pointers to
+* When the capacity is not enough to hold the new elements, a re-allocation is attempted.
-* variables of the same type.
+*
-*
+* @param allocator (@c CxAllocator*) the allocator to use for a possible reallocation
-* @param target (@c void**) a pointer to the target array
+* @param array the name of the array where the elements shall be added
-* @param size (@c SIZE_TYPE*) a pointer to the size of the target array
+* @param other (@c void*) a pointer to an array of data that shall be added
-* @param capacity (@c SIZE_TYPE*) a pointer to the capacity of the target array
+* @param n (@c size_t) the number of elements that shall be added
-* @param elem_size (@c size_t) the size of one element
+* @retval zero success
-* @param elem (@c void*) a pointer to the element to add
+* @retval non-zero a re-allocation was necessary but failed
-* @param reallocator (@c CxArrayReallocator*) the array reallocator to use
+*/
-* @retval zero success
+#define cx_array_add_array_a(allocator, array, other, n) \
-* @retval non-zero failure
+cx_array_insert_(allocator, (CxArray*)&(array), sizeof((array).data[0]), (array).size, other, n)
-*/
-#define cx_array_add(target, size, capacity, elem_size, elem, reallocator) \
+/**
-cx_array_copy((void**)(target), size, capacity, sizeof(*(size)), \
+* Appends data to an array.
-*(size), elem, elem_size, 1, reallocator)
+*
+* When the capacity is not enough to hold the new elements, a re-allocation is attempted.
-/**
+*
-* Convenience macro that uses cx_array_add() with a default layout and
+* @param array the name of the array where the elements shall be added
-* the specified reallocator.
+* @param other (@c void*) a pointer to an array of data that shall be added
-*
+* @param n (@c size_t) the number of elements that shall be added
-* @param reallocator (@c CxArrayReallocator*) the array reallocator to use
+* @retval zero success
-* @param array the name of the array (NOT a pointer or alias to the array)
+* @retval non-zero a re-allocation was necessary but failed
-* @param elem the element to add (NOT a pointer, address is automatically taken)
+*/
-* @retval zero success
+#define cx_array_add_array(array, other, n) \
-* @retval non-zero failure
+cx_array_add_array_a(cxDefaultAllocator, array, other, n)
-* @see CX_ARRAY_DECLARE()
-* @see cx_array_simple_add()
+/**
-*/
+* Inserts sorted data into a sorted array.
-#define cx_array_simple_add_a(reallocator, array, elem) \
+*
-cx_array_simple_copy_a(reallocator, array, array##_size, &(elem), 1)
+* Internal function - do not use.
+*
-/**
+* @param allocator the allocator to use for a possible reallocation
-* Convenience macro that uses cx_array_add() with a default layout and
+* @param array a pointer to the array structure
-* the default reallocator.
+* @param elem_size the size of one element
-*
+* @param sorted_data a pointer to an array of data that shall be inserted
-* @param array the name of the array (NOT a pointer or alias to the array)
+* @param n the number of elements that shall be inserted
-* @param elem the element to add (NOT a pointer, address is automatically taken)
+* @param cmp_func the compare function
-* @retval zero success
+* @param allow_duplicates @c false if duplicates shall be skipped during insertion
-* @retval non-zero failure
+* @retval zero success
-* @see CX_ARRAY_DECLARE()
+* @retval non-zero a re-allocation was necessary but failed
-* @see cx_array_simple_add_a()
+*/
-*/
+cx_attr_nonnull
-#define cx_array_simple_add(array, elem) \
+CX_EXPORT int cx_array_insert_sorted_(const CxAllocator *allocator, CxArray *array,
-cx_array_simple_add_a(cx_array_default_reallocator, array, elem)
+size_t elem_size, const void *sorted_data, size_t n,
+cx_compare_func cmp_func, bool allow_duplicates);
-/**
-* Inserts a sorted array into another sorted array.
-*
-* If either the target or the source array is not already sorted with respect
-* to the specified @p cmp_func, the behavior is undefined.
-*
-* If the capacity is insufficient to hold the new data, a reallocation
-* attempt is made.
-* You can create your own reallocator by hand, use #cx_array_default_reallocator,
-* or use the convenience function cx_array_reallocator() to create a custom reallocator.
-*
-* @param target a pointer to the target array
-* @param size a pointer to the size of the target array
-* @param capacity a pointer to the capacity of the target array
-* @param cmp_func the compare function for the elements
-* @param src the source array
-* @param elem_size the size of one element
-* @param elem_count the number of elements to insert
-* @param reallocator the array reallocator to use
-* (@c NULL defaults to #cx_array_default_reallocator)
-* @retval zero success
-* @retval non-zero failure
-*/
-cx_attr_nonnull_arg(1, 2, 3, 5)
-CX_EXPORT int cx_array_insert_sorted(void **target, size_t *size, size_t *capacity,
-cx_compare_func cmp_func, const void *src, size_t elem_size, size_t elem_count,
-CxArrayReallocator *reallocator);
 /**
 * Inserts an element into a sorted array.
 *
-* If the target array is not already sorted with respect
+* When the capacity is not enough to hold the new element, a re-allocation is attempted.
-* to the specified @p cmp_func, the behavior is undefined.
+*
-*
+* @attention if the array is not sorted according to the specified @p cmp_func, the behavior is undefined.
-* If the capacity is not enough to hold the new data, a reallocation
+*
-* attempt is made.
+* @param allocator (@c CxAllocator*) the allocator to use for a possible reallocation
-*
+* @param array the name of the array where the elements shall be inserted
-* The \@ SIZE_TYPE is flexible and can be any unsigned integer type.
+* @param element the element that shall be inserted
-* It is important, however, that @p size and @p capacity are pointers to
+* @param cmp_func (@c cx_compare_func) the compare function that establishes the order
-* variables of the same type.
+* @retval zero success
-*
+* @retval non-zero a re-allocation was necessary but failed
-* @param target (@c void**) a pointer to the target array
+*/
-* @param size (@c SIZE_TYPE*) a pointer to the size of the target array
+#define cx_array_insert_sorted_a(allocator, array, element, cmp_func) \
-* @param capacity (@c SIZE_TYPE*) a pointer to the capacity of the target array
+cx_array_insert_sorted_(allocator, (CxArray*)&(array), sizeof((array).data[0]), (void*)&(element), 1, cmp_func, true)
-* @param elem_size (@c size_t) the size of one element
-* @param elem (@c void*) a pointer to the element to add
+/**
-* @param cmp_func (@c cx_cmp_func) the compare function for the elements
+* Inserts an element into a sorted array.
-* @param reallocator (@c CxArrayReallocator*) the array reallocator to use
+*
-* @retval zero success
+* When the capacity is not enough to hold the new element, a re-allocation is attempted.
-* @retval non-zero failure
+*
-*/
+* @attention if the array is not sorted according to the specified @p cmp_func, the behavior is undefined.
-#define cx_array_add_sorted(target, size, capacity, elem_size, elem, cmp_func, reallocator) \
+*
-cx_array_insert_sorted((void**)(target), size, capacity, cmp_func, elem, elem_size, 1, reallocator)
+* @param array the name of the array where the elements shall be inserted
+* @param element the element that shall be inserted
-/**
+* @param cmp_func (@c cx_compare_func) the compare function that establishes the order
-* Convenience macro for cx_array_add_sorted() with a default
+* @retval zero success
-* layout and the specified reallocator.
+* @retval non-zero a re-allocation was necessary but failed
-*
+*/
-* @param reallocator (@c CxArrayReallocator*) the array reallocator to use
+#define cx_array_insert_sorted(array, element, cmp_func) \
-* @param array the name of the array (NOT a pointer or alias to the array)
+cx_array_insert_sorted_a(cxDefaultAllocator, array, element, cmp_func)
-* @param elem the element to add (NOT a pointer, address is automatically taken)
-* @param cmp_func (@c cx_cmp_func) the compare function for the elements
+/**
-* @retval zero success
+* Inserts sorted data into a sorted array.
-* @retval non-zero failure
+*
-* @see CX_ARRAY_DECLARE()
+* When the capacity is not enough to hold the new elements, a re-allocation is attempted.
-* @see cx_array_simple_add_sorted()
+*
-*/
+* @attention if either array is not sorted according to the specified @p cmp_func, the behavior is undefined.
-#define cx_array_simple_add_sorted_a(reallocator, array, elem, cmp_func) \
+*
-cx_array_add_sorted(&array, &(array##_size), &(array##_capacity), \
+* @param allocator (@c CxAllocator*) the allocator to use for a possible reallocation
-sizeof((array)[0]), &(elem), cmp_func, reallocator)
+* @param array the name of the array where the elements shall be inserted
+* @param sorted_data (@c void*) a pointer to an array of sorted data that shall be inserted
-/**
+* @param n (@c size_t) the number of elements that shall be inserted
-* Convenience macro for cx_array_add_sorted() with a default
+* @param cmp_func (@c cx_compare_func) the compare function that establishes the order
-* layout and the default reallocator.
+* @retval zero success
-*
+* @retval non-zero a re-allocation was necessary but failed
-* @param array the name of the array (NOT a pointer or alias to the array)
+*/
-* @param elem the element to add (NOT a pointer, address is automatically taken)
+#define cx_array_insert_sorted_array_a(allocator, array, sorted_data, n, cmp_func) \
-* @param cmp_func (@c cx_cmp_func) the compare function for the elements
+cx_array_insert_sorted_(allocator, (CxArray*)&(array), sizeof((array).data[0]), sorted_data, n, cmp_func, true)
-* @retval zero success
-* @retval non-zero failure
+/**
-* @see CX_ARRAY_DECLARE()
+* Inserts sorted data into a sorted array.
-* @see cx_array_simple_add_sorted_a()
+*
-*/
+* When the capacity is not enough to hold the new elements, a re-allocation is attempted.
-#define cx_array_simple_add_sorted(array, elem, cmp_func) \
+*
-cx_array_simple_add_sorted_a(NULL, array, elem, cmp_func)
+* @attention if either array is not sorted according to the specified @p cmp_func, the behavior is undefined.
+*
-/**
+* @param array the name of the array where the elements shall be inserted
-* Convenience macro for cx_array_insert_sorted() with a default
+* @param sorted_data (@c void*) a pointer to an array of sorted data that shall be inserted
-* layout and the specified reallocator.
+* @param n (@c size_t) the number of elements that shall be inserted
-*
+* @param cmp_func (@c cx_compare_func) the compare function that establishes the order
-* @param reallocator (@c CxArrayReallocator*) the array reallocator to use
+* @retval zero success
-* @param array the name of the array (NOT a pointer or alias to the array)
+* @retval non-zero a re-allocation was necessary but failed
-* @param src (@c void*) pointer to the source array
+*/
-* @param n (@c size_t) number of elements in the source array
+#define cx_array_insert_sorted_array(array, sorted_data, n, cmp_func) \
-* @param cmp_func (@c cx_cmp_func) the compare function for the elements
+cx_array_insert_sorted_array_a(cxDefaultAllocator, array, sorted_data, n, cmp_func)
-* @retval zero success
-* @retval non-zero failure
+/**
-* @see CX_ARRAY_DECLARE()
+* Inserts an element into a sorted array if it is not already contained.
-* @see cx_array_simple_insert_sorted()
+*
-*/
+* When the capacity is not enough to hold the new element, a re-allocation is attempted.
-#define cx_array_simple_insert_sorted_a(reallocator, array, src, n, cmp_func) \
+*
-cx_array_insert_sorted((void**)(&array), &(array##_size), &(array##_capacity), \
+* @attention if the array is not sorted according to the specified @p cmp_func, the behavior is undefined.
-cmp_func, src, sizeof((array)[0]), n, reallocator)
+*
+* @param allocator (@c CxAllocator*) the allocator to use for a possible reallocation
-/**
+* @param array the name of the array where the elements shall be inserted
-* Convenience macro for cx_array_insert_sorted() with a default
+* @param element the element that shall be inserted
-* layout and the default reallocator.
+* @param cmp_func (@c cx_compare_func) the compare function that establishes the order
-*
+* @retval zero success
-* @param array the name of the array (NOT a pointer or alias to the array)
+* @retval non-zero a re-allocation was necessary but failed
-* @param src (@c void*) pointer to the source array
+*/
-* @param n (@c size_t) number of elements in the source array
+#define cx_array_insert_unique_a(allocator, array, element, cmp_func) \
-* @param cmp_func (@c cx_cmp_func) the compare function for the elements
+cx_array_insert_sorted_(allocator, (CxArray*)&(array), sizeof((array).data[0]), (void*)&(element), 1, cmp_func, false)
-* @retval zero success
-* @retval non-zero failure
+/**
-* @see CX_ARRAY_DECLARE()
+* Inserts an element into a sorted array if it is not already contained.
-* @see cx_array_simple_insert_sorted_a()
+*
-*/
+* When the capacity is not enough to hold the new element, a re-allocation is attempted.
-#define cx_array_simple_insert_sorted(array, src, n, cmp_func) \
+*
-cx_array_simple_insert_sorted_a(NULL, array, src, n, cmp_func)
+* @attention if the array is not sorted according to the specified @p cmp_func, the behavior is undefined.
+*
+* @param array the name of the array where the elements shall be inserted
-/**
+* @param element the element that shall be inserted
-* Inserts a sorted array into another sorted array, avoiding duplicates.
+* @param cmp_func (@c cx_compare_func) the compare function that establishes the order
-*
+* @retval zero success
-* If either the target or the source array is not already sorted with respect
+* @retval non-zero a re-allocation was necessary but failed
-* to the specified @p cmp_func, the behavior is undefined.
+*/
-*
+#define cx_array_insert_unique(array, element, cmp_func) \
-* If the capacity is insufficient to hold the new data, a reallocation
+cx_array_insert_unique_a(cxDefaultAllocator, array, element, cmp_func)
-* attempt is made.
-* You can create your own reallocator by hand, use #cx_array_default_reallocator,
+/**
-* or use the convenience function cx_array_reallocator() to create a custom reallocator.
+* Inserts sorted data into a sorted array, skipping duplicates.
 *
-* @param target a pointer to the target array
+* When the capacity is not enough to hold the new elements, a re-allocation is attempted.
-* @param size a pointer to the size of the target array
+*
-* @param capacity a pointer to the capacity of the target array
+* @attention if either array is not sorted according to the specified @p cmp_func, the behavior is undefined.
-* @param cmp_func the compare function for the elements
+*
-* @param src the source array
+* @param allocator (@c CxAllocator*) the allocator to use for a possible reallocation
-* @param elem_size the size of one element
+* @param array the name of the array where the elements shall be inserted
-* @param elem_count the number of elements to insert
+* @param sorted_data (@c void*) a pointer to an array of sorted data that shall be inserted
-* @param reallocator the array reallocator to use
+* @param n (@c size_t) the number of elements that shall be inserted
-* (@c NULL defaults to #cx_array_default_reallocator)
+* @param cmp_func (@c cx_compare_func) the compare function that establishes the order
 * @retval zero success
-* @retval non-zero failure
+* @retval non-zero a re-allocation was necessary but failed
 */
-cx_attr_nonnull_arg(1, 2, 3, 5)
+#define cx_array_insert_unique_array_a(allocator, array, sorted_data, n, cmp_func) \
-CX_EXPORT int cx_array_insert_unique(void **target, size_t *size, size_t *capacity,
+cx_array_insert_sorted_(allocator, (CxArray*)&(array), sizeof((array).data[0]), sorted_data, n, cmp_func, false)
-cx_compare_func cmp_func, const void *src, size_t elem_size, size_t elem_count,
-CxArrayReallocator *reallocator);
+/**
+* Inserts sorted data into a sorted array, skipping duplicates.
-/**
+*
-* Inserts an element into a sorted array if it does not exist.
+* When the capacity is not enough to hold the new elements, a re-allocation is attempted.
 *
-* If the target array is not already sorted with respect
+* @attention if either array is not sorted according to the specified @p cmp_func, the behavior is undefined.
-* to the specified @p cmp_func, the behavior is undefined.
+*
-*
+* @param array the name of the array where the elements shall be inserted
-* If the capacity is insufficient to hold the new data, a reallocation
+* @param sorted_data (@c void*) a pointer to an array of sorted data that shall be inserted
-* attempt is made.
+* @param n (@c size_t) the number of elements that shall be inserted
-*
+* @param cmp_func (@c cx_compare_func) the compare function that establishes the order
-* The \@ SIZE_TYPE is flexible and can be any unsigned integer type.
+* @retval zero success
-* It is important, however, that @p size and @p capacity are pointers to
+* @retval non-zero a re-allocation was necessary but failed
-* variables of the same type.
+*/
-*
+#define cx_array_insert_unique_array(array, sorted_data, n, cmp_func) \
-* @param target (@c void**) a pointer to the target array
+cx_array_insert_unique_array_a(cxDefaultAllocator, array, sorted_data, n, cmp_func)
-* @param size (@c SIZE_TYPE*) a pointer to the size of the target array
-* @param capacity (@c SIZE_TYPE*) a pointer to the capacity of the target array
+/**
-* @param elem_size (@c size_t) the size of one element
+* Inserts sorted data into a sorted array.
-* @param elem (@c void*) a pointer to the element to add
+*
-* @param cmp_func (@c cx_cmp_func) the compare function for the elements
+* Internal function - do not use.
-* @param reallocator (@c CxArrayReallocator*) the array reallocator to use
+*
-* @retval zero success (also when the element was already present)
+* @param allocator the allocator to use for a possible reallocation
-* @retval non-zero failure
+* @param array a pointer to the array structure
-*/
+* @param elem_size the size of one element
-#define cx_array_add_unique(target, size, capacity, elem_size, elem, cmp_func, reallocator) \
+* @param sorted_data a pointer to an array of data that shall be inserted
-cx_array_insert_unique((void**)(target), size, capacity, cmp_func, elem, elem_size, 1, reallocator)
+* @param n the number of elements that shall be inserted
+* @param cmp_func the compare function
-/**
+* @param context additional context for the compare function
-* Convenience macro for cx_array_add_unique() with a default
+* @param allow_duplicates @c false if duplicates shall be skipped during insertion
-* layout and the specified reallocator.
+* @retval zero success
-*
+* @retval non-zero a re-allocation was necessary but failed
-* @param reallocator (@c CxArrayReallocator*) the array reallocator to use
+*/
-* @param array the name of the array (NOT a pointer or alias to the array)
+cx_attr_nonnull_arg(1, 2, 4, 6)
-* @param elem the element to add (NOT a pointer, address is automatically taken)
+CX_EXPORT int cx_array_insert_sorted_c_(const CxAllocator *allocator, CxArray *array,
-* @param cmp_func (@c cx_cmp_func) the compare function for the elements
+size_t elem_size, const void *sorted_data, size_t n,
-* @retval zero success
+cx_compare_func2 cmp_func, void *context, bool allow_duplicates);
-* @retval non-zero failure
-* @see CX_ARRAY_DECLARE()
+/**
-* @see cx_array_simple_add_unique()
+* Inserts an element into a sorted array.
-*/
+*
-#define cx_array_simple_add_unique_a(reallocator, array, elem, cmp_func) \
+* When the capacity is not enough to hold the new element, a re-allocation is attempted.
-cx_array_add_unique(&array, &(array##_size), &(array##_capacity), \
+*
-sizeof((array)[0]), &(elem), cmp_func, reallocator)
+* @attention if the array is not sorted according to the specified @p cmp_func, the behavior is undefined.
+*
-/**
+* @param allocator (@c CxAllocator*) the allocator to use for a possible reallocation
-* Convenience macro for cx_array_add_unique() with a default
+* @param array the name of the array where the elements shall be inserted
-* layout and the default reallocator.
+* @param element the element that shall be inserted
-*
+* @param cmp_func (@c cx_compare_func2) the compare function that establishes the order
-* @param array the name of the array (NOT a pointer or alias to the array)
+* @param context (@c void*) additional context for the compare function
-* @param elem the element to add (NOT a pointer, address is automatically taken)
+* @retval zero success
-* @param cmp_func (@c cx_cmp_func) the compare function for the elements
+* @retval non-zero a re-allocation was necessary but failed
-* @retval zero success
+*/
-* @retval non-zero failure
+#define cx_array_insert_sorted_ca(allocator, array, element, cmp_func) \
-* @see CX_ARRAY_DECLARE()
+cx_array_insert_sorted_c_(allocator, (CxArray*)&(array), sizeof((array).data[0]), (void*)&(element), 1, cmp_func, context, true)
-* @see cx_array_simple_add_unique_a()
-*/
+/**
-#define cx_array_simple_add_unique(array, elem, cmp_func) \
+* Inserts an element into a sorted array.
-cx_array_simple_add_unique_a(NULL, array, elem, cmp_func)
+*
+* When the capacity is not enough to hold the new element, a re-allocation is attempted.
-/**
+*
-* Convenience macro for cx_array_insert_unique() with a default
+* @attention if the array is not sorted according to the specified @p cmp_func, the behavior is undefined.
-* layout and the specified reallocator.
+*
-*
+* @param array the name of the array where the elements shall be inserted
-* @param reallocator (@c CxArrayReallocator*) the array reallocator to use
+* @param element the element that shall be inserted
-* @param array the name of the array (NOT a pointer or alias to the array)
+* @param cmp_func (@c cx_compare_func2) the compare function that establishes the order
-* @param src (@c void*) pointer to the source array
+* @param context (@c void*) additional context for the compare function
-* @param n (@c size_t) number of elements in the source array
+* @retval zero success
-* @param cmp_func (@c cx_cmp_func) the compare function for the elements
+* @retval non-zero a re-allocation was necessary but failed
-* @retval zero success
+*/
-* @retval non-zero failure
+#define cx_array_insert_sorted_c(array, element, cmp_func, context) \
-* @see CX_ARRAY_DECLARE()
+cx_array_insert_sorted_ca(cxDefaultAllocator, array, element, cmp_func, context)
-* @see cx_array_simple_insert_unique()
-*/
+/**
-#define cx_array_simple_insert_unique_a(reallocator, array, src, n, cmp_func) \
+* Inserts sorted data into a sorted array.
-cx_array_insert_unique((void**)(&array), &(array##_size), &(array##_capacity), \
+*
-cmp_func, src, sizeof((array)[0]), n, reallocator)
+* When the capacity is not enough to hold the new elements, a re-allocation is attempted.
+*
-/**
+* @attention if either array is not sorted according to the specified @p cmp_func, the behavior is undefined.
-* Convenience macro for cx_array_insert_unique() with a default
+*
-* layout and the default reallocator.
+* @param allocator (@c CxAllocator*) the allocator to use for a possible reallocation
-*
+* @param array the name of the array where the elements shall be inserted
-* @param array the name of the array (NOT a pointer or alias to the array)
+* @param sorted_data (@c void*) a pointer to an array of sorted data that shall be inserted
-* @param src (@c void*) pointer to the source array
+* @param n (@c size_t) the number of elements that shall be inserted
-* @param n (@c size_t) number of elements in the source array
+* @param cmp_func (@c cx_compare_func2) the compare function that establishes the order
-* @param cmp_func (@c cx_cmp_func) the compare function for the elements
+* @param context (@c void*) additional context for the compare function
 * @retval zero success
-* @retval non-zero failure
+* @retval non-zero a re-allocation was necessary but failed
-* @see CX_ARRAY_DECLARE()
+*/
-* @see cx_array_simple_insert_unique_a()
+#define cx_array_insert_sorted_array_ca(allocator, array, sorted_data, n, cmp_func, context) \
-*/
+cx_array_insert_sorted_c_(allocator, (CxArray*)&(array), sizeof((array).data[0]), sorted_data, n, cmp_func, context, true)
-#define cx_array_simple_insert_unique(array, src, n, cmp_func) \
-cx_array_simple_insert_unique_a(NULL, array, src, n, cmp_func)
+/**
+* Inserts sorted data into a sorted array.
+*
+* When the capacity is not enough to hold the new elements, a re-allocation is attempted.
+*
+* @attention if either array is not sorted according to the specified @p cmp_func, the behavior is undefined.
+*
+* @param array the name of the array where the elements shall be inserted
+* @param sorted_data (@c void*) a pointer to an array of sorted data that shall be inserted
+* @param n (@c size_t) the number of elements that shall be inserted
+* @param cmp_func (@c cx_compare_func2) the compare function that establishes the order
+* @param context (@c void*) additional context for the compare function
+* @retval zero success
+* @retval non-zero a re-allocation was necessary but failed
+*/
+#define cx_array_insert_sorted_array_c(array, sorted_data, n, cmp_func, context) \
+cx_array_insert_sorted_array_ca(cxDefaultAllocator, array, sorted_data, n, cmp_func, context)
+/**
+* Inserts an element into a sorted array if it is not already contained.
+*
+* When the capacity is not enough to hold the new element, a re-allocation is attempted.
+*
+* @attention if the array is not sorted according to the specified @p cmp_func, the behavior is undefined.
+*
+* @param allocator (@c CxAllocator*) the allocator to use for a possible reallocation
+* @param array the name of the array where the elements shall be inserted
+* @param element the element that shall be inserted
+* @param cmp_func (@c cx_compare_func2) the compare function that establishes the order
+* @param context (@c void*) additional context for the compare function
+* @retval zero success
+* @retval non-zero a re-allocation was necessary but failed
+*/
+#define cx_array_insert_unique_ca(allocator, array, element, cmp_func, context) \
+cx_array_insert_sorted_c_(allocator, (CxArray*)&(array), sizeof((array).data[0]), (void*)&(element), 1, cmp_func, context, false)
+/**
+* Inserts an element into a sorted array if it is not already contained.
+*
+* When the capacity is not enough to hold the new element, a re-allocation is attempted.
+*
+* @attention if the array is not sorted according to the specified @p cmp_func, the behavior is undefined.
+*
+* @param array the name of the array where the elements shall be inserted
+* @param element the element that shall be inserted
+* @param cmp_func (@c cx_compare_func2) the compare function that establishes the order
+* @param context (@c void*) additional context for the compare function
+* @retval zero success
+* @retval non-zero a re-allocation was necessary but failed
+*/
+#define cx_array_insert_unique_c(array, element, cmp_func, context) \
+cx_array_insert_unique_ca(cxDefaultAllocator, array, element, cmp_func, context)
+/**
+* Inserts sorted data into a sorted array, skipping duplicates.
+*
+* When the capacity is not enough to hold the new elements, a re-allocation is attempted.
+*
+* @attention if either array is not sorted according to the specified @p cmp_func, the behavior is undefined.
+*
+* @param allocator (@c CxAllocator*) the allocator to use for a possible reallocation
+* @param array the name of the array where the elements shall be inserted
+* @param sorted_data (@c void*) a pointer to an array of sorted data that shall be inserted
+* @param n (@c size_t) the number of elements that shall be inserted
+* @param cmp_func (@c cx_compare_func2) the compare function that establishes the order
+* @param context (@c void*) additional context for the compare function
+* @retval zero success
+* @retval non-zero a re-allocation was necessary but failed
+*/
+#define cx_array_insert_unique_array_ca(allocator, array, sorted_data, n, cmp_func, context) \
+cx_array_insert_sorted_c_(allocator, (CxArray*)&(array), sizeof((array).data[0]), sorted_data, n, cmp_func, context, false)
+/**
+* Inserts sorted data into a sorted array, skipping duplicates.
+*
+* When the capacity is not enough to hold the new elements, a re-allocation is attempted.
+*
+* @attention if either array is not sorted according to the specified @p cmp_func, the behavior is undefined.
+*
+* @param array the name of the array where the elements shall be inserted
+* @param sorted_data (@c void*) a pointer to an array of sorted data that shall be inserted
+* @param n (@c size_t) the number of elements that shall be inserted
+* @param cmp_func (@c cx_compare_func2) the compare function that establishes the order
+* @param context (@c void*) additional context for the compare function
+* @retval zero success
+* @retval non-zero a re-allocation was necessary but failed
+*/
+#define cx_array_insert_unique_array_c(array, sorted_data, n, cmp_func, context) \
+cx_array_insert_unique_array_ca(cxDefaultAllocator, array, sorted_data, n, cmp_func, context)
+/**
+* An alternative to qsort_r() when that is not available on your platform.
+*
+* If it is available, qsort_r() is used directly.
+*
+* @param array the array that shall be sorted
+* @param nmemb the number of elements in the array
+* @param size the size of one element
+* @param fn the compare function
+* @param context the context for the compare function
+*/
+CX_EXPORT void cx_array_qsort_c(void *array, size_t nmemb, size_t size,
+cx_compare_func2 fn, void *context);
+/**
+* Sorts an array.
+*
+* Internal function - do not use.
+*
+* @param array a pointer to the array structure
+* @param elem_size the size of one element
+* @param fn the compare function
+*/
+CX_EXPORT void cx_array_sort_(CxArray *array, size_t elem_size,
+cx_compare_func fn);
+/**
+* Sorts an array.
+*
+* Internal function - do not use.
+*
+* @param array a pointer to the array structure
+* @param elem_size the size of one element
+* @param fn the compare function
+* @param context the context for the compare function
+*/
+CX_EXPORT void cx_array_sort_c_(CxArray *array, size_t elem_size,
+cx_compare_func2 fn, void *context);
+/**
+* Sorts an array.
+*
+* @param array the name of the array
+* @param fn (@c cx_compare_func) the compare function
+* @param context (@c void*) the context for the compare function
+*/
+#define cx_array_sort(array, fn) \
+cx_array_sort_((CxArray*)&(array), sizeof((array).data[0]), fn)
+/**
+* Sorts an array.
+*
+* @param array the name of the array
+* @param fn (@c cx_compare_func2) the compare function
+* @param context (@c void*) the context for the compare function
+*/
+#define cx_array_sort_c(array, fn, context) \
+cx_array_sort_c_((CxArray*)&(array), sizeof((array).data[0]), fn, context)
+/**
+* Creates an iterator over the elements of an array.
+*
+* Internal function - do not use.
+*
+* @param array a pointer to the array structure
+* @param elem_size the size of one element
+* @return an iterator over the elements
+*/
+cx_attr_nodiscard cx_attr_nonnull
+CX_EXPORT CxIterator cx_array_iterator_(CxArray *array, size_t elem_size);
+/**
+* Creates an iterator over the elements of an array.
+*
+* The iterator will yield pointers to the elements.
+*
+* This iterator cannot be used to remove elements
+* because it does not get a modifiable reference to the array's size.
+*
+* @param array the name of the array
+* @return an iterator over the elements
+* @see cx_array_iterator_ptr()
+*/
+#define cx_array_iterator(array) \
+cx_array_iterator_((CxArray*)&(array), sizeof((array).data[0]))
+/**
+* Creates an iterator over the elements of an array containing pointers.
+*
+* Internal function - do not use.
+*
+* @param array the name of the array
+* @return an iterator over the elements
+*/
+cx_attr_nodiscard cx_attr_nonnull
+CX_EXPORT CxIterator cx_array_iterator_ptr_(CxArray *array);
+/**
+* Creates an iterator over the elements of an array containing pointers.
+*
+* The iterator will yield the elements themselves, which are supposed to
+* be pointers.
+*
+* This iterator cannot be used to remove elements
+* because it does not get a modifiable reference to the array's size.
+*
+* @param array the name of the array
+* @return an iterator over the elements
+* @see cx_array_iterator()
+*/
+#define cx_array_iterator_ptr(array) \
+cx_array_iterator_ptr_((CxArray*)&(array))
+/**
+* Removes elements from the array.
+*
+* Internal function - do not use.
+*
+* @param array a pointer to the array structure
+* @param elem_size the size of one element
+* @param index the index of the first element to remove
+* @param n the number of elements to remove
+* @param fast indicates whether tail elements should be copied into the gap
+*/
+cx_attr_nonnull
+CX_EXPORT void cx_array_remove_(CxArray *array, size_t elem_size, size_t index, size_t n, bool fast);
+/**
+* Removes one element from the array.
+*
+* Tail elements are all moved by one. If you don't need a stable order
+* in the array, consider using cx_array_remove_fast().
+*
+* If the index is out of bounds, this function does nothing.
+*
+* @param array the name of the array
+* @param index (@c size_t) the index of the element to remove
+* @see cx_array_remove_fast()
+*/
+#define cx_array_remove(array, index) \
+cx_array_remove_((CxArray*)&(array), sizeof((array).data[0]), index, 1, false)
+/**
+* Removes one element from the array.
+*
+* The gap will be filled with a copy of the last element in the array.
+* This changes the order of elements. If you want a stable order,
+* use cx_array_remove() instead.
+*
+* If the index is out of bounds, this function does nothing.
+*
+* @param array the name of the array
+* @param index (@c size_t) the index of the element to remove
+* @see cx_array_remove()
+*/
+#define cx_array_remove_fast(array, index) \
+cx_array_remove_((CxArray*)&(array), sizeof((array).data[0]), index, 1, true)
+/**
+* Removes multiple elements from the array.
+*
+* Tail elements are all moved to close the gap. If you don't need a stable
+* order in the array, consider using cx_array_remove_array_fast().
+*
+* If the index is out of bounds, this function does nothing.
+* If @n overflows the array, this function removes as many elements as it can.
+*
+* @param array the name of the array
+* @param index (@c size_t) the index of the first element to remove
+* @param n (@c size_t) the number of elements to remove
+* @see cx_array_remove_array_fast()
+*/
+#define cx_array_remove_array(array, index, n) \
+cx_array_remove_((CxArray*)&(array), sizeof((array).data[0]), index, n, false)
+/**
+* Removes multiple elements from the array.
+*
+* Tail elements are copied into the gap. If you have more tail elements
+* than the number of elements that are removed, this will change the order
+* of elements. If you want a stable order, use cx_array_remove_array() instead.
+*
+* If the index is out of bounds, this function does nothing.
+* If @n overflows the array, this function removes as many elements as it can.
+*
+* @param array the name of the array
+* @param index (@c size_t) the index of the first element to remove
+* @param n (@c size_t) the number of elements to remove
+* @see cx_array_remove_array()
+*/
+#define cx_array_remove_array_fast(array, index, n) \
+cx_array_remove_((CxArray*)&(array), sizeof((array).data[0]), index, n, true)
+/**
+* Deallocates an array.
+*
+* Internal function - do not use.
+*
+* @param allocator (@c CxAllocator*) the allocator which was used to allocate the array
+* @param array a pointer to the array structure
+*/
+cx_attr_nonnull
+CX_EXPORT void cx_array_free_(const CxAllocator *allocator, CxArray *array);
+/**
+* Deallocates an array.
+*
+* The structure is reset to zero and can be re-initialized with
+* cx_array_inita().
+*
+* @param array the name of the array
+*/
+#define cx_array_free(array) cx_array_free_(cxDefaultAllocator, (CxArray*)&(array))
+/**
+* Deallocates an array.
+*
+* The structure is reset to zero and can be re-initialized with
+* cx_array_init_a().
+*
+* @param allocator (@c CxAllocator*) the allocator which was used to allocate the array
+* @param array the name of the array
+*/
+#define cx_array_free_a(allocator, array) cx_array_free_(allocator, (CxArray*)&(array))
 /**
 * Searches the largest lower bound in a sorted array.
 *
 * In other words, this function returns the index of the largest element
 * in @p arr that is less or equal to @p elem with respect to @p cmp_func.
 * When no such element exists, @p size is returned.
+*
+* When such an element exists more than once, the largest index of all those
+* elements is returned.
 *
 * If @p elem is contained in the array, this is identical to
 * #cx_array_binary_search().
 *
 * If the array is not sorted with respect to the @p cmp_func, the behavior
 CX_EXPORT size_t cx_array_binary_search_inf(const void *arr, size_t size,
 size_t elem_size, const void *elem, cx_compare_func cmp_func);
 /**
 * Searches an item in a sorted array.
+*
+* When such an element exists more than once, the largest index of all those
+* elements is returned.
 *
 * If the array is not sorted with respect to the @p cmp_func, the behavior
 * is undefined.
 *
 * @param arr the array to search
 *
 * In other words, this function returns the index of the smallest element
 * in @p arr that is greater or equal to @p elem with respect to @p cmp_func.
 * When no such element exists, @p size is returned.
 *
+* When such an element exists more than once, the smallest index of all those
+* elements is returned.
+*
 * If @p elem is contained in the array, this is identical to
 * #cx_array_binary_search().
 *
 * If the array is not sorted with respect to the @p cmp_func, the behavior
 * is undefined.
 */
 cx_attr_nonnull
 CX_EXPORT size_t cx_array_binary_search_sup(const void *arr, size_t size,
 size_t elem_size, const void *elem, cx_compare_func cmp_func);
+/**
+* Searches the largest lower bound in a sorted array.
+*
+* In other words, this function returns the index of the largest element
+* in @p arr that is less or equal to @p elem with respect to @p cmp_func.
+* When no such element exists, @p size is returned.
+*
+* When such an element exists more than once, the largest index of all those
+* elements is returned.
+*
+* If @p elem is contained in the array, this is identical to
+* #cx_array_binary_search().
+*
+* If the array is not sorted with respect to the @p cmp_func, the behavior
+* is undefined.
+*
+* @param arr the array to search
+* @param size the size of the array
+* @param elem_size the size of one element
+* @param elem the element to find
+* @param cmp_func the compare function
+* @param context the context for the compare function
+* @return the index of the largest lower bound, or @p size
+* @see cx_array_binary_search_sup()
+* @see cx_array_binary_search()
+*/
+cx_attr_nonnull
+CX_EXPORT size_t cx_array_binary_search_inf_c(const void *arr, size_t size,
+size_t elem_size, const void *elem, cx_compare_func2 cmp_func, void *context);
+/**
+* Searches an item in a sorted array.
+*
+* When such an element exists more than once, the largest index of all those
+* elements is returned.
+*
+* If the array is not sorted with respect to the @p cmp_func, the behavior
+* is undefined.
+*
+* @param arr the array to search
+* @param size the size of the array
+* @param elem_size the size of one element
+* @param elem the element to find
+* @param cmp_func the compare function
+* @param context the context for the compare function
+* @return the index of the element in the array, or @p size if the element
+* cannot be found
+* @see cx_array_binary_search_inf()
+* @see cx_array_binary_search_sup()
+*/
+cx_attr_nonnull
+CX_EXPORT size_t cx_array_binary_search_c(const void *arr, size_t size,
+size_t elem_size, const void *elem, cx_compare_func2 cmp_func, void *context);
+/**
+* Searches the smallest upper bound in a sorted array.
+*
+* In other words, this function returns the index of the smallest element
+* in @p arr that is greater or equal to @p elem with respect to @p cmp_func.
+* When no such element exists, @p size is returned.
+*
+* When such an element exists more than once, the smallest index of all those
+* elements is returned.
+*
+* If @p elem is contained in the array, this is identical to
+* #cx_array_binary_search().
+*
+* If the array is not sorted with respect to the @p cmp_func, the behavior
+* is undefined.
+*
+* @param arr the array to search
+* @param size the size of the array
+* @param elem_size the size of one element
+* @param elem the element to find
+* @param cmp_func the compare function
+* @param context the context for the compare function
+* @return the index of the smallest upper bound, or @p size
+* @see cx_array_binary_search_inf()
+* @see cx_array_binary_search()
+*/
+cx_attr_nonnull
+CX_EXPORT size_t cx_array_binary_search_sup_c(const void *arr, size_t size,
+size_t elem_size, const void *elem, cx_compare_func2 cmp_func, void *context);
 /**
 * Swaps two array elements.
 *
 * @param arr the array
 * @param elem_size the element size
 /**
 * Allocates an array list for storing elements with @p elem_size bytes each.
 *
 * If @p elem_size is #CX_STORE_POINTERS, the created list stores pointers instead of
 * copies of the added elements, and the compare function will be automatically set
-* to cx_cmp_ptr(), if none is given.
+* to cx_cmp_ptr().
 *
 * @param allocator the allocator for allocating the list memory
 * (if @c NULL, the cxDefaultAllocator will be used)
-* @param comparator the comparator for the elements
-* (if @c NULL, and the list is not storing pointers, sort and find
-* functions will not work)
 * @param elem_size the size of each element in bytes
 * @param initial_capacity the initial number of elements the array can store
 * @return the created list
 */
 cx_attr_nodiscard
 cx_attr_malloc
 cx_attr_dealloc(cxListFree, 1)
 CX_EXPORT CxList *cxArrayListCreate(const CxAllocator *allocator,
-cx_compare_func comparator, size_t elem_size, size_t initial_capacity);
+size_t elem_size, size_t initial_capacity);
-/**
-* Allocates an array list for storing elements with @p elem_size bytes each.
-*
-* The list will use the cxDefaultAllocator and @em NO compare function.
-* If you want to call functions that need a compare function, you have to
-* set it immediately after creation or use cxArrayListCreate().
-*
-* If @p elem_size is #CX_STORE_POINTERS, the created list stores pointers instead of
-* copies of the added elements and the compare function will be automatically set
-* to cx_cmp_ptr().
-*
-* @param elem_size (@c size_t) the size of each element in bytes
-* @param initial_capacity (@c size_t) the initial number of elements the array can store
-* @return the created list
-*/
-#define cxArrayListCreateSimple(elem_size, initial_capacity) \
-cxArrayListCreate(NULL, NULL, elem_size, initial_capacity)
 #ifdef __cplusplus
 } // extern "C"
 #endif

comparison: ucx/cx/array_list.h

ucx/cx/array_list.h

Mercurial > hg > dav / file comparison

comparison: ucx/cx/array_list.h

ucx/cx/array_list.h