docs/src/modules.md

Wed, 16 May 2018 19:27:45 +0200

author
Mike Becker <universe@uap-core.de>
date
Wed, 16 May 2018 19:27:45 +0200
changeset 321
9af21a50b516
parent 314
5d28dc8f0765
child 325
a3e63cb21e20
permissions
-rw-r--r--

adds scstr_t to modules.md + fixes parenthesis bug in sstrsplit_a macro

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

mercurial