Mercurial > hg > ucx / changeset

     1.1 --- a/docs/src/Makefile	Mon Nov 13 15:54:17 2017 +0100
     1.2 +++ b/docs/src/Makefile	Mon Nov 20 16:10:23 2017 +0100
     1.3 @@ -30,7 +30,6 @@
     1.4  PFLAGS=-c ucx.css -B header.html -A footer.html -T 'UAP Common Extensions'
     1.5  
     1.6  SRC  = index.md
     1.7 -SRC += examples.md
     1.8  SRC += install.md
     1.9  SRC += license.md
    1.10  SRC += modules.md

     2.1 --- a/docs/src/examples.md	Mon Nov 13 15:54:17 2017 +0100
     2.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.3 @@ -1,46 +0,0 @@
     2.4 ----
     2.5 -title: Examples
     2.6 ----
     2.7 -
     2.8 -On this page you find several example use cases in which the UAP Common
     2.9 -Extensions make life easier.
    2.10 -The examples are ordered by the complexity of the problem and start with
    2.11 -simple showcases.
    2.12 -Finally, we show how to implement a simple [properties editor](#props) with UCX.
    2.13 -
    2.14 -<a name="sstr"></a>
    2.15 -
    2.16 -## String
    2.17 -
    2.18 -Coming soon...
    2.19 -
    2.20 -<a name="list"></a>
    2.21 -
    2.22 -## List
    2.23 -
    2.24 -Coming soon...
    2.25 -
    2.26 -<a name="mpool"></a>
    2.27 -
    2.28 -## Memory Pool
    2.29 -
    2.30 -Coming soon...
    2.31 -
    2.32 -<a name="buffer"></a>
    2.33 -
    2.34 -## Buffer
    2.35 -
    2.36 -Coming soon...
    2.37 -
    2.38 -<a name="tests"></a>
    2.39 -
    2.40 -## Testing
    2.41 -
    2.42 -Coming soon...
    2.43 -
    2.44 -<a name="props"></a>
    2.45 -
    2.46 -## Properties Editor
    2.47 -
    2.48 -Coming soon...
    2.49 -

     3.1 --- a/docs/src/header.html	Mon Nov 13 15:54:17 2017 +0100
     3.2 +++ b/docs/src/header.html	Mon Nov 20 16:10:23 2017 +0100
     3.3 @@ -34,22 +34,12 @@
     3.4                          <li><a href="modules.html#utils">Utilities</a></li>
     3.5                      </ul>
     3.6                      </li>
     3.7 -                    <li><a href="examples.html">Examples</a>
     3.8 -                    <ul>
     3.9 -                        <li><a href="examples.html#sstr">String</a></li>
    3.10 -                        <li><a href="examples.html#list">List</a></li>
    3.11 -                        <li><a href="examples.html#mpool">Memory Pool</a></li>
    3.12 -                        <li><a href="examples.html#buffer">Buffer</a></li>
    3.13 -                        <li><a href="examples.html#tests">Testing</a></li>
    3.14 -                        <li><a href="examples.html#props">Properties Editor</a></li>
    3.15 -                    </ul>
    3.16 -                    </li>
    3.17 +                    <li><a target="_blank" href="api/index.html">API Reference</a></li>
    3.18                  </ul>
    3.19              </div>
    3.20              <div class="nav">
    3.21 -                <h3>Resources</h3>
    3.22 +                <h3>Repositories</h3>
    3.23                  <ul>
    3.24 -                    <li><a target="_blank" href="api/index.html">API Reference</a></li>
    3.25                      <li><a target="_blank" href="https://develop.uap-core.de/hg/ucx/">UAP Core Repository</a></li>
    3.26                      <li><a target="_blank" href="https://sourceforge.net/p/ucx/">Source Forge</a></li>
    3.27                  </ul>

     4.1 --- a/docs/src/modules.md	Mon Nov 13 15:54:17 2017 +0100
     4.2 +++ b/docs/src/modules.md	Mon Nov 20 16:10:23 2017 +0100
     4.3 @@ -13,6 +13,16 @@
     4.4  via `#include <ucx/MODULENAME.h>`.
     4.5  Required modules are included automatically.
     4.6  
     4.7 +<div id="modules" align="center">
     4.8 +    
     4.9 +----------------------- ---------------------- ---------------------------- -------------------------
    4.10 +[Allocator](#allocator) [AVL&nbsp;Tree](#avl)  [Buffer](#buffer)            [List](#list)
    4.11 +[Logging](#logging)     [Map](#map)            [Memory&nbsp;Pool](#mempool) [Properties](#properties)
    4.12 +[Stack](#stack)         [String](#string)      [Testing](#test)             [Utilities](#utils)
    4.13 +----------------------- ---------------------- ---------------------------- -------------------------
    4.14 +
    4.15 +</div>
    4.16 +
    4.17  <a name="allocator"></a>
    4.18  
    4.19  ## Allocator
    4.20 @@ -151,6 +161,77 @@
    4.21  The `sstr_t` type of this module always carries the string and its length to
    4.22  reduce the risk of buffer overflows dramatically.
    4.23  
    4.24 +### Initialization
    4.25 +
    4.26 +There are several ways to create an `sstr_t`:
    4.27 +
    4.28 +```C
    4.29 +/* (1) sstr() uses strlen() internally, hence cstr MUST be zero-terminated */
    4.30 +sstr_t a = sstr(cstr);
    4.31 +
    4.32 +/* (2) cstr does not need to be zero-terminated, if length is specified */
    4.33 +sstr_t b = sstrn(cstr, len);
    4.34 +
    4.35 +/* (3) S() macro creates sstr_t from a string using sizeof() and using sstrn().
    4.36 +       This version is especially useful for function arguments */
    4.37 +sstr_t c = S("hello");
    4.38 +
    4.39 +/* (4) ST() macro creates sstr_t struct literal using sizeof() */
    4.40 +sstr_t d = ST("hello");
    4.41 +```
    4.42 +
    4.43 +You should not use the `S()` or `ST()` macro with string of unknown origin,
    4.44 +since the `sizeof()` call might not coincide with the string length in those
    4.45 +cases. If you know what you are doing, it can save you some performance,
    4.46 +because you do not need the `strlen()` call.
    4.47 +
    4.48 +### Finding the position of a substring
    4.49 +
    4.50 +The `sstrstr()` function gives you a new `sstr_t` object starting with the
    4.51 +requested substring. Thus determining the position comes down to a simple
    4.52 +subtraction.
    4.53 +
    4.54 +```C
    4.55 +sstr_t haystack = ST("Here we go!");
    4.56 +sstr_t needle = ST("we");
    4.57 +sstr_t result = sstrstr(haystack, needle);
    4.58 +if (result.ptr)
    4.59 +    printf("Found at position %zd.\n", haystack.length-result.length);
    4.60 +else
    4.61 +    printf("Not found.\n");
    4.62 +```
    4.63 +
    4.64 +### Spliting a string by a delimiter
    4.65 +
    4.66 +The `sstrsplit()` function (and its allocator based version `sstrsplit_a()`) is
    4.67 +very powerful and might look a bit nasty at a first glance. But it is indeed
    4.68 +very simple to use. It is even more convenient in combination with a memory
    4.69 +pool.
    4.70 +
    4.71 +```C
    4.72 +sstr_t test = ST("here::are::some::strings");
    4.73 +sstr_t delim = ST("::");
    4.74 +
    4.75 +ssize_t count = 0; /* no limit */
    4.76 +UcxMempool* pool = ucx_mempool_new_default();
    4.77 +
    4.78 +sstr_t* result = sstrsplit_a(pool->allocator, test, delim, &count);
    4.79 +for (ssize_t i = 0 ; i < count ; i++) {
    4.80 +    /* don't forget to specify the length via the %*s format specifier */
    4.81 +    printf("%*s\n", result[i].length, result[i].ptr);
    4.82 +}
    4.83 +
    4.84 +ucx_mempool_destroy(pool);
    4.85 +```
    4.86 +The output is:
    4.87 +
    4.88 +    here
    4.89 +    are
    4.90 +    some
    4.91 +    strings
    4.92 +
    4.93 +The memory pool ensures, that all strings are freed.
    4.94 +
    4.95  <a name="test"></a>
    4.96  
    4.97  ## Testing

     5.1 --- a/docs/src/ucx.css	Mon Nov 13 15:54:17 2017 +0100
     5.2 +++ b/docs/src/ucx.css	Mon Nov 20 16:10:23 2017 +0100
     5.3 @@ -92,3 +92,23 @@
     5.4  #content h3 {
     5.5      font-size: 1.05em;
     5.6  }
     5.7 +
     5.8 +#modules table {
     5.9 +    border-collapse: separate;
    5.10 +    border-spacing: .25em;
    5.11 +}
    5.12 +
    5.13 +#modules td > a {
    5.14 +    display: table-cell;
    5.15 +    text-align: center;
    5.16 +    vertical-align: middle;
    5.17 +    width: 10em;
    5.18 +    height: 2em;
    5.19 +    border-style: solid;
    5.20 +    border-width: 1pt;
    5.21 +    border-color: #2e2e2e;
    5.22 +}
    5.23 +
    5.24 +#modules td > a:hover {
    5.25 +    background: #e9ebec;
    5.26 +}