1.1 --- a/docs/src/modules.md Fri Jul 05 15:07:43 2019 +0200
1.2 +++ b/docs/src/modules.md Fri Jul 05 15:47:57 2019 +0200
1.3 @@ -15,11 +15,12 @@
1.4
1.5 <div id="modules" align="center">
1.6
1.7 ------------------------ ---------------------- ---------------------------- -------------------------
1.8 -[Allocator](#allocator) [AVL Tree](#avl-tree) [Buffer](#buffer) [List](#list)
1.9 -[Logging](#logging) [Map](#map) [Memory Pool](#memory-pool) [Properties](#properties)
1.10 -[Stack](#stack) [String](#string) [Testing](#testing) [Utilities](#utilities)
1.11 ------------------------ ---------------------- ---------------------------- -------------------------
1.12 +----------------------- ---------------------- -------------------------------- ---------------------------
1.13 +[String](#string) [Buffer](#buffer)
1.14 +[Allocator](#allocator) [Stack](#stack) [Memory Pool](#memory-pool)
1.15 +[Array](#array) [List](#list) [Map](#map) [AVL Tree](#avl-tree)
1.16 +[Logging](#logging) [Testing](#testing) [Utilities](#utilities) [Properties](#properties)
1.17 +----------------------- ---------------------- -------------------------------- ---------------------------
1.18
1.19 </div>
1.20
1.21 @@ -41,6 +42,60 @@
1.22 can be provided to the memory management functions. One example is the
1.23 [UCX Memory Pool](#memory-pool).
1.24
1.25 +## Array
1.26 +
1.27 +*Header file:* [array.h](api/array_8h.html)
1.28 +*Required modules:* [Allocator](#allocator)
1.29 +
1.30 +The UCX Array is an implementation of a dynamic array with automatic
1.31 +reallocation. The array structure contains a capacity, the current size,
1.32 +the size of each element, the raw pointer to the memory area and an allocator.
1.33 +Unlike an [UcxList](#list), the array structure is typically passed by value,
1.34 +unless it is subjected to change. Arrays are in most cases much faster than
1.35 +linked list.
1.36 +
1.37 +### Remove duplicates from an array of strings
1.38 +
1.39 +The following example shows, how a `UcxArray` can be built with
1.40 +a standard dynamic C array (pointer+length) as basis.
1.41 +
1.42 +```C
1.43 +#include <stdio.h>
1.44 +#include <ucx/array.h>
1.45 +#include <ucx/string.h>
1.46 +#include <ucx/utils.h>
1.47 +
1.48 +UcxArray remove_duplicates(sstr_t* array, size_t arrlen) {
1.49 + // worst case is no duplicates, hence the capacity is set to arrlen
1.50 + UcxArray result = ucx_array_new(arrlen, sizeof(sstr_t));
1.51 + // only append elements, if they are not already present in the array
1.52 + for (size_t i = 0 ; i < arrlen ; ++i) {
1.53 + if (!ucx_array_contains(result, array+i, ucx_cmp_sstr, NULL)) {
1.54 + ucx_array_append(&result, array+i);
1.55 + }
1.56 + }
1.57 + // make the array as small as possible
1.58 + ucx_array_shrink(&result);
1.59 + return result;
1.60 +}
1.61 +
1.62 +/* ... */
1.63 +
1.64 +sstr_t* array = /* some standard array of strings */
1.65 +size_t arrlen = /* the length of the array */
1.66 +
1.67 +UcxArray result = remove_duplicates(array,arrlen);
1.68 +
1.69 +/* Iterate over the array and print the elements */
1.70 +for (size_t i = 0 ; i < result.size ; i++) {
1.71 + sstr_t s = ucx_array_at_typed(sstr_t, result, i);
1.72 + printf("%" PRIsstr "\n", SFMT(s));
1.73 +}
1.74 +
1.75 +/* Free the array. */
1.76 +ucx_array_free(&result);
1.77 +```
1.78 +
1.79 ## AVL Tree
1.80
1.81 *Header file:* [avl.h](api/avl_8h.html)
1.82 @@ -195,6 +250,8 @@
1.83
1.84 Assume you are given an array of `sstr_t` and want to create a list of these
1.85 strings without duplicates.
1.86 +This is a similar example to the one [above](#array), but here we are
1.87 +using a `UcxList`.
1.88 ```C
1.89 #include <stdio.h>
1.90 #include <ucx/list.h>
