docs/src/modules.md

Modules
=======

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](#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.

<a name="allocator"></a>

## Allocator

*Header file:* [allocator.h](api/allocator_8h.html)  
*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](#mempool).

<a name="avl"></a>

## AVL Tree

*Header file:* [avl.h](api/avl_8h.html)  
*Required modules:* [Allocator](#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.

<a name="buffer"></a>

## Buffer

*Header file:* [buffer.h](api/buffer_8h.html)  
*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](#utils) 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.

<a name="list"></a>

## List

*Header file:* [list.h](api/list_8h.html)  
*Required modules:* [Allocator](#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.

<a name="logging"></a>

## Logging

*Header file:* [logging.h](api/logging_8h.html)  
*Required modules:* [Map](#map), [String](#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.


<a name="map"></a>

## Map

*Header file:* [map.h](api/map_8h.html)  
*Required modules:* [Allocator](#allocator), [String](#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.

<a name="mempool"></a>

## Memory Pool

*Header file:* [mempool.h](api/mempool_8h.html)  
*Required modules:* [Allocator](#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.

<a name="properties"></a>

## Properties

*Header file:* [properties.h](api/properties_8h.html)  
*Required modules:* [Map](#map)

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

<a name="stack"></a>

## Stack

*Header file:* [stack.h](api/stack_8h.html)  
*Required modules:* [Allocator](#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.

<a name="string"></a>

## String

*Header file:* [string.h](api/string_8h.html)  
*Required modules:* [Allocator](#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.

<a name="test"></a>

## Testing

*Header file:* [test.h](api/test_8h.html)  
*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.

<a name="utils"></a>

## Utilities

*Header file:* [utils.h](api/utils_8h.html)  
*Required modules:* [Allocator](#allocator), [String](#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.