diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/ccommon_api.md | 60 | ||||
| -rw-r--r-- | docs/csview_api.md | 27 |
2 files changed, 57 insertions, 30 deletions
diff --git a/docs/ccommon_api.md b/docs/ccommon_api.md index afbcb8a7..eb7918b9 100644 --- a/docs/ccommon_api.md +++ b/docs/ccommon_api.md @@ -33,10 +33,10 @@ c_forrange (i, int, 30, 0, -5) printf(" %d", i); ### c_foreach -| Usage | Description | -|:----------------------------------------------|:--------------------------------| -| `c_foreach (it, ctype, container)` | `Iteratate all elements ` | -| `c_foreach (it, ctype, it1, it2)` | `Iterate the range [it1, it2)` | +| Usage | Description | +|:-------------------------------------|:-----------------------------| +| `c_foreach (it, ctype, container)` | Iteratate all elements | +| `c_foreach (it, ctype, it1, it2)` | Iterate the range [it1, it2) | ```c using_csset(x, int); @@ -49,44 +49,58 @@ c_foreach (i, csset_x, it, csset_x_end(&set)) printf(" %d", *i.ref); // 7 12 23 ``` -### c_withfile, c_withbuffer, c_breakwith -Simplifies reading a file. Use only **c_breakwith** to break out of the block if needed. -**c_withbuffer** uses stack memory if buf is up to 256 bytes, and heap memory otherwise: +### c_with, c_withbuffer, c_breakwith +General defer in block mechanics. **c_withbuffer** is special for buffers, uses stack memory if buf is up to 256 bytes, +and heap memory otherwise. -| Usage | Description | -|:-------------------------------|:----------------------------------| -| `c_withfile (fp, fileopen)` | `Declare, open and close file` | -| `c_withbuffer (buf, type, n)` | `Declare, allocate and free buf` | +***NB***: Use only **c_breakwith** to break out of the block if needed, never use **return**, **break**, +or **goto** inside a with-block. + +| Usage | Description | +|:-------------------------------|:-------------------------------------| +| `c_with (acquire, release)` | Do `acquire`. Defer `release` to end | +| `c_withbuffer (buf, type, n)` | Declare, allocate and free buf | + +The `acquire`argument must be of the form: `type var = get_resource`. ```c -// Load each line of a text file into a vector of strings +// Example: Load 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 readFile(const char* name) { +cvec_str readFile(const char* name) +{ + // receiver should check errno variable cvec_str vec = cvec_str_init(); - // Next line declares, opens, and closes the FILE* - c_withfile (fp, fopen(name, "r")) { - cstr line = cstr_init(); - while (cstr_getline(&line, fp)) - cvec_str_emplace_back(&vec, line.str); - cstr_del(&line); - } - return vec; // receiver should check errno variable + c_with (FILE* fp = fopen(name, "r"), fclose(fp)) + c_with (cstr line = cstr_null, cstr_del(&line)) + while (cstr_getline(&line, fp)) + cvec_str_emplace_back(&vec, line.str); + + return vec; +} + +int main() +{ + c_with (cvec_str x = readFile(__FILE__), cvec_str_del(&x)) + c_foreach (i, cvec_str, x) + printf("%s\n", i.ref->str); } ``` -### c_new, c_new_n, c_del +### c_new, c_new_n, c_del, c_make | Usage | Meaning | |:-------------------------------|:----------------------------------------| | `c_new (type)` | `(type *) c_malloc(sizeof(type))` | | `c_new_n (type, N)` | `(type *) c_malloc((N)*sizeof(type))` | -| `c_del (ctype, c1, ..., cN)` | `ctype_del(c1); ... ctype_del(cN)` | +| `c_del (ctype, &c1, ..., &cN)` | `ctype_del(&c1); ... ctype_del(&cN)` | +| `c_make(type){value...}` | `(type){value...}` // c++ compatability | + ```c int* array = c_new_n (int, 100); c_free(array); diff --git a/docs/csview_api.md b/docs/csview_api.md index 4098114c..a76eb262 100644 --- a/docs/csview_api.md +++ b/docs/csview_api.md @@ -22,11 +22,13 @@ All csview definitions and prototypes are available by including a single header ## Methods ```c -csview csview_new(const char literal_only[]); // csview from literal, no strlen() csview c_sv(const char literal_only[]); // shorthand for csview_new() +csview csview_new(const char literal_only[]); // csview from literal, no strlen() csview csview_from(const char* str); // construct csview csview_from_n(const char* str, size_t n); // construct csview csview_from_s(cstr s); // construct +csview csview_remove_prefix(csview sv, size_t n); +csview csview_remove_suffix(csview sv, size_t n); csview csview_substr(csview sv, size_t pos, size_t n); size_t csview_size(csview sv); @@ -79,9 +81,11 @@ uint64_t csview_hash_ref(const csview* x, size_t ignored); ## Constants and macros -| Name | Value | -|:------------------|:------------------| -| `csview_null` | csview null value | +| Name | Value | Usage | +|:-----------------|:-------------------|:---------------------------------| +| `csview_null` | same as `c_sv("")` | `sview = csview_null;` | +| `c_sv(literal)` | csview constructor | `sview = c_sv("hello, world");` | +| `csview_PRN(sv)` | printf argument | `printf("%.*s", csview_PRN(sv));`| ## Container adaptors ``` @@ -106,23 +110,31 @@ using_cset_sv() ## Example ```c +#include <stc/csview.h> +#include <stc/cvec.h> #include <stc/cmap.h> -using_cmap_svkey(si, int); // cmap<cstr, int> with csview as convertion type -using_cvec_sv(); // cvec<cstr> with csview as convertion type +// cmap<cstr, int> with csview as convertion type +using_cmap_svkey(si, int); +// cvec<cstr> with csview as convertion type +using_cvec_sv(); int main() { csview text = c_sv("A long and winded literal string"); printf("%s\nLength: %zu\n\n", text.str, text.size); + // cvec of cstr elements, using csview as "emplace" type c_var (cvec_sv, vec, { c_sv("Element 1"), c_sv("Element 2"), c_sv("Element 3") }); + + // push constructed cstr directly cvec_sv_push_back(&vec, cstr_new("Second last element")); - cvec_sv_emplace_back(&vec, c_sv("Last element")); // converts from csview to cstr + // emplace constructs cstr from a csview + cvec_sv_emplace_back(&vec, c_sv("Last element")); c_foreach (i, cvec_sv, vec) printf("%s\n", i.ref->str); @@ -133,6 +145,7 @@ int main() }); cmap_si_emplace(&map, c_sv("gone mad"), 300); + // cmap_si_get() knows the length of "world" without strlen(). cmap_si_value_t* v = cmap_si_get(&map, c_sv("world")); printf("\n%s: %d\n", v->first.str, v->second); |