Added container equality function to docs _eq(c1, c2).

6 files changed, 29 insertions, 4 deletions

diff --git a/docs/ccommon_api.md b/docs/ccommon_api.md
index e37a1463..eaf01996 100644
--- a/docs/ccommon_api.md
+++ b/docs/ccommon_api.md
@@ -204,22 +204,40 @@ if (it.ref) cmap_str_erase_at(&map, it);
 c_erase_if(i, csmap_str, map, cstr_contains(i.ref, "hello"));
 ```
 
-### csort - two times faster qsort
+### sort_n_ - two times faster qsort
 
-When very fast array sorting is required, **csort** is about twice as fast as *qsort()*, and often simpler to use.
+The **sort_n**, **sort_ij** algorithm is about twice as fast as *qsort()*, and often simpler to use.
 You may customize `i_tag` and the comparison function `i_cmp` or `i_less`.  
 
 There is a [benchmark/test file here](../misc/benchmarks/various/csort_bench.c).
 ```c
 #define i_val int
 #include <stc/algo/sort.h>
+#include <stdio.h>
 
 int main() {
-    int array[] = {5, 3, 5, 9, 7, 4, 7, 2, 4, 9, 3, 1, 2, 6, 4};
-    csort_int(array, c_arraylen(array));
+    int nums[] = {5, 3, 5, 9, 7, 4, 7, 2, 4, 9, 3, 1, 2, 6, 4};
+    intarray_sort_n(nums, c_arraylen(nums));
+    c_forrange (i, c_arraylen(arr)) printf(" %d", arr[i]);
 }
 ```
+Containers with random access may also be sorted. Even sorting cdeq/cqueue (with ring buffer) is
+possible and very fast. Note that `i_more` must be defined to pick up template parameters from the container:
+```c
+#define i_type MyDeq
+#define i_val int
+#define i_more
+#include <stc/cdeq.h> // deque
+#include <stc/algo/sort.h>
+#include <stdio.h>
 
+int main() {
+    MyDeq deq = c_make(MyDeq, {5, 3, 5, 9, 7, 4, 7, 2, 4, 9, 3, 1, 2, 6, 4});
+    MyDeq_sort_n(&deq, MyDeq_size(&deq));
+    c_foreach (i, MyDeq, deq) printf(" %d", *i.ref);
+    MyDeq_drop(&deq);
+}
+```
 
 ### c_new, c_delete
 
@@ -403,6 +421,8 @@ The **checkauto** utility described below, ensures that the `c_auto*` macros are
 | `continue`                             | Exit a defer-block without resource leak                  |
 
 ```c
+#include <stc/algo/raii.h> // or <stc/calgo.h>
+...
 // `c_defer` executes the expression(s) when leaving scope.
 cstr s1 = cstr_lit("Hello"), s2 = cstr_lit("world");
 c_defer (cstr_drop(&s1), cstr_drop(&s2))
diff --git a/docs/cdeq_api.md b/docs/cdeq_api.md
index 91022a5c..99980c24 100644
--- a/docs/cdeq_api.md
+++ b/docs/cdeq_api.md
@@ -79,6 +79,7 @@ cdeq_X_iter         cdeq_X_end(const cdeq_X* self);
 void                cdeq_X_next(cdeq_X_iter* it);
 cdeq_X_iter         cdeq_X_advance(cdeq_X_iter it, intptr_t n);
 
+bool                cdeq_X_eq(const cdeq_X* c1, const cdeq_X* c2); // require i_eq/i_cmp/i_less.
 cdeq_X_value        cdeq_X_value_clone(cdeq_X_value val);
 cdeq_X_raw          cdeq_X_value_toraw(const cdeq_X_value* pval);
 void                cdeq_X_value_drop(cdeq_X_value* pval);
diff --git a/docs/clist_api.md b/docs/clist_api.md
index 44c3bb7c..eb84fbd4 100644
--- a/docs/clist_api.md
+++ b/docs/clist_api.md
@@ -96,6 +96,7 @@ clist_X_iter        clist_X_end(const clist_X* self);
 void                clist_X_next(clist_X_iter* it);
 clist_X_iter        clist_X_advance(clist_X_iter it, size_t n);                         // return n elements ahead.
 
+bool                clist_X_eq(const clist_X* c1, const clist_X* c2);                   // equality test
 clist_X_value       clist_X_value_clone(clist_X_value val);
 clist_X_raw         clist_X_value_toraw(const clist_X_value* pval);
 void                clist_X_value_drop(clist_X_value* pval);
diff --git a/docs/cqueue_api.md b/docs/cqueue_api.md
index 7d8d4e5c..f5df86d6 100644
--- a/docs/cqueue_api.md
+++ b/docs/cqueue_api.md
@@ -51,6 +51,7 @@ cqueue_X_iter       cqueue_X_end(const cqueue_X* self);
 void                cqueue_X_next(cqueue_X_iter* it);
 cqueue_X_iter       cqueue_X_advance(cqueue_X_iter it, intptr_t n);
 
+bool                cqueue_X_eq(const cqueue_X* c1, const cqueue_X* c2); //  require i_eq/i_cmp/i_less.
 i_val               cqueue_X_value_clone(i_val value);
 cqueue_X_raw        cqueue_X_value_toraw(const cqueue_X_value* pval);
 void                cqueue_X_value_drop(cqueue_X_value* pval);
diff --git a/docs/cstack_api.md b/docs/cstack_api.md
index c20de7d1..9cb7b42b 100644
--- a/docs/cstack_api.md
+++ b/docs/cstack_api.md
@@ -54,6 +54,7 @@ cstack_X_iter       cstack_X_begin(const cstack_X* self);
 cstack_X_iter       cstack_X_end(const cstack_X* self);
 void                cstack_X_next(cstack_X_iter* it);
 
+bool                cstack_X_eq(const cstack_X* c1, const cstack_X* c2); // require i_eq/i_cmp/i_less.
 i_val               cstack_X_value_clone(i_val value);
 i_valraw            cstack_X_value_toraw(const cvec_X_value* pval);
 void                cstack_X_value_drop(cvec_X_value* pval);
diff --git a/docs/cvec_api.md b/docs/cvec_api.md
index 194d48e1..841321b2 100644
--- a/docs/cvec_api.md
+++ b/docs/cvec_api.md
@@ -91,6 +91,7 @@ cvec_X_iter         cvec_X_end(const cvec_X* self);
 void                cvec_X_next(cvec_X_iter* iter);
 cvec_X_iter         cvec_X_advance(cvec_X_iter it, size_t n);
 
+bool                cvec_X_eq(const cvec_X* c1, const cvec_X* c2); // equality comp.
 cvec_X_value        cvec_X_value_clone(cvec_X_value val);
 cvec_X_raw          cvec_X_value_toraw(const cvec_X_value* pval);
 cvec_X_raw          cvec_X_value_drop(cvec_X_value* pval);