Merge branch 'stclib:master' into modifiedHEADmodified

1 files changed, 32 insertions, 25 deletions

diff --git a/docs/carc_api.md b/docs/carc_api.md
index 48b64ff0..3e394378 100644
--- a/docs/carc_api.md
+++ b/docs/carc_api.md
@@ -6,29 +6,35 @@ deallocated when the last remaining **carc** owning the object is destroyed with
 
 The object is destroyed using *carc_X_drop()*. A **carc** may also own no objects, in which 
 case it is called empty. The *carc_X_cmp()*, *carc_X_drop()* methods are defined based on
-the `i_cmp` and `i_valdrop` macros specified. Use *carc_X_clone(p)* when sharing ownership of
+the `i_cmp` and `i_keydrop` macros specified. Use *carc_X_clone(p)* when sharing ownership of
 the pointed-to object. 
 
 All **carc** functions can be called by multiple threads on different instances of **carc** without
 additional synchronization even if these instances are copies and share ownership of the same object.
 **carc** uses thread-safe atomic reference counting, through the *carc_X_clone()* and *carc_X_drop()* methods.
 
-When declaring a container with shared pointers, define `i_valboxed` with the carc type, see example.
+When declaring a container with shared pointers, define `i_keyboxed` with the carc type, see example.
 
 See similar c++ class [std::shared_ptr](https://en.cppreference.com/w/cpp/memory/shared_ptr) for a functional reference, or Rust [std::sync::Arc](https://doc.rust-lang.org/std/sync/struct.Arc.html) / [std::rc::Rc](https://doc.rust-lang.org/std/rc/struct.Rc.html).
 
 ## Header file and declaration
 
 ```c
-#define i_type            // full typename of the carc
-#define i_val             // value: REQUIRED
-
-#define i_valraw          // convertion "raw" type - defaults to i_val
-#define i_valto           // convertion func i_val* => i_valraw: REQUIRED IF i_valraw defined.
-#define i_valfrom         // convertion func i_valraw => i_val
-      
-#define i_opt c_no_atomic // Non-atomic reference counting, like Rust Rc.
-#define i_tag             // alternative typename: carc_{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>         // carc container type name
+#define i_cmp <f>          // three-way compareison. REQUIRED IF i_key is a non-integral type
+                           // Note that containers of carcs will "inherit" i_cmp
+                           // when using carc in containers with i_valboxed MyArc - ie. the i_type.
+#define i_use_cmp          // define instead of i_cmp only when i_key is an integral/native-type.
+#define i_keydrop <f>      // destroy element func - defaults to empty destruct
+#define i_keyclone <f>     // REQUIRED if i_keydrop is defined, unless 'i_opt c_no_clone' is defined.
+
+#define i_keyraw <t>       // convertion type (lookup): default to {i_key}
+#define i_keyto <f>        // convertion func i_key* => i_keyraw: REQUIRED IF i_keyraw defined.
+#define i_keyfrom <f>      // from-raw func.
+
+#define i_opt c_no_atomic  // Non-atomic reference counting, like Rust Rc.
+#define i_tag <s>          // alternative typename: carc_{i_tag}. i_tag defaults to i_key
 #include <stc/carc.h>
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.
@@ -36,9 +42,9 @@ See similar c++ class [std::shared_ptr](https://en.cppreference.com/w/cpp/memory
 ## Methods
 ```c
 carc_X      carc_X_init();                                     // empty shared pointer
-carc_X      carc_X_from(i_valraw raw);                         // create an carc from raw type (available if i_valraw defined by user).
-carc_X      carc_X_from_ptr(i_val* p);                         // create an carc from raw pointer. Takes ownership of p.
-carc_X      carc_X_make(i_val val);                            // create an carc from constructed val object. Faster than from_ptr().
+carc_X      carc_X_from(i_keyraw raw);                         // create an carc from raw type (available if i_keyraw defined by user).
+carc_X      carc_X_from_ptr(i_key* p);                         // create an carc from raw pointer. Takes ownership of p.
+carc_X      carc_X_make(i_key key);                            // create an carc from constructed key object. Faster than from_ptr().
 
 carc_X      carc_X_clone(carc_X other);                        // return other with increased use count
 carc_X      carc_X_move(carc_X* self);                         // transfer ownership to receiver; self becomes NULL
@@ -49,7 +55,7 @@ void        carc_X_drop(carc_X* self);                         // destruct (decr
 long        carc_X_use_count(const carc_X* self);    
 
 void        carc_X_reset(carc_X* self);    
-void        carc_X_reset_to(carc_X* self, i_val* p);           // assign new carc from ptr. Takes ownership of p.
+void        carc_X_reset_to(carc_X* self, i_key* p);           // assign new carc from ptr. Takes ownership of p.
 
 uint64_t    carc_X_hash(const carc_X* x);                      // hash value
 int         carc_X_cmp(const carc_X* x, const carc_X* y);      // compares pointer addresses if no `i_cmp` is specified.
@@ -58,19 +64,19 @@ bool        carc_X_eq(const carc_X* x, const carc_X* y);       // carc_X_cmp() =
 
 // functions on pointed to objects.
 
-uint64_t    carc_X_value_hash(const i_val* x);
-int         carc_X_value_cmp(const i_val* x, const i_val* y);
-bool        carc_X_value_eq(const i_val* x, const i_val* y);
+uint64_t    carc_X_value_hash(const i_key* x);
+int         carc_X_value_cmp(const i_key* x, const i_key* y);
+bool        carc_X_value_eq(const i_key* x, const i_key* y);
 ```
 
 ## Types and constants
 
 | Type name         | Type definition                                   | Used to represent...   |
 |:------------------|:--------------------------------------------------|:-----------------------|
-| `carc_NULL`       | `{NULL, NULL}`                                    | Init nullptr const     |
+| `carc_null`       | `{0}`                                             | Init nullptr const     |
 | `carc_X`          | `struct { carc_X_value* get; long* use_count; }`  | The carc type          |
-| `carc_X_value`    | `i_val`                                           | The carc element type  |
-| `carc_X_raw`      | `i_valraw`                                        | Convertion type        |
+| `carc_X_value`    | `i_key`                                           | The carc element type  |
+| `carc_X_raw`      | `i_keyraw`                                        | Convertion type        |
 
 ## Example
 
@@ -78,6 +84,7 @@ bool        carc_X_value_eq(const i_val* x, const i_val* y);
 // Create two stacks with carcs to maps.
 // Demonstrate sharing and cloning of maps.
 // Show elements dropped.
+#define i_implement
 #include <stc/cstr.h>
 
 #define i_type Map
@@ -88,15 +95,15 @@ bool        carc_X_value_eq(const i_val* x, const i_val* y);
 #include <stc/csmap.h>
 
 #define i_type Arc // (atomic) ref. counted pointer
-#define i_val Map
-#define i_valdrop(p) (printf("drop Arc:\n"), Map_drop(p))
+#define i_key Map
+#define i_keydrop(p) (printf("drop Arc:\n"), Map_drop(p))
 #include <stc/carc.h>
 
 #define i_type Stack
-#define i_valboxed Arc // Note: use i_valboxed for carc or cbox value types
+#define i_keyboxed Arc // Note: use i_keyboxed for carc or cbox value types
 #include <stc/cstack.h>
 
-int main()
+int main(void)
 {
     Stack s1 = {0}, s2 = {0};
     Map *map;