Mercurial > hg > ucx / changeset

--- a/src/array_list.c	Sat Jan 04 14:18:27 2025 +0100
+++ b/src/array_list.c	Sat Jan 04 14:19:11 2025 +0100
@@ -126,7 +126,11 @@
     assert(array != NULL);
     assert(size != NULL);
     assert(capacity != NULL);
-    assert(reallocator != NULL);
+
+    // default reallocator
+    if (reallocator == NULL) {
+        reallocator = cx_array_default_reallocator;
+    }
 
     // determine size and capacity
     size_t oldcap;
@@ -219,7 +223,11 @@
     assert(size != NULL);
     assert(capacity != NULL);
     assert(src != NULL);
-    assert(reallocator != NULL);
+
+    // default reallocator
+    if (reallocator == NULL) {
+        reallocator = cx_array_default_reallocator;
+    }
 
     // determine size and capacity
     size_t oldcap;
@@ -341,7 +349,11 @@
     assert(capacity != NULL);
     assert(cmp_func != NULL);
     assert(sorted_data != NULL);
-    assert(reallocator != NULL);
+
+    // default reallocator
+    if (reallocator == NULL) {
+        reallocator = cx_array_default_reallocator;
+    }
 
     // corner case
     if (elem_count == 0) return 0;

--- a/src/cx/array_list.h	Sat Jan 04 14:18:27 2025 +0100
+++ b/src/cx/array_list.h	Sat Jan 04 14:19:11 2025 +0100
@@ -26,11 +26,11 @@
  * POSSIBILITY OF SUCH DAMAGE.
  */
 /**
- * \file array_list.h
- * \brief Array list implementation.
- * \author Mike Becker
- * \author Olaf Wintermann
- * \copyright 2-Clause BSD License
+ * @file array_list.h
+ * @brief Array list implementation.
+ * @author Mike Becker
+ * @author Olaf Wintermann
+ * @copyright 2-Clause BSD License
  */
 
 
@@ -52,44 +52,82 @@
 /**
  * Declares variables for an array that can be used with the convenience macros.
  *
+ * @par Examples
+ * @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)
  *
+ * @see cx_array_initialize()
  * @see cx_array_simple_add()
  * @see cx_array_simple_copy()
- * @see cx_array_initialize()
  * @see cx_array_simple_add_sorted()
  * @see cx_array_simple_insert_sorted()
  */
 #define CX_ARRAY_DECLARE_SIZED(type, name, size_type) \
-    type * name;                                      \
-    /** Array size. */ size_type name##_size;         \
+    type * name; \
+    /** Array size. */ size_type name##_size; \
     /** Array capacity. */ size_type name##_capacity
 
 /**
  * Declares variables for an array that can be used with the convenience macros.
  *
- * The size and capacity variables will have `size_t` type.
+ * The size and capacity variables will have @c size_t type.
  * Use #CX_ARRAY_DECLARE_SIZED() to specify a different type.
  *
+ * @par Examples
+ * @code
+ * // int array
+ * CX_ARRAY_DECLARE(int, myarray)
+ *
+ * // initializing code
+ * cx_array_initialize(myarray, 32); // reserve space for 32
+ * @endcode
+ *
  * @param type the type of the data
  * @param name the name of the array
  *
+ * @see cx_array_initialize()
  * @see cx_array_simple_add()
  * @see cx_array_simple_copy()
- * @see cx_array_initialize()
  * @see cx_array_simple_add_sorted()
  * @see cx_array_simple_insert_sorted()
  */
 #define CX_ARRAY_DECLARE(type, name) CX_ARRAY_DECLARE_SIZED(type, name, size_t)
 
 /**
- * Initializes an array declared with CX_ARRAY_DECLARE().
+ * Initializes an array with the given capacity.
+ *
+ * The type of the capacity depends on the type used during declaration.
+ *
+ * @par Examples
+ * @code
+ * CX_ARRAY_DECLARE_SIZED(int, arr1, uint8_t)
+ * CX_ARRAY_DECLARE(int, arr2) // size and capacity are implicitly size_t
+ *
+ * // initializing code
+ * cx_array_initialize(arr1, 500); // error: maximum for uint8_t is 255
+ * cx_array_initialize(arr2, 500); // OK
+ * @endcode
+ *
  *
  * The memory for the array is allocated with stdlib malloc().
- * @param array the array
+ * @param array the name of the array
  * @param capacity the initial capacity
+ * @see cx_array_initialize_a()
+ * @see CX_ARRAY_DECLARE_SIZED()
+ * @see CX_ARRAY_DECLARE()
  */
 #define cx_array_initialize(array, capacity) \
         array##_capacity = capacity; \
@@ -97,12 +135,26 @@
         array = malloc(sizeof(array[0]) * capacity)
 
 /**
- * Initializes an array declared with CX_ARRAY_DECLARE().
+ * Initializes an array with the given capacity using the specified allocator.
+ *
+ * @par Example
+ * @code
+ * CX_ARRAY_DECLARE(int, myarray)
+ *
  *
- * The memory for the array is allocated with the specified allocator.
- * @param allocator the allocator
- * @param array the array
+ * const CxAllocator *al = // ...
+ * cx_array_initialize_a(al, myarray, 128);
+ * // ...
+ * cxFree(al, myarray); // don't forget to free with same allocator
+ * @endcode
+ *
+ * The memory for the array is allocated with stdlib malloc().
+ * @param allocator (@c CxAllocator*) the allocator
+ * @param array the name of the array
  * @param capacity the initial capacity
+ * @see cx_array_initialize()
+ * @see CX_ARRAY_DECLARE_SIZED()
+ * @see CX_ARRAY_DECLARE()
  */
 #define cx_array_initialize_a(allocator, array, capacity) \
         array##_capacity = capacity; \
@@ -111,6 +163,8 @@
 
 /**
  * Defines a reallocation mechanism for arrays.
+ * You can create your own, use cx_array_reallocator(), or
+ * use the #cx_array_default_reallocator.
  */
 struct cx_array_reallocator_s {
     /**
@@ -126,7 +180,7 @@
      * @param capacity the new capacity (number of elements)
      * @param elem_size the size of each element
      * @param alloc a reference to this allocator
-     * @return a pointer to the reallocated memory or \c NULL on failure
+     * @return a pointer to the reallocated memory or @c NULL on failure
      */
     cx_attr_nodiscard
     cx_attr_nonnull_arg(4)
@@ -164,24 +218,27 @@
 /**
  * A default stdlib-based array reallocator.
  */
-extern struct cx_array_reallocator_s *cx_array_default_reallocator;
+extern CxArrayReallocator *cx_array_default_reallocator;
 
 /**
  * Creates a new array reallocator.
  *
- * When \p allocator is \c NULL, the stdlib default allocator will be used.
+ * When @p allocator is @c NULL, the stdlib default allocator will be used.
  *
- * When \p stackmem is not \c NULL, the reallocator is supposed to be used
- * \em only for the specific array that is initially located at \p stackmem.
+ * When @p stackmem is not @c NULL, the reallocator is supposed to be used
+ * @em only for the specific array that is initially located at @p stackmem.
  * When reallocation is needed, the reallocator checks, if the array is
- * still located at \p stackmem and copies the contents to the heap.
+ * still located at @p stackmem and copies the contents to the heap.
+ *
+ * @note Invoking this function with both arguments @c NULL will return a
+ * reallocator that behaves like #cx_array_default_reallocator.
  *
  * @param allocator the allocator this reallocator shall be based on
  * @param stackmem the address of the array when the array is initially located
- * on the stack
+ * on the stack or shall not reallocated in place
  * @return an array reallocator
  */
-struct cx_array_reallocator_s cx_array_reallocator(
+CxArrayReallocator cx_array_reallocator(
         const struct cx_allocator_s *allocator,
         const void *stackmem
 );
@@ -189,17 +246,17 @@
 /**
  * Reserves memory for additional elements.
  *
- * 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.
- * You can create your own reallocator by hand or use the convenience function
- * cx_array_reallocator().
+ * 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.
+ * 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 function can be useful to replace subsequent calls to cx_array_copy()
  * with one single cx_array_reserve() and then - after guaranteeing a
  * sufficient capacity - use simple memmove() or memcpy().
  *
- * The \p width in bytes refers to the size and capacity.
+ * The @p width in bytes refers to the size and capacity.
  * Both must have the same width.
  * Supported are 0, 1, 2, and 4, as well as 8 if running on a 64 bit
  * architecture. If set to zero, the native word width is used.
@@ -207,14 +264,16 @@
  * @param array a pointer to the target array
  * @param size a pointer to the size of the array
  * @param capacity a pointer to the capacity of the array
- * @param width the width in bytes for the \p size and \p capacity or zero for default
+ * @param width the width in bytes for the @p size and @p capacity or zero for default
  * @param elem_size the size of one element
  * @param elem_count the number of expected additional elements
  * @param reallocator the array reallocator to use
- * @return zero on success, non-zero on failure
+ * (@c NULL defaults to #cx_array_default_reallocator)
+ * @retval zero success
+ * @retval non-zero failure
  * @see cx_array_reallocator()
  */
-cx_attr_nonnull
+cx_attr_nonnull_arg(1, 2, 3)
 int cx_array_reserve(
         void **array,
         void *size,
@@ -222,23 +281,23 @@
         unsigned width,
         size_t elem_size,
         size_t elem_count,
-        struct cx_array_reallocator_s *reallocator
+        CxArrayReallocator *reallocator
 );
 
 /**
  * Copies elements from one array to another.
  *
- * The elements are copied to the \p target array at the specified \p index,
- * overwriting possible elements. The \p index does not need to be in range of
- * the current array \p size. If the new index plus the number of elements added
- * would extend the array's size, the remaining \p capacity is used.
+ * The elements are copied to the @p target array at the specified @p index,
+ * overwriting possible elements. The @p index does not need to be in range of
+ * the current array @p size. If the new index plus the number of elements added
+ * would extend the array's size, the remaining @p capacity is used.
  *
- * If the \p capacity is also insufficient to hold the new data, a reallocation
- * attempt is made with the specified \p reallocator.
- * You can create your own reallocator by hand or use the convenience function
- * cx_array_reallocator().
+ * If the @p capacity is also insufficient to hold the new data, a reallocation
+ * attempt is made with the specified @p reallocator.
+ * 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.
  *
- * The \p width in bytes refers to the size and capacity.
+ * The @p width in bytes refers to the size and capacity.
  * Both must have the same width.
  * Supported are 0, 1, 2, and 4, as well as 8 if running on a 64 bit
  * architecture. If set to zero, the native word width is used.
@@ -246,16 +305,18 @@
  * @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 width the width in bytes for the \p size and \p capacity or zero for default
+ * @param width the width in bytes for the @p size and @p capacity or zero for default
  * @param index the index where the copied elements shall be placed
  * @param src the source array
  * @param elem_size the size of one element
  * @param elem_count the number of elements to copy
  * @param reallocator the array reallocator to use
- * @return zero on success, non-zero on failure
+ * (@c NULL defaults to #cx_array_default_reallocator)
+ * @retval zero success
+ * @retval non-zero failure
  * @see cx_array_reallocator()
  */
-cx_attr_nonnull
+cx_attr_nonnull_arg(1, 2, 3, 6)
 int cx_array_copy(
         void **target,
         void *size,
@@ -265,19 +326,20 @@
         const void *src,
         size_t elem_size,
         size_t elem_count,
-        struct cx_array_reallocator_s *reallocator
+        CxArrayReallocator *reallocator
 );
 
 /**
  * Convenience macro that uses cx_array_copy() with a default layout and
  * the specified reallocator.
  *
- * @param reallocator the array reallocator to use
- * @param array the name of the array (NOT a pointer to the array)
- * @param index the index where the copied elements shall be placed
- * @param src the source array
- * @param count the number of elements to copy
- * @return zero on success, non-zero on failure
+ * @param reallocator (@c CxArrayReallocator*) the array reallocator to use
+ * @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 src (@c void*) the source array
+ * @param count (@c size_t) the number of elements to copy
+ * @retval zero success
+ * @retval non-zero failure
  * @see CX_ARRAY_DECLARE()
  * @see cx_array_simple_copy()
  */
@@ -290,26 +352,27 @@
  * Convenience macro that uses cx_array_copy() with a default layout and
  * the default reallocator.
  *
- * @param array the name of the array (NOT a pointer to the array)
- * @param index the index where the copied elements shall be placed
- * @param src the source array
- * @param count the number of elements to copy
- * @return zero on success, non-zero on failure
+ * @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 src (@c void*) the source array
+ * @param count (@c size_t) the number of elements to copy
+ * @retval zero success
+ * @retval non-zero failure
  * @see CX_ARRAY_DECLARE()
  * @see cx_array_simple_copy_a()
  */
 #define cx_array_simple_copy(array, index, src, count) \
-    cx_array_simple_copy_a(cx_array_default_reallocator, \
-    array, index, src, count)
+    cx_array_simple_copy_a(NULL, array, index, src, count)
 
 /**
  * Convenience macro that uses cx_array_reserve() with a default layout and
  * the specified reallocator.
  *
- * @param reallocator the array reallocator to use
- * @param array the name of the array (NOT a pointer to the array)
- * @param count the number of expected additional elements
- * @return zero on success, non-zero on failure
+ * @param reallocator (@c CxArrayReallocator*) the array reallocator to use
+ * @param array the name of the array (NOT a pointer or alias to the array)
+ * @param count (@c size_t) the number of expected @em additional elements
+ * @retval zero success
+ * @retval non-zero failure
  * @see CX_ARRAY_DECLARE()
  * @see cx_array_simple_reserve()
  */
@@ -322,33 +385,38 @@
  * Convenience macro that uses cx_array_reserve() with a default layout and
  * the default reallocator.
  *
- * @param array the name of the array (NOT a pointer to the array)
- * @param count the number of expected additional elements
- * @return zero on success, non-zero on failure
+ * @param array the name of the array (NOT a pointer or alias to the array)
+ * @param count (@c size_t) the number of expected additional elements
+ * @retval zero success
+ * @retval non-zero failure
  * @see CX_ARRAY_DECLARE()
  * @see cx_array_simple_reserve_a()
  */
 #define cx_array_simple_reserve(array, count) \
-    cx_array_simple_reserve_a(cx_array_default_reallocator, \
-    array, count)
+    cx_array_simple_reserve_a(NULL, array, count)
 
 /**
  * Adds an element to an array with the possibility of allocating more space.
  *
- * The element \p elem is added to the end of the \p target array which contains
- * \p size elements, already. The \p capacity must point to a variable denoting
+ * The element @p elem is added to the end of the @p target array which contains
+ * @p size elements, already. The @p capacity must point to a variable denoting
  * the current maximum number of elements the array can hold.
  *
  * 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.
+ * increase the @p capacity is made and the new capacity is written back.
+ *
+ * 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
+ * variables of the same type.
  *
- * @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 elem_size the size of one element
- * @param elem a pointer to the element to add
- * @param reallocator the array reallocator to use
- * @return zero on success, non-zero on failure
+ * @param target (@c void**) a pointer to the target array
+ * @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
+ * @param elem (@c void*) a pointer to the element to add
+ * @param reallocator (@c CxArrayReallocator*) the array reallocator to use
+ * @retval zero success
+ * @retval non-zero failure
  */
 #define cx_array_add(target, size, capacity, elem_size, elem, reallocator) \
     cx_array_copy((void**)(target), size, capacity, sizeof(*(size)), \
@@ -358,10 +426,11 @@
  * Convenience macro that uses cx_array_add() with a default layout and
  * the specified reallocator.
  *
- * @param reallocator the array reallocator to use
- * @param array the name of the array (NOT a pointer to the array)
+ * @param reallocator (@c CxArrayReallocator*) the array reallocator to use
+ * @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)
- * @return zero on success, non-zero on failure
+ * @retval zero success
+ * @retval non-zero failure
  * @see CX_ARRAY_DECLARE()
  * @see cx_array_simple_add()
  */
@@ -372,9 +441,10 @@
  * Convenience macro that uses cx_array_add() with a default layout and
  * the default reallocator.
  *
- * @param array the name of the array (NOT a pointer to the array)
+ * @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)
- * @return zero on success, non-zero on failure
+ * @retval zero success
+ * @retval non-zero failure
  * @see CX_ARRAY_DECLARE()
  * @see cx_array_simple_add_a()
  */
@@ -385,10 +455,12 @@
  * 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.
+ * 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
@@ -398,9 +470,11 @@
  * @param elem_size the size of one element
  * @param elem_count the number of elements to insert
  * @param reallocator the array reallocator to use
- * @return zero on success, non-zero on failure
+ * (@c NULL defaults to #cx_array_default_reallocator)
+ * @retval zero success
+ * @retval non-zero failure
  */
-cx_attr_nonnull
+cx_attr_nonnull_arg(1, 2, 3, 5)
 int cx_array_insert_sorted(
         void **target,
         size_t *size,
@@ -409,25 +483,31 @@
         const void *src,
         size_t elem_size,
         size_t elem_count,
-        struct cx_array_reallocator_s *reallocator
+        CxArrayReallocator *reallocator
 );
 
 /**
  * Inserts an element into a sorted array.
  *
  * If the target array is not already sorted with respect
- * to the specified \p cmp_func, the behavior is undefined.
+ * 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.
  *
- * @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 elem_size the size of one element
- * @param elem a pointer to the element to add
- * @param reallocator the array reallocator to use
- * @return zero on success, non-zero on failure
+ * 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
+ * variables of the same type.
+ *
+ * @param target (@c void**) a pointer to the target array
+ * @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
+ * @param elem (@c void*) a pointer to the element to add
+ * @param cmp_func (@c cx_cmp_func) the compare function for the elements
+ * @param reallocator (@c CxArrayReallocator*) the array reallocator to use
+ * @retval zero success
+ * @retval non-zero failure
  */
 #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)
@@ -436,11 +516,12 @@
  * Convenience macro for cx_array_add_sorted() with a default
  * layout and the specified reallocator.
  *
- * @param reallocator the array reallocator to use
- * @param array the name of the array (NOT a pointer to the array)
+ * @param reallocator (@c CxArrayReallocator*) the array reallocator to use
+ * @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)
- * @param cmp_func the compare function for the elements
- * @return zero on success, non-zero on failure
+ * @param cmp_func (@c cx_cmp_func) the compare function for the elements
+ * @retval zero success
+ * @retval non-zero failure
  * @see CX_ARRAY_DECLARE()
  * @see cx_array_simple_add_sorted()
  */
@@ -452,26 +533,28 @@
  * Convenience macro for cx_array_add_sorted() with a default
  * layout and the default reallocator.
  *
- * @param array the name of the array (NOT a pointer to the array)
+ * @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)
- * @param cmp_func the compare function for the elements
- * @return zero on success, non-zero on failure
+ * @param cmp_func (@c cx_cmp_func) the compare function for the elements
+ * @retval zero success
+ * @retval non-zero failure
  * @see CX_ARRAY_DECLARE()
  * @see cx_array_simple_add_sorted_a()
  */
 #define cx_array_simple_add_sorted(array, elem, cmp_func) \
-    cx_array_simple_add_sorted_a(cx_array_default_reallocator, array, elem, cmp_func)
+    cx_array_simple_add_sorted_a(NULL, array, elem, cmp_func)
 
 /**
  * Convenience macro for cx_array_insert_sorted() with a default
  * layout and the specified reallocator.
  *
- * @param reallocator the array reallocator to use
- * @param array the name of the array (NOT a pointer to the array)
- * @param src pointer to the source array
- * @param n number of elements in the source array
- * @param cmp_func the compare function for the elements
- * @return zero on success, non-zero on failure
+ * @param reallocator (@c CxArrayReallocator*) the array reallocator to use
+ * @param array the name of the array (NOT a pointer or alias to the array)
+ * @param src (@c void*) pointer to the source array
+ * @param n (@c size_t) number of elements in the source array
+ * @param cmp_func (@c cx_cmp_func) the compare function for the elements
+ * @retval zero success
+ * @retval non-zero failure
  * @see CX_ARRAY_DECLARE()
  * @see cx_array_simple_insert_sorted()
  */
@@ -483,28 +566,29 @@
  * Convenience macro for cx_array_insert_sorted() with a default
  * layout and the default reallocator.
  *
- * @param array the name of the array (NOT a pointer to the array)
- * @param src pointer to the source array
- * @param n number of elements in the source array
- * @param cmp_func the compare function for the elements
- * @return zero on success, non-zero on failure
+ * @param array the name of the array (NOT a pointer or alias to the array)
+ * @param src (@c void*) pointer to the source array
+ * @param n (@c size_t) number of elements in the source array
+ * @param cmp_func (@c cx_cmp_func) the compare function for the elements
+ * @retval zero success
+ * @retval non-zero failure
  * @see CX_ARRAY_DECLARE()
  * @see cx_array_simple_insert_sorted_a()
  */
 #define cx_array_simple_insert_sorted(array, src, n, cmp_func) \
-    cx_array_simple_insert_sorted_a(cx_array_default_reallocator, array, src, n, cmp_func)
+    cx_array_simple_insert_sorted_a(NULL, array, src, n, 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.
+ * 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.
  *
- * If \p elem is contained in the array, this is identical to
+ * 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
+ * If the array is not sorted with respect to the @p cmp_func, the behavior
  * is undefined.
  *
  * @param arr the array to search
@@ -512,7 +596,9 @@
  * @param elem_size the size of one element
  * @param elem the element to find
  * @param cmp_func the compare function
- * @return the index of the largest lower bound, or \p size
+ * @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
 size_t cx_array_binary_search_inf(
@@ -526,7 +612,7 @@
 /**
  * Searches an item in a sorted array.
  *
- * If the array is not sorted with respect to the \p cmp_func, the behavior
+ * If the array is not sorted with respect to the @p cmp_func, the behavior
  * is undefined.
  *
  * @param arr the array to search
@@ -534,8 +620,10 @@
  * @param elem_size the size of one element
  * @param elem the element to find
  * @param cmp_func the compare function
- * @return the index of the element in the array, or \p size if the element
+ * @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
 size_t cx_array_binary_search(
@@ -550,13 +638,13 @@
  * 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.
+ * 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.
  *
- * If \p elem is contained in the array, this is identical to
+ * 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
+ * If the array is not sorted with respect to the @p cmp_func, the behavior
  * is undefined.
  *
  * @param arr the array to search
@@ -564,7 +652,9 @@
  * @param elem_size the size of one element
  * @param elem the element to find
  * @param cmp_func the compare function
- * @return the index of the smallest upper bound, or \p size
+ * @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
 size_t cx_array_binary_search_sup(
@@ -592,16 +682,16 @@
 );
 
 /**
- * Allocates an array list for storing elements with \p elem_size bytes each.
+ * Allocates an array list for storing elements with @p elem_size bytes each.
  *
- * If \p elem_size is CX_STORE_POINTERS, the created list will be created as if
+ * If @p elem_size is CX_STORE_POINTERS, the created list will be created as if
  * cxListStorePointers() was called immediately after creation and the compare
  * function will be automatically set to cx_cmp_ptr(), if none is given.
  *
  * @param allocator the allocator for allocating the list memory
- * (if \c NULL, a default stdlib allocator will be used)
+ * (if @c NULL, a default stdlib allocator will be used)
  * @param comparator the comparator for the elements
- * (if \c NULL, and the list is not storing pointers, sort and find
+ * (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
@@ -618,18 +708,18 @@
 );
 
 /**
- * Allocates an array list for storing elements with \p elem_size bytes each.
+ * Allocates an array list for storing elements with @p elem_size bytes each.
  *
- * The list will use the cxDefaultAllocator and \em NO compare function.
+ * 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 will be created as if
+ * If @p elem_size is CX_STORE_POINTERS, the created list will be created as if
  * cxListStorePointers() was called immediately after creation and the compare
  * function will be automatically set to cx_cmp_ptr().
  *
- * @param elem_size the size of each element in bytes
- * @param initial_capacity the initial number of elements the array can store
+ * @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) \