Preparation for merging in V2.0 to master branch.

6 files changed, 32 insertions, 26 deletions

diff --git a/README.md b/README.md
index a088092d..00cd9531 100644
--- a/README.md
+++ b/README.md
@@ -3,6 +3,13 @@
 STC - Standard Template Containers for C

 ========================================

 

+News

+----

+**VERSION 2.X RELEASED**: This main version uses a different way to instantiate templated containers,

+and is not compatible with v1.X, however the usage is otherwise compatible with v1.X. The new style

+has multiple advantages, e.g. implementation does no longer contain long macro definitions to generate

+code. Also, specfiying template arguments is more user friendly and flexible.

+

 Introduction

 ------------

 A modern, templated, user-friendly, fast, fully type-safe, and customizable container library for C99,

@@ -12,7 +19,7 @@ For an introduction to templated containers, please read the blog by Ian Fisher
 

 STC is a compact, header-only library with the all the major "standard" data containers, except for the

 multimap/set variants. However, there is an example how to create a multimap in the examples folder.

-- [***carrN*** - **2D and 3D dynamic array** type](docs/carray_api.md)

+- [***carr2, carr3*** - **2d** and **3d** dynamic **array** type](docs/carray_api.md)

 - [***cbits*** - **std::bitset** alike type](docs/cbits_api.md)

 - [***cdeq*** - **std::deque** alike type](docs/cdeq_api.md)

 - [***clist*** - **std::forward_list** alike type](docs/clist_api.md)

@@ -29,7 +36,7 @@ multimap/set variants. However, there is an example how to create a multimap in
 - [***cvec*** - **std::vector** alike type](docs/cvec_api.md)

 

 Others:

-- [***crandom*** - A novel extremely fast *PRNG* named **stc64**](docs/crandom_api.md)

+- [***crandom*** - A novel very fast *PRNG* named **stc64**](docs/crandom_api.md)

 - [***ccommon*** - Some handy macros and general definitions](docs/ccommon_api.md)

 

 Highlights

@@ -192,33 +199,33 @@ in your build environment and place all the instantiations of containers used in
 #define i_tag ii

 #define i_key int

 #define i_val int

-#include <stc/cmap.h>  // cmap int => int

+#include <stc/cmap.h>  // cmap_ii: int => int

 

 #define i_tag ix

 #define i_key int64_t

-#include <stc/cset.h>  // cset int64_t

+#include <stc/cset.h>  // cset_ix

 

 #define i_val int

-#include <stc/cvec.h>  // cvec int

+#include <stc/cvec.h>  // cvec_int

 

 #define i_tag pnt

 #define i_val Point

-#include <stc/clist.h> // clist Point

+#include <stc/clist.h> // clist_pnt

 ```

 

 The *emplace* versus non-emplace container methods

 --------------------------------------------------

 STC, like c++ STL, has two sets of methods for adding elements to containers. One set begins

 with **emplace**, e.g. **cvec_X_emplace_back()**. This is a convenient alternative to

-**cvec_X_push_back()** when dealing non-trivial container elements, e.g. smart pointers or

-elements using dynamic memory.

+**cvec_X_push_back()** when dealing non-trivial container elements, e.g. strings, shared pointers or

+other elements using dynamic memory or shared resources.

 

-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. 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 ***constructs*** or ***clones*** the given elements before they are added

+to the container. In contrast, the *non-emplace* methods ***moves*** the given elements into the

+container. For containers of integral or trivial element types, **emplace** and corresponding

+*non-emplace* methods are identical.

 

-| Move and insert element   | Construct element in-place   | Container                                   |

+| non-emplace: Move         | emplace: Clone               | Container                                   |

 |:--------------------------|:-----------------------------|:--------------------------------------------|

 | insert()                  | emplace()                    | cmap, cset, csmap, csset, cvec, cdeq, clist |

 | insert_or_assign(), put() | emplace_or_assign()          | cmap, csmap                                 |

@@ -230,7 +237,7 @@ Strings are the most commonly used non-trivial data type. STC containers have pr
 definitions for cstr container elements, so they are fail-safe to use both with the **emplace**

 and non-emplace methods:

 ```c

-#define i_val_str

+#define i_val_str       // special macro to enable container of cstr

 #include <stc/cvec.h>   // vector of string (cstr)

 ...

 c_forvar (cvec_str vec = cvec_str_init(), cvec_str_del(&vec))   // defer vector destructor to end of block

diff --git a/include/stc/alt/clist.h b/benchmarks/others/old/clist.h
index 10d8092e..10d8092e 100644
--- a/include/stc/alt/clist.h
+++ b/benchmarks/others/old/clist.h
diff --git a/include/stc/alt/csmap.h b/benchmarks/others/old/csmap.h
index 88c3967a..88c3967a 100644
--- a/include/stc/alt/csmap.h
+++ b/benchmarks/others/old/csmap.h
diff --git a/docs/carray_api.md b/docs/carray_api.md
index 44f3c8a0..71d27390 100644
--- a/docs/carray_api.md
+++ b/docs/carray_api.md
@@ -1,9 +1,8 @@
-# STC [carray](../include/stc/carray.h): Dynamic Multi-dimensional Array
+# STC [carr2, carr3](../include/stc/carray.h): Dynamic Multi-dimensional Arrays
 ![Array](pics/array.jpg)
 
-The **carr2** and **carr3** are templated 2D and 3D containers arrays. They are allocated on the heap as a single
-contiguous block of memory. The arrays can be indexed like regular constant size multi-dimensional arrays in C,
-which also store data as one contiguous block of memory.
+The **carr2** and **carr3** are templated 2D and 3D dynamic arrays. They are allocated on the heap as a single
+contiguous block of memory. The arrays can be indexed like regular constant size multi-dimensional arrays in C.
 
 See the c++ class [boost::multi_array](https://www.boost.org/doc/libs/release/libs/multi_array) for similar functionality.
 
diff --git a/examples/mmap.c b/examples/mmap.c
index 823d1d2b..1cf145d6 100644
--- a/examples/mmap.c
+++ b/examples/mmap.c
@@ -60,7 +60,7 @@ int main()
         clist_str_iter_t pos;

         c_foreach (e, csmap_mult, mmap)

             if ((pos = clist_str_find(&e.ref->second, "bar")).ref != clist_str_end(&e.ref->second).ref) {

-                clist_str_erase(&e.ref->second, pos);

+                clist_str_erase_at(&e.ref->second, pos);

                 break;

             }

         print(mmap);

diff --git a/examples/sharedptr.c b/examples/sharedptr.c
index a8132fee..40e1be6f 100644
--- a/examples/sharedptr.c
+++ b/examples/sharedptr.c
@@ -5,19 +5,19 @@ void int_del(int* x) {
 }

 

 #define i_val int

-#define i_valdel int_del

-#include <stc/csptr.h>

+#define i_valdel int_del  // optional func to show elements destroyed

+#include <stc/csptr.h>    // define csptr_int shared pointers

 

-#define i_key_csptr int

-#include <stc/csset.h>

+#define i_key_csptr int   // refer to csptr_int definition above

+#include <stc/csset.h>    // define a sorted set of csptr_int

 

 #define i_val_csptr int

 #include <stc/cvec.h>

 

 int main()

 {

-    c_forauto (cvec_int, vec) // raii

-    c_forauto (csset_int, set) // raii

+    c_forauto (cvec_int, vec)   // declare and init vec, call del at scope exit

+    c_forauto (csset_int, set)  // declare and init set, call del at scope exit

     {

         cvec_int_push_back(&vec, csptr_int_make(2021));

         cvec_int_push_back(&vec, csptr_int_make(2012));

@@ -31,7 +31,7 @@ int main()
         // add odd numbers from vec to set

         c_foreach (i, cvec_int, vec)

             if (*i.ref->get & 1)

-                csset_int_emplace(&set, *i.ref); // copy shared pointer => increments ref.

+                csset_int_emplace(&set, *i.ref); // copy shared pointer => increments counter.

 

         // erase the two last elements in vec

         cvec_int_pop_back(&vec);