Mercurial > hg > toolkit / file comparison

comparison: ucx/cx/hash_map.h

ucx/cx/hash_map.h

changeset 440
7c4b9cba09ca
parent 324
ce13a778654a
equal deleted inserted replaced
439:bf7084544cb1 440:7c4b9cba09ca
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26 * POSSIBILITY OF SUCH DAMAGE. 26 * POSSIBILITY OF SUCH DAMAGE.
27 */ 27 */
28 /** 28 /**
29 * \file hash_map.h 29 * @file hash_map.h
30 * \brief Hash map implementation. 30 * @brief Hash map implementation.
31 * \author Mike Becker 31 * @author Mike Becker
32 * \author Olaf Wintermann 32 * @author Olaf Wintermann
33 * \copyright 2-Clause BSD License 33 * @copyright 2-Clause BSD License
34 */ 34 */
35 35
36 #ifndef UCX_HASH_MAP_H 36 #ifndef UCX_HASH_MAP_H
37 #define UCX_HASH_MAP_H 37 #define UCX_HASH_MAP_H
38 38
65 65
66 66
67 /** 67 /**
68 * Creates a new hash map with the specified number of buckets. 68 * Creates a new hash map with the specified number of buckets.
69 * 69 *
70 * If \p buckets is zero, an implementation defined default will be used. 70 * If @p buckets is zero, an implementation defined default will be used.
71 * 71 *
72 * If \p elem_size is CX_STORE_POINTERS, the created map will be created as if 72 * If @p elem_size is CX_STORE_POINTERS, the created map will be created as if
73 * cxMapStorePointers() was called immediately after creation. 73 * cxMapStorePointers() was called immediately after creation.
74 * 74 *
75 * @note Iterators provided by this hash map implementation provide the remove operation. 75 * @note Iterators provided by this hash map implementation provide the remove operation.
76 * The index value of an iterator is incremented when the iterator advanced without removal. 76 * The index value of an iterator is incremented when the iterator advanced without removal.
77 * In other words, when the iterator is finished, \c index==size . 77 * In other words, when the iterator is finished, @c index==size .
78 * 78 *
79 * @param allocator the allocator to use 79 * @param allocator the allocator to use
80 * (if @c NULL, a default stdlib allocator will be used)
80 * @param itemsize the size of one element 81 * @param itemsize the size of one element
81 * @param buckets the initial number of buckets in this hash map 82 * @param buckets the initial number of buckets in this hash map
82 * @return a pointer to the new hash map 83 * @return a pointer to the new hash map
83 */ 84 */
84 __attribute__((__nonnull__, __warn_unused_result__)) 85 cx_attr_nodiscard
86 cx_attr_malloc
87 cx_attr_dealloc(cxMapFree, 1)
85 CxMap *cxHashMapCreate( 88 CxMap *cxHashMapCreate(
86 const CxAllocator *allocator, 89 const CxAllocator *allocator,
87 size_t itemsize, 90 size_t itemsize,
88 size_t buckets 91 size_t buckets
89 ); 92 );
90 93
91 /** 94 /**
92 * Creates a new hash map with a default number of buckets. 95 * Creates a new hash map with a default number of buckets.
93 * 96 *
94 * If \p elem_size is CX_STORE_POINTERS, the created map will be created as if 97 * If @p elem_size is CX_STORE_POINTERS, the created map will be created as if
95 * cxMapStorePointers() was called immediately after creation. 98 * cxMapStorePointers() was called immediately after creation.
96 * 99 *
97 * @note Iterators provided by this hash map implementation provide the remove operation. 100 * @note Iterators provided by this hash map implementation provide the remove operation.
98 * The index value of an iterator is incremented when the iterator advanced without removal. 101 * The index value of an iterator is incremented when the iterator advanced without removal.
99 * In other words, when the iterator is finished, \c index==size . 102 * In other words, when the iterator is finished, @c index==size .
100 * 103 *
101 * @param itemsize the size of one element 104 * @param itemsize (@c size_t) the size of one element
102 * @return a pointer to the new hash map 105 * @return (@c CxMap*) a pointer to the new hash map
103 */ 106 */
104 #define cxHashMapCreateSimple(itemsize) \ 107 #define cxHashMapCreateSimple(itemsize) cxHashMapCreate(NULL, itemsize, 0)
105 cxHashMapCreate(cxDefaultAllocator, itemsize, 0)
106 108
107 /** 109 /**
108 * Increases the number of buckets, if necessary. 110 * Increases the number of buckets, if necessary.
109 * 111 *
110 * The load threshold is \c 0.75*buckets. If the element count exceeds the load 112 * The load threshold is @c 0.75*buckets. If the element count exceeds the load
111 * threshold, the map will be rehashed. Otherwise, no action is performed and 113 * threshold, the map will be rehashed. Otherwise, no action is performed and
112 * this function simply returns 0. 114 * this function simply returns 0.
113 * 115 *
114 * The rehashing process ensures, that the number of buckets is at least 116 * The rehashing process ensures, that the number of buckets is at least
115 * 2.5 times the element count. So there is enough room for additional 117 * 2.5 times the element count. So there is enough room for additional
118 * You can use this function after filling a map to increase access performance. 120 * You can use this function after filling a map to increase access performance.
119 * 121 *
120 * @note If the specified map is not a hash map, the behavior is undefined. 122 * @note If the specified map is not a hash map, the behavior is undefined.
121 * 123 *
122 * @param map the map to rehash 124 * @param map the map to rehash
123 * @return zero on success, non-zero if a memory allocation error occurred 125 * @retval zero success
126 * @retval non-zero if a memory allocation error occurred
124 */ 127 */
125 __attribute__((__nonnull__)) 128 cx_attr_nonnull
126 int cxMapRehash(CxMap *map); 129 int cxMapRehash(CxMap *map);
127 130
128 131
129 #ifdef __cplusplus 132 #ifdef __cplusplus
130 } // extern "C" 133 } // extern "C"

Mercurial Repository: toolkit

mercurial