Mercurial > hg > dbutils / file comparison

comparison: ucx/cx/hash_map.h

ucx/cx/hash_map.h

changeset 16
04c9f8d8f03b
parent 11
0aa8cbd7912e
child 21
5ea41679e15d
equal deleted inserted replaced
15:862ab606ee06 16:04c9f8d8f03b
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 stores pointers instead of
73 * cxMapStorePointers() was called immediately after creation. 73 * copies of the added elements.
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
86 cx_attr_malloc 86 cx_attr_malloc
87 cx_attr_dealloc(cxMapFree, 1) 87 cx_attr_dealloc(cxMapFree, 1)
88 cx_attr_export
88 CxMap *cxHashMapCreate( 89 CxMap *cxHashMapCreate(
89 const CxAllocator *allocator, 90 const CxAllocator *allocator,
90 size_t itemsize, 91 size_t itemsize,
91 size_t buckets 92 size_t buckets
92 ); 93 );
93 94
94 /** 95 /**
95 * Creates a new hash map with a default number of buckets. 96 * Creates a new hash map with a default number of buckets.
96 * 97 *
97 * If \p elem_size is CX_STORE_POINTERS, the created map will be created as if 98 * If @p elem_size is #CX_STORE_POINTERS, the created map stores pointers instead of
98 * cxMapStorePointers() was called immediately after creation. 99 * copies of the added elements.
99 * 100 *
100 * @note Iterators provided by this hash map implementation provide the remove operation. 101 * @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. 102 * 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 . 103 * In other words, when the iterator is finished, @c index==size .
103 * 104 *
104 * @param itemsize the size of one element 105 * @param itemsize (@c size_t) the size of one element
105 * @return a pointer to the new hash map 106 * @return (@c CxMap*) a pointer to the new hash map
106 */ 107 */
107 #define cxHashMapCreateSimple(itemsize) \ 108 #define cxHashMapCreateSimple(itemsize) cxHashMapCreate(NULL, itemsize, 0)
108 cxHashMapCreate(cxDefaultAllocator, itemsize, 0)
109 109
110 /** 110 /**
111 * Increases the number of buckets, if necessary. 111 * Increases the number of buckets, if necessary.
112 * 112 *
113 * The load threshold is \c 0.75*buckets. If the element count exceeds the load 113 * 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 114 * threshold, the map will be rehashed. Otherwise, no action is performed and
115 * this function simply returns 0. 115 * this function simply returns 0.
116 * 116 *
117 * The rehashing process ensures, that the number of buckets is at least 117 * 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 118 * 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. 121 * You can use this function after filling a map to increase access performance.
122 * 122 *
123 * @note If the specified map is not a hash map, the behavior is undefined. 123 * @note If the specified map is not a hash map, the behavior is undefined.
124 * 124 *
125 * @param map the map to rehash 125 * @param map the map to rehash
126 * @return zero on success, non-zero if a memory allocation error occurred 126 * @retval zero success
127 * @retval non-zero if a memory allocation error occurred
127 */ 128 */
128 cx_attr_nonnull 129 cx_attr_nonnull
130 cx_attr_export
129 int cxMapRehash(CxMap *map); 131 int cxMapRehash(CxMap *map);
130 132
131 133
132 #ifdef __cplusplus 134 #ifdef __cplusplus
133 } // extern "C" 135 } // extern "C"

Mercurial Repository: dbutils

mercurial