Mercurial > hg > ucx / file comparison

comparison: src/cx/kv_list.h

src/cx/kv_list.h

changeset 1675
36c0fb2b60b2
parent 1605
55b13f583356
equal deleted inserted replaced
1674:8b0f162ac88e 1675:36c0fb2b60b2
38 38
39 #include "common.h" 39 #include "common.h"
40 #include "list.h" 40 #include "list.h"
41 #include "map.h" 41 #include "map.h"
42 42
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
46
47 /** 43 /**
48 * Allocates a linked list with a lookup-map for storing elements with @p elem_size bytes each. 44 * Allocates a linked list with a lookup-map for storing elements with @p elem_size bytes each.
49 * 45 *
50 * If @p elem_size is #CX_STORE_POINTERS, the created list stores pointers instead of 46 * If @p elem_size is #CX_STORE_POINTERS, the created list stores pointers instead of
51 * copies of the added elements, and the compare function will be automatically set 47 * copies of the added elements, and the compare function will be automatically set
61 * @param elem_size the size of each element in bytes 57 * @param elem_size the size of each element in bytes
62 * @return the created list 58 * @return the created list
63 * @see cxKvListAsMap() 59 * @see cxKvListAsMap()
64 * @see cxKvListAsList() 60 * @see cxKvListAsList()
65 */ 61 */
66 cx_attr_nodiscard cx_attr_malloc cx_attr_dealloc(cxListFree, 1) 62 CX_EXTERN CX_NODISCARD CX_MALLOC CX_DEALLOC(cxListFree, 1)
67 CX_EXPORT CxList *cxKvListCreate(const CxAllocator *allocator, 63 CxList *cxKvListCreate(const CxAllocator *allocator,
68 size_t elem_size); 64 size_t elem_size);
69 65
70 /** 66 /**
71 * Allocates a linked list with a lookup-map for storing elements with @p elem_size bytes each. 67 * Allocates a linked list with a lookup-map for storing elements with @p elem_size bytes each.
72 * 68 *
83 * @param elem_size the size of each element in bytes 79 * @param elem_size the size of each element in bytes
84 * @return the created list wrapped into the CxMap interface 80 * @return the created list wrapped into the CxMap interface
85 * @see cxKvListAsMap() 81 * @see cxKvListAsMap()
86 * @see cxKvListAsList() 82 * @see cxKvListAsList()
87 */ 83 */
88 cx_attr_nodiscard cx_attr_malloc cx_attr_dealloc(cxMapFree, 1) 84 CX_EXTERN CX_NODISCARD CX_MALLOC CX_DEALLOC(cxMapFree, 1)
89 CX_EXPORT CxMap *cxKvListCreateAsMap(const CxAllocator *allocator, 85 CxMap *cxKvListCreateAsMap(const CxAllocator *allocator,
90 size_t elem_size); 86 size_t elem_size);
91 87
92 /** 88 /**
93 * Converts a map pointer belonging to a key-value-List back to the original list pointer. 89 * Converts a map pointer belonging to a key-value-List back to the original list pointer.
94 * 90 *
95 * @param map a map pointer that was returned by a call to cxKvListAsMap() 91 * @param map a map pointer that was returned by a call to cxKvListAsMap()
96 * @return the original list pointer 92 * @return the original list pointer
97 */ 93 */
98 cx_attr_nodiscard cx_attr_nonnull cx_attr_returns_nonnull 94 CX_EXTERN CX_NODISCARD CX_NONNULL CX_RETURNS_NONNULL
99 CX_EXPORT CxList *cxKvListAsList(CxMap *map); 95 CxList *cxKvListAsList(CxMap *map);
100 96
101 /** 97 /**
102 * Converts a map pointer belonging to a key-value-List back to the original list pointer. 98 * Converts a map pointer belonging to a key-value-List back to the original list pointer.
103 * 99 *
104 * @param list a list created by cxKvListCreate() 100 * @param list a list created by cxKvListCreate()
105 * @return a map pointer that lets you use the list as if it was a map 101 * @return a map pointer that lets you use the list as if it was a map
106 */ 102 */
107 cx_attr_nodiscard cx_attr_nonnull cx_attr_returns_nonnull 103 CX_EXTERN CX_NODISCARD CX_NONNULL CX_RETURNS_NONNULL
108 CX_EXPORT CxMap *cxKvListAsMap(CxList *list); 104 CxMap *cxKvListAsMap(CxList *list);
109 105
110 /** 106 /**
111 * Sets or updates the key of a list item. 107 * Sets or updates the key of a list item.
112 * 108 *
113 * This is, for example, useful when you have inserted an element using the CxList interface, 109 * This is, for example, useful when you have inserted an element using the CxList interface,
118 * @param key the key 114 * @param key the key
119 * @retval zero success 115 * @retval zero success
120 * @retval non-zero memory allocation failure or the index is out of bounds 116 * @retval non-zero memory allocation failure or the index is out of bounds
121 * @see cxKvListSetKey() 117 * @see cxKvListSetKey()
122 */ 118 */
123 cx_attr_nonnull 119 CX_EXTERN CX_NONNULL
124 CX_EXPORT int cx_kv_list_set_key(CxList *list, size_t index, CxHashKey key); 120 int cx_kv_list_set_key(CxList *list, size_t index, CxHashKey key);
125 121
126 /** 122 /**
127 * Inserts an item into the list at the specified index and associates it with the specified key. 123 * Inserts an item into the list at the specified index and associates it with the specified key.
128 * 124 *
129 * @param list the list 125 * @param list the list
132 * @param value the value 128 * @param value the value
133 * @retval zero success 129 * @retval zero success
134 * @retval non-zero memory allocation failure or the index is out of bounds 130 * @retval non-zero memory allocation failure or the index is out of bounds
135 * @see cxKvListInsert() 131 * @see cxKvListInsert()
136 */ 132 */
137 cx_attr_nonnull 133 CX_EXTERN CX_NONNULL
138 CX_EXPORT int cx_kv_list_insert(CxList *list, size_t index, CxHashKey key, void *value); 134 int cx_kv_list_insert(CxList *list, size_t index, CxHashKey key, void *value);
139 135
140 /** 136 /**
141 * Sets or updates the key of a list item. 137 * Sets or updates the key of a list item.
142 * 138 *
143 * This is, for example, useful when you have inserted an element using the CxList interface, 139 * This is, for example, useful when you have inserted an element using the CxList interface,
163 * @retval non-zero memory allocation failure or the index is out of bounds 159 * @retval non-zero memory allocation failure or the index is out of bounds
164 * @see CX_HASH_KEY() 160 * @see CX_HASH_KEY()
165 */ 161 */
166 #define cxKvListInsert(list, index, key, value) cx_kv_list_insert(list, index, CX_HASH_KEY(key), value) 162 #define cxKvListInsert(list, index, key, value) cx_kv_list_insert(list, index, CX_HASH_KEY(key), value)
167 163
168
169 /** 164 /**
170 * Removes the key of a list item. 165 * Removes the key of a list item.
171 * 166 *
172 * This can be useful if you want to explicitly remove an item from the lookup map. 167 * This can be useful if you want to explicitly remove an item from the lookup map.
173 * 168 *
176 * @param list the list 171 * @param list the list
177 * @param index the index of the element in the list 172 * @param index the index of the element in the list
178 * @retval zero success 173 * @retval zero success
179 * @retval non-zero the index is out of bounds 174 * @retval non-zero the index is out of bounds
180 */ 175 */
181 cx_attr_nonnull 176 CX_EXTERN CX_NONNULL
182 CX_EXPORT int cxKvListRemoveKey(CxList *list, size_t index); 177 int cxKvListRemoveKey(CxList *list, size_t index);
183 178
184 /** 179 /**
185 * Returns the key of a list item. 180 * Returns the key of a list item.
186 * 181 *
187 * @param list the list 182 * @param list the list
188 * @param index the index of the element in the list 183 * @param index the index of the element in the list
189 * @return a pointer to the key or @c NULL when the index is out of bounds or the item does not have a key 184 * @return a pointer to the key or @c NULL when the index is out of bounds or the item does not have a key
190 */ 185 */
191 cx_attr_nonnull 186 CX_EXTERN CX_NONNULL CX_NODISCARD
192 CX_EXPORT const CxHashKey *cxKvListGetKey(CxList *list, size_t index); 187 const CxHashKey *cxKvListGetKey(CxList *list, size_t index);
193 188
194 /** 189 /**
195 * Adds an item into the list and associates it with the specified key. 190 * Adds an item into the list and associates it with the specified key.
196 * 191 *
197 * @param list (@c CxList*) the list 192 * @param list (@c CxList*) the list
200 * @retval zero success 195 * @retval zero success
201 * @retval non-zero memory allocation failure 196 * @retval non-zero memory allocation failure
202 */ 197 */
203 #define cxKvListAdd(list, key, value) cxKvListInsert(list, (list)->collection.size, key, value) 198 #define cxKvListAdd(list, key, value) cxKvListInsert(list, (list)->collection.size, key, value)
204 199
205 #ifdef __cplusplus
206 } // extern "C"
207 #endif
208
209 #endif // UCX_KV_LIST_H 200 #endif // UCX_KV_LIST_H

Mercurial Repository: ucx

mercurial