Added cpqueue, cqueue, and cstack docs. Removed examples from README.md

10 files changed, 316 insertions, 410 deletions

diff --git a/README.md b/README.md
index 67c2d242..e012e450 100644
--- a/README.md
+++ b/README.md
@@ -5,19 +5,19 @@ Introduction
 ------------

 

 An elegant, fully typesafe, generic, customizable, user-friendly, consistent, and very fast standard container library for C99. This is a small headers only library with the most used container components, and a few algorithms:

-- [***carray*** - Dynamic generic **multi-dimensional array**](docs/carray_api.md), implemented as a single contiguous block of memory.

-- [***cbitset*** - A **bitset** - *std::bitset*- or *boost::dynamic_bitset*-like](docs/cbitset_api.md)

-- [***clist*** - Generic circular **singly linked List** type](docs/clist_api.md). Can be used as a *queue* as it supports *push_back(), push_front(), and pop_front()*. Supports various *splice* functions and *merge sort*.

-- [***cmap*** - Generic fast **unordered map** type](docs/cmap_api.md) Implemented as open hashing without tombstones. Highly customizable and fast.

-- [***cset*** - Generic fast **unordered set** type](docs/cset_api.md) Same as cmap, but contains and uses keys only.

+- [***carray*** - Generic dynamic **multi-dimensional array**](docs/carray_api.md)

 - [***cstr*** - Powerful and compact **string** type](docs/cstr_api.md)

-- [***cvec*** - Dynamic generic **vector** type](docs/cvec_api.md)

+- [***cbitset*** - A *std::bitset*/*boost::dynamic_bitset*-like **bitset** type](docs/cbitset_api.md)

+- [***clist*** - Generic circular **singly linked list** type](docs/clist_api.md)

+- [***cmap*** - Generic fast **unordered map** type](docs/cmap_api.md)

+- [***cset*** - Generic fast **unordered set** type](docs/cset_api.md)

+- [***cvec*** - Generic dynamic **vector** type](docs/cvec_api.md)

 - [***cstack*** - A **stack** adapter type](docs/cstack_api.md)

 - [***cqueue*** - A **queue** adapter type](docs/cqueue_api.md)

 - [***cpqueue*** - A **priority queue** adapter type](docs/cpqueue_api.md)

 - [***cptr*** - Support for pointers and shared pointers in containers](docs/cptr_api.md)

-- [***coption*** - Implements *coption_get()*, a **getopt_long**-like function](docs/coption_api.md), for command line argument parsing.

-- [***crandom*** - A few very efficent modern **random number generators**](docs/crandom_api.md) *pcg32* and my own *64-bit PRNG* inspired by *sfc64*, with uniform and normal distributions.

+- [***crandom*** - A few very efficent modern **random number generators**](docs/crandom_api.md)

+- [***coption*** - Implements *coption_get()*, a **getopt_long**-like function](docs/coption_api.md)

 - [***ccommon*** - Collection of general definitions](docs/ccommon_api.md)

 

 The usage of the containers is quite similar to the C++ standard containers, so it should be easy if you are familiar with them.

@@ -184,391 +184,3 @@ for cmaps with cstr_t keys and/or values:
 - *using_cset_str()* // cstr_t set

 

 To customize your own cmap type to work like these, you may want to look at **examples/advanced.c**. It demonstrates how to use a custom struct as a hash map key, by using the optional parameters to using_cmap().

-

-Example usages

---------------

-The examples folder contains further examples.

-

-**cvec** of *int64_t*.

-```C

-#include <stc/cvec.h>

-#include <stdio.h>

-

-using_cvec(ix, int64_t); // ix is just an example type tag name.

-

-int main() {

-    cvec_ix bignums = cvec_ix_init(); // use cvec_ix_init() if initializing after declaration.

-    cvec_ix_reserve(&bignums, 50);

-

-    c_forrange (i, int, 1, 50)

-        cvec_ix_push_back(&bignums, i * i * i);

-

-    cvec_ix_pop_back(&bignums); // erase the last

-

-    c_forrange (i, int, 1, cvec_ix_size(bignums))

-        bignums.data[i] /= i; // make them smaller

-

-    c_foreach (i, cvec_ix, bignums)

-        printf(" %d", *i.val);

-    cvec_ix_del(&bignums);

-}

-// Output:

- 1 8 13 21 31 43 57 73 91 111 133 157 183 211 241 273 307 343 381 421 463 507 553 601 651 703 757 813 871 931 993 1057 1123 1191 1261 1333 1407 1483 1561 1641 1723 1807 1893 1981 2071 2163 2257 2353

-```

-**cvec** of *cstr_t*.

-```C

-#include <stc/cstr.h>

-#include <stc/cvec.h>

-

-using_cvec_str();

-

-int main() {

-    cvec_str names = cvec_str_init();

-    cvec_str_emplace_back(&names, "Mary");

-    cvec_str_emplace_back(&names, "Joe");

-    cstr_assign(&names.data[1], "Jake"); // replace "Joe".

-

-    // Use push_back() rather than emplace_back() when adding a cstr_t type:

-    cstr_t tmp = cstr_from_fmt("%d elements so far", cvec_str_size(names));

-    cvec_str_push_back(&names, tmp); // tmp is moved to names, do not del() it.

-

-    printf("%s\n", names.data[1].str); // Access the second element

-

-    c_foreach (i, cvec_str, names)

-        printf("item: %s\n", i.val->str);

-    cvec_str_del(&names);

-}

-// Output:

-Jake

-item: Mary

-item: Jake

-item: 2 elements so far

-```

-**cstr** string example.

-```C

-#include <stc/cstr.h>

-

-int main() {

-    cstr_t s1 = cstr_from("one-nine-three-seven-five");

-    printf("%s.\n", s1.str);

-

-    cstr_insert(&s1, 3, "-two");

-    printf("%s.\n", s1.str);

-

-    cstr_erase(&s1, 7, 5); // -nine

-    printf("%s.\n", s1.str);

-

-    cstr_replace(&s1, cstr_find(&s1, "seven"), 5, "four");

-    printf("%s.\n", s1.str);

-

-    // reassign:

-    cstr_assign(&s1, "one two three four five six seven");

-    cstr_append(&s1, " eight");

-    printf("append: %s\n", s1.str);

-

-    cstr_t full_path = cstr_from_fmt("%s/%s.%s", "directory", "filename", "ext");

-    printf("%s\n", full_path.str);

-

-    c_del(cstr, &s1, &full_path);

-}

-// Output:

-one-nine-three-seven-five.

-one-two-nine-three-seven-five.

-one-two-three-seven-five.

-one-two-three-four-five.

-append: one two three four five six seven eight

-directory/filename.ext

-```

-**cmap** of *int => int*, and **cmap** of *cstr_t* => *cstr_t*

-```C

-#include <stdio.h>

-#include <stc/cmap.h>

-#include <stc/cstr.h>

-

-using_cmap(ii, int, int);

-using_cmap_str();

-

-int main() {

-    // -- map of ints --

-    cmap_ii nums = cmap_ii_init();

-    cmap_ii_put(&nums, 8, 64); // similar to insert_or_assign()

-    cmap_ii_emplace(&nums, 11, 121);

-

-    printf("%d\n", cmap_ii_find(&nums, 8)->second);

-    cmap_ii_del(&nums);

-

-    // -- map of str --

-    cmap_str strings = cmap_str_init();

-    cmap_str_emplace(&strings, "Make", "my");

-    cmap_str_emplace(&strings, "Rainy", "day");

-    cmap_str_emplace(&strings, "Sunny", "afternoon");

-    c_push_items(&strings, cmap_str, { {"Eleven", "XI"}, {"Six", "VI"} });

-

-    printf("size = %zu\n", cmap_str_size(strings));

-    c_foreach (i, cmap_str, strings)

-        printf("%s: %s\n", i.val->first.str, i.val->second.str);

-    cmap_str_del(&strings); // frees all strings and map.

-}

-// Output:

-64

-size = 5

-Rainy: day

-Sunny: afternoon

-Six: VI

-Make: my

-Eleven: XI

-```

-**cset** of *cstr*.

-```C

-#include <stc/cstr.h>

-#include <stc/cmap.h>

-

-using_cset_str(); // cstr set. See the discussion above.

-

-int main() {

-    cset_str words = cset_str_init();

-    cset_str_insert(&words, "Hello");

-    cset_str_insert(&words, "Sad");

-    cset_str_insert(&words, "World");

-

-    cset_str_erase(&words, "Sad");

-

-    // iterate the set of cstr_t values:

-    c_foreach (i, cset_str, words)

-        printf("%s ", i.val->str);

-    cset_str_del(&words);

-}

-// Output:

-Hello World

-```

-**clist** of *int64_t*. Similar to c++ *std::forward_list*, but can do both *push_front()* and *push_back()* as well as *pop_front()*.

-```C

-#include <stdio.h>

-#include <stc/clist.h>

-

-using_clist(fx, double);

-

-int main() {

-    clist_fx list = clist_fx_init();

-    c_push_items(&list, clist_fx, {

-        10.0, 20.0, 30.0, 40.0, 50.0, 60.0, 70.0, 80.0, 90.0

-    });

-    // interleave push_front / push_back:

-    c_forrange (i, int, 1, 10) {

-        if (i & 1) clist_fx_push_front(&list, (float) i);

-        else       clist_fx_push_back(&list, (float) i);

-    }

-

-    printf("initial: ");

-    c_foreach (i, clist_fx, list)

-        printf(" %g", *i.val);

-

-    clist_fx_sort(&list); // mergesort O(n*log n)

-

-    printf("\nsorted: ");

-    c_foreach (i, clist_fx, list)

-        printf(" %g", *i.val);

-

-    clist_fx_del(&list);

-}

-// Output:

-initial:  9 7 5 3 1 10 20 30 40 50 60 70 80 90 2 4 6 8

-sorted:  1 2 3 4 5 6 7 8 9 10 20 30 40 50 60 70 80 90

-```

-**cpqueue** priority queue demo:

-```C

-#include <stdio.h>

-#include <stc/cpqueue.h>

-#include <stc/crandom.h>

-

-using_cvec(i, int64_t);

-using_cpqueue(i, cvec_i, >); // adaptor type, '>' = min-heap

-

-int main()

-{

-    size_t N = 10000000;

-    crand_rng64_t rng = crand_rng64_init(1234);

-    crand_uniform_i64_t dist = crand_uniform_i64_init(0, N * 10);

-

-    cpqueue_i heap = cpqueue_i_init();

-    // Push ten million random numbers to priority queue, plus some negative ones.

-    c_forrange (N)

-        cpqueue_i_push(&heap, crand_uniform_i64(&rng, &dist));

-    c_push_items(&heap, cpqueue_i, {-231, -32, -873, -4, -343});

-

-    // Extract and disply the fifty smallest.

-    c_forrange (50) {

-        printf("%zd ", *cpqueue_i_top(&heap));

-        cpqueue_i_pop(&heap);

-    }

-    cpqueue_i_del(&heap);

-}

-// Output:

- -873 -343 -231 -32 -4 3 5 6 18 23 31 54 68 87 99 105 107 125 128 147 150 155 167 178 181 188 213 216 272 284 287 302 306 311 313 326 329 331 344 348 363 367 374 385 396 399 401 407 412 477

-```

-**cqueue** adapter container. Uses singly linked list as representation.

-```C

-#include <stc/cqueue.h>

-#include <stdio.h>

-

-using_clist(i, int);

-using_cqueue(i, clist_i);

-

-int main() {

-    cqueue_i queue = cqueue_i_init();

-

-    // push() and pop() a few.

-    c_forrange (i, 20)

-        cqueue_i_push(&queue, i);

-

-    c_forrange (5)

-        cqueue_i_pop(&queue);

-

-    c_foreach (i, cqueue_i, queue)

-        printf(" %d", *i.val);

-

-    cqueue_i_del(&queue);

-}

-// Output:

- 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19

-```

-**carray**. 1d, 2d and 3d arrays, allocated from heap in one memory block. *carray3* may have sub-array "views" of *carray2* and *carray1* etc., as shown in the following example:

-```C

-#include <stdio.h>

-#include <stc/carray.h>

-

-using_carray(f, float);

-

-int main()

-{

-    carray3f a3 = carray3f_init(30, 20, 10, 0.0f);  // define a3[30][20][10], init with 0.0f.

-    *carray3f_at(&a3, 5, 4, 3) = 3.14f;         // a3[5][4][3] = 3.14

-

-    carray1f a1 = carray3f_at2(&a3, 5, 4);      // sub-array a3[5][4] (no data copy).

-    carray2f a2 = carray3f_at1(&a3, 5);         // sub-array a3[5]

-

-    printf("%f\n", *carray1f_at(&a1, 3));       // a1[3] (3.14f)

-    printf("%f\n", *carray2f_at(&a2, 4, 3));    // a2[4][3] (3.14f)

-    printf("%f\n", *carray3f_at(&a3, 5, 4, 3)); // a3[5][4][3] (3.14f)

-    // ...

-    carray1f_del(&a1); // does nothing, since it is a sub-array.

-    carray2f_del(&a2); // same.

-    carray3f_del(&a3); // free array, and invalidates a1, a2.

-}

-// Output:

-3.140000

-3.140000

-3.140000

-```

-Finally, a demo of **cmap**, **cvec**, **cstr** and **random**: Normal distribution with a random mean and standard deviation, which may produce this:

-```

-  55 *

-  56 **

-  57 ****

-  58 ******

-  59 *********

-  60 **************

-  61 ********************

-  62 ***************************

-  63 ************************************

-  64 ********************************************

-  65 *****************************************************

-  66 *************************************************************

-  67 ********************************************************************

-  68 ************************************************************************

-  69 *************************************************************************

-  70 ************************************************************************

-  71 *******************************************************************

-  72 *************************************************************

-  73 *****************************************************

-  74 ********************************************

-  75 ***********************************

-  76 ***************************

-  77 ********************

-  78 **************

-  79 **********

-  80 ******

-  81 ****

-  82 **

-  83 *

-Normal distribution with mean=69, stddev=5. '*' = 10811 samples out of 10000000.

-```

-Code:

-```C

-#include <stdio.h>

-#include <time.h>

-#include <math.h>

-#include <stc/cmap.h>

-#include <stc/cvec.h>

-#include <stc/cstr.h>

-#include <stc/crandom.h>

-

-using_cmap(ii, int, int);

-

-static int compare(cmap_ii_value_t *a, cmap_ii_value_t *b)

-{

-    return c_default_compare(&a->first, &b->first);

-}

-using_cvec(mi, cmap_ii_value_t, c_default_del, compare);

-

-cvec_mi make_normal_dist(crand_rng64_t* rng, crand_normal_f64_t* dist, int n);

-void display_hist(cvec_mi hist, int scale, int mean, int stddev);

-

-

-int main(int argc, char* argv[])

-{

-    // Seed with a real random value, if available

-    crand_rng64_t rng = crand_rng64_init(time(NULL));

-

-    // Choose random mean and standard deviation

-    crand_uniform_i64_t mean_dist = crand_uniform_i64_init(-99, 99),

-                        sdev_dist = crand_uniform_i64_init(5, 12);

-

-    int mean = (int) crand_uniform_i64(&rng, &mean_dist);

-    int stddev = (int) crand_uniform_i64(&rng, &sdev_dist);

-

-    // Setup a normal distribution:

-    crand_normal_f64_t norm_dist = crand_normal_f64_init(mean, stddev);

-

-    int samples = 10000000, scale = 74;

-    cvec_mi hist = make_normal_dist(&rng, &norm_dist, samples);

-    display_hist(hist, scale, mean, stddev);

-

-    cvec_mi_del(&hist);

-}

-

-cvec_mi make_normal_dist(crand_rng64_t* rng, crand_normal_f64_t* dist, int n)

-{

-    cmap_ii mhist = cmap_ii_init();

-    c_forrange (n) {

-        cmap_ii_emplace(&mhist, (int) round(crand_normal_f64(rng, dist)), 0).first->second += 1;

-    }

-

-    // Transfer cmap entries to a cvec, sort and return it.

-    cvec_mi hist = cvec_mi_init();

-    c_foreach (i, cmap_ii, mhist) {

-        cvec_mi_push_back(&hist, *i.val);

-    }

-    cvec_mi_sort(&hist);

-    cmap_ii_del(&mhist);

-    return hist;

-}

-

-void display_hist(cvec_mi hist, int scale, int mean, int stddev)

-{

-    cstr_t bar = cstr_init();

-    int n = 0; // samples

-    c_foreach (i, cvec_mi, hist)

-        n += i.val->second;

-    c_foreach (i, cvec_mi, hist) {

-        int k = (int) (i.val->second * stddev * scale * 25ull / 10 / n);

-        if (k > 0) {

-            cstr_take(&bar, cstr_with_size(k, '*'));

-            printf("%4d %s\n", i.val->first, bar.str);

-        }

-    }

-    printf("Normal distribution with mean=%d, stddev=%d. '*' = %.0f samples out of %d.\n",

-           mean, stddev, n / (2.5 * stddev * scale), n);

-    cstr_del(&bar);

-}

-```

diff --git a/docs/carray_api.md b/docs/carray_api.md
index fb351b96..d2387f39 100644
--- a/docs/carray_api.md
+++ b/docs/carray_api.md
@@ -1,6 +1,8 @@
 # Container type carray
 
 This describes the API of the unordered set type **carray**.
+1d, 2d and 3d arrays, allocated from heap in one single contiguous block of memory.
+*carray3* may have sub-array "views" of *carray2* and *carray1* etc.
 
 ## Declaration
 
@@ -83,18 +85,24 @@ using_carray(f, float);
 
 int main()
 {
-    carray3f a3 = carray3f_init(30, 20, 10, 0.f);
-    *carray3f_at(&a3, 5, 4, 3) = 10.2f;         // a3[5][4][3]
-    carray2f a2 = carray3f_at1(&a3, 5);         // sub-array reference: a2 = a3[5]
-    printf("%g\n", *carray2f_at(&a2, 4, 3));    // lookup a2[4][3] (=10.2f)
-    printf("%g\n", *carray3f_at(&a3, 5, 4, 3)); // same data location, via a3 array.
-
-    carray2f_del(&a2); // does nothing, since it is a sub-array.
-    carray3f_del(&a3); // destroy a3, invalidates a2.
+    carray3f a3 = carray3f_init(30, 20, 10, 0.0f);  // define a3[30][20][10], init with 0.0f.
+    *carray3f_at(&a3, 5, 4, 3) = 3.14f;             // a3[5][4][3] = 3.14
+
+    carray1f a1 = carray3f_at2(&a3, 5, 4);          // sub-array a3[5][4] (no data copy).
+    carray2f a2 = carray3f_at1(&a3, 5);             // sub-array a3[5]
+
+    printf("%f\n", *carray1f_at(&a1, 3));           // a1[3] (3.14f)
+    printf("%f\n", *carray2f_at(&a2, 4, 3));        // a2[4][3] (3.14f)
+    printf("%f\n", *carray3f_at(&a3, 5, 4, 3));     // a3[5][4][3] (3.14f)
+    // ...
+    carray1f_del(&a1); // does nothing, since it is a sub-array.
+    carray2f_del(&a2); // same.
+    carray3f_del(&a3); // free array, and invalidates a1, a2.
 }
 ```
 Output:
 ```
-10.2
-10.2
-```
\ No newline at end of file
+3.140000
+3.140000
+3.140000
+```
diff --git a/docs/clist_api.md b/docs/clist_api.md
index d899e6ad..455a66fb 100644
--- a/docs/clist_api.md
+++ b/docs/clist_api.md
@@ -1,6 +1,8 @@
 # Container type clist
 
 This describes the API of circular singly linked list type **clist**.
+Similar to c++ *std::forward_list*, but can do both *push_front()* and *push_back()* as well as *pop_front()*.
+Also supports various *splice* functions and *merge sort*.
 
 ## Declaration
 
diff --git a/docs/cmap_api.md b/docs/cmap_api.md
index 3541c9ab..8bd079ae 100644
--- a/docs/cmap_api.md
+++ b/docs/cmap_api.md
@@ -1,6 +1,7 @@
 # Container type cmap
 
-This describes the API of the unordered map type **cmap**.
+This describes the API of the unordered map type **cmap**. Elements are pairs of keys and mapped values.
+Implemented as open hashing without tombstones. Highly customizable and fast.
 
 ## Declaration
 
diff --git a/docs/cpqueue_api.md b/docs/cpqueue_api.md
new file mode 100644
index 00000000..1b0ad6ca
--- /dev/null
+++ b/docs/cpqueue_api.md
@@ -0,0 +1,89 @@
+# Container type cpqueue
+
+This describes the API of the queue type **cpqueue**.
+
+## Declaration
+
+```c
+#define using_cpqueue(X, CType)
+```
+The macro `using_cpqueue()` can be instantiated with 2 arguments in the global scope.
+**cpqueue** uses normally a **cvec** type as undelying implementation.
+Default values are given above for args not specified. `X` is a type tag name and
+will affect the names of all cpqueue types and methods. E.g. declaring `using_cpqueue(my, cvec_my);`,
+`X` should be replaced by `my` in all of the following documentation.
+
+## Types
+
+| Type name              | Type definition                        | Used to represent...                |
+|:-----------------------|:---------------------------------------|:------------------------------------|
+| `cpqueue_X`            | Depending on underlying container type | The cpqueue type                     |
+| `cpqueue_X_value_t`    |                                        | The cpqueue element type             |
+| `cpqueue_X_input_t`    |                                        | cpqueue input type                   |
+| `cpqueue_X_rawvalue_t` |                                        | cpqueue raw value type               |
+| `cpqueue_X_iter_t`     |                                        | cpqueue iterator                     |
+
+## Header file
+
+All cpqueue definitions and prototypes may be included in your C source file by including a single header file.
+
+```c
+#include "stc/cpqueue.h"
+```
+
+## Methods
+
+```c
+cpqueue_X               cpqueue_X_init(void);
+void                    cpqueue_X_make_heap(cpqueue_X* self);
+void                    cpqueue_X_del(cpqueue_X* self);
+
+size_t                  cpqueue_X_size(cpqueue_X pq);
+bool                    cpqueue_X_empty(cpqueue_X pq);
+cpqueue_X_value_t*      cpqueue_X_top(cpqueue_X* self);
+
+void                    cpqueue_X_push_n(cpqueue_X *self, const cpqueue_X_input_t in[], size_t size);
+void                    cpqueue_X_emplace(cpqueue_X* self, cpqueue_X_rawvalue_t raw);
+void                    cpqueue_X_push(cpqueue_X* self, cpqueue_X_value_t value);
+void                    cpqueue_X_pop(cpqueue_X* self);
+void                    cpqueue_X_erase(cpqueue_X* self, size_t i);
+
+cpqueue_X_iter_t        cpqueue_X_begin(cpqueue_X* self);
+cpqueue_X_iter_t        cpqueue_X_end(cpqueue_X* self);
+void                    cpqueue_X_next(cpqueue_X_iter_t* it);
+cpqueue_X_value_t*      cpqueue_X_itval(cpqueue_X_iter_t it);
+```
+
+## Example
+```c
+#include <stdio.h>
+#include "stc/cpqueue.h"
+#include "stc/crandom.h"
+
+using_cvec(i, int64_t);
+using_cpqueue(i, cvec_i, >); // adaptor type, '>' = min-heap
+
+int main()
+{
+    size_t N = 10000000;
+    crand_rng64_t rng = crand_rng64_init(1234);
+    crand_uniform_i64_t dist = crand_uniform_i64_init(0, N * 10);
+
+    cpqueue_i heap = cpqueue_i_init();
+    // Push ten million random numbers to priority queue, plus some negative ones.
+    c_forrange (N)
+        cpqueue_i_push(&heap, crand_uniform_i64(&rng, &dist));
+    c_push_items(&heap, cpqueue_i, {-231, -32, -873, -4, -343});
+
+    // Extract and display the fifty smallest.
+    c_forrange (50) {
+        printf("%zd ", *cpqueue_i_top(&heap));
+        cpqueue_i_pop(&heap);
+    }
+    cpqueue_i_del(&heap);
+}
+```
+Output:
+```
+ -873 -343 -231 -32 -4 3 5 6 18 23 31 54 68 87 99 105 107 125 128 147 150 155 167 178 181 188 213 216 272 284 287 302 306 311 313 326 329 331 344 348 363 367 374 385 396 399 401 407 412 477
+```
\ No newline at end of file
diff --git a/docs/cqueue_api.md b/docs/cqueue_api.md
new file mode 100644
index 00000000..b54c0810
--- /dev/null
+++ b/docs/cqueue_api.md
@@ -0,0 +1,83 @@
+# Container type cqueue
+
+This describes the API of the queue type **cqueue**.
+
+## Declaration
+
+```c
+#define using_cqueue(X, CType)
+```
+The macro `using_cqueue()` can be instantiated with 2 arguments in the global scope.
+**cqueue** uses normally a **clist** type as undelying implementation.
+Default values are given above for args not specified. `X` is a type tag name and
+will affect the names of all cqueue types and methods. E.g. declaring `using_cqueue(my, clist_my);`,
+`X` should be replaced by `my` in all of the following documentation.
+
+## Types
+
+| Type name             | Type definition                        | Used to represent...                |
+|:----------------------|:---------------------------------------|:------------------------------------|
+| `cqueue_X`            | Depending on underlying container type | The cqueue type                     |
+| `cqueue_X_value_t`    |                                        | The cqueue element type             |
+| `cqueue_X_input_t`    |                                        | cqueue input type                   |
+| `cqueue_X_rawvalue_t` |                                        | cqueue raw value type               |
+| `cqueue_X_iter_t`     |                                        | cqueue iterator                     |
+
+## Header file
+
+All cqueue definitions and prototypes may be included in your C source file by including a single header file.
+
+```c
+#include "stc/cqueue.h"
+```
+
+## Methods
+
+```c
+cqueue_X                cqueue_X_init(void);
+void                    cqueue_X_del(cqueue_X* self);
+
+size_t                  cqueue_X_size(cqueue_X pq);
+bool                    cqueue_X_empty(cqueue_X pq);
+cqueue_X_value_t*       cqueue_X_front(cqueue_X* self);
+cqueue_X_value_t*       cqueue_X_back(cqueue_X* self);
+
+void                    cqueue_X_push_n(cqueue_X *self, const cqueue_X_input_t in[], size_t size);
+void                    cqueue_X_emplace(cqueue_X* self, cqueue_X_rawvalue_t raw);
+void                    cqueue_X_push(cqueue_X* self, cqueue_X_value_t value);
+void                    cqueue_X_pop(cqueue_X* self);
+
+cqueue_X_iter_t         cqueue_X_begin(cqueue_X* self);
+cqueue_X_iter_t         cqueue_X_end(cqueue_X* self);
+void                    cqueue_X_next(cqueue_X_iter_t* it);
+cqueue_X_value_t*       cqueue_X_itval(cqueue_X_iter_t it);
+```
+
+## Examples
+```c
+#include <stdio.h>
+#include "stc/cqueue.h"
+
+using_clist(i, int);
+using_cqueue(i, clist_i);
+
+int main() {
+    cqueue_i queue = cqueue_i_init();
+
+    // push() and pop() a few.
+    c_forrange (i, 20)
+        cqueue_i_push(&queue, i);
+
+    c_forrange (5)
+        cqueue_i_pop(&queue);
+
+    c_foreach (i, cqueue_i, queue)
+        printf(" %d", *i.val);
+
+    cqueue_i_del(&queue);
+}
+```
+Output:
+```
+5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
+```
\ No newline at end of file
diff --git a/docs/crandom_api.md b/docs/crandom_api.md
index ca798d07..f066197e 100644
--- a/docs/crandom_api.md
+++ b/docs/crandom_api.md
@@ -1,6 +1,7 @@
 # Random number generators
 
-This describes the API of module **crandom**.
+This describes the API of module **crandom**. Contains *pcg32* and a extremely fast *64-bit PRNG* inspired by *sfc64*.
+The RNG's can generate uniform and normal distributions.
 
 ## Types
 
diff --git a/docs/cset_api.md b/docs/cset_api.md
index 92ec3e88..970276e9 100644
--- a/docs/cset_api.md
+++ b/docs/cset_api.md
@@ -1,6 +1,7 @@
 # Container type cset

 

 This describes the API of the unordered set type **cset**.

+Same base implementation as cmap, but contains and uses keys only.

 

 ## Declaration

 

diff --git a/docs/cstack_api.md b/docs/cstack_api.md
new file mode 100644
index 00000000..783b1cf9
--- /dev/null
+++ b/docs/cstack_api.md
@@ -0,0 +1,78 @@
+# Container type cstack
+
+This describes the API of the queue type **cstack**.
+
+## Declaration
+
+```c
+#define using_cstack(X, CType)
+```
+The macro `using_cstack()` can be instantiated with 2 arguments in the global scope.
+**cstack** uses normally a **cvec** type as undelying implementation.
+Default values are given above for args not specified. `X` is a type tag name and
+will affect the names of all cstack types and methods. E.g. declaring `using_cstack(my, cvec_my);`,
+`X` should be replaced by `my` in all of the following documentation.
+
+## Types
+
+| Type name             | Type definition                        | Used to represent...                |
+|:----------------------|:---------------------------------------|:------------------------------------|
+| `cstack_X`            | Depending on underlying container type | The cstack type                     |
+| `cstack_X_value_t`    |                                        | The cstack element type             |
+| `cstack_X_input_t`    |                                        | cstack input type                   |
+| `cstack_X_rawvalue_t` |                                        | cstack raw value type               |
+| `cstack_X_iter_t`     |                                        | cstack iterator                     |
+
+## Header file
+
+All cstack definitions and prototypes may be included in your C source file by including a single header file.
+
+```c
+#include "stc/cstack.h"
+```
+
+## Methods
+
+```c
+cstack_X                cstack_X_init(void);
+void                    cstack_X_del(cstack_X* self);
+
+size_t                  cstack_X_size(cstack_X pq);
+bool                    cstack_X_empty(cstack_X pq);
+cstack_X_value_t*       cstack_X_top(cstack_X* self);
+
+void                    cstack_X_push_n(cstack_X *self, const cstack_X_input_t in[], size_t size);
+void                    cstack_X_emplace(cstack_X* self, cstack_X_rawvalue_t raw);
+void                    cstack_X_push(cstack_X* self, cstack_X_value_t value);
+void                    cstack_X_pop(cstack_X* self);
+
+cstack_X_iter_t         cstack_X_begin(cstack_X* self);
+cstack_X_iter_t         cstack_X_end(cstack_X* self);
+void                    cstack_X_next(cstack_X_iter_t* it);
+cstack_X_value_t*       cstack_X_itval(cstack_X_iter_t it);
+```
+
+## Example
+```c
+#include <stdio.h>
+#include "stc/cstack.h"
+
+using_cvec(i, int);
+using_cstack(i, cvec_i);
+
+int main() {
+    cstack_i stack = cstack_i_init();
+
+    for (int i=0; i < 100; ++i)
+        cstack_i_push(&stack, i*i);
+
+    for (int i=0; i < 90; ++i)
+        cstack_i_pop(&stack);
+
+    printf("top: %d\n", *cstack_i_top(&stack));
+}
+```
+Output:
+```
+top: 81
+```
\ No newline at end of file
diff --git a/docs/cvec_api.md b/docs/cvec_api.md
index 7a60c110..3db9e7c8 100644
--- a/docs/cvec_api.md
+++ b/docs/cvec_api.md
@@ -105,7 +105,7 @@ void                cvec_X_next(cvec_X_iter_t* it);
 cvec_X_value_t*     cvec_X_itval(cvec_X_iter_t it);
 ```
 
-## Example
+## Examples
 ```c
 #include <stdio.h>
 #include "stc/cvec.h"
@@ -141,4 +141,35 @@ Output:
 ```
 initial:  7 5 16 8 25 13
 sorted:  5 7 8 13 16 25
+```
+### Example 2
+```c
+#include "stc/cstr.h"
+#include "stc/cvec.h"
+
+using_cvec_str();
+
+int main() {
+    cvec_str names = cvec_str_init();
+    cvec_str_emplace_back(&names, "Mary");
+    cvec_str_emplace_back(&names, "Joe");
+    cstr_assign(&names.data[1], "Jake"); // replace "Joe".
+
+    // Use push_back() rather than emplace_back() when adding a cstr_t type:
+    cstr_t tmp = cstr_from_fmt("%d elements so far", cvec_str_size(names));
+    cvec_str_push_back(&names, tmp); // tmp is moved to names, do not del() it.
+
+    printf("%s\n", names.data[1].str); // Access the second element
+
+    c_foreach (i, cvec_str, names)
+        printf("item: %s\n", i.val->str);
+    cvec_str_del(&names);
+}
+```
+Output:
+```
+Jake
+item: Mary
+item: Jake
+item: 2 elements so far
 ```
\ No newline at end of file