Removed the cptr raw pointer. Only keep csptr: shared_ptr. Renamed cptr.h to csptr.h.

1 files changed, 190 insertions, 0 deletions

diff --git a/docs/csptr_api.md b/docs/csptr_api.md
new file mode 100644
index 00000000..9669d97b
--- /dev/null
+++ b/docs/csptr_api.md
@@ -0,0 +1,190 @@
+# STC [csptr](../stc/csptr.h): Shared Pointers
+
+**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 either of the following happens:
+
+- the last remaining **csptr** owning the object is destroyed with *csptr_X_del()*;
+- the last remaining **csptr** owning the object is assigned another pointer via *csptr_X_clone()*, *csptr_X_move()* or by *csptr_X_reset()*.
+
+The object is destroyed using *csptr_X_del()* or a custom deleter that is supplied to **csptr**
+in the using-statement.
+
+A **csptr** may also own no objects, in which case it is called empty.
+
+All **csptr** functions can be called by multiple threads on different instances of **csptr** 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_del()* methods.
+
+See the c++ classes [std::shared_ptr](https://en.cppreference.com/w/cpp/memory/shared_ptr) for a functional reference.
+
+## Header file and declaration
+
+```c
+#include <stc/csptr.h>
+
+using_csptr(X, Value);
+using_csptr(X, Value, valueCompare);
+using_csptr(X, Value, valueCompare, valueDel);
+```
+The macro `using_csptr()` must be instantiated in the global scope. `X` is a type tag name and will affect the names of all csptr types and methods. E.g. declaring `using_csptr(v4, Vec4)`, `X` should be replaced by `v4` 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.
+
+```c
+csptr_X             csptr_X_from(csptr_X_value_t* ptr);     // constructor
+csptr_X             csptr_X_make(csptr_X_value_t val);      // make_shared
+void                csptr_X_reset(csptr_X* self);
+void                csptr_X_reset_to(csptr_X* self, csptr_X_value_t* ptr);
+
+csptr_X             csptr_X_clone(csptr_X sptr);            // share the pointer (increase use count)
+void                csptr_X_move(csptr_X* self);            // transfer ownership instead of sharing. 
+void                csptr_X_del(csptr_X* self);             // destructor: decrease use count, destroy at 0
+
+int                 csptr_X_compare(csptr_X* x, csptr_X* y);
+bool                csptr_X_equals(csptr_X* x, csptr_X* y);
+```
+
+## Types
+
+| Type name           | Type definition                                               | Used to represent...     |
+|:--------------------|:--------------------------------------------------------------|:-------------------------|
+| `csptr_X`           | `struct { csptr_X_value_t* get; atomic_count_t* use_count; }` | The csptr type           |
+| `csptr_X_value_t`   | `Value`                                                       | The csptr element type   |
+| `atomic_count_t`    | `long`                                                        | The reference counter    |
+
+## Example
+
+```c
+#include <stc/csptr.h>
+#include <stc/cstr.h>
+
+typedef struct { cstr name, last; } Person;
+
+Person* Person_make(Person* p, const char* name, const char* last) {
+    p->name = cstr_from(name), p->last = cstr_from(last);
+    return p;
+}
+void Person_del(Person* p) {
+    printf("Destroy: %s %s\n", p->name.str, p->last.str);
+    c_del(cstr, &p->name, &p->last);
+}
+
+using_csptr(pe, Person, c_no_compare, Person_del);
+
+int main() {
+    csptr_pe p = csptr_pe_from(Person_make(c_new(Person), "John", "Smiths"));
+    csptr_pe q = csptr_pe_clone(p); // means: share the pointer
+    
+    printf("Person: %s %s. uses: %zu\n", p.get->name.str, p.get->last.str, *p.use_count);
+    csptr_pe_del(&p);
+
+    printf("Last man standing: %s %s. uses: %zu\n", q.get->name.str, q.get->last.str, *q.use_count);
+    csptr_pe_del(&q);
+}
+```
+Output:
+```
+Person: John Smiths. uses: 2
+Last man standing: John Smiths. uses: 1
+Destroy: John Smiths
+```
+
+### Example 2
+
+Advanced: Two different ways to store Person in vectors: 1) `cvec<Person>`, 2) `cvec< csptr<Person> >`.
+```c
+#include <stc/csptr.h>
+#include <stc/cstr.h>
+#include <stc/cvec.h>
+
+typedef struct { cstr name, last; } Person;
+
+Person* Person_make(Person* p, const char* name, const char* last) {
+    p->name = cstr_from(name), p->last = cstr_from(last);
+    return p;
+}
+int Person_compare(const Person* p, const Person* q) {
+    int cmp = strcmp(p->name.str, q->name.str);
+    return cmp == 0 ? strcmp(p->last.str, q->last.str) : cmp;
+}
+void Person_del(Person* p) {
+    printf("del: %s\n", p->name.str);
+    c_del(cstr, &p->name, &p->last);
+}
+
+// 1. cvec of Person struct; emplace and cloning disabled.
+using_cvec(pe, Person, Person_compare, Person_del, c_no_clone);
+
+// 2. cvec of shared-ptr to Person - with emplace_back() and cloning cvec ENABLED.
+using_csptr(pe, Person, Person_compare, Person_del);
+using_cvec(ps, csptr_pe, csptr_pe_compare, csptr_pe_del, csptr_pe_clone);
+
+const char* names[] = {
+    "Joe", "Jordan",
+    "Annie", "Aniston",
+    "Jane", "Jacobs"
+};
+
+int main() {
+    cvec_pe vec1 = cvec_pe_init();
+    cvec_ps vec2 = cvec_ps_init();
+
+    for (int i = 0; i < 6; i += 2) {
+        Person tmp;
+        cvec_pe_push_back(&vec1, *Person_make(&tmp, names[i], names[i+1]));
+        cvec_ps_push_back(&vec2, csptr_pe_from(Person_make(c_new(Person), names[i], names[i+1])));
+    }
+    puts("1. Sorted vec1 of Person:");
+    cvec_pe_sort(&vec1);
+    c_foreach (i, cvec_pe, vec1)
+        printf("  %s %s\n", i.ref->name.str, i.ref->last.str);
+
+    // Append a shared copy of vec2.data[0]. Will only be destructed once!
+    cvec_ps_emplace_back(&vec2, vec2.data[0]);   // emplace will internally call csptr_ps_clone()!
+    puts("\n2. Sorted vec2 of shared-pointer to Person:");
+    cvec_ps_sort(&vec2);
+    c_foreach (i, cvec_ps, vec2)
+        printf("  %s %s\n", i.ref->get->name.str, i.ref->get->last.str);
+
+    // Share vec2.data[1] with elem1 variable.
+    csptr_pe elem1 = csptr_pe_clone(vec2.data[1]);
+
+    puts("\nDestroy vec1:");
+    cvec_pe_del(&vec1);
+    puts("\nDestroy vec2:");
+    cvec_ps_del(&vec2);
+
+    puts("\nDestroy elem1:");
+    csptr_pe_del(&elem1);
+}
+```
+Output:
+```
+1. Sorted vec1 of Person:
+  Annie Aniston
+  Jane Jacobs
+  Joe Jordan
+
+2. Sorted vec2 of shared-pointer to Person:
+  Annie Aniston
+  Jane Jacobs
+  Joe Jordan
+  Joe Jordan
+
+Destroy vec1:
+del: Annie
+del: Jane
+del: Joe
+
+Destroy vec2:
+del: Annie
+del: Joe
+
+Destroy elem1:
+del: Jane
+```