Merge branch 'stclib:master' into modifiedHEADmodified

1 files changed, 43 insertions, 40 deletions

diff --git a/docs/clist_api.md b/docs/clist_api.md
index a1dbe105..a24d813b 100644
--- a/docs/clist_api.md
+++ b/docs/clist_api.md
@@ -22,16 +22,17 @@ See the c++ class [std::list](https://en.cppreference.com/w/cpp/container/list)
 ## Header file and declaration
 
 ```c
-#define i_type      // container type name (default: clist_{i_val})
-#define i_val       // value: REQUIRED
-#define i_cmp       // three-way compare two i_valraw* : REQUIRED IF i_valraw is a non-integral type
-#define i_valdrop   // destroy value func - defaults to empty destruct
-#define i_valclone  // REQUIRED IF i_valdrop defined
-
-#define i_valraw    // convertion "raw" type (default: {i_val})
-#define i_valto     // convertion func i_val* => i_valraw
-#define i_valfrom   // convertion func i_valraw => i_val
-#define i_tag       // alternative typename: cpque_{i_tag}. i_tag defaults to i_val
+#define i_key <t>      // element type: REQUIRED. Note: i_val* may be specified instead of i_key*.
+#define i_type <t>     // clist container type name
+#define i_cmp <f>      // three-way compare two i_keyraw*
+#define i_use_cmp      // define instead of i_cmp only when i_key is an integral/native-type.
+#define i_keydrop <f>  // destroy value func - defaults to empty destruct
+#define i_keyclone <f> // REQUIRED IF i_keydrop defined
+
+#define i_keyraw <t>   // convertion "raw" type (default: {i_key})
+#define i_keyto <f>    // convertion func i_key* => i_keyraw
+#define i_keyfrom <f>  // convertion func i_keyraw => i_key
+#define i_tag <s>      // alternative typename: cpque_{i_tag}. i_tag defaults to i_key
 #include <stc/clist.h>
 ```
 
@@ -53,50 +54,53 @@ intptr_t            clist_X_count(const clist_X* list);
 clist_X_value*      clist_X_back(const clist_X* self);
 clist_X_value*      clist_X_front(const clist_X* self);
 
-void                clist_X_push_back(clist_X* self, i_val value);                      // note: no pop_back()
-void                clist_X_push_front(clist_X* self, i_val value);
-void                clist_X_push(clist_X* self, i_val value);                           // alias for push_back()
+void                clist_X_push_back(clist_X* self, i_key value);                      // note: no pop_back()
+void                clist_X_push_front(clist_X* self, i_key value);
+void                clist_X_push(clist_X* self, i_key value);                           // alias for push_back()
 
-void                clist_X_emplace_back(clist_X* self, i_valraw raw);
-void                clist_X_emplace_front(clist_X* self, i_valraw raw);
-void                clist_X_emplace(clist_X* self, i_valraw raw);                       // alias for emplace_back()
+void                clist_X_emplace_back(clist_X* self, i_keyraw raw);
+void                clist_X_emplace_front(clist_X* self, i_keyraw raw);
+void                clist_X_emplace(clist_X* self, i_keyraw raw);                       // alias for emplace_back()
 
-clist_X_iter        clist_X_insert_at(clist_X* self, clist_X_iter it, i_val value);     // return iter to new elem
-clist_X_iter        clist_X_emplace_at(clist_X* self, clist_X_iter it, i_valraw raw);
+clist_X_iter        clist_X_insert_at(clist_X* self, clist_X_iter it, i_key value);     // return iter to new elem
+clist_X_iter        clist_X_emplace_at(clist_X* self, clist_X_iter it, i_keyraw raw);
 
 void                clist_X_pop_front(clist_X* self);
 clist_X_iter        clist_X_erase_at(clist_X* self, clist_X_iter it);                   // return iter after it
 clist_X_iter        clist_X_erase_range(clist_X* self, clist_X_iter it1, clist_X_iter it2);
-intptr_t            clist_X_remove(clist_X* self, i_valraw raw);                        // removes all matches
+intptr_t            clist_X_remove(clist_X* self, i_keyraw raw);                        // removes all matches
 
 clist_X             clist_X_split_off(clist_X* self, clist_X_iter i1, clist_X_iter i2); // split off [i1, i2)
 clist_X_iter        clist_X_splice(clist_X* self, clist_X_iter it, clist_X* other);     // return updated valid it
 clist_X_iter        clist_X_splice_range(clist_X* self, clist_X_iter it,                // return updated valid it
                                          clist_X* other, clist_X_iter it1, clist_X_iter it2);
 
-clist_X_iter        clist_X_find(const clist_X* self, i_valraw raw);
-clist_X_iter        clist_X_find_in(clist_X_iter it1, clist_X_iter it2, i_valraw raw);
-const i_val*        clist_X_get(const clist_X* self, i_valraw raw);
-i_val*              clist_X_get_mut(clist_X* self, i_valraw raw);
+clist_X_iter        clist_X_find(const clist_X* self, i_keyraw raw);
+clist_X_iter        clist_X_find_in(clist_X_iter it1, clist_X_iter it2, i_keyraw raw);
+const i_key*        clist_X_get(const clist_X* self, i_keyraw raw);
+i_key*              clist_X_get_mut(clist_X* self, i_keyraw raw);
 
 void                clist_X_reverse(clist_X* self);
 void                clist_X_sort(clist_X* self);
 void                clist_X_sort_with(clist_X* self, int(*cmp)(const clist_X_value*, const clist_X_value*));
 
 // Node API
-clist_X_node*       clist_X_get_node(clist_X_value* val);                               // get the enclosing node
+clist_X_node*       clist_X_get_node(clist_X_value* val);                               // get enclosing node
 clist_X_value*      clist_X_push_back_node(clist_X* self, clist_X_node* node);
 clist_X_value*      clist_X_insert_after_node(clist_X* self, clist_X_node* ref, clist_X_node* node);
-clist_X_node*       clist_X_unlink_after_node(clist_X* self, clist_X_node* ref);        // return the unlinked node
+clist_X_node*       clist_X_unlink_after_node(clist_X* self, clist_X_node* ref);        // return unlinked node
+clist_X_node*       clist_X_unlink_front_node(clist_X* self);                           // return unlinked node
 void                clist_X_erase_after_node(clist_X* self, clist_X_node* node);
 
 clist_X_iter        clist_X_begin(const clist_X* self);
 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.
+clist_X_iter        clist_X_advance(clist_X_iter it, size_t n);                         // return n elements ahead.
 
-clist_X_raw         clist_X_value_toraw(clist_X_value* pval);
+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);
 ```
 
 ## Types
@@ -105,8 +109,8 @@ clist_X_value       clist_X_value_clone(clist_X_value val);
 |:--------------------|:------------------------------------|:-----------------------------------------|
 | `clist_X`           | `struct { clist_X_node* last; }`                      | The clist type         |
 | `clist_X_node`      | `struct { clist_X_node* next; clist_X_value value; }` | The clist node type |
-| `clist_X_value`     | `i_val`                                               | The clist element type |
-| `clist_X_raw`       | `i_valraw`                                            | clist raw value type   |
+| `clist_X_value`     | `i_key`                                               | The clist element type |
+| `clist_X_raw`       | `i_keyraw`                                            | clist raw value type   |
 | `clist_X_iter`      | `struct { clist_value *ref; ... }`                    | clist iterator         |
 
 ## Example
@@ -114,14 +118,13 @@ clist_X_value       clist_X_value_clone(clist_X_value val);
 Interleave *push_front()* / *push_back()* then *sort()*:
 ```c
 #define i_type DList
-#define i_val double
-#define i_extern // link with sort() fn.
+#define i_key double
 #include <stc/clist.h>
 
 #include <stdio.h>
 
-int main() {
-    DList list = c_make(DList, {10., 20., 30., 40., 50., 60., 70., 80., 90.});
+int main(void) {
+    DList list = c_init(DList, {10., 20., 30., 40., 50., 60., 70., 80., 90.});
 
     c_forrange (i, 1, 10) {
         if (i & 1) DList_push_front(&list, (double) i);
@@ -152,14 +155,14 @@ Use of *erase_at()* and *erase_range()*:
 ```c
 // erasing from clist
 #define i_tag i
-#define i_val int
+#define i_key int
 #include <stc/clist.h>
 
 #include <stdio.h>
 
-int main ()
+int main(void)
 {
-    clist_i L = c_make(clist_i, {10, 20, 30, 40, 50});
+    clist_i L = c_init(clist_i, {10, 20, 30, 40, 50});
                                                 // 10 20 30 40 50
     clist_i_iter it = clist_i_begin(&L);        // ^
     clist_i_next(&it); 
@@ -187,14 +190,14 @@ mylist contains: 10 30
 Splice `[30, 40]` from *L2* into *L1* before `3`:
 ```c
 #define i_tag i
-#define i_val int
+#define i_key int
 #include <stc/clist.h>
 
 #include <stdio.h>
 
-int main() {
-    clist_i L1 = c_make(clist_i, {1, 2, 3, 4, 5});
-    clist_i L2 = c_make(clist_i, {10, 20, 30, 40, 50});
+int main(void) {
+    clist_i L1 = c_init(clist_i, {1, 2, 3, 4, 5});
+    clist_i L2 = c_init(clist_i, {10, 20, 30, 40, 50});
 
     clist_i_iter i = clist_i_advance(clist_i_begin(&L1), 2);
     clist_i_iter j1 = clist_i_advance(clist_i_begin(&L2), 2), j2 = clist_i_advance(j1, 2);