- Removed deprecated carc_make and cbox_make (replaced by carc_from, cbox_from)

- Some improvements to template.h
- Many smaller improvements to examples and docs.

12 files changed, 107 insertions, 89 deletions

diff --git a/examples/arc_containers.c b/examples/arc_containers.c
index 6aa80dcf..356afaf5 100644
--- a/examples/arc_containers.c
+++ b/examples/arc_containers.c
@@ -9,14 +9,14 @@
 #include <stc/csmap.h>
 
 #define i_type Arc // (atomic) ref. counted type
-#define i_val Map
+#define i_val_bind Map
 #define i_valdrop(p) (printf("drop Arc:\n"), Map_drop(p))
 // no need for atomic ref. count in single thread:
 #define i_opt c_no_atomic
 #include <stc/carc.h>
 
 #define i_type Stack
-#define i_val_arcbox Arc // define i_val_bind for carc/cbox value (not i_val)
+#define i_val_arcbox Arc // define i_val_arcbox for carc/cbox value (not i_val)
 #include <stc/cstack.h>
 
 #define i_type List
@@ -30,18 +30,18 @@ int main()
     {
         // POPULATE stack with shared pointers to Maps:
         Map *map;
-        map = Stack_push(&stack, Arc_make(Map_init()))->get;
+        map = Stack_push(&stack, Arc_from(Map_init()))->get;
         Map_emplace(map, "Joey", 1990);
         Map_emplace(map, "Mary", 1995);
         Map_emplace(map, "Joanna", 1992);
 
-        map = Stack_push(&stack, Arc_make(Map_init()))->get;
+        map = Stack_push(&stack, Arc_from(Map_init()))->get;
         Map_emplace(map, "Rosanna", 2001);
         Map_emplace(map, "Brad", 1999);
         Map_emplace(map, "Jack", 1980);
 
         // POPULATE list:
-        map = List_push_back(&list, Arc_make(Map_init()))->get;
+        map = List_push_back(&list, Arc_from(Map_init()))->get;
         Map_emplace(map, "Steve", 1979);
         Map_emplace(map, "Rick", 1974);
         Map_emplace(map, "Tracy", 2003);
diff --git a/examples/arc_demo.c b/examples/arc_demo.c
index 345432b6..96e5dadd 100644
--- a/examples/arc_demo.c
+++ b/examples/arc_demo.c
@@ -13,7 +13,7 @@ void int_drop(int* x) {
 #define i_valdrop int_drop  // optional, just to display the elements destroyed
 #include <stc/carc.h>       // Arc
 
-#define i_key_arcbox Arc    // note: use i_key_bind instead of i_key for carc/cbox elements
+#define i_key_arcbox Arc    // note: use i_key_arcbox instead of i_key for carc/cbox elements
 #include <stc/csset.h>      // csset_Arc (like: std::set<std::shared_ptr<int>>)
 
 #define i_val_arcbox Arc    // note: as above.
@@ -26,7 +26,7 @@ int main()
     {
         const int years[] = {2021, 2012, 2022, 2015};
         c_forloop (i, c_arraylen(years))
-            cvec_Arc_push_back(&vec, Arc_make(years[i]));
+            cvec_Arc_push(&vec, Arc_from(years[i]));
 
         printf("vec:");
         c_foreach (i, cvec_Arc, vec) printf(" %d", *i.ref->get);
diff --git a/examples/arcvec_erase.c b/examples/arcvec_erase.c
index 63b646a3..6990c94a 100644
--- a/examples/arcvec_erase.c
+++ b/examples/arcvec_erase.c
@@ -5,9 +5,7 @@ void show_drop(int* x) { printf("drop: %d\n", *x); }
 #define i_type Arc
 #define i_val int
 #define i_valdrop show_drop
-// carc/cbox will use pointer address comparison of i_val
-// if no 'i_cmp' is defined, otherwise 'i_cmp' is used
-// to compare object values.
+#define i_cmp c_default_cmp // enable object comparisons (default ptr compare)
 #include <stc/carc.h>       // Shared pointer to int
 
 #define i_type Vec
@@ -29,9 +27,8 @@ int main()
         printf("vec before erase :");
         c_foreach (i, Vec, vec)
             printf(" %d", *i.ref->get);
-        puts("");
 
-        printf("erase vec.data[2]; or first matching value depending on compare.\n");
+        printf("\nerase vec.data[2]; or first matching value depending on compare.\n");
         Vec_iter it;
         it = Vec_find(&vec, *vec.data[2].get);
         if (it.ref != Vec_end(&vec).ref)
@@ -45,6 +42,11 @@ int main()
         printf("vec after erase  :");
         c_foreach (i, Vec, vec)
             printf(" %d", *i.ref->get);
+
+        Vec_sort(&vec);
+        printf("\nvec after sort   :");
+        c_foreach (i, Vec, vec)
+            printf(" %d", *i.ref->get);
         
         puts("\nDone");
     }
diff --git a/examples/box.c b/examples/box.c
index b12f1f71..b0f05530 100644
--- a/examples/box.c
+++ b/examples/box.c
@@ -3,7 +3,7 @@
 
 typedef struct { cstr name, last; } Person;
 
-Person Person_new(const char* name, const char* last) {
+Person Person_make(const char* name, const char* last) {
     return (Person){.name = cstr_from(name), .last = cstr_from(last)};
 }
 
@@ -33,24 +33,24 @@ void Person_drop(Person* p) {
 
 #define i_type Persons
 #define i_val_arcbox PBox // informs that PBox is a smart pointer.
-#include <stc/cvec.h>
+#include <stc/csset.h>
 
 int main()
 {
     c_auto (Persons, vec)
     c_auto (PBox, p, q)
     {
-        p = PBox_make(Person_new("Laura", "Palmer"));
+        p = PBox_from(Person_make("Laura", "Palmer"));
         q = PBox_clone(p);
         cstr_assign(&q.get->name, "Leland");
 
         printf("orig: %s %s\n", cstr_str(&p.get->name), cstr_str(&p.get->last));
         printf("copy: %s %s\n", cstr_str(&q.get->name), cstr_str(&q.get->last));
 
-        Persons_push(&vec, PBox_make(Person_new("Dale", "Cooper")));
-        Persons_push(&vec, PBox_make(Person_new("Audrey", "Home")));
+        Persons_emplace(&vec, Person_make("Dale", "Cooper"));
+        Persons_emplace(&vec, Person_make("Audrey", "Home"));
 
-        // NB! Clone p and q to the vector using emplace_back()
+        // NB! Clone/share p and q in the Persons container.
         Persons_push(&vec, PBox_clone(p));
         Persons_push(&vec, PBox_clone(q));
 
@@ -59,16 +59,10 @@ int main()
         puts("");
 
         // Look-up Audrey! Create a temporary Person for lookup.
-        c_with (Person a = Person_new("Audrey", "Home"), Person_drop(&a)) {
+        c_with (Person a = Person_make("Audrey", "Home"), Person_drop(&a)) {
             const PBox *v = Persons_get(&vec, a); // lookup
             if (v) printf("found: %s %s\n", cstr_str(&v->get->name), cstr_str(&v->get->last));
         }
         puts("");
-
-        // Alternative to use cbox (when not placed in container).
-        Person *she = c_new(Person, Person_new("Shelly", "Johnson"));
-        printf("%s %s\n", cstr_str(&she->name), cstr_str(&she->last));
-        c_delete(Person, she); // drop and free
-        puts("");
     }
 }
diff --git a/examples/csmap_find.c b/examples/csmap_find.c
index 9287a89b..98da589e 100644
--- a/examples/csmap_find.c
+++ b/examples/csmap_find.c
@@ -52,12 +52,12 @@ int main()
         print_collection_csmap_istr(&m1);
 
         typedef cvec_istr_value pair;
-        cvec_istr_push_back(&v, (pair){43, "Tc"});
-        cvec_istr_push_back(&v, (pair){41, "Nb"});
-        cvec_istr_push_back(&v, (pair){46, "Pd"});
-        cvec_istr_push_back(&v, (pair){42, "Mo"});
-        cvec_istr_push_back(&v, (pair){44, "Ru"});
-        cvec_istr_push_back(&v, (pair){44, "Ru"}); // attempt a duplicate
+        cvec_istr_push(&v, (pair){43, "Tc"});
+        cvec_istr_push(&v, (pair){41, "Nb"});
+        cvec_istr_push(&v, (pair){46, "Pd"});
+        cvec_istr_push(&v, (pair){42, "Mo"});
+        cvec_istr_push(&v, (pair){44, "Ru"});
+        cvec_istr_push(&v, (pair){44, "Ru"}); // attempt a duplicate
 
         puts("Inserting the following vector data into m1:");
         print_collection_cvec_istr(&v);
diff --git a/examples/csmap_insert.c b/examples/csmap_insert.c
index 4d4c3871..5b18d691 100644
--- a/examples/csmap_insert.c
+++ b/examples/csmap_insert.c
@@ -63,11 +63,11 @@ int main()
     c_auto (csmap_ii, m2)
     c_auto (cvec_ii, v) {
         typedef cvec_ii_value ipair;
-        cvec_ii_push_back(&v, (ipair){43, 294});
-        cvec_ii_push_back(&v, (ipair){41, 262});
-        cvec_ii_push_back(&v, (ipair){45, 330});
-        cvec_ii_push_back(&v, (ipair){42, 277});
-        cvec_ii_push_back(&v, (ipair){44, 311});
+        cvec_ii_push(&v, (ipair){43, 294});
+        cvec_ii_push(&v, (ipair){41, 262});
+        cvec_ii_push(&v, (ipair){45, 330});
+        cvec_ii_push(&v, (ipair){42, 277});
+        cvec_ii_push(&v, (ipair){44, 311});
 
         puts("Inserting the following vector data into m2:");
         c_foreach (e, cvec_ii, v)
diff --git a/examples/demos.c b/examples/demos.c
index 3f0125fd..d15e5c6e 100644
--- a/examples/demos.c
+++ b/examples/demos.c
@@ -39,12 +39,12 @@ void vectordemo1()
     {
         cvec_ix_reserve(&bignums, 100);
         for (size_t i = 10; i <= 100; i += 10)
-            cvec_ix_push_back(&bignums, i * i);
+            cvec_ix_push(&bignums, i * i);
 
         printf("erase - %d: %" c_zu "\n", 3, bignums.data[3]);
         cvec_ix_erase_n(&bignums, 3, 1); // erase index 3
 
-        cvec_ix_pop_back(&bignums);      // erase the last
+        cvec_ix_pop(&bignums);           // erase the last
         cvec_ix_erase_n(&bignums, 0, 1); // erase the first
 
         for (size_t i = 0; i < cvec_ix_size(&bignums); ++i) {
diff --git a/examples/gauss1.c b/examples/gauss1.c
index 81d57852..65a6cc07 100644
--- a/examples/gauss1.c
+++ b/examples/gauss1.c
@@ -11,7 +11,7 @@
 #include <stc/cmap.h>
 
 // Declare int vector with entries from the cmap.
-#define i_val cmap_ii_raw
+#define i_val cmap_ii_value
 #define i_less(x, y) x->first < y->first
 #define i_tag ii
 #include <stc/cvec.h>
@@ -39,7 +39,7 @@ int main()
 
         // Transfer map to vec and sort it by map keys.
         c_foreach (i, cmap_ii, histmap)
-            cvec_ii_push_back(&histvec, (cmap_ii_raw){i.ref->first, i.ref->second});
+            cvec_ii_push(&histvec, (cmap_ii_value){i.ref->first, i.ref->second});
 
         cvec_ii_sort(&histvec);
 
diff --git a/examples/new_sptr.c b/examples/new_sptr.c
index e3431d8a..1c0ea89b 100644
--- a/examples/new_sptr.c
+++ b/examples/new_sptr.c
@@ -1,10 +1,41 @@
 #include <stc/cstr.h>
 
-struct Person { cstr name, last; } typedef Person;
+typedef struct { cstr name, last; } Person;
+Person Person_make(const char* name, const char* last);
+Person Person_clone(Person p);
+void Person_drop(Person* p);
+int Person_cmp(const Person* a, const Person* b);
+uint64_t Person_hash(const Person* p);
 
-Person Person_from(const char* name, const char* last) {
+#define i_type PersonArc
+#define i_val_bind Person // "class" ensure Person_drop will be called
+#define i_cmp Person_cmp   // enable carc object comparisons (not ptr to obj)
+#define i_hash Person_hash // enable carc object hash (not ptr to obj)
+#include <stc/carc.h>
+
+#define i_type IPtr
+#define i_val int
+#define i_valdrop(x) printf("drop: %d\n", *x)
+#include <stc/carc.h>
+
+#define i_type IPStack
+#define i_val_arcbox IPtr
+#include <stc/cstack.h>
+
+#define i_type PASet
+#define i_val_arcbox PersonArc
+#include <stc/cset.h>
+
+
+Person Person_make(const char* name, const char* last) {
     return (Person){.name = cstr_from(name), .last = cstr_from(last)};
 }
+int Person_cmp(const Person* a, const Person* b) {
+    return cstr_cmp(&a->name, &b->name);
+}
+uint64_t Person_hash(const Person* p) {
+    return cstr_hash(&p->name);
+}
 Person Person_clone(Person p) {
     p.name = cstr_clone(p.name), p.last = cstr_clone(p.last);
     return p;
@@ -14,41 +45,28 @@ void Person_drop(Person* p) {
     c_drop(cstr, &p->name, &p->last);
 }
 
-#define i_val_bind Person
-#define i_tag person
-#include <stc/carc.h>
-
-// ...
-#define i_type SPtr
-#define i_val int
-#define i_valdrop(x) printf("drop: %d\n", *x)
-#include <stc/carc.h>
-
-#define i_val_arcbox SPtr
-#define i_tag iptr
-#include <stc/cstack.h>
 
 int main(void) {
-    c_auto (carc_person, p, q, r, s)
+    c_auto (PersonArc, p, q, r, s)
     {
         puts("Ex1");
-        p = carc_person_from(Person_from("John", "Smiths"));
-        q = carc_person_clone(p);
-        r = carc_person_clone(p);
-        s = carc_person_from(Person_clone(*p.get)); // deep copy
-        printf("%s %s. uses: %lu\n", cstr_str(&r.get->name), cstr_str(&s.get->last), *p.use_count);
+        p = PersonArc_from(Person_make("John", "Smiths"));
+        q = PersonArc_clone(p); // share
+        r = PersonArc_clone(p);
+        s = PersonArc_from(Person_clone(*p.get)); // deep copy
+        printf("%s %s: refs %ld\n", cstr_str(&p.get->name), cstr_str(&p.get->last), *p.use_count);
     }
-
-    c_auto (cstack_iptr, stk) {
+    c_auto (IPStack, vec)
+    {
         puts("Ex2");
-        cstack_iptr_push(&stk, SPtr_from(10));
-        cstack_iptr_push(&stk, SPtr_from(20));
-        cstack_iptr_push(&stk, SPtr_from(30));
-        cstack_iptr_push(&stk, SPtr_clone(*cstack_iptr_top(&stk)));
-        cstack_iptr_push(&stk, SPtr_clone(*cstack_iptr_begin(&stk).ref));
-
-        c_foreach (i, cstack_iptr, stk)
-            printf(" (%d, uses %ld)", *i.ref->get, *i.ref->use_count);
+        IPStack_push(&vec, IPtr_from(10));
+        IPStack_push(&vec, IPtr_from(20));
+        IPStack_emplace(&vec, 30); // same as IPStack_push(&vec, IPtr_from(30));
+        IPStack_push(&vec, IPtr_clone(*IPStack_back(&vec)));
+        IPStack_push(&vec, IPtr_clone(*IPStack_front(&vec)));
+
+        c_foreach (i, IPStack, vec)
+            printf(" (%d: refs %ld)", *i.ref->get, *i.ref->use_count);
         puts("");
     }
 }
diff --git a/examples/new_vec.c b/examples/new_vec.c
index e0fa79ae..6e6be95a 100644
--- a/examples/new_vec.c
+++ b/examples/new_vec.c
@@ -21,7 +21,8 @@ int point_cmp(const Point* a, const Point* b) {
 }
 
 #define i_val Point
-#define i_cmp point_cmp
+//#define i_cmp point_cmp
+#define i_less(a, b) a->x < b->x || (a->x == b->x && a->y < b->y)
 #define i_opt c_is_fwd
 #define i_tag pnt
 #include <stc/cvec.h>
@@ -40,17 +41,18 @@ int main()
     c_auto (cvec_pnt, pvec)
     c_auto (cvec_str, svec)
     {
-        cvec_i32_push_back(&vec, 123);
-        cvec_float_push_back(&fvec, 123.3f);
+        cvec_i32_push(&vec, 123);
+        cvec_float_push(&fvec, 123.3f);
 
-        cvec_pnt_push_back(&pvec, (Point){42, 14});
-        cvec_pnt_push_back(&pvec, (Point){32, 94});
-        cvec_pnt_push_back(&pvec, (Point){62, 81});
+        cvec_pnt_push(&pvec, (Point){42, 14});
+        cvec_pnt_push(&pvec, (Point){32, 94});
+        cvec_pnt_push(&pvec, (Point){62, 81});
+        cvec_pnt_push(&pvec, (Point){32, 91});
         cvec_pnt_sort(&pvec);
         c_foreach (i, cvec_pnt, pvec)
             printf(" (%d %d)", i.ref->x, i.ref->y);
         puts("");
 
-        cvec_str_emplace_back(&svec, "Hello, friend");
+        cvec_str_emplace(&svec, "Hello, friend");
     }
 }
diff --git a/examples/person_arc.c b/examples/person_arc.c
index cd8d1f87..203d362a 100644
--- a/examples/person_arc.c
+++ b/examples/person_arc.c
@@ -3,7 +3,7 @@
 
 typedef struct { cstr name, last; } Person;
 
-Person Person_new(const char* name, const char* last) {
+Person Person_make(const char* name, const char* last) {
     return (Person){.name = cstr_from(name), .last = cstr_from(last)};
 }
 
@@ -28,11 +28,12 @@ void Person_drop(Person* p) {
 }
 
 #define i_type PSPtr
-#define i_val_bind Person // binds Person_cmp, ...
+#define i_val_bind Person // ensure Person_drop
+#define i_cmp Person_cmp   // specify object cmp, instead of ptr cmp for arc.
 #include <stc/carc.h>
 
 #define i_type Persons
-#define i_val_arcbox PSPtr // binds PSPtr_cmp, ...
+#define i_val_arcbox PSPtr // binds PSPtr_cmp, PSPtr_drop...
 #include <stc/cvec.h>
 
 
@@ -41,32 +42,33 @@ int main()
     c_auto (Persons, vec)
     c_auto (PSPtr, p, q)
     {
-        p = PSPtr_make(Person_new("Laura", "Palmer"));
+        p = PSPtr_from(Person_make("Laura", "Palmer"));
 
         // We want a deep copy -- PSPtr_clone(p) only shares!
-        q = PSPtr_make(Person_clone(*p.get));
+        q = PSPtr_from(Person_clone(*p.get));
         cstr_assign(&q.get->name, "Leland");
 
         printf("orig: %s %s\n", cstr_str(&p.get->name), cstr_str(&p.get->last));
         printf("copy: %s %s\n", cstr_str(&q.get->name), cstr_str(&q.get->last));
 
-        Persons_push_back(&vec, PSPtr_make(Person_new("Dale", "Cooper")));
-        Persons_push_back(&vec, PSPtr_make(Person_new("Audrey", "Home")));
+        // Use Persons_emplace to implicitly call PSPtr_make on the argument.
+        // No need to do: Persons_push(&vec, PSPtr_make(Person_make("Audrey", "Home")));
+        Persons_emplace(&vec, Person_make("Audrey", "Home"));
+        Persons_emplace(&vec, Person_make("Dale", "Cooper"));
 
         // Clone/share p and q to the vector
         c_forlist (i, PSPtr, {p, q})
-            Persons_push_back(&vec, PSPtr_clone(*i.ref));
+            Persons_push(&vec, PSPtr_clone(*i.ref));
 
         c_foreach (i, Persons, vec)
             printf("%s %s\n", cstr_str(&i.ref->get->name), cstr_str(&i.ref->get->last));
         puts("");
 
         // Look-up Audrey!
-        c_with (Person a = Person_new("Audrey", "Home"), Person_drop(&a)) {
+        c_with (Person a = Person_make("Audrey", "Home"), Person_drop(&a)) {
             const PSPtr *v = Persons_get(&vec, a);
             if (v) printf("found: %s %s\n", cstr_str(&v->get->name), cstr_str(&v->get->last));
         }
-
         puts("");
     }
 }
diff --git a/examples/vikings.c b/examples/vikings.c
index f291a601..528c30bf 100644
--- a/examples/vikings.c
+++ b/examples/vikings.c
@@ -40,7 +40,7 @@ static inline RViking Viking_toraw(const Viking* vp) {
 #define i_val       int         // mapped type
 #include <stc/cmap.h>
 /*
- i_key_bind set up these defines, unless they are already defined:
+ i_key_bind implies these defines, unless they are already defined:
    i_cmp        => RViking_cmp
    //i_hash     => RViking_hash     // already defined.
    //i_keyclone => Viking_clone     // not used, because of c_no_clone