Added some examples.

4 files changed, 152 insertions, 15 deletions

diff --git a/docs/clist_api.md b/docs/clist_api.md
index ebb056bf..eba55a90 100644
--- a/docs/clist_api.md
+++ b/docs/clist_api.md
@@ -105,3 +105,39 @@ clist_T_iter_t      clist_T_end(const clist_T* self);
 void                clist_T_next(clist_T_iter_t* it);
 clist_T_value_t*    clist_T_itval(clist_T_iter_t it);
 ```
+
+Example:
+```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
+```
\ No newline at end of file
diff --git a/docs/cmap_api.md b/docs/cmap_api.md
index 6e98a42f..05d59da8 100644
--- a/docs/cmap_api.md
+++ b/docs/cmap_api.md
@@ -63,13 +63,14 @@ be replaced by `my` in all of the following documentation.
 
 ## Constants and macros
 
-| Name                       | Value            |
-|:---------------------------|:-----------------|
-|  `cmap_inits`              | `{...}`          |
-|  `cmap_empty(map)`         | `true` if empty  |
-|  `cmap_size(map)`          |                  |
-|  `cmap_capacity(map)`      |                  |
-
+| Name                                            | Purpose                |
+|:------------------------------------------------|:-----------------------|
+|  `cmap_inits`                                   | Initializer const      |
+|  `cmap_empty(map)`                              | Test for empty map     |
+|  `cmap_size(map)`                               | Get map size           |
+|  `cmap_capacity(map)`                           | Get map capacity       |
+|  `c_try_emplace(self, ctype, key, val)          | Emplace if key exist   |
+|  `c_insert_items(self, ctype, array)`           | Insert literals list   |
 
 ## Header file
 
@@ -125,3 +126,43 @@ cmap_bucket_t       cmap_T_bucket(const cmap_T* self, const cmap_T_rawkey_t* raw
 uint32_t            c_default_hash16(const void *data, size_t len);
 uint32_t            c_default_hash32(const void* data, size_t len);
 ```
+
+Example:
+```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 cstr_t --
+    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
+```
diff --git a/docs/cset_api.md b/docs/cset_api.md
index 50b7347b..88a735bd 100644
--- a/docs/cset_api.md
+++ b/docs/cset_api.md
@@ -47,20 +47,21 @@ be replaced by `my` in all of the following documentation.
 

 ## Constants and macros

 

-| Name                       | Value            |

-|:---------------------------|:-----------------|

-|  `cset_inits`              | `{...}`          |

-|  `cset_empty(map)`         | `true` if empty  |

-|  `cset_size(map)`          |                  |

-|  `cset_capacity(map)`      |                  |

-

+| Name                                            | Purpose                  |

+|:------------------------------------------------|:-------------------------|

+|  `cset_inits`                                   | Initializer const        |

+|  `cset_empty(set)`                              | Test for empty set       |

+|  `cset_size(set)`                               | Get set size             |

+|  `cset_capacity(set)`                           | Get set capacity         |

+|  `c_try_emplace(self, ctype, key, val)`         | Emplace if key exist     |

+|  `c_insert_items(self, ctype, array)`           | Insert literals list     |

 

 ## Header file

 

 All cset definitions and prototypes may be included in your C source file by including a single header file.

 

 ```c

-#include "stc/cset.h"

+#include "stc/cset.h" or "stc/cmap.h"

 ```

 ## Methods

 

@@ -105,3 +106,26 @@ cset_bucket_t       cset_T_bucket(const cset_T* self, const cset_T_rawkey_t* raw
 uint32_t            c_default_hash16(const void *data, size_t len);

 uint32_t            c_default_hash32(const void* data, size_t len);

 ```

+

+Example:

+```c

+#include <stc/cstr.h>

+#include <stc/cmap.h>

+

+using_cset_str();

+

+int main() {

+    cset_str words = cset_str_init();

+    cset_str_emplace(&words, "Hello");

+    cset_str_emplace(&words, "Crazy");

+    cset_str_emplace(&words, "World");

+    cset_str_erase(&words, "Crazy");

+

+    // 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

+```

diff --git a/docs/cstr_api.md b/docs/cstr_api.md
index 6fbd1253..c3f6765d 100644
--- a/docs/cstr_api.md
+++ b/docs/cstr_api.md
@@ -152,3 +152,39 @@ int          cstr_compare_raw(const char** x, const char** y);
 bool         cstr_equals_raw(const char** x, const char** y);
 uint32_t     cstr_hash_raw(const char* const* spp, size_t ignored);
 ```
+
+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
+```
\ No newline at end of file