docs/src/modules-ucx2.md

Sat, 19 Oct 2024 13:21:58 +0200

author
Mike Becker <universe@uap-core.de>
date
Sat, 19 Oct 2024 13:21:58 +0200
changeset 931
be71809e69d1
parent 719
034ec7abb83e
permissions
-rw-r--r--

add test coverage for unlinking tree nodes w/o prev pointer

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

mercurial