More cleanups and refinements.

5 files changed, 55 insertions, 49 deletions

diff --git a/docs/carray_api.md b/docs/carray_api.md
index 3ae293c3..836726c2 100644
--- a/docs/carray_api.md
+++ b/docs/carray_api.md
@@ -84,7 +84,8 @@ int main()
 {
     // Ex1
     int xd = 30, yd = 20, zd = 10;
-    carray3f arr3 = carray3f_init(xd, yd, zd, 0.0f);  // define arr3[30][20][10], init with 0.0f.
+    // define arr3[30][20][10], initialized with zeros.
+    carray3f arr3 = carray3f_with_values(xd, yd, zd, 0.0f);
     arr3.data[5][4][3] = 3.14f;
 
     float *arr1 = arr3.data[5][4];
diff --git a/docs/ccommon_api.md b/docs/ccommon_api.md
index 75e27327..bf79a757 100644
--- a/docs/ccommon_api.md
+++ b/docs/ccommon_api.md
@@ -56,14 +56,17 @@ constructors are defined. This ensures that resources are released after usage,
 **NB**: ***Only*** use `c_breakwith` to break out of the `c_with`-block if needed. ***Never*** use `return`,
 `break`, or `goto` inside the block.
 
-| 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 (ctype, v)`         | `c_with (ctype v = ctype_init(), ctype_del(&v))` |
-| `c_withbuf (buf, type, n)`     | Declare, allocate and free memory buffer         |
+| 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, var)`          | `c_with (type var = type_init(), type_del(&var))` |
+| `c_withbuf (buf, type, n)`       | Declare, allocate and free memory buffer          |
 
 The `acquire`argument must be of the form: `type var = get_resource`.
+**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()* 
+that destructs the object. These are available for all STC containers.
 
 ```c
 // Example: Load each line of a text file into a vector of strings
diff --git a/docs/cmap_api.md b/docs/cmap_api.md
index 9fd96e5c..590577a7 100644
--- a/docs/cmap_api.md
+++ b/docs/cmap_api.md
@@ -206,17 +206,17 @@ using_cmap(vi, Vec3i, int, c_memcmp_equals, // bitwise equals
 
 int main()
 {
-    cmap_vi vecs = cmap_vi_init();
-
-    cmap_vi_emplace(&vecs, (Vec3i){100,   0,   0}, 1);
-    cmap_vi_emplace(&vecs, (Vec3i){  0, 100,   0}, 2);
-    cmap_vi_emplace(&vecs, (Vec3i){  0,   0, 100}, 3);
-    cmap_vi_emplace(&vecs, (Vec3i){100, 100, 100}, 4);
-
-    c_foreach (i, cmap_vi, vecs)
-        printf("{ %3d, %3d, %3d }: %d\n", i.ref->first.x,  i.ref->first.y,  i.ref->first.z,  i.ref->second);
-
-    cmap_vi_del(&vecs);
+    // Define map with defered destruct
+    c_with (cmap_vi vecs = cmap_vi_init(), cmap_vi_del(&vecs))
+    {
+        cmap_vi_emplace(&vecs, (Vec3i){100,   0,   0}, 1);
+        cmap_vi_emplace(&vecs, (Vec3i){  0, 100,   0}, 2);
+        cmap_vi_emplace(&vecs, (Vec3i){  0,   0, 100}, 3);
+        cmap_vi_emplace(&vecs, (Vec3i){100, 100, 100}, 4);
+
+        c_foreach (i, cmap_vi, vecs)
+            printf("{ %3d, %3d, %3d }: %d\n", i.ref->first.x,  i.ref->first.y,  i.ref->first.z,  i.ref->second);
+    }
 }
 ```
 Output:
@@ -238,16 +238,16 @@ using_cmap(iv, int, Vec3i);
 
 int main()
 {
-    cmap_iv vecs = cmap_iv_init();
-    cmap_iv_emplace(&vecs, 1, (Vec3i){100,   0,   0});
-    cmap_iv_emplace(&vecs, 2, (Vec3i){  0, 100,   0});
-    cmap_iv_emplace(&vecs, 3, (Vec3i){  0,   0, 100});
-    cmap_iv_emplace(&vecs, 4, (Vec3i){100, 100, 100});
-
-    c_foreach (i, cmap_iv, vecs)
-        printf("%d: { %3d, %3d, %3d }\n", i.ref->first, i.ref->second.x,  i.ref->second.y,  i.ref->second.z);
-
-    cmap_iv_del(&vecs);
+    c_with (cmap_iv vecs = cmap_iv_init(), cmap_iv_del(&vecs))
+    {
+        cmap_iv_emplace(&vecs, 1, (Vec3i){100,   0,   0});
+        cmap_iv_emplace(&vecs, 2, (Vec3i){  0, 100,   0});
+        cmap_iv_emplace(&vecs, 3, (Vec3i){  0,   0, 100});
+        cmap_iv_emplace(&vecs, 4, (Vec3i){100, 100, 100});
+
+        c_foreach (i, cmap_iv, vecs)
+            printf("%d: { %3d, %3d, %3d }\n", i.ref->first, i.ref->second.x,  i.ref->second.y,  i.ref->second.z);
+    }
 }
 ```
 Output:
diff --git a/docs/cpque_api.md b/docs/cpque_api.md
index a5cd056e..6f7917f5 100644
--- a/docs/cpque_api.md
+++ b/docs/cpque_api.md
@@ -68,18 +68,20 @@ int main()
     stc64_t rng = stc64_init(1234);
     stc64_uniform_t dist = stc64_uniform_init(0, N * 10);
 
-    cpque_i heap = cpque_i_init();
-    // Push ten million random numbers to priority queue, plus some negative ones.
-    c_forrange (N)
-        cpque_i_push(&heap, stc64_uniform(&rng, &dist));
-    c_emplace(cpque_i, heap, {-231, -32, -873, -4, -343});
-
-    // Extract and display the fifty smallest.
-    c_forrange (50) {
-        printf("%zd ", *cpque_i_top(&heap));
-        cpque_i_pop(&heap);
+    // Declare heap, with defered del()
+    c_with (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)
+            cpque_i_push(&heap, stc64_uniform(&rng, &dist));
+        c_emplace(cpque_i, heap, {-231, -32, -873, -4, -343});
+
+        // Extract and display the fifty smallest.
+        c_forrange (50) {
+            printf("%zd ", *cpque_i_top(&heap));
+            cpque_i_pop(&heap);
+        }
     }
-    cpque_i_del(&heap);
 }
 ```
 Output:
diff --git a/docs/csmap_api.md b/docs/csmap_api.md
index 5b76f7bb..a5d0aeee 100644
--- a/docs/csmap_api.md
+++ b/docs/csmap_api.md
@@ -221,16 +221,16 @@ using_csmap(iv, int, Vec3i);
 
 int main()
 {
-    csmap_iv vecs = csmap_iv_init();
-    csmap_iv_emplace(&vecs, 1, (Vec3i){100,   0,   0});
-    csmap_iv_emplace(&vecs, 2, (Vec3i){  0, 100,   0});
-    csmap_iv_emplace(&vecs, 3, (Vec3i){  0,   0, 100});
-    csmap_iv_emplace(&vecs, 4, (Vec3i){100, 100, 100});
-
-    c_foreach (i, csmap_iv, vecs)
-        printf("%d: { %3d, %3d, %3d }\n", i.ref->first, i.ref->second.x, i.ref->second.y, i.ref->second.z);
-
-    csmap_iv_del(&vecs);
+    c_with (csmap_iv vecs = csmap_iv_init(), csmap_iv_del(&vecs))
+    {
+        csmap_iv_emplace(&vecs, 1, (Vec3i){100,   0,   0});
+        csmap_iv_emplace(&vecs, 2, (Vec3i){  0, 100,   0});
+        csmap_iv_emplace(&vecs, 3, (Vec3i){  0,   0, 100});
+        csmap_iv_emplace(&vecs, 4, (Vec3i){100, 100, 100});
+
+        c_foreach (i, csmap_iv, vecs)
+            printf("%d: { %3d, %3d, %3d }\n", i.ref->first, i.ref->second.x, i.ref->second.y, i.ref->second.z);
+    }
 }
 ```
 Output: