Added: crange number generator type. (similar to c++ std::iota). Fixed c_forfilter again. Cleanups. Docs added.

5 files changed, 90 insertions, 8 deletions

diff --git a/docs/ccommon_api.md b/docs/ccommon_api.md
index c45dadc1..8938f0d2 100644
--- a/docs/ccommon_api.md
+++ b/docs/ccommon_api.md
@@ -149,9 +149,9 @@ c_forlist (i, int, {1, 2, 3})
 c_forlist (i, cmap_ii_raw, { {4, 5}, {6, 7} })
     cmap_ii_insert(&map, i.ref->first, i.ref->second);
 
-// even string literals
+// even string literals pushed to a stack of cstr:
 c_forlist (i, const char*, {"Hello", "crazy", "world"})
-    cstack_s_push(&stk, *i.ref);
+    cstack_str_emplace(&stk, *i.ref);
 ```
 
 ### c_foreach, c_forpair
@@ -168,7 +168,7 @@ c_forlist (i, const char*, {"Hello", "crazy", "world"})
 #define i_tag ii
 #include <stc/csmap.h>
 ...
-c_forlist (i, csmap_ii_value, { {23,1}, {3,2}, {7,3}, {5,4}, {12,5} })
+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);
 
 c_foreach (i, csmap_ii, map)
@@ -186,7 +186,7 @@ c_forpair (id, count, csmap_ii, map)
 ```
 
 ### c_forrange
-Declare an iterator and specify a range to iterate with a for loop. Like python's ***for i in range()*** loop:
+Abstaction for iterating sequence of numbers. Like python's ***for i in range()*** loop.
 
 | Usage                                         | Python equivalent                    |
 |:----------------------------------------------|:-------------------------------------|
@@ -207,6 +207,88 @@ c_forrange (i, int, 30, 0, -5) printf(" %d", i);
 // 30 25 20 15 10 5
 ```
 
+### c_forwhile, c_forfilter
+Iterate containers with stop-criteria and chained range filtering.
+
+| Usage                                                      | Description                          |
+|:-----------------------------------------------------------|:-------------------------------------|
+| `c_forwhile (it, ctype, container, whilepred)`             | Iterate as long as whilepred is true |
+| `c_forfilter (it, ctype, container, filter(s))`            | Filter out items in chain            |
+| `c_forfilter (it, ctype, container, filter(s), whilepred)` | Adds a "takewhile" filter argument   |
+
+| Built-in filter                   | Description                          |
+|:----------------------------------|:-------------------------------------|
+| `c_flt_drop(it, numItems)`        | Drop numItems                        |
+| `c_flt_dropwhile(it, predicate)`  | Drop items until predicate is false  |
+| `c_flt_take(it, numItems)`        | Take numItems                        |
+
+`it.index` holds the current item index.
+```c
+#define i_type IVec
+#define i_val int
+#include <stc/cstack.h>
+#include <stdio.h>
+
+bool flt_prime(int i) {
+    for (int j=2; j*j <= i; ++j){
+        if (i % j == 0) return false;
+    }
+    return true;
+}
+#define flt_odd(i) ((i) & 1)
+
+int main() {
+    c_auto (IVec, vec) {
+        c_forrange (i, 1000) IVec_push(&vec, 1000000 + i);
+
+        c_forfilter (i, IVec, vec,
+                          flt_odd(*i.ref)
+                     && c_flt_drop(i, 100) // built-in
+                     &&   flt_prime(*i.ref)
+                      , c_flt_take(i, 10)) { // breaks loop on false.
+            printf(" %d", *i.ref);  
+        }
+        puts("");
+    }
+}
+// Out: 1000211 1000213 1000231 1000249 1000253 1000273 1000289 1000291 1000303 1000313 
+```
+Note that `c_flt_take()` is given as an optional argument, which makes the loop stop when it becomes false (for efficiency). Chaining it after `flt_prime()` instead will give same result, but the full input is processed.
+
+### crange
+**crange** is a number sequence generator type. The **crange_value** type is `intmax_t`. Below, *start*, *end*, *step* are of *crange_type*.
+```c
+crange      crange_init(void);              // will generate 0, 1, 2, ...
+crange      crange_from(start);             // will generate start, start+1, ...
+crange      crange_from(start, end);        // will generate start, start+1, ... end-1
+crange      crange_from(start, end, step);  // will generate start, start+step, ... upto-not-including end
+                                            // note that step may be negative.
+crange_iter crange_begin(crange* self);
+crange_iter crange_end(crange* self);
+void        crange_next(crange_iter* it);
+
+// Example usage:
+
+bool isPrime(int i) {
+    for (int j=2; j*j <= i; ++j) if (i % j == 0) return false;
+    return true;
+}
+
+crange r1 = crange_from(3, 32, 2);
+printf("1 2");
+c_forfilter (i, crange, r1, 
+                isPrime(*i.ref))
+    printf(" %lld", *i.ref);
+// 1 2 3 5 7 11 13 17 19 23 29 31
+
+crange r2 = crange_from(3, INTMAX_MAX, 2);
+printf("1 2");
+c_forfilter (i, crange, r2, 
+                isPrime(*i.ref)
+              , c_flt_take(10))
+    printf(" %lld", *i.ref);
+// 1 2 3 5 7 11 13 17 19 23 29 31
+```
 ### c_find_if, c_find_in, c_erase_if
 Find or erase linearily in containers using a predicate
 ```c
diff --git a/docs/cdeq_api.md b/docs/cdeq_api.md
index 969cecc2..cfd5565e 100644
--- a/docs/cdeq_api.md
+++ b/docs/cdeq_api.md
@@ -81,7 +81,7 @@ void                cdeq_X_sort_range(cdeq_X_iter i1, cdeq_X_iter i2,
 cdeq_X_iter         cdeq_X_begin(const cdeq_X* self);
 cdeq_X_iter         cdeq_X_end(const cdeq_X* self);
 void                cdeq_X_next(cdeq_X_iter* it);
-cdeq_X_iter         cdeq_X_advance(cdeq_X_iter it, isize_t n);
+cdeq_X_iter         cdeq_X_advance(cdeq_X_iter it, intptr_t n);
 
 cdeq_X_raw          cdeq_X_value_toraw(cdeq_X_value* pval);
 cdeq_X_value        cdeq_X_value_clone(cdeq_X_value val);
diff --git a/docs/cstr_api.md b/docs/cstr_api.md
index 53850e04..439faca7 100644
--- a/docs/cstr_api.md
+++ b/docs/cstr_api.md
@@ -108,7 +108,7 @@ void         cstr_u8_erase(cstr* self, size_t bytepos, size_t u8len); // erase u
 cstr_iter    cstr_begin(const cstr* self);
 cstr_iter    cstr_end(const cstr* self);
 void         cstr_next(cstr_iter* it);
-cstr_iter    cstr_advance(cstr_iter it, isize_t n);
+cstr_iter    cstr_advance(cstr_iter it, intptr_t n);
 
 // utf8 functions requires linking with src/utf8code.c symbols:
 bool         cstr_valid_utf8(const cstr* self);                       // check if str is valid utf8
diff --git a/docs/csview_api.md b/docs/csview_api.md
index 37ebf79a..70587911 100644
--- a/docs/csview_api.md
+++ b/docs/csview_api.md
@@ -55,7 +55,7 @@ bool            csview_valid_utf8(csview sv);                       // requires
 csview_iter     csview_begin(const csview* self);
 csview_iter     csview_end(const csview* self);
 void            csview_next(csview_iter* it);                       // utf8 codepoint step, not byte!
-csview_iter     csview_advance(csview_iter it, isize_t n);
+csview_iter     csview_advance(csview_iter it, intptr_t n);
 
 // from utf8.h
 size_t          utf8_size(const char *s);
diff --git a/docs/cvec_api.md b/docs/cvec_api.md
index dca273aa..c9442bb1 100644
--- a/docs/cvec_api.md
+++ b/docs/cvec_api.md
@@ -92,7 +92,7 @@ void                cvec_X_sort_range(cvec_X_iter i1, cvec_X_iter i2,
 cvec_X_iter         cvec_X_begin(const cvec_X* self);
 cvec_X_iter         cvec_X_end(const cvec_X* self);
 void                cvec_X_next(cvec_X_iter* iter);
-cvec_X_iter         cvec_X_advance(cvec_X_iter it, isize_t n);
+cvec_X_iter         cvec_X_advance(cvec_X_iter it, intptr_t n);
 
 cvec_X_raw          cvec_X_value_toraw(cvec_X_value* pval);
 cvec_X_value        cvec_X_value_clone(cvec_X_value val);