Renamed csptr to carc. i_key/val_ref renamed to i_key/val_sptr. Change inspired by Rust Arc/Rc. cbox name is taken from Rust Box type.

2 files changed, 54 insertions, 52 deletions

diff --git a/docs/cbox_api.md b/docs/cbox_api.md
index 011beea2..e05e69f0 100644
--- a/docs/cbox_api.md
+++ b/docs/cbox_api.md
@@ -1,4 +1,4 @@
-# STC [cbox](../include/stc/cbox.h): (Boxed) Heap Allocated Objects
+# STC [cbox](../include/stc/cbox.h): Smart Pointer (Boxed object)
 
 **cbox** is a A box 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`
@@ -21,7 +21,7 @@ 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_drop          // destroy value func - defaults to empty destruct
-#define i_from         // create from raw/clone func - REQUIRED if i_drop is defined,
+#define i_from          // create from raw/clone func - REQUIRED if i_drop is defined,
                         // unless 'i_opt c_no_clone' is defined.
 #define i_tag           // type name tag, defaults to i_val
 #include <stc/cbox.h>    
@@ -76,7 +76,7 @@ void int_drop(int* x) {
 // both for the cbox type and the container of cbox elements. It will also 
 // disable emplace container functions.
 //
-// This applies to all container types, except those with csptr elements, as they
+// This applies to all container types, except those with carc elements, as they
 // define cloning internally.
 
 #define i_val int
@@ -84,11 +84,11 @@ void int_drop(int* x) {
 #define i_from c_default_clone
 #include <stc/cbox.h>         // cbox_int
 
-#define i_key_bind cbox_int   // note: use i_key_bind instead of i_key
+#define i_key_sptr cbox_int   // note: use i_key_sptr instead of i_key
 #define i_tag int             // tag otherwise defaults to 'ref'
 #include <stc/csset.h>        // csset_int (like: std::set<std::unique_ptr<int>>)
 
-#define i_val_bind cbox_int   // note: use i_val_bind instead of i_val
+#define i_val_sptr cbox_int   // note: use i_val_sptr instead of i_val
 #define i_tag int             // tag otherwise defaults to 'ref'
 #include <stc/cvec.h>         // cvec_int (like: std::vector<std::unique_ptr<int>>)
 
diff --git a/docs/csptr_api.md b/docs/csptr_api.md
index 95575417..e33bf410 100644
--- a/docs/csptr_api.md
+++ b/docs/csptr_api.md
@@ -1,23 +1,24 @@
-# STC [csptr](../include/stc/csptr.h): Atomic Reference Counted
+# STC [carc](../include/stc/carc.h): Atomic Reference Counted Smart Pointer
 
-**csptr** is a smart pointer that retains shared ownership of an object through a pointer.
-Several **csptr** objects may own the same object. The object is destroyed and its memory
-deallocated when the last remaining **csptr** owning the object is destroyed with *csptr_X_drop()*;
+**carc** is a smart pointer that retains shared ownership of an object through a pointer.
+Several **carc** objects may own the same object. The object is destroyed and its memory
+deallocated when the last remaining **carc** owning the object is destroyed with *carc_X_drop()*;
 
-The object is destroyed using *csptr_X_drop()*. A **csptr** may also own no objects, in which 
-case it is called empty. The *csptr_X_cmp()*, *csptr_X_drop()* methods are defined based on
-the `i_cmp` and `i_valdrop` macros specified. Use *csptr_X_clone(p)* when sharing ownership of
+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 pointed-to object. 
 
-All **csptr** functions can be called by multiple threads on different instances of **csptr** without
+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.
-**csptr** uses thread-safe atomic reference counting, through the *csptr_X_clone()* and *csptr_X_drop()* methods.
+**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_val_bind` as the csptr type, see example.
+When declaring a container with shared pointers, define `i_val_bind` as the carc type, see example.
 
-For containers, make sure to pass the result of create functions *csptr_X_new()* **only** to *insert()*,
-*push_back()*, and *push()* functions. Use *emplace()* method for sharing existing **csptr**s between
-containers or other existing shared pointers, as they internally clone/share the input.
+Make sure to pass the result of create functions like *carc_X_from()* **only** to *insert()*,
+*push_back()*, and *push()* functions, as it is *moved* into the container. Use *emplace()* 
+method for sharing existing **carc**s between containers or other existing shared pointers,
+as they clone/share the input internally.
 
 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).
 
@@ -29,41 +30,42 @@ See similar c++ class [std::shared_ptr](https://en.cppreference.com/w/cpp/memory
 #define i_drop            // destroy value func - defaults to empty destruct
 #define i_tag             // defaults to i_val
 #define i_opt c_no_atomic // Non-atomic reference counting, like Rust Rc.
-#include <stc/csptr.h>
+#include <stc/carc.h>
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.
 
 ## Methods
 ```c
-csptr_X     csptr_X_init();                                      // empty shared pointer
-csptr_X     csptr_X_new(i_valraw raw);                           // like csptr_X_from(), but construct owned value from raw.
-csptr_X     csptr_X_from(i_val val);                             // create new heap allocated object. Take ownership of val.
-csptr_X     csptr_X_from_ptr(i_val* p);                          // create a csptr from raw pointer. Takes ownership of p.
-    
-csptr_X     csptr_X_clone(csptr_X other);                        // return other with increased use count
-csptr_X     csptr_X_move(csptr_X* self);                         // transfer ownership to another csptr.
-void        csptr_X_take(csptr_X* self, csptr_X other);          // take ownership of other.
-void        csptr_X_copy(csptr_X* self, csptr_X other);          // copy shared (increase use count)
-    
-void        csptr_X_drop(csptr_X* self);                         // destruct (decrease use count, free at 0)
-long        csptr_X_use_count(csptr_X ptr);    
-    
-void        csptr_X_reset(csptr_X* self);    
-void        csptr_X_reset_from(csptr_X* self, i_val val);        // assign new csptr with value. Takes ownership of val.
-
-uint64_t    csptr_X_value_hash(const i_val* x, size_t n);        // hash value
-int         csptr_X_value_cmp(const i_val* x, const i_val* y);   // compares pointer addresses if 'i_opt c_no_cmp'
-                                                                 // is defined. Otherwise uses 'i_cmp' or default compare.
-bool        csptr_X_value_eq(const i_val* x, const i_val* y);    // cbox_X_value_cmp == 0
+carc_X      carc_X_init();                                     // empty shared pointer
+carc_X      carc_X_new(i_valraw raw);                          // like carc_X_from(), but construct owned value from raw.
+carc_X      carc_X_from(i_val val);                            // create new heap allocated object. Take ownership of val.
+carc_X      carc_X_from_ptr(i_val* p);                         // create a carc from raw pointer. Takes ownership of p.
+
+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 another carc.
+void        carc_X_take(carc_X* self, carc_X other);           // take ownership of other.
+void        carc_X_copy(carc_X* self, carc_X other);           // copy shared (increase use count)
+
+void        carc_X_drop(carc_X* self);                         // destruct (decrease use count, free at 0)
+long        carc_X_use_count(carc_X ptr);    
+
+void        carc_X_reset(carc_X* self);    
+void        carc_X_reset_from(carc_X* self, i_val val);        // assign new carc with value. Takes ownership of val.
+
+uint64_t    carc_X_value_hash(const i_val* x, size_t n);       // hash value
+int         carc_X_value_cmp(const i_val* x, const i_val* y);  // compares pointer addresses if 'i_opt c_no_cmp'
+                                                               // is defined. Otherwise uses 'i_cmp' or default compare.
+bool        carc_X_value_eq(const i_val* x, const i_val* y);   // cbox_X_value_cmp == 0
 ```
 
 ## Types and constants
 
-| Type name          | Type definition                                    | Used to represent...    |
-|:-------------------|:---------------------------------------------------|:------------------------|
-| `csptr_null`       | `{NULL, NULL}`                                     | Init nullptr const      |
-| `csptr_X`          | `struct { csptr_X_value* get; long* use_count; }`  | The csptr type          |
-| `csptr_X_value`    | `i_val`                                            | The csptr element type  |
+| Type name         | Type definition                                   | Used to represent...   |
+|:------------------|:--------------------------------------------------|:-----------------------|
+| `carc_null`       | `{NULL, NULL}`                                    | 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        |
 
 ## Example
 
@@ -83,14 +85,14 @@ bool        csptr_X_value_eq(const i_val* x, const i_val* y);    // cbox_X_value
 // no comparison of Maps needed (or available), and
 // no need for atomic ref. count in single thread:
 #define i_opt c_no_cmp|c_no_atomic 
-#include <stc/csptr.h>
+#include <stc/carc.h>
 
 #define i_type Stack
-#define i_val_bind Arc // define i_val_bind for csptr / cbox value, not i_val
+#define i_val_sptr Arc // define i_val_sptr for carc/cbox value, not i_val or i_val_bind
 #include <stc/cstack.h>
 
 #define i_type List
-#define i_val_bind Arc // as above
+#define i_val_sptr Arc // as above
 #include <stc/clist.h>
 
 int main()
@@ -100,28 +102,28 @@ int main()
     {
         // POPULATE the stack with shared pointers to Map:
         Map *map;
-        map = Stack_push(&stack, Arc_new(Map_init()))->get;
+        map = Stack_push(&stack, Arc_from(Map_init()))->get;
         c_apply(v, Map_emplace(map, c_pair(v)), Map_raw, {
             {"Joey", 1990}, {"Mary", 1995}, {"Joanna", 1992}
         });
-        map = Stack_push(&stack, Arc_new(Map_init()))->get;
+        map = Stack_push(&stack, Arc_from(Map_init()))->get;
         c_apply(v, Map_emplace(map, c_pair(v)), Map_raw, {
             {"Rosanna", 2001}, {"Brad", 1999}, {"Jack", 1980}
         });
 
         // POPULATE the list:
-        map = List_push_back(&list, Arc_new(Map_init()))->get;
+        map = List_push_back(&list, Arc_from(Map_init()))->get;
         c_apply(v, Map_emplace(map, c_pair(v)), Map_raw, {
             {"Steve", 1979}, {"Rick", 1974}, {"Tracy", 2003}
         });
         
-        // Share two Maps from the stack with the list using emplace (clones the csptr):
+        // Share two Maps from the stack with the list using emplace (clones the carc):
         List_emplace_back(&list, stack.data[0]);
         List_emplace_back(&list, stack.data[1]);
         
         // Clone (deep copy) a Map from the stack to the list
         // List will contain two shared and two unshared maps.
-        map = List_push_back(&list, Arc_new(Map_clone(*stack.data[1].get)))->get;
+        map = List_push_back(&list, Arc_from(Map_clone(*stack.data[1].get)))->get;
         
         // Add one more element to the cloned map:
         Map_emplace_or_assign(map, "CLONED", 2021);