Renamed cbitset to cbits. Added more docs.

10 files changed, 137 insertions, 127 deletions

diff --git a/docs/cbits_api.md b/docs/cbits_api.md
new file mode 100644
index 00000000..f2e135fd
--- /dev/null
+++ b/docs/cbits_api.md
@@ -0,0 +1,116 @@
+# STC Container [cbits](../stc/cbits.h): Bitset
+![Bitset](pics/bitset.jpg)
+
+A **cbits** represents a set of bits. It provides accesses to the value of individual bits via *cbits_test()* and provides the bitwise operators that one can apply to builtin integers. The number of bits in the set is specified at runtime via a parameter to the constructor *cbits_with_size()* or by *cbits_resize()*. A **cbits* bitset can be manipulated by standard logic operators and converted to and from strings.
+
+The **cbits** container is similar to the c++ class [std::bitset](https://en.cppreference.com/w/cpp/utility/bitset) and [boost::dynamic_bitset](https://www.boost.org/doc/libs/release/libs/dynamic_bitset/dynamic_bitset.html).
+
+## Types
+
+| cbits               | Type definition           | Used to represent...         |
+|:--------------------|:--------------------------|:-----------------------------|
+| `cbits`             | `struct { ... }`          | The cbits type               |
+| `cbits_iter_t`      | `struct { ... }`          | The cbits iterator type      |
+
+## Header file
+
+All cstr definitions and prototypes may be included in your C source file by including a single header file.
+
+```c
+#include "stc/cbits.h"
+```
+## Methods
+
+```c
+cbits            cbits_init(void);
+cbits            cbits_with_size(size_t size, bool value);
+cbits            cbits_from_str(const char* str);
+
+cbits            cbits_clone(cbits_t other);
+void             cbits_resize(cbits_t* self, size_t size, bool value);
+
+cbits            cbits_intersect(cbits_t s1, cbits_t s2);
+cbits            cbits_union(cbits_t s1, cbits_t s2);
+cbits            cbits_xor(cbits_t s1, cbits_t s2);
+cbits            cbits_not(cbits_t s1);
+
+void             cbits_del(cbits_t* self);
+
+cbits*           cbits_assign(cbits_t* self, cbits_t other);
+cbits*           cbits_take(cbits_t* self, cbits_t other);
+cbits            cbits_move(cbits_t* self);
+
+size_t           cbits_size(cbits_t set);
+size_t           cbits_count(cbits_t set);
+bool             cbits_is_disjoint(cbits_t set, cbits_t other);
+bool             cbits_is_subset(cbits_t set, cbits_t other);
+bool             cbits_is_superset(cbits_t set, cbits_t other);
+char*            cbits_to_str(cbits_t set, char* str, size_t start, intptr_t stop);
+
+void             cbits_set(cbits_t *self, size_t i);
+void             cbits_reset(cbits_t *self, size_t i);
+void             cbits_set_value(cbits_t *self, size_t i, bool value);
+void             cbits_flip(cbits_t *self, size_t i);
+bool             cbits_test(cbits_t set, size_t i);
+void             cbits_set_all(cbits_t *self, bool value);
+void             cbits_set_all64(cbits_t *self, uint64_t pattern);
+void             cbits_flip_all(cbits_t *self);
+
+void             cbits_intersect_with(cbits_t *self, cbits_t other);
+void             cbits_union_with(cbits_t *self, cbits_t other);
+void             cbits_xor_with(cbits_t *self, cbits_t other);
+
+cbits_iter_t     cbits_begin(cbits_t* self);
+cbits_iter_t     cbits_end(cbits_t* self);
+void             cbits_next(cbits_iter_t* it);
+bool             cbits_itval(cbits_iter_t it);
+```
+
+## Example
+```c
+#include <stdio.h>
+#include "stc/cbits.h"
+
+static inline cbits sieveOfEratosthenes(size_t n)
+{
+    cbits primes = cbits_with_size(n + 1, true);
+    cbits_reset(&primes, 0);
+    cbits_reset(&primes, 1);
+
+    c_forrange (i, size_t, 2, n+1) {
+        // If primes[i] is not changed, then it is a prime
+        if (cbits_test(primes, i) && i*i <= n) {
+            c_forrange (j, size_t, i*i, n+1, i) {
+                cbits_reset(&primes, j);
+            }
+        }
+    }
+    return primes;
+}
+
+int main(void)
+{
+    int n = 100000000;
+    printf("computing prime numbers up to %u\n", n);
+
+    cbits primes = sieveOfEratosthenes(n);
+    puts("done");
+
+    size_t np = cbits_count(primes);
+    printf("number of primes: %zu\n", np);
+
+    printf("2 ");
+    c_forrange (i, int, 3, 1001, 2) {
+       if (cbits_test(primes, i)) printf("%d ", i);
+    }
+    puts("");
+    cbits_del(&primes);
+}
+```
+Output:
+```
+computing prime numbers up to 100000000
+done
+number of primes: 5761455
+2 3 5 7 11 13 17 19 23 29 31 37 41 43 47 53 59 61 67 71 73 79 83 89 97 101 103 107 109 113 127 131 137 139 149 151 157 163 167 173 179 181 191 193 197 199 211 223 227 229 233 239 241 251 257 263 269 271 277 281 283 293 307 311 313 317 331 337 347 349 353 359 367 373 379 383 389 397 401 409 419 421 431 433 439 443 449 457 461 463 467 479 487 491 499 503 509 521 523 541 547 557 563 569 571 577 587 593 599 601 607 613 617 619 631 641 643 647 653 659 661 673 677 683 691 701 709 719 727 733 739 743 751 757 761 769 773 787 797 809 811 821 823 827 829 839 853 857 859 863 877 881 883 887 907 911 919 929 937 941 947 953 967 971 977 983 991 997
+```
diff --git a/docs/cbitset_api.md b/docs/cbitset_api.md
deleted file mode 100644
index 7a5f1210..00000000
--- a/docs/cbitset_api.md
+++ /dev/null
@@ -1,115 +0,0 @@
-# STC Container [cbitset](../stc/cbitset.h): Bitset
-![Bitset](pics/bitset.jpg)
-
-A **cbitset** represents a resizable sequence of N bits. Bitsets can be manipulated by standard logic operators and converted to and from strings and integers. See [std::bitset](https://en.cppreference.com/w/cpp/utility/bitset) or
-[boost::dynamic_bitset](https://www.boost.org/doc/libs/release/libs/dynamic_bitset/dynamic_bitset.html) for similar c++ classes.
-
-## Types
-
-| cbitset               | Type definition           | Used to represent...                 |
-|:----------------------|:--------------------------|:-------------------------------------|
-| `cbitset_t`           | `struct { ... }`          | The cbitset type                     |
-| `cbitset_iter_t`      | `struct { ... }`          | The cbitset iterator type            |
-
-## Header file
-
-All cstr definitions and prototypes may be included in your C source file by including a single header file.
-
-```c
-#include "stc/cbitset.h"
-```
-## Methods
-
-```c
-cbitset_t        cbitset_init(void);
-cbitset_t        cbitset_with_size(size_t size, bool value);
-cbitset_t        cbitset_from_str(const char* str);
-
-cbitset_t        cbitset_clone(cbitset_t other);
-void             cbitset_resize(cbitset_t* self, size_t size, bool value);
-
-cbitset_t        cbitset_intersect(cbitset_t s1, cbitset_t s2);
-cbitset_t        cbitset_union(cbitset_t s1, cbitset_t s2);
-cbitset_t        cbitset_xor(cbitset_t s1, cbitset_t s2);
-cbitset_t        cbitset_not(cbitset_t s1);
-
-void             cbitset_del(cbitset_t* self);
-
-cbitset_t*       cbitset_assign(cbitset_t* self, cbitset_t other);
-cbitset_t*       cbitset_take(cbitset_t* self, cbitset_t other);
-cbitset_t        cbitset_move(cbitset_t* self);
-
-size_t           cbitset_size(cbitset_t set);
-size_t           cbitset_count(cbitset_t set);
-bool             cbitset_is_disjoint(cbitset_t set, cbitset_t other);
-bool             cbitset_is_subset(cbitset_t set, cbitset_t other);
-bool             cbitset_is_superset(cbitset_t set, cbitset_t other);
-char*            cbitset_to_str(cbitset_t set, char* str, size_t start, intptr_t stop);
-
-void             cbitset_set(cbitset_t *self, size_t i);
-void             cbitset_reset(cbitset_t *self, size_t i);
-void             cbitset_set_value(cbitset_t *self, size_t i, bool value);
-void             cbitset_flip(cbitset_t *self, size_t i);
-bool             cbitset_test(cbitset_t set, size_t i);
-void             cbitset_set_all(cbitset_t *self, bool value);
-void             cbitset_set_all64(cbitset_t *self, uint64_t pattern);
-void             cbitset_flip_all(cbitset_t *self);
-
-void             cbitset_intersect_with(cbitset_t *self, cbitset_t other);
-void             cbitset_union_with(cbitset_t *self, cbitset_t other);
-void             cbitset_xor_with(cbitset_t *self, cbitset_t other);
-
-cbitset_iter_t   cbitset_begin(cbitset_t* self);
-cbitset_iter_t   cbitset_end(cbitset_t* self);
-void             cbitset_next(cbitset_iter_t* it);
-bool             cbitset_itval(cbitset_iter_t it);
-```
-
-## Example
-```c
-#include <stdio.h>
-#include "stc/cbitset.h"
-
-static inline cbitset_t sieveOfEratosthenes(size_t n)
-{
-    cbitset_t pbits = cbitset_with_size(n + 1, true);
-    cbitset_reset(&pbits, 0);
-    cbitset_reset(&pbits, 1);
-
-    c_forrange (i, size_t, 2, n+1) {
-        // If pbits[i] is not changed, then it is a prime
-        if (cbitset_test(pbits, i) && i*i <= n) {
-            c_forrange (j, size_t, i*i, n+1, i) {
-                cbitset_reset(&pbits, j);
-            }
-        }
-    }
-    return pbits;
-}
-
-int main(void)
-{
-    int n = 100000000;
-    printf("computing prime numbers up to %u\n", n);
-
-    cbitset_t primes = sieveOfEratosthenes(n);
-    puts("done");
-
-    size_t np = cbitset_count(primes);
-    printf("number of primes: %zu\n", np);
-
-    printf("2 ");
-    c_forrange (i, int, 3, 1001, 2) {
-       if (cbitset_test(primes, i)) printf("%d ", i);
-    }
-    puts("");
-    cbitset_del(&primes);
-}
-```
-Output:
-```
-computing prime numbers up to 100000000
-done
-number of primes: 5761455
-2 3 5 7 11 13 17 19 23 29 31 37 41 43 47 53 59 61 67 71 73 79 83 89 97 101 103 107 109 113 127 131 137 139 149 151 157 163 167 173 179 181 191 193 197 199 211 223 227 229 233 239 241 251 257 263 269 271 277 281 283 293 307 311 313 317 331 337 347 349 353 359 367 373 379 383 389 397 401 409 419 421 431 433 439 443 449 457 461 463 467 479 487 491 499 503 509 521 523 541 547 557 563 569 571 577 587 593 599 601 607 613 617 619 631 641 643 647 653 659 661 673 677 683 691 701 709 719 727 733 739 743 751 757 761 769 773 787 797 809 811 821 823 827 829 839 853 857 859 863 877 881 883 887 907 911 919 929 937 941 947 953 967 971 977 983 991 997
-```
diff --git a/docs/cdeq_api.md b/docs/cdeq_api.md
index 83c2779e..7bc68b88 100644
--- a/docs/cdeq_api.md
+++ b/docs/cdeq_api.md
@@ -1,7 +1,7 @@
 # STC Container [cdeq](../stc/cdeq.h): Double Ended Queue
 ![Deque](pics/deque.jpg)
 
-A **cdeq** is an indexed sequence container that allows fast insertion and deletion at both its beginning and its end.
+A **cdeq** is an indexed sequence container that allows fast insertion and deletion at both its beginning and its end. Note that this container is implemented similar to a vector, but has the same performance profile for both *push_back()* and *push_front()* as *cvec_X_push_back()*. Iterators may be invalidated after push-operations.
 See [std::deque](https://en.cppreference.com/w/cpp/container/deque) for a similar c++ class.
 
 ## Declaration
diff --git a/docs/clist_api.md b/docs/clist_api.md
index 767d5f24..53e3b350 100644
--- a/docs/clist_api.md
+++ b/docs/clist_api.md
@@ -1,10 +1,11 @@
 # STC Container [clist](../stc/clist.h): Forward List
 ![List](pics/list.jpg)
 
-This is similar to c++ [std::forward_list](https://en.cppreference.com/w/cpp/container/forward_list), but supports both
-*push_front()* and *push_back()* as well as *pop_front()* in **O**(1) time. Implemented as a circular singly linked list.
-Also supports various *splice* functions and *merge-sort*. Note that like std::forward_list, the representation size of **clist**
-is only one pointer, and length of the list is not stored. The method *clist_X_size()* is therefore computed in **O**(*n*) time.
+The **clist** container supports fast insertion and removal of elements from anywhere in the container. It is similar to the c++ [std::forward_list](https://en.cppreference.com/w/cpp/container/forward_list), but **clist** also supports *push_back()* (**O**(1) time). It is implemented as a circular singly-linked list. Fast random access is not supported.
+
+Adding, removing and moving the elements within the list, or across several lists, does not invalidate the iterators currently referring to other elements in the list. However, an iterator or reference referring to an element is invalidated when the corresponding element is removed (via *erase_after*) from the list.
+
+**clist** also supports various *splice* functions and *merge-sort*. **clist** itself occupies only one pointer in memory, like *std::forward_list*, the length of **clist** is not stored. The method *clist_X_size()* is available, however computed in **O**(*n*) time.
 
 ## Declaration
 
diff --git a/docs/cpque_api.md b/docs/cpque_api.md
index c402ea24..10a40043 100644
--- a/docs/cpque_api.md
+++ b/docs/cpque_api.md
@@ -1,16 +1,20 @@
 # STC Container [cpque](../stc/cpque.h): Priority Queue
 
-This describes the API of the priority queue type **cpque**. It is implemented as a heap.
+A priority queue is a container adaptor that provides constant time lookup of the largest (by default) element, at the expense of logarithmic insertion and extraction.
+
 See [std::priority_queue](https://en.cppreference.com/w/cpp/container/priority_queue) for a similar c++ class.
 
+Working with a priority_queue is similar to managing a heap in some random access container, with the benefit of not being able to accidentally invalidate the heap.
+
 ## Declaration
 
 ```c
 #define using_cpque(X, ctype, heap_variant)
 ```
 The macro `using_cpque()` must be instantiated in the global scope.
-**cpque** uses normally a **cvec** type as underlying implementation, specified as `ctype`.
-The `heap_variant` must be given as `<` or `>`, specifying *max-heap* or *min-heap* for the priority queue.
+**cpque** uses normally **cvec_X** or **cdeq_X** as underlying implementation, specified as `ctype`.
+The `heap_variant` must be given as `<` or `>`, specifying *max-heap* or *min-heap* for the priority queue to change the ordering, e.g. `>` would cause the smallest element to appear as the *cpque_X_top()*.
+
 Note that the function `{ctype}_value_compare(x, y)` defined by the underlying vector type is used to
 compare values (priorities). `X` is a type tag name and will affect the names of all cpque types and methods.
 Declaring `using_cpque(my, cvec_my, >);`, `X` should be replaced by `my` in the following documentation.
diff --git a/docs/cqueue_api.md b/docs/cqueue_api.md
index b399a14c..96b46c64 100644
--- a/docs/cqueue_api.md
+++ b/docs/cqueue_api.md
@@ -10,7 +10,7 @@ See [std::queue](https://en.cppreference.com/w/cpp/container/queue) for a simila
 #define using_cqueue(X, ctype)
 ```
 The macro `using_cqueue()` must be instantiated in the global scope. **cqueue** uses normally
-a **clist** type as underlying implementation, given as `ctype`. `X` is a type tag name and
+a **cdeq_X** or **clist_X** type as underlying implementation, given as `ctype`. `X` is a type tag name and
 will affect the names of all cqueue types and methods. E.g. declaring `using_cqueue(my, clist_my);`,
 `X` should be replaced by `my` in all of the following documentation.
 
diff --git a/docs/cset_api.md b/docs/cset_api.md
index 9efd261c..4fe694e7 100644
--- a/docs/cset_api.md
+++ b/docs/cset_api.md
@@ -44,7 +44,7 @@ be replaced by `my` in all of the following documentation.
 All cset definitions and prototypes may be included in your C source file by including a single header file.

 

 ```c

-#include "stc/cmap.h"

+#include "stc/cmap.h"  // both cmap and cset

 ```

 ## Methods

 

diff --git a/docs/csset_api.md b/docs/csset_api.md
index 88b44168..23510763 100644
--- a/docs/csset_api.md
+++ b/docs/csset_api.md
@@ -38,7 +38,7 @@ be replaced by `my` in all of the following documentation.
 All csset definitions and prototypes may be included in your C source file by including a single header file.

 

 ```c

-#include "stc/csmap.h"

+#include "stc/csmap.h" // both csmap and csset

 ```

 ## Methods

 

diff --git a/docs/cstack_api.md b/docs/cstack_api.md
index 04927112..5a2516b8 100644
--- a/docs/cstack_api.md
+++ b/docs/cstack_api.md
@@ -10,7 +10,7 @@ See [std::stack](https://en.cppreference.com/w/cpp/container/stack) for a simila
 #define using_cstack(X, ctype)
 ```
 The macro `using_cstack()` must be instantiated in the global scope. **cstack** uses normally
-a **cvec** type as underlying implementation, given as `ctype`. `X` is a type tag name and will
+a **cvec_X** or **cdeq_X** type as underlying implementation, given as `ctype`. `X` is a type tag name and will
 affect the names of all cstack types and methods. E.g. declaring `using_cstack(my, cvec_my);`,
 `X` should be replaced by `my` in all of the following documentation.
 
diff --git a/docs/cvec_api.md b/docs/cvec_api.md
index 53c9e0f2..b19cf436 100644
--- a/docs/cvec_api.md
+++ b/docs/cvec_api.md
@@ -4,6 +4,10 @@
 A **cvec** is a sequence container that encapsulates dynamic size arrays.
 See [std::vector](https://en.cppreference.com/w/cpp/container/vector) for a similar c++ class.
 
+The storage of the vector is handled automatically, being expanded and contracted as needed. Vectors usually occupy more space than static arrays, because more memory is allocated to handle future growth. This way a vector does not need to reallocate each time an element is inserted, but only when the additional memory is exhausted. The total amount of allocated memory can be queried using *cvec_X_capacity()* function. Extra memory can be returned to the system via a call to *cvec_X_shrink_to_fit()*.
+
+Reallocations are usually costly operations in terms of performance. The *cvec_X_reserve()* function can be used to eliminate reallocations if the number of elements is known beforehand.
+
 ## Declaration
 
 ```c