1.1 --- a/docs/src/modules.md Mon Nov 13 15:54:17 2017 +0100
1.2 +++ b/docs/src/modules.md Mon Nov 20 16:10:23 2017 +0100
1.3 @@ -13,6 +13,16 @@
1.4 via `#include <ucx/MODULENAME.h>`.
1.5 Required modules are included automatically.
1.6
1.7 +<div id="modules" align="center">
1.8 +
1.9 +----------------------- ---------------------- ---------------------------- -------------------------
1.10 +[Allocator](#allocator) [AVL Tree](#avl) [Buffer](#buffer) [List](#list)
1.11 +[Logging](#logging) [Map](#map) [Memory Pool](#mempool) [Properties](#properties)
1.12 +[Stack](#stack) [String](#string) [Testing](#test) [Utilities](#utils)
1.13 +----------------------- ---------------------- ---------------------------- -------------------------
1.14 +
1.15 +</div>
1.16 +
1.17 <a name="allocator"></a>
1.18
1.19 ## Allocator
1.20 @@ -151,6 +161,77 @@
1.21 The `sstr_t` type of this module always carries the string and its length to
1.22 reduce the risk of buffer overflows dramatically.
1.23
1.24 +### Initialization
1.25 +
1.26 +There are several ways to create an `sstr_t`:
1.27 +
1.28 +```C
1.29 +/* (1) sstr() uses strlen() internally, hence cstr MUST be zero-terminated */
1.30 +sstr_t a = sstr(cstr);
1.31 +
1.32 +/* (2) cstr does not need to be zero-terminated, if length is specified */
1.33 +sstr_t b = sstrn(cstr, len);
1.34 +
1.35 +/* (3) S() macro creates sstr_t from a string using sizeof() and using sstrn().
1.36 + This version is especially useful for function arguments */
1.37 +sstr_t c = S("hello");
1.38 +
1.39 +/* (4) ST() macro creates sstr_t struct literal using sizeof() */
1.40 +sstr_t d = ST("hello");
1.41 +```
1.42 +
1.43 +You should not use the `S()` or `ST()` macro with string of unknown origin,
1.44 +since the `sizeof()` call might not coincide with the string length in those
1.45 +cases. If you know what you are doing, it can save you some performance,
1.46 +because you do not need the `strlen()` call.
1.47 +
1.48 +### Finding the position of a substring
1.49 +
1.50 +The `sstrstr()` function gives you a new `sstr_t` object starting with the
1.51 +requested substring. Thus determining the position comes down to a simple
1.52 +subtraction.
1.53 +
1.54 +```C
1.55 +sstr_t haystack = ST("Here we go!");
1.56 +sstr_t needle = ST("we");
1.57 +sstr_t result = sstrstr(haystack, needle);
1.58 +if (result.ptr)
1.59 + printf("Found at position %zd.\n", haystack.length-result.length);
1.60 +else
1.61 + printf("Not found.\n");
1.62 +```
1.63 +
1.64 +### Spliting a string by a delimiter
1.65 +
1.66 +The `sstrsplit()` function (and its allocator based version `sstrsplit_a()`) is
1.67 +very powerful and might look a bit nasty at a first glance. But it is indeed
1.68 +very simple to use. It is even more convenient in combination with a memory
1.69 +pool.
1.70 +
1.71 +```C
1.72 +sstr_t test = ST("here::are::some::strings");
1.73 +sstr_t delim = ST("::");
1.74 +
1.75 +ssize_t count = 0; /* no limit */
1.76 +UcxMempool* pool = ucx_mempool_new_default();
1.77 +
1.78 +sstr_t* result = sstrsplit_a(pool->allocator, test, delim, &count);
1.79 +for (ssize_t i = 0 ; i < count ; i++) {
1.80 + /* don't forget to specify the length via the %*s format specifier */
1.81 + printf("%*s\n", result[i].length, result[i].ptr);
1.82 +}
1.83 +
1.84 +ucx_mempool_destroy(pool);
1.85 +```
1.86 +The output is:
1.87 +
1.88 + here
1.89 + are
1.90 + some
1.91 + strings
1.92 +
1.93 +The memory pool ensures, that all strings are freed.
1.94 +
1.95 <a name="test"></a>
1.96
1.97 ## Testing
