diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/carray_api.md | 123 | ||||
| -rw-r--r-- | docs/ccommon_api.md | 2 | ||||
| -rw-r--r-- | docs/cspan_api.md | 120 |
3 files changed, 121 insertions, 124 deletions
diff --git a/docs/carray_api.md b/docs/carray_api.md deleted file mode 100644 index 803a1610..00000000 --- a/docs/carray_api.md +++ /dev/null @@ -1,123 +0,0 @@ -# STC [carr2, carr3](../include/stc/carray.h): Dynamic Multi-dimensional Arrays - - -The **carr2** and **carr3** are templated 2D and 3D dynamic arrays. They are allocated on the heap as a single -contiguous block of memory. The arrays can be indexed like regular constant size multi-dimensional arrays in C. - -See the c++ class [boost::multi_array](https://www.boost.org/doc/libs/release/libs/multi_array) for similar functionality. - -## Header file and declaration - -```c -#define i_type // full typename of the container -#define i_val // value: REQUIRED -#define i_valdrop // destroy value func - defaults to empty destruct -#define i_valclone // REQUIRED IF valdrop is defined. -#include <stc/carr2.h> // or <stc/carr3.h> -``` -`X` should be replaced by the value of `i_tag` in all of the following documentation. - -## Methods - -carr2_X: -```c -carr2_X carr2_X_with_size(size_t xdim, size_t ydim, i_val val); -carr2_X carr2_X_with_data(size_t xdim, size_t ydim, i_val* array); -carr2_X carr2_X_new_uninit(size_t xdim, size_t ydim); -carr2_X carr2_X_clone(carr2_X arr); -void carr2_X_copy(carr2_X* self, const carr2_X* other); -i_val* carr2_X_release(carr2_X* self); // release storage (not freed) -void carr2_X_drop(carr2_X* self); - -size_t carr2_X_size(const carr2_X* self); -i_val* carr2_X_data(carr2_X* self); // access storage data -const i_val* carr2_X_at(const carr2_X* self, size_t x, size_t y); -size_t carr2_X_idx(const carr2_X* self, size_t x, size_t y); - -carr2_X_iter carr2_X_begin(const carr2_X* self); -carr2_X_iter carr2_X_end(const carr2_X* self); -void carr2_X_next(carr2_X_iter* it); -``` -The **carr2** elements can be accessed with `arr.data[x][y];` or with `carr2_i_at(&arr, x, y)`. - -carr3: -```c -carr3_X carr3_X_with_size(size_t xdim, size_t ydim, size_t zdim, i_val val); -carr3_X carr3_X_with_data(size_t xdim, size_t ydim, size_t zdim, i_val* array); -carr3_X carr3_X_new_uninit(size_t xdim, size_t ydim, size_t zdim); -carr3_X carr3_X_clone(carr3_X arr); -void carr3_X_copy(carr3_X* self, const carr3_X* other); -i_val* carr3_X_release(carr3_X* self); // release storage (not freed) -void carr3_X_drop(carr3_X* self); - -size_t carr3_X_size(const carr3_X* self); -i_val* carr3_X_data(carr3_X* self); // storage data -const i_val* carr3_X_at(const carr3_X* self, size_t x, size_t y, size_t z); -size_t carr3_X_idx(const carr3_X* self, size_t x, size_t y, size_t z); - -carr3_X_iter carr3_X_begin(const carr3_X* self); -carr3_X_iter carr3_X_end(const carr3_X* self); -void carr3_X_next(carr3_X_iter* it); -``` -The **carr3** elements can be accessed with `arr.data[x][y][z];` or with `carr3_i_at(&arr, x, y, z)`. - -## Types - -| Type name | Type definition | Used to represent... | -|:------------------|:-----------------------------------------------------|:---------------------| -| `carr2_X` | `struct { i_val **data; size_t xdim, ydim; }` | The array 2D type | -| `carr2_X_value` | `i_val` | The value type | -| `carr2_X_iter` | `struct { i_val *ref; }` | Iterator type | -| | | | -| `carr3_X` | `struct { i_val ***data; size_t xdim, ydim, zdim; }` | The array 3D type | -| `carr3_X_value` | `i_val` | The value type | -| `carr3_X_iter` | `struct { i_val *ref; }` | Iterator type | - -## Example -```c -#include <stdio.h> - -#define i_val uint32_t -#define i_tag i -#include <stc/carr2.h> - -#define i_val float -#define i_tag f -#include <stc/carr3.h> - -int main() -{ - // Ex1 - int xd = 30, yd = 20, zd = 10; - // define arr3[30][20][10], initialized with zeros. - c_WITH (carr3_f arr3 = carr3_f_with_size(xd, yd, zd, 0.0f), carr3_f_drop(&arr3)) { - arr3.data[5][4][3] = 3.14f; - - float *arr1 = arr3.data[5][4]; - float **arr2 = arr3.data[5]; - - printf("%f\n", arr1[3]); // 3.14 - printf("%f\n", arr2[4][3]); // 3.14 - printf("%f\n", arr3.data[5][4][3]); // 3.14 - } - - // Ex2 - int w = 256, h = 128; - c_WITH (carr2_i image = carr2_i_new_uninit(w, h), carr2_i_drop(&image)) { - int n = 0; - c_FOREACH (i, carr2_i, image) { - uint32_t t = n++ % 256; - *i.ref = t | t << 8 | t << 16 | 255; - } - - for (int y = 0; y < image.ydim; ++y) - image.data[y][y] = 0xffffffff; - } -} -``` -Output: -``` -3.140000 -3.140000 -3.140000 -``` diff --git a/docs/ccommon_api.md b/docs/ccommon_api.md index e17e98ca..b610ff04 100644 --- a/docs/ccommon_api.md +++ b/docs/ccommon_api.md @@ -282,7 +282,7 @@ c_FORFILTER (i, crange, r1 // 2. The 11 first primes: printf("2"); -c_FORFILTER (i, crange, crange_object(3, INT64_MAX, 2) +c_FORFILTER (i, crange, crange_literal(3, INT64_MAX, 2) , isPrime(*i.ref) , c_FLT_TAKE(10)) printf(" %lld", *i.ref); diff --git a/docs/cspan_api.md b/docs/cspan_api.md new file mode 100644 index 00000000..7af96c06 --- /dev/null +++ b/docs/cspan_api.md @@ -0,0 +1,120 @@ +# STC [cspan](../include/stc/cspan.h): Multi-dimensional Array View + + +The **cspan** is templated non-owning multi-dimensional view of an array. + +See the c++ class [std::mdspan](https://en.cppreference.com/w/cpp/container/mdspan) for a similar functionality. + +## Header file and declaration + +```c +#include <stc/cspan.h> +using_cspan(SpanType, ValueType, Rank); // define SpanType with ValueType elements. + // Rank is number of dimensions (max 4 atm.) +// Shorthands: +using_cspan2(S, ValueType); // define span types S1, S2 with Ranks 1, 2. +using_cspan3(S, ValueType); // define span types S1, S2, S3 with Ranks 1, 2, 3. +using_cspan4(S, ValueType); // define span types S1.., S4 with Ranks 1, 2, 3, 4. +``` +## Methods + +```c +SpanType& cspan_literal(SpanType, {val1, val2, ...}); // create a 1D cspan compound literal +SpanType cspan_from_array(ValueType array[]); // create a 1D cspan from an array. +SpanType cspan_from(STCContainer* cnt); // create a 1D cspan from a STC container; + // cstack, cvec, cdeq, cqueue, or cpque +SpanType cspan_make(ValueType* data, size_t xdim, ...); // make N-dimensional cspan +void cspan_reshape(const SpanType* self, size_t x, ...); // change the extent of each dimension + +size_t cspan_size(const SpanType* self); // return number of elements +unsigned cspan_rank(const SpanType* self); // return number of dimensions +ValueType* cspan_at(SpanType* self, size_t x, ...); // access element +size_t cspan_index(const SpanType* self, size_t x, ...); // index of element + +SpanType cspan_slice1(SpanType1* self, size_t x0, size_t with); // get a slice of a 1D cspan +SpanType cspan_slice2(SpanType2* self, size_t x0, size_t with); // get a slice of a 2D cspan +SpanType cspan_slice3(SpanType3* self, size_t x0, size_t with); // get a slice of a 3D cspan +SpanType cspan_slice4(SpanType4* self, size_t x0, size_t with); // get a slice of a 4D cspan + +SpanType3 cspan_4to3(SpanType4* self, size_t x); // return a 3D subspan +SpanType2 cspan_4to2(SpanType4* self, size_t x, size_t y); // return a 2D subspan +SpanType1 cspan_4to1(SpanType4* self, size_t x, size_t y, size_t z); // return a 1D subspan +SpanType2 cspan_3to2(SpanType3* self, size_t x); // return a 2D subspan +SpanType1 cspan_3to1(SpanType3* self, size_t x, size_t y); // return a 1D subspan +SpanType1 cspan_2to1(SpanType2* self, size_t x); // return a 1D subspan + +SpanType_iter cspan_begin(const SpanType* self); +SpanTyåe_iter cspan_end(const SpanType* self); +void cspan_next(SpanType_iter* it); +``` +## Types + +| Type name | Type definition | Used to represent... | +|:-----------------|:-----------------------------------------------------|:---------------------| +| SpanType | `struct { ValueType *data; uint32_t dim[RANK]; }` | The SpanType | +| SpanType`_value` | `ValueType` | The ValueType | +| SpanType`_iter` | `struct { ValueType *ref; ... }` | Iterator type | + +## Example +```c +#include <stdio.h> +#define i_val float +#include <stc/cstack.h> + +#include <stc/cspan.h> +using_cspan3(FS, float); // define spans FS1, FS2, and FS3. + +int main() +{ + int xd = 6, yd = 4, zd = 3; + c_AUTO (cstack_float, vec) { + c_FORRANGE (i, xd*yd*zd) + cstack_float_push(&vec, i); + + // define arr[xd][yd][zd] cspan + FS3 span3 = cspan_make(vec.data, xd, yd, zd); + *cspan_at(&span3, 4, 3, 2) = 3.14f; + printf("index: %d", (int)cspan_index(&span3, 4, 3, 2)); + + FS1 span1 = cspan_3to1(&span3, 4, 3); + printf("\niterate span1: "); + c_FOREACH (i, FS1, span1) + printf("%g ", *i.ref); + + FS2 span2 = cspan_3to2(&span3, 4); + printf("\niterate span2: "); + c_FOREACH (i, FS2, span2) + printf("%g ", *i.ref); + + puts("\niterate span3 by dimensions:"); + c_FORRANGE (i, span3.dim[0]) { + c_FORRANGE (j, span3.dim[1]) { + c_FORRANGE (k, span3.dim[2]) + printf(" %g", *cspan_at(&span3, i, j, k)); + printf(" |"); + } + puts(""); + } + + printf("%g\n", *cspan_at(&span3, 4, 3, 2)); + printf("%g\n", *cspan_at(&span2, 3, 2)); + printf("%g\n", *cspan_at(&span1, 2)); + } +} +``` +Output: +``` +index: 59 +iterate span1: 57 58 3.14 +iterate span2: 48 49 50 51 52 53 54 55 56 57 58 3.14 +iterate span3 by dimensions: + 0 1 2 | 3 4 5 | 6 7 8 | 9 10 11 | + 12 13 14 | 15 16 17 | 18 19 20 | 21 22 23 | + 24 25 26 | 27 28 29 | 30 31 32 | 33 34 35 | + 36 37 38 | 39 40 41 | 42 43 44 | 45 46 47 | + 48 49 50 | 51 52 53 | 54 55 56 | 57 58 3.14 | + 60 61 62 | 63 64 65 | 66 67 68 | 69 70 71 | +3.14 +3.14 +3.14 +``` |