comparison: docs/src/modules.md
docs/src/modules.md
- changeset 267
- f4789572c9d6
- parent 264
- 24f5484bae97
- child 277
- f819fe5e20f5
equal
deleted
inserted
replaced
| 266:33d229634809 | 267:f4789572c9d6 |
|---|---|
| 11 By default the header files are placed into an `ucx` directory within your | 11 By default the header files are placed into an `ucx` directory within your |
| 12 systems include directory. In this case you can use an module by including it | 12 systems include directory. In this case you can use an module by including it |
| 13 via `#include <ucx/MODULENAME.h>`. | 13 via `#include <ucx/MODULENAME.h>`. |
| 14 Required modules are included automatically. | 14 Required modules are included automatically. |
| 15 | 15 |
| 16 <div id="modules" align="center"> | |
| 17 | |
| 18 ----------------------- ---------------------- ---------------------------- ------------------------- | |
| 19 [Allocator](#allocator) [AVL Tree](#avl) [Buffer](#buffer) [List](#list) | |
| 20 [Logging](#logging) [Map](#map) [Memory Pool](#mempool) [Properties](#properties) | |
| 21 [Stack](#stack) [String](#string) [Testing](#test) [Utilities](#utils) | |
| 22 ----------------------- ---------------------- ---------------------------- ------------------------- | |
| 23 | |
| 24 </div> | |
| 25 | |
| 16 <a name="allocator"></a> | 26 <a name="allocator"></a> |
| 17 | 27 |
| 18 ## Allocator | 28 ## Allocator |
| 19 | 29 |
| 20 *Header file:* [allocator.h](api/allocator_8h.html) | 30 *Header file:* [allocator.h](api/allocator_8h.html) |
| 149 can easily get the length with `strlen`, this is not generally possible for | 159 can easily get the length with `strlen`, this is not generally possible for |
| 150 arbitrary strings. | 160 arbitrary strings. |
| 151 The `sstr_t` type of this module always carries the string and its length to | 161 The `sstr_t` type of this module always carries the string and its length to |
| 152 reduce the risk of buffer overflows dramatically. | 162 reduce the risk of buffer overflows dramatically. |
| 153 | 163 |
| 164 ### Initialization | |
| 165 | |
| 166 There are several ways to create an `sstr_t`: | |
| 167 | |
| 168 ```C | |
| 169 /* (1) sstr() uses strlen() internally, hence cstr MUST be zero-terminated */ | |
| 170 sstr_t a = sstr(cstr); | |
| 171 | |
| 172 /* (2) cstr does not need to be zero-terminated, if length is specified */ | |
| 173 sstr_t b = sstrn(cstr, len); | |
| 174 | |
| 175 /* (3) S() macro creates sstr_t from a string using sizeof() and using sstrn(). | |
| 176 This version is especially useful for function arguments */ | |
| 177 sstr_t c = S("hello"); | |
| 178 | |
| 179 /* (4) ST() macro creates sstr_t struct literal using sizeof() */ | |
| 180 sstr_t d = ST("hello"); | |
| 181 ``` | |
| 182 | |
| 183 You should not use the `S()` or `ST()` macro with string of unknown origin, | |
| 184 since the `sizeof()` call might not coincide with the string length in those | |
| 185 cases. If you know what you are doing, it can save you some performance, | |
| 186 because you do not need the `strlen()` call. | |
| 187 | |
| 188 ### Finding the position of a substring | |
| 189 | |
| 190 The `sstrstr()` function gives you a new `sstr_t` object starting with the | |
| 191 requested substring. Thus determining the position comes down to a simple | |
| 192 subtraction. | |
| 193 | |
| 194 ```C | |
| 195 sstr_t haystack = ST("Here we go!"); | |
| 196 sstr_t needle = ST("we"); | |
| 197 sstr_t result = sstrstr(haystack, needle); | |
| 198 if (result.ptr) | |
| 199 printf("Found at position %zd.\n", haystack.length-result.length); | |
| 200 else | |
| 201 printf("Not found.\n"); | |
| 202 ``` | |
| 203 | |
| 204 ### Spliting a string by a delimiter | |
| 205 | |
| 206 The `sstrsplit()` function (and its allocator based version `sstrsplit_a()`) is | |
| 207 very powerful and might look a bit nasty at a first glance. But it is indeed | |
| 208 very simple to use. It is even more convenient in combination with a memory | |
| 209 pool. | |
| 210 | |
| 211 ```C | |
| 212 sstr_t test = ST("here::are::some::strings"); | |
| 213 sstr_t delim = ST("::"); | |
| 214 | |
| 215 ssize_t count = 0; /* no limit */ | |
| 216 UcxMempool* pool = ucx_mempool_new_default(); | |
| 217 | |
| 218 sstr_t* result = sstrsplit_a(pool->allocator, test, delim, &count); | |
| 219 for (ssize_t i = 0 ; i < count ; i++) { | |
| 220 /* don't forget to specify the length via the %*s format specifier */ | |
| 221 printf("%*s\n", result[i].length, result[i].ptr); | |
| 222 } | |
| 223 | |
| 224 ucx_mempool_destroy(pool); | |
| 225 ``` | |
| 226 The output is: | |
| 227 | |
| 228 here | |
| 229 are | |
| 230 some | |
| 231 strings | |
| 232 | |
| 233 The memory pool ensures, that all strings are freed. | |
| 234 | |
| 154 <a name="test"></a> | 235 <a name="test"></a> |
| 155 | 236 |
| 156 ## Testing | 237 ## Testing |
| 157 | 238 |
| 158 *Header file:* [test.h](api/test_8h.html) | 239 *Header file:* [test.h](api/test_8h.html) |
