ucx: comparison src/cx/map.h

-:2c2304622981
+:65baf7f45ac8
 #ifndef UCX_MAP_H
 #define UCX_MAP_H
 #include "common.h"
 #include "collection.h"
+#include "string.h"
 #include "hash_key.h"
 #ifdef    __cplusplus
 extern "C" {
 #endif
 __attribute__((__nonnull__))
 static inline void cxMapClear(CxMap *map) {
 map->cl->clear(map);
 }
+// TODO: set-like map operations (union, intersect, difference)
+/**
+* Creates a value iterator for a map.
+*
+* \note An iterator iterates over all elements successively. Therefore the order
+* highly depends on the map implementation and may change arbitrarily when the contents change.
+*
+* @param map the map to create the iterator for
+* @return an iterator for the currently stored values
+*/
+__attribute__((__nonnull__, __warn_unused_result__))
+static inline CxIterator cxMapIteratorValues(CxMap *map) {
+return map->cl->iterator_values(map);
+}
+/**
+* Creates a key iterator for a map.
+*
+* The elements of the iterator are keys of type CxHashKey.
+*
+* \note An iterator iterates over all elements successively. Therefore the order
+* highly depends on the map implementation and may change arbitrarily when the contents change.
+*
+* @param map the map to create the iterator for
+* @return an iterator for the currently stored keys
+*/
+__attribute__((__nonnull__, __warn_unused_result__))
+static inline CxIterator cxMapIteratorKeys(CxMap *map) {
+return map->cl->iterator_keys(map);
+}
+/**
+* Creates an iterator for a map.
+*
+* The elements of the iterator are key/value pairs of type CxMapEntry.
+*
+* \note An iterator iterates over all elements successively. Therefore the order
+* highly depends on the map implementation and may change arbitrarily when the contents change.
+*
+* @param map the map to create the iterator for
+* @return an iterator for the currently stored entries
+* @see cxMapIteratorKeys()
+* @see cxMapIteratorValues()
+*/
+__attribute__((__nonnull__, __warn_unused_result__))
+static inline CxIterator cxMapIterator(CxMap *map) {
+return map->cl->iterator(map);
+}
+/**
+* Creates a mutating iterator over the values of a map.
+*
+* \note An iterator iterates over all elements successively. Therefore the order
+* highly depends on the map implementation and may change arbitrarily when the contents change.
+*
+* @param map the map to create the iterator for
+* @return an iterator for the currently stored values
+*/
+__attribute__((__nonnull__, __warn_unused_result__))
+static inline CxMutIterator cxMapMutIteratorValues(CxMap *map) {
+return map->cl->mut_iterator_values(map);
+}
+/**
+* Creates a mutating iterator over the keys of a map.
+*
+* The elements of the iterator are keys of type CxHashKey.
+*
+* \note An iterator iterates over all elements successively. Therefore the order
+* highly depends on the map implementation and may change arbitrarily when the contents change.
+*
+* @param map the map to create the iterator for
+* @return an iterator for the currently stored keys
+*/
+__attribute__((__nonnull__, __warn_unused_result__))
+static inline CxMutIterator cxMapMutIteratorKeys(CxMap *map) {
+return map->cl->mut_iterator_keys(map);
+}
+/**
+* Creates a mutating iterator for a map.
+*
+* The elements of the iterator are key/value pairs of type CxMapEntry.
+*
+* \note An iterator iterates over all elements successively. Therefore the order
+* highly depends on the map implementation and may change arbitrarily when the contents change.
+*
+* @param map the map to create the iterator for
+* @return an iterator for the currently stored entries
+* @see cxMapMutIteratorKeys()
+* @see cxMapMutIteratorValues()
+*/
+__attribute__((__nonnull__, __warn_unused_result__))
+static inline CxMutIterator cxMapMutIterator(CxMap *map) {
+return map->cl->mut_iterator(map);
+}
+#ifdef __cplusplus
+} // end the extern "C" block here, because we want to start overloading
 /**
 * Puts a key/value-pair into the map.
 *
 * @param map the map
 * @param key the key
 * @return 0 on success, non-zero value on failure
 */
 __attribute__((__nonnull__))
 static inline int cxMapPut(
 CxMap *map,
-CxHashKey key,
+CxHashKey const &key,
 void *value
 ) {
 return map->cl->put(map, key, value);
+}
+/**
+* Puts a key/value-pair into the map.
+*
+* @param map the map
+* @param key the key
+* @param value the value
+* @return 0 on success, non-zero value on failure
+*/
+__attribute__((__nonnull__))
+static inline int cxMapPut(
+CxMap *map,
+cxstring const &key,
+void *value
+) {
+return map->cl->put(map, cx_hash_key_cxstr(key), value);
+}
+/**
+* Puts a key/value-pair into the map.
+*
+* @param map the map
+* @param key the key
+* @param value the value
+* @return 0 on success, non-zero value on failure
+*/
+__attribute__((__nonnull__))
+static inline int cxMapPut(
+CxMap *map,
+char const *key,
+void *value
+) {
+return map->cl->put(map, cx_hash_key_str(key), value);
 }
 /**
 * Retrieves a value by using a key.
 *
 * @return the value
 */
 __attribute__((__nonnull__, __warn_unused_result__))
 static inline void *cxMapGet(
 CxMap const *map,
-CxHashKey key
+CxHashKey const &key
 ) {
 return map->cl->get(map, key);
+}
+/**
+* Retrieves a value by using a key.
+*
+* @param map the map
+* @param key the key
+* @return the value
+*/
+__attribute__((__nonnull__, __warn_unused_result__))
+static inline void *cxMapGet(
+CxMap const *map,
+cxstring const &key
+) {
+return map->cl->get(map, cx_hash_key_cxstr(key));
+}
+/**
+* Retrieves a value by using a key.
+*
+* @param map the map
+* @param key the key
+* @return the value
+*/
+__attribute__((__nonnull__, __warn_unused_result__))
+static inline void *cxMapGet(
+CxMap const *map,
+char const *key
+) {
+return map->cl->get(map, cx_hash_key_str(key));
 }
 /**
 * Removes a key/value-pair from the map by using the key.
 *
 * @see cxMapDetach()
 */
 __attribute__((__nonnull__))
 static inline void cxMapRemove(
 CxMap *map,
-CxHashKey key
+CxHashKey const &key
 ) {
 (void) map->cl->remove(map, key, true);
+}
+/**
+* Removes a key/value-pair from the map by using the key.
+*
+* Always invokes the destructor function, if any, on the removed element.
+* If this map is storing pointers and you just want to retrieve the pointer
+* without invoking the destructor, use cxMapRemoveAndGet().
+* If you just want to detach the element from the map without invoking the
+* destructor or returning the element, use cxMapDetach().
+*
+* @param map the map
+* @param key the key
+* @see cxMapRemoveAndGet()
+* @see cxMapDetach()
+*/
+__attribute__((__nonnull__))
+static inline void cxMapRemove(
+CxMap *map,
+cxstring const &key
+) {
+(void) map->cl->remove(map, cx_hash_key_cxstr(key), true);
+}
+/**
+* Removes a key/value-pair from the map by using the key.
+*
+* Always invokes the destructor function, if any, on the removed element.
+* If this map is storing pointers and you just want to retrieve the pointer
+* without invoking the destructor, use cxMapRemoveAndGet().
+* If you just want to detach the element from the map without invoking the
+* destructor or returning the element, use cxMapDetach().
+*
+* @param map the map
+* @param key the key
+* @see cxMapRemoveAndGet()
+* @see cxMapDetach()
+*/
+__attribute__((__nonnull__))
+static inline void cxMapRemove(
+CxMap *map,
+char const *key
+) {
+(void) map->cl->remove(map, cx_hash_key_str(key), true);
 }
 /**
 * Detaches a key/value-pair from the map by using the key
 * without invoking the destructor.
 * @see cxMapRemoveAndGet()
 */
 __attribute__((__nonnull__))
 static inline void cxMapDetach(
 CxMap *map,
-CxHashKey key
+CxHashKey const &key
 ) {
 (void) map->cl->remove(map, key, false);
+}
+/**
+* Detaches a key/value-pair from the map by using the key
+* without invoking the destructor.
+*
+* In general, you should only use this function if the map does not own
+* the data and there is a valid reference to the data somewhere else
+* in the program. In all other cases it is preferable to use
+* cxMapRemove() or cxMapRemoveAndGet().
+*
+* @param map the map
+* @param key the key
+* @see cxMapRemove()
+* @see cxMapRemoveAndGet()
+*/
+__attribute__((__nonnull__))
+static inline void cxMapDetach(
+CxMap *map,
+cxstring const &key
+) {
+(void) map->cl->remove(map, cx_hash_key_cxstr(key), false);
+}
+/**
+* Detaches a key/value-pair from the map by using the key
+* without invoking the destructor.
+*
+* In general, you should only use this function if the map does not own
+* the data and there is a valid reference to the data somewhere else
+* in the program. In all other cases it is preferable to use
+* cxMapRemove() or cxMapRemoveAndGet().
+*
+* @param map the map
+* @param key the key
+* @see cxMapRemove()
+* @see cxMapRemoveAndGet()
+*/
+__attribute__((__nonnull__))
+static inline void cxMapDetach(
+CxMap *map,
+char const *key
+) {
+(void) map->cl->remove(map, cx_hash_key_str(key), false);
 }
 /**
 * Removes a key/value-pair from the map by using the key.
 *
 CxHashKey key
 ) {
 return map->cl->remove(map, key, !map->store_pointer);
 }
-// TODO: set-like map operations (union, intersect, difference)
+/**
+* Removes a key/value-pair from the map by using the key.
-/**
+*
-* Creates a value iterator for a map.
+* This function can be used when the map is storing pointers,
-*
+* in order to retrieve the pointer from the map without invoking
-* \note An iterator iterates over all elements successively. Therefore the order
+* any destructor function. Sometimes you do not want the pointer
-* highly depends on the map implementation and may change arbitrarily when the contents change.
+* to be returned - in that case (instead of suppressing the "unused
-*
+* result" warning) you can use cxMapDetach().
-* @param map the map to create the iterator for
+*
-* @return an iterator for the currently stored values
+* If this map is not storing pointers, this function behaves like
-*/
+* cxMapRemove() and returns \c NULL.
-__attribute__((__nonnull__, __warn_unused_result__))
+*
-static inline CxIterator cxMapIteratorValues(CxMap *map) {
+* @param map the map
-return map->cl->iterator_values(map);
+* @param key the key
-}
+* @return the stored pointer or \c NULL if either the key is not present
+* in the map or the map is not storing pointers
-/**
+* @see cxMapStorePointers()
-* Creates a key iterator for a map.
+* @see cxMapDetach()
-*
+*/
-* The elements of the iterator are keys of type CxHashKey.
+__attribute__((__nonnull__, __warn_unused_result__))
-*
+static inline void *cxMapRemoveAndGet(
-* \note An iterator iterates over all elements successively. Therefore the order
+CxMap *map,
-* highly depends on the map implementation and may change arbitrarily when the contents change.
+cxstring key
-*
+) {
-* @param map the map to create the iterator for
+return map->cl->remove(map, cx_hash_key_cxstr(key), !map->store_pointer);
-* @return an iterator for the currently stored keys
+}
-*/
-__attribute__((__nonnull__, __warn_unused_result__))
+/**
-static inline CxIterator cxMapIteratorKeys(CxMap *map) {
+* Removes a key/value-pair from the map by using the key.
-return map->cl->iterator_keys(map);
+*
-}
+* This function can be used when the map is storing pointers,
+* in order to retrieve the pointer from the map without invoking
-/**
+* any destructor function. Sometimes you do not want the pointer
-* Creates an iterator for a map.
+* to be returned - in that case (instead of suppressing the "unused
-*
+* result" warning) you can use cxMapDetach().
-* The elements of the iterator are key/value pairs of type CxMapEntry.
+*
-*
+* If this map is not storing pointers, this function behaves like
-* \note An iterator iterates over all elements successively. Therefore the order
+* cxMapRemove() and returns \c NULL.
-* highly depends on the map implementation and may change arbitrarily when the contents change.
+*
-*
+* @param map the map
-* @param map the map to create the iterator for
+* @param key the key
-* @return an iterator for the currently stored entries
+* @return the stored pointer or \c NULL if either the key is not present
-* @see cxMapIteratorKeys()
+* in the map or the map is not storing pointers
-* @see cxMapIteratorValues()
+* @see cxMapStorePointers()
-*/
+* @see cxMapDetach()
-__attribute__((__nonnull__, __warn_unused_result__))
+*/
-static inline CxIterator cxMapIterator(CxMap *map) {
+__attribute__((__nonnull__, __warn_unused_result__))
-return map->cl->iterator(map);
+static inline void *cxMapRemoveAndGet(
-}
+CxMap *map,
+char const *key
+) {
-/**
+return map->cl->remove(map, cx_hash_key_str(key), !map->store_pointer);
-* Creates a mutating iterator over the values of a map.
+}
-*
-* \note An iterator iterates over all elements successively. Therefore the order
+#else // __cplusplus
-* highly depends on the map implementation and may change arbitrarily when the contents change.
-*
+/**
-* @param map the map to create the iterator for
+* Puts a key/value-pair into the map.
-* @return an iterator for the currently stored values
+*
-*/
+* @param map the map
-__attribute__((__nonnull__, __warn_unused_result__))
+* @param key the key
-static inline CxMutIterator cxMapMutIteratorValues(CxMap *map) {
+* @param value the value
-return map->cl->mut_iterator_values(map);
+* @return 0 on success, non-zero value on failure
-}
+*/
+__attribute__((__nonnull__))
-/**
+static inline int cx_map_put(
-* Creates a mutating iterator over the keys of a map.
+CxMap *map,
-*
+CxHashKey key,
-* The elements of the iterator are keys of type CxHashKey.
+void *value
-*
+) {
-* \note An iterator iterates over all elements successively. Therefore the order
+return map->cl->put(map, key, value);
-* highly depends on the map implementation and may change arbitrarily when the contents change.
+}
-*
-* @param map the map to create the iterator for
+/**
-* @return an iterator for the currently stored keys
+* Puts a key/value-pair into the map.
-*/
+*
-__attribute__((__nonnull__, __warn_unused_result__))
+* @param map the map
-static inline CxMutIterator cxMapMutIteratorKeys(CxMap *map) {
+* @param key the key
-return map->cl->mut_iterator_keys(map);
+* @param value the value
-}
+* @return 0 on success, non-zero value on failure
+*/
-/**
+__attribute__((__nonnull__))
-* Creates a mutating iterator for a map.
+static inline int cx_map_put_cxstr(
-*
+CxMap *map,
-* The elements of the iterator are key/value pairs of type CxMapEntry.
+cxstring key,
-*
+void *value
-* \note An iterator iterates over all elements successively. Therefore the order
+) {
-* highly depends on the map implementation and may change arbitrarily when the contents change.
+return map->cl->put(map, cx_hash_key_cxstr(key), value);
-*
+}
-* @param map the map to create the iterator for
-* @return an iterator for the currently stored entries
+/**
-* @see cxMapMutIteratorKeys()
+* Puts a key/value-pair into the map.
-* @see cxMapMutIteratorValues()
+*
-*/
+* @param map the map
-__attribute__((__nonnull__, __warn_unused_result__))
+* @param key the key
-static inline CxMutIterator cxMapMutIterator(CxMap *map) {
+* @param value the value
-return map->cl->mut_iterator(map);
+* @return 0 on success, non-zero value on failure
-}
+*/
+__attribute__((__nonnull__))
-#ifdef    __cplusplus
+static inline int cx_map_put_str(
-}
+CxMap *map,
-#endif
+char const *key,
+void *value
+) {
+return map->cl->put(map, cx_hash_key_str(key), value);
+}
+/**
+* Puts a key/value-pair into the map.
+*
+* @param map the map
+* @param key the key
+* @param value the value
+* @return 0 on success, non-zero value on failure
+*/
+#define cxMapPut(map, key, value) _Generic((key), \
+CxHashKey: cx_map_put,                        \
+cxstring: cx_map_put_cxstr,                   \
+char*: cx_map_put_str)                        \
+(map, key, value)
+/**
+* Retrieves a value by using a key.
+*
+* @param map the map
+* @param key the key
+* @return the value
+*/
+__attribute__((__nonnull__, __warn_unused_result__))
+static inline void *cx_map_get(
+CxMap const *map,
+CxHashKey key
+) {
+return map->cl->get(map, key);
+}
+/**
+* Retrieves a value by using a key.
+*
+* @param map the map
+* @param key the key
+* @return the value
+*/
+__attribute__((__nonnull__, __warn_unused_result__))
+static inline void *cx_map_get_cxstr(
+CxMap const *map,
+cxstring key
+) {
+return map->cl->get(map, cx_hash_key_cxstr(key));
+}
+/**
+* Retrieves a value by using a key.
+*
+* @param map the map
+* @param key the key
+* @return the value
+*/
+__attribute__((__nonnull__, __warn_unused_result__))
+static inline void *cx_map_get_str(
+CxMap const *map,
+char const *key
+) {
+return map->cl->get(map, cx_hash_key_str(key));
+}
+/**
+* Retrieves a value by using a key.
+*
+* @param map the map
+* @param key the key
+* @return the value
+*/
+#define cxMapGet(map, key) _Generic((key), \
+CxHashKey: cx_map_get,                 \
+cxstring: cx_map_get_cxstr,            \
+char*: cx_map_get_str)                 \
+(map, key)
+/**
+* Removes a key/value-pair from the map by using the key.
+*
+* @param map the map
+* @param key the key
+*/
+__attribute__((__nonnull__))
+static inline void cx_map_remove(
+CxMap *map,
+CxHashKey key
+) {
+(void) map->cl->remove(map, key, true);
+}
+/**
+* Removes a key/value-pair from the map by using the key.
+*
+* @param map the map
+* @param key the key
+*/
+__attribute__((__nonnull__))
+static inline void cx_map_remove_cxstr(
+CxMap *map,
+cxstring key
+) {
+(void) map->cl->remove(map, cx_hash_key_cxstr(key), true);
+}
+/**
+* Removes a key/value-pair from the map by using the key.
+*
+* @param map the map
+* @param key the key
+*/
+__attribute__((__nonnull__))
+static inline void cx_map_remove_str(
+CxMap *map,
+char const *key
+) {
+(void) map->cl->remove(map, cx_hash_key_str(key), true);
+}
+/**
+* Removes a key/value-pair from the map by using the key.
+*
+* Always invokes the destructor function, if any, on the removed element.
+* If this map is storing pointers and you just want to retrieve the pointer
+* without invoking the destructor, use cxMapRemoveAndGet().
+* If you just want to detach the element from the map without invoking the
+* destructor or returning the element, use cxMapDetach().
+*
+* @param map the map
+* @param key the key
+* @see cxMapRemoveAndGet()
+* @see cxMapDetach()
+*/
+#define cxMapRemove(map, key) _Generic((key), \
+CxHashKey: cx_map_remove,                 \
+cxstring: cx_map_remove_cxstr,            \
+char*: cx_map_remove_str)                 \
+(map, key)
+/**
+* Detaches a key/value-pair from the map by using the key
+* without invoking the destructor.
+*
+* @param map the map
+* @param key the key
+*/
+__attribute__((__nonnull__))
+static inline void cx_map_detach(
+CxMap *map,
+CxHashKey key
+) {
+(void) map->cl->remove(map, key, false);
+}
+/**
+* Detaches a key/value-pair from the map by using the key
+* without invoking the destructor.
+*
+* @param map the map
+* @param key the key
+*/
+__attribute__((__nonnull__))
+static inline void cx_map_detach_cxstr(
+CxMap *map,
+cxstring key
+) {
+(void) map->cl->remove(map, cx_hash_key_cxstr(key), false);
+}
+/**
+* Detaches a key/value-pair from the map by using the key
+* without invoking the destructor.
+*
+* @param map the map
+* @param key the key
+*/
+__attribute__((__nonnull__))
+static inline void cx_map_detach_str(
+CxMap *map,
+char const *key
+) {
+(void) map->cl->remove(map, cx_hash_key_str(key), false);
+}
+/**
+* Detaches a key/value-pair from the map by using the key
+* without invoking the destructor.
+*
+* In general, you should only use this function if the map does not own
+* the data and there is a valid reference to the data somewhere else
+* in the program. In all other cases it is preferable to use
+* cxMapRemove() or cxMapRemoveAndGet().
+*
+* @param map the map
+* @param key the key
+* @see cxMapRemove()
+* @see cxMapRemoveAndGet()
+*/
+#define cxMapDetach(map, key) _Generic((key), \
+CxHashKey: cx_map_detach,                 \
+cxstring: cx_map_detach_cxstr,            \
+char*: cx_map_detach_str)                 \
+(map, key)
+/**
+* Removes a key/value-pair from the map by using the key.
+*
+* @param map the map
+* @param key the key
+* @return the stored pointer or \c NULL if either the key is not present
+* in the map or the map is not storing pointers
+*/
+__attribute__((__nonnull__, __warn_unused_result__))
+static inline void *cx_map_remove_and_get(
+CxMap *map,
+CxHashKey key
+) {
+return map->cl->remove(map, key, !map->store_pointer);
+}
+/**
+* Removes a key/value-pair from the map by using the key.
+*
+* @param map the map
+* @param key the key
+* @return the stored pointer or \c NULL if either the key is not present
+* in the map or the map is not storing pointers
+*/
+__attribute__((__nonnull__, __warn_unused_result__))
+static inline void *cx_map_remove_and_get_cxstr(
+CxMap *map,
+cxstring key
+) {
+return map->cl->remove(map, cx_hash_key_cxstr(key), !map->store_pointer);
+}
+/**
+* Removes a key/value-pair from the map by using the key.
+*
+* @param map the map
+* @param key the key
+* @return the stored pointer or \c NULL if either the key is not present
+* in the map or the map is not storing pointers
+*/
+__attribute__((__nonnull__, __warn_unused_result__))
+static inline void *cx_map_remove_and_get_str(
+CxMap *map,
+char const *key
+) {
+return map->cl->remove(map, cx_hash_key_str(key), !map->store_pointer);
+}
+/**
+* Removes a key/value-pair from the map by using the key.
+*
+* This function can be used when the map is storing pointers,
+* in order to retrieve the pointer from the map without invoking
+* any destructor function. Sometimes you do not want the pointer
+* to be returned - in that case (instead of suppressing the "unused
+* result" warning) you can use cxMapDetach().
+*
+* If this map is not storing pointers, this function behaves like
+* cxMapRemove() and returns \c NULL.
+*
+* @param map the map
+* @param key the key
+* @return the stored pointer or \c NULL if either the key is not present
+* in the map or the map is not storing pointers
+* @see cxMapStorePointers()
+* @see cxMapDetach()
+*/
+#define cxMapRemoveAndGet(map, key) _Generic((key), \
+CxHashKey: cx_map_remove_and_get,               \
+cxstring: cx_map_remove_and_get_cxstr,          \
+char*: cx_map_remove_and_get_str)               \
+(map, key)
+#endif // __cplusplus
 #endif // UCX_MAP_H

Mercurial > hg > ucx / file comparison

comparison: src/cx/map.h

src/cx/map.h