Final cspan API changes: cspan_XtoY() => cspan_atX(). Docs updated.

1 files changed, 15 insertions, 17 deletions

diff --git a/docs/cspan_api.md b/docs/cspan_api.md
index b9879a6f..15125e78 100644
--- a/docs/cspan_api.md
+++ b/docs/cspan_api.md
@@ -3,7 +3,8 @@
 
 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.
+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
 
@@ -17,8 +18,8 @@ using_cspan3(S, ValueType);                 // define span types S1, S2, S3 with
 using_cspan4(S, ValueType);                 // define span types S1.., S4 with Ranks 1, 2, 3, 4.
 ```
 ## Methods
-Note that `cspan_make()`, `cmake_from*()`, `cspan_sliceX()` `and cspan_XtoY()` require a (safe) cast to its span-type
-on assignment, but not on initialization of a span variable.
+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.
 ```c
 SpanType        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
@@ -30,20 +31,17 @@ void            cspan_resize(SpanType* self, size_t xdim, ...);             // c
 
 size_t          cspan_size(SpanType spn);                                   // return number of elements
 unsigned        cspan_rank(SpanType spn);                                   // return number of dimensions
-ValueType*      cspan_at(SpanType spn, size_t x, ...);                      // access element
 size_t          cspan_index(SpanType spn, size_t x, ...);                   // index of element
 
-SpanType1       cspan_subspan1(SpanType1 spn, size_t offset, size_t count); // get a slice of a 1D cspan
-SpanType2       cspan_subspan2(SpanType2 spn, size_t offset, size_t count); // get a slice of a 2D cspan
-SpanType3       cspan_subspan3(SpanType3 spn, size_t offset, size_t count); // get a slice of a 3D cspan
-SpanType4       cspan_subspan4(SpanType4 spn, size_t offset, size_t count); // get a slice of a 4D cspan
+ValueType*      cspan_at(SpanType spn, size_t x, ...);                      // return value pointer from a 1D, 2D, 3D or 4D cspan
+SpanType1       cspan_at2(SpanType2 spn, size_t x);                         // return a 1D subarray cspan
+SpanType        cspan_at3(SpanType3 spn, size_t x, ...);                    // return a 2D or 1D subarray cspan
+SpanType        cspan_at4(SpanType4 spn, size_t x, ...);                    // return a 3D, 2D or 1D subarray cspan
 
-SpanType1       cspan_2to1(SpanType2 spn, size_t x);                        // return a 1D subspan
-SpanType1       cspan_3to1(SpanType3 spn, size_t x, size_t y);              // return a 1D subspan
-SpanType2       cspan_3to2(SpanType3 spn, size_t x);                        // return a 2D subspan
-SpanType1       cspan_4to1(SpanType4 spn, size_t x, size_t y, size_t z);    // return a 1D subspan
-SpanType2       cspan_4to2(SpanType4 spn, size_t x, size_t y);              // return a 2D subspan
-SpanType3       cspan_4to3(SpanType4 spn, size_t x);                        // return a 3D subspan
+SpanType1       cspan_subspan1(SpanType1 spn, size_t offset, size_t count); // return a slice of a 1D cspan
+SpanType2       cspan_subspan2(SpanType2 spn, size_t offset, size_t count); // return a slice of a 2D cspan
+SpanType3       cspan_subspan3(SpanType3 spn, size_t offset, size_t count); // return a slice of a 3D cspan
+SpanType4       cspan_subspan4(SpanType4 spn, size_t offset, size_t count); // return a slice of a 4D cspan
 
 SpanType_iter   SpanType_begin(const SpanType* self);
 SpanType_iter   SpanType_end(const SpanType* self);
@@ -73,17 +71,17 @@ int main()
         c_FORRANGE (i, xd*yd*zd)
             cstack_float_push(&vec, i);
 
-        // define arr[xd][yd][zd] cspan
+        // 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));
 
-        FS1 span1 = cspan_3to1(span3, 4, 3);
+        FS1 span1 = cspan_at3(span3, 4, 3);
         printf("\niterate span1: ");
         c_FOREACH (i, FS1, span1)
             printf("%g ", *i.ref);
 
-        FS2 span2 = cspan_3to2(span3, 4);
+        FS2 span2 = cspan_at3(span3, 4);
         printf("\niterate span2: ");
         c_FOREACH (i, FS2, span2)
             printf("%g ", *i.ref);