# HG changeset patch
# User Mike Becker <universe@uap-core.de>
# Date 1766057185 -3600
# Node ID c52a4c67e29ee16cadad89946cd44d38f020f1e0
# Parent  bf5d647f939dbeea4d28c353e303dbdac5c8669b
add convenience array_sort functions - relates to #622

diff -r bf5d647f939d -r c52a4c67e29e docs/Writerside/topics/array_list.h.md
--- a/docs/Writerside/topics/array_list.h.md	Thu Dec 18 12:11:30 2025 +0100
+++ b/docs/Writerside/topics/array_list.h.md	Thu Dec 18 12:26:25 2025 +0100
@@ -114,6 +114,30 @@
 > with `cx_array_copy_to_new()` or `cx_array_copy_to_new_a()` before adding or inserting more elements.
 >{style="note"}
 
+## Sorting
+
+```C
+#include <cx/array_list.h>
+
+void cx_array_qsort_c(void *array, size_t nmemb, size_t size,
+        cx_compare_func2 fn, void *context);
+
+void cx_array_sort(CxArray array, cx_compare_func fn);
+        
+void cx_array_sort_c(CxArray array,
+        cx_compare_func2 fn, void *context);
+```
+
+With simple `cx_compare_func` functions, arrays can always be sorted with standard `qsort()`.
+Sorting arrays with `cx_compare_func2` functions, however, need special support by either `qsort_r()` (GNU) or `qsort_s()` (ISO).
+However, both functions come with their own challenges.
+On the one hand, `qsort_r()` is not ISO standard, and on the other hand `qsort_s()` is only optional and has an incorrect parameter order in the Microsoft C library.
+
+To provide a platform independent solution, UCX detects if `qsort_r()` is available and implements a fallback when it is not.
+You can safely use `cx_array_qsort_c()` everywhere wehere you would use `qsort_r()`.
+
+The functions `cx_array_sort()` and `cx_array_sort_c()` are for convenient work with arrays declared with `CX_ARRAY()`.
+
 ## Insertion Sort
 
 ```C
diff -r bf5d647f939d -r c52a4c67e29e src/array_list.c
--- a/src/array_list.c	Thu Dec 18 12:11:30 2025 +0100
+++ b/src/array_list.c	Thu Dec 18 12:26:25 2025 +0100
@@ -372,6 +372,16 @@
 #endif
 }
 
+void cx_array_sort_(CxArray *array, size_t elem_size,
+        cx_compare_func fn) {
+    qsort(array->data, array->size, elem_size, fn);
+}
+
+void cx_array_sort_c_(CxArray *array, size_t elem_size,
+        cx_compare_func2 fn, void *context) {
+    cx_array_qsort_c(array->data, array->size, elem_size, fn, context);
+}
+
 CxIterator cx_array_iterator_(CxArray *array, size_t elem_size) {
     return cxIterator(array->data, elem_size, array->size);
 }
diff -r bf5d647f939d -r c52a4c67e29e src/cx/array_list.h
--- a/src/cx/array_list.h	Thu Dec 18 12:11:30 2025 +0100
+++ b/src/cx/array_list.h	Thu Dec 18 12:26:25 2025 +0100
@@ -560,6 +560,51 @@
         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.