Added cmap_emplace_key() / csmap_emplace_key()

More docs.

1 files changed, 7 insertions, 1 deletions

diff --git a/docs/cmap_api.md b/docs/cmap_api.md
index 17f27662..4e6da57d 100644
--- a/docs/cmap_api.md
+++ b/docs/cmap_api.md
@@ -71,7 +71,8 @@ cmap_X_result         cmap_X_insert_or_assign(cmap_X* self, i_key key, i_val map
 cmap_X_result         cmap_X_push(cmap_X* self, cmap_X_value entry);                    // similar to insert
 
 cmap_X_result         cmap_X_emplace(cmap_X* self, i_keyraw rkey, i_valraw rmapped);    // no change if rkey in map
-cmap_X_result         cmap_X_emplace_or_assign(cmap_X* self, i_keyraw rkey, i_valraw rmapped); // always update
+cmap_X_result         cmap_X_emplace_or_assign(cmap_X* self, i_keyraw rkey, i_valraw rmapped); // always update mapped
+cmap_X_result         cmap_X_emplace_key(cmap_X* self, i_keyraw rkey);                 // see example 1.
 
 int                   cmap_X_erase(cmap_X* self, i_keyraw rkey);                        // return 0 or 1
 cmap_X_iter           cmap_X_erase_at(cmap_X* self, cmap_X_iter it);                    // return iter after it
@@ -138,6 +139,11 @@ int main(void)
     cmap_str_emplace(&umap, "BLACK", "#000000");
     cmap_str_emplace(&umap, "WHITE", "#FFFFFF");
 
+    // Insert only if "CYAN" is not in the map: create mapped value when needed only.
+    cmap_str_result res = cmap_str_emplace_key(&umap, "CYAN");
+    if (res.inserted)
+        res.ref->second = cstr_from("#00FFFF"); // must assign second if key was inserted.
+
     // Output values by key
     printf("The HEX of color RED is:[%s]\n", cstr_str(cmap_str_at(&umap, "RED")));
     printf("The HEX of color BLACK is:[%s]\n", cstr_str(cmap_str_at(&umap, "BLACK")));