Mercurial > hg > ucx / file comparison

comparison: src/cx/kv_list.h

src/cx/kv_list.h

changeset 1605
55b13f583356
parent 1426
3a89b31f0724
equal deleted inserted replaced
1604:68b75c091028 1605:55b13f583356
47 /** 47 /**
48 * Allocates a linked list with a lookup-map for storing elements with @p elem_size bytes each. 48 * Allocates a linked list with a lookup-map for storing elements with @p elem_size bytes each.
49 * 49 *
50 * If @p elem_size is #CX_STORE_POINTERS, the created list stores pointers instead of 50 * 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 51 * copies of the added elements, and the compare function will be automatically set
52 * to cx_cmp_ptr() if none is given. 52 * to cx_cmp_ptr().
53 * 53 *
54 * After creating the list, it can also be used as a map after converting the pointer 54 * After creating the list, it can also be used as a map after converting the pointer
55 * to a CxMap pointer with cxKvListAsMap(). 55 * to a CxMap pointer with cxKvListAsMap().
56 * When you want to use the list interface again, you can also convert the map pointer back 56 * When you want to use the list interface again, you can also convert the map pointer back
57 * with cxKvListAsList(). 57 * with cxKvListAsList().
58 * 58 *
59 * @param allocator the allocator for allocating the list nodes 59 * @param allocator the allocator for allocating the list nodes
60 * (if @c NULL, the cxDefaultAllocator will be used) 60 * (if @c NULL, the cxDefaultAllocator will be used)
61 * @param comparator the comparator for the elements
62 * (if @c NULL, and the list is not storing pointers, sort and find
63 * functions will not work)
64 * @param elem_size the size of each element in bytes 61 * @param elem_size the size of each element in bytes
65 * @return the created list 62 * @return the created list
66 * @see cxKvListAsMap() 63 * @see cxKvListAsMap()
67 * @see cxKvListAsList() 64 * @see cxKvListAsList()
68 */ 65 */
69 cx_attr_nodiscard cx_attr_malloc cx_attr_dealloc(cxListFree, 1) 66 cx_attr_nodiscard cx_attr_malloc cx_attr_dealloc(cxListFree, 1)
70 CX_EXPORT CxList *cxKvListCreate(const CxAllocator *allocator, 67 CX_EXPORT CxList *cxKvListCreate(const CxAllocator *allocator,
71 cx_compare_func comparator, size_t elem_size); 68 size_t elem_size);
72 69
73 /** 70 /**
74 * Allocates a linked list with a lookup-map for storing elements with @p elem_size bytes each. 71 * Allocates a linked list with a lookup-map for storing elements with @p elem_size bytes each.
75 * 72 *
76 * If @p elem_size is #CX_STORE_POINTERS, the created list stores pointers instead of 73 * If @p elem_size is #CX_STORE_POINTERS, the created list stores pointers instead of
77 * copies of the added elements, and the compare function will be automatically set 74 * copies of the added elements, and the compare function will be automatically set
78 * to cx_cmp_ptr() if none is given. 75 * to cx_cmp_ptr().
79 * 76 *
80 * This function creates the list with cxKvListCreate() and immediately applies 77 * This function creates the list with cxKvListCreate() and immediately applies
81 * cxKvListAsMap(). If you want to use the returned object as a list, you can call 78 * cxKvListAsMap(). If you want to use the returned object as a list, you can call
82 * cxKvListAsList() later. 79 * cxKvListAsList() later.
83 * 80 *
84 * @param allocator the allocator for allocating the list nodes 81 * @param allocator the allocator for allocating the list nodes
85 * (if @c NULL, the cxDefaultAllocator will be used) 82 * (if @c NULL, the cxDefaultAllocator will be used)
86 * @param comparator the comparator for the elements
87 * (if @c NULL, and the list is not storing pointers, sort and find
88 * functions will not work)
89 * @param elem_size the size of each element in bytes 83 * @param elem_size the size of each element in bytes
90 * @return the created list wrapped into the CxMap interface 84 * @return the created list wrapped into the CxMap interface
91 * @see cxKvListAsMap() 85 * @see cxKvListAsMap()
92 * @see cxKvListAsList() 86 * @see cxKvListAsList()
93 */ 87 */
94 cx_attr_nodiscard cx_attr_malloc cx_attr_dealloc(cxMapFree, 1) 88 cx_attr_nodiscard cx_attr_malloc cx_attr_dealloc(cxMapFree, 1)
95 CX_EXPORT CxMap *cxKvListCreateAsMap(const CxAllocator *allocator, 89 CX_EXPORT CxMap *cxKvListCreateAsMap(const CxAllocator *allocator,
96 cx_compare_func comparator, size_t elem_size); 90 size_t elem_size);
97
98 /**
99 * Allocates a linked list with a lookup-map for storing elements with @p elem_size bytes each.
100 *
101 * The list will use cxDefaultAllocator and no comparator function. If you want
102 * to call functions that need a comparator, you must either set one immediately
103 * after list creation or use cxKvListCreate().
104 *
105 * If @p elem_size is #CX_STORE_POINTERS, the created list stores pointers instead of
106 * copies of the added elements, and the compare function will be automatically set
107 * to cx_cmp_ptr().
108 *
109 * After creating the list, it can also be used as a map after converting the pointer
110 * to a CxMap pointer with cxKvListAsMap().
111 * When you want to use the list interface again, you can also convert the map pointer back
112 * with cxKvListAsList().
113 *
114 * @param elem_size (@c size_t) the size of each element in bytes
115 * @return (@c CxList*) the created list
116 * @see cxKvListAsMap()
117 * @see cxKvListAsList()
118 */
119 #define cxKvListCreateSimple(elem_size) cxKvListCreate(NULL, NULL, elem_size)
120
121 /**
122 * Allocates a linked list with a lookup-map for storing elements with @p elem_size bytes each.
123 *
124 * The list will use cxDefaultAllocator and no comparator function. If you want
125 * to call functions that need a comparator, you must either set one immediately
126 * after list creation or use cxKvListCreate().
127 *
128 * If @p elem_size is #CX_STORE_POINTERS, the created list stores pointers instead of
129 * copies of the added elements, and the compare function will be automatically set
130 * to cx_cmp_ptr().
131 *
132 * This macro behaves as if the list was created with cxKvListCreateSimple() and
133 * immediately followed up by cxKvListAsMap().
134 * If you want to use the returned object as a list, you can call cxKvListAsList() later.
135 *
136 * @param elem_size (@c size_t) the size of each element in bytes
137 * @return (@c CxMap*) the created list wrapped into the CxMap interface
138 * @see cxKvListAsMap()
139 * @see cxKvListAsList()
140 */
141 #define cxKvListCreateAsMapSimple(elem_size) cxKvListCreateAsMap(NULL, NULL, elem_size)
142 91
143 /** 92 /**
144 * Converts a map pointer belonging to a key-value-List back to the original list pointer. 93 * Converts a map pointer belonging to a key-value-List back to the original list pointer.
145 * 94 *
146 * @param map a map pointer that was returned by a call to cxKvListAsMap() 95 * @param map a map pointer that was returned by a call to cxKvListAsMap()
150 CX_EXPORT CxList *cxKvListAsList(CxMap *map); 99 CX_EXPORT CxList *cxKvListAsList(CxMap *map);
151 100
152 /** 101 /**
153 * Converts a map pointer belonging to a key-value-List back to the original list pointer. 102 * Converts a map pointer belonging to a key-value-List back to the original list pointer.
154 * 103 *
155 * @param list a list created by cxKvListCreate() or cxKvListCreateSimple() 104 * @param list a list created by cxKvListCreate()
156 * @return a map pointer that lets you use the list as if it was a map 105 * @return a map pointer that lets you use the list as if it was a map
157 */ 106 */
158 cx_attr_nodiscard cx_attr_nonnull cx_attr_returns_nonnull 107 cx_attr_nodiscard cx_attr_nonnull cx_attr_returns_nonnull
159 CX_EXPORT CxMap *cxKvListAsMap(CxList *list); 108 CX_EXPORT CxMap *cxKvListAsMap(CxList *list);
160 109

Mercurial Repository: ucx

mercurial