Renamed c_with => c_fordefer, and removed c_withvar. Macros were too deceiving and hid the fact that it was for-loops. Now it is more explicit.

5 files changed, 22 insertions, 24 deletions

diff --git a/docs/ccommon_api.md b/docs/ccommon_api.md
index 7e329cfe..08b92396 100644
--- a/docs/ccommon_api.md
+++ b/docs/ccommon_api.md
@@ -2,25 +2,23 @@
 
 The following handy macros are safe to use, i.e. have no side-effects.
 
-### c_defer, c_with, c_withvar, c_withbuf, c_exitwith/c_exitdefer
-General ***defer*** mechanics. These macros allows to specify a resource release explicitly or implicitly where the
-resource acquisition is made. This ensures that resources are released after usage, and avoids memory leaks.
-**c_with / c_withvar** are inspired by Python's *with* statement, and **c_defer** from Go language.
+### c_fordefer, c_forbuffer
+General ***defer*** mechanics for resource acquisition. These macros allows to specify the release of the
+resource where the resource acquisition is made. This ensures that resources are released after usage.
 
-**NB**: ***Only*** use `c_exitwith`/`c_exitdefer` to break out of `c_with*`/`c_defer`-blocks.
-***Never*** use `return`, `goto` or `break` inside such a block.
+**NB**: These macros are one-time **for**-loops. ***Do only*** use `continue` in order to break out of a 
+`c_fordefer` / `c_forbuffer`-block. ***Do not*** use `return`, `goto` or `break`, as it will prevent the
+`release`-statement to be executed at the end.
 
 | Usage                            | Description                                       |
 |:---------------------------------|:--------------------------------------------------|
-| `c_with (acquire, release)`      | Do `acquire`. Defer `release` to end of block     |
-| `c_defer (release...)`           | Defer `release` to end of defer block             |
-| `c_withvar (type, v1,...v3)`     | `c_with (type v1 = type_init(), type_del(&v1))`   |
-| `c_withbuf (buf, type, n)`       | Declare, allocate and free memory buffer          |
+| `c_fordefer (acquire, release)`  | Do `acquire`. Defer `release` to end of block     |
+| `c_fordefer (release)`           | Defer execution of `release` to end of block      |
+| `c_forbuffer (buf, type, n)`     | Declare, allocate and free memory buffer          |
 
-The `acquire`argument must be of the form: `type var = getResource`.
-**c_with** and **c_defer** are general macros, whereas **c_withvar** requires that there 
-are methods *type_init()* to create and return an object of type, and *type_del()* 
-which destructs the object. These are available for all STC containers.
+The `acquire`argument must be of the form: `type var = getResource`. Note that the `release` argument can be 
+a list of statements enclosed in parathesises. **c_forbuffer** uses stack memory if buffer is <= to 256 bytes,
+othewise it uses more expensive heap memory.
 
 ```c
 // Example: Load each line of a text file into a vector of strings
@@ -35,8 +33,8 @@ cvec_str readFile(const char* name)
     // receiver should check errno variable
     cvec_str vec = cvec_str_init();
 
-    c_with (FILE* fp = fopen(name, "r"), fclose(fp)) {
-        c_with (cstr line = cstr_null, cstr_del(&line))
+    c_fordefer (FILE* fp = fopen(name, "r"), fclose(fp)) {
+        c_fordefer (cstr line = cstr_null, cstr_del(&line))
             while (cstr_getline(&line, fp))
                 cvec_str_emplace_back(&vec, line.str);
     }
@@ -45,7 +43,7 @@ cvec_str readFile(const char* name)
 
 int main()
 {
-    c_with (cvec_str x = readFile(__FILE__), cvec_str_del(&x))
+    c_fordefer (cvec_str x = readFile(__FILE__), cvec_str_del(&x))
         c_foreach (i, cvec_str, x)
             printf("%s\n", i.ref->str);
 }
diff --git a/docs/cmap_api.md b/docs/cmap_api.md
index a9481903..6bd998ba 100644
--- a/docs/cmap_api.md
+++ b/docs/cmap_api.md
@@ -208,7 +208,7 @@ using_cmap(vi, Vec3i, int, c_memcmp_equals, // bitwise equals
 int main()
 {
     // Define map with defered destruct
-    c_with (cmap_vi vecs = cmap_vi_init(), cmap_vi_del(&vecs))
+    c_fordefer (cmap_vi vecs = cmap_vi_init(), cmap_vi_del(&vecs))
     {
         cmap_vi_insert(&vecs, (Vec3i){100,   0,   0}, 1);
         cmap_vi_insert(&vecs, (Vec3i){  0, 100,   0}, 2);
@@ -239,7 +239,7 @@ using_cmap(iv, int, Vec3i);
 
 int main()
 {
-    c_with (cmap_iv vecs = cmap_iv_init(), cmap_iv_del(&vecs))
+    c_fordefer (cmap_iv vecs = cmap_iv_init(), cmap_iv_del(&vecs))
     {
         cmap_iv_insert(&vecs, 1, (Vec3i){100,   0,   0});
         cmap_iv_insert(&vecs, 2, (Vec3i){  0, 100,   0});
diff --git a/docs/cpque_api.md b/docs/cpque_api.md
index eaa476c1..503e322e 100644
--- a/docs/cpque_api.md
+++ b/docs/cpque_api.md
@@ -69,7 +69,7 @@ int main()
     stc64_uniform_t dist = stc64_uniform_init(0, N * 10);
 
     // Declare heap, with defered del()
-    c_with (cpque_i heap = cpque_i_init(), cpque_i_del(&heap))
+    c_fordefer (cpque_i heap = cpque_i_init(), cpque_i_del(&heap))
     {
         // Push ten million random numbers to priority queue, plus some negative ones.
         c_forrange (N)
diff --git a/docs/csmap_api.md b/docs/csmap_api.md
index 52c2829b..257e439c 100644
--- a/docs/csmap_api.md
+++ b/docs/csmap_api.md
@@ -192,7 +192,7 @@ using_csmap(vi, Vec3i, int, Vec3i_compare);
 
 int main()
 {
-    c_with (csmap_vi vecs = csmap_vi_init(), csmap_vi_del(&vecs))
+    c_fordefer (csmap_vi vecs = csmap_vi_init(), csmap_vi_del(&vecs))
     {
       csmap_vi_insert(&vecs, (Vec3i){100,   0,   0}, 1);
       csmap_vi_insert(&vecs, (Vec3i){  0, 100,   0}, 2);
@@ -223,7 +223,7 @@ using_csmap(iv, int, Vec3i);
 
 int main()
 {
-    c_with (csmap_iv vecs = csmap_iv_init(), csmap_iv_del(&vecs))
+    c_fordefer (csmap_iv vecs = csmap_iv_init(), csmap_iv_del(&vecs))
     {
         csmap_iv_insert(&vecs, 1, (Vec3i){100,   0,   0});
         csmap_iv_insert(&vecs, 2, (Vec3i){  0, 100,   0});
diff --git a/docs/csview_api.md b/docs/csview_api.md
index 16d59eae..26857938 100644
--- a/docs/csview_api.md
+++ b/docs/csview_api.md
@@ -128,7 +128,7 @@ int main()
     csview text = c_lit("The length of this literal is evaluated at compile time and stored in csview text.");
     printf("%s\nLength: %zu\n\n", text.str, text.size);
 
-    c_withvar (cmap_si, map) // defines map and defers destruction.
+    c_fordefer (cmap_si map = csmap_si_init(), csmap_si_del(&map))
     {
         cmap_si_emplace(&map, c_lit("hello"), 100);
         cmap_si_emplace(&map, c_lit("world"), 200);
@@ -187,7 +187,7 @@ int main()
     print_split(c_lit("This has no matching separator"), c_lit("xx"));
     puts("");
 
-    c_with (cvec_str v = string_split(c_lit("Split,this,,string,now,"), c_lit(",")), cvec_str_del(&v))
+    c_fordefer (cvec_str v = string_split(c_lit("Split,this,,string,now,"), c_lit(",")), cvec_str_del(&v))
         c_foreach (i, cvec_str, v)
             printf("\"%s\"\n", i.ref->str);
 }