Mercurial > hg > ucx / changeset

--- a/CHANGELOG	Sun Oct 26 11:50:33 2025 +0100
+++ b/CHANGELOG	Sun Oct 26 12:01:28 2025 +0100
@@ -7,8 +7,9 @@
  + adds support for integer keys to CxHashKey
  * adds support for comparing arbitrary strings without explicit call to cx_strcast()
  * adds cxListClone() and cxMapClone()
+ * adds cxMapDifference() and cxMapListDifference()
+ * adds cxListContains() and cxMapContains()
  * adds cxListSet()
- * adds cxListContains()
  * adds cxListFirst() and cxListLast()
  * adds cxListRemoveAndGetFirst() and cxListRemoveAndGetLast(),
    and corresponding macro aliases cxListPopFront() and cxListPop()

--- a/docs/Writerside/topics/about.md	Sun Oct 26 11:50:33 2025 +0100
+++ b/docs/Writerside/topics/about.md	Sun Oct 26 12:01:28 2025 +0100
@@ -34,8 +34,9 @@
 * adds support for integer keys to CxHashKey
 * adds support for comparing arbitrary strings without explicit call to cx_strcast()
 * adds cxListClone() and cxMapClone()
+* adds cxMapDifference() and cxMapListDifference()
+* adds cxListContains() and cxMapContains()
 * adds cxListSet()
-* adds cxListContains()
 * adds cxListFirst() and cxListLast()
 * adds cxListRemoveAndGetFirst() and cxListRemoveAndGetLast(),
   and corresponding macro aliases cxListPopFront() and cxListPop()

--- a/docs/Writerside/topics/map.h.md	Sun Oct 26 11:50:33 2025 +0100
+++ b/docs/Writerside/topics/map.h.md	Sun Oct 26 12:01:28 2025 +0100
@@ -300,6 +300,18 @@
         cx_clone_func clone_func,
         const CxAllocator *clone_allocator,
         void *data);
+        
+int cxMapDifference(CxMap *dst,
+        const CxMap *minuend, const CxMap *subtrahend,
+        cx_clone_func clone_func,
+        const CxAllocator *clone_allocator,
+        void *data);
+
+int cxMapListDifference(CxMap *dst,
+        const CxMap *src, const CxList *keys,
+        cx_clone_func clone_func,
+        const CxAllocator *clone_allocator,
+        void *data);
 ```
 
 With `cxMapClone()` you can create deep copies of the values in one map and insert them into another map.
@@ -307,9 +319,14 @@
 But when a key already exists in the destination map, the value is overwritten with the clone from the source map.
 If the destination map has destructors defined, they are called for the replaced element.
 
+The functions `cxMapDifference()` and `cxMapListDifference()` are similar to `cxMapClone()`
+except that they only clone an element from the source map, when the key is _not_ contained in the
+other map (or list, respectively).
+This is equivalent to computing the set difference for the set of keys.
+
 Refer to the documentation of the [clone-function callback](allocator.h.md#clone-function) to learn how to implement it.
 
-The function returns zero if and only if all clone operations were successful.
+The functions return zero if and only if all clone operations were successful.
 
 > It is perfectly possible to clone items into a map of a different type.
 > For example, you can clone entries from a map that is just storing pointers (`CX_STORE_POINTERS`) to a map that

--- a/src/cx/map.h	Sun Oct 26 11:50:33 2025 +0100
+++ b/src/cx/map.h	Sun Oct 26 12:01:28 2025 +0100
@@ -508,10 +508,38 @@
         cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data);
 
 
+/**
+ * Clones entries of a map if their key is not present in another map.
+ *
+ * @param dst the destination map
+ * @param minuend the map to subtract the entries from
+ * @param subtrahend the map containing the elements to be subtracted
+ * @param clone_func the clone function for the values
+ * @param clone_allocator the allocator that is passed to the clone function
+ * @param data optional additional data that is passed to the clone function
+ * @retval zero when the elements were successfully cloned
+ * @retval non-zero when an allocation error occurred
+ */
 cx_attr_nonnull_arg(1, 2, 3, 4)
 CX_EXPORT int cxMapDifference(CxMap *dst, const CxMap *minuend, const CxMap *subtrahend,
         cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data);
 
+/**
+ * Clones entries of a map if their key is not present in a list.
+ *
+ * Note that the list must contain keys of type @c CxKey
+ * (or pointers to such keys).
+ * Generic key types cannot be processed in this case.
+ *
+ * @param dst the destination map
+ * @param src the source map
+ * @param keys the list of @c CxKey items
+ * @param clone_func the clone function for the values
+ * @param clone_allocator the allocator that is passed to the clone function
+ * @param data optional additional data that is passed to the clone function
+ * @retval zero when the elements were successfully cloned
+ * @retval non-zero when an allocation error occurred
+ */
 cx_attr_nonnull_arg(1, 2, 3, 4)
 CX_EXPORT int cxMapListDifference(CxMap *dst, const CxMap *src, const CxList *keys,
         cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data);