Thu, 03 May 2018 09:49:38 +0200
adds ucx_longintcmp() compare function
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 a 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-tree) [Buffer](#buffer) [List](#list)
20 [Logging](#logging) [Map](#map) [Memory Pool](#memory-pool) [Properties](#properties)
21 [Stack](#stack) [String](#string) [Testing](#testing) [Utilities](#utilities)
22 ----------------------- ---------------------- ---------------------------- -------------------------
24 </div>
26 ## Allocator
28 *Header file:* [allocator.h](api/allocator_8h.html)
29 *Required modules:* None.
31 A UCX allocator consists of a pointer to the memory area / pool and four
32 function pointers to memory management functions operating on this memory
33 area / pool. These functions shall behave equivalent to the standard libc
34 functions `malloc`, `calloc`, `realloc` and `free`.
36 The signature of the memory management functions is based on the signature
37 of the respective libc function but each of them takes the pointer to the
38 memory area / pool as first argument.
40 As the pointer to the memory area / pool can be arbitrarily chosen, any data
41 can be provided to the memory management functions. One example is the
42 [UCX Memory Pool](#memory-pool).
44 ## AVL Tree
46 *Header file:* [avl.h](api/avl_8h.html)
47 *Required modules:* [Allocator](#allocator)
49 This binary search tree implementation allows average O(1) insertion and
50 removal of elements (excluding binary search time).
51 All common binary tree operations are implemented. Furthermore, this module
52 provides search functions via lower and upper bounds.
54 ## Buffer
56 *Header file:* [buffer.h](api/buffer_8h.html)
57 *Required modules:* None.
59 Instances of this buffer implementation can be used to read from or to write to
60 memory like you would do with a stream. This allows the use of
61 `ucx_stream_copy()` from the [Utilities](#utilities) module to copy contents
62 from one buffer to another or from file or network streams to the buffer and
63 vice-versa.
65 More features for convenient use of the buffer can be enabled, like automatic
66 memory management and automatic resizing of the buffer space.
67 See the documentation of the macro constants in the header file for more
68 information.
70 ## List
72 *Header file:* [list.h](api/list_8h.html)
73 *Required modules:* [Allocator](#allocator)
75 This module provides the data structure and several functions for a doubly
76 linked list. Among the common operations like insert, remove, search and sort,
77 we allow convenient iteration via a special `UCX_FOREACH` macro.
79 ## Logging
81 *Header file:* [logging.h](api/logging_8h.html)
82 *Required modules:* [Map](#map), [String](#string)
84 The logging module comes with some predefined log levels and allows some more
85 customization. You may choose if you want to get timestamps or source file and
86 line number logged automatically when outputting a message.
89 ## Map
91 *Header file:* [map.h](api/map_8h.html)
92 *Required modules:* [Allocator](#allocator), [String](#string)
94 This module provides a hash map implementation using murmur hash 2 and separate
95 chaining with linked lists. Similarly to the list module, we provide a
96 `UCX_MAP_FOREACH` macro to conveniently iterate through the key/value pairs.
98 ## Memory Pool
100 *Header file:* [mempool.h](api/mempool_8h.html)
101 *Required modules:* [Allocator](#allocator)
103 Here we have a concrete allocator implementation in the sense of a memory pool.
104 This pool allows you to register destructor functions for the allocated memory,
105 which are automatically called on the destruction of the pool.
106 But you may also register *independent* destructor functions within a pool in
107 case, some external library allocated memory for you, which you wish to be
108 destroyed together with this pool.
110 ## Properties
112 *Header file:* [properties.h](api/properties_8h.html)
113 *Required modules:* [Map](#map)
115 This module provides load and store function for `*.properties` files.
116 The key/value pairs are stored within an UCX Map.
118 ### Example: Loading properties from a file
120 ```C
121 // Open the file as usual
122 FILE* file = fopen("myprops.properties", "r");
123 if (!file) {
124 // error handling
125 return 1;
126 }
128 // Load the properties from the file
129 UcxMap* myprops = ucx_map_new(16);
130 if (ucx_properties_load(myprops, file)) {
131 // error handling
132 fclose(file);
133 ucx_map_free(myprops);
134 return 1;
135 }
137 // Print out the key/value pairs
138 char* propval;
139 UcxMapIterator propiter = ucx_map_iterator(myprops);
140 UCX_MAP_FOREACH(key, propval, propiter) {
141 printf("%s = %s\n", (char*)key.data, propval);
142 }
144 // Don't forget to free the values before freeing the map
145 ucx_map_free_content(myprops, NULL);
146 ucx_map_free(myprops);
147 fclose(file);
148 ```
149 ## Stack
151 *Header file:* [stack.h](api/stack_8h.html)
152 *Required modules:* [Allocator](#allocator)
154 This concrete implementation of an UCX Allocator allows you to grab some amount
155 of memory which is then handled as a stack.
156 Please note, that the term *stack* only refers to the behavior of this
157 allocator. You may still choose if you want to use stack or heap memory
158 for the underlying space.
160 A typical use case is an algorithm where you need to allocate and free large
161 amounts of memory very frequently.
163 ## String
165 *Header file:* [string.h](api/string_8h.html)
166 *Required modules:* [Allocator](#allocator)
168 This module provides a safe implementation of bounded string.
169 Usually C strings do not carry a length. While for zero-terminated strings you
170 can easily get the length with `strlen`, this is not generally possible for
171 arbitrary strings.
172 The `sstr_t` type of this module always carries the string and its length to
173 reduce the risk of buffer overflows dramatically.
175 ### Initialization
177 There are several ways to create an `sstr_t`:
179 ```C
180 /* (1) sstr() uses strlen() internally, hence cstr MUST be zero-terminated */
181 sstr_t a = sstr(cstr);
183 /* (2) cstr does not need to be zero-terminated, if length is specified */
184 sstr_t b = sstrn(cstr, len);
186 /* (3) S() macro creates sstr_t from a string using sizeof() and using sstrn().
187 This version is especially useful for function arguments */
188 sstr_t c = S("hello");
190 /* (4) ST() macro creates sstr_t struct literal using sizeof() */
191 sstr_t d = ST("hello");
192 ```
194 You should not use the `S()` or `ST()` macro with string of unknown origin,
195 since the `sizeof()` call might not coincide with the string length in those
196 cases. If you know what you are doing, it can save you some performance,
197 because you do not need the `strlen()` call.
199 ### Finding the position of a substring
201 The `sstrstr()` function gives you a new `sstr_t` object starting with the
202 requested substring. Thus determining the position comes down to a simple
203 subtraction.
205 ```C
206 sstr_t haystack = ST("Here we go!");
207 sstr_t needle = ST("we");
208 sstr_t result = sstrstr(haystack, needle);
209 if (result.ptr)
210 printf("Found at position %zd.\n", haystack.length-result.length);
211 else
212 printf("Not found.\n");
213 ```
215 ### Spliting a string by a delimiter
217 The `sstrsplit()` function (and its allocator based version `sstrsplit_a()`) is
218 very powerful and might look a bit nasty at a first glance. But it is indeed
219 very simple to use. It is even more convenient in combination with a memory
220 pool.
222 ```C
223 sstr_t test = ST("here::are::some::strings");
224 sstr_t delim = ST("::");
226 ssize_t count = 0; /* no limit */
227 UcxMempool* pool = ucx_mempool_new_default();
229 sstr_t* result = sstrsplit_a(pool->allocator, test, delim, &count);
230 for (ssize_t i = 0 ; i < count ; i++) {
231 /* don't forget to specify the length via the %*s format specifier */
232 printf("%*s\n", result[i].length, result[i].ptr);
233 }
235 ucx_mempool_destroy(pool);
236 ```
237 The output is:
239 here
240 are
241 some
242 strings
244 The memory pool ensures, that all strings are freed.
246 ## Testing
248 *Header file:* [test.h](api/test_8h.html)
249 *Required modules:* None.
251 This module provides a testing framework which allows you to execute test cases
252 within test suites.
253 To avoid code duplication within tests, we also provide the possibility to
254 define test subroutines.
256 ## Utilities
258 *Header file:* [utils.h](api/utils_8h.html)
259 *Required modules:* [Allocator](#allocator), [String](#string)
261 In this module we provide very general utility function for copy and compare
262 operations.
263 We also provide several `printf` variants to conveniently print formatted data
264 to streams or strings.
266 ### A simple copy program
268 The utilities package provides several stream copy functions.
269 One of them has a very simple interface and can, for instance, be used to copy
270 whole files in a single call.
271 This is a minimal working example:
272 ```C
273 #include <stdio.h>
274 #include <ucx/utils.h>
276 int main(int argc, char** argv) {
278 if (argc != 3) {
279 fprintf(stderr, "Use %s <src> <dest>", argv[0]);
280 return 1;
281 }
283 FILE *srcf = fopen(argv[1], "r"); // insert error handling on your own
284 FILE *destf = fopen(argv[2], "w");
286 size_t n = ucx_stream_copy(srcf, destf, fread, fwrite);
287 printf("%zu bytes copied.\n", n);
289 fclose(srcf);
290 fclose(destf);
293 return 0;
294 }
295 ```
297 ### Automatic allocation for formatted strings
299 The UCX utility function `ucx_asprintf()` and it's convenient shortcut
300 `ucx_sprintf` allow easy formatting of strings, without ever having to worry
301 about the required space.
302 ```C
303 sstr_t mystring = ucx_sprintf("The answer is: %d!", 42);
304 ```
305 Still, you have to pass `mystring.ptr` to `free()` (or the free function of
306 your allocator, if you use `ucx_asprintf`).
307 If you don't have all the information ready to build your string, you can even
308 use a [UcxBuffer](#buffer) as a target with the utility function
309 `ucx_bprintf()`.
310 ```C
311 UcxBuffer* strbuffer = ucx_buffer_new(NULL, 512, UCX_BUFFER_AUTOEXTEND);
313 for (unsigned int i = 2 ; i < 100 ; i++) {
314 ucx_bprintf(strbuffer, "Integer %d is %s\n",
315 i, prime(i) ? "prime" : "not prime");
316 }
318 // print the result to stdout
319 printf("%s", (char*)strbuffer->space);
321 ucx_buffer_free(strbuffer);
322 ```