docs/Writerside/topics/about.md

# Overview

Welcome to the UAP Common Extensions.

With this library we provide useful data structures and algorithms for common
programmatic tasks in the C language. Using the build files, you can create
a static and a shared lib containing all units, but you may also use the UCX
sources in your project and compile specific units by yourself.

If you want to use this library, you can [download and install](install.md)
the recent version.
The source code is also available as Mercurial repository [at our site](https://uap-core.de/hg/ucx/) and
on [Source Forge](https://sourceforge.net/p/ucx/code/).

## Authors

Mike Becker [&lt;universe@uap-core.de&gt;](mailto:universe@uap-core.de)

Olaf Wintermann
[&lt;olaf.wintermann@gmail.com&gt;](mailto:olaf.wintermann@gmail.com)

## Other Resources

* [Doxygen Documentation](https://ucx.sourceforge.io/api/)
* [Test Coverage Report](https://ucx.sourceforge.io/coverage/)

## Changelog

### Version 3.2 - preview {collapsible="true"}

* adds cxMempoolTransfer() and cxMempoolTransferObject()
* adds support for different destruction strategies in CxMempool
* adds new key-value-based list implementation
* adds support for integer keys to CxHashKey
* adds support for comparing arbitrary strings without explicit call to cx_strcast()
* adds cxListClone() and cxMapClone()
* adds cxListDifference(), cxMapDifference(), and cxMapListDifference()
* adds cxListContains() and cxMapContains()
* adds cxListSet()
* adds cxListFirst() and cxListLast()
* adds cxListRemoveAndGetFirst() and cxListRemoveAndGetLast(),
  and corresponding macro aliases cxListPopFront() and cxListPop()
* adds cxListEmplace(), cxListEmplaceAt(), cxListEmplaceArray(), cxListEmplaceArrayAt(), and cxMapEmplace()
* adds cxListInsertUnique() and cxListInsertUniqueArray()
* adds cx_array_insert_unique() and various convenience macros
* adds cx_linked_list_insert_unique() and cx_linked_list_insert_unique_chain()
* adds cxBufferShrink()
* adds cxTreeSize()
* adds CX_PRIstr and CX_SFMT macros for formatting UCX strings
* adds cx_strcpy() and cx_strcpy_a()
* adds cxJsonArrRemove() and cxJsonObjRemove()
* adds cxStdlibAllocator and allows changes of cxDefaultAllocator
* improves performance of the CxList array list implementation
* changes over-aggressively declaring functions as static inline
* changes cx_str() and cx_mutstr() to allow NULL strings
* changes cx_strcast() to also accept C-strings as input
* changes grow strategy for the memory pool to reduce reallocations
* changes grow strategy for CxBuffer, which does now take the page size into account
* changes the implementation of cx_strreplacen() for improved efficiency
* changes all cxListIterator() and cxMapIterator() family of functions to also accept NULL as argument
* changes insert_element member function of CxList to accept NULL source and return a pointer to the inserted element
* changes the compare function wrapper for pointer lists so that it no longer invokes the actual compare function for NULL pointers
* changes struct cx_array_reallocator_s by replacing the four generic data members with two specifically named members
* fixes critical memory overflow in the stack-based array reallocator (this unfortunately breaks the function signature)
* fixes critical bug in cx_array_insert_sorted() that caused an infinite loop when inserting duplicates
* fixes mempool implementation not supporting NULL as argument for realloc
* fixes mempool implementation not supporting zero as size for realloc
* fixes that the elem_count member of an iterator was not updated after removing an element flagged by cxIteratorFlagRemoval()
* fixes that starting an iteration in a non-root node incorrectly continues iteration with the siblings of that node
* fixes unnecessary allocations in cx_strcat() family of functions
* fixes errno value after failing cxBufferSeek() to be consistently EINVAL
* fixes implementation of cxBufferTerminate()
* fixes allocator arguments for some printf.h functions not being const
* fixes that cx_tree_search() did not investigate subtrees with equally good distance
* fixes that memory was freed by the wrong allocator in cx_vasprintf_a() when the underlying vsnprintf() failed
* removes all functions that create mutating iterators in favor of making all iterators possibly mutating
* removes the use of C23 attributes because they don't mix well with GNU attributes in GCC 15

### Version 3.1 - 2025-02-11 {collapsible="true"}

* adds properties.h
* adds tree.h
* adds json.h
* adds locale-independent string to number conversion functions
* adds reallocarray() like functions to allocator.h
* adds cxIterator() to create iterators over raw C arrays
* adds cxIteratorPtr() to create iterators over raw C pointer arrays
* adds cx_array_reallocator() and cx_array_default_reallocator
* adds several new array and list functions
* adds cxBufferReset()
* adds cxBufferAppend()
* adds cxBufferEnableFlushing() and cxBufferFlush()
* adds CX_BUFFER_COPY_ON_WRITE and CX_BUFFER_COPY_ON_EXTEND flags
* adds cxBufferWriteFunc and cxBufferReadFunc function pointers (for convenience)
* adds cx_cmp_ptr()
* adds cx_vcmp_* family of functions
* adds cx_sprintf() and several more variants
* adds runtime constants to read out the actual SBO sizes
* adds improved version of UCX 2 Test framework (now a self-contained header)
* adds cx_nmemb() utility function to common.h
* changes that CxMap returns own CxMapIterator to save memory in CxIterator
* changes name of cxBasicMempoolCreate() to cxMempoolCreateSimple()
* changes all functions, for which there is no dedicated xyz_a variant,
  to accept NULL as allocator argument (in which case a default allocator will be used)
* changes the name of destroy functions that actually free the memory to better indicate their behavior
* changes cx_strcat variants to allow handling of ENOMEM
* changes cx_strcast() to also accept cxstring (and doing nothing in that case)
* changes the behavior of cxBufferSeek() to allow offset zero for SEEK_END
* moves cx_compare_func typedef to compare.h
* moves cx_szmul() to common.h
* moves stream copy functions to new streams.h
* removes cx_strupper() and cx_strlower() because they only do the right thing in special cases
* removes several *_m variants of functions in string.h in favor of automatic conversion
* removes utils.h
* removes flag_removal function from iterator
* removes cxMapDetach() and makes cxMapRemoveAndGet() compatible with both map variants
* removes the API for changing the store_pointer property of collections after their creation
* removes CMake
* removes GTest dependency
* removes flags to disable SBO in tests
* removes CX_LINKED_LIST_SWAP_SBO_SIZE (it's not really an optimization for linked lists)
* fixes cx_strcmp() and cx_strcasecmp() not being useful for lexicographic ordering
* fixes cx_hash_key_cxstr() evaluating the argument twice
* fixes critical bug that produced wrong results when comparing lists of different type but same size
* ends UCX 2.1 long term support

### Version 3.0 - 2023-07-09 {collapsible="true"}

* complete redesign from scratch
* collections can now store copies of objects and not just pointers
* collections are now dynamically implemented
* users of the library can specify own implementations of collections that work with the UCX API
* low level API for custom lists that do not use the UCX structures
* various fixes and improvements
* drops some other, rarely used, features
* removes testing implementation from the lib

### Version 2.1 - 2019-12-30 {collapsible="true"}

* adds string replace functions
* adds set operations for ` UcxList` and `UcxMap`
* adds `sstrcaseprefix()` and `sstrcasesuffix()`
* improves Doxygen documentation in ucx/string.h
* adds `UcxArray` data type
* adds support for CMake builds, but main build system is still autotools

### Version 2.0 - 2018-12-28 {collapsible="true"}

* some uncritical bug fixes
* overflow of `sstrnlen` now returns `SIZE_MAX` instead of zero
* adds `scstr_t` - a `const char*` variant for sstr_t
* renames utility compare functions

### Version 1.1 - 2018-05-14 {collapsible="true"}

* adds missing 32 bit support to integer overflow checks
* adds `ucx_buffer_to_sstr()` macro
* adds `ucx_avl_free_content()`
* adds some more compare and distance functions in utils.h
* adds `SFMT()` and `PRIsstr` convenience macros
* destructor functions for `*_free_content()` functions are now optional

### Version 1.0.1 - 2018-01-21 {collapsible="true"}

* some bug fixes
* adds integer overflow checks

### Version 1.0 - 2017-10-28 {collapsible="true"}

* first stable version of UCX released