about.md- allocator.h.md
- array_list.h.md
- buffer.h.md
- collection.h.md
- collections.md
- compare.h.md
- features.md
- hash_key.h.md
- hash_map.h.md
- install.md
- iterator.h.md
- json.h.md
- kv_list.h.md
- license.md
- linked_list.h.md
- list.h.md
- map.h.md
- memory.md
- mempool.h.md
- parsers.md
- printf.h.md
- properties.h.md
- streams.h.md
- string.h.md
- strings.md
- test.h.md
- tree.h.md
- utils.md
1 # Overview
2
3 Welcome to the UAP Common Extensions.
4
5 With this library we provide useful data structures and algorithms for common
6 programmatic tasks in the C language. Using the build files, you can create
7 a static and a shared lib containing all units, but you may also use the UCX
8 sources in your project and compile specific units by yourself.
9
10 If you want to use this library, you can [download and install](install.md)
11 the recent version.
12 The source code is also available as Mercurial repository [at our site](https://uap-core.de/hg/ucx/) and
13 on [Source Forge](https://sourceforge.net/p/ucx/code/).
14
15 ## Authors
16
17 Mike Becker [<universe@uap-core.de>](mailto:universe@uap-core.de)
18
19 Olaf Wintermann
20 [<olaf.wintermann@gmail.com>](mailto:olaf.wintermann@gmail.com)
21
22 ## Other Resources
23
24 * [Doxygen Documentation](https://ucx.sourceforge.io/api/)
25 * [Test Coverage Report](https://ucx.sourceforge.io/coverage/)
26
27 ## Changelog
28
29 ### Version 4.0 - preview {collapsible="true"}
30
31 * adds cx_system_page_size() to allocator.h
32 * adds cxJsonFromString()
33 * adds line continuation support to CxProperties / CxPropertiesConfig
34 * changes cxFreeDefault() from a macro to a function so that it can be used as a simple destructor
35 * changes cxBufferReserve() to allow reducing the capacity
36 * changes the members of CxJson and CxJsonValue
37 * changes the return value of cxJsonObjIter() to CxMapIterator
38 * changes CxTree structure so that it now inherits CX_COLLECTION_BASE
39 * changes cxPropertiesLoad() to directly load properties from a file to a CxMap
40 * fixes cxJsonWrite() incorrectly returning non-zero when strings needed to be escaped
41 * fixes cxJsonNext() incorrectly returning CX_JSON_INCOMPLETE_DATA when the input ends with trailing spaces
42 * fixes critical memory leak when using cxMapFree() on a kv-list that is using destructors
43 * fixes that overwriting items with cxMapPut() in a kv-list did not work
44 * fixes that cxReallocate(), cxReallocateArray(), cx_reallocate(), and cx_reallocatearray()
45 were not returning zero after freeing the memory when passed a size of zero
46 * removes the sort_members feature from CxJsonWriter
47 * removes the source and sink API from properties.h
48
49 ### Version 3.2 - 2025-11-30 {collapsible="true"}
50
51 * adds cxMempoolTransfer() and cxMempoolTransferObject()
52 * adds support for different destruction strategies in CxMempool
53 * adds new key-value-based list implementation
54 * adds support for integer keys to CxHashKey
55 * adds support for comparing arbitrary strings without explicit call to cx_strcast()
56 * adds clone, union, difference, and intersection functions for CxList and CxMap
57 * adds cxListContains() and cxMapContains()
58 * adds cxListReserve() and cxListShrink()
59 * adds cxListSet()
60 * adds cxListFirst() and cxListLast()
61 * adds cxListRemoveAndGetFirst() and cxListRemoveAndGetLast(),
62 and corresponding macro aliases cxListPopFront() and cxListPop()
63 * adds cxListEmplace(), cxListEmplaceAt(), cxListEmplaceArray(), cxListEmplaceArrayAt(), and cxMapEmplace()
64 * adds cxListInsertUnique() and cxListInsertUniqueArray()
65 * adds cx_array_insert_unique() and various convenience macros
66 * adds cx_linked_list_insert_unique() and cx_linked_list_insert_unique_chain()
67 * adds cxCollectionCompareFunc() to conveniently set a compare function for a collection
68 without needing to access the base struct manually
69 * adds cxBufferShrink()
70 * adds cxBufferPop()
71 * adds cxTreeSize()
72 * adds CX_PRIstr and CX_SFMT macros for formatting UCX strings
73 * adds cx_strcpy() and cx_strcpy_a()
74 * adds cxJsonArrRemove() and cxJsonObjRemove()
75 * adds cxStdlibAllocator and allows changes of cxDefaultAllocator
76 * improves performance of the CxList array list implementation
77 * changes over-aggressively declaring functions as static inline
78 * changes cx_str() and cx_mutstr() to allow NULL strings
79 * changes cx_strcast() to also accept C-strings as input
80 * changes grow strategy for the memory pool to reduce reallocations
81 * changes grow strategy for CxBuffer, which does now take the page size into account
82 * changes the implementation of cx_strreplacen() for improved efficiency
83 * changes all cxListIterator() and cxMapIterator() family of functions to also accept NULL as argument
84 * changes insert_element member function of CxList to accept NULL source and return a pointer to the inserted element
85 * changes the compare function wrapper for pointer lists so that it no longer invokes the actual compare function for NULL pointers
86 * changes struct cx_array_reallocator_s by replacing the four generic data members with two specifically named members
87 * changes cx_array_reserve() so that it reserves exactly the requested capacity (i.e., without overallocation)
88 * changes all other array functions to perform smart overallocation to avoid too many subsequent allocations
89 * changes that binary search and infimum always report the largest index, and supremum always reports the smallest index
90 when the found element appears more than once in the array
91 * fixes critical memory overflow in the stack-based array reallocator (this unfortunately breaks the function signature)
92 * fixes critical bug in cx_array_insert_sorted() that caused an infinite loop when inserting duplicates
93 * fixes mempool implementation not supporting NULL as argument for realloc
94 * fixes mempool implementation not supporting zero as size for realloc
95 * fixes that the elem_count member of an iterator was not updated after removing an element flagged by cxIteratorFlagRemoval()
96 * fixes that starting an iteration in a non-root node incorrectly continues iteration with the siblings of that node
97 * fixes unnecessary allocations in cx_strcat() family of functions
98 * fixes ineffective overflow check in cx_strcat() family of functions
99 * fixes errno value after failing cxBufferSeek() to be consistently EINVAL
100 * fixes implementation of cxBufferTerminate()
101 * fixes that cxBufferWrite() could auto-extend the buffer beyond the configured threshold
102 * fixes allocator arguments for some printf.h functions not being const
103 * fixes that cx_tree_search() did not investigate subtrees with equally good distance
104 * fixes that memory was freed by the wrong allocator in cx_vasprintf_a() when the underlying vsnprintf() failed
105 * removes all functions that create mutating iterators in favor of making all iterators possibly mutating
106 * removes the use of C23 attributes because they don't mix well with GNU attributes in GCC 15
107
108 ### Version 3.1 - 2025-02-11 {collapsible="true"}
109
110 * adds properties.h
111 * adds tree.h
112 * adds json.h
113 * adds locale-independent string to number conversion functions
114 * adds reallocarray() like functions to allocator.h
115 * adds cxIterator() to create iterators over raw C arrays
116 * adds cxIteratorPtr() to create iterators over raw C pointer arrays
117 * adds cx_array_reallocator() and cx_array_default_reallocator
118 * adds several new array and list functions
119 * adds cxBufferReset()
120 * adds cxBufferAppend()
121 * adds cxBufferEnableFlushing() and cxBufferFlush()
122 * adds CX_BUFFER_COPY_ON_WRITE and CX_BUFFER_COPY_ON_EXTEND flags
123 * adds cxBufferWriteFunc and cxBufferReadFunc function pointers (for convenience)
124 * adds cx_cmp_ptr()
125 * adds cx_vcmp_* family of functions
126 * adds cx_sprintf() and several more variants
127 * adds runtime constants to read out the actual SBO sizes
128 * adds improved version of UCX 2 Test framework (now a self-contained header)
129 * adds cx_nmemb() utility function to common.h
130 * changes that CxMap returns own CxMapIterator to save memory in CxIterator
131 * changes name of cxBasicMempoolCreate() to cxMempoolCreateSimple()
132 * changes all functions, for which there is no dedicated xyz_a variant,
133 to accept NULL as allocator argument (in which case a default allocator will be used)
134 * changes the name of destroy functions that actually free the memory to better indicate their behavior
135 * changes cx_strcat variants to allow handling of ENOMEM
136 * changes cx_strcast() to also accept cxstring (and doing nothing in that case)
137 * changes the behavior of cxBufferSeek() to allow offset zero for SEEK_END
138 * moves cx_compare_func typedef to compare.h
139 * moves cx_szmul() to common.h
140 * moves stream copy functions to new streams.h
141 * removes cx_strupper() and cx_strlower() because they only do the right thing in special cases
142 * removes several *_m variants of functions in string.h in favor of automatic conversion
143 * removes utils.h
144 * removes flag_removal function from iterator
145 * removes cxMapDetach() and makes cxMapRemoveAndGet() compatible with both map variants
146 * removes the API for changing the store_pointer property of collections after their creation
147 * removes CMake
148 * removes GTest dependency
149 * removes flags to disable SBO in tests
150 * removes CX_LINKED_LIST_SWAP_SBO_SIZE (it's not really an optimization for linked lists)
151 * fixes cx_strcmp() and cx_strcasecmp() not being useful for lexicographic ordering
152 * fixes cx_hash_key_cxstr() evaluating the argument twice
153 * fixes critical bug that produced wrong results when comparing lists of different type but same size
154 * ends UCX 2.1 long term support
155
156 ### Version 3.0 - 2023-07-09 {collapsible="true"}
157
158 * complete redesign from scratch
159 * collections can now store copies of objects and not just pointers
160 * collections are now dynamically implemented
161 * users of the library can specify own implementations of collections that work with the UCX API
162 * low level API for custom lists that do not use the UCX structures
163 * various fixes and improvements
164 * drops some other, rarely used, features
165 * removes testing implementation from the lib
166
167 ### Version 2.1 - 2019-12-30 {collapsible="true"}
168
169 * adds string replace functions
170 * adds set operations for ` UcxList` and `UcxMap`
171 * adds `sstrcaseprefix()` and `sstrcasesuffix()`
172 * improves Doxygen documentation in ucx/string.h
173 * adds `UcxArray` data type
174 * adds support for CMake builds, but main build system is still autotools
175
176 ### Version 2.0 - 2018-12-28 {collapsible="true"}
177
178 * some uncritical bug fixes
179 * overflow of `sstrnlen` now returns `SIZE_MAX` instead of zero
180 * adds `scstr_t` - a `const char*` variant for sstr_t
181 * renames utility compare functions
182
183 ### Version 1.1 - 2018-05-14 {collapsible="true"}
184
185 * adds missing 32 bit support to integer overflow checks
186 * adds `ucx_buffer_to_sstr()` macro
187 * adds `ucx_avl_free_content()`
188 * adds some more compare and distance functions in utils.h
189 * adds `SFMT()` and `PRIsstr` convenience macros
190 * destructor functions for `*_free_content()` functions are now optional
191
192 ### Version 1.0.1 - 2018-01-21 {collapsible="true"}
193
194 * some bug fixes
195 * adds integer overflow checks
196
197 ### Version 1.0 - 2017-10-28 {collapsible="true"}
198
199 * first stable version of UCX released
200