Sun, 21 Jan 2018 10:57:32 +0100
adds integer overflow checks to sstrlen and sstrcat
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 <a name="stack"></a>
136 ## Stack
138 *Header file:* [stack.h](api/stack_8h.html)
139 *Required modules:* [Allocator](#allocator)
141 This concrete implementation of an UCX Allocator allows you to grab some amount
142 of memory which is then handled as a stack.
143 Please note, that the term *stack* only refers to the behavior of this
144 allocator. You may still choose if you want to use stack or heap memory
145 for the underlying space.
147 A typical use case is an algorithm where you need to allocate and free large
148 amounts of memory very frequently.
150 <a name="string"></a>
152 ## String
154 *Header file:* [string.h](api/string_8h.html)
155 *Required modules:* [Allocator](#allocator)
157 This module provides a safe implementation of bounded string.
158 Usually C strings do not carry a length. While for zero-terminated strings you
159 can easily get the length with `strlen`, this is not generally possible for
160 arbitrary strings.
161 The `sstr_t` type of this module always carries the string and its length to
162 reduce the risk of buffer overflows dramatically.
164 ### Initialization
166 There are several ways to create an `sstr_t`:
168 ```C
169 /* (1) sstr() uses strlen() internally, hence cstr MUST be zero-terminated */
170 sstr_t a = sstr(cstr);
172 /* (2) cstr does not need to be zero-terminated, if length is specified */
173 sstr_t b = sstrn(cstr, len);
175 /* (3) S() macro creates sstr_t from a string using sizeof() and using sstrn().
176 This version is especially useful for function arguments */
177 sstr_t c = S("hello");
179 /* (4) ST() macro creates sstr_t struct literal using sizeof() */
180 sstr_t d = ST("hello");
181 ```
183 You should not use the `S()` or `ST()` macro with string of unknown origin,
184 since the `sizeof()` call might not coincide with the string length in those
185 cases. If you know what you are doing, it can save you some performance,
186 because you do not need the `strlen()` call.
188 ### Finding the position of a substring
190 The `sstrstr()` function gives you a new `sstr_t` object starting with the
191 requested substring. Thus determining the position comes down to a simple
192 subtraction.
194 ```C
195 sstr_t haystack = ST("Here we go!");
196 sstr_t needle = ST("we");
197 sstr_t result = sstrstr(haystack, needle);
198 if (result.ptr)
199 printf("Found at position %zd.\n", haystack.length-result.length);
200 else
201 printf("Not found.\n");
202 ```
204 ### Spliting a string by a delimiter
206 The `sstrsplit()` function (and its allocator based version `sstrsplit_a()`) is
207 very powerful and might look a bit nasty at a first glance. But it is indeed
208 very simple to use. It is even more convenient in combination with a memory
209 pool.
211 ```C
212 sstr_t test = ST("here::are::some::strings");
213 sstr_t delim = ST("::");
215 ssize_t count = 0; /* no limit */
216 UcxMempool* pool = ucx_mempool_new_default();
218 sstr_t* result = sstrsplit_a(pool->allocator, test, delim, &count);
219 for (ssize_t i = 0 ; i < count ; i++) {
220 /* don't forget to specify the length via the %*s format specifier */
221 printf("%*s\n", result[i].length, result[i].ptr);
222 }
224 ucx_mempool_destroy(pool);
225 ```
226 The output is:
228 here
229 are
230 some
231 strings
233 The memory pool ensures, that all strings are freed.
235 <a name="test"></a>
237 ## Testing
239 *Header file:* [test.h](api/test_8h.html)
240 *Required modules:* None.
242 This module provides a testing framework which allows you to execute test cases
243 within test suites.
244 To avoid code duplication within tests, we also provide the possibility to
245 define test subroutines.
247 <a name="utils"></a>
249 ## Utilities
251 *Header file:* [utils.h](api/utils_8h.html)
252 *Required modules:* [Allocator](#allocator), [String](#string)
254 In this module we provide very general utility function for copy and compare
255 operations.
256 We also provide several `printf` variants to conveniently print formatted data
257 to streams or strings.