More docs update.

5 files changed, 194 insertions, 39 deletions

diff --git a/docs/cbitset_api.md b/docs/cbitset_api.md
index 59459b62..41e4d976 100644
--- a/docs/cbitset_api.md
+++ b/docs/cbitset_api.md
@@ -64,3 +64,52 @@ cbitset_iter_t   cbitset_end(cbitset_t* self);
 void             cbitset_next(cbitset_iter_t* it);
 bool             cbitset_itval(cbitset_iter_t it);
 ```
+
+## Example
+```c
+#include <stdio.h>
+#include <stc/cbitset.h>
+
+static inline cbitset_t sieveOfEratosthenes(size_t n)
+{
+    cbitset_t pbits = cbitset_with_size(n + 1, true);
+    cbitset_reset(&pbits, 0);
+    cbitset_reset(&pbits, 1);
+
+    c_forrange (i, size_t, 2, n+1) {
+        // If pbits[i] is not changed, then it is a prime
+        if (cbitset_test(pbits, i) && i*i <= n) {
+            c_forrange (j, size_t, i*i, n+1, i) {
+                cbitset_reset(&pbits, j);
+            }
+        }
+    }
+    return pbits;
+}
+
+int main(void)
+{
+    int n = 100000000;
+    printf("computing prime numbers up to %u\n", n);
+
+    cbitset_t primes = sieveOfEratosthenes(n);
+    puts("done");
+
+    size_t np = cbitset_count(primes);
+    printf("number of primes: %zu\n", np);
+
+    printf("2 ");
+    c_forrange (i, int, 3, 1001, 2) {
+       if (cbitset_test(primes, i)) printf("%d ", i);
+    }
+    puts("");
+    cbitset_del(&primes);
+}
+```
+Output:
+```
+computing prime numbers up to 100000000
+done
+number of primes: 5761455
+2 3 5 7 11 13 17 19 23 29 31 37 41 43 47 53 59 61 67 71 73 79 83 89 97 101 103 107 109 113 127 131 137 139 149 151 157 163 167 173 179 181 191 193 197 199 211 223 227 229 233 239 241 251 257 263 269 271 277 281 283 293 307 311 313 317 331 337 347 349 353 359 367 373 379 383 389 397 401 409 419 421 431 433 439 443 449 457 461 463 467 479 487 491 499 503 509 521 523 541 547 557 563 569 571 577 587 593 599 601 607 613 617 619 631 641 643 647 653 659 661 673 677 683 691 701 709 719 727 733 739 743 751 757 761 769 773 787 797 809 811 821 823 827 829 839 853 857 859 863 877 881 883 887 907 911 919 929 937 941 947 953 967 971 977 983 991 997
+```
diff --git a/docs/clist_api.md b/docs/clist_api.md
index 1d17d5e9..c3958e52 100644
--- a/docs/clist_api.md
+++ b/docs/clist_api.md
@@ -104,7 +104,7 @@ void                clist_X_next(clist_X_iter_t* it);
 clist_X_value_t*    clist_X_itval(clist_X_iter_t it);
 ```
 
-Example:
+## Example
 ```c
 #include <stdio.h>
 #include "stc/clist.h"
@@ -134,8 +134,9 @@ int main() {
 
     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
 ```
\ No newline at end of file
diff --git a/docs/crandom_api.md b/docs/crandom_api.md
index 84865a26..5d0a8a98 100644
--- a/docs/crandom_api.md
+++ b/docs/crandom_api.md
@@ -4,15 +4,15 @@ This describes the API of module **crandom**.
 
 ## Types
 
-| crandom               | Type definition                            | Used to represent...                 |
-|:----------------------|:-------------------------------------------|:-------------------------------------|
-| `crand_rng32_t`       | `struct {uint64_t state[2];}`              | The crandom type                     |
-| `crand_uniform_i32_t` | `struct {int32_t offset; uint32_t range;}` | The crandom element type             |
-| `crand_uniform_f32_t` | `struct {float offset, range;}`            | crandom iterator                     |
-| `crand_rng64_t`       | `struct {uint64_t state[4];}`              |                                      |
-| `crand_uniform_i64_t` | `struct {int64_t offset; uint64_t range;}` |                                      |
-| `crand_uniform_f64_t` | `struct {double offset, range;}`           |                                      |
-| `crand_normal_f64_t`  | `struct {double mean, stddev, next; bool has_next;}` |                            |
+| crandom               | Type definition                                      | Used to represent...                 |
+|:----------------------|:-----------------------------------------------------|:-------------------------------------|
+| `crand_rng32_t`       | `struct {uint64_t state[2];}`                        | The crandom type                     |
+| `crand_uniform_i32_t` | `struct {int32_t offset; uint32_t range;}`           | The crandom element type             |
+| `crand_uniform_f32_t` | `struct {float offset, range;}`                      | crandom iterator                     |
+| `crand_rng64_t`       | `struct {uint64_t state[4];}`                        |                                      |
+| `crand_uniform_i64_t` | `struct {int64_t offset; uint64_t range;}`           |                                      |
+| `crand_uniform_f64_t` | `struct {double offset, range;}`                     |                                      |
+| `crand_normal_f64_t`  | `struct {double mean, stddev, next; bool has_next;}` |                                      |
 
 ## Header file
 
@@ -23,37 +23,137 @@ All cstr definitions and prototypes may be included in your C source file by inc
 
 ## Methods
 
-### Construction
+### Interface for 32-bits random number generators
+```c
+(1)     crand_rng32_t           crand_rng32_init(uint64_t seed);
+(2)     crand_rng32_t           crand_rng32_with_seq(uint64_t seed, uint64_t seq);
+(3)     uint32_t                crand_i32(crand_rng32_t* rng);
+(4)     float                   crand_f32(crand_rng32_t* rng);
+(5)     crand_uniform_i32_t     crand_uniform_i32_init(int32_t low, int32_t high);
+(6)     int32_t                 crand_uniform_i32(crand_rng32_t* rng, crand_uniform_i32_t* dist);
+(7)     uint32_t                crand_unbiased_i32(crand_rng32_t* rng, crand_uniform_i32_t* dist);
+(8)     crand_uniform_f32_t     crand_uniform_f32_init(float low, float high); /*  */
+(9)     float                   crand_uniform_f32(crand_rng32_t* rng, crand_uniform_f32_t* dist);
+```
+(1-2) RNG engine initializers. (3) Integer random number generator with range \[0, 2^32). (5) Integer generator with range \[low, high].
+(7) Unbiased version, see https://github.com/lemire/fastrange. (8) 32-bit float random number in range \[low, high), 23 bits resolution numbers.
 
-Interfaces to create 32-bits random numbers:
+### Interface for 64-bits random number generators
 ```c
-crand_rng32_t           crand_rng32_with_seq(uint64_t seed, uint64_t seq);
-crand_rng32_t           crand_rng32_init(uint64_t seed);
+(1)     crand_rng64_t           crand_rng64_with_seq(uint64_t seed, uint64_t seq);
+(2)     crand_rng64_t           crand_rng64_init(uint64_t seed);
+(3)     uint64_t                crand_i64(crand_rng64_t* rng);
+(4)     double                  crand_f64(crand_rng64_t* rng);
+(5)     crand_uniform_i64_t     crand_uniform_i64_init(int64_t low, int64_t high);
+(6)     int64_t                 crand_uniform_i64(crand_rng64_t* rng, crand_uniform_i64_t* dist);
+(7)     crand_uniform_f64_t     crand_uniform_f64_init(double low, double high);
+(8)     double                  crand_uniform_f64(crand_rng64_t* rng, crand_uniform_f64_t* dist);
+(9)     crand_normal_f64_t      crand_normal_f64_init(double mean, double stddev);
+(10)    double                  crand_normal_f64(crand_rng64_t* rng, crand_normal_f64_t* dist);
+```
+(1-2) RNG engine initializers. (3) Integer generator, range \[0, 2^64): PRNG copyright Tyge Løvset, NORCE Research, 2020.
+(4) Double random number in range \[low, high), 52 bit resolution. (5-8) Initializers and generators of uniform random numbers.
+Integer generator has range \[low, high]. (9-10) Initializer and generator for normal distributed random numbers.
+(9-10) Initializer and generator for normal-distributed random numbers.
 
-uint32_t                crand_i32(crand_rng32_t* rng); /* int random number generator, range [0, 2^32) */
-float                   crand_f32(crand_rng32_t* rng);
+## Example
+```c
+#include <stdio.h>
+#include <time.h>
+#include <math.h>
+#include <stc/crandom.h>
+#include <stc/cstr.h>
+#include <stc/cmap.h>
+#include <stc/cvec.h>
 
-crand_uniform_i32_t     crand_uniform_i32_init(int32_t low, int32_t high);  /* int generator in range [low, high] */
-int32_t                 crand_uniform_i32(crand_rng32_t* rng, crand_uniform_i32_t* dist);
+// Declare int -> int hashmap with typetag 'i'.
+using_cmap(i, int, size_t);
 
-uint32_t                crand_unbiased_i32(crand_rng32_t* rng, crand_uniform_i32_t* dist); /* https://github.com/lemire/fastrange */
-crand_uniform_f32_t     crand_uniform_f32_init(float low, float high); /* float random number in range [low, high). Note: 23 bit resolution. */
-float                   crand_uniform_f32(crand_rng32_t* rng, crand_uniform_f32_t* dist);
-```
-Interfaces to create 64-bits random numbers:
-```c
-crand_rng64_t           crand_rng64_with_seq(uint64_t seed, uint64_t seq); /* engine initializers */
-crand_rng64_t           crand_rng64_init(uint64_t seed);
+// Comparison of map keys.
+static int compare(cmap_i_entry_t *a, cmap_i_entry_t *b) {
+    return c_default_compare(&a->first, &b->first);
+}
+// Vector of map entries, with comparison function.
+using_cvec(e, cmap_i_entry_t, c_default_del, compare);
+
+int main()
+{
+    enum {N = 10000000};
+    const double Mean = -12.0, StdDev = 6.0, Mag = 8000.0 / StdDev;
 
-uint64_t                crand_i64(crand_rng64_t* rng); /* int generator, range [0, 2^64). PRNG copyright Tyge Løvset, NORCE Research, 2020 */
-double                  crand_f64(crand_rng64_t* rng); /* double random number in range [low, high). 52 bit resolution. */
+    printf("Demo of gaussian / normal distribution of %d random samples\n", N);
 
-crand_uniform_i64_t     crand_uniform_i64_init(int64_t low, int64_t high); /* int generator in range [low, high] */
-int64_t                 crand_uniform_i64(crand_rng64_t* rng, crand_uniform_i64_t* dist);
+    // Setup random engine with normal distribution.
+    uint64_t seed = time(NULL);
+    crand_rng64_t rng = crand_rng64_init(seed);
+    crand_normal_f64_t dist = crand_normal_f64_init(Mean, StdDev);
 
-crand_uniform_f64_t     crand_uniform_f64_init(double low, double high);
-double                  crand_uniform_f64(crand_rng64_t* rng, crand_uniform_f64_t* dist);
+    // Create histogram map
+    cmap_i mhist = cmap_i_init();
+    for (size_t i = 0; i < N; ++i) {
+        int index = (int) round( crand_normal_f64(&rng, &dist) );
+        cmap_i_emplace(&mhist, index, 0).first->second += 1;
+    }
 
-crand_normal_f64_t      crand_normal_f64_init(double mean, double stddev);
-double                  crand_normal_f64(crand_rng64_t* rng, crand_normal_f64_t* dist);
+    // Transfer map to vec and sort it by map keys.
+    cvec_e vhist = cvec_e_init();
+    c_foreach (i, cmap_i, mhist)
+        cvec_e_push_back(&vhist, *i.val);
+    cvec_e_sort(&vhist);
+
+    // Print the gaussian bar chart
+    cstr_t bar = cstr_init();
+    c_foreach (i, cvec_e, vhist) {
+        size_t n = (size_t) (i.val->second * Mag / N);
+        if (n > 0) {
+            // bar string: take ownership in new str after freeing current.
+            cstr_take(&bar, cstr_with_size(n, '*'));
+            printf("%4d %s\n", i.val->first, bar.str);
+        }
+    }
+    // Cleanup
+    cstr_del(&bar);
+    cmap_i_del(&mhist);
+    cvec_e_del(&vhist);
+}
+```
+Output:
 ```
+Demo of gaussian / normal distribution of 10000000 random samples
+ -29 *
+ -28 **
+ -27 ***
+ -26 *****
+ -25 ********
+ -24 ************
+ -23 ****************
+ -22 **********************
+ -21 ****************************
+ -20 ************************************
+ -19 ********************************************
+ -18 *****************************************************
+ -17 **************************************************************
+ -16 **********************************************************************
+ -15 ******************************************************************************
+ -14 ***********************************************************************************
+ -13 ***************************************************************************************
+ -12 ****************************************************************************************
+ -11 ***************************************************************************************
+ -10 ***********************************************************************************
+  -9 ******************************************************************************
+  -8 **********************************************************************
+  -7 **************************************************************
+  -6 *****************************************************
+  -5 ********************************************
+  -4 ************************************
+  -3 ****************************
+  -2 **********************
+  -1 ****************
+   0 ************
+   1 ********
+   2 *****
+   3 ***
+   4 **
+   5 *
+   6 *
+```
\ No newline at end of file
diff --git a/docs/cset_api.md b/docs/cset_api.md
index f0c62c8a..ddf1012d 100644
--- a/docs/cset_api.md
+++ b/docs/cset_api.md
@@ -126,16 +126,19 @@ int main ()
   c_foreach (x, cset_str, second) cset_str_emplace(&fifth, x.val->str);

   c_foreach (x, cset_str, third) cset_str_emplace(&fifth, x.val->str);

   c_foreach (x, cset_str, fourth) cset_str_emplace(&fifth, x.val->str);

+  c_del(cset_str, &first, &second, &third, &fourth);

 

-  printf("fifth contains:\n-------------\n");

+  printf("fifth contains:\n\n");

   c_foreach (x, cset_str, fifth) printf("%s\n", x.val->str);

+  cset_str_del(&fifth);

 

-  c_del(cset_str, &first, &second, &third, &fourth, &fifth);

   return 0;

 }

 ```

 Output:

 ```

+fifth contains:

+

 red

 green

 flour

diff --git a/docs/cstr_api.md b/docs/cstr_api.md
index 5766647f..aa7ec53d 100644
--- a/docs/cstr_api.md
+++ b/docs/cstr_api.md
@@ -138,7 +138,7 @@ These methods may be used by other container types.
 (4)     uint32_t     c_string_hash(const char* str);
 ```
 
-Example:
+## Example
 ```c
 #include "stc/cstr.h"
 
@@ -165,7 +165,9 @@ int main() {
 
     c_del(cstr, &s1, &full_path);
 }
-// Output:
+```
+Output:
+```
 one-nine-three-seven-five.
 one-two-nine-three-seven-five.
 one-two-three-seven-five.