Mercurial > hg > ucx / changeset

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

--- a/docs/src/modules.md	Fri Jul 05 15:07:43 2019 +0200
+++ b/docs/src/modules.md	Fri Jul 05 15:47:57 2019 +0200
@@ -15,11 +15,12 @@
 
 <div id="modules" align="center">
     
------------------------ ----------------------      ----------------------------     -------------------------
-[Allocator](#allocator) [AVL&nbsp;Tree](#avl-tree)  [Buffer](#buffer)                [List](#list)
-[Logging](#logging)     [Map](#map)                 [Memory&nbsp;Pool](#memory-pool) [Properties](#properties)
-[Stack](#stack)         [String](#string)           [Testing](#testing)              [Utilities](#utilities)
------------------------ ----------------------      ----------------------------     -------------------------
+----------------------- ----------------------  --------------------------------  ---------------------------
+[String](#string)       [Buffer](#buffer)
+[Allocator](#allocator) [Stack](#stack)         [Memory&nbsp;Pool](#memory-pool)     
+[Array](#array)         [List](#list)           [Map](#map)                       [AVL&nbsp;Tree](#avl-tree)
+[Logging](#logging)     [Testing](#testing)     [Utilities](#utilities)           [Properties](#properties)                         
+----------------------- ----------------------  --------------------------------  ---------------------------
 
 </div>
 
@@ -41,6 +42,60 @@
 can be provided to the memory management functions. One example is the
 [UCX Memory Pool](#memory-pool).
 
+## Array
+
+*Header file:* [array.h](api/array_8h.html)  
+*Required modules:* [Allocator](#allocator)
+
+The UCX Array is an implementation of a dynamic array with automatic
+reallocation. The array structure contains a capacity, the current size,
+the size of each element, the raw pointer to the memory area and an allocator.
+Unlike an [UcxList](#list), the array structure is typically passed by value,
+unless it is subjected to change. Arrays are in most cases much faster than
+linked list.
+
+### Remove duplicates from an array of strings
+
+The following example shows, how a `UcxArray` can be built with
+a standard dynamic C array (pointer+length) as basis.
+
+```C
+#include <stdio.h>
+#include <ucx/array.h>
+#include <ucx/string.h>
+#include <ucx/utils.h>
+
+UcxArray remove_duplicates(sstr_t* array, size_t arrlen) {
+    // worst case is no duplicates, hence the capacity is set to arrlen
+    UcxArray result = ucx_array_new(arrlen, sizeof(sstr_t));
+    // only append elements, if they are not already present in the array
+    for (size_t i = 0 ; i < arrlen ; ++i) {
+        if (!ucx_array_contains(result, array+i, ucx_cmp_sstr, NULL)) {
+            ucx_array_append(&result, array+i);
+        }
+    }
+    // make the array as small as possible
+    ucx_array_shrink(&result);
+    return result;
+}
+
+/* ... */
+
+sstr_t* array = /* some standard array of strings */
+size_t arrlen = /* the length of the array */
+
+UcxArray result = remove_duplicates(array,arrlen);
+
+/* Iterate over the array and print the elements */
+for (size_t i = 0 ; i < result.size ; i++) {
+    sstr_t s = ucx_array_at_typed(sstr_t, result, i);
+    printf("%" PRIsstr "\n", SFMT(s));
+}
+
+/* Free the array. */
+ucx_array_free(&result);
+```
+
 ## AVL Tree
 
 *Header file:* [avl.h](api/avl_8h.html)  
@@ -195,6 +250,8 @@
 
 Assume you are given an array of `sstr_t` and want to create a list of these
 strings without duplicates.
+This is a similar example to the one [above](#array), but here we are
+using a `UcxList`.
 ```C
 #include <stdio.h>
 #include <ucx/list.h>