From 64bffee9fffc4cb68e06b395b42275804ccce9b2 Mon Sep 17 00:00:00 2001 From: Tyge Løvset Date: Wed, 2 Dec 2020 14:24:15 +0100 Subject: Added carray docs. --- README.md | 2 +- docs/carray_api.md | 100 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/crandom_api.md | 3 +- docs/cset_api.md | 2 +- examples/ex_gaussian.c | 3 +- stc/carray.h | 14 +++---- 6 files changed, 111 insertions(+), 13 deletions(-) create mode 100644 docs/carray_api.md 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 +#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 -#include +#include +#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. -- cgit v1.2.3