Mercurial > hg > ucx / file comparison

comparison: src/cx/hash_map.h

src/cx/hash_map.h

changeset 1095
a5b0e47fc7de
parent 993
b642eca4b956
child 1111
78eeeb950883
equal deleted inserted replaced
1094:aea6f31a82d7 1095:a5b0e47fc7de
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 * (if @c NULL, a default stdlib allocator will be used)
81 * @param itemsize the size of one element 81 * @param itemsize the size of one element
82 * @param buckets the initial number of buckets in this hash map 82 * @param buckets the initial number of buckets in this hash map
83 * @return a pointer to the new hash map 83 * @return a pointer to the new hash map
84 */ 84 */
85 cx_attr_nodiscard 85 cx_attr_nodiscard
92 ); 92 );
93 93
94 /** 94 /**
95 * Creates a new hash map with a default number of buckets. 95 * Creates a new hash map with a default number of buckets.
96 * 96 *
97 * 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
98 * cxMapStorePointers() was called immediately after creation. 98 * cxMapStorePointers() was called immediately after creation.
99 * 99 *
100 * @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.
101 * 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.
102 * In other words, when the iterator is finished, \c index==size . 102 * In other words, when the iterator is finished, @c index==size .
103 * 103 *
104 * @param itemsize the size of one element 104 * @param itemsize (@c size_t) the size of one element
105 * @return a pointer to the new hash map 105 * @return (@c CxMap*) a pointer to the new hash map
106 */ 106 */
107 #define cxHashMapCreateSimple(itemsize) \ 107 #define cxHashMapCreateSimple(itemsize) cxHashMapCreate(NULL, itemsize, 0)
108 cxHashMapCreate(cxDefaultAllocator, itemsize, 0)
109 108
110 /** 109 /**
111 * Increases the number of buckets, if necessary. 110 * Increases the number of buckets, if necessary.
112 * 111 *
113 * 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
114 * 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
115 * this function simply returns 0. 114 * this function simply returns 0.
116 * 115 *
117 * 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
118 * 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
121 * 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.
122 * 121 *
123 * @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.
124 * 123 *
125 * @param map the map to rehash 124 * @param map the map to rehash
126 * @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
127 */ 127 */
128 cx_attr_nonnull 128 cx_attr_nonnull
129 int cxMapRehash(CxMap *map); 129 int cxMapRehash(CxMap *map);
130 130
131 131

Mercurial Repository: ucx

mercurial