Wed, 02 May 2018 16:14:40 +0200
makes destructor functions for *_free_content() optional + more documentation for UcxProperties
1 ---
2 title: Modules
3 ---
5 UCX provides several modules for data structures and algorithms.
6 You may choose to use specific modules by inclueding the corresponding header
7 file.
8 Please note, that some modules make use of other UCX modules.
9 For instance, the [Allocator](#allocator) module is used by many other modules
10 to allow flexible memory allocation.
11 By default the header files are placed into an `ucx` directory within your
12 systems include directory. In this case you can use an module by including it
13 via `#include <ucx/MODULENAME.h>`.
14 Required modules are included automatically.
16 <div id="modules" align="center">
18 ----------------------- ---------------------- ---------------------------- -------------------------
19 [Allocator](#allocator) [AVL Tree](#avl) [Buffer](#buffer) [List](#list)
20 [Logging](#logging) [Map](#map) [Memory Pool](#mempool) [Properties](#properties)
21 [Stack](#stack) [String](#string) [Testing](#test) [Utilities](#utils)
22 ----------------------- ---------------------- ---------------------------- -------------------------
24 </div>
26 <a name="allocator"></a>
28 ## Allocator
30 *Header file:* [allocator.h](api/allocator_8h.html)
31 *Required modules:* None.
33 A UCX allocator consists of a pointer to the memory area / pool and four
34 function pointers to memory management functions operating on this memory
35 area / pool. These functions shall behave equivalent to the standard libc
36 functions `malloc`, `calloc`, `realloc` and `free`.
38 The signature of the memory management functions is based on the signature
39 of the respective libc function but each of them takes the pointer to the
40 memory area / pool as first argument.
42 As the pointer to the memory area / pool can be arbitrarily chosen, any data
43 can be provided to the memory management functions. One example is the
44 [UCX Memory Pool](#mempool).
46 <a name="avl"></a>
48 ## AVL Tree
50 *Header file:* [avl.h](api/avl_8h.html)
51 *Required modules:* [Allocator](#allocator)
53 This binary search tree implementation allows average O(1) insertion and
54 removal of elements (excluding binary search time).
55 All common binary tree operations are implemented. Furthermore, this module
56 provides search functions via lower and upper bounds.
58 <a name="buffer"></a>
60 ## Buffer
62 *Header file:* [buffer.h](api/buffer_8h.html)
63 *Required modules:* None.
65 Instances of this buffer implementation can be used to read from or to write to
66 memory like you would do with a stream. This allows the use of
67 `ucx_stream_copy` from the [Utilities](#utils) module to copy contents from one
68 buffer to another or from file or network streams to the buffer and
69 vice-versa.
71 More features for convenient use of the buffer can be enabled, like automatic
72 memory management and automatic resizing of the buffer space.
73 See the documentation of the macro constants in the header file for more
74 information.
76 <a name="list"></a>
78 ## List
80 *Header file:* [list.h](api/list_8h.html)
81 *Required modules:* [Allocator](#allocator)
83 This module provides the data structure and several functions for a doubly
84 linked list. Among the common operations like insert, remove, search and sort,
85 we allow convenient iteration via a special `UCX_FOREACH` macro.
87 <a name="logging"></a>
89 ## Logging
91 *Header file:* [logging.h](api/logging_8h.html)
92 *Required modules:* [Map](#map), [String](#string)
94 The logging module comes with some predefined log levels and allows some more
95 customization. You may choose if you want to get timestamps or source file and
96 line number logged automatically when outputting a message.
99 <a name="map"></a>
101 ## Map
103 *Header file:* [map.h](api/map_8h.html)
104 *Required modules:* [Allocator](#allocator), [String](#string)
106 This module provides a hash map implementation using murmur hash 2 and separate
107 chaining with linked lists. Similarly to the list module, we provide a
108 `UCX_MAP_FOREACH` macro to conveniently iterate through the key/value pairs.
110 <a name="mempool"></a>
112 ## Memory Pool
114 *Header file:* [mempool.h](api/mempool_8h.html)
115 *Required modules:* [Allocator](#allocator)
117 Here we have a concrete allocator implementation in the sense of a memory pool.
118 This pool allows you to register destructor functions for the allocated memory,
119 which are automatically called on the destruction of the pool.
120 But you may also register *independent* destructor functions within a pool in
121 case, some external library allocated memory for you, which you wish to be
122 destroyed together with this pool.
124 <a name="properties"></a>
126 ## Properties
128 *Header file:* [properties.h](api/properties_8h.html)
129 *Required modules:* [Map](#map)
131 This module provides load and store function for `*.properties` files.
132 The key/value pairs are stored within an UCX Map.
134 ### Example: Loading properties from a file
136 ```C
137 // Open the file as usual
138 FILE* file = fopen("myprops.properties", "r");
139 if (!file) {
140 // error handling
141 return 1;
142 }
144 // Load the properties from the file
145 UcxMap* myprops = ucx_map_new(16);
146 if (ucx_properties_load(myprops, file)) {
147 // error handling
148 fclose(file);
149 ucx_map_free(myprops);
150 return 1;
151 }
153 // Print out the key/value pairs
154 char* propval;
155 UcxMapIterator propiter = ucx_map_iterator(myprops);
156 UCX_MAP_FOREACH(key, propval, propiter) {
157 printf("%s = %s\n", (char*)key.data, propval);
158 }
160 // Don't forget to free the values before freeing the map
161 ucx_map_free_content(myprops, NULL);
162 ucx_map_free(myprops);
163 fclose(file);
164 ```
166 <a name="stack"></a>
168 ## Stack
170 *Header file:* [stack.h](api/stack_8h.html)
171 *Required modules:* [Allocator](#allocator)
173 This concrete implementation of an UCX Allocator allows you to grab some amount
174 of memory which is then handled as a stack.
175 Please note, that the term *stack* only refers to the behavior of this
176 allocator. You may still choose if you want to use stack or heap memory
177 for the underlying space.
179 A typical use case is an algorithm where you need to allocate and free large
180 amounts of memory very frequently.
182 <a name="string"></a>
184 ## String
186 *Header file:* [string.h](api/string_8h.html)
187 *Required modules:* [Allocator](#allocator)
189 This module provides a safe implementation of bounded string.
190 Usually C strings do not carry a length. While for zero-terminated strings you
191 can easily get the length with `strlen`, this is not generally possible for
192 arbitrary strings.
193 The `sstr_t` type of this module always carries the string and its length to
194 reduce the risk of buffer overflows dramatically.
196 ### Initialization
198 There are several ways to create an `sstr_t`:
200 ```C
201 /* (1) sstr() uses strlen() internally, hence cstr MUST be zero-terminated */
202 sstr_t a = sstr(cstr);
204 /* (2) cstr does not need to be zero-terminated, if length is specified */
205 sstr_t b = sstrn(cstr, len);
207 /* (3) S() macro creates sstr_t from a string using sizeof() and using sstrn().
208 This version is especially useful for function arguments */
209 sstr_t c = S("hello");
211 /* (4) ST() macro creates sstr_t struct literal using sizeof() */
212 sstr_t d = ST("hello");
213 ```
215 You should not use the `S()` or `ST()` macro with string of unknown origin,
216 since the `sizeof()` call might not coincide with the string length in those
217 cases. If you know what you are doing, it can save you some performance,
218 because you do not need the `strlen()` call.
220 ### Finding the position of a substring
222 The `sstrstr()` function gives you a new `sstr_t` object starting with the
223 requested substring. Thus determining the position comes down to a simple
224 subtraction.
226 ```C
227 sstr_t haystack = ST("Here we go!");
228 sstr_t needle = ST("we");
229 sstr_t result = sstrstr(haystack, needle);
230 if (result.ptr)
231 printf("Found at position %zd.\n", haystack.length-result.length);
232 else
233 printf("Not found.\n");
234 ```
236 ### Spliting a string by a delimiter
238 The `sstrsplit()` function (and its allocator based version `sstrsplit_a()`) is
239 very powerful and might look a bit nasty at a first glance. But it is indeed
240 very simple to use. It is even more convenient in combination with a memory
241 pool.
243 ```C
244 sstr_t test = ST("here::are::some::strings");
245 sstr_t delim = ST("::");
247 ssize_t count = 0; /* no limit */
248 UcxMempool* pool = ucx_mempool_new_default();
250 sstr_t* result = sstrsplit_a(pool->allocator, test, delim, &count);
251 for (ssize_t i = 0 ; i < count ; i++) {
252 /* don't forget to specify the length via the %*s format specifier */
253 printf("%*s\n", result[i].length, result[i].ptr);
254 }
256 ucx_mempool_destroy(pool);
257 ```
258 The output is:
260 here
261 are
262 some
263 strings
265 The memory pool ensures, that all strings are freed.
267 <a name="test"></a>
269 ## Testing
271 *Header file:* [test.h](api/test_8h.html)
272 *Required modules:* None.
274 This module provides a testing framework which allows you to execute test cases
275 within test suites.
276 To avoid code duplication within tests, we also provide the possibility to
277 define test subroutines.
279 <a name="utils"></a>
281 ## Utilities
283 *Header file:* [utils.h](api/utils_8h.html)
284 *Required modules:* [Allocator](#allocator), [String](#string)
286 In this module we provide very general utility function for copy and compare
287 operations.
288 We also provide several `printf` variants to conveniently print formatted data
289 to streams or strings.