changeset
refine docs for map.h - issue #548
Sun, 05 Jan 2025 12:40:43 +0100
- author
- Mike Becker <universe@uap-core.de>
- date
- Sun, 05 Jan 2025 12:40:43 +0100
- changeset 1102
- db5e355e5349
- parent 1101
- 2872f287fadc
- child 1103
- 7c1e322b9165
refine docs for map.h - issue #548
| src/cx/map.h | file | annotate | diff | comparison | revisions |
--- a/src/cx/map.h Sun Jan 05 12:07:39 2025 +0100 +++ b/src/cx/map.h Sun Jan 05 12:40:43 2025 +0100 @@ -26,11 +26,11 @@ * POSSIBILITY OF SUCH DAMAGE. */ /** - * \file map.h - * \brief Interface for map implementations. - * \author Mike Becker - * \author Olaf Wintermann - * \copyright 2-Clause BSD License + * @file map.h + * @brief Interface for map implementations. + * @author Mike Becker + * @author Olaf Wintermann + * @copyright 2-Clause BSD License */ #ifndef UCX_MAP_H @@ -89,19 +89,16 @@ /** * Deallocates the entire memory. */ - cx_attr_nonnull void (*deallocate)(struct cx_map_s *map); /** * Removes all elements. */ - cx_attr_nonnull void (*clear)(struct cx_map_s *map); /** * Add or overwrite an element. */ - cx_attr_nonnull int (*put)( CxMap *map, CxHashKey key, @@ -111,8 +108,6 @@ /** * Returns an element. */ - cx_attr_nonnull - cx_attr_nodiscard void *(*get)( const CxMap *map, CxHashKey key @@ -121,15 +116,13 @@ /** * Removes an element. * - * Implementations SHALL check if \p targetbuf is set and copy the elements + * Implementations SHALL check if @p targetbuf is set and copy the elements * to the buffer without invoking any destructor. - * When \p targetbuf is not set, the destructors SHALL be invoked. + * When @p targetbuf is not set, the destructors SHALL be invoked. * - * The function SHALL return zero when the \p key was found and + * The function SHALL return zero when the @p key was found and * non-zero, otherwise. */ - cx_attr_nonnull_arg(1) - cx_attr_access_w(3) int (*remove)( CxMap *map, CxHashKey key, @@ -139,8 +132,6 @@ /** * Creates an iterator for this map. */ - cx_attr_nonnull - cx_attr_nodiscard CxIterator (*iterator)(const CxMap *map, enum cx_map_iterator_type type); }; @@ -162,6 +153,9 @@ * A shared instance of an empty map. * * 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. */ extern CxMap *const cxEmptyMap; @@ -212,6 +206,8 @@ /** * Deallocates the memory of the specified map. * + * Also calls the content destructor functions for each element, if specified. + * * @param map the map to be freed */ static inline void cxMapFree(CxMap *map) { @@ -223,6 +219,8 @@ /** * 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 */ cx_attr_nonnull @@ -241,13 +239,10 @@ return map->collection.size; } - -// 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 + * @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 @@ -264,7 +259,7 @@ * * The elements of the iterator are keys of type 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 @@ -281,7 +276,7 @@ * * The elements of the iterator are key/value pairs of type 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 @@ -299,7 +294,7 @@ /** * Creates a mutating iterator over the values of a map. * - * \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 @@ -314,7 +309,7 @@ * * The elements of the iterator are keys of type 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 @@ -329,7 +324,7 @@ * * The elements of the iterator are key/value pairs of type 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 @@ -343,15 +338,6 @@ #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 - * @param value the value - * @return 0 on success, non-zero value on failure - */ cx_attr_nonnull static inline int cxMapPut( CxMap *map, @@ -361,15 +347,6 @@ 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 - */ cx_attr_nonnull static inline int cxMapPut( CxMap *map, @@ -379,14 +356,6 @@ 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 - */ cx_attr_nonnull static inline int cxMapPut( CxMap *map, @@ -396,14 +365,6 @@ 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 - */ cx_attr_nonnull cx_attr_cstr_arg(2) static inline int cxMapPut( @@ -414,13 +375,6 @@ return map->cl->put(map, cx_hash_key_str(key), value); } -/** - * Retrieves a value by using a key. - * - * @param map the map - * @param key the key - * @return the value - */ cx_attr_nonnull cx_attr_nodiscard static inline void *cxMapGet( @@ -430,13 +384,6 @@ return map->cl->get(map, key); } -/** - * Retrieves a value by using a key. - * - * @param map the map - * @param key the key - * @return the value - */ cx_attr_nonnull cx_attr_nodiscard static inline void *cxMapGet( @@ -446,13 +393,6 @@ 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 - */ cx_attr_nonnull cx_attr_nodiscard static inline void *cxMapGet( @@ -462,13 +402,6 @@ 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 - */ cx_attr_nonnull cx_attr_nodiscard cx_attr_cstr_arg(2) @@ -479,17 +412,6 @@ return map->cl->get(map, cx_hash_key_str(key)); } -/** - * Removes a key/value-pair from the map by using the key. - * - * Always invokes the destructors functions, if any, on the removed element. - * - * @param map the map - * @param key the key - * @return zero on success, non-zero if the key was not found - * - * @see cxMapRemoveAndGet() - */ cx_attr_nonnull static inline int cxMapRemove( CxMap *map, @@ -498,17 +420,6 @@ return map->cl->remove(map, key, nullptr); } -/** - * Removes a key/value-pair from the map by using the key. - * - * Always invokes the destructors functions, if any, on the removed element. - * - * @param map the map - * @param key the key - * @return zero on success, non-zero if the key was not found - * - * @see cxMapRemoveAndGet() - */ cx_attr_nonnull static inline int cxMapRemove( CxMap *map, @@ -517,17 +428,6 @@ return map->cl->remove(map, cx_hash_key_cxstr(key), nullptr); } -/** - * Removes a key/value-pair from the map by using the key. - * - * Always invokes the destructors functions, if any, on the removed element. - * - * @param map the map - * @param key the key - * @return zero on success, non-zero if the key was not found - * - * @see cxMapRemoveAndGet() - */ cx_attr_nonnull static inline int cxMapRemove( CxMap *map, @@ -536,17 +436,6 @@ return map->cl->remove(map, cx_hash_key_cxstr(key), nullptr); } -/** - * Removes a key/value-pair from the map by using the key. - * - * Always invokes the destructors functions, if any, on the removed element. - * - * @param map the map - * @param key the key - * @return zero on success, non-zero if the key was not found - * - * @see cxMapRemoveAndGet() - */ cx_attr_nonnull cx_attr_cstr_arg(2) static inline int cxMapRemove( @@ -556,24 +445,6 @@ return map->cl->remove(map, cx_hash_key_str(key), nullptr); } -/** - * Removes a key/value-pair from the map by using the key. - * - * This function will copy the contents to the target buffer - * which must be guaranteed to be large enough to hold the element. - * The destructor functions, if any, will \em not be called. - * - * If this map is storing pointers, the element is the pointer itself - * and not the object it points to. - * - * @param map the map - * @param key the key - * @param targetbuf the buffer where the element shall be copied to - * @return zero on success, non-zero if the key was not found - * - * @see cxMapStorePointers() - * @see cxMapRemove() - */ cx_attr_nonnull cx_attr_access_w(3) static inline int cxMapRemoveAndGet( @@ -584,24 +455,6 @@ return map->cl->remove(map, key, targetbuf); } -/** - * Removes a key/value-pair from the map by using the key. - * - * This function will copy the contents to the target buffer - * which must be guaranteed to be large enough to hold the element. - * The destructor functions, if any, will \em not be called. - * - * If this map is storing pointers, the element is the pointer itself - * and not the object it points to. - * - * @param map the map - * @param key the key - * @param targetbuf the buffer where the element shall be copied to - * @return zero on success, non-zero if the key was not found - * - * @see cxMapStorePointers() - * @see cxMapRemove() - */ cx_attr_nonnull cx_attr_access_w(3) static inline int cxMapRemoveAndGet( @@ -612,24 +465,6 @@ return map->cl->remove(map, cx_hash_key_cxstr(key), targetbuf); } -/** - * Removes a key/value-pair from the map by using the key. - * - * This function will copy the contents to the target buffer - * which must be guaranteed to be large enough to hold the element. - * The destructor functions, if any, will \em not be called. - * - * If this map is storing pointers, the element is the pointer itself - * and not the object it points to. - * - * @param map the map - * @param key the key - * @param targetbuf the buffer where the element shall be copied to - * @return zero on success, non-zero if the key was not found - * - * @see cxMapStorePointers() - * @see cxMapRemove() - */ cx_attr_nonnull cx_attr_access_w(3) static inline int cxMapRemoveAndGet( @@ -640,24 +475,6 @@ return map->cl->remove(map, cx_hash_key_cxstr(key), targetbuf); } -/** - * Removes a key/value-pair from the map by using the key. - * - * This function will copy the contents to the target buffer - * which must be guaranteed to be large enough to hold the element. - * The destructor functions, if any, will \em not be called. - * - * If this map is storing pointers, the element is the pointer itself - * and not the object it points to. - * - * @param map the map - * @param key the key - * @param targetbuf the buffer where the element shall be copied to - * @return zero on success, non-zero if the key was not found - * - * @see cxMapStorePointers() - * @see cxMapRemove() - */ cx_attr_nonnull cx_attr_access_w(3) cx_attr_cstr_arg(2) @@ -672,12 +489,7 @@ #else // __cplusplus /** - * 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 + * @copydoc cxMapPut() */ cx_attr_nonnull static inline int cx_map_put( @@ -689,12 +501,7 @@ } /** - * 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 + * @copydoc cxMapPut() */ cx_attr_nonnull static inline int cx_map_put_cxstr( @@ -706,12 +513,7 @@ } /** - * 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 + * @copydoc cxMapPut() */ cx_attr_nonnull static inline int cx_map_put_mustr( @@ -723,12 +525,7 @@ } /** - * 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 + * @copydoc cxMapPut() */ cx_attr_nonnull cx_attr_cstr_arg(2) @@ -743,10 +540,19 @@ /** * 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 + * A possible existing value will be overwritten. + * + * If this map is storing pointers, the @p value pointer is written + * to the map. Otherwise, the memory is copied from @p value with + * memcpy(). + * + * The @p key is always copied. + * + * @param map (@c CxMap*) the map + * @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 */ #define cxMapPut(map, key, value) _Generic((key), \ CxHashKey: cx_map_put, \ @@ -757,11 +563,7 @@ (map, key, value) /** - * Retrieves a value by using a key. - * - * @param map the map - * @param key the key - * @return the value + * @copydoc cxMapGet() */ cx_attr_nonnull cx_attr_nodiscard @@ -773,11 +575,7 @@ } /** - * Retrieves a value by using a key. - * - * @param map the map - * @param key the key - * @return the value + * @copydoc cxMapGet() */ cx_attr_nonnull cx_attr_nodiscard @@ -789,11 +587,7 @@ } /** - * Retrieves a value by using a key. - * - * @param map the map - * @param key the key - * @return the value + * @copydoc cxMapGet() */ cx_attr_nonnull cx_attr_nodiscard @@ -805,11 +599,7 @@ } /** - * Retrieves a value by using a key. - * - * @param map the map - * @param key the key - * @return the value + * @copydoc cxMapGet() */ cx_attr_nonnull cx_attr_nodiscard @@ -824,9 +614,13 @@ /** * Retrieves a value by using a key. * - * @param map the map - * @param key the key - * @return the value + * If this map is storing pointers, the stored pointer is returned. + * Otherwise, a pointer to the element within the map's memory + * is returned (which is valid as long as the element stays in the map). + * + * @param map (@c CxMap*) the map + * @param key (@c CxHashKey, @c char*, @c cxstring, or @c cxmutstr) the key + * @return (@c void*) the value */ #define cxMapGet(map, key) _Generic((key), \ CxHashKey: cx_map_get, \ @@ -837,13 +631,7 @@ (map, key) /** - * Removes a key/value-pair from the map by using the key. - * - * Always invokes the destructors functions, if any, on the removed element. - * - * @param map the map - * @param key the key - * @return zero on success, non-zero if the key was not found + * @copydoc cxMapRemove() */ cx_attr_nonnull static inline int cx_map_remove( @@ -854,13 +642,7 @@ } /** - * Removes a key/value-pair from the map by using the key. - * - * Always invokes the destructors functions, if any, on the removed element. - * - * @param map the map - * @param key the key - * @return zero on success, non-zero if the key was not found + * @copydoc cxMapRemove() */ cx_attr_nonnull static inline int cx_map_remove_cxstr( @@ -871,13 +653,7 @@ } /** - * Removes a key/value-pair from the map by using the key. - * - * Always invokes the destructors functions, if any, on the removed element. - * - * @param map the map - * @param key the key - * @return zero on success, non-zero if the key was not found + * @copydoc cxMapRemove() */ cx_attr_nonnull static inline int cx_map_remove_mustr( @@ -888,13 +664,7 @@ } /** - * Removes a key/value-pair from the map by using the key. - * - * Always invokes the destructors functions, if any, on the removed element. - * - * @param map the map - * @param key the key - * @return zero on success, non-zero if the key was not found + * @copydoc cxMapRemove() */ cx_attr_nonnull cx_attr_cstr_arg(2) @@ -910,9 +680,10 @@ * * Always invokes the destructors functions, if any, on the removed element. * - * @param map the map - * @param key the key - * @return zero on success, non-zero if the key was not found + * @param map (@c CxMap*) the map + * @param key (@c CxHashKey, @c char*, @c cxstring, or @c cxmutstr) the key + * @retval zero success + * @retval non-zero the key was not found * * @see cxMapRemoveAndGet() */ @@ -925,19 +696,7 @@ (map, key) /** - * Removes a key/value-pair from the map by using the key. - * - * This function will copy the contents to the target buffer - * which must be guaranteed to be large enough to hold the element. - * The destructor functions, if any, will \em not be called. - * - * If this map is storing pointers, the element is the pointer itself - * and not the object it points to. - * - * @param map the map - * @param key the key - * @param targetbuf the buffer where the element shall be copied to - * @return zero on success, non-zero if the key was not found + * @copydoc cxMapRemoveAndGet() */ cx_attr_nonnull cx_attr_access_w(3) @@ -950,19 +709,7 @@ } /** - * Removes a key/value-pair from the map by using the key. - * - * This function will copy the contents to the target buffer - * which must be guaranteed to be large enough to hold the element. - * The destructor functions, if any, will \em not be called. - * - * If this map is storing pointers, the element is the pointer itself - * and not the object it points to. - * - * @param map the map - * @param key the key - * @param targetbuf the buffer where the element shall be copied to - * @return zero on success, non-zero if the key was not found + * @copydoc cxMapRemoveAndGet() */ cx_attr_nonnull cx_attr_access_w(3) @@ -975,19 +722,7 @@ } /** - * Removes a key/value-pair from the map by using the key. - * - * This function will copy the contents to the target buffer - * which must be guaranteed to be large enough to hold the element. - * The destructor functions, if any, will \em not be called. - * - * If this map is storing pointers, the element is the pointer itself - * and not the object it points to. - * - * @param map the map - * @param key the key - * @param targetbuf the buffer where the element shall be copied to - * @return zero on success, non-zero if the key was not found + * @copydoc cxMapRemoveAndGet() */ cx_attr_nonnull cx_attr_access_w(3) @@ -1000,19 +735,7 @@ } /** - * Removes a key/value-pair from the map by using the key. - * - * This function will copy the contents to the target buffer - * which must be guaranteed to be large enough to hold the element. - * The destructor functions, if any, will \em not be called. - * - * If this map is storing pointers, the element is the pointer itself - * and not the object it points to. - * - * @param map the map - * @param key the key - * @param targetbuf the buffer where the element shall be copied to - * @return zero on success, non-zero if the key was not found + * @copydoc cxMapRemoveAndGet() */ cx_attr_nonnull cx_attr_access_w(3) @@ -1028,17 +751,19 @@ /** * Removes a key/value-pair from the map by using the key. * - * This function will copy the contents to the target buffer - * which must be guaranteed to be large enough to hold the element. - * The destructor functions, if any, will \em not be called. + * This function will copy the contents of the removed element + * to the target buffer 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. * * If this map is storing pointers, the element is the pointer itself * and not the object it points to. * - * @param map the map - * @param key the key - * @param targetbuf the buffer where the element shall be copied to - * @return zero on success, non-zero if the key was not found + * @param map (@c CxMap*) the map + * @param key (@c CxHashKey, @c char*, @c cxstring, or @c cxmutstr) the key + * @param targetbuf (@c void*) the buffer where the element shall be copied to + * @retval zero success + * @retval non-zero the key was not found * * @see cxMapStorePointers() * @see cxMapRemove()
