Mercurial > hg > ucx / changeset

     1.1 --- a/docs/src/modules.md	Thu Nov 07 10:10:36 2019 +0100
     1.2 +++ b/docs/src/modules.md	Thu Nov 07 10:43:31 2019 +0100
     1.3 @@ -61,22 +61,17 @@
     1.4  a standard dynamic C array (pointer+length) as basis.
     1.5  
     1.6  ```C
     1.7 -#include <stdio.h>
     1.8 -#include <ucx/array.h>
     1.9 -#include <ucx/string.h>
    1.10 -#include <ucx/utils.h>
    1.11 -
    1.12 -UcxArray remove_duplicates(sstr_t* array, size_t arrlen) {
    1.13 +UcxArray* create_unique(sstr_t* array, size_t arrlen) {
    1.14      // worst case is no duplicates, hence the capacity is set to arrlen
    1.15 -    UcxArray result = ucx_array_new(arrlen, sizeof(sstr_t));
    1.16 +    UcxArray* result = ucx_array_new(arrlen, sizeof(sstr_t));
    1.17      // only append elements, if they are not already present in the array
    1.18      for (size_t i = 0 ; i < arrlen ; ++i) {
    1.19          if (!ucx_array_contains(result, array+i, ucx_cmp_sstr, NULL)) {
    1.20 -            ucx_array_append(&result, array+i);
    1.21 +            ucx_array_append_from(result, array+i, 1);
    1.22          }
    1.23      }
    1.24      // make the array as small as possible
    1.25 -    ucx_array_shrink(&result);
    1.26 +    ucx_array_shrink(result);
    1.27      return result;
    1.28  }
    1.29  
    1.30 @@ -85,16 +80,36 @@
    1.31  sstr_t* array = /* some standard array of strings */
    1.32  size_t arrlen = /* the length of the array */
    1.33  
    1.34 -UcxArray result = remove_duplicates(array,arrlen);
    1.35 +UcxArray* result = create_unique(array,arrlen);
    1.36  
    1.37  /* Iterate over the array and print the elements */
    1.38 -for (size_t i = 0 ; i < result.size ; i++) {
    1.39 -    sstr_t s = ucx_array_at_typed(sstr_t, result, i);
    1.40 -    printf("%" PRIsstr "\n", SFMT(s));
    1.41 +sstr_t* unique = result->data;
    1.42 +for (size_t i = 0 ; i < result->size ; i++) {
    1.43 +    printf("%" PRIsstr "\n", SFMT(unique[i]));
    1.44  }
    1.45  
    1.46  /* Free the array. */
    1.47 -ucx_array_free(&result);
    1.48 +ucx_array_free(result);
    1.49 +```
    1.50 +### Preventing out of bounds writes
    1.51 +
    1.52 +The functions `ucx_array_reserve()`, `ucx_array_resize()`, `ucx_array_grow()`,
    1.53 +and `ucx_array_shrink()` allow easy management of the array capacity.
    1.54 +Imagine you want to add `n` elements to an array. If your `n` elements are
    1.55 +already somewhere else consecutively in memory, you can use
    1.56 +`ucx_array_append_from()` and benefit from the autogrow facility in this family
    1.57 +of functions. Otherwise, you can ask the array to have enough capacity for
    1.58 +holding additional `n` elements.
    1.59 +
    1.60 +```C
    1.61 +size_t n = // ... elements to add
    1.62 +if (ucx_array_grow(array, n)) {
    1.63 +   fprintf(stderr, "Cannot add %zu elements to the array.\n", n);
    1.64 +   return 1;
    1.65 +}
    1.66 +for (size_t i = 0 ; i < n ; i++) {
    1.67 +    ((int*)array->data)[array->size++] = 80;
    1.68 +}
    1.69  ```
    1.70  
    1.71  ## AVL Tree