More docs improvements.

6 files changed, 42 insertions, 33 deletions

diff --git a/docs/ccommon_api.md b/docs/ccommon_api.md
index 04af832b..c25d76da 100644
--- a/docs/ccommon_api.md
+++ b/docs/ccommon_api.md
@@ -176,18 +176,22 @@ c_forlist (i, int, {1, 2, 3})
 #define i_tag ii
 #include <stc/csmap.h>
 ...
-c_forlist (i, csmap_ii_raw, { {23,1}, {3,2}, {7,3}, {5,4}, {12,5} })
-    csmap_ii_insert(&map, i.ref->first, i.ref->second);
+csmap_ii map = c_make(csmap_ii, { {23,1}, {3,2}, {7,3}, {5,4}, {12,5} });
 
 c_foreach (i, csmap_ii, map)
     printf(" %d", i.ref->first);
 // 3 5 7 12 23
+// same without using c_foreach:
+for (csmap_ii_iter i = csmap_ii_begin(&map); i.ref; csmap_ii_next(&i))
+    printf(" %d", i.ref->first);
 
 csmap_ii_iter it = csmap_ii_find(&map, 7);
+// iterate from it to end
 c_foreach (i, csmap_ii, it, csmap_ii_end(&map))
     printf(" %d", i.ref->first);
 // 7 12 23
 
+// structured binding:
 c_forpair (id, count, csmap_ii, map)
     printf(" (%d %d)", *_.id, *_.count);
 // (3 2) (5 4) (7 3) (12 5) (23 1)
@@ -235,6 +239,7 @@ Iterate containers with stop-criteria and chained range filtering.
 #define i_type IVec
 #define i_val int
 #include <stc/cstack.h>
+#include <stc/algo/filter.h>
 #include <stdio.h>
 
 bool isPrime(int i) {
diff --git a/docs/cmap_api.md b/docs/cmap_api.md
index 263aff10..2c6274ae 100644
--- a/docs/cmap_api.md
+++ b/docs/cmap_api.md
@@ -23,7 +23,6 @@ See the c++ class [std::unordered_map](https://en.cppreference.com/w/cpp/contain
 #define i_hash      // hash func i_keyraw*: REQUIRED IF i_keyraw is non-pod type
 #define i_eq        // equality comparison two i_keyraw*: REQUIRED IF i_keyraw is a
                     // non-integral type. Three-way i_cmp may alternatively be specified.
-
 #define i_keydrop   // destroy key func - defaults to empty destruct
 #define i_keyclone  // REQUIRED IF i_keydrop defined
 #define i_keyraw    // convertion "raw" type - defaults to i_key
@@ -36,10 +35,10 @@ See the c++ class [std::unordered_map](https://en.cppreference.com/w/cpp/contain
 #define i_valfrom   // convertion func i_valraw => i_val
 #define i_valto     // convertion func i_val* => i_valraw
 
-#define i_size      // default: uint32_t. If defined, table expand 2x (else 1.5x)
+#define i_tag       // alternative typename: cmap_{i_tag}. i_tag defaults to i_val
 #define i_hash_functor // advanced, see examples/functor.c for similar usage.
 #define i_eq_functor // advanced, see examples/functor.c for similar usage.
-#define i_tag       // alternative typename: cmap_{i_tag}. i_tag defaults to i_val
+#define i_size      // define cmap_X_sizet. default int32_t. If defined, table expand 2x (else 1.5x)
 #include <stc/cmap.h>
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.
@@ -48,20 +47,20 @@ See the c++ class [std::unordered_map](https://en.cppreference.com/w/cpp/contain
 
 ```c
 cmap_X                cmap_X_init(void);
-cmap_X                cmap_X_with_capacity(int64_t cap);
+cmap_X                cmap_X_with_capacity(cmap_X_sizet cap);
 cmap_X                cmap_X_clone(cmap_x map);
 
 void                  cmap_X_clear(cmap_X* self);
 void                  cmap_X_copy(cmap_X* self, const cmap_X* other);
 float                 cmap_X_max_load_factor(const cmap_X* self);                       // default: 0.85f
-bool                  cmap_X_reserve(cmap_X* self, int64_t size);
+bool                  cmap_X_reserve(cmap_X* self, cmap_X_sizet size);
 void                  cmap_X_shrink_to_fit(cmap_X* self);
 void                  cmap_X_drop(cmap_X* self);                                        // destructor
 
 bool                  cmap_X_empty(const cmap_X* self );
-int64_t               cmap_X_size(const cmap_X* self);
-int64_t               cmap_X_capacity(const cmap_X* self);                              // buckets * max_load_factor
-int64_t               cmap_X_bucket_count(const cmap_X* self);                          // num. of allocated buckets
+cmap_X_sizet          cmap_X_size(const cmap_X* self);
+cmap_X_sizet          cmap_X_capacity(const cmap_X* self);                              // buckets * max_load_factor
+cmap_X_sizet          cmap_X_bucket_count(const cmap_X* self);                          // num. of allocated buckets
 
 const cmap_X_mapped*  cmap_X_at(const cmap_X* self, i_keyraw rkey);                     // rkey must be in map
 cmap_X_mapped*        cmap_X_at_mut(cmap_X* self, i_keyraw rkey);                       // mutable at
@@ -84,7 +83,7 @@ void                  cmap_X_erase_entry(cmap_X* self, cmap_X_value* entry);
 cmap_X_iter           cmap_X_begin(const cmap_X* self);
 cmap_X_iter           cmap_X_end(const cmap_X* self);
 void                  cmap_X_next(cmap_X_iter* it);
-cmap_X_iter           cmap_X_advance(cmap_X_iter it, uint64_t n);
+cmap_X_iter           cmap_X_advance(cmap_X_iter it, cmap_X_sizet n);
 
 cmap_X_value          cmap_X_value_clone(cmap_X_value val);
 cmap_X_raw            cmap_X_value_toraw(cmap_X_value* pval);
diff --git a/docs/cset_api.md b/docs/cset_api.md
index 1c38d000..27e633b4 100644
--- a/docs/cset_api.md
+++ b/docs/cset_api.md
@@ -18,10 +18,10 @@ A **cset** is an associative container that contains a set of unique objects of
 #define i_keyfrom   // convertion func i_keyraw => i_key - defaults to plain copy
 #define i_keyto     // convertion func i_key* => i_keyraw - defaults to plain copy
 
-#define i_size      // default: uint32_t. If defined, table expand 2x (else 1.5x)
+#define i_tag       // alternative typename: cmap_{i_tag}. i_tag defaults to i_val
 #define i_hash_functor // advanced, see examples/functor.c for similar usage.
 #define i_eq_functor // advanced, see examples/functor.c for similar usage.
-#define i_tag       // alternative typename: cmap_{i_tag}. i_tag defaults to i_val
+#define i_size      // defines cset_X_sizet. default int32_t. If defined, table expand 2x (else 1.5x)
 #include <stc/cset.h>
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.
@@ -36,14 +36,14 @@ cset_X              cset_X_clone(cset_x set);
 void                cset_X_clear(cset_X* self);
 void                cset_X_copy(cset_X* self, const cset_X* other);
 float               cset_X_max_load_factor(const cset_X* self);              // default: 0.85
-bool                cset_X_reserve(cset_X* self, intptr_t size);
+bool                cset_X_reserve(cset_X* self, cset_X_sizet size);
 void                cset_X_shrink_to_fit(cset_X* self);
 void                cset_X_drop(cset_X* self);                               // destructor
 
-intptr_t            cset_X_size(const cset_X* self);                         // num. of allocated buckets
-intptr_t            cset_X_capacity(const cset_X* self);                     // buckets * max_load_factor
+cset_X_sizet        cset_X_size(const cset_X* self);                         // num. of allocated buckets
+cset_X_sizet        cset_X_capacity(const cset_X* self);                     // buckets * max_load_factor
 bool                cset_X_empty(const cset_X* self);
-intptr_t            cset_X_bucket_count(const cset_X* self);
+cset_X_sizet        cset_X_bucket_count(const cset_X* self);
 
 bool                cset_X_contains(const cset_X* self, i_keyraw rkey);
 const cset_X_value* cset_X_get(const cset_X* self, i_keyraw rkey);          // return NULL if not found
@@ -54,7 +54,7 @@ cset_X_result       cset_X_insert(cset_X* self, i_key key);
 cset_X_result       cset_X_push(cset_X* self, i_key key);                    // alias for insert.
 cset_X_result       cset_X_emplace(cset_X* self, i_keyraw rkey);
 
-intptr_t            cset_X_erase(cset_X* self, i_keyraw rkey);               // return 0 or 1
+int                 cset_X_erase(cset_X* self, i_keyraw rkey);               // return 0 or 1
 cset_X_iter         cset_X_erase_at(cset_X* self, cset_X_iter it);           // return iter after it
 void                cset_X_erase_entry(cset_X* self, cset_X_value* entry);
 
diff --git a/docs/csmap_api.md b/docs/csmap_api.md
index 80fa96fb..59185081 100644
--- a/docs/csmap_api.md
+++ b/docs/csmap_api.md
@@ -32,8 +32,9 @@ See the c++ class [std::map](https://en.cppreference.com/w/cpp/container/map) fo
 #define i_valfrom   // convertion func i_valraw => i_val
 #define i_valto     // convertion func i_val* => i_valraw
 
-#define i_cmp_functor // advanced, see examples/functor.c for similar usage.
 #define i_tag       // alternative typename: csmap_{i_tag}. i_tag defaults to i_val
+#define i_cmp_functor // advanced, see examples/functor.c for similar usage.
+#define i_size      // defines csmap_X_sizet type; defaults to int32_t
 #include <stc/csmap.h>
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.
@@ -42,8 +43,8 @@ See the c++ class [std::map](https://en.cppreference.com/w/cpp/container/map) fo
 
 ```c
 csmap_X               csmap_X_init(void);
-csset_X               csmap_X_with_capacity(int64_t cap);
-bool                  csmap_X_reserve(csmap_X* self, int64_t cap);
+csset_X               csmap_X_with_capacity(csmap_X_sizet cap);
+bool                  csmap_X_reserve(csmap_X* self, csmap_X_sizet cap);
 void                  csmap_X_shrink_to_fit(csmap_X* self);
 csmap_X               csmap_X_clone(csmap_x map);
 
@@ -52,8 +53,8 @@ void                  csmap_X_copy(csmap_X* self, const csmap_X* other);
 void                  csmap_X_drop(csmap_X* self);                                               // destructor
 
 bool                  csmap_X_empty(const csmap_X* self);
-int64_t               csmap_X_size(const csmap_X* self);
-int64_t               csmap_X_capacity(const csmap_X* self);
+csmap_X_sizet         csmap_X_size(const csmap_X* self);
+csmap_X_sizet         csmap_X_capacity(const csmap_X* self);
 
 const csmap_X_mapped* csmap_X_at(const csmap_X* self, i_keyraw rkey);                            // rkey must be in map
 csmap_X_mapped*       csmap_X_at_mut(csmap_X* self, i_keyraw rkey);                              // mutable at
@@ -74,14 +75,14 @@ csmap_X_result        csmap_X_push(csmap_X* self, csmap_X_value entry);
 csmap_X_result        csmap_X_emplace(csmap_X* self, i_keyraw rkey, i_valraw rmapped);           // no change if rkey in map
 csmap_X_result        csmap_X_emplace_or_assign(csmap_X* self, i_keyraw rkey, i_valraw rmapped); // always update rmapped
 
-intptr_t              csmap_X_erase(csmap_X* self, i_keyraw rkey);
+int                   csmap_X_erase(csmap_X* self, i_keyraw rkey);
 csmap_X_iter          csmap_X_erase_at(csmap_X* self, csmap_X_iter it);                          // returns iter after it
 csmap_X_iter          csmap_X_erase_range(csmap_X* self, csmap_X_iter it1, csmap_X_iter it2);    // returns updated it2
 
 csmap_X_iter          csmap_X_begin(const csmap_X* self);
 csmap_X_iter          csmap_X_end(const csmap_X* self);
 void                  csmap_X_next(csmap_X_iter* iter);
-csmap_X_iter          csmap_X_advance(csmap_X_iter it, uint64_t n);
+csmap_X_iter          csmap_X_advance(csmap_X_iter it, csmap_X_sizet n);
 
 csmap_X_value         csmap_X_value_clone(csmap_X_value val);
 csmap_X_raw           csmap_X_value_toraw(csmap_X_value* pval);
diff --git a/docs/cspan_api.md b/docs/cspan_api.md
index 2bd93a2b..db706a51 100644
--- a/docs/cspan_api.md
+++ b/docs/cspan_api.md
@@ -1,9 +1,8 @@
 # STC [cspan](../include/stc/cspan.h): Multi-dimensional Array View
 ![Array](pics/array.jpg)
 
-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.
+The **cspan** is templated non-owning multi-dimensional view of an array. It is similar to 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).
 
 ## Header file and declaration
 
@@ -18,7 +17,11 @@ using_cspan3(S, ValueType);              // define span types S, S2, S3 with ran
 using_cspan4(S, ValueType);              // define span types S, S2, S3, S4 with ranks 1, 2, 3, 4.
 ```
 ## Methods
-All functions are type-safe, and index arguments are side-effect safe.
+
+All functions are type-safe. Note that the span argument itself is generally not side-effect safe,
+i.e., it may be expanded multiple times. However, all integer arguments are safe, e.g.
+`cspan_at(&ms3, i++, j++, k++)` is fine. 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
 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
diff --git a/docs/csset_api.md b/docs/csset_api.md
index 3d7698ed..4618bd18 100644
--- a/docs/csset_api.md
+++ b/docs/csset_api.md
@@ -20,6 +20,7 @@ See the c++ class [std::set](https://en.cppreference.com/w/cpp/container/set) fo
 
 #define i_cmp_functor // advanced, see examples/functor.c for similar usage.
 #define i_tag       // alternative typename: csset_{i_tag}. i_tag defaults to i_val
+#define i_size      // defines csset_X_sizet type; defaults to int32_t
 #include <stc/csset.h>
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.
@@ -28,8 +29,8 @@ See the c++ class [std::set](https://en.cppreference.com/w/cpp/container/set) fo
 
 ```c
 csset_X              csset_X_init(void);
-csset_X              csset_X_with_capacity(intptr_t cap);
-bool                 csset_X_reserve(csset_X* self, intptr_t cap);
+csset_X              csset_X_with_capacity(csset_X_sizet cap);
+bool                 csset_X_reserve(csset_X* self, csset_X_sizet cap);
 void                 csset_X_shrink_to_fit(csset_X* self);
 csset_X              csset_X_clone(csset_x set);
 
@@ -37,7 +38,7 @@ void                 csset_X_clear(csset_X* self);
 void                 csset_X_copy(csset_X* self, const csset_X* other);
 void                 csset_X_drop(csset_X* self);                                             // destructor
 
-intptr_t             csset_X_size(const csset_X* self);
+csset_X_sizet        csset_X_size(const csset_X* self);
 bool                 csset_X_empty(const csset_X* self);
 
 const csset_X_value* csset_X_get(const csset_X* self, i_keyraw rkey);                         // const get
@@ -51,7 +52,7 @@ csset_X_result       csset_X_insert(csset_X* self, i_key key);
 csset_X_result       csset_X_push(csset_X* self, i_key key);                                  // alias for insert()
 csset_X_result       csset_X_emplace(csset_X* self, i_keyraw rkey);
 
-intptr_t             csset_X_erase(csset_X* self, i_keyraw rkey);
+int                  csset_X_erase(csset_X* self, i_keyraw rkey);
 csset_X_iter         csset_X_erase_at(csset_X* self, csset_X_iter it);                        // return iter after it
 csset_X_iter         csset_X_erase_range(csset_X* self, csset_X_iter it1, csset_X_iter it2);  // return updated it2