Added carray docs.

6 files changed, 111 insertions, 13 deletions

diff --git a/README.md b/README.md
index 714da7da..67c2d242 100644
--- a/README.md
+++ b/README.md
@@ -5,7 +5,7 @@ Introduction
 ------------

 

 An elegant, fully typesafe, generic, customizable, user-friendly, consistent, and very fast standard container library for C99. This is a small headers only library with the most used container components, and a few algorithms:

-- [***carray*** - Dynamic generic **multi-dimensional array**](docs/cbitset_api.md), implemented as a single contiguous block of memory.

+- [***carray*** - Dynamic generic **multi-dimensional array**](docs/carray_api.md), implemented as a single contiguous block of memory.

 - [***cbitset*** - A **bitset** - *std::bitset*- or *boost::dynamic_bitset*-like](docs/cbitset_api.md)

 - [***clist*** - Generic circular **singly linked List** type](docs/clist_api.md). Can be used as a *queue* as it supports *push_back(), push_front(), and pop_front()*. Supports various *splice* functions and *merge sort*.

 - [***cmap*** - Generic fast **unordered map** type](docs/cmap_api.md) Implemented as open hashing without tombstones. Highly customizable and fast.

diff --git a/docs/carray_api.md b/docs/carray_api.md
new file mode 100644
index 00000000..c657667a
--- /dev/null
+++ b/docs/carray_api.md
@@ -0,0 +1,100 @@
+# Container type carray
+
+This describes the API of the unordered set type **carray**.
+
+## Declaration
+
+```c
+#define using_carray(X, Value, valueDestroy=c_default_del)
+```
+The macro `using_carray()` can be instantiated with 2 or 3 arguments in the global scope.
+Default values are given above for args not specified. `X` is a type tag name and
+will affect the names of all cset types and methods. E.g. declaring `using_carray(my, int);`, `X` should
+be replaced by `my` in all of the following documentation. The `#` character should be replaced by `1`, `2` or `3`.
+
+## Types
+
+| Type name            | Type definition               | Used to represent...      |
+|:---------------------|:------------------------------|:--------------------------|
+| `carray#X`           | `struct {`                    | The carray type           |
+|                      | `  carray#X_value_t* data;`   |                           |
+|                      | `  ...;`                      |                           |
+|                      | `}`                           |                           |
+| `carray#X_value_t`   | `Value`                       | The value type            |
+| `carray#X_iter_t`    | `struct { Value *val; }`      | Iterator type             |
+
+## Constants and macros
+
+| Name                 | Purpose                  |
+|:---------------------|:-------------------------|
+| `carray1_size(arr)   |                          |
+| `carray1_xdim(arr)   |                          |
+|                      |                          |
+| `carray2_size(arr)   |                          |
+| `carray2_xdim(arr)   |                          |
+| `carray2_ydim(arr)   |                          |
+|                      |                          |
+| `carray3_size(arr)   |                          |
+| `carray3_xdim(arr)   |                          |
+| `carray3_ydim(arr)   |                          |
+| `carray3_zdim(arr)   |                          |
+
+## Header file
+
+All cset definitions and prototypes may be included in your C source file by including a single header file.
+
+```c
+#include "stc/carray.h"
+```
+## Methods
+
+### Constructors
+```c
+carray1X            carray1X_init(size_t xdim, Value val);
+carray2X            carray2X_init(size_t ydim, size_t xdim, Value val);
+carray3X            carray3X_init(size_t zdim, size_t ydim, size_t xdim, Value val);
+carray1X            carray1X_from(Value* array, size_t xdim);
+carray2X            carray2X_from(Value* array, size_t ydim, size_t xdim);
+carray3X            carray3X_from(Value* array, size_t zdim, size_t ydim, size_t xdim);
+```
+### Data access
+```c
+Value*              carray1X_at(carray1X *self, size_t x);
+Value*              carray2X_at(carray2X *self, size_t y, size_t x);
+Value*              carray3X_at(carray3X *self, size_t z, size_t y, size_t x);
+carray1X            carray2X_at1(carray2X *self, size_t y);
+carray1X            carray3X_at2(carray3X *self, size_t z, size_t y);
+carray2X            carray3X_at1(carray3X *self, size_t z);
+```
+### Iterators
+```c
+carray#X_iter_t     carray#X_begin(carray#X* self);
+carray#X_iter_t     carray#X_end(carray#X* self);
+void                carray#X_next(carray#X_iter_t* it);
+carray#X_value_t*   carray#X_itval(carray#X_iter_t it);
+```
+
+## Example
+```c
+#include <stdio.h>
+#include "stc/carray.h"
+
+using_carray(f, float);
+
+int main()
+{
+    carray3f a3 = carray3f_init(30, 20, 10, 0.f);
+    *carray3f_at(&a3, 5, 4, 3) = 10.2f;         // a3[5][4][3]
+    carray2f a2 = carray3f_at1(&a3, 5);         // sub-array reference: a2 = a3[5]
+    printf("%g\n", *carray2f_at(&a2, 4, 3));    // lookup a2[4][3] (=10.2f)
+    printf("%g\n", *carray3f_at(&a3, 5, 4, 3)); // same data location, via a3 array.
+
+    carray2f_del(&a2); // does nothing, since it is a sub-array.
+    carray3f_del(&a3); // destroy a3, invalidates a2.
+}
+```
+Output:
+```
+10.2
+10.2
+```
\ No newline at end of file
diff --git a/docs/crandom_api.md b/docs/crandom_api.md
index 0d0f415d..ca798d07 100644
--- a/docs/crandom_api.md
+++ b/docs/crandom_api.md
@@ -107,8 +107,7 @@ int main()
     c_foreach (i, cvec_e, vhist) {
         size_t n = (size_t) (i.val->second * StdDev * Scale * 2.5 / N);
         if (n > 0) {
-            // Bar string: move new str after freeing current
-            cstr_take(&bar, cstr_with_size(n, '*'));
+            cstr_resize(&bar, n, '*');
             printf("%4d %s\n", i.val->first, bar.str);
         }
     }
diff --git a/docs/cset_api.md b/docs/cset_api.md
index d705ab02..92ec3e88 100644
--- a/docs/cset_api.md
+++ b/docs/cset_api.md
@@ -93,7 +93,7 @@ bool                cset_X_contains(const cset_X* self, RawKey rkey);
 cset_X_iter_t       cset_X_begin(cset_X* self);

 cset_X_iter_t       cset_X_end(cset_X* self);

 void                cset_X_next(cset_X_iter_t* it);

-cset_X_mapped_t*    cset_X_itval(cset_X_iter_t it);

+cset_X_value_t*     cset_X_itval(cset_X_iter_t it);

 

 cset_bucket_t       cset_X_bucket(const cset_X* self, const cset_X_rawkey_t* rkeyPtr);

 

diff --git a/examples/ex_gaussian.c b/examples/ex_gaussian.c
index 3ef20e7d..3ed30cf2 100644
--- a/examples/ex_gaussian.c
+++ b/examples/ex_gaussian.c
@@ -46,8 +46,7 @@ int main()
     c_foreach (i, cvec_e, vhist) {

         size_t n = (size_t) (i.val->second * StdDev * Scale * 2.5 / N);

         if (n > 0) {

-            // bar string: take ownership in new str after freeing current.

-            cstr_take(&bar, cstr_with_size(n, '*'));

+            cstr_resize(&bar, n, '*');

             printf("%4d %s\n", i.val->first, bar.str);

         }

     }

diff --git a/stc/carray.h b/stc/carray.h
index fa96da99..44df27a8 100644
--- a/stc/carray.h
+++ b/stc/carray.h
@@ -29,17 +29,17 @@
 /*

  Multi-dimensional generic array allocated as one block of heap-memory.

  // demo:

-#include <stdio.h.h>

-#include <stc/carray.h>

+#include <stdio.h>

+#include "stc/carray.h"

 using_carray(f, float);

 

 int main()

 {

-    carray3f a3 = carray3f_init(30, 20, 10, 0.f);

-    *carray3f_at(a3, 5, 4, 3) = 10.2f;         // a3[5][4][3]

-    carray2f a2 = carray3f_at1(a3, 5);         // sub-array reference: a2 = a3[5]

-    printf("%g\n", *carray2f_at(a2, 4, 3));    // lookup a2[4][3] (=10.2f)

-    printf("%g\n", *carray3f_at(a3, 5, 4, 3)); // same data location, via a3 array.

+    carray3f a3 = carray3f_init(30, 20, 10, 0.0f);

+    *carray3f_at(&a3, 5, 4, 3) = 10.2f;         // a3[5][4][3]

+    carray2f a2 = carray3f_at1(&a3, 5);         // sub-array reference: a2 = a3[5]

+    printf("%g\n", *carray2f_at(&a2, 4, 3));    // lookup a2[4][3] (=10.2f)

+    printf("%g\n", *carray3f_at(&a3, 5, 4, 3)); // same data location, via a3 array.

 

     carray2f_del(&a2); // does nothing, since it is a sub-array.

     carray3f_del(&a3); // destroy a3, invalidates a2.