docs/src/modules.md

Mon, 20 Nov 2017 18:06:32 +0100

author
Mike Becker <universe@uap-core.de>
date
Mon, 20 Nov 2017 18:06:32 +0100
changeset 268
00e88487a654
parent 267
f4789572c9d6
child 277
f819fe5e20f5
permissions
-rw-r--r--

removes man dir from clean target of doc makefile

264
24f5484bae97 web doc has now proper titles
Mike Becker <universe@uap-core.de>
parents: 259
diff changeset
1 ---
24f5484bae97 web doc has now proper titles
Mike Becker <universe@uap-core.de>
parents: 259
diff changeset
2 title: Modules
24f5484bae97 web doc has now proper titles
Mike Becker <universe@uap-core.de>
parents: 259
diff changeset
3 ---
259
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
4
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
5 UCX provides several modules for data structures and algorithms.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
6 You may choose to use specific modules by inclueding the corresponding header
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
7 file.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
8 Please note, that some modules make use of other UCX modules.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
9 For instance, the [Allocator](#allocator) module is used by many other modules
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
10 to allow flexible memory allocation.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
11 By default the header files are placed into an `ucx` directory within your
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
12 systems include directory. In this case you can use an module by including it
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
13 via `#include <ucx/MODULENAME.h>`.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
14 Required modules are included automatically.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
15
267
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
16 <div id="modules" align="center">
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
17
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
18 ----------------------- ---------------------- ---------------------------- -------------------------
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
19 [Allocator](#allocator) [AVL&nbsp;Tree](#avl) [Buffer](#buffer) [List](#list)
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
20 [Logging](#logging) [Map](#map) [Memory&nbsp;Pool](#mempool) [Properties](#properties)
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
21 [Stack](#stack) [String](#string) [Testing](#test) [Utilities](#utils)
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
22 ----------------------- ---------------------- ---------------------------- -------------------------
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
23
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
24 </div>
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
25
259
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
26 <a name="allocator"></a>
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
27
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
28 ## Allocator
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
29
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
30 *Header file:* [allocator.h](api/allocator_8h.html)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
31 *Required modules:* None.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
32
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
33 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
34 function pointers to memory management functions operating on this memory
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
35 area / pool. These functions shall behave equivalent to the standard libc
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
36 functions `malloc`, `calloc`, `realloc` and `free`.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
37
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
38 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
39 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
40 memory area / pool as first argument.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
41
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
42 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
43 can be provided to the memory management functions. One example is the
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
44 [UCX Memory Pool](#mempool).
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
45
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
46 <a name="avl"></a>
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
47
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
48 ## AVL Tree
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
49
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
50 *Header file:* [avl.h](api/avl_8h.html)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
51 *Required modules:* [Allocator](#allocator)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
52
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
53 This binary search tree implementation allows average O(1) insertion and
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
54 removal of elements (excluding binary search time).
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
55 All common binary tree operations are implemented. Furthermore, this module
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
56 provides search functions via lower and upper bounds.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
57
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
58 <a name="buffer"></a>
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
59
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
60 ## Buffer
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
61
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
62 *Header file:* [buffer.h](api/buffer_8h.html)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
63 *Required modules:* None.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
64
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
65 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
66 memory like you would do with a stream. This allows the use of
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
67 `ucx_stream_copy` from the [Utilities](#utils) module to copy contents from one
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
68 buffer to another or from file or network streams to the buffer and
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
69 vice-versa.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
70
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
71 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
72 memory management and automatic resizing of the buffer space.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
73 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
74 information.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
75
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
76 <a name="list"></a>
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
77
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
78 ## List
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
79
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
80 *Header file:* [list.h](api/list_8h.html)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
81 *Required modules:* [Allocator](#allocator)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
82
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
83 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
84 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
85 we allow convenient iteration via a special `UCX_FOREACH` macro.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
86
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
87 <a name="logging"></a>
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
88
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
89 ## Logging
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
90
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
91 *Header file:* [logging.h](api/logging_8h.html)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
92 *Required modules:* [Map](#map), [String](#string)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
93
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
94 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
95 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
96 line number logged automatically when outputting a message.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
97
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
98
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
99 <a name="map"></a>
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
100
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
101 ## Map
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
102
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
103 *Header file:* [map.h](api/map_8h.html)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
104 *Required modules:* [Allocator](#allocator), [String](#string)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
105
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
106 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
107 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
108 `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
109
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
110 <a name="mempool"></a>
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
111
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
112 ## Memory Pool
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
113
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
114 *Header file:* [mempool.h](api/mempool_8h.html)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
115 *Required modules:* [Allocator](#allocator)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
116
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
117 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
118 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
119 which are automatically called on the destruction of the pool.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
120 But you may also register *independent* destructor functions within a pool in
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
121 case, some external library allocated memory for you, which you wish to be
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
122 destroyed together with this pool.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
123
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
124 <a name="properties"></a>
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
125
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
126 ## Properties
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
127
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
128 *Header file:* [properties.h](api/properties_8h.html)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
129 *Required modules:* [Map](#map)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
130
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
131 This module provides load and store function for `*.properties` files.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
132 The key/value pairs are stored within an UCX Map.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
133
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
134 <a name="stack"></a>
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
135
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
136 ## Stack
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
137
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
138 *Header file:* [stack.h](api/stack_8h.html)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
139 *Required modules:* [Allocator](#allocator)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
140
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
141 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
142 of memory which is then handled as a stack.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
143 Please note, that the term *stack* only refers to the behavior of this
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
144 allocator. You may still choose if you want to use stack or heap memory
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
145 for the underlying space.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
146
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
147 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
148 amounts of memory very frequently.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
149
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
150 <a name="string"></a>
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
151
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
152 ## String
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
153
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
154 *Header file:* [string.h](api/string_8h.html)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
155 *Required modules:* [Allocator](#allocator)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
156
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
157 This module provides a safe implementation of bounded string.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
158 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
159 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
160 arbitrary strings.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
161 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
162 reduce the risk of buffer overflows dramatically.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
163
267
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
164 ### Initialization
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
165
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
166 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
167
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
168 ```C
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
169 /* (1) sstr() uses strlen() internally, hence cstr MUST be zero-terminated */
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
170 sstr_t a = sstr(cstr);
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
171
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
172 /* (2) cstr does not need to be zero-terminated, if length is specified */
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
173 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
174
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
175 /* (3) S() macro creates sstr_t from a string using sizeof() and using sstrn().
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
176 This version is especially useful for function arguments */
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
177 sstr_t c = S("hello");
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
178
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
179 /* (4) ST() macro creates sstr_t struct literal using sizeof() */
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
180 sstr_t d = ST("hello");
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
181 ```
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
182
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
183 You should not use the `S()` or `ST()` macro with string of unknown origin,
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
184 since the `sizeof()` call might not coincide with the string length in those
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
185 cases. If you know what you are doing, it can save you some performance,
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
186 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
187
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
188 ### 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
189
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
190 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
191 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
192 subtraction.
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
193
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
194 ```C
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
195 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
196 sstr_t needle = ST("we");
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
197 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
198 if (result.ptr)
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
199 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
200 else
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
201 printf("Not found.\n");
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
202 ```
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
203
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
204 ### 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
205
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
206 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
207 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
208 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
209 pool.
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
210
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
211 ```C
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
212 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
213 sstr_t delim = ST("::");
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
214
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
215 ssize_t count = 0; /* no limit */
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
216 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
217
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
218 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
219 for (ssize_t i = 0 ; i < count ; i++) {
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
220 /* don't forget to specify the length via the %*s format specifier */
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
221 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
222 }
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
223
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
224 ucx_mempool_destroy(pool);
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
225 ```
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
226 The output is:
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
227
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
228 here
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
229 are
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
230 some
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
231 strings
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
232
f4789572c9d6 restructures documentation + adds some examples for sstr_t
Mike Becker <universe@uap-core.de>
parents: 264
diff changeset
233 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
234
259
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
235 <a name="test"></a>
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
236
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
237 ## Testing
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
238
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
239 *Header file:* [test.h](api/test_8h.html)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
240 *Required modules:* None.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
241
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
242 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
243 within test suites.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
244 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
245 define test subroutines.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
246
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
247 <a name="utils"></a>
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
248
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
249 ## Utilities
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
250
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
251 *Header file:* [utils.h](api/utils_8h.html)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
252 *Required modules:* [Allocator](#allocator), [String](#string)
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
253
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
254 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
255 operations.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
256 We also provide several `printf` variants to conveniently print formatted data
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
257 to streams or strings.
2f5dea574a75 modules documentation
Mike Becker <universe@uap-core.de>
parents: 256
diff changeset
258

mercurial