Mercurial > hg > ucx / file diff

--- a/docs/Writerside/topics/map.h.md	Fri Aug 15 17:46:47 2025 +0200
+++ b/docs/Writerside/topics/map.h.md	Sun Aug 17 23:05:16 2025 +0200
@@ -193,21 +193,28 @@
 #include <cx/map.h>
 
 int cxMapPut(CxMap *map, KeyType key, void *value);
+
+void *cxMapEmplace(CxMap *map, KeyType key);
 ```
 
-The function `cxMapPut()` stores the specified `key` / `value` pair.
+The function `cxMapPut()` stores the specified `key` / `value` pair,
+and returns zero if the element was successfully put into the map and non-zero otherwise.
 
 The key is always copied.
 The behavior for the value is dependent on whether the map is storing pointers.
 If it is storing pointers, the `value` pointer is directly stored in the map.
 Otherwise, the memory pointed to by `value` is copied, using the element size of the collection.
 
-If an element is already associated with the specified key, it is replaced.
+The function `cxMapEmplace()` is similar to `cxMapPut()`, but instead of adding an existing value to the map,
+it returns a pointer to newly allocated memory for the value.
+The memory is allocated using the allocator of the map.
+If the map is storing pointers, the allocated memory will only be that for a pointer.
+Otherwise, the memory is allocated using the known element size.
+
+Both functions, if an element is already associated with the specified key, replace the existing element.
 If [destructor functions](collection.h.md#destructor-functions) are registered,
 they are invoked for the old element before it is replaced.
 
-This function returns zero if the element was successfully put into the map and non-zero otherwise.
-
 ## Access
 
 ```C