Mercurial > hg > ucx / changeset

     1.1 --- a/docs/src/header.html	Fri Jul 05 15:07:43 2019 +0200
     1.2 +++ b/docs/src/header.html	Fri Jul 05 15:47:57 2019 +0200
     1.3 @@ -21,6 +21,7 @@
     1.4                      <li><a href="modules.html">Modules</a>
     1.5                      <ul>
     1.6                          <li><a href="modules.html#allocator">Allocator</a></li>
     1.7 +                        <li><a href="modules.html#array">Array</a></li>
     1.8                          <li><a href="modules.html#avl-tree">AVL Tree</a></li>
     1.9                          <li><a href="modules.html#buffer">Buffer</a></li>
    1.10                          <li><a href="modules.html#list">List</a></li>

     2.1 --- a/docs/src/modules.md	Fri Jul 05 15:07:43 2019 +0200
     2.2 +++ b/docs/src/modules.md	Fri Jul 05 15:47:57 2019 +0200
     2.3 @@ -15,11 +15,12 @@
     2.4  
     2.5  <div id="modules" align="center">
     2.6      
     2.7 ------------------------ ----------------------      ----------------------------     -------------------------
     2.8 -[Allocator](#allocator) [AVL&nbsp;Tree](#avl-tree)  [Buffer](#buffer)                [List](#list)
     2.9 -[Logging](#logging)     [Map](#map)                 [Memory&nbsp;Pool](#memory-pool) [Properties](#properties)
    2.10 -[Stack](#stack)         [String](#string)           [Testing](#testing)              [Utilities](#utilities)
    2.11 ------------------------ ----------------------      ----------------------------     -------------------------
    2.12 +----------------------- ----------------------  --------------------------------  ---------------------------
    2.13 +[String](#string)       [Buffer](#buffer)
    2.14 +[Allocator](#allocator) [Stack](#stack)         [Memory&nbsp;Pool](#memory-pool)     
    2.15 +[Array](#array)         [List](#list)           [Map](#map)                       [AVL&nbsp;Tree](#avl-tree)
    2.16 +[Logging](#logging)     [Testing](#testing)     [Utilities](#utilities)           [Properties](#properties)                         
    2.17 +----------------------- ----------------------  --------------------------------  ---------------------------
    2.18  
    2.19  </div>
    2.20  
    2.21 @@ -41,6 +42,60 @@
    2.22  can be provided to the memory management functions. One example is the
    2.23  [UCX Memory Pool](#memory-pool).
    2.24  
    2.25 +## Array
    2.26 +
    2.27 +*Header file:* [array.h](api/array_8h.html)  
    2.28 +*Required modules:* [Allocator](#allocator)
    2.29 +
    2.30 +The UCX Array is an implementation of a dynamic array with automatic
    2.31 +reallocation. The array structure contains a capacity, the current size,
    2.32 +the size of each element, the raw pointer to the memory area and an allocator.
    2.33 +Unlike an [UcxList](#list), the array structure is typically passed by value,
    2.34 +unless it is subjected to change. Arrays are in most cases much faster than
    2.35 +linked list.
    2.36 +
    2.37 +### Remove duplicates from an array of strings
    2.38 +
    2.39 +The following example shows, how a `UcxArray` can be built with
    2.40 +a standard dynamic C array (pointer+length) as basis.
    2.41 +
    2.42 +```C
    2.43 +#include <stdio.h>
    2.44 +#include <ucx/array.h>
    2.45 +#include <ucx/string.h>
    2.46 +#include <ucx/utils.h>
    2.47 +
    2.48 +UcxArray remove_duplicates(sstr_t* array, size_t arrlen) {
    2.49 +    // worst case is no duplicates, hence the capacity is set to arrlen
    2.50 +    UcxArray result = ucx_array_new(arrlen, sizeof(sstr_t));
    2.51 +    // only append elements, if they are not already present in the array
    2.52 +    for (size_t i = 0 ; i < arrlen ; ++i) {
    2.53 +        if (!ucx_array_contains(result, array+i, ucx_cmp_sstr, NULL)) {
    2.54 +            ucx_array_append(&result, array+i);
    2.55 +        }
    2.56 +    }
    2.57 +    // make the array as small as possible
    2.58 +    ucx_array_shrink(&result);
    2.59 +    return result;
    2.60 +}
    2.61 +
    2.62 +/* ... */
    2.63 +
    2.64 +sstr_t* array = /* some standard array of strings */
    2.65 +size_t arrlen = /* the length of the array */
    2.66 +
    2.67 +UcxArray result = remove_duplicates(array,arrlen);
    2.68 +
    2.69 +/* Iterate over the array and print the elements */
    2.70 +for (size_t i = 0 ; i < result.size ; i++) {
    2.71 +    sstr_t s = ucx_array_at_typed(sstr_t, result, i);
    2.72 +    printf("%" PRIsstr "\n", SFMT(s));
    2.73 +}
    2.74 +
    2.75 +/* Free the array. */
    2.76 +ucx_array_free(&result);
    2.77 +```
    2.78 +
    2.79  ## AVL Tree
    2.80  
    2.81  *Header file:* [avl.h](api/avl_8h.html)  
    2.82 @@ -195,6 +250,8 @@
    2.83  
    2.84  Assume you are given an array of `sstr_t` and want to create a list of these
    2.85  strings without duplicates.
    2.86 +This is a similar example to the one [above](#array), but here we are
    2.87 +using a `UcxList`.
    2.88  ```C
    2.89  #include <stdio.h>
    2.90  #include <ucx/list.h>