diff -r d9f4285c795c -r 2f5dea574a75 docs/src/modules.md --- a/docs/src/modules.md Sat Oct 28 11:25:27 2017 +0200 +++ b/docs/src/modules.md Sat Oct 28 15:43:51 2017 +0200 @@ -1,2 +1,176 @@ 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 `. +Required modules are included automatically. + + + +## 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). + + + +## 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. + + + +## 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. + + + +## 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. + + + +## 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. + + + + +## 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. + + + +## 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. + + + +## 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. + + + +## 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. + + + +## 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. + + + +## 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. + + + +## 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. +