Updated docs.

16 files changed, 138 insertions, 117 deletions

diff --git a/docs/carray_api.md b/docs/carray_api.md
index 0e4e5643..920e1623 100644
--- a/docs/carray_api.md
+++ b/docs/carray_api.md
@@ -1,15 +1,16 @@
-# STC Container [carray](../stc/carray.h): Dynamic 1/2/3 Dimensional Array
+# STC [carray](../stc/carray.h): Dynamic 1/2/3 Dimensional Array
 ![Array](pics/array.jpg)
 
 This is 1D, 2D and 3D arrays, which are allocated from heap in one single contiguous block of memory.
 *carray3* may have sub-array "views" of *carray2* and *carray1* etc.
-See [boost::multi_array](https://www.boost.org/doc/libs/release/libs/multi_array) for similar c++ classes.
+
+See the c++ class [boost::multi_array](https://www.boost.org/doc/libs/release/libs/multi_array) for similar functionality.
 
 ## Declaration
 
 ```c
-#define using_carray(X, Value, valueDestroy=c_default_del, 
-                               valueClone=c_default_clone)
+using_carray(X, Value, valueDestroy=c_default_del, 
+                       valueClone=c_default_clone)
 ```
 The macro `using_carray()` can be instantiated with 2 or 4 arguments in the global scope.
 Default values are given above for args not specified. `X` and `N` are type tags and
diff --git a/docs/cbits_api.md b/docs/cbits_api.md
index 86b50f1e..07f5e072 100644
--- a/docs/cbits_api.md
+++ b/docs/cbits_api.md
@@ -1,9 +1,11 @@
-# STC Container [cbits](../stc/cbits.h): Bitset
+# STC [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.
+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).
+See the c++ class [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 a functional description.
 
 ## Header file
 
diff --git a/docs/cdeq_api.md b/docs/cdeq_api.md
index f118504a..ca4855da 100644
--- a/docs/cdeq_api.md
+++ b/docs/cdeq_api.md
@@ -1,18 +1,19 @@
-# STC Container [cdeq](../stc/cdeq.h): Double Ended Queue
+# STC [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. 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.
+
+See the c++ class [std::deque](https://en.cppreference.com/w/cpp/container/deque) for a functional description.
 
 ## Declaration
 
 ```c
-#define using_cdeq(X, Value, valueCompareRaw=c_default_compare,
-                             valueDestroy=c_default_del,
-                             valueFromRaw=c_default_clone,
-                             valueToRaw=c_default_to_raw,
-                             RawValue=Value)
-#define using_cdeq_str()
+using_cdeq(X, Value, valueCompareRaw=c_default_compare,
+                     valueDestroy=c_default_del,
+                     valueFromRaw=c_default_clone,
+                     valueToRaw=c_default_to_raw,
+                     RawValue=Value)
+using_cdeq_str()
 ```
 The macro `using_cdeq()` can be instantiated with 2, 3, 5, or 7 arguments in the global scope.
 Defaults values are given above for args not specified. `X` is a type tag name and
diff --git a/docs/clist_api.md b/docs/clist_api.md
index a8dfbe64..dd3a9a49 100644
--- a/docs/clist_api.md
+++ b/docs/clist_api.md
@@ -1,21 +1,28 @@
-# STC Container [clist](../stc/clist.h): Forward List
+# STC [clist](../stc/clist.h): Forward List
 ![List](pics/list.jpg)
 
-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.
+The **clist** container supports fast insertion and removal of elements from anywhere in the container.
+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.
 
-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.
+Unlike the similar c++ class *std::forward_list*, **clist** also supports *push_back()* (**O**(1) time).
+It is implemented as a circular singly-linked list. A **clist** object occupies only one pointer in memory,
+and like *std::forward_list* the length of the list is not stored. The method *clist_X_size()* is available,
+however computed in **O**(*n*) time.
 
-**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.
+See the c++ class [std::forward_list](https://en.cppreference.com/w/cpp/container/forward_list) for a functional description.
 
 ## Declaration
 
 ```c
-#define using_clist(X, Value, valueCompareRaw=c_default_compare,
-                              valueDestroy=c_default_del,
-                              valueFromRaw=c_default_clone,
-                              valueToRaw=c_default_to_raw,
-                              RawValue=Value)
-#define using_clist_str()
+using_clist(X, Value, valueCompareRaw=c_default_compare,
+                      valueDestroy=c_default_del,
+                      valueFromRaw=c_default_clone,
+                      valueToRaw=c_default_to_raw,
+                      RawValue=Value)
+using_clist_str()
 ```
 The macro `using_clist()` can be instantiated with 2, 3, 5, or 7 arguments in the global scope.
 Default values are given above for args not specified. `X` is a type tag name and
diff --git a/docs/cmap_api.md b/docs/cmap_api.md
index 2de13ac6..3fee4e66 100644
--- a/docs/cmap_api.md
+++ b/docs/cmap_api.md
@@ -1,33 +1,33 @@
-# STC Container [cmap](../stc/cmap.h): Unordered Map
+# STC [cmap](../stc/cmap.h): Unordered Map
 ![Map](pics/map.jpg)
 
-A **cmap** is an associative container that contains key-value pairs with unique keys. Search, insertion, and removal of elements have average constant-time complexity.
-Elements are pairs of keys and mapped values. Implemented as open hashing with linear probing and without storing tombstones. Very fast, see performance comparisons.
+A **cmap** is an associative container that contains key-value pairs with unique keys. Search, insertion,
+and removal of elements have average constant-time complexity. Internally, the elements are not sorted in any particular order, but organized into buckets. Which bucket an element is placed into depends entirely on the hash of its key. This allows fast access to individual elements, since once the hash is computed, it refers to the exact bucket the element is placed into. It is implemented as open hashing with linear probing, and without leaving tombstones on erase.
 
-Please refer to the documentation of the c++ class [std::unordered_map](https://en.cppreference.com/w/cpp/container/unordered_map) for a functional description.
+See the c++ class [std::unordered_map](https://en.cppreference.com/w/cpp/container/unordered_map) for a functional description.
 
 ## Declaration
 
 ```c
-#define using_cmap(X, Key, Mapped, keyEqualsRaw=c_default_equals,
-                                   keyHashRaw=c_default_hash,
-                                   mappedDestroy=c_default_del,
-                                   mappedClone=c_default_clone,
-                                   keyDestroy=c_default_del,
-                                   keyFromRaw=c_default_clone,
-                                   keyToRaw=c_default_to_raw,
-                                   RawKey=Key)
-
-#define using_cmap_strkey(X, Mapped, mappedDestroy=c_default_del,
-                                     mappedClone=c_default_clone)
-
-#define using_cmap_strval(X, Key, keyEquals=c_default_equals,
-                                  keyHash=c_default_hash,
-                                  keyDestroy=c_default_del,
-                                  keyFromRaw=c_default_clone,
-                                  keyToRaw=c_default_to_raw,
-                                  RawKey=Key)
-#define using_cmap_str()
+using_cmap(X, Key, Mapped, keyEqualsRaw=c_default_equals,
+                           keyHashRaw=c_default_hash,
+                           mappedDestroy=c_default_del,
+                           mappedClone=c_default_clone,
+                           keyDestroy=c_default_del,
+                           keyFromRaw=c_default_clone,
+                           keyToRaw=c_default_to_raw,
+                           RawKey=Key)
+
+using_cmap_strkey(X, Mapped, mappedDestroy=c_default_del,
+                             mappedClone=c_default_clone)
+
+using_cmap_strval(X, Key, keyEquals=c_default_equals,
+                          keyHash=c_default_hash,
+                          keyDestroy=c_default_del,
+                          keyFromRaw=c_default_clone,
+                          keyToRaw=c_default_to_raw,
+                          RawKey=Key)
+using_cmap_str()
 ```
 The macro `using_cmap()` can be instantiated with 3, 5, 7, 9, or 11 arguments in the global scope.
 Default values are given above for args not specified. `X` is a type tag name and
diff --git a/docs/coption_api.md b/docs/coption_api.md
index 66038b38..e03c6b53 100644
--- a/docs/coption_api.md
+++ b/docs/coption_api.md
@@ -1,6 +1,7 @@
-# STC Module [copt](../stc/coption.h): Command line argument parsing
+# STC [coption](../stc/coption.h): Command line argument parsing
 
 This describes the API of the *coption_get()* function for command line argument parsing.
+
 See [getopt_long](https://www.freebsd.org/cgi/man.cgi?getopt_long(3)) for a similar posix function.
 
 ## Types
diff --git a/docs/cpque_api.md b/docs/cpque_api.md
index 080d580e..e85b8bb9 100644
--- a/docs/cpque_api.md
+++ b/docs/cpque_api.md
@@ -8,7 +8,7 @@ See the c++ class [std::priority_queue](https://en.cppreference.com/w/cpp/contai
 ## Declaration
 
 ```c
-#define using_cpque(X, ctype, direction)
+using_cpque(X, ctype, direction)
 ```
 The macro `using_cpque()` must be instantiated in the global scope.
 **cpque** uses normally **cvec_X** or **cdeq_X** as underlying implementation, specified as `ctype`.
diff --git a/docs/cptr_api.md b/docs/cptr_api.md
index c44e08a3..f95b0062 100644
--- a/docs/cptr_api.md
+++ b/docs/cptr_api.md
@@ -1,20 +1,21 @@
-# STC Module [cptr](../stc/cptr.h): Smart Pointers
+# STC [cptr](../stc/cptr.h): Smart Pointers
 
-This module simplifies management of pointers in containers. The **csptr** type is similar to a c++
-[std::shared_ptr](https://en.cppreference.com/w/cpp/memory/shared_ptr).
+**cptr** (managed raw pointer) and **csptr** (shared pointer) enables memory managed pointers in containers.
 
-Raw pointers and shared pointers (**csptr**) may be used as items of containers. The pointed-to elements are automatically destructed and deleted when the container is destructed. **csptr** elements are only deleted if there are no other shared references to the element. **csptr** uses thread-safe atomic use-count, through the *csptr_X_clone(sp)* and *csptr_X_del(&sp)* methods.
+The pointed-to elements are automatically destructed and deleted when the container is destructed. **csptr** elements are only deleted if there are no other shared references to the element. **csptr** uses thread-safe atomic use-count, through the *csptr_X_clone()* and *csptr_X_del()* methods.
+
+ See the c++ classes [std::shared_ptr](https://en.cppreference.com/w/cpp/memory/shared_ptr) for a functional reference.
 
 ## Declaration
 
 ```c
-#define using_cptr(X, Value, valueCompare=c_default_compare,
-                             valueDestroy=c_default_del,
-                             valueClone=c_default_clone)
+using_cptr(X, Value, valueCompare=c_default_compare,
+                     valueDestroy=c_default_del,
+                     valueClone=c_default_clone)
 
-#define using_csptr(X, Value, valueCompare=c_default_compare,
-                              valueDestroy=c_default_del,
-                              valueClone=ignored)
+using_csptr(X, Value, valueCompare=c_default_compare,
+                      valueDestroy=c_default_del,
+                      valueClone=ignored)
 ```
 The macro `using_cptr()` must be instantiated in the global scope. `X` is a type tag name and will
 affect the names of all cptr types and methods. E.g. declaring `using_cptr(my, cvec_my);`,
diff --git a/docs/cqueue_api.md b/docs/cqueue_api.md
index 04454a0e..7a225e92 100644
--- a/docs/cqueue_api.md
+++ b/docs/cqueue_api.md
@@ -7,7 +7,7 @@ See the c++ class [std::queue](https://en.cppreference.com/w/cpp/container/queue
 
 ## Declaration
 ```c
-#define using_cqueue(X, ctype)
+using_cqueue(X, ctype)
 ```
 The macro `using_cqueue()` must be instantiated in the global scope. **cqueue** uses normally
 a **cdeq_X** or **clist_X** type as underlying implementation, given as `ctype`. See example below for usage.
diff --git a/docs/crandom_api.md b/docs/crandom_api.md
index c8ad34ff..1e93c4af 100644
--- a/docs/crandom_api.md
+++ b/docs/crandom_api.md
@@ -1,11 +1,12 @@
-# STC Module [crandom](../stc/crandom.h): Pseudo Random Number Generators
+# STC [crandom](../stc/crandom.h): Pseudo Random Number Generator
 ![Random](pics/random.jpg)
 
-This describes the API of module **crandom**. It contains **stc64**, a *64-bit PRNG*, and can generate
-bounded uniform and normal distributed random numbers. See [random](https://en.cppreference.com/w/cpp/header/random)
-for similar c++ functionality.
+This describes the API of module **crandom**. It features a *64-bit PRNG* named **stc64**,
+and can generate bounded uniform and normal distributed random numbers.
 
-**stc64** is an extremely fast PRNG by Tyge Løvset, suited for parallel usage. It features a
+See [random](https://en.cppreference.com/w/cpp/header/random) for similar c++ functionality.
+
+**stc64** is a novel, extremely fast PRNG by Tyge Løvset, suited for parallel usage. It features a
 Weyl-sequence as part of the state. It is faster than *sfc64*, *wyhash64*, *pcg64*, and *xoshiro256\*\**
 on common platforms. It does not require fast multiplication or 128-bit integer operations. It has a
 256 bit state, but updates only 192 bit per generated number.
diff --git a/docs/cset_api.md b/docs/cset_api.md
index 67bc4f92..a1303597 100644
--- a/docs/cset_api.md
+++ b/docs/cset_api.md
@@ -1,18 +1,19 @@
-# STC Container [cset](../stc/cmap.h): Unordered Set

+# STC [cset](../stc/cmap.h): Unordered Set

 ![Set](pics/set.jpg)

 

-A **cset** is an associative container that contains a set of unique objects of type Key. Search, insertion, and removal have average constant-time complexity. See [std::unordered_set](https://en.cppreference.com/w/cpp/container/unordered_set) for a similar c++ class.

+A **cset** is an associative container that contains a set of unique objects of type Key. Search, insertion, and removal have average constant-time complexity. See the c++ class 

+[std::unordered_set](https://en.cppreference.com/w/cpp/container/unordered_set) for a functional description.

 

 ## Declaration

 

 ```c

-#define using_cset(X, Key, keyEqualsRaw=c_default_equals,

-                           keyHashRaw=c_default_hash,

-                           keyDestroy=c_default_del,

-                           keyFromRaw=c_default_clone,

-                           keyToRaw=c_default_to_raw,                           

-                           RawKey=Key)

-#define using_cset_str()                           

+using_cset(X, Key, keyEqualsRaw=c_default_equals,

+                   keyHashRaw=c_default_hash,

+                   keyDestroy=c_default_del,

+                   keyFromRaw=c_default_clone,

+                   keyToRaw=c_default_to_raw,                           

+                   RawKey=Key)

+using_cset_str()                           

 ```

 The macro `using_cset()` can be instantiated with 2, 4, 6, or 8 arguments in the global scope.

 Default values are given above for args not specified. `X` is a type tag name and

@@ -26,7 +27,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"  // both cmap and cset

+#include "stc/cset.h"

 ```

 ## Methods

 

diff --git a/docs/csmap_api.md b/docs/csmap_api.md
index 3060811e..92457d2c 100644
--- a/docs/csmap_api.md
+++ b/docs/csmap_api.md
@@ -1,29 +1,30 @@
-# STC Container [csmap](../stc/csmap.h): Sorted Map
+# STC [csmap](../stc/csmap.h): Sorted Map
 ![Map](pics/smap.jpg)
 
 A **csmap** is a sorted associative container that contains key-value pairs with unique keys. Keys are sorted by using the comparison function *keyCompare*. Search, removal, and insertion operations have logarithmic complexity. **csmap** is implemented as an AA-tree.
-See [std::map](https://en.cppreference.com/w/cpp/container/map) for a similar c++ class.
+
+See the c++ class [std::map](https://en.cppreference.com/w/cpp/container/map) for a functional description.
 
 ## Declaration
 
 ```c
-#define using_csmap(X, Key, Mapped, keyCompareRaw=c_default_compare,
-                                    mappedDestroy=c_default_del,
-                                    mappedClone=c_default_clone,
-                                    keyDestroy=c_default_del,
-                                    keyFromRaw=c_default_clone,
-                                    keyToRaw=c_default_to_raw,
-                                    RawKey=Key)
-
-#define using_csmap_strkey(X, Mapped, mappedDestroy=c_default_del,
-                                      mappedClone=c_default_clone)
-
-#define using_csmap_strval(X, Key, keyCompare=c_default_compare,
-                                   keyDestroy=c_default_del,
-                                   keyFromRaw=c_default_clone,
-                                   keyToRaw=c_default_to_raw,
-                                   RawKey=Key)
-#define using_csmap_str()
+using_csmap(X, Key, Mapped, keyCompareRaw=c_default_compare,
+                            mappedDestroy=c_default_del,
+                            mappedClone=c_default_clone,
+                            keyDestroy=c_default_del,
+                            keyFromRaw=c_default_clone,
+                            keyToRaw=c_default_to_raw,
+                            RawKey=Key)
+
+using_csmap_strkey(X, Mapped, mappedDestroy=c_default_del,
+                              mappedClone=c_default_clone)
+
+using_csmap_strval(X, Key, keyCompare=c_default_compare,
+                           keyDestroy=c_default_del,
+                           keyFromRaw=c_default_clone,
+                           keyToRaw=c_default_to_raw,
+                           RawKey=Key)
+using_csmap_str()
 ```
 The macro `using_csmap()` can be instantiated with 3, 4, 6, 8, or 10 arguments in the global scope.
 Default values are given above for args not specified. `X` is a type tag name and
diff --git a/docs/csset_api.md b/docs/csset_api.md
index 4aded6a8..31210284 100644
--- a/docs/csset_api.md
+++ b/docs/csset_api.md
@@ -1,17 +1,19 @@
-# STC Container [csset](../stc/csmap.h): Sorted Set

+# STC [csset](../stc/csmap.h): Sorted Set

 ![Set](pics/sset.jpg)

 

-A **csset** is an associative container that contains a sorted set of unique objects of type *Key*. Sorting is done using the key comparison function *keyCompare*. Search, removal, and insertion operations have logarithmic complexity. **csset** is implemented as a AA-tree. See [std::set](https://en.cppreference.com/w/cpp/container/set) for a similar c++ class.

+A **csset** is an associative container that contains a sorted set of unique objects of type *Key*. Sorting is done using the key comparison function *keyCompare*. Search, removal, and insertion operations have logarithmic complexity. **csset** is implemented as a AA-tree.

+

+See the c++ class [std::set](https://en.cppreference.com/w/cpp/container/set) for a functional description.

 

 ## Declaration

 

 ```c

-#define using_csset(X, Key, keyCompare=c_default_compare,

-                            keyDestroy=c_default_del,

-                            keyFromRaw=c_default_clone,

-                            keyToRaw=c_default_to_raw,                           

-                            RawKey=Key)

-#define using_csset_str()                           

+using_csset(X, Key, keyCompare=c_default_compare,

+                    keyDestroy=c_default_del,

+                    keyFromRaw=c_default_clone,

+                    keyToRaw=c_default_to_raw,                           

+                    RawKey=Key)

+using_csset_str()                           

 ```

 The macro `using_csset()` can be instantiated with 2, 3, 5, or 7 arguments in the global scope.

 Default values are given above for args not specified. `X` is a type tag name and

@@ -25,7 +27,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" // both csmap and csset

+#include "stc/csset.h"

 ```

 ## Methods

 

diff --git a/docs/cstack_api.md b/docs/cstack_api.md
index b32e9dc5..764b258b 100644
--- a/docs/cstack_api.md
+++ b/docs/cstack_api.md
@@ -1,13 +1,14 @@
-# STC Container [cstack](../stc/cstack.h): Stack
+# STC [cstack](../stc/cstack.h): Stack
 ![Stack](pics/stack.jpg)
 
-This describes the API of the stack type **cstack**.
+The **cstack** is a container adapter that gives the programmer the functionality of a stack - specifically, a LIFO (last-in, first-out) data structure. The class template acts as a wrapper to the underlying container - only a specific set of functions is provided. The stack pushes and pops the element from the back of the underlying container, known as the top of the stack.
+
 See [std::stack](https://en.cppreference.com/w/cpp/container/stack) for a similar c++ class.
 
 ## Declaration
 
 ```c
-#define using_cstack(X, ctype)
+using_cstack(X, ctype)
 ```
 The macro `using_cstack()` must be instantiated in the global scope. **cstack** uses normally
 a **cvec_X** or **cdeq_X** type as underlying implementation, given as `ctype`. `X` is a type tag name and will
diff --git a/docs/cstr_api.md b/docs/cstr_api.md
index cab7aa3b..c6292906 100644
--- a/docs/cstr_api.md
+++ b/docs/cstr_api.md
@@ -1,7 +1,8 @@
-# STC Container [cstr](../stc/cstr.h): String
+# STC [cstr](../stc/cstr.h): String
 ![String](pics/string.jpg)
 
-This describes the API of string type **cstr**.
+A **cstr* is an object that represent sequences of characters. It supports an interface similar to that of a standard container of bytes, but adding features specifically designed to operate with strings of single-byte characters.
+
 See [std::basic_string](https://en.cppreference.com/w/cpp/string/basic_string) for a similar c++ class.
 
 ## Header file
diff --git a/docs/cvec_api.md b/docs/cvec_api.md
index a94d10e1..8cc7af15 100644
--- a/docs/cvec_api.md
+++ b/docs/cvec_api.md
@@ -1,22 +1,23 @@
-# STC Container [cvec](../stc/cvec.h): Vector
+# STC [cvec](../stc/cvec.h): Vector
 ![Vector](pics/vector.jpg)
 
 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.
 
+See the c++ class [std::vector](https://en.cppreference.com/w/cpp/container/vector) for a functional description.
+
 ## Declaration
 
 ```c
-#define using_cvec(X, Value, valueCompareRaw=c_default_compare,
-                             valueDestroy=c_default_del,
-                             valueFromRaw=c_default_clone,
-                             valueToRaw=c_default_to_raw,
-                             RawValue=Value)
-#define using_cvec_str()
+using_cvec(X, Value, valueCompareRaw=c_default_compare,
+                     valueDestroy=c_default_del,
+                     valueFromRaw=c_default_clone,
+                     valueToRaw=c_default_to_raw,
+                     RawValue=Value)
+using_cvec_str()
 ```
 The macro `using_cvec()` can be instantiated with 2, 3, 5, or 7 arguments in the global scope.
 Defaults values are given above for args not specified. `X` is a type tag name and