webserver: comparison src/ucx/cx/map.h

-:eb48f716b31c
+:e10457d74fe1
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */
 /**
-* \file map.h
+* @file map.h
-* \brief Interface for map implementations.
+* @brief Interface for map implementations.
-* \author Mike Becker
+* @author Mike Becker
-* \author Olaf Wintermann
+* @author Olaf Wintermann
-* \version 3.0
+* @copyright 2-Clause BSD License
-* \copyright 2-Clause BSD License
 */
 #ifndef UCX_MAP_H
 #define UCX_MAP_H
 typedef struct cx_map_s CxMap;
 /** Type for a map entry. */
 typedef struct cx_map_entry_s CxMapEntry;
+/** Type for a map iterator. */
+typedef struct cx_map_iterator_s CxMapIterator;
 /** Type for map class definitions. */
 typedef struct cx_map_class_s cx_map_class;
 /** Structure for the UCX map. */
 struct cx_map_s {
-CX_COLLECTION_MEMBERS
+/**
+* Base attributes.
+*/
+CX_COLLECTION_BASE;
 /** The map class definition. */
 cx_map_class *cl;
 };
 /**
+* A map entry.
+*/
+struct cx_map_entry_s {
+/**
+* A pointer to the key.
+*/
+const CxHashKey *key;
+/**
+* A pointer to the value.
+*/
+void *value;
+};
+/**
 * The type of iterator for a map.
 */
 enum cx_map_iterator_type {
 /**
 * Iterates over key/value pairs.
 */
 CX_MAP_ITERATOR_VALUES
 };
 /**
+* Internal iterator struct - use CxMapIterator.
+*/
+struct cx_map_iterator_s {
+/**
+* Inherited common data for all iterators.
+*/
+CX_ITERATOR_BASE;
+/**
+* Handle for the source map.
+*/
+union {
+/**
+* Access for mutating iterators.
+*/
+CxMap *m;
+/**
+* Access for normal iterators.
+*/
+const CxMap *c;
+} map;
+/**
+* Handle for the current element.
+*
+* @attention Depends on the map implementation, do not assume a type (better: do not use!).
+*/
+void *elem;
+/**
+* Reserved memory for a map entry.
+*
+* If a map implementation uses an incompatible layout, the iterator needs something
+* to point to during iteration which @em is compatible.
+*/
+CxMapEntry entry;
+/**
+* Field for storing the current slot number.
+*
+* (Used internally)
+*/
+size_t slot;
+/**
+* Counts the elements successfully.
+* It usually does not denote a stable index within the map as it would be for arrays.
+*/
+size_t index;
+/**
+* The size of a value stored in this map.
+*/
+size_t elem_size;
+/**
+* May contain the total number of elements, if known.
+* Set to @c SIZE_MAX when the total number is unknown during iteration.
+*
+* @remark The UCX implementations of #CxMap always know the number of elements they store.
+*/
+size_t elem_count;
+/**
+* The type of this iterator.
+*/
+enum cx_map_iterator_type type;
+};
+/**
 * The class definition for arbitrary maps.
 */
 struct cx_map_class_s {
 /**
 * Deallocates the entire memory.
 */
-__attribute__((__nonnull__))
+void (*deallocate)(struct cx_map_s *map);
-void (*destructor)(struct cx_map_s *map);
 /**
 * Removes all elements.
 */
-__attribute__((__nonnull__))
 void (*clear)(struct cx_map_s *map);
 /**
 * Add or overwrite an element.
 */
-__attribute__((__nonnull__))
 int (*put)(
 CxMap *map,
 CxHashKey key,
 void *value
 );
 /**
 * Returns an element.
 */
-__attribute__((__nonnull__, __warn_unused_result__))
 void *(*get)(
-CxMap const *map,
+const CxMap *map,
 CxHashKey key
 );
 /**
 * Removes an element.
-*/
+*
-__attribute__((__nonnull__))
+* Implementations SHALL check if @p targetbuf is set and copy the elements
-void *(*remove)(
+* to the buffer without invoking any destructor.
+* When @p targetbuf is not set, the destructors SHALL be invoked.
+*
+* The function SHALL return zero when the @p key was found and
+* non-zero, otherwise.
+*/
+int (*remove)(
 CxMap *map,
 CxHashKey key,
-bool destroy
+void *targetbuf
 );
 /**
 * Creates an iterator for this map.
 */
-__attribute__((__nonnull__, __warn_unused_result__))
+CxMapIterator (*iterator)(const CxMap *map, enum cx_map_iterator_type type);
-CxIterator (*iterator)(CxMap const *map, enum cx_map_iterator_type type);
 };
 /**
-* A map entry.
-*/
-struct cx_map_entry_s {
-/**
-* A pointer to the key.
-*/
-CxHashKey const *key;
-/**
-* A pointer to the value.
-*/
-void *value;
-};
-/**
 * A shared instance of an empty map.
 *
-* Writing to that map is undefined.
+* Writing to that map is not allowed.
-*/
+*
+* You can use this is a placeholder for initializing CxMap pointers
+* for which you do not want to reserve memory right from the beginning.
+*/
+cx_attr_export
 extern CxMap *const cxEmptyMap;
 /**
-* Advises the map to store copies of the objects (default mode of operation).
-*
-* Retrieving objects from this map will yield pointers to the copies stored
-* within this list.
-*
-* @param map the map
-* @see cxMapStorePointers()
-*/
-__attribute__((__nonnull__))
-static inline void cxMapStoreObjects(CxMap *map) {
-map->store_pointer = false;
-}
-/**
-* Advises the map to only store pointers to the objects.
-*
-* Retrieving objects from this list will yield the original pointers stored.
-*
-* @note This function forcibly sets the element size to the size of a pointer.
-* Invoking this function on a non-empty map that already stores copies of
-* objects is undefined.
-*
-* @param map the map
-* @see cxMapStoreObjects()
-*/
-__attribute__((__nonnull__))
-static inline void cxMapStorePointers(CxMap *map) {
-map->store_pointer = true;
-map->item_size = sizeof(void *);
-}
-/**
 * Deallocates the memory of the specified map.
 *
-* @param map the map to be destroyed
+* Also calls the content destructor functions for each element, if specified.
-*/
+*
-__attribute__((__nonnull__))
+* @param map the map to be freed
-static inline void cxMapDestroy(CxMap *map) {
+*/
-map->cl->destructor(map);
+cx_attr_export
-}
+void cxMapFree(CxMap *map);
 /**
 * Clears a map by removing all elements.
 *
+* Also calls the content destructor functions for each element, if specified.
+*
 * @param map the map to be cleared
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 static inline void cxMapClear(CxMap *map) {
 map->cl->clear(map);
 }
+/**
-// TODO: set-like map operations (union, intersect, difference)
+* Returns the number of elements in this map.
+*
+* @param map the map
+* @return the number of stored elements
+*/
+cx_attr_nonnull
+static inline size_t cxMapSize(const CxMap *map) {
+return map->collection.size;
+}
 /**
 * Creates a value iterator for a map.
 *
-* \note An iterator iterates over all elements successively. Therefore the order
+* When the map is storing pointers, those pointers are returned.
+* Otherwise, the iterator iterates over pointers to the memory within the map where the
+* respective elements are stored.
+*
+* @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__))
+cx_attr_nonnull
-static inline CxIterator cxMapIteratorValues(CxMap const *map) {
+cx_attr_nodiscard
+static inline CxMapIterator cxMapIteratorValues(const CxMap *map) {
 return map->cl->iterator(map, CX_MAP_ITERATOR_VALUES);
 }
 /**
 * Creates a key iterator for a map.
 *
-* The elements of the iterator are keys of type CxHashKey.
+* The elements of the iterator are keys of type CxHashKey and the pointer returned
-*
+* during iterator shall be treated as @c const @c CxHashKey* .
-* \note An iterator iterates over all elements successively. Therefore the order
+*
+* @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__))
+cx_attr_nonnull
-static inline CxIterator cxMapIteratorKeys(CxMap const *map) {
+cx_attr_nodiscard
+static inline CxMapIterator cxMapIteratorKeys(const CxMap *map) {
 return map->cl->iterator(map, CX_MAP_ITERATOR_KEYS);
 }
 /**
 * Creates an iterator for a map.
 *
-* The elements of the iterator are key/value pairs of type CxMapEntry.
+* The elements of the iterator are key/value pairs of type CxMapEntry and the pointer returned
-*
+* during iterator shall be treated as @c const @c CxMapEntry* .
-* \note An iterator iterates over all elements successively. Therefore the order
+*
+* @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__))
+cx_attr_nonnull
-static inline CxIterator cxMapIterator(CxMap const *map) {
+cx_attr_nodiscard
+static inline CxMapIterator cxMapIterator(const CxMap *map) {
 return map->cl->iterator(map, CX_MAP_ITERATOR_PAIRS);
 }
 /**
 * Creates a mutating iterator over the values of a map.
 *
-* \note An iterator iterates over all elements successively. Therefore the order
+* When the map is storing pointers, those pointers are returned.
+* Otherwise, the iterator iterates over pointers to the memory within the map where the
+* respective elements are stored.
+*
+* @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__))
+cx_attr_nonnull
-CxMutIterator cxMapMutIteratorValues(CxMap *map);
+cx_attr_nodiscard
+cx_attr_export
+CxMapIterator cxMapMutIteratorValues(CxMap *map);
 /**
 * Creates a mutating iterator over the keys of a map.
 *
-* The elements of the iterator are keys of type CxHashKey.
+* The elements of the iterator are keys of type CxHashKey and the pointer returned
-*
+* during iterator shall be treated as @c const @c CxHashKey* .
-* \note An iterator iterates over all elements successively. Therefore the order
+*
+* @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__))
+cx_attr_nonnull
-CxMutIterator cxMapMutIteratorKeys(CxMap *map);
+cx_attr_nodiscard
+cx_attr_export
+CxMapIterator cxMapMutIteratorKeys(CxMap *map);
 /**
 * Creates a mutating iterator for a map.
 *
-* The elements of the iterator are key/value pairs of type CxMapEntry.
+* The elements of the iterator are key/value pairs of type CxMapEntry and the pointer returned
-*
+* during iterator shall be treated as @c const @c CxMapEntry* .
-* \note An iterator iterates over all elements successively. Therefore the order
+*
+* @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__))
+cx_attr_nonnull
-CxMutIterator cxMapMutIterator(CxMap *map);
+cx_attr_nodiscard
+cx_attr_export
+CxMapIterator cxMapMutIterator(CxMap *map);
 #ifdef __cplusplus
 } // end the extern "C" block here, because we want to start overloading
+cx_attr_nonnull
-/**
-* 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,
 CxHashKey const &key,
 void *value
 ) {
 return map->cl->put(map, key, value);
 }
+cx_attr_nonnull
-/**
-* 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);
 }
-/**
+cx_attr_nonnull
-* 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,
 cxmutstr const &key,
 void *value
 ) {
 return map->cl->put(map, cx_hash_key_cxstr(key), value);
 }
-/**
+cx_attr_nonnull
-* Puts a key/value-pair into the map.
+cx_attr_cstr_arg(2)
-*
-* @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,
+const char *key,
 void *value
 ) {
 return map->cl->put(map, cx_hash_key_str(key), value);
 }
-/**
+cx_attr_nonnull
-* Retrieves a value by using a key.
+cx_attr_nodiscard
-*
-* @param map the map
-* @param key the key
-* @return the value
-*/
-__attribute__((__nonnull__, __warn_unused_result__))
 static inline void *cxMapGet(
-CxMap const *map,
+const CxMap *map,
 CxHashKey const &key
 ) {
 return map->cl->get(map, key);
 }
-/**
+cx_attr_nonnull
-* Retrieves a value by using a key.
+cx_attr_nodiscard
-*
-* @param map the map
-* @param key the key
-* @return the value
-*/
-__attribute__((__nonnull__, __warn_unused_result__))
 static inline void *cxMapGet(
-CxMap const *map,
+const CxMap *map,
 cxstring const &key
 ) {
 return map->cl->get(map, cx_hash_key_cxstr(key));
 }
-/**
+cx_attr_nonnull
-* Retrieves a value by using a key.
+cx_attr_nodiscard
-*
-* @param map the map
-* @param key the key
-* @return the value
-*/
-__attribute__((__nonnull__, __warn_unused_result__))
 static inline void *cxMapGet(
-CxMap const *map,
+const CxMap *map,
 cxmutstr const &key
 ) {
 return map->cl->get(map, cx_hash_key_cxstr(key));
 }
-/**
+cx_attr_nonnull
-* Retrieves a value by using a key.
+cx_attr_nodiscard
-*
+cx_attr_cstr_arg(2)
-* @param map the map
-* @param key the key
-* @return the value
-*/
-__attribute__((__nonnull__, __warn_unused_result__))
 static inline void *cxMapGet(
-CxMap const *map,
+const CxMap *map,
-char const *key
+const char *key
 ) {
 return map->cl->get(map, cx_hash_key_str(key));
 }
-/**
+cx_attr_nonnull
-* Removes a key/value-pair from the map by using the key.
+static inline int cxMapRemove(
-*
-* 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,
 CxHashKey const &key
 ) {
-(void) map->cl->remove(map, key, true);
+return map->cl->remove(map, key, nullptr);
 }
-/**
+cx_attr_nonnull
-* Removes a key/value-pair from the map by using the key.
+static inline int cxMapRemove(
-*
-* 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);
+return map->cl->remove(map, cx_hash_key_cxstr(key), nullptr);
 }
-/**
+cx_attr_nonnull
-* Removes a key/value-pair from the map by using the key.
+static inline int cxMapRemove(
-*
-* 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,
 cxmutstr const &key
 ) {
-(void) map->cl->remove(map, cx_hash_key_cxstr(key), true);
+return map->cl->remove(map, cx_hash_key_cxstr(key), nullptr);
 }
-/**
+cx_attr_nonnull
-* Removes a key/value-pair from the map by using the key.
+cx_attr_cstr_arg(2)
-*
+static inline int cxMapRemove(
-* Always invokes the destructor function, if any, on the removed element.
+CxMap *map,
-* If this map is storing pointers and you just want to retrieve the pointer
+const char *key
-* without invoking the destructor, use cxMapRemoveAndGet().
+) {
-* If you just want to detach the element from the map without invoking the
+return map->cl->remove(map, cx_hash_key_str(key), nullptr);
-* destructor or returning the element, use cxMapDetach().
+}
-*
-* @param map the map
+cx_attr_nonnull
-* @param key the key
+cx_attr_access_w(3)
-* @see cxMapRemoveAndGet()
+static inline int cxMapRemoveAndGet(
-* @see cxMapDetach()
+CxMap *map,
-*/
+CxHashKey key,
-__attribute__((__nonnull__))
+void *targetbuf
-static inline void cxMapRemove(
+) {
-CxMap *map,
+return map->cl->remove(map, key, targetbuf);
-char const *key
+}
-) {
-(void) map->cl->remove(map, cx_hash_key_str(key), true);
+cx_attr_nonnull
-}
+cx_attr_access_w(3)
+static inline int cxMapRemoveAndGet(
-/**
+CxMap *map,
-* Detaches a key/value-pair from the map by using the key
+cxstring key,
-* without invoking the destructor.
+void *targetbuf
-*
+) {
-* In general, you should only use this function if the map does not own
+return map->cl->remove(map, cx_hash_key_cxstr(key), targetbuf);
-* 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().
+cx_attr_nonnull
-*
+cx_attr_access_w(3)
-* @param map the map
+static inline int cxMapRemoveAndGet(
-* @param key the key
+CxMap *map,
-* @see cxMapRemove()
+cxmutstr key,
-* @see cxMapRemoveAndGet()
+void *targetbuf
-*/
+) {
-__attribute__((__nonnull__))
+return map->cl->remove(map, cx_hash_key_cxstr(key), targetbuf);
-static inline void cxMapDetach(
+}
-CxMap *map,
-CxHashKey const &key
+cx_attr_nonnull
-) {
+cx_attr_access_w(3)
-(void) map->cl->remove(map, key, false);
+cx_attr_cstr_arg(2)
-}
+static inline int cxMapRemoveAndGet(
+CxMap *map,
-/**
+const char *key,
-* Detaches a key/value-pair from the map by using the key
+void *targetbuf
-* without invoking the destructor.
+) {
-*
+return map->cl->remove(map, cx_hash_key_str(key), targetbuf);
-* 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,
-cxmutstr 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.
-*
-* 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()
-*/
-__attribute__((__nonnull__, __warn_unused_result__))
-static inline void *cxMapRemoveAndGet(
-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.
-*
-* 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()
-*/
-__attribute__((__nonnull__, __warn_unused_result__))
-static inline void *cxMapRemoveAndGet(
-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.
-*
-* 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()
-*/
-__attribute__((__nonnull__, __warn_unused_result__))
-static inline void *cxMapRemoveAndGet(
-CxMap *map,
-cxmutstr 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.
-*
-* 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()
-*/
-__attribute__((__nonnull__, __warn_unused_result__))
-static inline void *cxMapRemoveAndGet(
-CxMap *map,
-char const *key
-) {
-return map->cl->remove(map, cx_hash_key_str(key), !map->store_pointer);
 }
 #else // __cplusplus
 /**
-* Puts a key/value-pair into the map.
+* @copydoc cxMapPut()
-*
+*/
-* @param map the map
+cx_attr_nonnull
-* @param key the key
-* @param value the value
-* @return 0 on success, non-zero value on failure
-*/
-__attribute__((__nonnull__))
 static inline int cx_map_put(
 CxMap *map,
 CxHashKey key,
 void *value
 ) {
 return map->cl->put(map, key, value);
 }
 /**
-* Puts a key/value-pair into the map.
+* @copydoc cxMapPut()
-*
+*/
-* @param map the map
+cx_attr_nonnull
-* @param key the key
-* @param value the value
-* @return 0 on success, non-zero value on failure
-*/
-__attribute__((__nonnull__))
 static inline int cx_map_put_cxstr(
 CxMap *map,
 cxstring key,
 void *value
 ) {
 return map->cl->put(map, cx_hash_key_cxstr(key), value);
 }
 /**
-* Puts a key/value-pair into the map.
+* @copydoc cxMapPut()
-*
+*/
-* @param map the map
+cx_attr_nonnull
-* @param key the key
-* @param value the value
-* @return 0 on success, non-zero value on failure
-*/
-__attribute__((__nonnull__))
 static inline int cx_map_put_mustr(
 CxMap *map,
 cxmutstr key,
 void *value
 ) {
 return map->cl->put(map, cx_hash_key_cxstr(key), value);
 }
 /**
+* @copydoc cxMapPut()
+*/
+cx_attr_nonnull
+cx_attr_cstr_arg(2)
+static inline int cx_map_put_str(
+CxMap *map,
+const char *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
+* A possible existing value will be overwritten.
-* @param key the key
+* If destructor functions are specified, they are called for
-* @param value the value
+* the overwritten element.
-* @return 0 on success, non-zero value on failure
+*
-*/
+* If this map is storing pointers, the @p value pointer is written
-__attribute__((__nonnull__))
+* to the map. Otherwise, the memory is copied from @p value with
-static inline int cx_map_put_str(
+* memcpy().
-CxMap *map,
+*
-char const *key,
+* The @p key is always copied.
-void *value
+*
-) {
+* @param map (@c CxMap*) the map
-return map->cl->put(map, cx_hash_key_str(key), value);
+* @param key (@c CxHashKey, @c char*, @c cxstring, or @c cxmutstr) the key
-}
+* @param value (@c void*) the value
+* @retval zero success
-/**
+* @retval non-zero value on memory allocation failure
-* 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,                   \
 cxmutstr: cx_map_put_mustr,                   \
 char*: cx_map_put_str,                        \
-char const*: cx_map_put_str)                  \
+const char*: cx_map_put_str)                  \
 (map, key, value)
 /**
+* @copydoc cxMapGet()
+*/
+cx_attr_nonnull
+cx_attr_nodiscard
+static inline void *cx_map_get(
+const CxMap *map,
+CxHashKey key
+) {
+return map->cl->get(map, key);
+}
+/**
+* @copydoc cxMapGet()
+*/
+cx_attr_nonnull
+cx_attr_nodiscard
+static inline void *cx_map_get_cxstr(
+const CxMap *map,
+cxstring key
+) {
+return map->cl->get(map, cx_hash_key_cxstr(key));
+}
+/**
+* @copydoc cxMapGet()
+*/
+cx_attr_nonnull
+cx_attr_nodiscard
+static inline void *cx_map_get_mustr(
+const CxMap *map,
+cxmutstr key
+) {
+return map->cl->get(map, cx_hash_key_cxstr(key));
+}
+/**
+* @copydoc cxMapGet()
+*/
+cx_attr_nonnull
+cx_attr_nodiscard
+cx_attr_cstr_arg(2)
+static inline void *cx_map_get_str(
+const CxMap *map,
+const char *key
+) {
+return map->cl->get(map, cx_hash_key_str(key));
+}
+/**
 * Retrieves a value by using a key.
 *
-* @param map the map
+* If this map is storing pointers, the stored pointer is returned.
-* @param key the key
+* Otherwise, a pointer to the element within the map's memory
-* @return the value
+* is returned (which is valid as long as the element stays in the map).
-*/
+*
-__attribute__((__nonnull__, __warn_unused_result__))
+* @param map (@c CxMap*) the map
-static inline void *cx_map_get(
+* @param key (@c CxHashKey, @c char*, @c cxstring, or @c cxmutstr) the key
-CxMap const *map,
+* @return (@c void*) the value
-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_mustr(
-CxMap const *map,
-cxmutstr 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,            \
 cxmutstr: cx_map_get_mustr,            \
 char*: cx_map_get_str,                 \
-char const*: cx_map_get_str)           \
+const char*: cx_map_get_str)           \
 (map, key)
 /**
+* @copydoc cxMapRemove()
+*/
+cx_attr_nonnull
+static inline int cx_map_remove(
+CxMap *map,
+CxHashKey key
+) {
+return map->cl->remove(map, key, NULL);
+}
+/**
+* @copydoc cxMapRemove()
+*/
+cx_attr_nonnull
+static inline int cx_map_remove_cxstr(
+CxMap *map,
+cxstring key
+) {
+return map->cl->remove(map, cx_hash_key_cxstr(key), NULL);
+}
+/**
+* @copydoc cxMapRemove()
+*/
+cx_attr_nonnull
+static inline int cx_map_remove_mustr(
+CxMap *map,
+cxmutstr key
+) {
+return map->cl->remove(map, cx_hash_key_cxstr(key), NULL);
+}
+/**
+* @copydoc cxMapRemove()
+*/
+cx_attr_nonnull
+cx_attr_cstr_arg(2)
+static inline int cx_map_remove_str(
+CxMap *map,
+const char *key
+) {
+return map->cl->remove(map, cx_hash_key_str(key), NULL);
+}
+/**
 * Removes a key/value-pair from the map by using the key.
 *
-* @param map the map
+* Always invokes the destructors functions, if any, on the removed element.
-* @param key the key
+*
-*/
+* @param map (@c CxMap*) the map
-__attribute__((__nonnull__))
+* @param key (@c CxHashKey, @c char*, @c cxstring, or @c cxmutstr) the key
-static inline void cx_map_remove(
+* @retval zero success
-CxMap *map,
+* @retval non-zero the key was not found
-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_mustr(
-CxMap *map,
-cxmutstr 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,            \
 cxmutstr: cx_map_remove_mustr,            \
 char*: cx_map_remove_str,                 \
-char const*: cx_map_remove_str)           \
+const char*: cx_map_remove_str)           \
 (map, key)
 /**
-* Detaches a key/value-pair from the map by using the key
+* @copydoc cxMapRemoveAndGet()
-* without invoking the destructor.
+*/
-*
+cx_attr_nonnull
-* @param map the map
+cx_attr_access_w(3)
-* @param key the key
+static inline int cx_map_remove_and_get(
-*/
+CxMap *map,
-__attribute__((__nonnull__))
+CxHashKey key,
-static inline void cx_map_detach(
+void *targetbuf
-CxMap *map,
+) {
-CxHashKey key
+return map->cl->remove(map, key, targetbuf);
-) {
+}
-(void) map->cl->remove(map, key, false);
-}
+/**
+* @copydoc cxMapRemoveAndGet()
-/**
+*/
-* Detaches a key/value-pair from the map by using the key
+cx_attr_nonnull
-* without invoking the destructor.
+cx_attr_access_w(3)
-*
+static inline int cx_map_remove_and_get_cxstr(
-* @param map the map
+CxMap *map,
-* @param key the key
+cxstring key,
-*/
+void *targetbuf
-__attribute__((__nonnull__))
+) {
-static inline void cx_map_detach_cxstr(
+return map->cl->remove(map, cx_hash_key_cxstr(key), targetbuf);
-CxMap *map,
+}
-cxstring key
-) {
+/**
-(void) map->cl->remove(map, cx_hash_key_cxstr(key), false);
+* @copydoc cxMapRemoveAndGet()
-}
+*/
+cx_attr_nonnull
-/**
+cx_attr_access_w(3)
-* Detaches a key/value-pair from the map by using the key
+static inline int cx_map_remove_and_get_mustr(
-* without invoking the destructor.
+CxMap *map,
-*
+cxmutstr key,
-* @param map the map
+void *targetbuf
-* @param key the key
+) {
-*/
+return map->cl->remove(map, cx_hash_key_cxstr(key), targetbuf);
-__attribute__((__nonnull__))
+}
-static inline void cx_map_detach_mustr(
-CxMap *map,
+/**
-cxmutstr key
+* @copydoc cxMapRemoveAndGet()
-) {
+*/
-(void) map->cl->remove(map, cx_hash_key_cxstr(key), false);
+cx_attr_nonnull
-}
+cx_attr_access_w(3)
+cx_attr_cstr_arg(2)
-/**
+static inline int cx_map_remove_and_get_str(
-* Detaches a key/value-pair from the map by using the key
+CxMap *map,
-* without invoking the destructor.
+const char *key,
-*
+void *targetbuf
-* @param map the map
+) {
-* @param key the key
+return map->cl->remove(map, cx_hash_key_str(key), targetbuf);
-*/
+}
-__attribute__((__nonnull__))
-static inline void cx_map_detach_str(
+/**
-CxMap *map,
+* Removes a key/value-pair from the map by using the key.
-char const *key
+*
-) {
+* This function will copy the contents of the removed element
-(void) map->cl->remove(map, cx_hash_key_str(key), false);
+* to the target buffer, which must be guaranteed to be large enough
-}
+* to hold the element (the map's element size).
+* The destructor functions, if any, will @em not be called.
-/**
+*
-* Detaches a key/value-pair from the map by using the key
+* If this map is storing pointers, the element is the pointer itself
-* without invoking the destructor.
+* and not the object it points to.
 *
-* In general, you should only use this function if the map does not own
+* @param map (@c CxMap*) the map
-* the data and there is a valid reference to the data somewhere else
+* @param key (@c CxHashKey, @c char*, @c cxstring, or @c cxmutstr) the key
-* in the program. In all other cases it is preferable to use
+* @param targetbuf (@c void*) the buffer where the element shall be copied to
-* cxMapRemove() or cxMapRemoveAndGet().
+* @retval zero success
-*
+* @retval non-zero the key was not found
-* @param map the map
+*
-* @param key the key
 * @see cxMapRemove()
-* @see cxMapRemoveAndGet()
+*/
-*/
+#define cxMapRemoveAndGet(map, key, targetbuf) _Generic((key), \
-#define cxMapDetach(map, key) _Generic((key), \
-CxHashKey: cx_map_detach,                 \
-cxstring: cx_map_detach_cxstr,            \
-cxmutstr: cx_map_detach_mustr,            \
-char*: cx_map_detach_str,                 \
-char const*: 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_mustr(
-CxMap *map,
-cxmutstr 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,          \
 cxmutstr: cx_map_remove_and_get_mustr,          \
 char*: cx_map_remove_and_get_str,               \
-char const*: cx_map_remove_and_get_str)         \
+const char*: cx_map_remove_and_get_str)         \
-(map, key)
+(map, key, targetbuf)
 #endif // __cplusplus
 #endif // UCX_MAP_H

Mercurial > hg > webserver / file comparison

comparison: src/ucx/cx/map.h

src/ucx/cx/map.h