Changed recommended order of defining template parameters.

13 files changed, 57 insertions, 53 deletions

diff --git a/docs/carray_api.md b/docs/carray_api.md
index b567d8aa..d7ece0fa 100644
--- a/docs/carray_api.md
+++ b/docs/carray_api.md
@@ -9,11 +9,11 @@ See the c++ class [boost::multi_array](https://www.boost.org/doc/libs/release/li
 ## Header file and declaration
 
 ```c
-#define i_tag       // defaults to i_val name
 #define i_val       // value: REQUIRED
+#define i_del       // destroy value func - defaults to empty destruct
 #define i_valfrom   // func Raw => i_val - defaults to plain copy
 #define i_valto     // func i_val => Raw - defaults to plain copy
-#define i_valdel    // destroy value func - defaults to empty destruct
+#define i_tag       // defaults to i_val
 
 #include <stc/carr2.h> // or <stc/carr3.h>
 ```
@@ -75,12 +75,12 @@ The **carr3** elements can be accessed like `carr3_i arr = ...; int val = arr.da
 ```c
 #include <stdio.h>
 
-#define i_tag i
 #define i_val uint32_t
+#define i_tag i
 #include <stc/carr2.h>
 
-#define i_tag f
 #define i_val float
+#define i_tag f
 #include <stc/carr3.h>
 
 int main()
diff --git a/docs/cdeq_api.md b/docs/cdeq_api.md
index bacb2f86..26a6bbff 100644
--- a/docs/cdeq_api.md
+++ b/docs/cdeq_api.md
@@ -8,13 +8,13 @@ See the c++ class [std::deque](https://en.cppreference.com/w/cpp/container/deque
 ## Header file and declaration
 
 ```c
-#define i_tag       // defaults to i_val name
 #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_del       // destroy value func - defaults to empty destruct
 #define i_valraw    // convertion "raw" type - defaults to i_val
 #define i_valfrom   // convertion func i_valraw => i_val - defaults to plain copy
 #define i_valto     // convertion func i_val* => i_valraw - defaults to plain copy
-#define i_valdel    // destroy value func - defaults to empty destruct
+#define i_tag       // defaults to i_val
 #include <stc/cdeq.h>
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.
@@ -94,8 +94,8 @@ cdeq_X_value_t      cdeq_X_value_clone(cdeq_X_value_t val);
 
 ## Examples
 ```c
-#define i_tag i
 #define i_val int
+#define i_tag i
 #include <stc/cdeq.h>
 
 #include <stdio.h>
diff --git a/docs/clist_api.md b/docs/clist_api.md
index e1b8f0b1..7ef12153 100644
--- a/docs/clist_api.md
+++ b/docs/clist_api.md
@@ -22,13 +22,13 @@ See the c++ class [std::list](https://en.cppreference.com/w/cpp/container/list)
 ## Header file and declaration
 
 ```c
-#define i_tag       // defaults to i_val name
 #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_del       // destroy value func - defaults to empty destruct
 #define i_valraw    // convertion "raw" type - defaults to i_val
 #define i_valfrom   // convertion func i_valraw => i_val - defaults to plain copy
 #define i_valto     // convertion func i_val* => i_valraw - defaults to plain copy
-#define i_valdel    // destroy value func - defaults to empty destruct
+#define i_tag       // defaults to i_val
 #include <stc/clist.h>
 ```
 
@@ -96,9 +96,10 @@ clist_X_value_t     clist_X_value_clone(clist_X_value_t val);
 
 Interleave *push_front()* / *push_back()* then *sort()*:
 ```c
-#define i_tag d
 #define i_val double
+#define i_tag d
 #include <stc/clist.h>
+
 #include <stdio.h>
 
 int main() {
diff --git a/docs/cmap_api.md b/docs/cmap_api.md
index 08f551e6..0146ff49 100644
--- a/docs/cmap_api.md
+++ b/docs/cmap_api.md
@@ -17,19 +17,19 @@ See the c++ class [std::unordered_map](https://en.cppreference.com/w/cpp/contain
 ## Header file and declaration
 
 ```c
-#define i_tag       // defaults to i_key name
 #define i_key       // key: REQUIRED
 #define i_val       // value: REQUIRED
-#define i_equ       // equality comparison two i_keyraw*. REQUIRED IF i_keyraw is non-integral type
-#define i_cmp       // three-way compare two i_keyraw* : may be defined instead of i_equ
+#define i_cmp       // three-way compare two i_keyraw*: REQUIRED IF i_keyraw is non-integral type
+#define i_equ       // equality comparison two i_keyraw*: ALTERNATIVE to i_cmp
+#define i_keydel    // destroy key func - defaults to empty destruct
 #define i_keyraw    // convertion "raw" type - defaults to i_key
 #define i_keyfrom   // convertion func i_keyraw => i_key - defaults to plain copy
 #define i_keyto     // convertion func i_key* => i_keyraw - defaults to plain copy
-#define i_keydel    // destroy key func - defaults to empty destruct
+#define i_valdel    // destroy value func - defaults to empty destruct
 #define i_valraw    // convertion "raw" type - defaults to i_val
 #define i_valfrom   // convertion func i_valraw => i_val - defaults to plain copy
 #define i_valto     // convertion func i_val* => i_valraw - defaults to plain copy
-#define i_valdel    // destroy value func - defaults to empty destruct
+#define i_tag       // defaults to i_key
 #include <stc/cmap.h>
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.
@@ -161,9 +161,9 @@ This example uses a cmap with cstr as mapped value.
 ```c
 #include <stc/cstr.h>
 
-#define i_tag id
 #define i_key int
 #define i_val_str
+#define i_tag id
 #include <stc/cmap.h>
 
 int main()
@@ -201,10 +201,10 @@ Demonstrate cmap with plain-old-data key type Vec3i and int as mapped type: cmap
 #include <stdio.h>
 typedef struct { int x, y, z; } Vec3i;
 
-#define i_tag vi
 #define i_key Vec3i
 #define i_val int
-#define i_cmp c_memcmp_equals // bitwise equals, uses c_default_hash
+#define i_cmp c_memcmp_equals // bitwise compare, and use c_default_hash
+#define i_tag vi
 #include <stc/cmap.h>
 
 int main()
@@ -236,9 +236,9 @@ Inverse: demonstrate cmap with mapped POD type Vec3i: cmap<int, Vec3i>:
 #include <stdio.h>
 typedef struct { int x, y, z; } Vec3i;
 
-#define i_tag iv
 #define i_key int
 #define i_val Vec3i
+#define i_tag iv
 #include <stc/cmap.h>
 
 int main()
@@ -285,12 +285,12 @@ static void Viking_del(Viking* v) {
     c_del(cstr, &v->name, &v->country);
 }
 
-#define i_tag vk
 #define i_key Viking
 #define i_val int
 #define i_equ Viking_equals
 #define i_hash Viking_hash
-#define i_keydel Viking_del
+#define i_del Viking_del
+#define i_tag vk
 #include <stc/cmap.h>
 
 int main()
@@ -358,15 +358,15 @@ static Viking Viking_fromR(RViking r)
 static RViking Viking_toR(const Viking* v) 
     { return (RViking){v->name.str, v->country.str}; }
 
-#define i_tag vk
 #define i_key Viking
 #define i_val int
 #define i_equ RViking_equals
 #define i_hash RViking_hash
+#define i_keydel Viking_del
 #define i_keyraw RViking
 #define i_keyfrom Viking_fromR
 #define i_keyto Viking_toR
-#define i_keydel Viking_del
+#define i_tag vk
 #include <stc/cmap.h>
 
 int main()
diff --git a/docs/cpque_api.md b/docs/cpque_api.md
index 4e58a323..4f22fe0e 100644
--- a/docs/cpque_api.md
+++ b/docs/cpque_api.md
@@ -8,13 +8,13 @@ See the c++ class [std::priority_queue](https://en.cppreference.com/w/cpp/contai
 ## Header file and declaration
 
 ```c
-#define i_tag       // defaults to i_val name
 #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_del       // destroy value func - defaults to empty destruct
 #define i_valraw    // convertion "raw" type - defaults to i_val
 #define i_valfrom   // convertion func i_valraw => i_val - defaults to plain copy
 #define i_valto     // convertion func i_val* => i_valraw - defaults to plain copy
-#define i_valdel    // destroy value func - defaults to empty destruct
+#define i_tag       // defaults to i_val
 #include <stc/cpque.h>
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.
@@ -58,9 +58,9 @@ cpque_X_value_t     cpque_X_value_clone(cpque_X_value_t val);
 #include <stc/crandom.h>
 #include <stdio.h>
 
-#define i_tag i
 #define i_val int64_t
 #define i_cmp -c_default_compare // min-heap
+#define i_tag i
 #include <stc/cpque.h>
 
 int main()
diff --git a/docs/cqueue_api.md b/docs/cqueue_api.md
index d5843614..76c189e5 100644
--- a/docs/cqueue_api.md
+++ b/docs/cqueue_api.md
@@ -7,13 +7,13 @@ See the c++ class [std::queue](https://en.cppreference.com/w/cpp/container/queue
 
 ## Header file and declaration
 ```c
-#define i_tag       // defaults to i_val name
 #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_del       // destroy value func - defaults to empty destruct
 #define i_valraw    // convertion "raw" type - defaults to i_val
 #define i_valfrom   // convertion func i_valraw => i_val - defaults to plain copy
 #define i_valto     // convertion func i_val* => i_valraw - defaults to plain copy
-#define i_valdel    // destroy value func - defaults to empty destruct
+#define i_tag       // defaults to i_val
 #include <stc/cqueue.h>
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.
@@ -57,8 +57,8 @@ cqueue_X_value_t        cqueue_X_value_clone(cqueue_X_value_t val);
 
 ## Examples
 ```c
-#define i_tag i
 #define i_val int
+#define i_tag i
 #include <stc/cqueue.h>
 
 #include <stdio.h>
diff --git a/docs/crandom_api.md b/docs/crandom_api.md
index 6398e197..3dd829aa 100644
--- a/docs/crandom_api.md
+++ b/docs/crandom_api.md
@@ -74,9 +74,9 @@ double              stc64_normalf(stc64_t* rng, stc64_normalf_t* dist);
 #include <stc/cstr.h>
 
 // Declare int -> int sorted map. Uses typetag 'i' for ints.
-#define i_tag i
 #define i_key int
 #define i_val size_t
+#define i_tag i
 #include <stc/csmap.h>
 
 int main()
diff --git a/docs/cset_api.md b/docs/cset_api.md
index d6c4ab80..e09436ea 100644
--- a/docs/cset_api.md
+++ b/docs/cset_api.md
@@ -7,15 +7,15 @@ A **cset** is an associative container that contains a set of unique objects of
 ## Header file and declaration

 

 ```c

-#define i_tag       // defaults to i_key name

 #define i_key       // key: REQUIRED

 #define i_hash      // hash func: REQUIRED IF i_keyraw is a non-pod type

-#define i_equ       // equality comparison two i_keyraw*.  REQUIRED IF i_keyraw is a non-integral type

-#define i_cmp       // three-way compare two i_keyraw* : alternative to i_equ

+#define i_cmp       // three-way compare two i_keyraw*: REQUIRED IF i_keyraw is a non-integral type

+#define i_equ       // equality comparison two i_keyraw*: ALTERNATIVE to i_cmp 

+#define i_del       // destroy key func - defaults to empty destruct

 #define i_keyraw    // convertion "raw" type - defaults to i_key

 #define i_keyfrom   // convertion func i_keyraw => i_key - defaults to plain copy

 #define i_keyto     // convertion func i_key* => i_keyraw - defaults to plain copy

-#define i_keydel    // destroy key func - defaults to empty destruct

+#define i_tag       // defaults to i_key

 #include <stc/cset.h>

 ```

 `X` should be replaced by the value of `i_tag` in all of the following documentation.

diff --git a/docs/csmap_api.md b/docs/csmap_api.md
index a1d3a5c7..46d5eff7 100644
--- a/docs/csmap_api.md
+++ b/docs/csmap_api.md
@@ -15,18 +15,18 @@ See the c++ class [std::map](https://en.cppreference.com/w/cpp/container/map) fo
 ## Header file and declaration
 
 ```c
-#define i_tag       // defaults to i_key name
 #define i_key       // key: REQUIRED
 #define i_val       // value: REQUIRED
 #define i_cmp       // three-way compare two i_keyraw* : REQUIRED IF i_keyraw is a non-integral type
+#define i_keydel    // destroy key func - defaults to empty destruct
 #define i_keyraw    // convertion "raw" type - defaults to i_key
 #define i_keyfrom   // convertion func i_keyraw => i_key - defaults to plain copy
 #define i_keyto     // convertion func i_key* => i_keyraw - defaults to plain copy
-#define i_keydel    // destroy key func - defaults to empty destruct
+#define i_valdel    // destroy value func - defaults to empty destruct
 #define i_valraw    // convertion "raw" type - defaults to i_val
 #define i_valfrom   // convertion func i_valraw => i_val - defaults to plain copy
 #define i_valto     // convertion func i_val* => i_valraw - defaults to plain copy
-#define i_valdel    // destroy value func - defaults to empty destruct
+#define i_tag       // defaults to i_key
 #include <stc/csmap.h>
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.
@@ -132,9 +132,9 @@ This example uses a csmap with cstr as mapped value.
 ```c
 #include <stc/cstr.h>
 
-#define i_tag id
 #define i_key int
 #define i_val_str
+#define i_tag id
 #include <stc/csmap.h>
 
 int main()
@@ -145,7 +145,7 @@ int main()
         {100, "Red"},
         {110, "Blue"},
     });
-    c_autoscope (0, csmap_id_del(&idnames)) 
+    c_autodefer (csmap_id_del(&idnames)) 
     {
         // put replaces existing mapped value:
         csmap_id_emplace_or_assign(&idnames, 110, "White");
@@ -178,10 +178,10 @@ static int Vec3i_compare(const Vec3i* a, const Vec3i* b) {
     return (a->z > b->z) - (a->z < b->z);
 }
 
-#define i_tag vi
 #define i_key Vec3i
 #define i_val int
 #define i_cmp Vec3i_compare // uses c_default_hash
+#define i_tag vi
 #include <stc/csmap.h>
 #include <stdio.h>
 
diff --git a/docs/csptr_api.md b/docs/csptr_api.md
index 026ce6c3..bd9bf7d2 100644
--- a/docs/csptr_api.md
+++ b/docs/csptr_api.md
@@ -26,10 +26,10 @@ See the c++ classes [std::shared_ptr](https://en.cppreference.com/w/cpp/memory/s
 ## Header file and declaration
 
 ```c
-#define i_tag       // defaults to i_val name
 #define i_val       // value: REQUIRED
 #define i_cmp       // three-way compare two i_val* : REQUIRED IF i_val is a non-integral type
-#define i_valdel    // destroy value func - defaults to empty destruct
+#define i_del       // destroy value func - defaults to empty destruct
+#define i_tag       // defaults to i_val
 #include <stc/csptr.h>
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.
diff --git a/docs/csset_api.md b/docs/csset_api.md
index f7cf0dc4..67ff1911 100644
--- a/docs/csset_api.md
+++ b/docs/csset_api.md
@@ -8,13 +8,13 @@ See the c++ class [std::set](https://en.cppreference.com/w/cpp/container/set) fo
 ## Header file and declaration

 

 ```c

-#define i_tag       // defaults to i_key name

 #define i_key       // key: REQUIRED

 #define i_cmp       // three-way compare two i_keyraw* : REQUIRED IF i_keyraw is a non-integral type

+#define i_del       // destroy key func - defaults to empty destruct

 #define i_keyraw    // convertion "raw" type - defaults to i_key

 #define i_keyfrom   // convertion func i_keyraw => i_key - defaults to plain copy

 #define i_keyto     // convertion func i_key* => i_keyraw - defaults to plain copy

-#define i_keydel    // destroy key func - defaults to empty destruct

+#define i_tag       // defaults to i_key

 #include <stc/csset.h>

 ```

 `X` should be replaced by the value of `i_tag` in all of the following documentation.

diff --git a/docs/cstack_api.md b/docs/cstack_api.md
index 91fa7de5..31f6ade7 100644
--- a/docs/cstack_api.md
+++ b/docs/cstack_api.md
@@ -8,13 +8,13 @@ See the c++ class [std::stack](https://en.cppreference.com/w/cpp/container/stack
 ## Header file and declaration
 
 ```c
-#define i_tag       // defaults to i_val name
 #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_del       // destroy value func - defaults to empty destruct
 #define i_valraw    // convertion "raw" type - defaults to i_val
 #define i_valfrom   // convertion func i_valraw => i_val - defaults to plain copy
 #define i_valto     // convertion func i_val* => i_valraw - defaults to plain copy
-#define i_valdel    // destroy value func - defaults to empty destruct
+#define i_tag       // defaults to i_val name
 #include <stc/cstack.h>
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.
@@ -59,9 +59,10 @@ cstack_X_value_t        cstack_X_value_clone(cstack_X_value_t val);
 
 ## Example
 ```c
-#define i_tag i
 #define i_val int
+#define i_tag i
 #include <stc/cstack.h>
+
 #include <stdio.h>
 
 int main() {
diff --git a/docs/cvec_api.md b/docs/cvec_api.md
index ee02950f..549bce2a 100644
--- a/docs/cvec_api.md
+++ b/docs/cvec_api.md
@@ -12,13 +12,13 @@ See the c++ class [std::vector](https://en.cppreference.com/w/cpp/container/vect
 ## Header file and declaration
 
 ```c
-#define i_tag       // defaults to i_val name
 #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_del       // destroy value func - defaults to empty destruct
 #define i_valraw    // convertion "raw" type - defaults to i_val
 #define i_valfrom   // convertion func i_valraw => i_val - defaults to plain copy
 #define i_valto     // convertion func i_val* => i_valraw - defaults to plain copy
-#define i_valdel    // destroy value func - defaults to empty destruct
+#define i_tag       // defaults to i_val
 #include <stc/cvec.h>
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.
@@ -99,9 +99,10 @@ cvec_X_value_t      cvec_X_value_clone(cvec_X_value_t val);
 
 ## Examples
 ```c
-#define i_tag i
 #define i_val int
+#define i_tag i
 #include <stc/cvec.h>
+
 #include <stdio.h>
 
 int main()
@@ -192,12 +193,13 @@ User User_clone(User user) {
     return user;
 }
 
-// declare a memory managed, clonable vector of users:
-#define i_tag u
+// Declare a memory managed, clonable vector of users.
+// Note that cvec_u_emplace_back() will clone input:
 #define i_val User
 #define i_cmp User_compare
-#define i_valdel User_del
+#define i_del User_del
 #define i_valfrom User_clone
+#define i_tag u
 #include <stc/cvec.h>
 
 int main(void) {