Added docs for cdeq.h

1 files changed, 150 insertions, 0 deletions

diff --git a/docs/cdeq_api.md b/docs/cdeq_api.md
new file mode 100644
index 00000000..db9051f9
--- /dev/null
+++ b/docs/cdeq_api.md
@@ -0,0 +1,150 @@
+# Container [cdeq](../stc/cdeq.h): Deque (Double Ended Queue)
+
+This describes the API of vector type **cdeq**.
+
+## Declaration
+
+```c
+#define using_cdeq(X, Value, valueDestroy=c_default_del,
+                             valueCompareRaw=c_default_compare,
+                             RawValue=Value,
+                             valueToRaw=c_default_to_raw,
+                             valueFromRaw=c_default_from_raw)
+#define using_cdeq_str()
+```
+The macro `using_cdeq()` can be instantiated with 2, 3, 4, or 7 arguments in the global scope.
+Defaults values are given above for args not specified. `X` is a type tag name and
+will affect the names of all cdeq types and methods. E.g. declaring `using_cdeq(my, int);`, `X` should
+be replaced by `my` in all of the following documentation.
+
+`using_cdeq_str()` is a shorthand, expands to:
+```
+using_cdeq(str, cstr_t, cstr_del, cstr_compare_raw, const char*, cstr_to_raw, cstr_from)
+```
+
+## Types
+
+| Type name            | Type definition                     | Used to represent...   |
+|:---------------------|:------------------------------------|:-----------------------|
+| `cdeq_X`             | `struct { cdeq_X_value_t* data; }`  | The cdeq type          |
+| `cdeq_X_value_t`     | `Value`                             | The cdeq value type    |
+| `cdeq_X_input_t`     | `cdeq_X_value_t`                    | The input type         |
+| `cdeq_X_rawvalue_t`  | `RawValue`                          | The raw value type     |
+| `cdeq_X_iter_t`      | `struct { cdeq_X_value_t* ref; }`   | The iterator type      |
+
+## Constants and macros
+
+| Name                       | Purpose              |
+|:---------------------------|:---------------------|
+|  `cdeq_inits`              | Initializer constant |
+|  `cdeq_empty(vec)`         | true if vec is empty |
+|  `cdeq_size(vec)`          | return vec length    |
+|  `cdeq_capacity(vec)`      | return vec capacity  |
+
+
+## Header file
+
+All cdeq definitions and prototypes may be included in your C source file by including a single header file.
+
+```c
+#include "stc/cdeq.h"
+```
+## Methods
+
+```c
+cdeq_X              cdeq_X_init(void);
+cdeq_X              cdeq_X_with_size(size_t size, Value fill);
+cdeq_X              cdeq_X_with_capacity(size_t size);
+cdeq_X              cdeq_X_clone(cdeq_X vec);
+
+void                cdeq_X_clear(cdeq_X* self);
+void                cdeq_X_shrink_to_fit(cdeq_X* self);
+void                cdeq_X_reserve(cdeq_X* self, size_t cap);
+void                cdeq_X_resize(cdeq_X* self, size_t size, Value fill);
+void                cdeq_X_swap(cdeq_X* a, cdeq_X* b);
+
+void                cdeq_X_del(cdeq_X* self);
+
+bool                cdeq_X_empty(cdeq_X vec);
+size_t              cdeq_X_size(cdeq_X vec);
+size_t              cdeq_X_capacity(cdeq_X vec);
+
+cdeq_X_value_t*     cdeq_X_at(cdeq_X* self, size_t idx);
+cdeq_X_value_t*     cdeq_X_front(cdeq_X* self);
+cdeq_X_value_t*     cdeq_X_back(cdeq_X* self);
+
+void                cdeq_X_push_n(cdeq_X *self, const cdeq_X_input_t arr[], size_t size);
+void                cdeq_X_push_front(cdeq_X* self, Value value);
+void                cdeq_X_push_back(cdeq_X* self, Value value);
+void                cdeq_X_emplace_front(cdeq_X* self, RawValue raw);
+void                cdeq_X_emplace_back(cdeq_X* self, RawValue raw);
+void                cdeq_X_pop_front(cdeq_X* self);
+void                cdeq_X_pop_back(cdeq_X* self);
+
+cdeq_X_iter_t       cdeq_X_emplace(cdeq_X* self, cdeq_X_iter_t pos, RawValue raw);
+cdeq_X_iter_t       cdeq_X_emplace_at(cdeq_X* self, size_t idx, RawValue raw);
+cdeq_X_iter_t       cdeq_X_insert(cdeq_X* self, cdeq_X_iter_t pos, Value value);
+cdeq_X_iter_t       cdeq_X_insert_at(cdeq_X* self, size_t idx, Value value);
+cdeq_X_iter_t       cdeq_X_insert_range(cdeq_X* self, cdeq_X_iter_t pos,
+                                        cdeq_X_iter_t first, cdeq_X_iter_t finish);
+cdeq_X_iter_t       cdeq_X_insert_range_p(cdeq_X* self, cdeq_X_value_t* pos,
+                                          const cdeq_X_value_t* pfirst, const cdeq_X_value_t* pfinish);
+
+cdeq_X_iter_t       cdeq_X_erase(cdeq_X* self, cdeq_X_iter_t pos);
+cdeq_X_iter_t       cdeq_X_erase_n(cdeq_X* self, size_t idx, size_t n);
+cdeq_X_iter_t       cdeq_X_erase_range(cdeq_X* self, cdeq_X_iter_t first, cdeq_X_iter_t finish);
+cdeq_X_iter_t       cdeq_X_erase_range_p(cdeq_X* self, cdeq_X_value_t* pfirst, cdeq_X_value_t* pfinish);
+
+cdeq_X_iter_t       cdeq_X_find(const cdeq_X* self, RawValue raw);
+cdeq_X_iter_t       cdeq_X_find_in_range(const cdeq_X* self,
+                                         cdeq_X_iter_t first, cdeq_X_iter_t finish, RawValue raw);
+
+void                cdeq_X_sort(cdeq_X* self);
+void                cdeq_X_sort_with(cdeq_X* self, size_t ifirst, size_t ifinish,
+                                     int(*cmp)(const cdeq_X_value_t*, const cdeq_X_value_t*));
+
+cdeq_X_iter_t       cdeq_X_begin(const cdeq_X* self);
+cdeq_X_iter_t       cdeq_X_end(const cdeq_X* self);
+void                cdeq_X_next(cdeq_X_iter_t* it);
+cdeq_X_value_t*     cdeq_X_itval(cdeq_X_iter_t it);
+size_t              cdeq_X_index(const cdeq_X vec, cdeq_X_iter_t it);
+
+Value               cdeq_X_value_from_raw(RawValue raw);
+```
+
+## Examples
+```c
+#include <stdio.h>
+#include <stc/cdeq.h>
+
+using_cdeq(i, int);
+
+int main() {
+    cdeq_i x = cdeq_i_init();
+    cdeq_i_push_front(&x, 10);
+    c_foreach (i, cdeq_i, x)
+        printf(" %d", *i.ref);
+    puts("");
+
+    c_push_items(&x, cdeq_i, {1, 4, 5, 22, 33, 2});
+    c_foreach (i, cdeq_i, x)
+        printf(" %d", *i.ref);
+    puts("");
+
+    cdeq_i_push_front(&x, 9);
+    cdeq_i_push_front(&x, 20);
+    cdeq_i_push_back(&x, 11);
+    cdeq_i_push_front(&x, 8);
+
+    c_foreach (i, cdeq_i, x)
+        printf(" %d", *i.ref);
+    puts("");
+    cdeq_i_del(&x);
+}
+```
+Output:
+```
+ 10
+ 10 1 4 5 22 33 2
+ 8 20 9 10 1 4 5 22 33 2 1
+```