Mercurial > hg > ucx / file revision

 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.