More cspan docs updates.

3 files changed, 66 insertions, 60 deletions

diff --git a/README.md b/README.md
index 63308051..a9d177e1 100644
--- a/README.md
+++ b/README.md
@@ -3,21 +3,22 @@
 STC - Smart Template Containers for C
 =====================================
 
-News: Version 4.1 RC (Feb 2023)
+News: Version 4.1 RC2 (Feb 2023)
 ------------------------------------------------
 Major changes:
 - Signed sizes and indices for all containers (no more mixing unsigned/signed bugs).
-- A new exciting [**cspan**](docs/cspan_api.md) single/multi-dimensional array view.
+- A new exciting [**cspan**](docs/cspan_api.md) single/multi-dimensional array view (with numpy-like slicing).
 - Updates on cregex with several new unicode character classes.
 - Uppercase flow-control macros (ccommon.h). Lowercase macros are [still supported](include/stc/priv/altnames.h).
+- Some API changes in cregex and cstr.
 - [See detailed changes for version 4](#version-4).
 
 Introduction
 ------------
 STC is a *modern*, *templated*, *user-friendly*, *type-safe*, *very fast* and *compact* container library for C99.
-The API is fairly similar to c++ STL, but a bit more uniform across the containers and takes
-inspiration from Rust and Python as well. It is an advantage to know how these containers work in other languages, like
-Java, C# or C++, but it's not required.
+The API has similarities with c++ STL, but is more uniform across the containers and takes inspiration from Rust
+and Python as well. It is an advantage to know how these containers work in other languages, like Java, C# or C++,
+but it's not required.
 
 This library allows you to manage both trivial to very complex data in a wide variety of containers
 without the need for boilerplate code. You may specify element-cloning, -comparison, -destruction and
diff --git a/docs/cspan_api.md b/docs/cspan_api.md
index 616b090e..650260a2 100644
--- a/docs/cspan_api.md
+++ b/docs/cspan_api.md
@@ -38,12 +38,12 @@ ValueType*      cspan_back(const SpanTypeN* self);
                 // {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}, ...);
                 
-                // create a subspan of lower rank. Like e.g. cspan_slice(Span2, &ms3, {x}, {c_ALL}, {c_ALL});
+                // 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});
+                // 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);
@@ -132,63 +132,68 @@ int main() {
 ```c
 #include <c11/fmt.h>
 #include <stc/cspan.h>
-#define i_val float
-#include <stc/cstack.h>
 
-using_cspan3(Span, float); // Shorthand to define span types Span, Span2, and Span3.
+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]"
-        Span3 span3 = cspan_md(vec.data, xd, yd, zd);
-        *cspan_at(&span3, 4, 3, 2) = 3.14159f;
-        fmt_print("index: {}", cspan_index(&span3, 4, 3, 2));
-
-        Span span1 = cspan_submd3(&span3, 4, 3);
-        printf("\niterate span1: ");
-        c_FOREACH (i, Span, span1)
-            fmt_print("{} ", *i.ref);
-
-        Span2 span2 = cspan_submd3(&span3, 4);
-        printf("\niterate span2: ");
-        c_FOREACH (i, Span2, span2)
-            fmt_print("{} ", *i.ref);
-
-        puts("\niterate span3 by dimensions:");
-        c_FORRANGE (i, span3.shape[0]) {
-            c_FORRANGE (j, span3.shape[1]) {
-                c_FORRANGE (k, span3.shape[2])
-                    fmt_printf(" {:2}", *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);
 
-        fmt_println("{}", *cspan_at(&span3, 4, 3, 2));
-        fmt_println("{}", *cspan_at(&span2, 3, 2));
-        fmt_println("{}", *cspan_at(&span1, 2));
+    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(" |");
+        }
+        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.14159 
-iterate span2: 48 49 50 51 52 53 54 55 56 57 58 3.14159 
-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.14159 |
- 60 61 62 | 63 64 65 | 66 67 68 | 69 70 71 |
-3.14159
-3.14159
-3.14159
+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
 ```
diff --git a/include/stc/cspan.h b/include/stc/cspan.h
index 30046898..68a13522 100644
--- a/include/stc/cspan.h
+++ b/include/stc/cspan.h
@@ -105,7 +105,7 @@ typedef struct { int32_t d[4]; } cspan_idx4;
 typedef struct { int32_t d[5]; } cspan_idx5;
 typedef struct { int32_t d[6]; } cspan_idx6;
 #define c_END -1
-#define c_ALL 0,c_END
+#define c_ALL 0,-1
 
 #define cspan_md(array, ...) \
     {.data=array, .shape={__VA_ARGS__}, .stride={.d={__VA_ARGS__}}}
@@ -144,7 +144,7 @@ typedef struct { int32_t d[6]; } cspan_idx6;
 #define cspan_front(self) ((self)->data)
 #define cspan_back(self) ((self)->data + cspan_size(self) - 1)
 
-// cspan_subspanN. (N<5) Optimized, but same as e.g. cspan_slice(Span2, &ms4, {offset, offset + count}, {c_ALL}, {c_ALL});
+// cspan_subspanN. (N<4) Optimized, same as e.g. cspan_slice(Span3, &ms3, {off,off+count}, {c_ALL}, {c_ALL});
 #define cspan_subspan(self, offset, count) \
     {.data=cspan_at(self, offset), .shape={count}}
 #define cspan_subspan2(self, offset, count) \
@@ -152,7 +152,7 @@ typedef struct { int32_t d[6]; } cspan_idx6;
 #define cspan_subspan3(self, offset, count) \
     {.data=cspan_at(self, offset, 0, 0), .shape={count, (self)->shape[1], (self)->shape[2]}, .stride={(self)->stride}}
 
-// cspan_submdN: return reduced rank
+// cspan_submdN: reduce rank (N<5) Optimized, same as e.g. cspan_slice(Span2, &ms4, {x}, {y}, {c_ALL}, {c_ALL});
 #define cspan_submd4(...) c_MACRO_OVERLOAD(cspan_submd4, __VA_ARGS__)
 #define cspan_submd3(...) c_MACRO_OVERLOAD(cspan_submd3, __VA_ARGS__)
 #define cspan_submd2(self, x) \
@@ -233,7 +233,7 @@ STC_INLINE intptr_t _cspan_slice(int32_t odim[], int32_t ostri[], int* orank,
         off *= stri[i];
         off += a[i][0];
         switch (a[i][1]) { 
-            case 0: s *= stri[i]; continue;
+            case 0: s *= stri[i]; ok &= c_LTu(a[i][0], shape[i]); continue;
             case -1: t = shape[i]; break;
             default: t = a[i][1]; break; 
         }