Mercurial > hg > toolkit / file diff

--- a/ucx/cx/map.h	Wed Dec 17 18:31:20 2025 +0100
+++ b/ucx/cx/map.h	Thu Dec 18 17:50:15 2025 +0100
@@ -183,9 +183,9 @@
      * Add or overwrite an element.
      * If the @p value is @c NULL, the implementation
      * shall only allocate memory instead of adding an existing value to the map.
-     * Returns a pointer to the allocated memory or @c NULL if allocation fails.
+     * Returns a map entry where the pointer to the key is @c NULL if allocation fails.
      */
-    void *(*put)(CxMap *map, CxHashKey key, void *value);
+    CxMapEntry (*put)(CxMap *map, CxHashKey key, void *value);
 
     /**
      * Returns an element.
@@ -357,8 +357,6 @@
  * @param map the map
  * @param key the key
  * @return the pointer to the allocated memory or @c NULL if allocation fails
- * @retval zero success
- * @retval non-zero value on memory allocation failure
  * @see cxMapEmplace()
  */
 cx_attr_nonnull
@@ -379,8 +377,6 @@
  * @param map (@c CxMap*) the map
  * @param key (any supported key type) the key
  * @return the pointer to the allocated memory or @c NULL if allocation fails
- * @retval zero success
- * @retval non-zero value on memory allocation failure
  * @see CX_HASH_KEY()
  */
 #define cxMapEmplace(map, key) cx_map_emplace(map, CX_HASH_KEY(key))
@@ -627,7 +623,7 @@
  * @see cxMapClone()
  */
 cx_attr_nonnull
-CX_EXPORT int cxMapCloneSimple(CxMap *dst, const CxMap *src);
+CX_EXPORT int cxMapCloneShallow(CxMap *dst, const CxMap *src);
 
 /**
  * Clones entries of a map if their key is not present in another map.
@@ -642,7 +638,7 @@
  * @retval non-zero when an allocation error occurred
  */
 cx_attr_nonnull
-CX_EXPORT int cxMapDifferenceSimple(CxMap *dst, const CxMap *minuend, const CxMap *subtrahend);
+CX_EXPORT int cxMapDifferenceShallow(CxMap *dst, const CxMap *minuend, const CxMap *subtrahend);
 
 /**
  * Clones entries of a map if their key is not present in a list.
@@ -663,7 +659,7 @@
  * @see cxMapListDifference()
  */
 cx_attr_nonnull
-CX_EXPORT int cxMapListDifferenceSimple(CxMap *dst, const CxMap *src, const CxList *keys);
+CX_EXPORT int cxMapListDifferenceShallow(CxMap *dst, const CxMap *src, const CxList *keys);
 
 
 /**
@@ -679,7 +675,7 @@
  * @retval non-zero when an allocation error occurred
  */
 cx_attr_nonnull
-CX_EXPORT int cxMapIntersectionSimple(CxMap *dst, const CxMap *src, const CxMap *other);
+CX_EXPORT int cxMapIntersectionShallow(CxMap *dst, const CxMap *src, const CxMap *other);
 
 /**
  * Clones entries of a map only if their key is present in a list.
@@ -699,7 +695,7 @@
  * @retval non-zero when an allocation error occurred
  */
 cx_attr_nonnull
-CX_EXPORT int cxMapListIntersectionSimple(CxMap *dst, const CxMap *src, const CxList *keys);
+CX_EXPORT int cxMapListIntersectionShallow(CxMap *dst, const CxMap *src, const CxList *keys);
 
 /**
  * Clones entries into a map if their key does not exist yet.
@@ -718,7 +714,23 @@
  * @retval non-zero when an allocation error occurred
  */
 cx_attr_nonnull
-CX_EXPORT int cxMapUnionSimple(CxMap *dst, const CxMap *src);
+CX_EXPORT int cxMapUnionShallow(CxMap *dst, const CxMap *src);
+
+
+/**
+ * Compares the entries of two maps.
+ *
+ * @param map the map
+ * @param other the other map that the first map is compared to
+ * @retval zero when both maps have the same key sets
+ * and the values are pairwise equivalent
+ * @retval negative when the first @p map has fewer keys than the @p other map
+ * @retval positive when the first @p map has more keys than the @p other map
+ * @retval non-zero (unspecified whether positive or negative) when the size
+ * of both maps is equal but a key or a value is different
+ */
+cx_attr_nonnull
+CX_EXPORT int cxMapCompare(const CxMap *map, const CxMap *other);
 
 #ifdef    __cplusplus
 } // extern "C"