Added docs/cptr_api.md

3 files changed, 103 insertions, 2 deletions

diff --git a/docs/clist_api.md b/docs/clist_api.md
index 4761384c..ecae5ba2 100644
--- a/docs/clist_api.md
+++ b/docs/clist_api.md
@@ -58,7 +58,6 @@ void                clist_X_del(clist_X* self);
 
 bool                clist_X_empty(clist_X list);
 size_t              clist_X_size(clist_X list);
-Value               clist_X_value_from_raw(RawValue val);
 
 clist_X_value_t*    clist_X_front(clist_X* self);
 clist_X_value_t*    clist_X_back(clist_X* self);
@@ -95,6 +94,8 @@ clist_X_iter_t      clist_X_begin(const clist_X* self);
 clist_X_iter_t      clist_X_end(const clist_X* self);
 void                clist_X_next(clist_X_iter_t* it);
 clist_X_value_t*    clist_X_itval(clist_X_iter_t it);
+
+Value               clist_X_value_from_raw(RawValue val);
 ```
 
 ## Example
diff --git a/docs/cptr_api.md b/docs/cptr_api.md
new file mode 100644
index 00000000..52518c3c
--- /dev/null
+++ b/docs/cptr_api.md
@@ -0,0 +1,99 @@
+# Container cptr: Shared Ptr
+
+This describes the API of the queue type **cptr**.
+
+ Declaration
+
+```c
+#define using_cptr(X, Value, valueDestroy=c_default_del,
+                             valueCompare=c_default_compare)
+
+#define using_csptr(X, Value, valueDestroy=c_default_del,
+                              valueCompare=c_default_compare)
+```
+The macro `using_cptr()` must be instantiated in the global scope. `X` is a type tag name and will
+affect the names of all cptr types and methods. E.g. declaring `using_cptr(my, cvec_my);`,
+`X` should be replaced by `my` in all of the following documentation.
+
+ Types
+
+| Type name           | Type definition                        | Used to represent...     |
+|:--------------------|:---------------------------------------|:-------------------------|
+| `cptr_X`            | Depends on underlying container type   | The cptr type            |
+| `cptr_X_value_t`    | "                                      | The cptr element type    |
+| `cptr_X_iter_t`     | "                                      | cptr iterator            |
+
+
+| Type name           | Type definition                        | Used to represent...     |
+|:--------------------|:---------------------------------------|:-------------------------|
+| `csptr_X`           | Depends on underlying container type   | The csptr type           |
+| `csptr_X_value_t`   | "                                      | The csptr element type   |
+| `csptr_X_iter_t`    | "                                      | csptr iterator           |
+
+
+Header file
+
+All cptr definitions and prototypes may be included in your C source file by including a single header file.
+
+```c
+#include "stc/cptr.h"
+```
+
+ Methods
+
+```c
+cptr_X              cptr_X_init(void);
+void                cptr_X_del(cptr_X* self);
+void                cptr_X_reset(cptr_X* self, cptr_X_value_t* ptr);
+
+int                 cptr_X_compare(cptr_X* x, cptr_X* y);
+```
+
+```c
+csptr_X             csptr_X_from(csptr_X_value_t* ptr);
+csptr_X             csptr_X_make(csptr_X_value_t val);
+csptr_X             csptr_X_share(csptr_X ptr);
+void                csptr_X_del(csptr_X* self);
+void                csptr_X_reset(csptr_X* self, csptr_X_value_t* p);
+
+int                 csptr_X_compare(csptr_X* x, csptr_X* y);
+int                 csptr_pointer_compare(cptr_X_value_t* x, cptr_X_value_t* y);
+```
+
+
+ Example
+```c
+#include <stc/cptr.h>
+#include <stc/cmap.h>
+#include <stc/cstr.h>
+#include <stdio.h>
+
+typedef struct { cstr_t name, last; } Person;
+
+Person* Person_from(Person* p, cstr_t name, cstr_t last) {
+    p->name = name, p->last = last;
+    return p;
+}
+void Person_del(Person* p) {
+    c_del(cstr, &p->name, &p->last);
+}
+
+using_csptr(ps, Person, Person_del, c_no_compare);
+using_cmap(ps, int, csptr_ps, csptr_ps_del);
+
+
+int main() {
+    cmap_ps map = cmap_inits;
+    c_forrange (i, 20)
+        c_try_emplace(&map, cmap_ps, (i * 7) % 10,
+                            csptr_ps_from(Person_from(c_new(Person), cstr_from_fmt("Name %d", (i * 7) % 10),
+                                                                     cstr_from_fmt("Last %d", (i * 9) % 10))));
+    c_foreach (i, cmap_ps, map)
+        printf(" %d: %s\n", i.val->first, i.val->second.get->name.str);
+    cmap_ps_del(&map);
+}
+```
+Output:
+```
+top: 81
+```
\ No newline at end of file
diff --git a/docs/cvec_api.md b/docs/cvec_api.md
index f1cd4b3f..fc3697ee 100644
--- a/docs/cvec_api.md
+++ b/docs/cvec_api.md
@@ -67,7 +67,6 @@ void                cvec_X_del(cvec_X* self);
 bool                cvec_X_empty(cvec_X vec);
 size_t              cvec_X_size(cvec_X vec);
 size_t              cvec_X_capacity(cvec_X vec);
-Value               cvec_X_value_from_raw(RawValue val);
 
 cvec_X_value_t*     cvec_X_at(cvec_X* self, size_t idx);
 cvec_X_value_t*     cvec_X_front(cvec_X* self);
@@ -105,6 +104,8 @@ cvec_X_iter_t       cvec_X_end(const cvec_X* self);
 void                cvec_X_next(cvec_X_iter_t* it);
 cvec_X_value_t*     cvec_X_itval(cvec_X_iter_t it);
 size_t              cvec_X_index(const cvec_X vec, cvec_X_iter_t it);
+
+Value               cvec_X_value_from_raw(RawValue val);
 ```
 
 ## Examples