--- a/src/cx/array_list.h Tue Dec 16 11:48:52 2025 +0100
+++ b/src/cx/array_list.h Tue Dec 16 12:07:01 2025 +0100
@@ -49,6 +49,12 @@
*/
CX_EXPORT extern const unsigned cx_array_swap_sbo_size;
+/**
+ * Declares a typed array with size and capacity.
+ *
+ * @param type the type of the elements
+ * @param name the name of the array
+ */
#define CX_ARRAY(type, name) \
struct { \
type *data; \
@@ -56,106 +62,570 @@
size_t capacity; \
} name
+/**
+ * Internal structure for arrays.
+ *
+ * A generalization of array structures declared with CX_ARRAY().
+ */
typedef struct cx_array_s {
+ /** The array data. */
void *data;
+ /** The number of elements. */
size_t size;
+ /** The maximum number of elements. */
size_t capacity;
} CxArray;
+/**
+ * Initializes an array by allocating memory.
+ *
+ * Internal function - do not use manually.
+ *
+ * @param allocator the allocator for the array
+ * @param array a pointer to the array structure
+ * @param elem_size size of one element
+ * @param capacity the initial maximum number of elements
+ * @retval zero allocation was successful
+ * @retval non-zero allocation failed
+ */
cx_attr_nonnull
CX_EXPORT int cx_array_init_(const CxAllocator *allocator, CxArray *array, size_t elem_size, size_t capacity);
+/**
+ * Initializes an array by allocating memory.
+ *
+ * The size is set to zero.
+ *
+ * @attention If the array was already initialized, this will leak memory.
+ * Use cx_array_reserve() to change the capacity of an initialized array.
+ *
+ * @param allocator (@c CxAllocator*) the allocator for the array
+ * @param array the name of the array
+ * @param capacity (@c size_t) the initial maximum number of elements
+ * @retval zero allocation was successful
+ * @retval non-zero allocation failed
+ */
#define cx_array_init_a(allocator, array, capacity) cx_array_init_(allocator, (CxArray*)&(array), sizeof((array).data[0]), capacity)
+/**
+ * Initializes an array by allocating memory.
+ *
+ * The size is set to zero.
+ *
+ * @attention If the array was already initialized, this will leak memory.
+ *
+ * @param array the name of the array
+ * @param capacity (@c size_t) the initial maximum number of elements
+ * @retval zero allocation was successful
+ * @retval non-zero allocation failed
+ */
#define cx_array_init(array, capacity) cx_array_init_a(cxDefaultAllocator, array, capacity)
+/**
+ * Initializes an array with fixed size memory.
+ *
+ * Internal function - do not use manually.
+ *
+ * @param array a pointer to the array structure
+ * @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
+ */
cx_attr_nonnull
CX_EXPORT void cx_array_init_fixed_(CxArray *array, const void *data, size_t capacity, size_t size);
-#define cx_array_init_fixed(array, fixed_size_array, num_initialized) cx_array_init_fixed_((CxArray*)&(array), fixed_size_array, cx_nmemb(fixed_size_array), num_initialized)
+/**
+ * Initializes an array with fixed size memory.
+ *
+ * This is useful, for example, when you want to work with memory on the stack
+ * and only want to move to the heap when the stack memory is not enough.
+ *
+ * With the @p num_initialized argument you can specify how many elements in the
+ * fixed size array are already correctly initialized, which determines the
+ * initial size of the array.
+ *
+ * The capacity is determined automatically by the compiler.
+ *
+ * @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.
+ *
+ * @attention When you pass a pointer to an array that does not have a fixed
+ * size, the behavior is unspecified.
+ *
+ * @param array the name of the array to initialize
+ * @param fixed_size_array (@c void*) the fixed size array
+ * @param num_initialized (@c size_t) the number of already initialized elements in the fixed size array
+ * @see cx_array_copy_to_new()
+ */
+#define cx_array_init_fixed(array, fixed_size_array, num_initialized) \
+ cx_array_init_fixed_((CxArray*)&(array), fixed_size_array, cx_nmemb(fixed_size_array), num_initialized)
+/**
+ * Changes the capacity of an array.
+ *
+ * Internal function - do not use.
+ *
+ * @param allocator the allocator
+ * @param array a pointer to the array structure
+ * @param elem_size the size of one element
+ * @param capacity the new capacity
+ * @retval zero allocation was successful
+ * @retval non-zero allocation failed
+ */
cx_attr_nonnull
CX_EXPORT int cx_array_reserve_(const CxAllocator *allocator, CxArray *array, size_t elem_size, size_t capacity);
-#define cx_array_reserve_a(allocator, array, capacity) cx_array_reserve_(allocator, (CxArray*)&(array), sizeof((array).data[0]), capacity)
+/**
+ * Changes the capacity of an array.
+ *
+ * If required, the size is reduced to fit into the new capacity.
+ *
+ * @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
+ * @retval zero allocation was successful
+ * @retval non-zero allocation failed
+ */
+#define cx_array_reserve_a(allocator, array, capacity) \
+ cx_array_reserve_(allocator, (CxArray*)&(array), sizeof((array).data[0]), capacity)
-#define cx_array_reserve(array, capacity) cx_array_reserve_a(cxDefaultAllocator, array, capacity)
+/**
+ * Changes the capacity of an array.
+ *
+ * If required, the size is reduced to fit into the new capacity.
+ *
+ * @param array the name of the array
+ * @param capacity (@c size_t) the new maximum number of elements
+ * @retval zero allocation was successful
+ * @retval non-zero allocation failed
+ */
+#define cx_array_reserve(array, capacity) \
+ cx_array_reserve_a(cxDefaultAllocator, array, capacity)
+/**
+ * Copies the array to a new memory region.
+ *
+ * Internal function - do not use.
+ *
+ * @param allocator the allocator for new new memory
+ * @param array a pointer to the array structure
+ * @param elem_size the size of one element
+ * @param capacity the new capacity
+ * @retval zero allocation was successful
+ * @retval non-zero allocation failed
+ */
cx_attr_nonnull
-CX_EXPORT int cx_array_move_to_new_(const CxAllocator *allocator, CxArray *array, size_t elem_size, size_t capacity);
+CX_EXPORT int cx_array_copy_to_new_(const CxAllocator *allocator, CxArray *array, size_t elem_size, size_t capacity);
+
+/**
+ * Copies the array to a new memory region.
+ *
+ * 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.
+ *
+ * @attention When the original memory does not belong to stack memory, and
+ * you do not have another reference to this memory, it will leak.
+ *
+ * @param allocator (@c CxAllocator*) the allocator for the new memory
+ * @param array the name of the array
+ * @param capacity (@c size_t) the new maximum number of elements
+ * @retval zero allocation was successful
+ * @retval non-zero allocation failed
+ * @see cx_array_init_fixed()
+ */
+#define cx_array_copy_to_new_a(allocator, array, capacity) \
+ cx_array_copy_to_new_(allocator, (CxArray*)&(array), sizeof((array).data[0]), capacity)
-#define cx_array_move_to_new_a(allocator, array, capacity) cx_array_move_to_new_(allocator, (CxArray*)&(array), sizeof((array).data[0]), capacity)
+/**
+ * Copies the array to a new memory region.
+ *
+ * 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.
+ *
+ * @attention When the original memory does not belong to stack memory, and
+ * you do not have another reference to this memory, it will leak.
+ *
+ * @param array the name of the array
+ * @param capacity (@c size_t) the new maximum number of elements
+ * @retval zero allocation was successful
+ * @retval non-zero allocation failed
+ * @see cx_array_init_fixed()
+ */
+#define cx_array_copy_to_new(array, capacity) \
+ cx_array_copy_to_new_a(cxDefaultAllocator, array, capacity)
-#define cx_array_move_to_new(array, capacity) cx_array_move_to_new_a(cxDefaultAllocator, array, capacity)
-
+/**
+ * Inserts data into an array.
+ *
+ * Internal function - do not use.
+ *
+ * @param allocator the allocator to use for a possible reallocation
+ * @param array a pointer to the array structure
+ * @param elem_size the size of one element
+ * @param index the index where to insert the @p other data
+ * @param other a pointer to an array of data that shall be inserted
+ * @param n the number of elements that shall be inserted
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
cx_attr_nonnull_arg(1, 2)
CX_EXPORT int cx_array_insert_(const CxAllocator *allocator, CxArray *array,
size_t elem_size, size_t index, const void *other, size_t n);
+/**
+ * Appends an element to an array.
+ *
+ * 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
+ * @param array the name of the array where the element shall be added
+ * @param element (@c void*) a pointer to the element that shall be added
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
#define cx_array_add_a(allocator, array, element) \
cx_array_insert_(allocator, (CxArray*)&(array), sizeof((array).data[0]), (array).size, element, 1)
-#define cx_array_add(array, element) cx_array_add_a(cxDefaultAllocator, array, element)
+/**
+ * Appends an element to an array.
+ *
+ * When the capacity is not enough to hold the new element, a re-allocation is attempted.
+ *
+ * @param array the name of the array where the element shall be added
+ * @param element (@c void*) a pointer to the element that shall be added
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
+#define cx_array_add(array, element) \
+ cx_array_add_a(cxDefaultAllocator, array, element)
+/**
+ * Inserts an element into an array.
+ *
+ * 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
+ * @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
+ * @param element (@c void*) a pointer to the element that shall be inserted
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
#define cx_array_insert_a(allocator, array, index, element) \
cx_array_insert_(allocator, (CxArray*)&(array), sizeof((array).data[0]), index, element, 1)
-#define cx_array_insert(array, index, element) cx_array_insert_a(cxDefaultAllocator, array, index, element)
+/**
+ * Inserts an element into an array.
+ *
+ * When the capacity is not enough to hold the new element, a re-allocation is attempted.
+ *
+ * @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
+ * @param element (@c void*) a pointer to the element that shall be inserted
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
+#define cx_array_insert(array, index, element) \
+ cx_array_insert_a(cxDefaultAllocator, array, index, element)
+/**
+ * Inserts data into an array.
+ *
+ * When the capacity is not enough to hold the new elements, a re-allocation is attempted.
+ *
+ * @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 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
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
#define cx_array_insert_array_a(allocator, array, index, other, n) \
cx_array_insert_(allocator, (CxArray*)&(array), sizeof((array).data[0]), index, other, n)
-#define cx_array_insert_array(array, index, other, n) cx_array_insert_array_a(cxDefaultAllocator, array, index, other, n)
+/**
+ * Inserts data into an array.
+ *
+ * When the capacity is not enough to hold the new elements, a re-allocation is attempted.
+ *
+ * @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
+ * @param n (@c size_t) the number of elements that shall be inserted
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
+#define cx_array_insert_array(array, index, other, n) \
+ cx_array_insert_array_a(cxDefaultAllocator, array, index, other, n)
+/**
+ * Appends data to an array.
+ *
+ * When the capacity is not enough to hold the new elements, a re-allocation is attempted.
+ *
+ * @param allocator (@c CxAllocator*) the allocator to use for a possible reallocation
+ * @param array the name of the array where the elements shall be added
+ * @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
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
#define cx_array_add_array_a(allocator, array, other, n) \
cx_array_insert_(allocator, (CxArray*)&(array), sizeof((array).data[0]), (array).size, other, n)
-#define cx_array_add_array(array, other, n) cx_array_add_array_a(cxDefaultAllocator, array, other, n)
+/**
+ * Appends data to an array.
+ *
+ * When the capacity is not enough to hold the new elements, a re-allocation is attempted.
+ *
+ * @param array the name of the array where the elements shall be added
+ * @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
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
+#define cx_array_add_array(array, other, n) \
+ cx_array_add_array_a(cxDefaultAllocator, array, other, n)
+/**
+ * Inserts sorted data into a sorted array.
+ *
+ * Internal function - do not use.
+ *
+ * @param allocator the allocator to use for a possible reallocation
+ * @param array a pointer to the array structure
+ * @param elem_size the size of one element
+ * @param cmp_func
+ * @param sorted_data a pointer to an array of data that shall be inserted
+ * @param n the number of elements that shall be inserted
+ * @param allow_duplicates @c false if duplicates shall be skipped during insertion
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
cx_attr_nonnull
CX_EXPORT int cx_array_insert_sorted_(const CxAllocator *allocator, CxArray *array,
size_t elem_size, cx_compare_func cmp_func, const void *sorted_data, size_t n,
bool allow_duplicates);
+/**
+ * Inserts an element into a sorted array.
+ *
+ * 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 cmp_func (@c cx_compare_func) the compare function that establishes the order
+ * @param element (@c void*) a pointer to element that shall be inserted
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
#define cx_array_insert_sorted_a(allocator, array, cmp_func, element) \
cx_array_insert_sorted_(allocator, (CxArray*)&(array), sizeof((array).data[0]), cmp_func, element, 1, true)
-#define cx_array_insert_sorted(array, cmp_func, element) cx_array_insert_sorted_a(cxDefaultAllocator, array, cmp_func, element)
+/**
+ * Inserts an element into a sorted array.
+ *
+ * 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 cmp_func (@c cx_compare_func) the compare function that establishes the order
+ * @param element (@c void*) a pointer to element that shall be inserted
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
+#define cx_array_insert_sorted(array, cmp_func, element) \
+ cx_array_insert_sorted_a(cxDefaultAllocator, array, cmp_func, element)
+/**
+ * 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 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 cmp_func (@c cx_compare_func) the compare function that establishes the order
+ * @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
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
#define cx_array_insert_sorted_array_a(allocator, array, cmp_func, sorted_data, n) \
cx_array_insert_sorted_(allocator, (CxArray*)&(array), sizeof((array).data[0]), cmp_func, sorted_data, n, true)
-#define cx_array_insert_sorted_array(array, cmp_func, sorted_data, n) cx_array_insert_sorted_array_a(cxDefaultAllocator, array, cmp_func, sorted_data, n)
+/**
+ * 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 cmp_func (@c cx_compare_func) the compare function that establishes the order
+ * @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
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
+#define cx_array_insert_sorted_array(array, cmp_func, sorted_data, n) \
+ cx_array_insert_sorted_array_a(cxDefaultAllocator, array, cmp_func, sorted_data, n)
+/**
+ * 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 cmp_func (@c cx_compare_func) the compare function that establishes the order
+ * @param element (@c void*) a pointer to element that shall be inserted
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
#define cx_array_insert_unique_a(allocator, array, cmp_func, element) \
cx_array_insert_sorted_(allocator, (CxArray*)&(array), sizeof((array).data[0]), cmp_func, element, 1, false)
-#define cx_array_insert_unique(array, cmp_func, element) cx_array_insert_unique_a(cxDefaultAllocator, array, cmp_func, element)
+/**
+ * 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 cmp_func (@c cx_compare_func) the compare function that establishes the order
+ * @param element (@c void*) a pointer to element that shall be inserted
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
+#define cx_array_insert_unique(array, cmp_func, element) \
+ cx_array_insert_unique_a(cxDefaultAllocator, array, cmp_func, element)
+/**
+ * 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 cmp_func (@c cx_compare_func) the compare function that establishes the order
+ * @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
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
#define cx_array_insert_unique_array_a(allocator, array, cmp_func, sorted_data, n) \
cx_array_insert_sorted_(allocator, (CxArray*)&(array), sizeof((array).data[0]), cmp_func, sorted_data, n, false)
-#define cx_array_insert_unique_array(array, cmp_func, sorted_data, n) cx_array_insert_unique_array_a(cxDefaultAllocator, array, cmp_func, sorted_data, n)
+/**
+ * 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 cmp_func (@c cx_compare_func) the compare function that establishes the order
+ * @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
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
+#define cx_array_insert_unique_array(array, cmp_func, sorted_data, n) \
+ cx_array_insert_unique_array_a(cxDefaultAllocator, array, cmp_func, sorted_data, n)
+/**
+ * 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);
-#define cx_array_iterator(array) cx_array_iterator_((CxArray*)&(array), sizeof((array).data[0]))
+/**
+ * Creates an iterator over the elements of an array.
+ *
+ * The iterator will yield pointers to the elements.
+ *
+ * @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);
-#define cx_array_iterator_ptr(array) 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.
+ *
+ * @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))
+/**
+ * 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.
*