More doc fixes on i_keyclone, i_keyfrom and i_valclone, i_valfrom

12 files changed, 44 insertions, 41 deletions

diff --git a/README.md b/README.md
index 9770f8e4..e7bae5d0 100644
--- a/README.md
+++ b/README.md
@@ -130,7 +130,7 @@ In order to include two **cvec**s with different element types, include cvec.h t
 compare function is required to enable sorting and searching (`<` and `==` operators is default and works
 for integral types only). Alternatively, `#define i_opt c_no_cmp` to disable methods using comparison.
 
-Similarly, if a destructor `i_valdrop` is defined, either define a `i_valfrom` construct/clone function
+Similarly, if a destructor `i_valdrop` is defined, either define a `i_valclone` clone function
 or `#define i_opt c_no_clone` to disable cloning and emplace methods. Unless these requirements are met,
 compile errors are generated.
 ```c
@@ -299,17 +299,17 @@ Properties:
 
 Key:
 - `i_keydrop` - Destroy map/set key func - defaults to empty destructor.
+- `i_keyclone` - **[required if]** *i_valdrop* is defined (not required for **carc**). 
 - `i_keyraw`  - Convertion "raw" type - defaults to *i_key*.
 - `i_keyfrom` - Convertion func *i_key* <- *i_keyraw*. **[required if]** *i_keyraw* is defined, else works as ***clone***. 
 - `i_keyto`   - Convertion func *i_key*\* -> *i_keyraw*.
-- `i_keyclone` - Defaults to *i_keyfrom(i_keyto(&key))*, but is defined for smart pointers.
 
 Val:
 - `i_valdrop` - Destroy mapped or value func - defaults to empty destruct.
+- `i_valclone` - **[required if]** *i_valdrop* is defined. 
 - `i_valraw`  - Convertion "raw" type - defaults to *i_val*.
-- `i_valfrom` - Convertion func *i_val* <- *i_valraw*. **[required if]** *i_valdrop* is defined. Works as ***clone*** when *i_valraw* is not specified. 
+- `i_valfrom` - Convertion func *i_val* <- *i_valraw*.
 - `i_valto`   - Convertion func *i_val*\* -> *i_valraw*.
-- `i_valclone` - Defaults to *i_valfrom(i_valto(&val))*.
 
 Special:
 - `i_key_str` - Define key type *cstr* and container i_tag = *str*. It binds type convertion from/to *const char*\*, and the ***cmp***, ***eq***, ***hash***, and ***keydrop*** functions.
@@ -369,12 +369,8 @@ This is made possible because the type configuration may be given an optional
 conversion/"rawvalue"-type as template parameter, along with a back and forth conversion
 methods to the container value type.
 
-Hence, `i_val x = ..., y = i_valfrom(i_valto(&x))` works as a *clone* function, where the output of 
-`i_valto()` is type `i_valraw`. Function `i_valfrom()` is a *clone* function when `i_valraw/i_valto` is
-undefined (i_valraw defaults to `i_val`). Same for `i_key`.
-
-Rawvalues are also beneficial for **lookup** and **map insertions**. The **emplace** methods constructs
-`cstr`-objects from the rawvalues, but only when required:
+Rawvalues are primarily beneficial for **lookup** and **map insertions**, however the
+**emplace** methods constructs `cstr`-objects from the rawvalues, but only when required:
 ```c
 cmap_str_emplace(&map, "Hello", "world");
 // Two cstr-objects were constructed by emplace
diff --git a/docs/carray_api.md b/docs/carray_api.md
index 8c63f381..cab5cb4c 100644
--- a/docs/carray_api.md
+++ b/docs/carray_api.md
@@ -11,8 +11,7 @@ See the c++ class [boost::multi_array](https://www.boost.org/doc/libs/release/li
 ```c
 #define i_val       // value: REQUIRED
 #define i_valdrop   // 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_valclone  // REQUIRED IF valdrop is defined.
 #define i_tag       // defaults to i_val
 
 #include <stc/carr2.h> // or <stc/carr3.h>
diff --git a/docs/cbox_api.md b/docs/cbox_api.md
index 2b91a137..59c44e02 100644
--- a/docs/cbox_api.md
+++ b/docs/cbox_api.md
@@ -3,10 +3,10 @@
 **cbox** is a smart pointer to a heap allocated value of type X. A **cbox** can
 be empty. The *cbox_X_cmp()*, *cbox_X_drop()* methods are defined based on the `i_cmp`
 and `i_valdrop` macros specified. Use *cbox_X_clone(p)* to make a deep copy, which uses the
-`i_valfrom` macro if defined.
+`i_valclone` macro if defined.
 
 When declaring a container of **cbox** values, define `i_val_arcbox` with the
-cbox type instead of defining `i_val`. This will auto-set `i_valdrop`, `i_valfrom`, and `i_cmp` using 
+cbox type instead of defining `i_val`. This will auto-set `i_valdrop`, `i_valclone`, and `i_cmp` using 
 functions defined by the specified **cbox**.
 
 See similar c++ class [std::unique_ptr](https://en.cppreference.com/w/cpp/memory/unique_ptr) for a functional reference, or Rust [std::boxed::Box](https://doc.rust-lang.org/std/boxed/struct.Box.html)
@@ -17,9 +17,9 @@ See similar c++ class [std::unique_ptr](https://en.cppreference.com/w/cpp/memory
 #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_valdrop       // destroy value func - defaults to empty destruct
-#define i_valraw        // convertion type
-#define i_valfrom          // create from raw/clone func - REQUIRED if i_valdrop is defined,
-                        // unless 'i_opt c_no_clone' is defined.
+#define i_valclone      // REQUIRED if i_valdrop is defined, unless 'i_opt c_no_clone' is defined.
+#define i_valraw        // convertion type (lookup)
+#define i_valfrom       // from-raw func.
 #define i_valto         // to-raw func.
 #define i_tag           // type name tag, defaults to i_val
 #include <stc/cbox.h>    
@@ -68,7 +68,7 @@ void int_drop(int* x) {
 #define i_type IBox
 #define i_val int
 #define i_valdrop int_drop    // optional func, just to display elements destroyed
-#define i_valfrom(x) x        // must specify because i_valdrop was defined.
+#define i_valclone(x) x       // must specify because i_valdrop was defined.
 #include <stc/cbox.h>
 
 #define i_type ISet
diff --git a/docs/cdeq_api.md b/docs/cdeq_api.md
index fb24c8d3..4a416d09 100644
--- a/docs/cdeq_api.md
+++ b/docs/cdeq_api.md
@@ -11,9 +11,10 @@ See the c++ class [std::deque](https://en.cppreference.com/w/cpp/container/deque
 #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 - 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_valfrom   // convertion func i_valraw => i_val
+#define i_valto     // convertion func i_val* => i_valraw
 #define i_tag       // defaults to i_val
 #include <stc/cdeq.h>
 ```
diff --git a/docs/clist_api.md b/docs/clist_api.md
index c785fbe5..5dd5d524 100644
--- a/docs/clist_api.md
+++ b/docs/clist_api.md
@@ -25,9 +25,10 @@ See the c++ class [std::list](https://en.cppreference.com/w/cpp/container/list)
 #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 - defaults to i_val
-#define i_valto     // convertion func i_val* => i_valraw - defaults to plain copy
-#define i_valfrom   // convertion func i_valraw => i_val - defaults to plain copy
+#define i_valto     // convertion func i_val* => i_valraw
+#define i_valfrom   // convertion func i_valraw => i_val
 #define i_tag       // defaults to i_val
 #include <stc/clist.h>
 ```
diff --git a/docs/cmap_api.md b/docs/cmap_api.md
index 51607be2..67210b6e 100644
--- a/docs/cmap_api.md
+++ b/docs/cmap_api.md
@@ -23,14 +23,16 @@ See the c++ class [std::unordered_map](https://en.cppreference.com/w/cpp/contain
 #define i_eq        // equality comparison two i_keyraw*: REQUIRED IF i_keyraw is a
                     // non-integral type. Three-way i_cmp may be specified alternatively.
 #define i_keydrop   // destroy key func - defaults to empty destruct
+#define i_keyclone  // REQUIRED IF i_valdrop defined
 #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_keyfrom   // convertion func i_keyraw => i_key
+#define i_keyto     // convertion func i_key* => i_keyraw
 
 #define i_valdrop   // destroy value func - defaults to empty destruct
+#define i_valclone  // REQUIRED IF i_valdrop defined
 #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_valfrom   // convertion func i_valraw => i_val
+#define i_valto     // convertion func i_val* => i_valraw
 
 #define i_tag       // typename tag. defaults to i_key
 #define i_type      // full typename of the container
diff --git a/docs/cpque_api.md b/docs/cpque_api.md
index b4ad48a9..1842c1b6 100644
--- a/docs/cpque_api.md
+++ b/docs/cpque_api.md
@@ -3,8 +3,6 @@
 A priority queue is a container adaptor that provides constant time lookup of the largest (by default) element, at the expense of logarithmic insertion and extraction.
 A user-provided ***i_cmp*** may be defined to set the ordering, e.g. using ***-c_default_cmp*** would cause the smallest element to appear as the top() value.
 
-Note that **cpque** does not support `i_valraw` and `i_valto`, so only cloning via `i_valfrom` is available.
-
 See the c++ class [std::priority_queue](https://en.cppreference.com/w/cpp/container/priority_queue) for a functional reference.
 
 ## Header file and declaration
@@ -13,8 +11,9 @@ See the c++ class [std::priority_queue](https://en.cppreference.com/w/cpp/contai
 #define i_val       // value: REQUIRED
 #define i_cmp       // three-way compare two i_val* : REQUIRED IF i_val/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 type
-#define i_valfrom   // convertion func i_valraw => i_val - defaults to plain copy
+#define i_valfrom   // convertion func i_valraw => i_val
 #define i_valto     // convertion func i_val* => i_valraw.
 #define i_tag       // defaults to i_val
 #define i_type      // container type name
diff --git a/docs/cqueue_api.md b/docs/cqueue_api.md
index bff0b5ce..ffb75216 100644
--- a/docs/cqueue_api.md
+++ b/docs/cqueue_api.md
@@ -10,9 +10,10 @@ See the c++ class [std::queue](https://en.cppreference.com/w/cpp/container/queue
 #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 - 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_valfrom   // convertion func i_valraw => i_val
+#define i_valto     // convertion func i_val* => i_valraw
 #define i_tag       // defaults to i_val
 #include <stc/cqueue.h>
 ```
diff --git a/docs/csmap_api.md b/docs/csmap_api.md
index cdbccb40..e19d0637 100644
--- a/docs/csmap_api.md
+++ b/docs/csmap_api.md
@@ -20,14 +20,16 @@ See the c++ class [std::map](https://en.cppreference.com/w/cpp/container/map) fo
 #define i_cmp       // three-way compare two i_keyraw* : REQUIRED IF i_keyraw is a non-integral type
 
 #define i_keydrop   // destroy key func - defaults to empty destruct
+#define i_keyclone  // REQUIRED IF i_valdrop defined
 #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_keyfrom   // convertion func i_keyraw => i_key
+#define i_keyto     // convertion func i_key* => i_keyraw
 
 #define i_valdrop   // destroy value func - defaults to empty destruct
+#define i_valclone  // REQUIRED IF i_valdrop defined
 #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_valfrom   // convertion func i_valraw => i_val
+#define i_valto     // convertion func i_val* => i_valraw
 
 #define i_tag       // typename tag. defaults to i_key
 #define i_type      // full typename of the container
diff --git a/docs/cstack_api.md b/docs/cstack_api.md
index f5962344..b30957d1 100644
--- a/docs/cstack_api.md
+++ b/docs/cstack_api.md
@@ -11,9 +11,10 @@ See the c++ class [std::stack](https://en.cppreference.com/w/cpp/container/stack
 #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 - 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_valfrom   // convertion func i_valraw => i_val
+#define i_valto     // convertion func i_val* => i_valraw
 #define i_tag       // defaults to i_val name
 #include <stc/cstack.h>
 ```
diff --git a/docs/cvec_api.md b/docs/cvec_api.md
index 7d724680..d60ee5fe 100644
--- a/docs/cvec_api.md
+++ b/docs/cvec_api.md
@@ -15,9 +15,10 @@ See the c++ class [std::vector](https://en.cppreference.com/w/cpp/container/vect
 #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 - 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_valfrom   // convertion func i_valraw => i_val
+#define i_valto     // convertion func i_val* => i_valraw
 #define i_tag       // defaults to i_val
 #include <stc/cvec.h>
 ```
@@ -204,7 +205,7 @@ User User_clone(User user) {
 #define i_val User
 #define i_cmp User_cmp
 #define i_valdrop User_drop
-#define i_valfrom User_clone
+#define i_valclone User_clone
 #define i_tag u
 #include <stc/cvec.h>
 
diff --git a/examples/arc_demo.c b/examples/arc_demo.c
index 0ba5bf0a..daeb5a68 100644
--- a/examples/arc_demo.c
+++ b/examples/arc_demo.c
@@ -6,7 +6,7 @@ void int_drop(int* x) {
 }

 

 // carc implements its own clone method using reference counting,

-// so 'i_valfrom' need not be defined (will be ignored).

+// so 'i_valclone' is not required to be defined (ignored).

 

 #define i_type Arc          // set type name to be defined (instead of 'carc_int')

 #define i_val int