Update ccommon_api.md

1 files changed, 48 insertions, 25 deletions

diff --git a/docs/ccommon_api.md b/docs/ccommon_api.md
index 3214fbef..2fc3e8e6 100644
--- a/docs/ccommon_api.md
+++ b/docs/ccommon_api.md
@@ -1,29 +1,14 @@
-# STC [ccommon](../stc/ccommon.h): Common definitions and safe macros
+# STC [ccommon](../stc/ccommon.h): Common definitions and handy macros
 
-This describes the features the ccommon.h header file.
+The following handy macros are completely safe to use, i.e. they have no side-effects.
 
-## Macros
-The following macros a completely safe to use, with no side-effects.
-
-
-#### c_new, c_del
-
-| Usage                          | Meaning                                 |
-|:-------------------------------|:----------------------------------------|
-| `c_new (type)`                 | `(type *) c_malloc(sizeof(type))`       |
-| `c_new (type, N)`              | `(type *) c_malloc((N) * sizeof(type))` |
-| `c_del (ctype, c1, ..., cN)`   | `ctype_del(c1); ... ctype_del(cN)`      |
+#### c_init, c_push_items
+**c_init** declares and initializes any container with an array of elements. **c_push_items** adds elements to any existing container.
 ```c
-int* array = c_new (int, 100);
-c_free(array);
-
-cstr a = cstr_from("Hello"), b = cstr_from("World");
-c_del(cstr, &a, &b);
+c_init (cvec_i, vec, {1, 2, 3});
+c_push_items(&vec, cvec_i, {4, 5, 6});
 ```
 
-#### c_malloc, c_calloc, c_realloc, c_free
-Memory allocator for the entire library. Macros can be overloaded by the user.
-
 #### c_forrange
 Declare an iterator and specify a range to iterate with a for loop. Like python's ***for i in range()*** function:
 
@@ -64,10 +49,48 @@ c_foreach (i, csset_x, it, csset_x_end(&set)) printf(" %d", *i.ref);
 // 7 12 23
 ```
 
-#### c_withbuffer
+#### c_withfile, c_breakwith
+Simplifies reading a file. Use **c_breakwith** if you need to break out of the block. Example:
+```c
+// Put each line of a text file into a vector of strings
+#include <errno.h>
+#include <stc/cstr.h>
+#include <stc/cvec.h>
+
+using_cvec_str();
+
+cvec_str // on return, check global errno variable for errors
+readFile(const char* name) {
+    cvec_str vec = cvec_str_init();
+
+    // Next line handles declaring, opening, and closing a FILE*
+    c_withfile (f, fopen(name, "r")) {
+        cstr_t line = cstr_inits;
+        while (cstr_getline(&line, f))
+            cvec_str_emplace_back(&vec, line.str);
+        cstr_del(&line);
+    }
+    return vec;
+}
+```
 
-#### c_withfile
+#### c_new, c_del
 
-#### c_push_items
+| Usage                          | Meaning                                 |
+|:-------------------------------|:----------------------------------------|
+| `c_new (type)`                 | `(type *) c_malloc(sizeof(type))`       |
+| `c_new (type, N)`              | `(type *) c_malloc((N) * sizeof(type))` |
+| `c_del (ctype, c1, ..., cN)`   | `ctype_del(c1); ... ctype_del(cN)`      |
+```c
+int* array = c_new (int, 100);
+c_free(array);
+
+cstr a = cstr_from("Hello"), b = cstr_from("World");
+c_del(cstr, &a, &b);
+```
+
+#### c_malloc, c_calloc, c_realloc, c_free
+Memory allocator for the entire library. Macros can be overloaded by the user.
 
-#### c_swap
+#### c_swap(type, x, y), c_arraylen(array)
+**c_swap**: Simple macro for swapping internals of two objects. **c_arraylen**: Return number of elements in an array, e.g. `int array[] = {1, 2, 3, 4};