UCX provides several modules for data structures and algorithms. You may choose to use specific modules by inclueding the corresponding header file. Please note, that some modules make use of other UCX modules. For instance, the Allocator module is used by many other modules to allow flexible memory allocation. By default the header files are placed into an ucx directory within your systems include directory. In this case you can use an module by including it via #include <ucx/MODULENAME.h>. Required modules are included automatically.

Allocator AVL Tree Buffer List
Logging Map Memory Pool Properties
Stack String Testing Utilities

Allocator

Header file: allocator.h
Required modules: None.

A UCX allocator consists of a pointer to the memory area / pool and four function pointers to memory management functions operating on this memory area / pool. These functions shall behave equivalent to the standard libc functions malloc, calloc, realloc and free.

The signature of the memory management functions is based on the signature of the respective libc function but each of them takes the pointer to the memory area / pool as first argument.

As the pointer to the memory area / pool can be arbitrarily chosen, any data can be provided to the memory management functions. One example is the UCX Memory Pool.

AVL Tree

Header file: avl.h
Required modules: Allocator

This binary search tree implementation allows average O(1) insertion and removal of elements (excluding binary search time). All common binary tree operations are implemented. Furthermore, this module provides search functions via lower and upper bounds.

Buffer

Header file: buffer.h
Required modules: None.

Instances of this buffer implementation can be used to read from or to write to memory like you would do with a stream. This allows the use of ucx_stream_copy from the Utilities module to copy contents from one buffer to another or from file or network streams to the buffer and vice-versa.

More features for convenient use of the buffer can be enabled, like automatic memory management and automatic resizing of the buffer space. See the documentation of the macro constants in the header file for more information.

List

Header file: list.h
Required modules: Allocator

This module provides the data structure and several functions for a doubly linked list. Among the common operations like insert, remove, search and sort, we allow convenient iteration via a special UCX_FOREACH macro.

Logging

Header file: logging.h
Required modules: Map, String

The logging module comes with some predefined log levels and allows some more customization. You may choose if you want to get timestamps or source file and line number logged automatically when outputting a message.

Map

Header file: map.h
Required modules: Allocator, String

This module provides a hash map implementation using murmur hash 2 and separate chaining with linked lists. Similarly to the list module, we provide a UCX_MAP_FOREACH macro to conveniently iterate through the key/value pairs.

Memory Pool

Header file: mempool.h
Required modules: Allocator

Here we have a concrete allocator implementation in the sense of a memory pool. This pool allows you to register destructor functions for the allocated memory, which are automatically called on the destruction of the pool. But you may also register independent destructor functions within a pool in case, some external library allocated memory for you, which you wish to be destroyed together with this pool.

Properties

Header file: properties.h
Required modules: Map

This module provides load and store function for *.properties files. The key/value pairs are stored within an UCX Map.

Stack

Header file: stack.h
Required modules: Allocator

This concrete implementation of an UCX Allocator allows you to grab some amount of memory which is then handled as a stack. Please note, that the term stack only refers to the behavior of this allocator. You may still choose if you want to use stack or heap memory for the underlying space.

A typical use case is an algorithm where you need to allocate and free large amounts of memory very frequently.

String

Header file: string.h
Required modules: Allocator

This module provides a safe implementation of bounded string. Usually C strings do not carry a length. While for zero-terminated strings you can easily get the length with strlen, this is not generally possible for arbitrary strings. The sstr_t type of this module always carries the string and its length to reduce the risk of buffer overflows dramatically.

Initialization

There are several ways to create an sstr_t:

/* (1) sstr() uses strlen() internally, hence cstr MUST be zero-terminated */
sstr_t a = sstr(cstr);

/* (2) cstr does not need to be zero-terminated, if length is specified */
sstr_t b = sstrn(cstr, len);

/* (3) S() macro creates sstr_t from a string using sizeof() and using sstrn().
       This version is especially useful for function arguments */
sstr_t c = S("hello");

/* (4) ST() macro creates sstr_t struct literal using sizeof() */
sstr_t d = ST("hello");

You should not use the S() or ST() macro with string of unknown origin, since the sizeof() call might not coincide with the string length in those cases. If you know what you are doing, it can save you some performance, because you do not need the strlen() call.

Finding the position of a substring

The sstrstr() function gives you a new sstr_t object starting with the requested substring. Thus determining the position comes down to a simple subtraction.

sstr_t haystack = ST("Here we go!");
sstr_t needle = ST("we");
sstr_t result = sstrstr(haystack, needle);
if (result.ptr)
    printf("Found at position %zd.\n", haystack.length-result.length);
else
    printf("Not found.\n");

Spliting a string by a delimiter

The sstrsplit() function (and its allocator based version sstrsplit_a()) is very powerful and might look a bit nasty at a first glance. But it is indeed very simple to use. It is even more convenient in combination with a memory pool.

sstr_t test = ST("here::are::some::strings");
sstr_t delim = ST("::");

ssize_t count = 0; /* no limit */
UcxMempool* pool = ucx_mempool_new_default();

sstr_t* result = sstrsplit_a(pool->allocator, test, delim, &count);
for (ssize_t i = 0 ; i < count ; i++) {
    /* don't forget to specify the length via the %*s format specifier */
    printf("%*s\n", result[i].length, result[i].ptr);
}

ucx_mempool_destroy(pool);

The output is:

here
are
some
strings

The memory pool ensures, that all strings are freed.

Testing

Header file: test.h
Required modules: None.

This module provides a testing framework which allows you to execute test cases within test suites. To avoid code duplication within tests, we also provide the possibility to define test subroutines.

Utilities

Header file: utils.h
Required modules: Allocator, String

In this module we provide very general utility function for copy and compare operations. We also provide several printf variants to conveniently print formatted data to streams or strings.