# STC [cspan](../include/stc/cspan.h): Multi-dimensional Array View ![Array](pics/array.jpg) The **cspan** is templated non-owning *single* and *multi-dimensional* view of an array. It has similarities with Python's numpy array slicing and C++ [std::span](https://en.cppreference.com/w/cpp/container/span) / [std::mdspan](https://en.cppreference.com/w/cpp/container/mdspan), and others. ## Header file and declaration **cspan** types are defined by the *using_cspan()* macro after the header is included. This is different from other containers where template parameters are defined prior to including each container. This works well mainly because cspan is non-owning. ```c #include 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 the literal number of dimensions // 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. ``` ## Methods All functions are type-safe. NOTE: the span argument itself is generally **not** side-effect safe - it may be expanded multiple times. However, all index arguments are safe, e.g. `cspan_at(&ms3, i++, j++, k++)` is safe, but `cspan_at(&spans[n++], i, j)` is an error! If the number of arguments does not match the span rank, a compile error is issued. Runtime bounds checks are enabled by default (define `STC_NDEBUG` or `NDEBUG` to disable). ```c SpanType cspan_init(TYPE SpanType, {v1, v2, ...}); // make a 1-d cspan from values SpanType cspan_from(STCContainer* cnt); // make a 1-d cspan from a cvec, cstack, cpque (heap) SpanType cspan_from_n(ValueType* ptr, intptr_t n); // make a 1-d cspan from a pointer and length SpanType cspan_from_array(ValueType array[]); // make a 1-d cspan from a C array intptr_t cspan_size(const SpanTypeN* self); // return number of elements intptr_t cspan_rank(const SpanTypeN* self); // dimensions; compile time constant intptr_t cspan_index(const SpanTypeN* self, intptr_t x, ..); // index of element ValueType* cspan_at(const SpanTypeN* self, intptr_t x, ...); // #args must match input span rank ValueType* cspan_front(const SpanTypeN* self); ValueType* cspan_back(const SpanTypeN* self); SpanTypeN_iter SpanType_begin(const SpanTypeN* self); SpanTypeN_iter SpanType_end(const SpanTypeN* self); void SpanType_next(SpanTypeN_iter* it); // make a multi-dim cspan SpanTypeN cspan_md(ValueType* data, d1, d2, ...); // row-major SpanTypeN cspan_md_layout(cspan_layout layout, ValueType* data, d1, d2, ...); // transpose a md span. Inverses layout and axes only. void cspan_transpose(const SpanTypeN* self); cspan_layout cspan_get_layout(const SpanTypeN* self); bool cspan_is_rowmajor(const SpanTypeN* self); bool cspan_is_colmajor(const SpanTypeN* self); // create a subspan of input span rank. Like e.g. cspan_slice(Span3, &ms3, {off,off+count}, {c_ALL}, {c_ALL}); SpanType cspan_subspan(const SpanType* span, intptr_t offset, intptr_t count); SpanType2 cspan_subspan2(const SpanType2* span, intptr_t offset, intptr_t count); SpanType3 cspan_subspan3(const SpanType3* span, intptr_t offset, intptr_t count); // create a sub md span of lower rank. Like e.g. cspan_slice(Span2, &ms4, {x}, {y}, {c_ALL}, {c_ALL}); OutSpan cspan_submd2(const SpanType2* parent, intptr_t x); // return a 1d subspan from a 2d span. OutSpanN cspan_submd3(const SpanType3* parent, intptr_t x, ...); // return a 1d or 2d subspan from a 3d span. OutSpanN cspan_submd4(const SpanType4* parent, intptr_t x, ...); // number of args decides rank of output span. // general slicing of an md span. // {i}: reduce rank. {i,c_END}: slice to end. {c_ALL}: use full extent. OutSpanN cspan_slice(TYPE OutSpanN, const SpanTypeM* parent, {x0,x1}, {y0,y1}.., {N0,N1}); ``` ## Types | Type name | Type definition / usage | Used to represent... | |:------------------|:----------------------------------------------------|:---------------------| | SpanTypeN | `struct { ValueType *data; uint32_t shape[N]; .. }` | SpanType with rank N | | SpanTypeN`_value` | `ValueType` | The ValueType | | `c_ALL` | `cspan_slice(&md, {1,3}, {c_ALL})` | Full extent | | `c_END` | `cspan_slice(&md, {1,c_END}, {2,c_END})` | End of extent | | `cspan_layout` | `enum { c_ROWMAJOR, c_COLMAJOR }` | Multi-dim layout | ## Example 1 [ [Run this code](https://godbolt.org/z/Tv9d1T3TM) ] ```c #include #define i_key int #include #define i_key int #include #include using_cspan(intspan, int); void printMe(intspan container) { printf("%d:", (int)cspan_size(&container)); c_foreach (e, intspan, container) printf(" %d", *e.ref); puts(""); } int main(void) { printMe( c_init(intspan, {1, 2, 3, 4}) ); int arr[] = {1, 2, 3, 4, 5}; printMe( (intspan)cspan_from_array(arr) ); cvec_int vec = c_init(cvec_int, {1, 2, 3, 4, 5, 6}); printMe( (intspan)cspan_from(&vec) ); cstack_int stk = c_init(cstack_int, {1, 2, 3, 4, 5, 6, 7}); printMe( (intspan)cspan_from(&stk) ); intspan spn = c_init(intspan, {1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12}); printMe( (intspan)cspan_subspan(&spn, 2, 8) ); // cleanup cvec_int_drop(&vec); cstack_int_drop(&stk); } ``` ## Example 2 Multi-dimension slicing (first in python): ```py import numpy as np def print_span(s2): for i in range(s2.shape[0]): for j in range(s2.shape[1]): print(" {}".format(s2[i, j]), end='') print('') print('') 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), order='C') ss3 = ms3[:, 0:3, 2:] a = ss3[1] b = np.transpose(a) print_span(ms3[1]) print_span(a) print_span(b) for i in a.flat: print(" {}".format(i), end='') print('') # prints row-wise for i in b.flat: print(" {}".format(i), end='') ''' 13 14 15 16 17 18 19 20 21 22 23 24 15 16 19 20 23 24 15 19 23 16 20 24 15 16 19 20 23 24 15 19 23 16 20 24 ''' ``` ... in C with STC cspan: [ [Run this code](https://godbolt.org/z/e3PeWe7e9) ] ```c #include #include using_cspan3(myspan, int); // define myspan, myspan2, myspan3. void print_span(myspan2 ms) { for (int i=0; i < ms.shape[0]; ++i) { for (int j=0; j < ms.shape[1]; ++j) printf(" %2d", *cspan_at(&ms, i, j)); puts(""); } puts(""); } int main(void) { 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); // row-major layout myspan3 ss3 = cspan_slice(myspan3, &ms3, {c_ALL}, {0,3}, {2,c_END}); myspan2 a = cspan_submd3(&ss3, 1); myspan2 b = a; cspan_transpose(&b); print_span((myspan2)cspan_submd3(&ms3, 1)); print_span(a); print_span(b); c_foreach (i, myspan2, a) printf(" %d", *i.ref); puts(""); // prints in storage order, same as a. c_foreach (i, myspan2, b) printf(" %d", *i.ref); } ``` ## Example 3 Slicing cspan without and with reducing the rank: [ [Run this code](https://godbolt.org/z/jjzcvPPxW) ] ```c #include #include #define i_key int #include #define i_key int #include using_cspan3(Span, int); // Shorthand to define Span, Span2, and Span3 int main(void) { Span span = c_init(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}); Span3 span3 = cspan_md(span.data, 2, 4, 3); // slice without reducing rank: Span3 ss3 = cspan_slice(Span3, &span3, {c_ALL}, {3,4}, {c_ALL}); for (int i=0; i < ss3.shape[0]; ++i) { for (int j=0; j < ss3.shape[1]; ++j) { for (int k=0; k < ss3.shape[2]; ++k) printf(" %2d", *cspan_at(&ss3, i, j, k)); puts(""); } puts(""); } // slice and reduce rank: Span2 ss2 = cspan_slice(Span2, &span3, {c_ALL}, {3}, {c_ALL}); for (int i=0; i < ss2.shape[0]; ++i) { for (int j=0; j < ss2.shape[1]; ++j) printf(" %2d", *cspan_at(&ss2, i, j)); puts(""); } } ```