Mercurial > hg > ucx / changeset

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

--- a/docs/src/examples.md	Mon Nov 13 15:54:17 2017 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,46 +0,0 @@
----
-title: Examples
----
-
-On this page you find several example use cases in which the UAP Common
-Extensions make life easier.
-The examples are ordered by the complexity of the problem and start with
-simple showcases.
-Finally, we show how to implement a simple [properties editor](#props) with UCX.
-
-<a name="sstr"></a>
-
-## String
-
-Coming soon...
-
-<a name="list"></a>
-
-## List
-
-Coming soon...
-
-<a name="mpool"></a>
-
-## Memory Pool
-
-Coming soon...
-
-<a name="buffer"></a>
-
-## Buffer
-
-Coming soon...
-
-<a name="tests"></a>
-
-## Testing
-
-Coming soon...
-
-<a name="props"></a>
-
-## Properties Editor
-
-Coming soon...
-

--- a/docs/src/header.html	Mon Nov 13 15:54:17 2017 +0100
+++ b/docs/src/header.html	Mon Nov 20 16:10:23 2017 +0100
@@ -34,22 +34,12 @@
                         <li><a href="modules.html#utils">Utilities</a></li>
                     </ul>
                     </li>
-                    <li><a href="examples.html">Examples</a>
-                    <ul>
-                        <li><a href="examples.html#sstr">String</a></li>
-                        <li><a href="examples.html#list">List</a></li>
-                        <li><a href="examples.html#mpool">Memory Pool</a></li>
-                        <li><a href="examples.html#buffer">Buffer</a></li>
-                        <li><a href="examples.html#tests">Testing</a></li>
-                        <li><a href="examples.html#props">Properties Editor</a></li>
-                    </ul>
-                    </li>
+                    <li><a target="_blank" href="api/index.html">API Reference</a></li>
                 </ul>
             </div>
             <div class="nav">
-                <h3>Resources</h3>
+                <h3>Repositories</h3>
                 <ul>
-                    <li><a target="_blank" href="api/index.html">API Reference</a></li>
                     <li><a target="_blank" href="https://develop.uap-core.de/hg/ucx/">UAP Core Repository</a></li>
                     <li><a target="_blank" href="https://sourceforge.net/p/ucx/">Source Forge</a></li>
                 </ul>

--- a/docs/src/modules.md	Mon Nov 13 15:54:17 2017 +0100
+++ b/docs/src/modules.md	Mon Nov 20 16:10:23 2017 +0100
@@ -13,6 +13,16 @@
 via `#include <ucx/MODULENAME.h>`.
 Required modules are included automatically.
 
+<div id="modules" align="center">
+    
+----------------------- ---------------------- ---------------------------- -------------------------
+[Allocator](#allocator) [AVL&nbsp;Tree](#avl)  [Buffer](#buffer)            [List](#list)
+[Logging](#logging)     [Map](#map)            [Memory&nbsp;Pool](#mempool) [Properties](#properties)
+[Stack](#stack)         [String](#string)      [Testing](#test)             [Utilities](#utils)
+----------------------- ---------------------- ---------------------------- -------------------------
+
+</div>
+
 <a name="allocator"></a>
 
 ## Allocator
@@ -151,6 +161,77 @@
 The `sstr_t` type of this module always carries the string and its length to
 reduce the risk of buffer overflows dramatically.
 
+### Initialization
+
+There are several ways to create an `sstr_t`:
+
+```C
+/* (1) sstr() uses strlen() internally, hence cstr MUST be zero-terminated */
+sstr_t a = sstr(cstr);
+
+/* (2) cstr does not need to be zero-terminated, if length is specified */
+sstr_t b = sstrn(cstr, len);
+
+/* (3) S() macro creates sstr_t from a string using sizeof() and using sstrn().
+       This version is especially useful for function arguments */
+sstr_t c = S("hello");
+
+/* (4) ST() macro creates sstr_t struct literal using sizeof() */
+sstr_t d = ST("hello");
+```
+
+You should not use the `S()` or `ST()` macro with string of unknown origin,
+since the `sizeof()` call might not coincide with the string length in those
+cases. If you know what you are doing, it can save you some performance,
+because you do not need the `strlen()` call.
+
+### Finding the position of a substring
+
+The `sstrstr()` function gives you a new `sstr_t` object starting with the
+requested substring. Thus determining the position comes down to a simple
+subtraction.
+
+```C
+sstr_t haystack = ST("Here we go!");
+sstr_t needle = ST("we");
+sstr_t result = sstrstr(haystack, needle);
+if (result.ptr)
+    printf("Found at position %zd.\n", haystack.length-result.length);
+else
+    printf("Not found.\n");
+```
+
+### Spliting a string by a delimiter
+
+The `sstrsplit()` function (and its allocator based version `sstrsplit_a()`) is
+very powerful and might look a bit nasty at a first glance. But it is indeed
+very simple to use. It is even more convenient in combination with a memory
+pool.
+
+```C
+sstr_t test = ST("here::are::some::strings");
+sstr_t delim = ST("::");
+
+ssize_t count = 0; /* no limit */
+UcxMempool* pool = ucx_mempool_new_default();
+
+sstr_t* result = sstrsplit_a(pool->allocator, test, delim, &count);
+for (ssize_t i = 0 ; i < count ; i++) {
+    /* don't forget to specify the length via the %*s format specifier */
+    printf("%*s\n", result[i].length, result[i].ptr);
+}
+
+ucx_mempool_destroy(pool);
+```
+The output is:
+
+    here
+    are
+    some
+    strings
+
+The memory pool ensures, that all strings are freed.
+
 <a name="test"></a>
 
 ## Testing

--- a/docs/src/ucx.css	Mon Nov 13 15:54:17 2017 +0100
+++ b/docs/src/ucx.css	Mon Nov 20 16:10:23 2017 +0100
@@ -92,3 +92,23 @@
 #content h3 {
     font-size: 1.05em;
 }
+
+#modules table {
+    border-collapse: separate;
+    border-spacing: .25em;
+}
+
+#modules td > a {
+    display: table-cell;
+    text-align: center;
+    vertical-align: middle;
+    width: 10em;
+    height: 2em;
+    border-style: solid;
+    border-width: 1pt;
+    border-color: #2e2e2e;
+}
+
+#modules td > a:hover {
+    background: #e9ebec;
+}