diff options
Diffstat (limited to 'docs/cspan_api.md')
| -rw-r--r-- | docs/cspan_api.md | 255 |
1 files changed, 167 insertions, 88 deletions
diff --git a/docs/cspan_api.md b/docs/cspan_api.md index 2865a1a5..d0463b0a 100644 --- a/docs/cspan_api.md +++ b/docs/cspan_api.md @@ -1,120 +1,199 @@ # 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++ classes [std::span](https://en.cppreference.com/w/cpp/container/span) and +The **cspan** is templated non-owning multi-dimensional view of an array. See the c++ classes +[std::span](https://en.cppreference.com/w/cpp/container/span) and [std::mdspan](https://en.cppreference.com/w/cpp/container/mdspan) for 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) +using_cspan(SpanType, ValueType); // define a 1-d SpanType with ValueType elements. +using_cspan(SpanTypeN, ValueType, Rank); // define multi-dimensional span with Rank. + // Rank is number of dimensions (max 5) // Shorthands: -using_cspan2(S, ValueType); // define span types S, S2 with ranks 1, 2. -using_cspan3(S, ValueType); // define span types S, S2, S3 with ranks 1, 2, 3. -using_cspan4(S, ValueType); // define span types S, S2, S3, S4 with ranks 1, 2, 3, 4. +using_cspan2(S, ValueType); // define span types S, S2 with ranks 1, 2. +using_cspan3(S, ValueType); // define span types S, S2, S3 with ranks 1, 2, 3. +using_cspan4(S, ValueType); // define span types S, S2, S3, S4 with ranks 1, 2, 3, 4. ``` ## Methods -Note that `cspan_make()`, `cmake_from*()`, `cspan_atN()`, `and cspan_subspanN()` require a (safe) cast to its span-type -on assignment, but not on initialization of a span variable. All functions are type-safe, and arguments are side-effect safe, except for SpanType arg. which must not have side-effects. +All functions are type-safe, and index arguments are side-effect safe. ```c -SpanType{N} cspan_make(ValueType* data, size_t xdim, ...); // make N-dimensional cspan -SpanType cspan_from(STCContainer* cnt); // create a 1D cspan from a compatible STC container -SpanType cspan_from_array(ValueType array[]); // create a 1D cspan from a C array -SpanType cspan_from_list(T ValueType, {val0, val1, ...}); // create a 1D cspan from an initializer list -SpanType& cspan_literal(T SpanType, {val0, val1, ...}); // create a 1D cspan compound literal from init list - -void cspan_resize(SpanType{N}* self, size_t xdim, ...); // change the extent of each dimension +SpanTypeN cspan_md(ValueType* data, intptr_t xdim, ...); // create a multi-dimensional cspan +SpanType cspan_make(T SpanType, {v1, v2, ...}); // make a 1d-dimensional cspan from values +SpanType cspan_from(STCContainer* cnt); // create a 1d cspan from a compatible STC container +SpanType cspan_from_array(ValueType array[]); // create a 1d cspan from a C array + +intptr_t cspan_size(const SpanTypeN* self); // return number of elements +unsigned cspan_rank(const SpanTypeN* self); // return number of dimensions +intptr_t cspan_index(const SpanTypeN* self, intptr_t x, ..); // index of element + +ValueType* cspan_at(const SpanTypeN* self, intptr_t x, ...); // at(): num of args specifies rank of input span. +ValueType* cspan_front(const SpanTypeN* self); +ValueType* cspan_back(const SpanTypeN* self); -size_t cspan_size(const SpanType{N}* self); // return number of elements -unsigned cspan_rank(const SpanType{N}* self); // return number of dimensions -size_t cspan_index(const SpanType{N}* self, size_t x, ...); // index of element + // general index slicing to create a subspan. + // {x} reduces rank. {x,c_END} slice to end. {c_ALL} take the full extent. +SpanTypeN cspan_slice(T SpanTypeN, const SpanTypeM* parent, {x0,x1}, {y0,y1}, ...); -ValueType* cspan_at(SpanType{N}* self, size_t x, ...); // at(): num of args decides input SpanType{N}. -SpanType cspan_at2(SpanType2* self, size_t x); // return a 1D subarray cspan. -SpanType{N} cspan_at3(SpanType3* self, size_t x, ...); // atN(): N decides input SpanType, -SpanType{N} cspan_at4(SpanType4* self, size_t x, ...); // and num of args decides returned SpanType{N}. - -SpanType cspan_subspan(const SpanType* self, size_t offset, size_t count); // return a slice of a 1D cspan -SpanType2 cspan_subspan2(const SpanType2 self, size_t offset, size_t count); // return a slice of a 2D cspan -SpanType3 cspan_subspan3(const SpanType3 self, size_t offset, size_t count); // return a slice of a 3D cspan -SpanType4 cspan_subspan4(const SpanType4 self, size_t offset, size_t count); // return a slice of a 4D cspan - -SpanType{N}_iter SpanType_begin(const SpanType{N}* self); -SpanType{N}_iter SpanType_end(const SpanType{N}* self); -void SpanType_next(SpanType{N}_iter* it); + // create a subspan of lower rank. Like e.g. cspan_slice(Span2, &ms4, {x}, {y}, {c_ALL}, {c_ALL}); +SpanType cspan_submd2(const SpanType2* self, intptr_t x); // return a 1d subspan from a 2d span. +SpanTypeN cspan_submd3(const SpanType3* self, intptr_t x, ...); // return a 1d or 2d subspan from a 3d span. +SpanTypeN cspan_submd4(const SpanType4* self, intptr_t x, ...); // number of args determines rank of output span. + + // create a subspan of same rank. Like e.g. cspan_slice(Span3, &ms3, {off,off+count}, {c_ALL}, {c_ALL}); +SpanType cspan_subspan(const SpanType* self, intptr_t offset, intptr_t count); +SpanType2 cspan_subspan2(const SpanType2 self, intptr_t offset, intptr_t count); +SpanType3 cspan_subspan3(const SpanType3 self, intptr_t offset, intptr_t count); + +SpanTypeN_iter SpanType_begin(const SpanTypeN* self); +SpanTypeN_iter SpanType_end(const SpanTypeN* self); +void SpanType_next(SpanTypeN_iter* it); ``` ## Types -| Type name | Type definition | Used to represent... | -|:--------------------|:-----------------------------------------------|:---------------------| -| SpanType{N} | `struct { ValueType *data; uint32_t dim[N]; }` | SpanType with rank N | -| SpanType{N}`_value` | `ValueType` | The ValueType | -| SpanType{N}`_iter` | `struct { ValueType *ref; ... }` | Iterator type | +| Type name | Type definition | Used to represent... | +|:------------------|:-----------------------------------------------|:---------------------| +| SpanTypeN | `struct { ValueType *data; uint32_t shape[N]; }` | SpanType with rank N | +| SpanTypeN`_value` | `ValueType` | The ValueType | +| `c_ALL` | `0,-1` | Full extent | +| `c_END` | `-1` | End of extent | + +## Example 1 + +The *cspan_slice()* function is similar to pythons numpy multi-dimensional arrays slicing, e.g.: +```py +import numpy as np + +if __name__ == '__main__': + ms3 = np.array((1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24), int) + + ms3 = np.reshape(ms3, (2, 3, 4)) + ss3 = ms3[:, 1:3, 2:] + ss2 = ss3[1] + + for i in range(ss2.shape[0]): + for j in range(ss2.shape[1]): + print(" {}".format(ss2[i, j]), end='') + print('') -## Example + for i in ss2.flat: + print(" {}".format(i), end='') + +# 19 20 23 24 +# 19 20 23 24 +``` +... can be done in C with cspan: ```c -#include <stdio.h> -#define i_val float -#include <stc/cstack.h> +#include <c11/fmt.h> +#include <stc/cspan.h> +using_cspan3(myspan, int); // define myspan, myspan2, myspan3. + +int main() { + int arr[] = {1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24}; + myspan3 ms3 = cspan_md(arr, 2, 3, 4); + myspan3 ss3 = cspan_slice(myspan3, &ms3, {c_ALL}, {1,3}, {2,c_END}); + myspan2 ss2 = cspan_submd3(&ss3, 1); + + c_FORRANGE (i, ss2.shape[0]) + c_FORRANGE (j, ss2.shape[1]) + fmt_print(" {}", *cspan_at(&ss2, i, j)); + puts(""); + + c_FOREACH (i, myspan2, ss2) + fmt_print(" {}", *i.ref); +} +``` +... and (almost) in C++23: +```c++ +#include <print> +#include <mdspan> +#include <tuple> + +int main() { + int arr[] = {1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24}; + + std::mdspan ms3(arr, 2, 3, 4); + auto ss3 = std::submdspan(ms3, std::full_extent, std::tuple{1,3}, std::tuple{2,4}); + auto ss2 = std::submdspan(ss3, 1, std::full_extent, std::full_extent); + + for (std::size_t i = 0; i < ss2.extent(0); ++i) + for (std::size_t j = 0; j < ss2.extent(1); ++j) + std::print(" {}", ss2[i, j]); + std::println(); + + // std::mdspan can't be iterated as a flat container! +} +``` +## Example 2 +Slicing cspan without and with reducing the rank (like numpy array slicing): +```c +#include <c11/fmt.h> #include <stc/cspan.h> -using_cspan3(FS, float); // Shorthand to define span types FS, FS2, and FS3. + +using_cspan3(Span, int); // Shorthand to define Span, Span2, and Span3 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 "span3[xd][yd][zd]" - 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)); - - FS span1 = cspan_at3(&span3, 4, 3); - printf("\niterate span1: "); - c_FOREACH (i, FS, span1) - printf("%g ", *i.ref); - - FS2 span2 = cspan_at3(&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(" %2g", *cspan_at(&span3, i, j, k)); - printf(" |"); - } - puts(""); + // c_make() can create any STC container/span from an initializer list: + Span span = c_make(Span, {1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, + 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24}); + // create a 3d cspan: + Span3 span3 = cspan_md(span.data, 2, 4, 3); + + // reduce rank: (i.e. span3[1]) + Span2 span2 = cspan_submd3(&span3, 1); + + puts("\niterate span2 flat:"); + c_FOREACH (i, Span2, span2) + fmt_print(" {}", *i.ref); + puts(""); + + // slice without reducing rank: + Span3 ss3 = cspan_slice(Span3, &span3, {c_ALL}, {3,4}, {c_ALL}); + + puts("\niterate ss3 by dimensions:"); + c_FORRANGE (i, ss3.shape[0]) { + c_FORRANGE (j, ss3.shape[1]) { + c_FORRANGE (k, ss3.shape[2]) + fmt_print(" {:2}", *cspan_at(&ss3, i, j, k)); + fmt_print(" |"); } - - printf("%g\n", *cspan_at(&span3, 4, 3, 2)); - printf("%g\n", *cspan_at(&span2, 3, 2)); - printf("%g\n", *cspan_at(&span1, 2)); + puts(""); + } + // slice and reduce rank: + Span2 ss2 = cspan_slice(Span2, &span3, {c_ALL}, {3}, {c_ALL}); + + puts("\niterate ss2 by dimensions:"); + c_FORRANGE (i, ss2.shape[0]) { + c_FORRANGE (j, ss2.shape[1]) { + fmt_print(" {:2}", *cspan_at(&ss2, i, j)); + fmt_print(" |"); + } + puts(""); } + + puts("\niterate ss2 flat:"); + c_FOREACH (i, Span2, ss2) + fmt_print(" {:2}", *i.ref); + puts(""); } ``` 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 +iterate span2 flat: + 13 14 15 16 17 18 19 20 21 22 23 24 + +iterate ss3 by dimensions: + 10 11 12 | + 22 23 24 | + +iterate ss2 by dimensions: + 10 | 11 | 12 | + 22 | 23 | 24 | + +iterate ss2 flat: + 10 11 12 22 23 24 ``` |