Replaced the two csptr doc examples with a better one. Same as sharedptr.c in examples.

12 files changed, 60 insertions, 108 deletions

diff --git a/docs/carray_api.md b/docs/carray_api.md
index 71d27390..0a26f457 100644
--- a/docs/carray_api.md
+++ b/docs/carray_api.md
@@ -16,7 +16,7 @@ See the c++ class [boost::multi_array](https://www.boost.org/doc/libs/release/li
 
 #include <stc/carr2.h> // or <stc/carr3.h>
 ```
-`X` should be replaced by the value of i_tag in all of the following documentation.
+`X` should be replaced by the value of ***i_tag*** in all of the following documentation.
 
 ## Methods
 
diff --git a/docs/cdeq_api.md b/docs/cdeq_api.md
index 1ad754a1..8832b393 100644
--- a/docs/cdeq_api.md
+++ b/docs/cdeq_api.md
@@ -17,7 +17,7 @@ See the c++ class [std::deque](https://en.cppreference.com/w/cpp/container/deque
 #define i_valdel    // destroy value func - defaults to empty destruct
 #include <stc/cdeq.h>
 ```
-`X` should be replaced by the value of i_tag in all of the following documentation.
+`X` should be replaced by the value of ***i_tag*** in all of the following documentation.
 
 ## Methods
 
diff --git a/docs/clist_api.md b/docs/clist_api.md
index 3f866815..1eb92c12 100644
--- a/docs/clist_api.md
+++ b/docs/clist_api.md
@@ -32,7 +32,7 @@ See the c++ class [std::list](https://en.cppreference.com/w/cpp/container/list)
 #include <stc/clist.h>
 ```
 
-`X` should be replaced by the value of i_tag in all of the following documentation.
+`X` should be replaced by the value of ***i_tag*** in all of the following documentation.
 
 ## Methods
 
diff --git a/docs/cmap_api.md b/docs/cmap_api.md
index 3fcc8ff8..4fee41b7 100644
--- a/docs/cmap_api.md
+++ b/docs/cmap_api.md
@@ -32,7 +32,7 @@ See the c++ class [std::unordered_map](https://en.cppreference.com/w/cpp/contain
 #define i_valdel    // destroy value func - defaults to empty destruct
 #include <stc/cmap.h>
 ```
-`X` should be replaced by the value of i_tag in all of the following documentation.
+`X` should be replaced by the value of ***i_tag*** in all of the following documentation.
 
 ## Methods
 
diff --git a/docs/cpque_api.md b/docs/cpque_api.md
index 343215bf..3b3338e8 100644
--- a/docs/cpque_api.md
+++ b/docs/cpque_api.md
@@ -1,7 +1,7 @@
 # STC [cpque](../include/stc/cpque.h): Priority Queue
 
 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 argument `<`or `>` must be supplied to set the ordering, e.g. using `>` would cause the smallest element to appear as the top().
+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.
 
 See the c++ class [std::priority_queue](https://en.cppreference.com/w/cpp/container/priority_queue) for a functional reference.
 
@@ -17,7 +17,7 @@ See the c++ class [std::priority_queue](https://en.cppreference.com/w/cpp/contai
 #define i_valdel    // destroy value func - defaults to empty destruct
 #include <stc/cpque.h>
 ```
-`X` should be replaced by the value of i_tag in all of the following documentation.
+`X` should be replaced by the value of ***i_tag*** in all of the following documentation.
 
 ## Methods
 
diff --git a/docs/cqueue_api.md b/docs/cqueue_api.md
index 16e87d47..3484f5cd 100644
--- a/docs/cqueue_api.md
+++ b/docs/cqueue_api.md
@@ -16,7 +16,7 @@ See the c++ class [std::queue](https://en.cppreference.com/w/cpp/container/queue
 #define i_valdel    // destroy value func - defaults to empty destruct
 #include <stc/cqueue.h>
 ```
-`X` should be replaced by the value of i_tag in all of the following documentation.
+`X` should be replaced by the value of ***i_tag*** in all of the following documentation.
 
 
 ## Methods
diff --git a/docs/cset_api.md b/docs/cset_api.md
index 8b645d29..f9a5cfb7 100644
--- a/docs/cset_api.md
+++ b/docs/cset_api.md
@@ -18,7 +18,7 @@ A **cset** is an associative container that contains a set of unique objects of
 #define i_keydel    // destroy key func - defaults to empty destruct

 #include <stc/cset.h>

 ```

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

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

 

 ## Methods

 

diff --git a/docs/csmap_api.md b/docs/csmap_api.md
index 143da587..a9481bf1 100644
--- a/docs/csmap_api.md
+++ b/docs/csmap_api.md
@@ -29,7 +29,7 @@ See the c++ class [std::map](https://en.cppreference.com/w/cpp/container/map) fo
 #define i_valdel    // destroy value func - defaults to empty destruct
 #include <stc/csmap.h>
 ```
-`X` should be replaced by the value of i_tag in all of the following documentation.
+`X` should be replaced by the value of ***i_tag*** in all of the following documentation.
 
 ## Methods
 
diff --git a/docs/csptr_api.md b/docs/csptr_api.md
index afef2154..8a6881be 100644
--- a/docs/csptr_api.md
+++ b/docs/csptr_api.md
@@ -27,14 +27,13 @@ See the c++ classes [std::shared_ptr](https://en.cppreference.com/w/cpp/memory/s
 #define i_valdel    // destroy value func - defaults to empty destruct
 #include <stc/csptr.h>
 ```
-`X` should be replaced by the value of i_tag in all of the following documentation.
+`X` should be replaced by the value of ***i_tag*** in all of the following documentation.
 
 ## Methods
 
-Use *csptr_X_clone(p)* when sharing ownership of the pointed-to object. See examples below.
-
-The *csptr_X_compare()*, *csptr_X_equals()* and *csptr_X_del()* methods are defined based on the *valeCompare* and *valueDel* arguments passed to the **using**-macro.
+The *csptr_X_compare()*, *csptr_X_del()* methods are defined based on the ***i_cmp*** and ***i_valdel*** macros specified.
 
+Use *csptr_X_clone(p)* when sharing ownership of the pointed-to object. For shared pointers stored in containers, define ***i_val_csptr*** to the shared pointers tag instead of a ***i_val*** macro. See example below.
 ```c
 csptr_X             csptr_X_init();                               // empty constructor
 csptr_X             csptr_X_make(Value val);                      // make_shared constructor, fast
@@ -66,114 +65,67 @@ bool                csptr_X_equals(const csptr_X* x, const csptr_X* y);
 ## Example
 
 ```c
-#include <stc/cstr.h>
-
-typedef struct { cstr name, surname; } Person;
+#include <stdio.h>
 
-Person Person_init(const char* name, const char* surname) {
-    return (Person){.name = cstr_from(name), .surname = cstr_from(surname)};
-}
-void Person_del(Person* p) {
-    printf("Person_del: %s %s\n", p->name.str, p->surname.str);
-    c_del(cstr, &p->name, &p->surname);
+void int_del(int* x) {
+    printf("del: %d\n", *x);
 }
 
-#define i_val Person
-#define i_cmp c_no_compare
-#define i_valdel Person_del
-#include <stc/csptr.h>
-
-int main() {
-    csptr_person p = csptr_person_make(Person_init("John", "Smiths"));
-    csptr_person q = csptr_person_clone(p); // means: share the pointer
-
-    printf("Person: %s %s. uses: %zu\n", p.get->name.str, p.get->surname.str, *p.use_count);
-    csptr_person_del(&p);
+#define i_val int
+#define i_valdel int_del  // optional func to show elements destroyed
+#include <stc/csptr.h>    // define csptr_int shared pointers
 
-    printf("Last man standing: %s %s. uses: %zu\n", q.get->name.str, q.get->surname.str, *q.use_count);
-    csptr_person_del(&q);
-}
-```
-Output:
-```
-Person: John Smiths. uses: 2
-Last man standing: John Smiths. uses: 1
-Person_del: John Smiths
-```
+#define i_key_csptr int   // refer to csptr_int definition above
+#include <stc/csset.h>    // define a sorted set of csptr_int
 
-### Example 2
+#define i_val_csptr int
+#include <stc/cvec.h>
 
-Vector of shared pointers to Person:
-```c
-#include <stc/cstr.h>
+int main()
+{
+    c_forauto (cvec_int, vec)   // declare and init vec, call del at scope exit
+    c_forauto (csset_int, set)  // declare and init set, call del at scope exit
+    {
+        cvec_int_push_back(&vec, csptr_int_make(2021));
+        cvec_int_push_back(&vec, csptr_int_make(2012));
+        cvec_int_push_back(&vec, csptr_int_make(2022));
+        cvec_int_push_back(&vec, csptr_int_make(2015));
 
-typedef struct { cstr name, surname; } Person;
+        printf("vec:");
+        c_foreach (i, cvec_int, vec) printf(" %d", *i.ref->get);
+        puts("");
 
-Person Person_init(const char* name, const char* surname) {
-    return (Person){.name = cstr_from(name), .surname = cstr_from(surname)};
-}
-void Person_del(Person* p) {
-    printf("Person_del: %s %s\n", p->name.str, p->surname.str);
-    c_del(cstr, &p->name, &p->surname);
-}
-int Person_compare(const Person* p, const Person* q) {
-    int cmp = strcmp(p->surname.str, q->surname.str);
-    return cmp == 0 ? strcmp(p->name.str, q->name.str) : cmp;
-}
+        // add odd numbers from vec to set
+        c_foreach (i, cvec_int, vec)
+            if (*i.ref->get & 1)
+                csset_int_emplace(&set, *i.ref); // copy shared pointer => increments counter.
 
-#define i_tag pers
-#define i_val Person
-#define i_cmp Person_compare
-#define i_valdel Person_del
-#include <stc/csptr.h>
+        // erase the two last elements in vec
+        cvec_int_pop_back(&vec);
+        cvec_int_pop_back(&vec);
 
-#define i_val_csptr pers  // shorthand: derives other i_xxx defines from this. i_tag may be defined.
-#include <stc/cvec.h>
+        printf("vec:");
+        c_foreach (i, cvec_int, vec) printf(" %d", *i.ref->get);
 
-const char* names[] = {
-    "Joe", "Jordan",
-    "Annie", "Aniston",
-    "Jane", "Jacobs"
-};
+        printf("\nset:");
+        c_foreach (i, csset_int, set) printf(" %d", *i.ref->get);
 
-int main() {
-    cvec_pers vec = cvec_pers_init();
+        c_forvar (csptr_int p = csptr_int_clone(vec.data[0]), csptr_int_del(&p)) {
+            printf("\n%d is now owned by %zu objects\n", *p.get, *p.use_count);
+        }
 
-    for (int i = 0; i < c_arraylen(names); i += 2) {
-        cvec_pers_push_back(&vec, csptr_pers_make(Person_init(names[i], names[i+1])));
+        puts("\nDone");
     }
-
-    // Append a shared copy of vec.data[0]. Will only be destructed once!
-    cvec_pers_emplace_back(&vec, vec.data[0]);  // will internally call csptr_pers_clone()!
-    
-    puts("\nSorted vec of shared-pointer to Person:");
-    cvec_pers_sort(&vec);
-    
-    c_foreach (i, cvec_pers, vec)
-        printf("  %s, %s\n", i.ref->get->surname.str, i.ref->get->name.str);
-
-    // Share vec.data[1] with elem1 variable.
-    csptr_pers elem1 = csptr_pers_clone(vec.data[1]);
-
-    puts("\nDestroy vec:");
-    cvec_pers_del(&vec);
-
-    puts("\nDestroy elem1:");
-    csptr_pers_del(&elem1);
 }
 ```
 Output:
 ```
-Sorted vec of shared-pointer to Person:
-  Aniston, Annie
-  Jacobs, Jane
-  Jordan, Joe
-  Jordan, Joe
-
-Destroy vec:
-Person_del: Annie Aniston
-Person_del: Joe Jordan
-
-Destroy elem1:
-Person_del: Jane Jacobs
+vec: 2021 2012 2022 2015
+del: 2022
+vec: 2021 2012
+set: 2015 2021
+Done
+del: 2015
+del: 2021
+del: 2012
 ```
diff --git a/docs/csset_api.md b/docs/csset_api.md
index 0fdb8086..83774b37 100644
--- a/docs/csset_api.md
+++ b/docs/csset_api.md
@@ -17,7 +17,7 @@ See the c++ class [std::set](https://en.cppreference.com/w/cpp/container/set) fo
 #define i_keydel    // destroy key func - defaults to empty destruct

 #include <stc/csset.h>

 ```

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

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

 

 ## Methods

 

diff --git a/docs/cstack_api.md b/docs/cstack_api.md
index 68f22b57..8d9abbc5 100644
--- a/docs/cstack_api.md
+++ b/docs/cstack_api.md
@@ -17,7 +17,7 @@ See the c++ class [std::stack](https://en.cppreference.com/w/cpp/container/stack
 #define i_valdel    // destroy value func - defaults to empty destruct
 #include <stc/cstack.h>
 ```
-`X` should be replaced by the value of i_tag in all of the following documentation.
+`X` should be replaced by the value of ***i_tag*** in all of the following documentation.
 
 ## Methods
 
diff --git a/docs/cvec_api.md b/docs/cvec_api.md
index 07164e46..64a7df2c 100644
--- a/docs/cvec_api.md
+++ b/docs/cvec_api.md
@@ -21,7 +21,7 @@ See the c++ class [std::vector](https://en.cppreference.com/w/cpp/container/vect
 #define i_valdel    // destroy value func - defaults to empty destruct
 #include <stc/cvec.h>
 ```
-`X` should be replaced by the value of i_tag in all of the following documentation.
+`X` should be replaced by the value of ***i_tag*** in all of the following documentation.
 
 ## Methods