docs/src/modules.md

Thu, 07 Nov 2019 10:10:36 +0100

author
Mike Becker <universe@uap-core.de>
date
Thu, 07 Nov 2019 10:10:36 +0100
changeset 369
28a8ccc442b0
parent 359
9f86bc73f96b
child 370
07ac32b385e4
permissions
-rw-r--r--

removes some bugs by redesigning the array API

264
24f5484bae97 web doc has now proper titles
Mike Becker <universe@uap-core.de>
parents: 259
diff changeset
1 ---
24f5484bae97 web doc has now proper titles
Mike Becker <universe@uap-core.de>
parents: 259
diff changeset
2 title: Modules
24f5484bae97 web doc has now proper titles
Mike Becker <universe@uap-core.de>
parents: 259
diff changeset
3 ---
259
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
4
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
5 UCX provides several modules for data structures and algorithms.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
6 You may choose to use specific modules by inclueding the corresponding header
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
7 file.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
8 Please note, that some modules make use of other UCX modules.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
9 For instance, the [Allocator](#allocator) module is used by many other modules
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
10 to allow flexible memory allocation.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
11 By default the header files are placed into an `ucx` directory within your
282
39e69d78b01d minor formatting fix in modules.md
Mike Becker <universe@uap-core.de>
parents: 281
diff changeset
12 systems include directory. In this case you can use a module by including it
259
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
13 via `#include <ucx/MODULENAME.h>`.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
14 Required modules are included automatically.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
15
267
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
16 <div id="modules" align="center">
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
17
340
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
18 ----------------------- ---------------------- -------------------------------- ---------------------------
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
19 [String](#string) [Buffer](#buffer)
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
20 [Allocator](#allocator) [Stack](#stack) [Memory&nbsp;Pool](#memory-pool)
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
21 [Array](#array) [List](#list) [Map](#map) [AVL&nbsp;Tree](#avl-tree)
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
22 [Logging](#logging) [Testing](#testing) [Utilities](#utilities) [Properties](#properties)
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
23 ----------------------- ---------------------- -------------------------------- ---------------------------
267
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
24
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
25 </div>
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
26
259
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
27 ## Allocator
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
28
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
29 *Header file:* [allocator.h](api/allocator_8h.html)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
30 *Required modules:* None.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
31
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
32 A UCX allocator consists of a pointer to the memory area / pool and four
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
33 function pointers to memory management functions operating on this memory
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
34 area / pool. These functions shall behave equivalent to the standard libc
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
35 functions `malloc`, `calloc`, `realloc` and `free`.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
36
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
37 The signature of the memory management functions is based on the signature
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
38 of the respective libc function but each of them takes the pointer to the
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
39 memory area / pool as first argument.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
40
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
41 As the pointer to the memory area / pool can be arbitrarily chosen, any data
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
42 can be provided to the memory management functions. One example is the
280
6e3c4036a80c removes artificial anchors from modules.md
Mike Becker <universe@uap-core.de>
parents: 279
diff changeset
43 [UCX Memory Pool](#memory-pool).
259
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
44
340
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
45 ## Array
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
46
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
47 *Header file:* [array.h](api/array_8h.html)
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
48 *Required modules:* [Allocator](#allocator)
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
49
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
50 The UCX Array is an implementation of a dynamic array with automatic
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
51 reallocation. The array structure contains a capacity, the current size,
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
52 the size of each element, the raw pointer to the memory area and an allocator.
359
9f86bc73f96b adjusts the UcxArray documentation to the recent changes
Mike Becker <universe@uap-core.de>
parents: 340
diff changeset
53 Arrays are in most cases much faster than linked list.
9f86bc73f96b adjusts the UcxArray documentation to the recent changes
Mike Becker <universe@uap-core.de>
parents: 340
diff changeset
54 One can decide, whether to create a new array on the heap with `ucx_array_new()`
9f86bc73f96b adjusts the UcxArray documentation to the recent changes
Mike Becker <universe@uap-core.de>
parents: 340
diff changeset
55 or to save one indirection by initializing a `UcxArray` structure on the stack
9f86bc73f96b adjusts the UcxArray documentation to the recent changes
Mike Becker <universe@uap-core.de>
parents: 340
diff changeset
56 with `ucx_array_init()`.
340
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
57
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
58 ### Remove duplicates from an array of strings
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
59
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
60 The following example shows, how a `UcxArray` can be built with
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
61 a standard dynamic C array (pointer+length) as basis.
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
62
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
63 ```C
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
64 #include <stdio.h>
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
65 #include <ucx/array.h>
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
66 #include <ucx/string.h>
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
67 #include <ucx/utils.h>
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
68
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
69 UcxArray remove_duplicates(sstr_t* array, size_t arrlen) {
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
70 // worst case is no duplicates, hence the capacity is set to arrlen
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
71 UcxArray result = ucx_array_new(arrlen, sizeof(sstr_t));
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
72 // only append elements, if they are not already present in the array
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
73 for (size_t i = 0 ; i < arrlen ; ++i) {
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
74 if (!ucx_array_contains(result, array+i, ucx_cmp_sstr, NULL)) {
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
75 ucx_array_append(&result, array+i);
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
76 }
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
77 }
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
78 // make the array as small as possible
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
79 ucx_array_shrink(&result);
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
80 return result;
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
81 }
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
82
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
83 /* ... */
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
84
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
85 sstr_t* array = /* some standard array of strings */
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
86 size_t arrlen = /* the length of the array */
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
87
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
88 UcxArray result = remove_duplicates(array,arrlen);
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
89
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
90 /* Iterate over the array and print the elements */
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
91 for (size_t i = 0 ; i < result.size ; i++) {
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
92 sstr_t s = ucx_array_at_typed(sstr_t, result, i);
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
93 printf("%" PRIsstr "\n", SFMT(s));
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
94 }
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
95
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
96 /* Free the array. */
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
97 ucx_array_free(&result);
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
98 ```
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
99
259
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
100 ## AVL Tree
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
101
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
102 *Header file:* [avl.h](api/avl_8h.html)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
103 *Required modules:* [Allocator](#allocator)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
104
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
105 This binary search tree implementation allows average O(1) insertion and
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
106 removal of elements (excluding binary search time).
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
107 All common binary tree operations are implemented. Furthermore, this module
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
108 provides search functions via lower and upper bounds.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
109
287
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
110 ### Filtering items with a time window
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
111
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
112 Suppose you have a list of items which contain a `time_t` value and your task
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
113 is to find all items within a time window `[t_start, t_end]`.
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
114 With AVL Trees this is easy:
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
115 ```C
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
116 /* ---------------------
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
117 * Somewhere in a header
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
118 */
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
119 typedef struct {
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
120 time_t ts;
294
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
121 /* other important data */
287
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
122 } MyObject;
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
123
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
124 /* -----------
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
125 * Source code
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
126 */
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
127
314
5d28dc8f0765 renames int and longint distance and compare functions according to the new scheme
Mike Becker <universe@uap-core.de>
parents: 310
diff changeset
128 UcxAVLTree* tree = ucx_avl_new(ucx_cmp_longint);
294
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
129 /* ... populate tree with objects, use '& MyObject.ts' as key ... */
287
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
130
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
131
294
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
132 /* Now find every item, with 30 <= ts <= 70 */
287
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
133 time_t ts_start = 30;
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
134 time_t ts_end = 70;
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
135
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
136 printf("Values in range:\n");
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
137 for (
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
138 UcxAVLNode* node = ucx_avl_find_node(
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
139 tree, (intptr_t) &ts_start,
314
5d28dc8f0765 renames int and longint distance and compare functions according to the new scheme
Mike Becker <universe@uap-core.de>
parents: 310
diff changeset
140 ucx_dist_longint, UCX_AVL_FIND_LOWER_BOUNDED);
287
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
141 node && (*(time_t*)node->key) <= ts_end;
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
142 node = ucx_avl_succ(node)
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
143 ) {
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
144 printf(" ts: %ld\n", ((MyObject*)node->value)->ts);
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
145 }
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
146
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
147 ucx_avl_free_content(tree, free);
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
148 ucx_avl_free(tree);
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
149 ```
98da78a1e69a adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents: 282
diff changeset
150
259
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
151 ## Buffer
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
152
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
153 *Header file:* [buffer.h](api/buffer_8h.html)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
154 *Required modules:* None.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
155
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
156 Instances of this buffer implementation can be used to read from or to write to
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
157 memory like you would do with a stream. This allows the use of
282
39e69d78b01d minor formatting fix in modules.md
Mike Becker <universe@uap-core.de>
parents: 281
diff changeset
158 `ucx_stream_copy()` from the [Utilities](#utilities) module to copy contents
39e69d78b01d minor formatting fix in modules.md
Mike Becker <universe@uap-core.de>
parents: 281
diff changeset
159 from one buffer to another or from file or network streams to the buffer and
259
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
160 vice-versa.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
161
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
162 More features for convenient use of the buffer can be enabled, like automatic
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
163 memory management and automatic resizing of the buffer space.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
164 See the documentation of the macro constants in the header file for more
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
165 information.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
166
290
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
167 ### Add line numbers to a file
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
168
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
169 When reading a file line by line, you have three options: first, you could limit
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
170 the maximum supported line length.
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
171 Second, you allocate a god buffer large
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
172 enough for the most lines a text file could have.
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
173 And third, undoubtedly the best option, you start with a small buffer, which
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
174 adjusts on demand.
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
175 An `UcxBuffer` can be created to do just that for you.
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
176 Just pass the `UCX_BUFFER_AUTOEXTEND` option to the initialization function.
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
177 Here is a full working program, which adds line numbers to a file.
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
178 ```C
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
179 #include <stdio.h>
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
180 #include <ucx/buffer.h>
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
181 #include <ucx/utils.h>
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
182
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
183 int main(int argc, char** argv) {
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
184
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
185 if (argc != 2) {
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
186 fprintf(stderr, "Usage: %s <file>\n", argv[0]);
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
187 return 1;
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
188 }
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
189
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
190 FILE* input = fopen(argv[1], "r");
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
191 if (!input) {
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
192 perror("Canno read input");
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
193 return 1;
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
194 }
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
195
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
196 const size_t chunksize = 256;
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
197
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
198 UcxBuffer* linebuf =
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
199 ucx_buffer_new(
294
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
200 NULL, /* the buffer should manage the memory area for us */
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
201 2*chunksize, /* initial size should be twice the chunk size */
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
202 UCX_BUFFER_AUTOEXTEND); /* the buffer will grow when necessary */
290
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
203
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
204 size_t lineno = 1;
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
205 do {
294
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
206 /* read line chunk */
290
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
207 size_t read = ucx_stream_ncopy(
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
208 input, linebuf, fread, ucx_buffer_write, chunksize);
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
209 if (read == 0) break;
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
210
294
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
211 /* handle line endings */
290
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
212 do {
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
213 sstr_t bufstr = ucx_buffer_to_sstr(linebuf);
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
214 sstr_t nl = sstrchr(bufstr, '\n');
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
215 if (nl.length == 0) break;
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
216
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
217 size_t linelen = bufstr.length - nl.length;
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
218 sstr_t linestr = sstrsubsl(bufstr, 0, linelen);
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
219
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
220 printf("%zu: %" PRIsstr "\n", lineno++, SFMT(linestr));
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
221
294
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
222 /* shift the buffer to the next line */
290
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
223 ucx_buffer_shift_left(linebuf, linelen+1);
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
224 } while(1);
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
225
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
226 } while(1);
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
227
294
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
228 /* print the 'noeol' line, if any */
290
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
229 sstr_t lastline = ucx_buffer_to_sstr(linebuf);
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
230 if (lastline.length > 0) {
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
231 printf("%zu: %" PRIsstr, lineno, SFMT(lastline));
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
232 }
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
233
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
234 fclose(input);
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
235 ucx_buffer_free(linebuf);
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
236
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
237 return 0;
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
238 }
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
239 ```
d5d6ab809ad3 adds new shift operations for UcxBuffer (including tests and a usage example in modules.md)
Mike Becker <universe@uap-core.de>
parents: 287
diff changeset
240
259
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
241 ## List
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
242
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
243 *Header file:* [list.h](api/list_8h.html)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
244 *Required modules:* [Allocator](#allocator)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
245
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
246 This module provides the data structure and several functions for a doubly
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
247 linked list. Among the common operations like insert, remove, search and sort,
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
248 we allow convenient iteration via a special `UCX_FOREACH` macro.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
249
294
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
250 ### Remove duplicates from an array of strings
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
251
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
252 Assume you are given an array of `sstr_t` and want to create a list of these
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
253 strings without duplicates.
340
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
254 This is a similar example to the one [above](#array), but here we are
8acf182f6424 adds documentation
Mike Becker <universe@uap-core.de>
parents: 326
diff changeset
255 using a `UcxList`.
294
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
256 ```C
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
257 #include <stdio.h>
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
258 #include <ucx/list.h>
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
259 #include <ucx/string.h>
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
260 #include <ucx/utils.h>
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
261
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
262 UcxList* remove_duplicates(sstr_t* array, size_t arrlen) {
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
263 UcxList* list = NULL;
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
264 for (size_t i = 0 ; i < arrlen ; ++i) {
310
b09677d72413 renames ucx_sstrcmp() to ucx_cmp_sstr()
Mike Becker <universe@uap-core.de>
parents: 304
diff changeset
265 if (ucx_list_find(list, array+i, ucx_cmp_sstr, NULL) == -1) {
294
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
266 sstr_t* s = malloc(sizeof(sstr_t));
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
267 *s = sstrdup(array[i]);
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
268 list = ucx_list_append(list, s);
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
269 }
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
270 }
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
271 return list;
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
272 }
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
273
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
274 /* we will need this function to clean up the list contents later */
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
275 void free_sstr(void* ptr) {
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
276 sstr_t* s = ptr;
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
277 free(s->ptr);
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
278 free(s);
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
279 }
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
280
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
281 /* ... */
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
282
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
283 sstr_t* array = /* some array of strings */
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
284 size_t arrlen = /* the length of the array */
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
285
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
286 UcxList* list = remove_duplicates(array,arrlen);
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
287
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
288 /* Iterate over the list and print the elements */
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
289 UCX_FOREACH(elem, list) {
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
290 sstr_t s = *((sstr_t*)elem->data);
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
291 printf("%" PRIsstr "\n", SFMT(s));
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
292 }
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
293
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
294 /* Use our free function to free the duplicated strings. */
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
295 ucx_list_free_content(list, free_sstr);
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
296 ucx_list_free(list);
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
297 ```
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
298
259
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
299 ## Logging
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
300
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
301 *Header file:* [logging.h](api/logging_8h.html)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
302 *Required modules:* [Map](#map), [String](#string)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
303
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
304 The logging module comes with some predefined log levels and allows some more
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
305 customization. You may choose if you want to get timestamps or source file and
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
306 line number logged automatically when outputting a message.
295
7fc65395188e documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents: 294
diff changeset
307 The following function call initializes a debug logger with all of the above
7fc65395188e documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents: 294
diff changeset
308 information:
7fc65395188e documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents: 294
diff changeset
309 ```C
7fc65395188e documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents: 294
diff changeset
310 log = ucx_logger_new(stdout, UCX_LOGGER_DEBUG,
7fc65395188e documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents: 294
diff changeset
311 UCX_LOGGER_LEVEL | UCX_LOGGER_TIMESTAMP | UCX_LOGGER_SOURCE);
7fc65395188e documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents: 294
diff changeset
312 ```
7fc65395188e documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents: 294
diff changeset
313 Afterwards you can use this logger with the predefined macros
7fc65395188e documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents: 294
diff changeset
314 ```C
7fc65395188e documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents: 294
diff changeset
315 ucx_logger_trace(log, "Verbose output");
7fc65395188e documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents: 294
diff changeset
316 ucx_logger_debug(log, "Debug message");
7fc65395188e documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents: 294
diff changeset
317 ucx_logger_info(log, "Information");
7fc65395188e documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents: 294
diff changeset
318 ucx_logger_warn(log, "Warning");
7fc65395188e documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents: 294
diff changeset
319 ucx_logger_error(log, "Error message");
7fc65395188e documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents: 294
diff changeset
320 ```
7fc65395188e documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents: 294
diff changeset
321 or you use
7fc65395188e documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents: 294
diff changeset
322 ```C
7fc65395188e documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents: 294
diff changeset
323 ucx_logger_log(log, CUSTOM_LEVEL, "Some message")
7fc65395188e documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents: 294
diff changeset
324 ```
7fc65395188e documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents: 294
diff changeset
325 When you use your custom log level, don't forget to register it with
7fc65395188e documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents: 294
diff changeset
326 ```C
7fc65395188e documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents: 294
diff changeset
327 ucx_logger_register_level(log, CUSTOM_LEVEL, "CUSTOM")
7fc65395188e documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents: 294
diff changeset
328 ```
7fc65395188e documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents: 294
diff changeset
329 where the last argument must be a string literal.
259
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
330
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
331 ## Map
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
332
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
333 *Header file:* [map.h](api/map_8h.html)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
334 *Required modules:* [Allocator](#allocator), [String](#string)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
335
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
336 This module provides a hash map implementation using murmur hash 2 and separate
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
337 chaining with linked lists. Similarly to the list module, we provide a
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
338 `UCX_MAP_FOREACH` macro to conveniently iterate through the key/value pairs.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
339
298
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
340 ### Parsing command line options
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
341
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
342 Assume you want to parse command line options and record them within a map.
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
343 One way to do this is shown by the following code sample:
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
344 ```C
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
345 UcxMap* options = ucx_map_new(16);
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
346 const char *NOARG = "";
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
347
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
348 char *option = NULL;
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
349 char optchar = 0;
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
350 for(int i=1;i<argc;i++) {
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
351 char *arg = argv[i];
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
352 size_t len = strlen(arg);
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
353 if(len > 1 && arg[0] == '-') {
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
354 for(int c=1;c<len;c++) {
299
e7dfcf229625 adjusts code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 298
diff changeset
355 if(option) {
e7dfcf229625 adjusts code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 298
diff changeset
356 fprintf(stderr,
e7dfcf229625 adjusts code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 298
diff changeset
357 "Missing argument for option -%c\n", optchar);
e7dfcf229625 adjusts code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 298
diff changeset
358 return 1;
e7dfcf229625 adjusts code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 298
diff changeset
359 }
298
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
360 switch(arg[c]) {
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
361 default: {
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
362 fprintf(stderr, "Unknown option -%c\n\n", arg[c]);
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
363 return 1;
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
364 }
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
365 case 'v': {
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
366 ucx_map_cstr_put(options, "verbose", NOARG);
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
367 break;
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
368 }
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
369 case 'o': {
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
370 option = "output";
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
371 optchar = 'o';
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
372 break;
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
373 }
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
374 }
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
375 }
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
376 } else if(option) {
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
377 ucx_map_cstr_put(options, option, arg);
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
378 option = NULL;
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
379 } else {
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
380 /* ... handle argument that is not an option ... */
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
381 }
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
382 }
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
383 if(option) {
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
384 fprintf(stderr,
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
385 "Missing argument for option -%c\n", optchar);
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
386 return 1;
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
387 }
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
388 ```
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
389 With the following loop, you can access the previously recorded options:
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
390 ```C
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
391 UcxMapIterator iter = ucx_map_iterator(options);
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
392 char *arg;
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
393 UCX_MAP_FOREACH(optkey, arg, iter) {
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
394 char* opt = optkey.data;
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
395 if (*arg) {
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
396 printf("%s = %s\n", opt, arg);
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
397 } else {
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
398 printf("%s active\n", opt);
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
399 }
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
400 }
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
401 ```
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
402 Don't forget to call `ucx_map_free()`, when you are done with the map.
fffe3a16a3de adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents: 297
diff changeset
403
259
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
404 ## Memory Pool
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
405
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
406 *Header file:* [mempool.h](api/mempool_8h.html)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
407 *Required modules:* [Allocator](#allocator)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
408
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
409 Here we have a concrete allocator implementation in the sense of a memory pool.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
410 This pool allows you to register destructor functions for the allocated memory,
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
411 which are automatically called on the destruction of the pool.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
412 But you may also register *independent* destructor functions within a pool in
302
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
413 case some external library allocated memory for you, which should be
259
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
414 destroyed together with this pool.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
415
302
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
416 Many UCX modules support the use of an allocator.
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
417 The [String Module](#string), for instance, provides the `sstrdup_a()` function,
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
418 which uses the specified allocator to allocate the memory for the duplicated
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
419 string.
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
420 This way, you can use a `UcxMempool` to keep track of the memory occupied by
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
421 duplicated strings and cleanup everything with just a single call to
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
422 `ucx_mempool_destroy()`.
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
423
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
424 ### Read CSV data into a structure
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
425
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
426 The following code example shows some of the basic memory pool functions and
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
427 how they can be used with other UCX modules.
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
428 ```C
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
429 #include <stdio.h>
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
430 #include <ucx/mempool.h>
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
431 #include <ucx/list.h>
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
432 #include <ucx/string.h>
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
433 #include <ucx/buffer.h>
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
434 #include <ucx/utils.h>
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
435
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
436 typedef struct {
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
437 sstr_t column_a;
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
438 sstr_t column_b;
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
439 sstr_t column_c;
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
440 } CSVData;
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
441
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
442 int main(int argc, char** argv) {
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
443
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
444 UcxMempool* pool = ucx_mempool_new(128);
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
445
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
446 FILE *f = fopen("test.csv", "r");
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
447 if (!f) {
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
448 perror("Cannot open file");
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
449 return 1;
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
450 }
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
451 /* close the file automatically at pool destruction*/
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
452 ucx_mempool_reg_destr(pool, f, (ucx_destructor) fclose);
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
453
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
454 /* create a buffer and register it at the memory pool for destruction */
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
455 UcxBuffer* content = ucx_buffer_new(NULL, 256, UCX_BUFFER_AUTOEXTEND);
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
456 ucx_mempool_reg_destr(pool, content, (ucx_destructor) ucx_buffer_free);
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
457
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
458 /* read the file and split it by lines first */
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
459 ucx_stream_copy(f, content, fread, ucx_buffer_write);
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
460 sstr_t contentstr = ucx_buffer_to_sstr(content);
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
461 ssize_t lc = 0;
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
462 sstr_t* lines = sstrsplit_a(pool->allocator, contentstr, S("\n"), &lc);
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
463
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
464 /* skip the header and parse the remaining data */
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
465 UcxList* datalist = NULL;
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
466 for (size_t i = 1 ; i < lc ; i++) {
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
467 if (lines[i].length == 0) continue;
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
468 ssize_t fc = 3;
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
469 sstr_t* fields = sstrsplit_a(pool->allocator, lines[i], S(";"), &fc);
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
470 if (fc != 3) {
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
471 fprintf(stderr, "Syntax error in line %zu.\n", i);
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
472 ucx_mempool_destroy(pool);
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
473 return 1;
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
474 }
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
475 CSVData* data = ucx_mempool_malloc(pool, sizeof(CSVData));
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
476 data->column_a = fields[0];
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
477 data->column_b = fields[1];
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
478 data->column_c = fields[2];
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
479 datalist = ucx_list_append_a(pool->allocator, datalist, data);
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
480 }
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
481
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
482 /* control output */
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
483 UCX_FOREACH(elem, datalist) {
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
484 CSVData* data = elem->data;
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
485 printf("Column A: %" PRIsstr " | "
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
486 "Column B: %" PRIsstr " | "
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
487 "Column C: %" PRIsstr "\n",
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
488 SFMT(data->column_a), SFMT(data->column_b), SFMT(data->column_c)
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
489 );
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
490 }
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
491
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
492 /* cleanup everything, no manual free() needed */
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
493 ucx_mempool_destroy(pool);
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
494
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
495 return 0;
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
496 }
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
497 ```
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
498
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
499 ### Overriding the default destructor
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
500
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
501 Sometimes you need to allocate memory with `ucx_mempool_malloc()`, but the
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
502 memory is not supposed to be freed with a simple call to `free()`.
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
503 In this case, you can overwrite the default destructor as follows:
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
504 ```C
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
505 MyObject* obj = ucx_mempool_malloc(pool, sizeof(MyObject));
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
506
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
507 /* some special initialization with own resource management */
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
508 my_object_init(obj);
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
509
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
510 /* register destructor function */
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
511 ucx_mempool_set_destr(obj, (ucx_destructor) my_object_destroy);
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
512 ```
304
1f9237cfeb26 fixes typo in modules.md
Mike Becker <universe@uap-core.de>
parents: 302
diff changeset
513 Be aware, that your destructor function should not free any memory, that is
302
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
514 also managed by the pool.
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
515 Otherwise you might be risking a double-free.
326
3dd7d21fb76b being more precise on the different required behavior of a destructor function for pooled and non-pooled memory
Mike Becker <universe@uap-core.de>
parents: 325
diff changeset
516 More precisely, a destructor function set with `ucx_mempool_set_destr()` MUST
3dd7d21fb76b being more precise on the different required behavior of a destructor function for pooled and non-pooled memory
Mike Becker <universe@uap-core.de>
parents: 325
diff changeset
517 NOT call `free()` on the specified pointer whereas a desructor function
3dd7d21fb76b being more precise on the different required behavior of a destructor function for pooled and non-pooled memory
Mike Becker <universe@uap-core.de>
parents: 325
diff changeset
518 registered with `ucx_mempool_reg_destr()` MAY (and in most cases will) call
3dd7d21fb76b being more precise on the different required behavior of a destructor function for pooled and non-pooled memory
Mike Becker <universe@uap-core.de>
parents: 325
diff changeset
519 `free()`.
302
8628147734d6 comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents: 301
diff changeset
520
259
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
521 ## Properties
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
522
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
523 *Header file:* [properties.h](api/properties_8h.html)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
524 *Required modules:* [Map](#map)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
525
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
526 This module provides load and store function for `*.properties` files.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
527 The key/value pairs are stored within an UCX Map.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
528
277
f819fe5e20f5 makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents: 267
diff changeset
529 ### Example: Loading properties from a file
f819fe5e20f5 makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents: 267
diff changeset
530
f819fe5e20f5 makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents: 267
diff changeset
531 ```C
294
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
532 /* Open the file as usual */
277
f819fe5e20f5 makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents: 267
diff changeset
533 FILE* file = fopen("myprops.properties", "r");
f819fe5e20f5 makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents: 267
diff changeset
534 if (!file) {
f819fe5e20f5 makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents: 267
diff changeset
535 // error handling
f819fe5e20f5 makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents: 267
diff changeset
536 return 1;
f819fe5e20f5 makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents: 267
diff changeset
537 }
f819fe5e20f5 makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents: 267
diff changeset
538
294
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
539 /* Load the properties from the file */
277
f819fe5e20f5 makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents: 267
diff changeset
540 UcxMap* myprops = ucx_map_new(16);
f819fe5e20f5 makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents: 267
diff changeset
541 if (ucx_properties_load(myprops, file)) {
294
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
542 /* ... error handling ... */
277
f819fe5e20f5 makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents: 267
diff changeset
543 fclose(file);
f819fe5e20f5 makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents: 267
diff changeset
544 ucx_map_free(myprops);
f819fe5e20f5 makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents: 267
diff changeset
545 return 1;
f819fe5e20f5 makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents: 267
diff changeset
546 }
f819fe5e20f5 makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents: 267
diff changeset
547
294
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
548 /* Print out the key/value pairs */
277
f819fe5e20f5 makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents: 267
diff changeset
549 char* propval;
f819fe5e20f5 makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents: 267
diff changeset
550 UcxMapIterator propiter = ucx_map_iterator(myprops);
f819fe5e20f5 makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents: 267
diff changeset
551 UCX_MAP_FOREACH(key, propval, propiter) {
f819fe5e20f5 makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents: 267
diff changeset
552 printf("%s = %s\n", (char*)key.data, propval);
f819fe5e20f5 makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents: 267
diff changeset
553 }
f819fe5e20f5 makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents: 267
diff changeset
554
294
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
555 /* Don't forget to free the values before freeing the map */
277
f819fe5e20f5 makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents: 267
diff changeset
556 ucx_map_free_content(myprops, NULL);
f819fe5e20f5 makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents: 267
diff changeset
557 ucx_map_free(myprops);
f819fe5e20f5 makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents: 267
diff changeset
558 fclose(file);
f819fe5e20f5 makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents: 267
diff changeset
559 ```
295
7fc65395188e documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents: 294
diff changeset
560
259
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
561 ## Stack
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
562
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
563 *Header file:* [stack.h](api/stack_8h.html)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
564 *Required modules:* [Allocator](#allocator)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
565
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
566 This concrete implementation of an UCX Allocator allows you to grab some amount
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
567 of memory which is then handled as a stack.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
568 Please note, that the term *stack* only refers to the behavior of this
301
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
569 allocator. You may still choose to use either stack or heap memory
259
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
570 for the underlying space.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
571 A typical use case is an algorithm where you need to allocate and free large
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
572 amounts of memory very frequently.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
573
301
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
574 The following code sample shows how to initialize a stack and push and pop
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
575 simple data.
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
576 ```C
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
577 const size_t len = 1024;
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
578 char space[len];
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
579 UcxStack stack;
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
580 ucx_stack_init(&stack, space, len);
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
581
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
582 int i = 42;
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
583 float f = 3.14f;
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
584 const char* str = "Hello!";
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
585 size_t strn = 7;
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
586
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
587 /* push the integer */
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
588 ucx_stack_push(&stack, sizeof(int), &i);
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
589
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
590 /* push the float and rember the address */
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
591 float* remember = ucx_stack_push(&stack, sizeof(float), &f);
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
592
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
593 /* push the string with zero terminator */
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
594 ucx_stack_push(&stack, strn, str);
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
595
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
596 /* if we forget, how big an element was, we can ask the stack */
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
597 printf("Length of string: %zu\n", ucx_stack_topsize(&stack)-1);
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
598
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
599 /* retrieve the string as sstr_t, without zero terminator! */
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
600 sstr_t s;
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
601 s.length = ucx_stack_topsize(&stack)-1;
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
602 s.ptr = malloc(s.length);
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
603 ucx_stack_popn(&stack, s.ptr, s.length);
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
604 printf("%" PRIsstr "\n", SFMT(s));
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
605
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
606 /* print the float directly from the stack and free it */
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
607 printf("Float: %f\n", *remember);
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
608 ucx_stack_free(&stack, remember);
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
609
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
610 /* the last element is the integer */
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
611 int j;
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
612 ucx_stack_pop(&stack, &j);
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
613 printf("Integer: %d\n", j);
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
614 ```
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
615
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
616
0f83916c1639 documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents: 299
diff changeset
617
259
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
618 ## String
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
619
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
620 *Header file:* [string.h](api/string_8h.html)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
621 *Required modules:* [Allocator](#allocator)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
622
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
623 This module provides a safe implementation of bounded string.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
624 Usually C strings do not carry a length. While for zero-terminated strings you
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
625 can easily get the length with `strlen`, this is not generally possible for
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
626 arbitrary strings.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
627 The `sstr_t` type of this module always carries the string and its length to
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
628 reduce the risk of buffer overflows dramatically.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
629
267
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
630 ### Initialization
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
631
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
632 There are several ways to create an `sstr_t`:
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
633
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
634 ```C
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
635 /* (1) sstr() uses strlen() internally, hence cstr MUST be zero-terminated */
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
636 sstr_t a = sstr(cstr);
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
637
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
638 /* (2) cstr does not need to be zero-terminated, if length is specified */
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
639 sstr_t b = sstrn(cstr, len);
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
640
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
641 /* (3) S() macro creates sstr_t from a string using sizeof() and using sstrn().
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
642 This version is especially useful for function arguments */
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
643 sstr_t c = S("hello");
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
644
325
a3e63cb21e20 changes sstr shortcut macros s.t. they distinguish sstr_t and scstr_t + add macros which can completely disable the shortcuts
Mike Becker <universe@uap-core.de>
parents: 321
diff changeset
645 /* (4) SC() macro works like S(), but makes the string immutable using scstr_t.
a3e63cb21e20 changes sstr shortcut macros s.t. they distinguish sstr_t and scstr_t + add macros which can completely disable the shortcuts
Mike Becker <universe@uap-core.de>
parents: 321
diff changeset
646 (available since UCX 2.0) */
a3e63cb21e20 changes sstr shortcut macros s.t. they distinguish sstr_t and scstr_t + add macros which can completely disable the shortcuts
Mike Becker <universe@uap-core.de>
parents: 321
diff changeset
647 scstr_t d = SC("hello");
a3e63cb21e20 changes sstr shortcut macros s.t. they distinguish sstr_t and scstr_t + add macros which can completely disable the shortcuts
Mike Becker <universe@uap-core.de>
parents: 321
diff changeset
648
a3e63cb21e20 changes sstr shortcut macros s.t. they distinguish sstr_t and scstr_t + add macros which can completely disable the shortcuts
Mike Becker <universe@uap-core.de>
parents: 321
diff changeset
649 /* (5) ST() macro creates sstr_t struct literal using sizeof() */
a3e63cb21e20 changes sstr shortcut macros s.t. they distinguish sstr_t and scstr_t + add macros which can completely disable the shortcuts
Mike Becker <universe@uap-core.de>
parents: 321
diff changeset
650 sstr_t e = ST("hello");
267
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
651 ```
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
652
325
a3e63cb21e20 changes sstr shortcut macros s.t. they distinguish sstr_t and scstr_t + add macros which can completely disable the shortcuts
Mike Becker <universe@uap-core.de>
parents: 321
diff changeset
653 You should not use the `S()`, `SC()`, or `ST()` macro with string of unknown
a3e63cb21e20 changes sstr shortcut macros s.t. they distinguish sstr_t and scstr_t + add macros which can completely disable the shortcuts
Mike Becker <universe@uap-core.de>
parents: 321
diff changeset
654 origin, since the `sizeof()` call might not coincide with the string length in
a3e63cb21e20 changes sstr shortcut macros s.t. they distinguish sstr_t and scstr_t + add macros which can completely disable the shortcuts
Mike Becker <universe@uap-core.de>
parents: 321
diff changeset
655 those cases. If you know what you are doing, it can save you some performance,
267
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
656 because you do not need the `strlen()` call.
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
657
321
9af21a50b516 adds scstr_t to modules.md + fixes parenthesis bug in sstrsplit_a macro
Mike Becker <universe@uap-core.de>
parents: 314
diff changeset
658 ### Handling immutable strings
9af21a50b516 adds scstr_t to modules.md + fixes parenthesis bug in sstrsplit_a macro
Mike Becker <universe@uap-core.de>
parents: 314
diff changeset
659
9af21a50b516 adds scstr_t to modules.md + fixes parenthesis bug in sstrsplit_a macro
Mike Becker <universe@uap-core.de>
parents: 314
diff changeset
660 *(Since: UCX 2.0)*
9af21a50b516 adds scstr_t to modules.md + fixes parenthesis bug in sstrsplit_a macro
Mike Becker <universe@uap-core.de>
parents: 314
diff changeset
661
9af21a50b516 adds scstr_t to modules.md + fixes parenthesis bug in sstrsplit_a macro
Mike Becker <universe@uap-core.de>
parents: 314
diff changeset
662 For immutable strings (i.e. `const char*` strings), UCX provides the `scstr_t`
9af21a50b516 adds scstr_t to modules.md + fixes parenthesis bug in sstrsplit_a macro
Mike Becker <universe@uap-core.de>
parents: 314
diff changeset
663 type, which works exactly as the `sstr_t` type but with a pointer
9af21a50b516 adds scstr_t to modules.md + fixes parenthesis bug in sstrsplit_a macro
Mike Becker <universe@uap-core.de>
parents: 314
diff changeset
664 to `const char`. All UCX string functions come in two flavors: one that enforces
9af21a50b516 adds scstr_t to modules.md + fixes parenthesis bug in sstrsplit_a macro
Mike Becker <universe@uap-core.de>
parents: 314
diff changeset
665 the `scstr_t` type, and another that usually accepts both types and performs
9af21a50b516 adds scstr_t to modules.md + fixes parenthesis bug in sstrsplit_a macro
Mike Becker <universe@uap-core.de>
parents: 314
diff changeset
666 a conversion automatically, if necessary.
9af21a50b516 adds scstr_t to modules.md + fixes parenthesis bug in sstrsplit_a macro
Mike Becker <universe@uap-core.de>
parents: 314
diff changeset
667
9af21a50b516 adds scstr_t to modules.md + fixes parenthesis bug in sstrsplit_a macro
Mike Becker <universe@uap-core.de>
parents: 314
diff changeset
668 There are some exceptions to this rule, as the return type may depend on the
9af21a50b516 adds scstr_t to modules.md + fixes parenthesis bug in sstrsplit_a macro
Mike Becker <universe@uap-core.de>
parents: 314
diff changeset
669 argument type.
9af21a50b516 adds scstr_t to modules.md + fixes parenthesis bug in sstrsplit_a macro
Mike Becker <universe@uap-core.de>
parents: 314
diff changeset
670 E.g. the `sstrchr()` function returns a substring starting at
9af21a50b516 adds scstr_t to modules.md + fixes parenthesis bug in sstrsplit_a macro
Mike Becker <universe@uap-core.de>
parents: 314
diff changeset
671 the first occurrence of the specified character.
9af21a50b516 adds scstr_t to modules.md + fixes parenthesis bug in sstrsplit_a macro
Mike Becker <universe@uap-core.de>
parents: 314
diff changeset
672 Since this substring points to the memory of the argument string, it does not
9af21a50b516 adds scstr_t to modules.md + fixes parenthesis bug in sstrsplit_a macro
Mike Becker <universe@uap-core.de>
parents: 314
diff changeset
673 accept `scstr_t` as input argument, because the return type would break the
9af21a50b516 adds scstr_t to modules.md + fixes parenthesis bug in sstrsplit_a macro
Mike Becker <universe@uap-core.de>
parents: 314
diff changeset
674 constness.
9af21a50b516 adds scstr_t to modules.md + fixes parenthesis bug in sstrsplit_a macro
Mike Becker <universe@uap-core.de>
parents: 314
diff changeset
675
9af21a50b516 adds scstr_t to modules.md + fixes parenthesis bug in sstrsplit_a macro
Mike Becker <universe@uap-core.de>
parents: 314
diff changeset
676
267
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
677 ### Finding the position of a substring
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
678
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
679 The `sstrstr()` function gives you a new `sstr_t` object starting with the
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
680 requested substring. Thus determining the position comes down to a simple
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
681 subtraction.
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
682
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
683 ```C
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
684 sstr_t haystack = ST("Here we go!");
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
685 sstr_t needle = ST("we");
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
686 sstr_t result = sstrstr(haystack, needle);
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
687 if (result.ptr)
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
688 printf("Found at position %zd.\n", haystack.length-result.length);
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
689 else
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
690 printf("Not found.\n");
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
691 ```
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
692
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
693 ### Spliting a string by a delimiter
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
694
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
695 The `sstrsplit()` function (and its allocator based version `sstrsplit_a()`) is
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
696 very powerful and might look a bit nasty at a first glance. But it is indeed
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
697 very simple to use. It is even more convenient in combination with a memory
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
698 pool.
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
699
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
700 ```C
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
701 sstr_t test = ST("here::are::some::strings");
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
702 sstr_t delim = ST("::");
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
703
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
704 ssize_t count = 0; /* no limit */
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
705 UcxMempool* pool = ucx_mempool_new_default();
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
706
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
707 sstr_t* result = sstrsplit_a(pool->allocator, test, delim, &count);
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
708 for (ssize_t i = 0 ; i < count ; i++) {
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
709 /* don't forget to specify the length via the %*s format specifier */
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
710 printf("%*s\n", result[i].length, result[i].ptr);
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
711 }
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
712
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
713 ucx_mempool_destroy(pool);
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
714 ```
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
715 The output is:
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
716
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
717 here
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
718 are
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
719 some
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
720 strings
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
721
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
722 The memory pool ensures, that all strings are freed.
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
723
325
a3e63cb21e20 changes sstr shortcut macros s.t. they distinguish sstr_t and scstr_t + add macros which can completely disable the shortcuts
Mike Becker <universe@uap-core.de>
parents: 321
diff changeset
724 ### Disabling convenience macros
a3e63cb21e20 changes sstr shortcut macros s.t. they distinguish sstr_t and scstr_t + add macros which can completely disable the shortcuts
Mike Becker <universe@uap-core.de>
parents: 321
diff changeset
725
a3e63cb21e20 changes sstr shortcut macros s.t. they distinguish sstr_t and scstr_t + add macros which can completely disable the shortcuts
Mike Becker <universe@uap-core.de>
parents: 321
diff changeset
726 If you are experiencing any troubles with the short convenience macros `S()`,
a3e63cb21e20 changes sstr shortcut macros s.t. they distinguish sstr_t and scstr_t + add macros which can completely disable the shortcuts
Mike Becker <universe@uap-core.de>
parents: 321
diff changeset
727 `SC()`, or `ST()`, you can disable them by setting the macro
a3e63cb21e20 changes sstr shortcut macros s.t. they distinguish sstr_t and scstr_t + add macros which can completely disable the shortcuts
Mike Becker <universe@uap-core.de>
parents: 321
diff changeset
728 `UCX_NO_SSTR_SHORTCUTS` before including the header (or via a compiler option).
a3e63cb21e20 changes sstr shortcut macros s.t. they distinguish sstr_t and scstr_t + add macros which can completely disable the shortcuts
Mike Becker <universe@uap-core.de>
parents: 321
diff changeset
729 For the formatting macros `SFMT()` and `PRIsstr` you can use the macro
a3e63cb21e20 changes sstr shortcut macros s.t. they distinguish sstr_t and scstr_t + add macros which can completely disable the shortcuts
Mike Becker <universe@uap-core.de>
parents: 321
diff changeset
730 `UCX_NO_SSTR_FORMAT_MACROS` to disable them.
a3e63cb21e20 changes sstr shortcut macros s.t. they distinguish sstr_t and scstr_t + add macros which can completely disable the shortcuts
Mike Becker <universe@uap-core.de>
parents: 321
diff changeset
731
a3e63cb21e20 changes sstr shortcut macros s.t. they distinguish sstr_t and scstr_t + add macros which can completely disable the shortcuts
Mike Becker <universe@uap-core.de>
parents: 321
diff changeset
732 Please keep in mind, that after disabling the macros, you cannot use them in
a3e63cb21e20 changes sstr shortcut macros s.t. they distinguish sstr_t and scstr_t + add macros which can completely disable the shortcuts
Mike Becker <universe@uap-core.de>
parents: 321
diff changeset
733 your code *and* foreign code that you might have included.
a3e63cb21e20 changes sstr shortcut macros s.t. they distinguish sstr_t and scstr_t + add macros which can completely disable the shortcuts
Mike Becker <universe@uap-core.de>
parents: 321
diff changeset
734 You should only disable the macros, if you are experiencing a nasty name clash
a3e63cb21e20 changes sstr shortcut macros s.t. they distinguish sstr_t and scstr_t + add macros which can completely disable the shortcuts
Mike Becker <universe@uap-core.de>
parents: 321
diff changeset
735 which cannot be otherwise resolved.
a3e63cb21e20 changes sstr shortcut macros s.t. they distinguish sstr_t and scstr_t + add macros which can completely disable the shortcuts
Mike Becker <universe@uap-core.de>
parents: 321
diff changeset
736
259
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
737 ## Testing
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
738
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
739 *Header file:* [test.h](api/test_8h.html)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
740 *Required modules:* None.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
741
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
742 This module provides a testing framework which allows you to execute test cases
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
743 within test suites.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
744 To avoid code duplication within tests, we also provide the possibility to
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
745 define test subroutines.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
746
297
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
747 You should declare test cases and subroutines in a header file per test unit
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
748 and implement them as you would implement normal functions.
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
749 ```C
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
750 /* myunit.h */
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
751 UCX_TEST(function_name);
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
752 UCX_TEST_SUBROUTINE(subroutine_name, paramlist); /* optional */
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
753
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
754
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
755 /* myunit.c */
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
756 UCX_TEST_SUBROUTINE(subroutine_name, paramlist) {
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
757 /* ... reusable tests with UCX_TEST_ASSERT() ... */
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
758 }
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
759
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
760 UCX_TEST(function_name) {
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
761 /* ... resource allocation and other test preparation ... */
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
762
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
763 /* mandatory marker for the start of the tests */
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
764 UCX_TEST_BEGIN
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
765
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
766 /* ... verifications with UCX_TEST_ASSERT() ...
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
767 * (and/or calls with UCX_TEST_CALL_SUBROUTINE())
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
768 */
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
769
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
770 /* mandatory marker for the end of the tests */
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
771 UCX_TEST_END
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
772
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
773 /* ... resource cleanup ...
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
774 * (all code after UCX_TEST_END is always executed)
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
775 */
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
776 }
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
777 ```
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
778 If you want to use the `UCX_TEST_ASSERT()` macro in a function, you are
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
779 *required* to use a `UCX_TEST_SUBROUTINE`.
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
780 Otherwise the testing framework does not know where to jump, when the assertion
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
781 fails.
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
782
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
783 After implementing the tests, you can easily build a test suite and execute it:
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
784 ```C
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
785 UcxTestSuite* suite = ucx_test_suite_new();
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
786 ucx_test_register(suite, testMyTestCase01);
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
787 ucx_test_register(suite, testMyTestCase02);
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
788 /* ... */
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
789 ucx_test_run(suite, stdout); /* stdout, or any other FILE stream */
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
790 ```
ba760f2195c3 documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents: 295
diff changeset
791
259
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
792 ## Utilities
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
793
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
794 *Header file:* [utils.h](api/utils_8h.html)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
795 *Required modules:* [Allocator](#allocator), [String](#string)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
796
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
797 In this module we provide very general utility function for copy and compare
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
798 operations.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
799 We also provide several `printf` variants to conveniently print formatted data
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
800 to streams or strings.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
801
279
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
802 ### A simple copy program
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
803
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
804 The utilities package provides several stream copy functions.
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
805 One of them has a very simple interface and can, for instance, be used to copy
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
806 whole files in a single call.
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
807 This is a minimal working example:
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
808 ```C
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
809 #include <stdio.h>
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
810 #include <ucx/utils.h>
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
811
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
812 int main(int argc, char** argv) {
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
813
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
814 if (argc != 3) {
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
815 fprintf(stderr, "Use %s <src> <dest>", argv[0]);
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
816 return 1;
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
817 }
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
818
294
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
819 FILE *srcf = fopen(argv[1], "r"); /* insert error handling on your own */
279
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
820 FILE *destf = fopen(argv[2], "w");
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
821
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
822 size_t n = ucx_stream_copy(srcf, destf, fread, fwrite);
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
823 printf("%zu bytes copied.\n", n);
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
824
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
825 fclose(srcf);
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
826 fclose(destf);
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
827
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
828
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
829 return 0;
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
830 }
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
831 ```
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
832
281
e8146a561e73 doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents: 280
diff changeset
833 ### Automatic allocation for formatted strings
279
ee37b179e597 doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents: 277
diff changeset
834
281
e8146a561e73 doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents: 280
diff changeset
835 The UCX utility function `ucx_asprintf()` and it's convenient shortcut
e8146a561e73 doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents: 280
diff changeset
836 `ucx_sprintf` allow easy formatting of strings, without ever having to worry
e8146a561e73 doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents: 280
diff changeset
837 about the required space.
e8146a561e73 doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents: 280
diff changeset
838 ```C
e8146a561e73 doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents: 280
diff changeset
839 sstr_t mystring = ucx_sprintf("The answer is: %d!", 42);
e8146a561e73 doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents: 280
diff changeset
840 ```
e8146a561e73 doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents: 280
diff changeset
841 Still, you have to pass `mystring.ptr` to `free()` (or the free function of
e8146a561e73 doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents: 280
diff changeset
842 your allocator, if you use `ucx_asprintf`).
e8146a561e73 doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents: 280
diff changeset
843 If you don't have all the information ready to build your string, you can even
e8146a561e73 doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents: 280
diff changeset
844 use a [UcxBuffer](#buffer) as a target with the utility function
e8146a561e73 doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents: 280
diff changeset
845 `ucx_bprintf()`.
e8146a561e73 doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents: 280
diff changeset
846 ```C
e8146a561e73 doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents: 280
diff changeset
847 UcxBuffer* strbuffer = ucx_buffer_new(NULL, 512, UCX_BUFFER_AUTOEXTEND);
e8146a561e73 doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents: 280
diff changeset
848
e8146a561e73 doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents: 280
diff changeset
849 for (unsigned int i = 2 ; i < 100 ; i++) {
e8146a561e73 doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents: 280
diff changeset
850 ucx_bprintf(strbuffer, "Integer %d is %s\n",
e8146a561e73 doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents: 280
diff changeset
851 i, prime(i) ? "prime" : "not prime");
e8146a561e73 doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents: 280
diff changeset
852 }
e8146a561e73 doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents: 280
diff changeset
853
294
bfa935ab7f85 example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents: 290
diff changeset
854 /* print the result to stdout */
281
e8146a561e73 doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents: 280
diff changeset
855 printf("%s", (char*)strbuffer->space);
e8146a561e73 doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents: 280
diff changeset
856
e8146a561e73 doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents: 280
diff changeset
857 ucx_buffer_free(strbuffer);
e8146a561e73 doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents: 280
diff changeset
858 ```

mercurial