# HG changeset patch
# User Mike Becker <universe@uap-core.de>
# Date 1526057191 -7200
# Node ID bfa935ab7f85cc99fe84cfe7e4f257aaf9e2b27d
# Parent  d994325445f1c53e4f16362ac92501d4b7d33f11
example code for the usage of a UcxList

diff -r d994325445f1 -r bfa935ab7f85 docs/src/modules.md
--- a/docs/src/modules.md	Fri May 11 18:35:08 2018 +0200
+++ b/docs/src/modules.md	Fri May 11 18:46:31 2018 +0200
@@ -62,7 +62,7 @@
  */
 typedef struct {
     time_t ts;
-    // other important data
+    /* other important data */
 } MyObject;
 
 /* -----------
@@ -70,10 +70,10 @@
  */
 
 UcxAVLTree* tree = ucx_avl_new(ucx_longintcmp);
-// ... populate tree with objects, use '& MyObject.ts' as key ...
+/* ... populate tree with objects, use '& MyObject.ts' as key ... */
 
 
-// Now find every item, with 30 <= ts <= 70
+/* Now find every item, with 30 <= ts <= 70 */
 time_t ts_start = 30;
 time_t ts_end = 70;
 
@@ -141,18 +141,18 @@
 
     UcxBuffer* linebuf =
         ucx_buffer_new(
-            NULL,       // the buffer should manage the memory area for us
-            chunksize,  // initial buffer size should be the chunk size
-            UCX_BUFFER_AUTOEXTEND); // the buffer will grow when necessary
+            NULL,       /* the buffer should manage the memory area for us */
+            2*chunksize,  /* initial size should be twice the chunk size */
+            UCX_BUFFER_AUTOEXTEND); /* the buffer will grow when necessary */
 
     size_t lineno = 1;
     do {
-        // read line chunk
+        /* read line chunk */
         size_t read = ucx_stream_ncopy(
                 input, linebuf, fread, ucx_buffer_write, chunksize);
         if (read == 0) break;
         
-        // handle line endings
+        /* handle line endings */
         do {
             sstr_t bufstr = ucx_buffer_to_sstr(linebuf);
             sstr_t nl = sstrchr(bufstr, '\n');
@@ -163,13 +163,13 @@
 
             printf("%zu: %" PRIsstr "\n", lineno++, SFMT(linestr));
 
-            // shift the buffer to the next line
+            /* shift the buffer to the next line */
             ucx_buffer_shift_left(linebuf, linelen+1);
         } while(1);
 
     } while(1);
 
-    // print the 'noeol' line, if any
+    /* print the 'noeol' line, if any */
     sstr_t lastline = ucx_buffer_to_sstr(linebuf);
     if (lastline.length > 0) {
         printf("%zu: %" PRIsstr, lineno, SFMT(lastline));
@@ -191,6 +191,53 @@
 linked list. Among the common operations like insert, remove, search and sort,
 we allow convenient iteration via a special `UCX_FOREACH` macro.
 
+### Remove duplicates from an array of strings
+
+Assume you are given an array of `sstr_t` and want to create a list of these
+strings without duplicates.
+```C
+#include <stdio.h>
+#include <ucx/list.h>
+#include <ucx/string.h>
+#include <ucx/utils.h>
+
+UcxList* remove_duplicates(sstr_t* array, size_t arrlen) {
+    UcxList* list = NULL;
+    for (size_t i = 0 ; i < arrlen ; ++i) {
+        if (ucx_list_find(list, array+i, ucx_sstrcmp, NULL) == -1) {
+            sstr_t* s = malloc(sizeof(sstr_t));
+            *s = sstrdup(array[i]);
+            list = ucx_list_append(list, s);
+        }
+    }
+    return list;
+}
+
+/* we will need this function to clean up the list contents later */
+void free_sstr(void* ptr) {
+    sstr_t* s = ptr;
+    free(s->ptr);
+    free(s);
+}
+
+/* ... */
+
+sstr_t* array = /* some array of strings */
+size_t arrlen = /* the length of the array */
+
+UcxList* list = remove_duplicates(array,arrlen);
+
+/* Iterate over the list and print the elements */
+UCX_FOREACH(elem, list) {
+    sstr_t s = *((sstr_t*)elem->data);
+    printf("%" PRIsstr "\n", SFMT(s));
+}
+
+/* Use our free function to free the duplicated strings. */
+ucx_list_free_content(list, free_sstr);
+ucx_list_free(list);
+```
+
 ## Logging
 
 *Header file:* [logging.h](api/logging_8h.html)  
@@ -233,30 +280,30 @@
 ### Example: Loading properties from a file
 
 ```C
-// Open the file as usual
+/* Open the file as usual */
 FILE* file = fopen("myprops.properties", "r");
 if (!file) {
     // error handling
     return 1;
 }
 
-// Load the properties from the file
+/* Load the properties from the file */
 UcxMap* myprops = ucx_map_new(16);
 if (ucx_properties_load(myprops, file)) {
-    // error handling
+    /* ... error handling ... */
     fclose(file);
     ucx_map_free(myprops);
     return 1;
 }
 
-// Print out the key/value pairs
+/* Print out the key/value pairs */
 char* propval;
 UcxMapIterator propiter = ucx_map_iterator(myprops);
 UCX_MAP_FOREACH(key, propval, propiter) {
     printf("%s = %s\n", (char*)key.data, propval);
 }
 
-// Don't forget to free the values before freeing the map
+/* Don't forget to free the values before freeing the map */
 ucx_map_free_content(myprops, NULL);
 ucx_map_free(myprops);
 fclose(file);
@@ -395,7 +442,7 @@
         return 1;
     }
 
-    FILE *srcf = fopen(argv[1], "r");     // insert error handling on your own
+    FILE *srcf = fopen(argv[1], "r");   /* insert error handling on your own */
     FILE *destf = fopen(argv[2], "w");
     
     size_t n =  ucx_stream_copy(srcf, destf, fread, fwrite);
@@ -430,7 +477,7 @@
                         i, prime(i) ? "prime" : "not prime");
 }
 
-// print the result to stdout
+/* print the result to stdout */
 printf("%s", (char*)strbuffer->space);
 
 ucx_buffer_free(strbuffer);