Improved docs for using_*() macros.

1 files changed, 57 insertions, 18 deletions

diff --git a/docs/cmap_api.md b/docs/cmap_api.md
index 8bd079ae..2fe5a830 100644
--- a/docs/cmap_api.md
+++ b/docs/cmap_api.md
@@ -6,17 +6,6 @@ Implemented as open hashing without tombstones. Highly customizable and fast.
 ## Declaration
 
 ```c
-#define using_cmap_str()
-
-#define using_cmap_strkey(X, Mapped, mappedDestroy=c_default_del)
-
-#define using_cmap_strval(X, Key, keyEquals=c_default_equals,
-                                  keyHash=c_default_hash16,
-                                  keyDestroy=c_default_del,
-                                  RawKey=Key,
-                                  keyToRaw=c_default_to_raw,
-                                  keyFromRaw=c_default_from_raw)
-
 #define using_cmap(X, Key, Mapped, mappedDestroy=c_default_del,
                                    keyEqualsRaw=c_default_equals,
                                    keyHashRaw=c_default_hash16,
@@ -26,14 +15,28 @@ Implemented as open hashing without tombstones. Highly customizable and fast.
                                    keyFromRaw=c_default_from_raw,
                                    RawMapped=Mapped,
                                    mappedFromRaw=c_default_from_raw)
+
+#define using_cmap_strkey(X, Mapped, mappedDestroy=c_default_del)
+
+#define using_cmap_strval(X, Key, keyEquals=c_default_equals,
+                                  keyHash=c_default_hash16,
+                                  keyDestroy=c_default_del,
+                                  RawKey=Key,
+                                  keyToRaw=c_default_to_raw,
+                                  keyFromRaw=c_default_from_raw)
+#define using_cmap_str()
 ```
 The macro `using_cmap()` can be instantiated with 3, 4, 6, 10, or 12 arguments in the global scope.
 Default values are given above for args not specified. `X` is a type tag name and
 will affect the names of all cmap types and methods. E.g. declaring `using_cmap(my, int);`, `X` should
 be replaced by `my` in all of the following documentation.
 
-`using_cmap_str()` is a specific definition of `using_cmap(str, cstr_t, ...)`. `using_cmap_strkey(X, ...)` and `using_cmap_strval(X, ...)`
-are special macros for `using_cmap()` with `cstr_t` as key and mapped value correspondingly.
+`using_cmap_strkey(X, ...)` and `using_cmap_strval(X, ...)` are special macros defined with
+`using_cmap()`. The `using_cmap_str()` macro expands to:
+```c
+using_cmap(str, cstr_t, cstr_t, cstr_del, cstr_equals_raw, cstr_hash_raw,
+           cstr_del, const char*, cstr_to_raw, cstr_from, const char*, cstr_from)
+```
 
 ## Types
 
@@ -103,7 +106,7 @@ cmap_X_result_t     cmap_X_emplace(cmap_X* self, RawKey rkey, RawMapped rmapped)
 cmap_X_result_t     cmap_X_insert(cmap_X* self, cmap_X_input_t in);
 cmap_X_result_t     cmap_X_insert_or_assign(cmap_X* self, RawKey rkey, RawMapped rmapped);
 cmap_X_result_t     cmap_X_put(cmap_X* self, RawKey rkey, RawMapped rmapped);
-cmap_X_result_t     cmap_X_putv(cmap_X* self, RawKey rkey, Mapped mapped);
+cmap_X_result_t     cmap_X_put_mapped(cmap_X* self, RawKey rkey, Mapped mapped);
 cmap_X_mapped_t*    cmap_X_at(const cmap_X* self, RawKey rkey);
 
 size_t              cmap_X_erase(cmap_X* self, RawKey rkey);
@@ -124,7 +127,7 @@ uint32_t            c_default_hash16(const void *data, size_t len);
 uint32_t            c_default_hash32(const void* data, size_t len);
 ```
 
-## Example
+## Examples
 ```c
 #include <stdio.h>
 #include "stc/cstr.h"
@@ -137,9 +140,9 @@ int main()
     // Create an unordered_map of three strings (that map to strings)
     cmap_str u = cmap_inits;
     c_push_items(&u, cmap_str, {
-        {"RED","#FF0000"},
-        {"GREEN","#00FF00"},
-        {"BLUE","#0000FF"}
+        {"RED", "#FF0000"},
+        {"GREEN", "#00FF00"},
+        {"BLUE", "#0000FF"}
     });
 
     // Iterate and print keys and values of unordered map
@@ -155,6 +158,7 @@ int main()
     printf("The HEX of color RED is:[%s]\n", cmap_str_at(&u, "RED")->str);
     printf("The HEX of color BLACK is:[%s]\n", cmap_str_at(&u, "BLACK")->str);
 
+    cmap_str_del(&u);
     return 0;
 }
 ```
@@ -166,3 +170,38 @@ Key:[BLUE] Value:[#0000FF]
 The HEX of color RED is:[#FF0000]
 The HEX of color BLACK is:[#000000]
 ```
+
+### Example 2
+For illustration, this example uses a cmap with cstr_t as mapped value, instead of `using_strval(id, int)` macro.
+We must therefore pass new constructed cstr_t objects to the map when inserting, instead of `const char*` strings.
+```c
+#include <stc/cstr.h>
+#include <stc/cmap.h>
+
+using_cmap(id, int, cstr_t, cstr_del);
+
+int main()
+{
+    uint32_t col = 0xcc7744ff;
+    cmap_id idnames = cmap_inits;
+    c_push_items(&idnames, cmap_id, {
+        {100, cstr_from("Red")},
+        {110, cstr_from("Blue")},
+        {120, cstr_from_fmt("#%08x", col)},
+    });
+    cmap_id_put(&idnames, 80, cstr_from("White"));
+
+    c_foreach (i, cmap_id, idnames)
+        printf("%d: %s\n", i.val->first, i.val->second.str);
+    puts("");
+
+    cmap_id_del(&idnames);
+}
+```
+Output:
+```c
+80: White
+100: Red
+110: Blue
+120: #cc7744ff
+```
\ No newline at end of file