From b1b19bc2e5a2732e59583184bfa18a34052d5ae1 Mon Sep 17 00:00:00 2001 From: Tyge Løvset Date: Wed, 24 Mar 2021 14:29:44 +0100 Subject: Cleanup in documentation. --- README.md | 25 ++++++++++++------------- docs/carray_api.md | 2 +- docs/cbits_api.md | 4 ++-- docs/cdeq_api.md | 4 ++-- docs/clist_api.md | 5 +++-- docs/cmap_api.md | 14 ++++++-------- docs/coption_api.md | 2 +- docs/cpque_api.md | 6 +++--- docs/cptr_api.md | 4 ++-- docs/cqueue_api.md | 31 ++++++++++++++++--------------- docs/crandom_api.md | 2 +- docs/cset_api.md | 5 ++--- docs/csmap_api.md | 13 ++++++------- docs/csset_api.md | 5 ++--- docs/cstack_api.md | 14 ++++++++------ docs/cstr_api.md | 2 +- docs/cvec_api.md | 9 +++++---- 17 files changed, 73 insertions(+), 74 deletions(-) diff --git a/README.md b/README.md index 69fffc08..2ace5dbb 100644 --- a/README.md +++ b/README.md @@ -181,7 +181,7 @@ in your build environment and place all the instantiations of containers used in using_cmap(ii, int, int); using_cset(ix, int64_t); using_cvec(i, int); -using_clist(pt, struct Point); +using_clist(p, struct Point); ``` The *emplace* versus non-emplace container methods @@ -191,16 +191,24 @@ with **emplace**, e.g. **cvec_X_emplace_back()**. This is a convenient alternati **cvec_X_push_back()** when dealing non-trivial container elements, e.g. smart pointers or elements using dynamic memory. -| Move and insert element | Construct element in-place | Container | +| Move and insert element | Construct element in-place | Container | |:--------------------------|:-----------------------------|:-------------------------| | insert() | emplace() | cmap, cset, csmap, csset | | insert_or_assign(), put() | emplace_or_assign() | cmap, csmap | +| push() | emplace() | cstack, cqueue, cpque | | push_back() | emplace_back() | cvec, cdeq, clist | | push_front() | emplace_front() | cdeq, clist | | insert_after() | emplace_after() | clist | -***Note***: For containers of integral or trivial element types, **emplace** and corresponding non-emplace methods are -identical, so the following does not apply for those. +Note these differences between STC and c++ STL maps: + +| STC maps | C++ STL maps | +|:-------------------------------------|:------------------------------| +| insert(Key, Mapped) | insert(Value) | +| emplace_or_assign(RawKey, RawMapped) | N/A | + +For containers of integral or trivial element types, **emplace** and corresponding +non-emplace methods are identical, so the following does not apply for those. The **emplace** methods ***construct*** or ***clone*** their own copy of the element to be added. In contrast, the non-emplace methods requires elements to be explicitly constructed or cloned before adding them. @@ -250,15 +258,6 @@ it = cmap_str_find(&map, "Hello"); Apart from strings, maps and sets are normally used with trivial value types. However, the last example on the **cmap** page demonstrates how to specify a map with non-trivial keys. -Note that some map method arguments are different between STC maps and c++ STL: - -| STC maps | C++ STL maps -|:-------------------------------------|:------------------------------| -| insert(Key, Mapped) | insert(Value) | -| emplace(RawKey, RawMapped) | emplace(Key, Mapped) | -| insert_or_assign(Key, Mapped) | insert_or_assign(Key, Mapped) | -| emplace_or_assign(RawKey, RawMapped) | N/A | - Memory efficiency ----------------- - **cstr**, **cvec**: Type size: one pointer. The size and capacity is stored as part of the heap allocation that also holds the vector elements. diff --git a/docs/carray_api.md b/docs/carray_api.md index 1f42deb6..36cb3950 100644 --- a/docs/carray_api.md +++ b/docs/carray_api.md @@ -74,8 +74,8 @@ The **carray** elements can be accessed like `carray3i arr = ...; int val = arr. ## Example ```c -#include "stc/carray.h" #include +#include using_carray3(f, float); using_carray2(i, uint32_t); diff --git a/docs/cbits_api.md b/docs/cbits_api.md index 85a08fb1..80a20c6f 100644 --- a/docs/cbits_api.md +++ b/docs/cbits_api.md @@ -12,7 +12,7 @@ for a functional description. All cbits definitions and prototypes are available by including a single header file. ```c -#include "stc/cbits.h" +#include ``` ## Methods @@ -61,8 +61,8 @@ void cbits_xor(cbits *self, cbits other); ## Example ```c +#include #include -#include "stc/cbits.h" static inline cbits sieveOfEratosthenes(size_t n) { diff --git a/docs/cdeq_api.md b/docs/cdeq_api.md index 1783b948..4422655c 100644 --- a/docs/cdeq_api.md +++ b/docs/cdeq_api.md @@ -29,7 +29,7 @@ using_cdeq(str, cstr, cstr_compare_raw, cstr_del, cstr_from, cstr_c_str, const c All cdeq definitions and prototypes are available by including a single header file. ```c -#include "stc/cdeq.h" +#include ``` ## Methods @@ -104,8 +104,8 @@ cdeq_X_value_t cdeq_X_value_clone(cdeq_X_value_t val); ## Examples ```c -#include #include +#include using_cdeq(i, int); diff --git a/docs/clist_api.md b/docs/clist_api.md index a3497703..4114eeb6 100644 --- a/docs/clist_api.md +++ b/docs/clist_api.md @@ -36,7 +36,7 @@ using_clist(str, cstr, cstr_compare_raw, cstr_del, cstr_from, cstr_c_str, const All clist definitions and prototypes are available by including a single header file. ```c -#include "stc/clist.h" +#include ``` ## Methods @@ -130,8 +130,9 @@ clist_i_splice_after(&L2, clist_i_begin(&L2), &tmp); Interleave *push_front()* / *push_back()* then *sort()*: ```c +#include #include -#include "stc/clist.h" + using_clist(d, double); int main() { diff --git a/docs/cmap_api.md b/docs/cmap_api.md index 952ae772..7fccbc46 100644 --- a/docs/cmap_api.md +++ b/docs/cmap_api.md @@ -110,9 +110,8 @@ void c_trivial_del(Type* val); // doe ## Examples ```c -#include -#include "stc/cstr.h" -#include "stc/cmap.h" +#include +#include using_cmap_str(); @@ -154,8 +153,8 @@ The HEX of color BLACK is:[#000000] ### Example 2 This example uses a cmap with cstr as mapped value, by the `using_cmap_strval(id, int)` macro. ```c -#include "stc/cstr.h" -#include "stc/cmap.h" +#include +#include /* cmap: */ using_cmap_strval(id, int); @@ -190,7 +189,7 @@ Output: ### Example 3 Demonstrate cmap with plain-old-data key type Vec3i and int as mapped type: cmap. ```c -#include "stc/cmap.h" +#include #include typedef struct { int x, y, z; } Vec3i; @@ -224,7 +223,7 @@ Output: ### Example 4 Inverse: demonstrate cmap with mapped POD type Vec3i: cmap: ```c -#include "stc/cmap.h" +#include #include typedef struct { int x, y, z; } Vec3i; @@ -255,7 +254,6 @@ Output: ### Example 5 Advanced, rare usage: Complex key type. ```c -#include #include #include diff --git a/docs/coption_api.md b/docs/coption_api.md index e03c6b53..b205f449 100644 --- a/docs/coption_api.md +++ b/docs/coption_api.md @@ -41,8 +41,8 @@ int coption_get(coption *opt, int argc, char *argv[], ## Example ```c +#include #include -#include "stc/coption.h" int main(int argc, char *argv[]) { static coption_long long_options[] = { diff --git a/docs/cpque_api.md b/docs/cpque_api.md index f6e5d26b..44f35b22 100644 --- a/docs/cpque_api.md +++ b/docs/cpque_api.md @@ -23,7 +23,7 @@ Declaring `using_cpque(i, cvec_i, >)`, `X` should be replaced by `i` in the foll All cpque definitions and prototypes are available by including a single header file. ```c -#include "stc/cpque.h" +#include ``` ## Methods @@ -60,9 +60,9 @@ cpque_X_value_t cpque_X_value_clone(cpque_X_value_t val); ## Example ```c +#include +#include #include -#include "stc/cpque.h" -#include "stc/crandom.h" using_cvec(i, int64_t); using_cpque(i, cvec_i, >); // adaptor type, '>' = min-heap diff --git a/docs/cptr_api.md b/docs/cptr_api.md index 37f9abe3..4ef2e443 100644 --- a/docs/cptr_api.md +++ b/docs/cptr_api.md @@ -26,7 +26,7 @@ affect the names of all cptr types and methods. E.g. declaring `using_cptr(v4, V All cptr and csptr definitions and prototypes are available by including a single header file. ```c -#include "stc/cptr.h" +#include ``` ## Methods @@ -70,8 +70,8 @@ int csptr_X_compare(csptr_X* x, csptr_X* y); Managed raw pointers (cptr) in a cvec. ```c #include -#include #include +#include typedef struct { cstr name, last; } Person; diff --git a/docs/cqueue_api.md b/docs/cqueue_api.md index d1f889f0..b1ce475a 100644 --- a/docs/cqueue_api.md +++ b/docs/cqueue_api.md @@ -19,7 +19,7 @@ a **cdeq_X** or **clist_X** type as underlying implementation, given as `ctype`. All cqueue definitions and prototypes are available by including a single header file. ```c -#include "stc/cqueue.h" /* includes default underlying implementation header cdeq.h */ +#include /* includes default underlying implementation header cdeq.h */ ``` ## Methods @@ -61,26 +61,26 @@ cqueue_X_value_t cqueue_X_value_clone(cqueue_X_value_t val); ## Examples ```c +#include #include -#include "stc/cqueue.h" using_cdeq(i, int); using_cqueue(i, cdeq_i); int main() { - cqueue_i queue = cqueue_i_init(); + cqueue_i Q = cqueue_i_init(); // push() and pop() a few. c_forrange (i, 20) - cqueue_i_push(&queue, i); + cqueue_i_push(&Q, i); c_forrange (5) - cqueue_i_pop(&queue); + cqueue_i_pop(&Q); - c_foreach (i, cqueue_i, queue) + c_foreach (i, cqueue_i, Q) printf(" %d", *i.ref); - cqueue_i_del(&queue); + cqueue_i_del(&Q); } ``` Output: @@ -88,28 +88,29 @@ Output: 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 ``` ### Example 2 +Use clist as underlying cqueue implementation. ```c +#include +#include #include -#include "stc/cqueue.h" -#include "stc/clist.h" -using_cdeq(i, int); +using_clist(i, int); using_cqueue(i, clist_i); int main() { - cqueue_i queue = cqueue_i_init(); + cqueue_i Q = cqueue_i_init(); // push() and pop() a few. c_forrange (i, 20) - cqueue_i_push(&queue, i); + cqueue_i_push(&Q, i); c_forrange (5) - cqueue_i_pop(&queue); + cqueue_i_pop(&Q); - c_foreach (i, cqueue_i, queue) + c_foreach (i, cqueue_i, Q) printf(" %d", *i.ref); - cqueue_i_del(&queue); + cqueue_i_del(&Q); } ``` Output: diff --git a/docs/crandom_api.md b/docs/crandom_api.md index 36d66c3c..fb022179 100644 --- a/docs/crandom_api.md +++ b/docs/crandom_api.md @@ -31,7 +31,7 @@ xoshiro and pcg (Vigna/O'Neill) PRNGs: https://www.pcg-random.org/posts/on-vigna All crandom definitions and prototypes are available by including a single header file. ```c -#include "stc/crandom.h" +#include ``` ## Methods diff --git a/docs/cset_api.md b/docs/cset_api.md index 31e2a33a..04159cf9 100644 --- a/docs/cset_api.md +++ b/docs/cset_api.md @@ -24,7 +24,7 @@ be replaced by `i` in all of the following documentation. All cset definitions and prototypes are available by including a single header file. ```c -#include "stc/cset.h" +#include ``` ## Methods @@ -77,9 +77,8 @@ cset_X_value_t cset_X_value_clone(cset_X_value_t val); ## Example ```c -#include +#include #include -#include using_cset_str(); diff --git a/docs/csmap_api.md b/docs/csmap_api.md index bd877ca1..bf3d3525 100644 --- a/docs/csmap_api.md +++ b/docs/csmap_api.md @@ -95,9 +95,8 @@ csmap_X_value_t csmap_X_value_clone(csmap_X_value_t val); ## Examples ```c -#include -#include "stc/cstr.h" -#include "stc/csmap.h" +#include +#include using_csmap_str(); @@ -139,8 +138,8 @@ The HEX of color BLACK is:[#000000] ### Example 2 This example uses a csmap with cstr as mapped value, by the `using_csmap_strval(id, int)` macro. ```c -#include "stc/cstr.h" -#include "stc/csmap.h" +#include +#include /* csmap: */ using_csmap_strval(id, int); @@ -175,7 +174,7 @@ Output: ### Example 3 Demonstrate csmap with plain-old-data key type Vec3i and int as mapped type: csmap. ```c -#include "stc/csmap.h" +#include #include typedef struct { int x, y, z; } Vec3i; @@ -215,7 +214,7 @@ Output: ### Example 4 Inverse: demonstrate csmap with mapped POD type Vec3i: csmap: ```c -#include "stc/csmap.h" +#include #include typedef struct { int x, y, z; } Vec3i; diff --git a/docs/csset_api.md b/docs/csset_api.md index 3760a4c0..3d1996e8 100644 --- a/docs/csset_api.md +++ b/docs/csset_api.md @@ -25,7 +25,7 @@ be replaced by `i` in all of the following documentation. All csset definitions and prototypes are available by including a single header file. ```c -#include "stc/csset.h" +#include ``` ## Methods @@ -74,9 +74,8 @@ csset_X_value_t csset_X_value_clone(csset_X_value_t val); ## Example ```c -#include +#include #include -#include using_csset_str(); diff --git a/docs/cstack_api.md b/docs/cstack_api.md index 83e95199..9d644b5c 100644 --- a/docs/cstack_api.md +++ b/docs/cstack_api.md @@ -20,7 +20,7 @@ affect the names of all cstack types and methods. E.g. declaring `using_cstack(i All cstack definitions and prototypes are available by including a single header file. ```c -#include "stc/cstack.h" /* includes default underlying implementation header cvec.h */ +#include /* includes default underlying implementation header cvec.h */ ``` ## Methods @@ -61,22 +61,24 @@ cstack_X_value_t cstack_X_value_clone(cstack_X_value_t val); ## Example ```c +#include #include -#include "stc/cstack.h" using_cvec(i, int); using_cstack(i, cvec_i); int main() { - cstack_i stack = cstack_i_init(); + cstack_i S = cstack_i_init(); for (int i=0; i < 100; ++i) - cstack_i_push(&stack, i*i); + cstack_i_push(&S, i*i); for (int i=0; i < 90; ++i) - cstack_i_pop(&stack); + cstack_i_pop(&S); - printf("top: %d\n", *cstack_i_top(&stack)); + printf("top: %d\n", *cstack_i_top(&S)); + + cstack_i_del(&S); } ``` Output: diff --git a/docs/cstr_api.md b/docs/cstr_api.md index c248e482..5bc07b7d 100644 --- a/docs/cstr_api.md +++ b/docs/cstr_api.md @@ -10,7 +10,7 @@ See the c++ class [std::basic_string](https://en.cppreference.com/w/cpp/string/b All cstr definitions and prototypes are available by including a single header file. ```c -#include "stc/cstr.h" +#include ``` ## Methods diff --git a/docs/cvec_api.md b/docs/cvec_api.md index aa27f938..48bb5475 100644 --- a/docs/cvec_api.md +++ b/docs/cvec_api.md @@ -33,7 +33,7 @@ using_cvec(str, cstr, cstr_compare_raw, cstr_del, cstr_from, cstr_c_str, const c All cvec definitions and prototypes are available by including a single header file. ```c -#include "stc/cvec.h" +#include ``` ## Methods @@ -106,8 +106,9 @@ cvec_X_value_t cvec_X_value_clone(cvec_X_value_t val); ## Examples ```c +#include #include -#include "stc/cvec.h" + using_cvec(i, int); int main() @@ -143,8 +144,8 @@ sorted: 5 7 8 13 16 25 ``` ### Example 2 ```c -#include "stc/cstr.h" -#include "stc/cvec.h" +#include +#include using_cvec_str(); -- cgit v1.2.3