Rewamp of cmap/csmap API. More to come.

11 files changed, 141 insertions, 146 deletions

diff --git a/docs/carray_api.md b/docs/carray_api.md
index 55d1f670..1e70d996 100644
--- a/docs/carray_api.md
+++ b/docs/carray_api.md
@@ -9,8 +9,8 @@ See the c++ class [boost::multi_array](https://www.boost.org/doc/libs/release/li
 ## Declaration
 
 ```c
-using_carray(X, Value, valueDestroy=c_default_del, 
-                       valueClone=c_default_clone)
+using_carray(X, Value);
+using_carray(X, Value, valueDestroy);
 ```
 The macro `using_carray()` can be instantiated with 2 or 4 arguments in the global scope.
 Default values are given above for args not specified. `X` and `N` are type tags and
diff --git a/docs/cdeq_api.md b/docs/cdeq_api.md
index 9aa8cd4b..8061cbdd 100644
--- a/docs/cdeq_api.md
+++ b/docs/cdeq_api.md
@@ -8,12 +8,12 @@ See the c++ class [std::deque](https://en.cppreference.com/w/cpp/container/deque
 ## Declaration
 
 ```c
-using_cdeq(X, Value, valueCompareRaw=c_default_compare,
-                     valueDestroy=c_default_del,
-                     valueFromRaw=c_default_clone,
-                     valueToRaw=c_default_to_raw,
-                     RawValue=Value)
-using_cdeq_str()
+using_cdeq(X, Value);
+using_cdeq(X, Value, valueCompareRaw);
+using_cdeq(X, Value, valueCompareRaw, valueDestroy);
+using_cdeq(X, Value, valueCompareRaw, valueDestroy, valueFromRaw, valueToRaw, RawValue);
+
+using_cdeq_str();
 ```
 The macro `using_cdeq()` can be instantiated with 2, 3, 5, or 7 arguments in the global scope.
 Defaults values are given above for args not specified. `X` is a type tag name and
@@ -60,11 +60,12 @@ cdeq_X_iter_t       cdeq_X_find(const cdeq_X* self, RawValue raw);
 cdeq_X_iter_t       cdeq_X_find_in_range(const cdeq_X* self,
                                          cdeq_X_iter_t first, cdeq_X_iter_t finish, RawValue raw);
 
-void                cdeq_X_push_n(cdeq_X *self, const cdeq_X_rawvalue_t arr[], size_t size);
 void                cdeq_X_push_front(cdeq_X* self, Value value);
 void                cdeq_X_push_back(cdeq_X* self, Value value);
 void                cdeq_X_emplace_front(cdeq_X* self, RawValue raw);
 void                cdeq_X_emplace_back(cdeq_X* self, RawValue raw);
+void                cdeq_X_push_n(cdeq_X *self, const cdeq_X_rawvalue_t arr[], size_t size);
+
 void                cdeq_X_pop_front(cdeq_X* self);
 void                cdeq_X_pop_back(cdeq_X* self);
 
diff --git a/docs/clist_api.md b/docs/clist_api.md
index d693a052..c69d61d3 100644
--- a/docs/clist_api.md
+++ b/docs/clist_api.md
@@ -17,11 +17,11 @@ See the c++ class [std::forward_list](https://en.cppreference.com/w/cpp/containe
 ## Declaration
 
 ```c
-using_clist(X, Value, valueCompareRaw=c_default_compare,
-                      valueDestroy=c_default_del,
-                      valueFromRaw=c_default_clone,
-                      valueToRaw=c_default_to_raw,
-                      RawValue=Value)
+using_clist(X, Value);
+using_clist(X, Value, valueCompareRaw);
+using_clist(X, Value, valueCompareRaw, valueDestroy);
+using_clist(X, Value, valueCompareRaw, valueDestroy, valueFromRaw, valueToRaw, RawValue);
+
 using_clist_str()
 ```
 The macro `using_clist()` can be instantiated with 2, 3, 5, or 7 arguments in the global scope.
@@ -54,17 +54,18 @@ size_t              clist_X_size(clist_X list); // note: O(n)
 clist_X_value_t*    clist_X_front(clist_X* self);
 clist_X_value_t*    clist_X_back(clist_X* self);
 
-void                clist_X_emplace_front(clist_X* self, RawValue raw);
 void                clist_X_push_front(clist_X* self, Value value);
-void                clist_X_pop_front(clist_X* self);
+void                clist_X_emplace_front(clist_X* self, RawValue raw);
 
-                    // non-std: push back, complexity O(1)
-void                clist_X_push_n(clist_X *self, const clist_X_rawvalue_t arr[], size_t size);
-void                clist_X_emplace_back(clist_X* self, RawValue ref);
+                    // non-std:
 void                clist_X_push_back(clist_X* self, Value value);
+void                clist_X_emplace_back(clist_X* self, RawValue raw);
+void                clist_X_push_n(clist_X *self, const clist_X_rawvalue_t arr[], size_t size);
+
+void                clist_X_pop_front(clist_X* self);
 
+clist_X_iter_t      clist_X_insert_after(clist_X* self, clist_X_iter_t it, Value value);
 clist_X_iter_t      clist_X_emplace_after(clist_X* self, clist_X_iter_t it, RawValue raw);
-clist_X_iter_t      clist_X_insert_after(clist_X* self, clist_X_iter_t it, Value raw);
 
 clist_X_iter_t      clist_X_erase_after(clist_X* self, clist_X_iter_t it);
 clist_X_iter_t      clist_X_erase_range_after(clist_X* self, clist_X_iter_t it1, clist_X_iter_t it2);
@@ -173,19 +174,19 @@ using_clist(i, int);
 
 int main ()
 {
-  c_init (clist_i, L, {10, 20, 30, 40, 50});
-                                               // 10 20 30 40 50
-  clist_i_iter_t it = clist_i_begin(&L);       // ^
-  it = clist_i_erase_after(&L, it);            // 10 30 40 50
-                                               //    ^
-  clist_i_iter_t end = clist_i_end(&L);        //
-  it = clist_i_erase_range_after(&L, it, end); // 10 30
-                                               //       ^
-  printf("mylist contains:");
-  c_foreach (x, clist_i, L) printf(" %d", *x.ref);
-  puts("");
-
-  clist_i_del(&L);
+    c_init (clist_i, L, {10, 20, 30, 40, 50});
+                                                 // 10 20 30 40 50
+    clist_i_iter_t it = clist_i_begin(&L);       // ^
+    it = clist_i_erase_after(&L, it);            // 10 30 40 50
+                                                 //    ^
+    clist_i_iter_t end = clist_i_end(&L);        //
+    it = clist_i_erase_range_after(&L, it, end); // 10 30
+                                                 //       ^
+    printf("mylist contains:");
+    c_foreach (x, clist_i, L) printf(" %d", *x.ref);
+    puts("");
+
+    clist_i_del(&L);
 }
 ```
 Output:
diff --git a/docs/cmap_api.md b/docs/cmap_api.md
index 04cfccf8..1b953f1d 100644
--- a/docs/cmap_api.md
+++ b/docs/cmap_api.md
@@ -9,43 +9,37 @@ See the c++ class [std::unordered_map](https://en.cppreference.com/w/cpp/contain
 ## Declaration
 
 ```c
-using_cmap(X, Key, Mapped, keyEqualsRaw=c_default_equals,
-                           keyHashRaw=c_default_hash,
-                           mappedDestroy=c_default_del,
-                           mappedClone=c_default_clone,
-                           keyDestroy=c_default_del,
-                           keyFromRaw=c_default_clone,
-                           keyToRaw=c_default_to_raw,
-                           RawKey=Key)
-
-using_cmap_strkey(X, Mapped, mappedDestroy=c_default_del,
-                             mappedClone=c_default_clone)
-
-using_cmap_strval(X, Key, keyEquals=c_default_equals,
-                          keyHash=c_default_hash,
-                          keyDestroy=c_default_del,
-                          keyFromRaw=c_default_clone,
-                          keyToRaw=c_default_to_raw,
-                          RawKey=Key)
-using_cmap_str()
+using_cmap(X, Key, Mapped);
+using_cmap(X, Key, Mapped, keyEquals, keyHash);
+using_cmap(X, Key, Mapped, keyEquals, keyHash, mappedDestroy);
+using_cmap(X, Key, Mapped, keyEquals, keyHash, mappedDestroy, mappedFromRaw, mappedToRaw, RawMapped);
+using_cmap(X, Key, Mapped, keyEqualsRaw, keyHashRaw, mappedDestroy, mappedFromRaw, mappedToRaw, RawMapped,
+                                                     keyDestroy, keyFromRaw, keyToRaw, RawKey);
+using_cmap_keyarg(X, Key, Mapped, keyEquals, keyHash, keyDestroy);
+using_cmap_keyarg(X, Key, Mapped, keyEqualsRaw, keyHashRaw, keyDestroy, keyFromRaw, keyToRaw, RawKey);
+
+using_cmap_strkey(X, Mapped);                    // cmap(str, cstr, Mapped, ...)
+using_cmap_strkey(X, Mapped, mappedDestroy);
+using_cmap_strkey(X, Mapped, mappedDestroy, mappedFromRaw, mappedToRaw, RawMapped);
+
+using_cmap_strval(X, Key);                       // cmap(str, Key, cstr, ...)
+using_cmap_strval(X, Key, keyEquals, keyHash);
+using_cmap_strval(X, Key, keyEquals, keyHash, keyDestroy);
+using_cmap_strval(X, Key, keyEqualsRaw, keyHashRaw, keyDestroy, keyFromRaw, keyToRaw, RawKey);
+
+using_cmap_str()                                 // cmap(str, cstr, cstr, ...)
 ```
-The macro `using_cmap()` can be instantiated with 3, 5, 7, 9, or 11 arguments in the global scope.
+The `using_cmap()` macro family must be instantiated in the global scope.
 Default values are given above for args not specified. `X` is a type tag name and
 will affect the names of all cmap types and methods. E.g. declaring `using_cmap(my, int);`, `X` should
 be replaced by `my` in all of the following documentation.
 
-`using_cmap_strkey()` and `using_cmap_strval()` are special macros defined by
-`using_cmap()`. The macro `using_cmap_str()` is a shorthand for
-```c
-using_cmap(str, cstr_t, cstr_t, cstr_del, ...) // uses char* as "raw" types
-```
-
 ## Header file
 
 All cmap definitions and prototypes may be included in your C source file by including a single header file.
 
 ```c
-#include "stc/cmap.h"
+#include <stc/cmap.h>
 ```
 ## Methods
 
@@ -69,12 +63,13 @@ size_t              cmap_X_bucket_count(cmap_X map);
 cmap_X_iter_t       cmap_X_find(const cmap_X* self, RawKey rkey);
 bool                cmap_X_contains(const cmap_X* self, RawKey rkey);
 
-void                cmap_X_push_n(cmap_X* self, const cmap_X_rawvalue_t arr[], size_t size);
+cmap_X_result_t     cmap_X_insert(cmap_X* self, Key key, Mapped mapped);                     // no change if key in map
+cmap_X_result_t     cmap_X_insert_or_assign(cmap_X* self, Key key, Mapped mapped);           // always update mapped
 cmap_X_result_t     cmap_X_emplace(cmap_X* self, RawKey rkey, RawMapped rmapped);            // no change if rkey in map
-cmap_X_result_t     cmap_X_put(cmap_X* self, RawKey rkey, RawMapped rmapped);                // std::map::operator[]
-cmap_X_result_t     cmap_X_insert(cmap_X* self, Key key, Mapped mapped);                     // like emplace, other params
-cmap_X_result_t     cmap_X_insert_or_assign(cmap_X* self, Key key, Mapped mapped);           // like put, other params
-cmap_X_mapped_t*    cmap_X_at(const cmap_X* self, RawKey rkey);                              // rkey must be in map
+cmap_X_result_t     cmap_X_emplace_put(cmap_X* self, RawKey rkey, RawMapped rmapped);        // always update rmapped
+void                cmap_X_push_n(cmap_X* self, const cmap_X_rawvalue_t arr[], size_t size);
+
+cmap_X_mapped_t*    cmap_X_at(const cmap_X* self, RawKey rkey);                              // rkey must be in map.
 
 size_t              cmap_X_erase(cmap_X* self, RawKey rkey);
 void                cmap_X_erase_entry(cmap_X* self, cmap_X_value_t* entry);
@@ -175,7 +170,7 @@ int main()
         {110, "Blue"},
     });
     /* put replaces existing mapped value: */
-    cmap_id_put(&idnames, 110, "White");
+    cmap_id_emplace_put(&idnames, 110, "White");
     /* put a constructed mapped value into map: */
     cmap_id_insert_or_assign(&idnames, 120, cstr_from_fmt("#%08x", col));
     /* emplace inserts only when key does not exist: */
@@ -209,10 +204,10 @@ int main()
 {
     cmap_v3 vecs = cmap_v3_init();
 
-    cmap_v3_put(&vecs, (Vec3i){100,   0,   0}, 1);
-    cmap_v3_put(&vecs, (Vec3i){  0, 100,   0}, 2);
-    cmap_v3_put(&vecs, (Vec3i){  0,   0, 100}, 3);
-    cmap_v3_put(&vecs, (Vec3i){100, 100, 100}, 4);
+    cmap_v3_emplace_put(&vecs, (Vec3i){100,   0,   0}, 1);
+    cmap_v3_emplace_put(&vecs, (Vec3i){  0, 100,   0}, 2);
+    cmap_v3_emplace_put(&vecs, (Vec3i){  0,   0, 100}, 3);
+    cmap_v3_emplace_put(&vecs, (Vec3i){100, 100, 100}, 4);
 
     c_foreach (i, cmap_v3, vecs)
         printf("{ %3d, %3d, %3d }: %d\n", i.ref->first.x,  i.ref->first.y,  i.ref->first.z,  i.ref->second);
@@ -240,10 +235,10 @@ using_cmap(iv, int, Vec3i);
 int main()
 {
     cmap_iv vecs = cmap_iv_init();
-    cmap_iv_put(&vecs, 1, (Vec3i){100,   0,   0});
-    cmap_iv_put(&vecs, 2, (Vec3i){  0, 100,   0});
-    cmap_iv_put(&vecs, 3, (Vec3i){  0,   0, 100});
-    cmap_iv_put(&vecs, 4, (Vec3i){100, 100, 100});
+    cmap_iv_emplace_put(&vecs, 1, (Vec3i){100,   0,   0});
+    cmap_iv_emplace_put(&vecs, 2, (Vec3i){  0, 100,   0});
+    cmap_iv_emplace_put(&vecs, 3, (Vec3i){  0,   0, 100});
+    cmap_iv_emplace_put(&vecs, 4, (Vec3i){100, 100, 100});
 
     c_foreach (i, cmap_iv, vecs)
         printf("%d: { %3d, %3d, %3d }\n", i.ref->first, i.ref->second.x,  i.ref->second.y,  i.ref->second.z);
@@ -312,7 +307,7 @@ int main()
         { {"Olaf", "Denmark"}, 24 },
         { {"Harald", "Iceland"}, 12 },
     });
-    cmap_vk_put(&vikings, (VikingRaw){"Bjorn", "Sweden"}, 10);
+    cmap_vk_emplace_put(&vikings, (VikingRaw){"Bjorn", "Sweden"}, 10);
     
     VikingRaw lookup = {"Einar", "Norway"};
 
diff --git a/docs/cpque_api.md b/docs/cpque_api.md
index a1762fbe..badc6315 100644
--- a/docs/cpque_api.md
+++ b/docs/cpque_api.md
@@ -39,9 +39,10 @@ bool                    cpque_X_empty(cpque_X pq);
 const
 cpque_X_value_t*        cpque_X_top(const cpque_X* self);
 
-void                    cpque_X_push_n(cpque_X *self, const cpque_X_rawvalue_t arr[], size_t size);
-void                    cpque_X_emplace(cpque_X* self, cpque_X_rawvalue_t raw);
 void                    cpque_X_push(cpque_X* self, cpque_X_value_t value);
+void                    cpque_X_emplace(cpque_X* self, cpque_X_rawvalue_t raw);
+void                    cpque_X_push_n(cpque_X *self, const cpque_X_rawvalue_t arr[], size_t size);
+
 void                    cpque_X_pop(cpque_X* self);
 void                    cpque_X_erase_at(cpque_X* self, size_t idx);
 
diff --git a/docs/cqueue_api.md b/docs/cqueue_api.md
index fee5bee4..653f9bfd 100644
--- a/docs/cqueue_api.md
+++ b/docs/cqueue_api.md
@@ -34,9 +34,10 @@ bool                    cqueue_X_empty(cqueue_X q);
 cqueue_X_value_t*       cqueue_X_front(cqueue_X* self);
 cqueue_X_value_t*       cqueue_X_back(cqueue_X* self);
 
-void                    cqueue_X_push_n(cqueue_X *self, const cqueue_X_rawvalue_t arr[], size_t size);
-void                    cqueue_X_emplace(cqueue_X* self, cqueue_X_rawvalue_t raw);
 void                    cqueue_X_push(cqueue_X* self, cqueue_X_value_t value);
+void                    cqueue_X_emplace(cqueue_X* self, cqueue_X_rawvalue_t raw);
+void                    cqueue_X_push_n(cqueue_X *self, const cqueue_X_rawvalue_t arr[], size_t size);
+
 void                    cqueue_X_pop(cqueue_X* self);
 
 cqueue_X_iter_t         cqueue_X_begin(cqueue_X* self);
diff --git a/docs/cset_api.md b/docs/cset_api.md
index 03a0e765..d2064cf2 100644
--- a/docs/cset_api.md
+++ b/docs/cset_api.md
@@ -7,13 +7,11 @@ A **cset** is an associative container that contains a set of unique objects of
 ## Declaration

 

 ```c

-using_cset(X, Key, keyEqualsRaw=c_default_equals,

-                   keyHashRaw=c_default_hash,

-                   keyDestroy=c_default_del,

-                   keyFromRaw=c_default_clone,

-                   keyToRaw=c_default_to_raw,                           

-                   RawKey=Key)

-using_cset_str()                           

+using_cset(X, Key);

+using_cset(X, Key, keyEqualsRaw, keyHashRaw);

+using_cset(X, Key, keyEqualsRaw, keyHashRaw, keyDestroy);

+using_cset(X, Key, keyEqualsRaw, keyHashRaw, keyDestroy, keyFromRaw, keyToRaw, RawKey);

+using_cset_str();

 ```

 The macro `using_cset()` can be instantiated with 2, 4, 6, or 8 arguments in the global scope.

 Default values are given above for args not specified. `X` is a type tag name and

@@ -51,13 +49,13 @@ size_t              cset_X_capacity(cset_X set);
 cset_X_iter_t       cset_X_find(const cset_X* self, RawKey rkey);

 bool                cset_X_contains(const cset_X* self, RawKey rkey);

 

-void                cset_X_push_n(cset_X* self, const RawKey arr[], size_t size);

-cset_X_result_t     cset_X_emplace(cset_X* self, RawKey rkey);

 cset_X_result_t     cset_X_insert(cset_X* self, Key key);

+cset_X_result_t     cset_X_emplace(cset_X* self, RawKey rkey);

+void                cset_X_push_n(cset_X* self, const RawKey arr[], size_t size);

 

 size_t              cset_X_erase(cset_X* self, RawKey rkey);

-void                cset_X_erase_entry(cset_X* self, cset_X_key_t* key);

 cset_X_iter_t       cset_X_erase_at(cset_X* self, cset_X_iter_t pos);

+void                cset_X_erase_entry(cset_X* self, cset_X_key_t* key);

 

 cset_X_iter_t       cset_X_begin(cset_X* self);

 cset_X_iter_t       cset_X_end(cset_X* self);

diff --git a/docs/csmap_api.md b/docs/csmap_api.md
index 72f90f08..ffbf7db4 100644
--- a/docs/csmap_api.md
+++ b/docs/csmap_api.md
@@ -8,41 +8,37 @@ See the c++ class [std::map](https://en.cppreference.com/w/cpp/container/map) fo
 ## Declaration
 
 ```c
-using_csmap(X, Key, Mapped, keyCompareRaw=c_default_compare,
-                            mappedDestroy=c_default_del,
-                            mappedClone=c_default_clone,
-                            keyDestroy=c_default_del,
-                            keyFromRaw=c_default_clone,
-                            keyToRaw=c_default_to_raw,
-                            RawKey=Key)
-
-using_csmap_strkey(X, Mapped, mappedDestroy=c_default_del,
-                              mappedClone=c_default_clone)
-
-using_csmap_strval(X, Key, keyCompare=c_default_compare,
-                           keyDestroy=c_default_del,
-                           keyFromRaw=c_default_clone,
-                           keyToRaw=c_default_to_raw,
-                           RawKey=Key)
-using_csmap_str()
+using_csmap(X, Key, Mapped);
+using_csmap(X, Key, Mapped, keyCompare);
+using_csmap(X, Key, Mapped, keyCompare, mappedDestroy);
+using_csmap(X, Key, Mapped, keyCompare, mappedDestroy, mappedFromRaw, mappedToRaw, RawMapped);
+using_csmap(X, Key, Mapped, keyCompareRaw, mappedDestroy, mappedFromRaw, mappedToRaw, RawMapped,
+                                           keyDestroy, keyFromRaw, keyToRaw, RawKey);
+using_csmap_keyarg(X, Key, Mapped, keyCompare, keyDestroy);
+using_csmap_keyarg(X, Key, Mapped, keyCompareRaw, keyDestroy, keyFromRaw, keyToRaw, RawKey);
+
+using_csmap_strkey(X, Mapped);                     // csmap(str, cstr, Mapped, ...)
+using_csmap_strkey(X, Mapped, mappedDestroy);
+using_csmap_strkey(X, Mapped, mappedDestroy, mappedFromRaw, mappedToRaw, RawMapped);
+
+using_csmap_strval(X, Key);                        // csmap(str, Key, cstr, ...)
+using_csmap_strval(X, Key, keyCompare);
+using_csmap_strval(X, Key, keyCompare, keyDestroy);
+using_csmap_strval(X, Key, keyCompareRaw, keyDestroy, keyFromRaw, keyToRaw, RawKey);
+
+using_csmap_str();                                 // csmap(str, cstr, cstr, ...)
 ```
-The macro `using_csmap()` can be instantiated with 3, 4, 6, 8, or 10 arguments in the global scope.
+The `using_csmap()` macro family must be instantiated in the global scope.
 Default values are given above for args not specified. `X` is a type tag name and
 will affect the names of all csmap types and methods. E.g. declaring `using_csmap(my, int);`, `X` should
 be replaced by `my` in all of the following documentation.
 
-`using_csmap_strkey()` and `using_csmap_strval()` are special macros defined by
-`using_csmap()`. The macro `using_csmap_str()` is a shorthand for
-```c
-using_csmap(str, cstr, cstr, cstr_compare_raw, cstr_del, cstr_from, ...)
-```
-
 ## Header file
 
 All csmap definitions and prototypes may be included in your C source file by including a single header file.
 
 ```c
-#include "stc/csmap.h"
+#include <stc/csmap.h>
 ```
 ## Methods
 
@@ -60,11 +56,12 @@ csmap_X_iter_t      csmap_X_find(const csmap_X* self, RawKey rkey);
 csmap_X_value_t*    csmap_X_find_it(const csmap_X* self, RawKey rkey, csmap_X_iter_t* out);  // return NULL if not found
 bool                csmap_X_contains(const csmap_X* self, RawKey rkey);
 
-void                csmap_X_push_n(csmap_X* self, const csmap_X_rawvalue_t arr[], size_t size);
+csmap_X_result_t    csmap_X_insert(csmap_X* self, Key key, Mapped mapped);                    // no change if key in map
+csmap_X_result_t    csmap_X_insert_or_assign(csmap_X* self, Key key, Mapped mapped);          // always update mapped
 csmap_X_result_t    csmap_X_emplace(csmap_X* self, RawKey rkey, RawMapped rmapped);           // no change if rkey in map
-csmap_X_result_t    csmap_X_put(csmap_X* self, RawKey rkey, RawMapped rmapped);               // std::map::operator[]
-csmap_X_result_t    csmap_X_insert(csmap_X* self, Key key, Mapped mapped);                    // like emplace, other params
-csmap_X_result_t    csmap_X_insert_or_assign(csmap_X* self, Key key, Mapped mapped);          // like put, other params
+csmap_X_result_t    csmap_X_emplace_put(csmap_X* self, RawKey rkey, RawMapped rmapped); // always update rmapped
+void                csmap_X_push_n(csmap_X* self, const csmap_X_rawvalue_t arr[], size_t size);
+
 csmap_X_mapped_t*   csmap_X_at(const csmap_X* self, RawKey rkey);                             // rkey must be in map.
 
 size_t              csmap_X_erase(csmap_X* self, RawKey rkey);
@@ -152,7 +149,7 @@ int main()
         {110, "Blue"},
     });
     /* put replaces existing mapped value: */
-    csmap_id_put(&idnames, 110, "White");
+    csmap_id_emplace_put(&idnames, 110, "White");
     /* put a constructed mapped value into map: */
     csmap_id_insert_or_assign(&idnames, 120, cstr_from_fmt("#%08x", col));
     /* emplace inserts only when key does not exist: */
@@ -192,10 +189,10 @@ int main()
 {
     csmap_vi vecs = csmap_vi_init();
 
-    csmap_vi_put(&vecs, (Vec3i){100,   0,   0}, 1);
-    csmap_vi_put(&vecs, (Vec3i){  0, 100,   0}, 2);
-    csmap_vi_put(&vecs, (Vec3i){  0,   0, 100}, 3);
-    csmap_vi_put(&vecs, (Vec3i){100, 100, 100}, 4);
+    csmap_vi_emplace_put(&vecs, (Vec3i){100,   0,   0}, 1);
+    csmap_vi_emplace_put(&vecs, (Vec3i){  0, 100,   0}, 2);
+    csmap_vi_emplace_put(&vecs, (Vec3i){  0,   0, 100}, 3);
+    csmap_vi_emplace_put(&vecs, (Vec3i){100, 100, 100}, 4);
 
     c_foreach (i, csmap_vi, vecs)
         printf("{ %3d, %3d, %3d }: %d\n", i.ref->first.x, i.ref->first.y, i.ref->first.z, i.ref->second);
@@ -223,10 +220,10 @@ using_csmap(iv, int, Vec3i);
 int main()
 {
     csmap_iv vecs = csmap_iv_init();
-    csmap_iv_put(&vecs, 1, (Vec3i){100,   0,   0});
-    csmap_iv_put(&vecs, 2, (Vec3i){  0, 100,   0});
-    csmap_iv_put(&vecs, 3, (Vec3i){  0,   0, 100});
-    csmap_iv_put(&vecs, 4, (Vec3i){100, 100, 100});
+    csmap_iv_emplace_put(&vecs, 1, (Vec3i){100,   0,   0});
+    csmap_iv_emplace_put(&vecs, 2, (Vec3i){  0, 100,   0});
+    csmap_iv_emplace_put(&vecs, 3, (Vec3i){  0,   0, 100});
+    csmap_iv_emplace_put(&vecs, 4, (Vec3i){100, 100, 100});
 
     c_foreach (i, csmap_iv, vecs)
         printf("%d: { %3d, %3d, %3d }\n", i.ref->first, i.ref->second.x, i.ref->second.y, i.ref->second.z);
diff --git a/docs/csset_api.md b/docs/csset_api.md
index 33eecd1b..79c01b72 100644
--- a/docs/csset_api.md
+++ b/docs/csset_api.md
@@ -8,12 +8,11 @@ See the c++ class [std::set](https://en.cppreference.com/w/cpp/container/set) fo
 ## Declaration

 

 ```c

-using_csset(X, Key, keyCompare=c_default_compare,

-                    keyDestroy=c_default_del,

-                    keyFromRaw=c_default_clone,

-                    keyToRaw=c_default_to_raw,                           

-                    RawKey=Key)

-using_csset_str()                           

+using_csset(X, Key);

+using_csset(X, Key, keyCompare);

+using_csset(X, Key, keyCompare, keyDestroy);

+using_csset(X, Key, keyCompare, keyDestroy, keyFromRaw, keyToRaw, RawKey);

+using_csset_str();

 ```

 The macro `using_csset()` can be instantiated with 2, 3, 5, or 7 arguments in the global scope.

 Default values are given above for args not specified. `X` is a type tag name and

@@ -45,9 +44,9 @@ csset_X_iter_t      csset_X_find(const csset_X* self, RawKey rkey);
 csset_X_value_t*    csset_X_find_it(const csset_X* self, RawKey rkey, csset_X_iter_t* out);

 bool                csset_X_contains(const csset_X* self, RawKey rkey);

 

-void                csset_X_push_n(csset_X* self, const RawKey arr[], size_t size);

-csset_X_result_t    csset_X_emplace(csset_X* self, RawKey rkey);

 csset_X_result_t    csset_X_insert(csset_X* self, Key key);

+csset_X_result_t    csset_X_emplace(csset_X* self, RawKey rkey);

+void                csset_X_push_n(csset_X* self, const RawKey arr[], size_t size);

 

 size_t              csset_X_erase(csset_X* self, RawKey rkey);

 csset_X_iter_t      csset_X_erase_at(csset_X* self, csset_X_iter_t pos);

diff --git a/docs/cstack_api.md b/docs/cstack_api.md
index 3028f6cb..86b0e42a 100644
--- a/docs/cstack_api.md
+++ b/docs/cstack_api.md
@@ -34,9 +34,10 @@ size_t                  cstack_X_size(cstack_X st);
 bool                    cstack_X_empty(cstack_X st);
 cstack_X_value_t*       cstack_X_top(cstack_X* self);
 
-void                    cstack_X_push_n(cstack_X *self, const cstack_X_rawvalue_t arr[], size_t size);
-void                    cstack_X_emplace(cstack_X* self, cstack_X_rawvalue_t raw);
 void                    cstack_X_push(cstack_X* self, cstack_X_value_t value);
+void                    cstack_X_emplace(cstack_X* self, cstack_X_rawvalue_t raw);
+void                    cstack_X_push_n(cstack_X *self, const cstack_X_rawvalue_t arr[], size_t size);
+
 void                    cstack_X_pop(cstack_X* self);
 
 cstack_X_iter_t         cstack_X_begin(cstack_X* self);
diff --git a/docs/cvec_api.md b/docs/cvec_api.md
index 7c523f02..ef5c9f99 100644
--- a/docs/cvec_api.md
+++ b/docs/cvec_api.md
@@ -12,11 +12,11 @@ See the c++ class [std::vector](https://en.cppreference.com/w/cpp/container/vect
 ## Declaration
 
 ```c
-using_cvec(X, Value, valueCompareRaw=c_default_compare,
-                     valueDestroy=c_default_del,
-                     valueFromRaw=c_default_clone,
-                     valueToRaw=c_default_to_raw,
-                     RawValue=Value)
+using_cvec(X, Value);
+using_cvec(X, Value, valueCompareRaw);
+using_cvec(X, Value, valueCompareRaw, valueDestroy);
+using_cvec(X, Value, valueCompareRaw, valueDestroy, valueFromRaw, valueToRaw, RawValue);
+
 using_cvec_str()
 ```
 The macro `using_cvec()` can be instantiated with 2, 3, 5, or 7 arguments in the global scope.
@@ -60,19 +60,20 @@ cvec_X_value_t*     cvec_X_at(cvec_X* self, size_t idx);
 cvec_X_value_t*     cvec_X_front(cvec_X* self);
 cvec_X_value_t*     cvec_X_back(cvec_X* self);
 
-void                cvec_X_push_n(cvec_X *self, const cvec_X_rawvalue_t arr[], size_t size);
-void                cvec_X_emplace_back(cvec_X* self, RawValue raw);
 void                cvec_X_push_back(cvec_X* self, Value value);
+void                cvec_X_emplace_back(cvec_X* self, RawValue raw);
+void                cvec_X_push_n(cvec_X *self, const cvec_X_rawvalue_t arr[], size_t size);
+
 void                cvec_X_pop_back(cvec_X* self);
 
-cvec_X_iter_t       cvec_X_emplace(cvec_X* self, size_t idx, RawValue raw);
-cvec_X_iter_t       cvec_X_emplace_at(cvec_X* self, cvec_X_iter_t pos, RawValue raw);
 cvec_X_iter_t       cvec_X_insert(cvec_X* self, size_t idx, Value value);
 cvec_X_iter_t       cvec_X_insert_at(cvec_X* self, cvec_X_iter_t pos, Value value);
 cvec_X_iter_t       cvec_X_insert_range(cvec_X* self, cvec_X_iter_t pos,
                                         cvec_X_iter_t first, cvec_X_iter_t finish);
 cvec_X_iter_t       cvec_X_insert_range_p(cvec_X* self, cvec_X_value_t* pos,
                                           const cvec_X_value_t* pfirst, const cvec_X_value_t* pfinish);
+cvec_X_iter_t       cvec_X_emplace(cvec_X* self, size_t idx, RawValue raw);
+cvec_X_iter_t       cvec_X_emplace_at(cvec_X* self, cvec_X_iter_t pos, RawValue raw);
 
 cvec_X_iter_t       cvec_X_erase(cvec_X* self, size_t idx, size_t n);
 cvec_X_iter_t       cvec_X_erase_at(cvec_X* self, cvec_X_iter_t pos);