dav: comparison ucx/cx/map.h

-:e77ccf1c4bb3
+:4d58cbcc9efa
 /**
 * 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.
 */
 void *(*get)(const CxMap *map, CxHashKey key);
 * The @p key is always copied.
 *
 * @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
 CX_EXPORT void *cx_map_emplace(CxMap *map, CxHashKey key);
 * The @p key is always copied.
 *
 * @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))
 /**
 */
 cx_attr_nonnull_arg(1, 2, 3)
 CX_EXPORT int cxMapUnion(CxMap *dst, const CxMap *src,
 cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data);
+/**
+* Performs a shallow clone of one map into another.
+*
+* This function uses the default allocator, if needed, and performs
+* shallow clones with @c memcpy().
+*
+* If the destination map already contains entries, the cloned entries
+* are added to that map, possibly overwriting existing elements when
+* the keys already exist.
+*
+* When elements in the destination map need to be replaced, any destructor
+* function is called on the replaced elements before replacing them.
+*
+* @attention If the cloned elements need to be destroyed by a destructor
+* function, you must make sure that the destination map also uses this
+* destructor function.
+*
+* @param dst the destination map
+* @param src the source map
+* @retval zero when all elements were successfully cloned
+* @retval non-zero when an allocation error occurred
+* @see cxMapClone()
+*/
+cx_attr_nonnull
+CX_EXPORT int cxMapCloneShallow(CxMap *dst, const CxMap *src);
+/**
+* Clones entries of a map if their key is not present in another map.
+*
+* This function uses the default allocator, if needed, and performs
+* shallow clones with @c memcpy().
+*
+* @param dst the destination map
+* @param minuend the map to subtract the entries from
+* @param subtrahend the map containing the elements to be subtracted
+* @retval zero when the elements were successfully cloned
+* @retval non-zero when an allocation error occurred
+*/
+cx_attr_nonnull
+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.
+*
+* This function uses the default allocator, if needed, and performs
+* shallow clones with @c memcpy().
+*
+* Note that the list must contain keys of type @c CxKey
+* (or pointers to such keys) and must use @c cx_hash_key_cmp
+* as the compare function.
+* 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
+* @retval zero when the elements were successfully cloned
+* @retval non-zero when an allocation error occurred
+* @see cxMapListDifference()
+*/
+cx_attr_nonnull
+CX_EXPORT int cxMapListDifferenceShallow(CxMap *dst, const CxMap *src, const CxList *keys);
+/**
+* Clones entries of a map only if their key is present in another map.
+*
+* This function uses the default allocator, if needed, and performs
+* shallow clones with @c memcpy().
+*
+* @param dst the destination map
+* @param src the map to clone the entries from
+* @param other the map to check for existence of the keys
+* @retval zero when the elements were successfully cloned
+* @retval non-zero when an allocation error occurred
+*/
+cx_attr_nonnull
+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.
+*
+* This function uses the default allocator, if needed, and performs
+* shallow clones with @c memcpy().
+*
+* Note that the list must contain keys of type @c CxKey
+* (or pointers to such keys) and must use @c cx_hash_key_cmp
+* as the compare function.
+* 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
+* @retval zero when the elements were successfully cloned
+* @retval non-zero when an allocation error occurred
+*/
+cx_attr_nonnull
+CX_EXPORT int cxMapListIntersectionShallow(CxMap *dst, const CxMap *src, const CxList *keys);
+/**
+* Clones entries into a map if their key does not exist yet.
+*
+* This function uses the default allocator, if needed, and performs
+* shallow clones with @c memcpy().
+*
+* If you want to calculate the union of two maps into a fresh new map,
+* you can proceed as follows:
+* 1. Clone the first map into a fresh, empty map.
+* 2. Use this function to clone the second map into the result from step 1.
+*
+* @param dst the destination map
+* @param src the map to clone the entries from
+* @retval zero when the elements were successfully cloned
+* @retval non-zero when an allocation error occurred
+*/
+cx_attr_nonnull
+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"
 #endif
 #endif // UCX_MAP_H

Mercurial > hg > dav / file comparison

comparison: ucx/cx/map.h

ucx/cx/map.h