Sun, 09 Jul 2023 12:17:29 +0200
Release Version 3.0
264
24f5484bae97
web doc has now proper titles
Mike Becker <universe@uap-core.de>
parents:
259
diff
changeset
|
1 | --- |
390
d345541018fa
starts ucx 3.0 development
Mike Becker <universe@uap-core.de>
parents:
370
diff
changeset
|
2 | title: UCX 2.1 Modules |
264
24f5484bae97
web doc has now proper titles
Mike Becker <universe@uap-core.de>
parents:
259
diff
changeset
|
3 | --- |
259 | 4 | |
390
d345541018fa
starts ucx 3.0 development
Mike Becker <universe@uap-core.de>
parents:
370
diff
changeset
|
5 | UCX 2.1 provided several modules for data structures and algorithms. |
717
aa17be68fc66
fix some typos in UCX 2.1 documentation
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
6 | You may choose to use specific modules by including the corresponding header |
259 | 7 | file. |
390
d345541018fa
starts ucx 3.0 development
Mike Becker <universe@uap-core.de>
parents:
370
diff
changeset
|
8 | Please note, that some modules make use of other UCX 2.1 modules. |
259 | 9 | For instance, the [Allocator](#allocator) module is used by many other modules |
10 | to allow flexible memory allocation. | |
717
aa17be68fc66
fix some typos in UCX 2.1 documentation
Mike Becker <universe@uap-core.de>
parents:
628
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 | 13 | via `#include <ucx/MODULENAME.h>`. |
14 | Required modules are included automatically. | |
15 | ||
719
034ec7abb83e
remove deprecated align=center attribute
Mike Becker <universe@uap-core.de>
parents:
717
diff
changeset
|
16 | <div id="modules"> |
267
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
17 | |
340 | 18 | ----------------------- ---------------------- -------------------------------- --------------------------- |
19 | [String](#string) [Buffer](#buffer) | |
20 | [Allocator](#allocator) [Stack](#stack) [Memory Pool](#memory-pool) | |
21 | [Array](#array) [List](#list) [Map](#map) [AVL Tree](#avl-tree) | |
22 | [Logging](#logging) [Testing](#testing) [Utilities](#utilities) [Properties](#properties) | |
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 | 27 | ## Allocator |
28 | ||
390
d345541018fa
starts ucx 3.0 development
Mike Becker <universe@uap-core.de>
parents:
370
diff
changeset
|
29 | *Header file:* [allocator.h](api-2.1/allocator_8h.html) |
259 | 30 | *Required modules:* None. |
31 | ||
32 | A UCX allocator consists of a pointer to the memory area / pool and four | |
33 | function pointers to memory management functions operating on this memory | |
34 | area / pool. These functions shall behave equivalent to the standard libc | |
35 | functions `malloc`, `calloc`, `realloc` and `free`. | |
36 | ||
37 | The signature of the memory management functions is based on the signature | |
38 | of the respective libc function but each of them takes the pointer to the | |
39 | memory area / pool as first argument. | |
40 | ||
41 | As the pointer to the memory area / pool can be arbitrarily chosen, any data | |
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 | 44 | |
340 | 45 | ## Array |
46 | ||
390
d345541018fa
starts ucx 3.0 development
Mike Becker <universe@uap-core.de>
parents:
370
diff
changeset
|
47 | *Header file:* [array.h](api-2.1/array_8h.html) |
340 | 48 | *Required modules:* [Allocator](#allocator) |
49 | ||
50 | The UCX Array is an implementation of a dynamic array with automatic | |
51 | reallocation. The array structure contains a capacity, the current size, | |
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 | 57 | |
58 | ### Remove duplicates from an array of strings | |
59 | ||
60 | The following example shows, how a `UcxArray` can be built with | |
61 | a standard dynamic C array (pointer+length) as basis. | |
62 | ||
63 | ```C | |
370
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
64 | UcxArray* create_unique(sstr_t* array, size_t arrlen) { |
340 | 65 | // worst case is no duplicates, hence the capacity is set to arrlen |
370
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
66 | UcxArray* result = ucx_array_new(arrlen, sizeof(sstr_t)); |
340 | 67 | // only append elements, if they are not already present in the array |
68 | for (size_t i = 0 ; i < arrlen ; ++i) { | |
69 | if (!ucx_array_contains(result, array+i, ucx_cmp_sstr, NULL)) { | |
370
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
70 | ucx_array_append_from(result, array+i, 1); |
340 | 71 | } |
72 | } | |
73 | // make the array as small as possible | |
370
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
74 | ucx_array_shrink(result); |
340 | 75 | return result; |
76 | } | |
77 | ||
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
78 | // ... |
340 | 79 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
80 | sstr_t* array = // some standard array of strings |
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
81 | size_t arrlen = // the length of the array |
340 | 82 | |
370
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
83 | UcxArray* result = create_unique(array,arrlen); |
340 | 84 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
85 | // Iterate over the array and print the elements |
370
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
86 | sstr_t* unique = result->data; |
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
87 | for (size_t i = 0 ; i < result->size ; i++) { |
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
88 | printf("%" PRIsstr "\n", SFMT(unique[i])); |
340 | 89 | } |
90 | ||
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
91 | // Free the array. |
370
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
92 | ucx_array_free(result); |
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
93 | ``` |
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
94 | ### Preventing out of bounds writes |
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
95 | |
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
96 | The functions `ucx_array_reserve()`, `ucx_array_resize()`, `ucx_array_grow()`, |
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
97 | and `ucx_array_shrink()` allow easy management of the array capacity. |
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
98 | Imagine you want to add `n` elements to an array. If your `n` elements are |
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
99 | already somewhere else consecutively in memory, you can use |
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
100 | `ucx_array_append_from()` and benefit from the autogrow facility in this family |
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
101 | of functions. Otherwise, you can ask the array to have enough capacity for |
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
102 | holding additional `n` elements. |
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
103 | |
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
104 | ```C |
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
105 | size_t n = // ... elements to add |
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
106 | if (ucx_array_grow(array, n)) { |
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
107 | fprintf(stderr, "Cannot add %zu elements to the array.\n", n); |
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
108 | return 1; |
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
109 | } |
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
110 | for (size_t i = 0 ; i < n ; i++) { |
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
111 | ((int*)array->data)[array->size++] = 80; |
07ac32b385e4
updates the web doc for array
Mike Becker <universe@uap-core.de>
parents:
359
diff
changeset
|
112 | } |
340 | 113 | ``` |
114 | ||
259 | 115 | ## AVL Tree |
116 | ||
390
d345541018fa
starts ucx 3.0 development
Mike Becker <universe@uap-core.de>
parents:
370
diff
changeset
|
117 | *Header file:* [avl.h](api-2.1/avl_8h.html) |
259 | 118 | *Required modules:* [Allocator](#allocator) |
119 | ||
120 | This binary search tree implementation allows average O(1) insertion and | |
121 | removal of elements (excluding binary search time). | |
122 | All common binary tree operations are implemented. Furthermore, this module | |
123 | provides search functions via lower and upper bounds. | |
124 | ||
287
98da78a1e69a
adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents:
282
diff
changeset
|
125 | ### 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
|
126 | |
98da78a1e69a
adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents:
282
diff
changeset
|
127 | 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
|
128 | 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
|
129 | 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
|
130 | ```C |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
131 | // Somewhere in a header |
287
98da78a1e69a
adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents:
282
diff
changeset
|
132 | typedef struct { |
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; |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
134 | // 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
|
135 | } MyObject; |
98da78a1e69a
adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents:
282
diff
changeset
|
136 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
137 | // Source code |
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
|
138 | UcxAVLTree* tree = ucx_avl_new(ucx_cmp_longint); |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
139 | // ... 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
|
140 | |
98da78a1e69a
adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents:
282
diff
changeset
|
141 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
142 | // 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
|
143 | 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
|
144 | 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
|
145 | |
98da78a1e69a
adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents:
282
diff
changeset
|
146 | 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
|
147 | for ( |
98da78a1e69a
adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents:
282
diff
changeset
|
148 | 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
|
149 | 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
|
150 | 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
|
151 | 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
|
152 | 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
|
153 | ) { |
98da78a1e69a
adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents:
282
diff
changeset
|
154 | 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
|
155 | } |
98da78a1e69a
adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents:
282
diff
changeset
|
156 | |
98da78a1e69a
adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents:
282
diff
changeset
|
157 | 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
|
158 | 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
|
159 | ``` |
98da78a1e69a
adds ucx_avl_free_content() function and documentation in modules.md
Mike Becker <universe@uap-core.de>
parents:
282
diff
changeset
|
160 | |
259 | 161 | ## Buffer |
162 | ||
390
d345541018fa
starts ucx 3.0 development
Mike Becker <universe@uap-core.de>
parents:
370
diff
changeset
|
163 | *Header file:* [buffer.h](api-2.1/buffer_8h.html) |
259 | 164 | *Required modules:* None. |
165 | ||
166 | Instances of this buffer implementation can be used to read from or to write to | |
167 | 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
|
168 | `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
|
169 | from one buffer to another or from file or network streams to the buffer and |
259 | 170 | vice-versa. |
171 | ||
172 | More features for convenient use of the buffer can be enabled, like automatic | |
173 | memory management and automatic resizing of the buffer space. | |
174 | See the documentation of the macro constants in the header file for more | |
175 | information. | |
176 | ||
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
|
177 | ### 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
|
178 | |
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 | 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
|
180 | 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
|
181 | 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
|
182 | 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
|
183 | 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
|
184 | 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
|
185 | 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
|
186 | 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
|
187 | 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
|
188 | ```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
|
189 | #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
|
190 | #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
|
191 | #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
|
192 | |
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 | 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
|
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 | 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
|
196 | 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
|
197 | 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
|
198 | } |
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 | |
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
|
200 | 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
|
201 | 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
|
202 | 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
|
203 | 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
|
204 | } |
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 | |
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
|
206 | 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
|
207 | |
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 | 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
|
209 | ucx_buffer_new( |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
210 | NULL, // the buffer should manage the memory area for us |
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
211 | 2*chunksize, // initial size should be twice the chunk size |
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
212 | 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
|
213 | |
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 | 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
|
215 | do { |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
216 | // 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
|
217 | 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
|
218 | 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
|
219 | 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
|
220 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
221 | // 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
|
222 | 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
|
223 | 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
|
224 | 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
|
225 | 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
|
226 | |
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 | 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
|
228 | 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
|
229 | |
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 | 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
|
231 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
232 | // 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
|
233 | 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
|
234 | } 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
|
235 | |
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 | } 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
|
237 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
238 | // 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
|
239 | 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
|
240 | 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
|
241 | 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
|
242 | } |
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
|
243 | |
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
|
244 | 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
|
245 | 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
|
246 | |
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
|
247 | 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
|
248 | } |
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
|
249 | ``` |
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
|
250 | |
259 | 251 | ## List |
252 | ||
390
d345541018fa
starts ucx 3.0 development
Mike Becker <universe@uap-core.de>
parents:
370
diff
changeset
|
253 | *Header file:* [list.h](api-2.1/list_8h.html) |
259 | 254 | *Required modules:* [Allocator](#allocator) |
255 | ||
256 | This module provides the data structure and several functions for a doubly | |
257 | linked list. Among the common operations like insert, remove, search and sort, | |
258 | we allow convenient iteration via a special `UCX_FOREACH` macro. | |
259 | ||
294
bfa935ab7f85
example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents:
290
diff
changeset
|
260 | ### 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
|
261 | |
bfa935ab7f85
example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents:
290
diff
changeset
|
262 | 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
|
263 | strings without duplicates. |
340 | 264 | This is a similar example to the one [above](#array), but here we are |
265 | using a `UcxList`. | |
294
bfa935ab7f85
example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents:
290
diff
changeset
|
266 | ```C |
bfa935ab7f85
example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents:
290
diff
changeset
|
267 | #include <stdio.h> |
bfa935ab7f85
example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents:
290
diff
changeset
|
268 | #include <ucx/list.h> |
bfa935ab7f85
example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents:
290
diff
changeset
|
269 | #include <ucx/string.h> |
bfa935ab7f85
example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents:
290
diff
changeset
|
270 | #include <ucx/utils.h> |
bfa935ab7f85
example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents:
290
diff
changeset
|
271 | |
bfa935ab7f85
example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents:
290
diff
changeset
|
272 | 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
|
273 | UcxList* list = NULL; |
bfa935ab7f85
example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents:
290
diff
changeset
|
274 | 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
|
275 | 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
|
276 | 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
|
277 | *s = sstrdup(array[i]); |
bfa935ab7f85
example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents:
290
diff
changeset
|
278 | 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
|
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 | return list; |
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 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
284 | // we will need this function to clean up the list contents later |
294
bfa935ab7f85
example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents:
290
diff
changeset
|
285 | void free_sstr(void* ptr) { |
bfa935ab7f85
example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents:
290
diff
changeset
|
286 | sstr_t* s = ptr; |
bfa935ab7f85
example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents:
290
diff
changeset
|
287 | free(s->ptr); |
bfa935ab7f85
example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents:
290
diff
changeset
|
288 | free(s); |
bfa935ab7f85
example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents:
290
diff
changeset
|
289 | } |
bfa935ab7f85
example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents:
290
diff
changeset
|
290 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
291 | // ... |
294
bfa935ab7f85
example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents:
290
diff
changeset
|
292 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
293 | sstr_t* array = // some array of strings |
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
294 | size_t arrlen = // the length of the array |
294
bfa935ab7f85
example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents:
290
diff
changeset
|
295 | |
bfa935ab7f85
example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents:
290
diff
changeset
|
296 | 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
|
297 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
298 | // Iterate over the list and print the elements |
294
bfa935ab7f85
example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents:
290
diff
changeset
|
299 | UCX_FOREACH(elem, list) { |
bfa935ab7f85
example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents:
290
diff
changeset
|
300 | 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
|
301 | printf("%" PRIsstr "\n", SFMT(s)); |
bfa935ab7f85
example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents:
290
diff
changeset
|
302 | } |
bfa935ab7f85
example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents:
290
diff
changeset
|
303 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
304 | // Use our free function to free the duplicated strings. |
294
bfa935ab7f85
example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents:
290
diff
changeset
|
305 | 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
|
306 | ucx_list_free(list); |
bfa935ab7f85
example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents:
290
diff
changeset
|
307 | ``` |
bfa935ab7f85
example code for the usage of a UcxList
Mike Becker <universe@uap-core.de>
parents:
290
diff
changeset
|
308 | |
259 | 309 | ## Logging |
310 | ||
390
d345541018fa
starts ucx 3.0 development
Mike Becker <universe@uap-core.de>
parents:
370
diff
changeset
|
311 | *Header file:* [logging.h](api-2.1/logging_8h.html) |
259 | 312 | *Required modules:* [Map](#map), [String](#string) |
313 | ||
314 | The logging module comes with some predefined log levels and allows some more | |
315 | customization. You may choose if you want to get timestamps or source file and | |
316 | 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
|
317 | 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
|
318 | information: |
7fc65395188e
documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents:
294
diff
changeset
|
319 | ```C |
7fc65395188e
documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents:
294
diff
changeset
|
320 | log = ucx_logger_new(stdout, UCX_LOGGER_DEBUG, |
7fc65395188e
documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents:
294
diff
changeset
|
321 | 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
|
322 | ``` |
7fc65395188e
documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents:
294
diff
changeset
|
323 | 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
|
324 | ```C |
7fc65395188e
documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents:
294
diff
changeset
|
325 | ucx_logger_trace(log, "Verbose output"); |
7fc65395188e
documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents:
294
diff
changeset
|
326 | ucx_logger_debug(log, "Debug message"); |
7fc65395188e
documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents:
294
diff
changeset
|
327 | ucx_logger_info(log, "Information"); |
7fc65395188e
documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents:
294
diff
changeset
|
328 | ucx_logger_warn(log, "Warning"); |
7fc65395188e
documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents:
294
diff
changeset
|
329 | ucx_logger_error(log, "Error message"); |
7fc65395188e
documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents:
294
diff
changeset
|
330 | ``` |
7fc65395188e
documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents:
294
diff
changeset
|
331 | or you use |
7fc65395188e
documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents:
294
diff
changeset
|
332 | ```C |
7fc65395188e
documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents:
294
diff
changeset
|
333 | ucx_logger_log(log, CUSTOM_LEVEL, "Some message") |
7fc65395188e
documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents:
294
diff
changeset
|
334 | ``` |
7fc65395188e
documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents:
294
diff
changeset
|
335 | 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
|
336 | ```C |
7fc65395188e
documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents:
294
diff
changeset
|
337 | ucx_logger_register_level(log, CUSTOM_LEVEL, "CUSTOM") |
7fc65395188e
documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents:
294
diff
changeset
|
338 | ``` |
7fc65395188e
documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents:
294
diff
changeset
|
339 | where the last argument must be a string literal. |
259 | 340 | |
341 | ## Map | |
342 | ||
390
d345541018fa
starts ucx 3.0 development
Mike Becker <universe@uap-core.de>
parents:
370
diff
changeset
|
343 | *Header file:* [map.h](api-2.1/map_8h.html) |
259 | 344 | *Required modules:* [Allocator](#allocator), [String](#string) |
345 | ||
346 | This module provides a hash map implementation using murmur hash 2 and separate | |
347 | chaining with linked lists. Similarly to the list module, we provide a | |
348 | `UCX_MAP_FOREACH` macro to conveniently iterate through the key/value pairs. | |
349 | ||
298
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
350 | ### Parsing command line options |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
351 | |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
352 | 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
|
353 | 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
|
354 | ```C |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
355 | UcxMap* options = ucx_map_new(16); |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
356 | const char *NOARG = ""; |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
357 | |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
358 | char *option = NULL; |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
359 | char optchar = 0; |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
360 | for(int i=1;i<argc;i++) { |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
361 | char *arg = argv[i]; |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
362 | size_t len = strlen(arg); |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
363 | if(len > 1 && arg[0] == '-') { |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
364 | for(int c=1;c<len;c++) { |
299
e7dfcf229625
adjusts code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
298
diff
changeset
|
365 | if(option) { |
e7dfcf229625
adjusts code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
298
diff
changeset
|
366 | fprintf(stderr, |
e7dfcf229625
adjusts code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
298
diff
changeset
|
367 | "Missing argument for option -%c\n", optchar); |
e7dfcf229625
adjusts code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
298
diff
changeset
|
368 | return 1; |
e7dfcf229625
adjusts code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
298
diff
changeset
|
369 | } |
298
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
370 | switch(arg[c]) { |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
371 | default: { |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
372 | 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
|
373 | return 1; |
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 | case 'v': { |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
376 | ucx_map_cstr_put(options, "verbose", NOARG); |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
377 | break; |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
378 | } |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
379 | case 'o': { |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
380 | option = "output"; |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
381 | optchar = 'o'; |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
382 | break; |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
383 | } |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
384 | } |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
385 | } |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
386 | } else if(option) { |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
387 | ucx_map_cstr_put(options, option, arg); |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
388 | option = NULL; |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
389 | } else { |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
390 | // ... handle argument that is not an option ... |
298
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
391 | } |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
392 | } |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
393 | if(option) { |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
394 | fprintf(stderr, |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
395 | "Missing argument for option -%c\n", optchar); |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
396 | return 1; |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
397 | } |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
398 | ``` |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
399 | 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
|
400 | ```C |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
401 | UcxMapIterator iter = ucx_map_iterator(options); |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
402 | char *arg; |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
403 | UCX_MAP_FOREACH(optkey, arg, iter) { |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
404 | char* opt = optkey.data; |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
405 | if (*arg) { |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
406 | printf("%s = %s\n", opt, arg); |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
407 | } else { |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
408 | printf("%s active\n", opt); |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
409 | } |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
410 | } |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
411 | ``` |
fffe3a16a3de
adds a code sample for UcxMap
Mike Becker <universe@uap-core.de>
parents:
297
diff
changeset
|
412 | 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
|
413 | |
259 | 414 | ## Memory Pool |
415 | ||
390
d345541018fa
starts ucx 3.0 development
Mike Becker <universe@uap-core.de>
parents:
370
diff
changeset
|
416 | *Header file:* [mempool.h](api-2.1/mempool_8h.html) |
259 | 417 | *Required modules:* [Allocator](#allocator) |
418 | ||
419 | Here we have a concrete allocator implementation in the sense of a memory pool. | |
420 | This pool allows you to register destructor functions for the allocated memory, | |
421 | which are automatically called on the destruction of the pool. | |
422 | 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
|
423 | case some external library allocated memory for you, which should be |
259 | 424 | destroyed together with this pool. |
425 | ||
302
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
426 | 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
|
427 | 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
|
428 | 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
|
429 | string. |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
430 | 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
|
431 | 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
|
432 | `ucx_mempool_destroy()`. |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
433 | |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
434 | ### Read CSV data into a structure |
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 | 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
|
437 | 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
|
438 | ```C |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
439 | #include <stdio.h> |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
440 | #include <ucx/mempool.h> |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
441 | #include <ucx/list.h> |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
442 | #include <ucx/string.h> |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
443 | #include <ucx/buffer.h> |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
444 | #include <ucx/utils.h> |
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 | typedef struct { |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
447 | sstr_t column_a; |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
448 | sstr_t column_b; |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
449 | sstr_t column_c; |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
450 | } CSVData; |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
451 | |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
452 | int main(int argc, char** argv) { |
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 | UcxMempool* pool = ucx_mempool_new(128); |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
455 | |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
456 | FILE *f = fopen("test.csv", "r"); |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
457 | if (!f) { |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
458 | perror("Cannot open file"); |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
459 | return 1; |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
460 | } |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
461 | // close the file automatically at pool destruction |
302
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
462 | 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
|
463 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
464 | // create a buffer and register it at the memory pool for destruction |
302
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
465 | 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
|
466 | 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
|
467 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
468 | // read the file and split it by lines first |
302
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
469 | 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
|
470 | 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
|
471 | ssize_t lc = 0; |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
472 | 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
|
473 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
474 | // skip the header and parse the remaining data |
302
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
475 | UcxList* datalist = NULL; |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
476 | 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
|
477 | if (lines[i].length == 0) continue; |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
478 | ssize_t fc = 3; |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
479 | 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
|
480 | if (fc != 3) { |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
481 | 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
|
482 | ucx_mempool_destroy(pool); |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
483 | return 1; |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
484 | } |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
485 | 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
|
486 | data->column_a = fields[0]; |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
487 | data->column_b = fields[1]; |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
488 | data->column_c = fields[2]; |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
489 | 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
|
490 | } |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
491 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
492 | // control output |
302
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
493 | UCX_FOREACH(elem, datalist) { |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
494 | CSVData* data = elem->data; |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
495 | printf("Column A: %" PRIsstr " | " |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
496 | "Column B: %" PRIsstr " | " |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
497 | "Column C: %" PRIsstr "\n", |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
498 | 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
|
499 | ); |
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 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
502 | // cleanup everything, no manual free() needed |
302
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
503 | ucx_mempool_destroy(pool); |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
504 | |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
505 | return 0; |
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 | ``` |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
508 | |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
509 | ### Overriding the default destructor |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
510 | |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
511 | 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
|
512 | 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
|
513 | 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
|
514 | ```C |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
515 | 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
|
516 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
517 | // some special initialization with own resource management |
302
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
518 | my_object_init(obj); |
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
519 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
520 | // register destructor function |
302
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
521 | 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
|
522 | ``` |
304
1f9237cfeb26
fixes typo in modules.md
Mike Becker <universe@uap-core.de>
parents:
302
diff
changeset
|
523 | 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
|
524 | also managed by the pool. |
717
aa17be68fc66
fix some typos in UCX 2.1 documentation
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
525 | 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
|
526 | More precisely, a destructor function set with `ucx_mempool_set_destr()` MUST |
717
aa17be68fc66
fix some typos in UCX 2.1 documentation
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
527 | NOT call `free()` on the specified pointer whereas a destructor function |
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
|
528 | 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
|
529 | `free()`. |
302
8628147734d6
comprehensive code example for the memory pool
Mike Becker <universe@uap-core.de>
parents:
301
diff
changeset
|
530 | |
259 | 531 | ## Properties |
532 | ||
390
d345541018fa
starts ucx 3.0 development
Mike Becker <universe@uap-core.de>
parents:
370
diff
changeset
|
533 | *Header file:* [properties.h](api-2.1/properties_8h.html) |
259 | 534 | *Required modules:* [Map](#map) |
535 | ||
536 | This module provides load and store function for `*.properties` files. | |
537 | The key/value pairs are stored within an UCX Map. | |
538 | ||
277
f819fe5e20f5
makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents:
267
diff
changeset
|
539 | ### 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
|
540 | |
f819fe5e20f5
makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents:
267
diff
changeset
|
541 | ```C |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
542 | // 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
|
543 | 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
|
544 | if (!file) { |
f819fe5e20f5
makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents:
267
diff
changeset
|
545 | // error handling |
f819fe5e20f5
makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents:
267
diff
changeset
|
546 | return 1; |
f819fe5e20f5
makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents:
267
diff
changeset
|
547 | } |
f819fe5e20f5
makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents:
267
diff
changeset
|
548 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
549 | // 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
|
550 | 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
|
551 | if (ucx_properties_load(myprops, file)) { |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
552 | // ... 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
|
553 | fclose(file); |
f819fe5e20f5
makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents:
267
diff
changeset
|
554 | 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
|
555 | return 1; |
f819fe5e20f5
makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents:
267
diff
changeset
|
556 | } |
f819fe5e20f5
makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents:
267
diff
changeset
|
557 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
558 | // 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
|
559 | char* propval; |
f819fe5e20f5
makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents:
267
diff
changeset
|
560 | 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
|
561 | 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
|
562 | 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
|
563 | } |
f819fe5e20f5
makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents:
267
diff
changeset
|
564 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
565 | // 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
|
566 | 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
|
567 | 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
|
568 | fclose(file); |
f819fe5e20f5
makes destructor functions for *_free_content() optional + more documentation for UcxProperties
Mike Becker <universe@uap-core.de>
parents:
267
diff
changeset
|
569 | ``` |
295
7fc65395188e
documents (and fixes!) the UcxLogger
Mike Becker <universe@uap-core.de>
parents:
294
diff
changeset
|
570 | |
259 | 571 | ## Stack |
572 | ||
390
d345541018fa
starts ucx 3.0 development
Mike Becker <universe@uap-core.de>
parents:
370
diff
changeset
|
573 | *Header file:* [stack.h](api-2.1/stack_8h.html) |
259 | 574 | *Required modules:* [Allocator](#allocator) |
575 | ||
576 | This concrete implementation of an UCX Allocator allows you to grab some amount | |
577 | of memory which is then handled as a stack. | |
578 | 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
|
579 | allocator. You may still choose to use either stack or heap memory |
259 | 580 | for the underlying space. |
581 | A typical use case is an algorithm where you need to allocate and free large | |
582 | amounts of memory very frequently. | |
583 | ||
301
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
584 | 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
|
585 | simple data. |
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
586 | ```C |
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
587 | const size_t len = 1024; |
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
588 | char space[len]; |
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
589 | UcxStack stack; |
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
590 | ucx_stack_init(&stack, space, len); |
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
591 | |
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
592 | int i = 42; |
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
593 | float f = 3.14f; |
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
594 | const char* str = "Hello!"; |
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
595 | size_t strn = 7; |
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
596 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
597 | // push the integer |
301
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
598 | ucx_stack_push(&stack, sizeof(int), &i); |
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
599 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
600 | // push the float and rember the address |
301
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
601 | float* remember = ucx_stack_push(&stack, sizeof(float), &f); |
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
602 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
603 | // push the string with zero terminator |
301
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
604 | ucx_stack_push(&stack, strn, str); |
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
605 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
606 | // if we forget, how big an element was, we can ask the stack |
301
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
607 | 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
|
608 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
609 | // retrieve the string as sstr_t, without zero terminator! |
301
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
610 | sstr_t s; |
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
611 | s.length = ucx_stack_topsize(&stack)-1; |
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
612 | s.ptr = malloc(s.length); |
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
613 | ucx_stack_popn(&stack, s.ptr, s.length); |
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
614 | printf("%" PRIsstr "\n", SFMT(s)); |
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
615 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
616 | // print the float directly from the stack and free it |
301
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
617 | printf("Float: %f\n", *remember); |
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
618 | ucx_stack_free(&stack, remember); |
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
619 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
620 | // the last element is the integer |
301
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
621 | int j; |
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
622 | ucx_stack_pop(&stack, &j); |
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
623 | printf("Integer: %d\n", j); |
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
624 | ``` |
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
625 | |
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
626 | |
0f83916c1639
documentation for the UcxStack
Mike Becker <universe@uap-core.de>
parents:
299
diff
changeset
|
627 | |
259 | 628 | ## String |
629 | ||
390
d345541018fa
starts ucx 3.0 development
Mike Becker <universe@uap-core.de>
parents:
370
diff
changeset
|
630 | *Header file:* [string.h](api-2.1/string_8h.html) |
259 | 631 | *Required modules:* [Allocator](#allocator) |
632 | ||
633 | This module provides a safe implementation of bounded string. | |
634 | Usually C strings do not carry a length. While for zero-terminated strings you | |
635 | can easily get the length with `strlen`, this is not generally possible for | |
636 | arbitrary strings. | |
637 | The `sstr_t` type of this module always carries the string and its length to | |
638 | reduce the risk of buffer overflows dramatically. | |
639 | ||
267
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
640 | ### Initialization |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
641 | |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
642 | 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
|
643 | |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
644 | ```C |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
645 | // (1) sstr() uses strlen() internally, hence cstr MUST be zero-terminated |
267
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
646 | sstr_t a = sstr(cstr); |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
647 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
648 | // (2) cstr does not need to be zero-terminated, if length is specified |
267
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
649 | 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
|
650 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
651 | // (3) S() macro creates sstr_t from a string using sizeof() and using sstrn(). |
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
652 | // This version is especially useful for function arguments |
267
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
653 | sstr_t c = S("hello"); |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
654 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
655 | // (4) SC() macro works like S(), but makes the string immutable using scstr_t. |
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
656 | // (available since UCX 2.0) |
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
|
657 | 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
|
658 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
659 | // (5) ST() macro creates sstr_t struct literal using sizeof() |
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
|
660 | 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
|
661 | ``` |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
662 | |
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
|
663 | 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
|
664 | 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
|
665 | 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
|
666 | 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
|
667 | |
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
|
668 | ### 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
|
669 | |
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 | *(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
|
671 | |
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 | 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
|
673 | 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
|
674 | 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
|
675 | 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
|
676 | 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
|
677 | |
9af21a50b516
adds scstr_t to modules.md + fixes parenthesis bug in sstrsplit_a macro
Mike Becker <universe@uap-core.de>
parents:
314
diff
changeset
|
678 | 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
|
679 | 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
|
680 | 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
|
681 | 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
|
682 | 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
|
683 | accept `scstr_t` as input argument, because the return type would break the |
717
aa17be68fc66
fix some typos in UCX 2.1 documentation
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
684 | const-ness. |
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
|
685 | |
9af21a50b516
adds scstr_t to modules.md + fixes parenthesis bug in sstrsplit_a macro
Mike Becker <universe@uap-core.de>
parents:
314
diff
changeset
|
686 | |
267
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
687 | ### 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
|
688 | |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
689 | 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
|
690 | 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
|
691 | subtraction. |
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 | ```C |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
694 | 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
|
695 | sstr_t needle = ST("we"); |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
696 | 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
|
697 | if (result.ptr) |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
698 | 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
|
699 | else |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
700 | printf("Not found.\n"); |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
701 | ``` |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
702 | |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
703 | ### 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
|
704 | |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
705 | 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
|
706 | 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
|
707 | 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
|
708 | pool. |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
709 | |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
710 | ```C |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
711 | 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
|
712 | sstr_t delim = ST("::"); |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
713 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
714 | ssize_t count = 0; // no limit |
267
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
715 | 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
|
716 | |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
717 | 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
|
718 | for (ssize_t i = 0 ; i < count ; i++) { |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
719 | // don't forget to specify the length via the %*s format specifier |
267
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
720 | 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
|
721 | } |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
722 | |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
723 | ucx_mempool_destroy(pool); |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
724 | ``` |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
725 | The output is: |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
726 | |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
727 | here |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
728 | are |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
729 | some |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
730 | strings |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
731 | |
f4789572c9d6
restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents:
264
diff
changeset
|
732 | 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
|
733 | |
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
|
734 | ### 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
|
735 | |
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 | 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
|
737 | `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
|
738 | `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
|
739 | 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
|
740 | `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
|
741 | |
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
|
742 | 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
|
743 | 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
|
744 | 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
|
745 | 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
|
746 | |
259 | 747 | ## Testing |
748 | ||
390
d345541018fa
starts ucx 3.0 development
Mike Becker <universe@uap-core.de>
parents:
370
diff
changeset
|
749 | *Header file:* [test.h](api-2.1/test_8h.html) |
259 | 750 | *Required modules:* None. |
751 | ||
752 | This module provides a testing framework which allows you to execute test cases | |
753 | within test suites. | |
754 | To avoid code duplication within tests, we also provide the possibility to | |
755 | define test subroutines. | |
756 | ||
297
ba760f2195c3
documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents:
295
diff
changeset
|
757 | 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
|
758 | 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
|
759 | ```C |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
760 | // myunit.h |
297
ba760f2195c3
documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents:
295
diff
changeset
|
761 | UCX_TEST(function_name); |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
762 | UCX_TEST_SUBROUTINE(subroutine_name, paramlist); // optional |
297
ba760f2195c3
documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents:
295
diff
changeset
|
763 | |
ba760f2195c3
documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents:
295
diff
changeset
|
764 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
765 | // myunit.c |
297
ba760f2195c3
documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents:
295
diff
changeset
|
766 | UCX_TEST_SUBROUTINE(subroutine_name, paramlist) { |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
767 | // ... reusable tests with UCX_TEST_ASSERT() ... |
297
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 | UCX_TEST(function_name) { |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
771 | // ... resource allocation and other test preparation ... |
297
ba760f2195c3
documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents:
295
diff
changeset
|
772 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
773 | // mandatory marker for the start of the tests |
297
ba760f2195c3
documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents:
295
diff
changeset
|
774 | UCX_TEST_BEGIN |
ba760f2195c3
documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents:
295
diff
changeset
|
775 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
776 | // ... verifications with UCX_TEST_ASSERT() ... |
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
777 | // (and/or calls with UCX_TEST_CALL_SUBROUTINE()) |
297
ba760f2195c3
documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents:
295
diff
changeset
|
778 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
779 | // mandatory marker for the end of the tests |
297
ba760f2195c3
documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents:
295
diff
changeset
|
780 | UCX_TEST_END |
ba760f2195c3
documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents:
295
diff
changeset
|
781 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
782 | // ... resource cleanup ... |
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
783 | // (all code after UCX_TEST_END is always executed) |
297
ba760f2195c3
documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents:
295
diff
changeset
|
784 | } |
ba760f2195c3
documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents:
295
diff
changeset
|
785 | ``` |
ba760f2195c3
documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents:
295
diff
changeset
|
786 | 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
|
787 | *required* to use a `UCX_TEST_SUBROUTINE`. |
717
aa17be68fc66
fix some typos in UCX 2.1 documentation
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
788 | Otherwise, the testing framework does not know where to jump, when the assertion |
297
ba760f2195c3
documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents:
295
diff
changeset
|
789 | fails. |
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 | 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
|
792 | ```C |
ba760f2195c3
documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents:
295
diff
changeset
|
793 | UcxTestSuite* suite = ucx_test_suite_new(); |
ba760f2195c3
documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents:
295
diff
changeset
|
794 | ucx_test_register(suite, testMyTestCase01); |
ba760f2195c3
documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents:
295
diff
changeset
|
795 | ucx_test_register(suite, testMyTestCase02); |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
796 | // ... |
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
797 | ucx_test_run(suite, stdout); // stdout, or any other FILE stream |
297
ba760f2195c3
documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents:
295
diff
changeset
|
798 | ``` |
ba760f2195c3
documentation for the testing framework
Mike Becker <universe@uap-core.de>
parents:
295
diff
changeset
|
799 | |
259 | 800 | ## Utilities |
801 | ||
390
d345541018fa
starts ucx 3.0 development
Mike Becker <universe@uap-core.de>
parents:
370
diff
changeset
|
802 | *Header file:* [utils.h](api-2.1/utils_8h.html) |
259 | 803 | *Required modules:* [Allocator](#allocator), [String](#string) |
804 | ||
805 | In this module we provide very general utility function for copy and compare | |
806 | operations. | |
807 | We also provide several `printf` variants to conveniently print formatted data | |
808 | to streams or strings. | |
809 | ||
279
ee37b179e597
doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents:
277
diff
changeset
|
810 | ### A simple copy program |
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 | 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
|
813 | 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
|
814 | whole files in a single call. |
ee37b179e597
doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents:
277
diff
changeset
|
815 | This is a minimal working example: |
ee37b179e597
doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents:
277
diff
changeset
|
816 | ```C |
ee37b179e597
doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents:
277
diff
changeset
|
817 | #include <stdio.h> |
ee37b179e597
doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents:
277
diff
changeset
|
818 | #include <ucx/utils.h> |
ee37b179e597
doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents:
277
diff
changeset
|
819 | |
ee37b179e597
doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents:
277
diff
changeset
|
820 | int main(int argc, char** argv) { |
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 | if (argc != 3) { |
ee37b179e597
doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents:
277
diff
changeset
|
823 | 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
|
824 | return 1; |
ee37b179e597
doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents:
277
diff
changeset
|
825 | } |
ee37b179e597
doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents:
277
diff
changeset
|
826 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
827 | 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
|
828 | FILE *destf = fopen(argv[2], "w"); |
ee37b179e597
doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents:
277
diff
changeset
|
829 | |
ee37b179e597
doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents:
277
diff
changeset
|
830 | 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
|
831 | printf("%zu bytes copied.\n", n); |
ee37b179e597
doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents:
277
diff
changeset
|
832 | |
ee37b179e597
doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents:
277
diff
changeset
|
833 | fclose(srcf); |
ee37b179e597
doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents:
277
diff
changeset
|
834 | fclose(destf); |
ee37b179e597
doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents:
277
diff
changeset
|
835 | |
ee37b179e597
doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents:
277
diff
changeset
|
836 | |
ee37b179e597
doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents:
277
diff
changeset
|
837 | return 0; |
ee37b179e597
doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents:
277
diff
changeset
|
838 | } |
ee37b179e597
doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents:
277
diff
changeset
|
839 | ``` |
ee37b179e597
doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents:
277
diff
changeset
|
840 | |
281
e8146a561e73
doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents:
280
diff
changeset
|
841 | ### Automatic allocation for formatted strings |
279
ee37b179e597
doc: MWE for ucx_stream_copy()
Mike Becker <universe@uap-core.de>
parents:
277
diff
changeset
|
842 | |
281
e8146a561e73
doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents:
280
diff
changeset
|
843 | 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
|
844 | `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
|
845 | 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
|
846 | ```C |
e8146a561e73
doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents:
280
diff
changeset
|
847 | 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
|
848 | ``` |
e8146a561e73
doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents:
280
diff
changeset
|
849 | 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
|
850 | 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
|
851 | 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
|
852 | 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
|
853 | `ucx_bprintf()`. |
e8146a561e73
doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents:
280
diff
changeset
|
854 | ```C |
e8146a561e73
doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents:
280
diff
changeset
|
855 | 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
|
856 | |
e8146a561e73
doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents:
280
diff
changeset
|
857 | 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
|
858 | 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
|
859 | 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
|
860 | } |
e8146a561e73
doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents:
280
diff
changeset
|
861 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
390
diff
changeset
|
862 | // 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
|
863 | 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
|
864 | |
e8146a561e73
doc: adds ucx_sprintf() and ucx_bprintf() samples + fixes leftmenu
Mike Becker <universe@uap-core.de>
parents:
280
diff
changeset
|
865 | 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
|
866 | ``` |