Merge branch 'stclib:master' into modifiedHEADmodified

1 files changed, 46 insertions, 48 deletions

diff --git a/docs/cdeq_api.md b/docs/cdeq_api.md
index fc11fe66..3ce58e78 100644
--- a/docs/cdeq_api.md
+++ b/docs/cdeq_api.md
@@ -1,24 +1,27 @@
 # STC [cdeq](../include/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 *cdeq_X_push_back()*. Iterators may be invalidated after push-operations.
+A **cdeq** is an indexed sequence container that allows fast insertion and deletion at both
+its beginning and its end, but has also fast random access to elements. The container is
+implemented as a circular dynamic buffer. Iterators may be invalidated after push-operations.
 
 See the c++ class [std::deque](https://en.cppreference.com/w/cpp/container/deque) for a functional description.
 
 ## Header file and declaration
 
 ```c
-#define i_type      // full typename of the container
-#define i_val       // value: REQUIRED
-#define i_cmp       // three-way compare two i_valraw* : REQUIRED IF i_valraw is a non-integral type
-#define i_valdrop   // destroy value func - defaults to empty destruct
-#define i_valclone  // REQUIRED IF i_valdrop defined
-
-#define i_valraw    // convertion "raw" type - defaults to i_val
-#define i_valfrom   // convertion func i_valraw => i_val
-#define i_valto     // convertion func i_val* => i_valraw
-
-#define i_tag       // alternative typename: cdeq_{i_tag}. i_tag defaults to i_val
+#define i_key <t>      // element type: REQUIRED. Note: i_val* may be specified instead of i_key*.
+#define i_type <t>     // cdeq container type name
+#define i_cmp <f>      // three-way compare of two i_keyraw*.
+#define i_use_cmp      // define instead of i_cmp only when i_key is an integral/native-type.
+#define i_keydrop <f>  // destroy value func - defaults to empty destruct
+#define i_keyclone <f> // REQUIRED IF i_keydrop is defined
+
+#define i_keyraw <t>   // convertion "raw" type - defaults to i_key
+#define i_keyfrom <f>  // convertion func i_keyraw => i_key
+#define i_keyto <f>    // convertion func i_key* => i_keyraw
+
+#define i_tag <s>      // alternative typename: cdeq_{i_tag}. i_tag defaults to i_key
 #include <stc/cdeq.h>
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.
@@ -32,81 +35,76 @@ cdeq_X              cdeq_X_clone(cdeq_X deq);
 
 void                cdeq_X_clear(cdeq_X* self);
 void                cdeq_X_copy(cdeq_X* self, const cdeq_X* other);
-cdeq_X_iter         cdeq_X_copy_range(cdeq_X* self, i_val* pos, const i_val* p1, const i_val* p2);
 bool                cdeq_X_reserve(cdeq_X* self, intptr_t cap);
 void                cdeq_X_shrink_to_fit(cdeq_X* self);
-void                cdeq_X_drop(cdeq_X* self);                                          // destructor
+void                cdeq_X_drop(cdeq_X* self);                                      // destructor
 
 bool                cdeq_X_empty(const cdeq_X* self);
 intptr_t            cdeq_X_size(const cdeq_X* self);
 intptr_t            cdeq_X_capacity(const cdeq_X* self);
 
 const cdeq_X_value* cdeq_X_at(const cdeq_X* self, intptr_t idx);
-const cdeq_X_value* cdeq_X_get(const cdeq_X* self, i_valraw raw);                       // return NULL if not found
-cdeq_X_value*       cdeq_X_get_mut(cdeq_X* self, i_valraw raw);                         // mutable get
-cdeq_X_iter         cdeq_X_find(const cdeq_X* self, i_valraw raw);
-cdeq_X_iter         cdeq_X_find_in(cdeq_X_iter i1, cdeq_X_iter i2, i_valraw raw);       // return cvec_X_end() if not found
+cdeq_X_value*       cdeq_X_at_mut(cdeq_X* self, intptr_t idx);
+const cdeq_X_value* cdeq_X_get(const cdeq_X* self, i_keyraw raw);                   // return NULL if not found
+cdeq_X_value*       cdeq_X_get_mut(cdeq_X* self, i_keyraw raw);                     // mutable get
+cdeq_X_iter         cdeq_X_find(const cdeq_X* self, i_keyraw raw);
+cdeq_X_iter         cdeq_X_find_in(cdeq_X_iter i1, cdeq_X_iter i2, i_keyraw raw);   // return cvec_X_end() if not found
 
 cdeq_X_value*       cdeq_X_front(const cdeq_X* self);
 cdeq_X_value*       cdeq_X_back(const cdeq_X* self);
 
-cdeq_X_value*       cdeq_X_push_front(cdeq_X* self, i_val value);
-cdeq_X_value*       cdeq_X_emplace_front(cdeq_X* self, i_valraw raw);
+cdeq_X_value*       cdeq_X_push_front(cdeq_X* self, i_key value);
+cdeq_X_value*       cdeq_X_emplace_front(cdeq_X* self, i_keyraw raw);
 void                cdeq_X_pop_front(cdeq_X* self);
+cdeq_X_value        cdeq_X_pull_front(cdeq_X* self);                                // move out front element
 
-cdeq_X_value*       cdeq_X_push_back(cdeq_X* self, i_val value);
-cdeq_X_value*       cdeq_X_push(cdeq_X* self, i_val value);                             // alias for push_back()
-cdeq_X_value*       cdeq_X_emplace_back(cdeq_X* self, i_valraw raw);
-cdeq_X_value*       cdeq_X_emplace(cdeq_X* self, i_valraw raw);                         // alias for emplace_back()
+cdeq_X_value*       cdeq_X_push_back(cdeq_X* self, i_key value);
+cdeq_X_value*       cdeq_X_push(cdeq_X* self, i_key value);                         // alias for push_back()
+cdeq_X_value*       cdeq_X_emplace_back(cdeq_X* self, i_keyraw raw);
+cdeq_X_value*       cdeq_X_emplace(cdeq_X* self, i_keyraw raw);                     // alias for emplace_back()
 void                cdeq_X_pop_back(cdeq_X* self);
+cdeq_X_value        cdeq_X_pull_back(cdeq_X* self);                                 // move out last element
 
-cdeq_X_iter         cdeq_X_insert(cdeq_X* self, intptr_t idx, i_val value);             // move value 
-cdeq_X_iter         cdeq_X_insert_n(cdeq_X* self, intptr_t idx, const i_val[] arr, intptr_t n);  // move arr values
-cdeq_X_iter         cdeq_X_insert_at(cdeq_X* self, cdeq_X_iter it, i_val value);        // move value 
-cdeq_X_iter         cdeq_X_insert_range(cdeq_X* self, i_val* pos,
-                                        const i_val* p1, const i_val* p2);
+cdeq_X_iter         cdeq_X_insert_n(cdeq_X* self, intptr_t idx, const i_key[] arr, intptr_t n);  // move values
+cdeq_X_iter         cdeq_X_insert_at(cdeq_X* self, cdeq_X_iter it, i_key value);    // move value 
+cdeq_X_iter         cdeq_X_insert_uninit(cdeq_X* self, intptr_t idx, intptr_t n);   // uninitialized data 
+                    // copy values:
+cdeq_X_iter         cdeq_X_emplace_n(cdeq_X* self, intptr_t idx, const i_keyraw[] arr, intptr_t n);
+cdeq_X_iter         cdeq_X_emplace_at(cdeq_X* self, cdeq_X_iter it, i_keyraw raw);
 
-cdeq_X_iter         cdeq_X_emplace_n(cdeq_X* self, intptr_t idx, const i_valraw[] arr, intptr_t n);  // clone values
-cdeq_X_iter         cdeq_X_emplace_at(cdeq_X* self, cdeq_X_iter it, i_valraw raw);
-cdeq_X_iter         cdeq_X_emplace_range(cdeq_X* self, i_val* pos,
-                                         const i_valraw* p1, const i_valraw* p2);
-
-cdeq_X_iter         cdeq_X_erase_n(cdeq_X* self, intptr_t idx, intptr_t n);
+void                cdeq_X_erase_n(cdeq_X* self, intptr_t idx, intptr_t n);
 cdeq_X_iter         cdeq_X_erase_at(cdeq_X* self, cdeq_X_iter it);
 cdeq_X_iter         cdeq_X_erase_range(cdeq_X* self, cdeq_X_iter it1, cdeq_X_iter it2);
-cdeq_X_iter         cdeq_X_erase_range_p(cdeq_X* self, i_val* p1, i_val* p2);
-
-void                cdeq_X_sort(cdeq_X* self);
-void                cdeq_X_sort_range(cdeq_X_iter i1, cdeq_X_iter i2,
-                                      int(*cmp)(const i_val*, const i_val*));
 
 cdeq_X_iter         cdeq_X_begin(const cdeq_X* self);
 cdeq_X_iter         cdeq_X_end(const cdeq_X* self);
 void                cdeq_X_next(cdeq_X_iter* it);
-cdeq_X_iter         cdeq_X_advance(cdeq_X_iter it, size_t n);
+cdeq_X_iter         cdeq_X_advance(cdeq_X_iter it, intptr_t n);
 
-cdeq_X_raw          cdeq_X_value_toraw(cdeq_X_value* pval);
+bool                cdeq_X_eq(const cdeq_X* c1, const cdeq_X* c2); // require i_eq/i_cmp/i_less.
 cdeq_X_value        cdeq_X_value_clone(cdeq_X_value val);
+cdeq_X_raw          cdeq_X_value_toraw(const cdeq_X_value* pval);
+void                cdeq_X_value_drop(cdeq_X_value* pval);
 ```
 
 ## Types
 
 | Type name          | Type definition                     | Used to represent...   |
 |:-------------------|:------------------------------------|:-----------------------|
-| `cdeq_X`           | `struct { cdeq_X_value* data; }`  | The cdeq type          |
-| `cdeq_X_value`     | `i_val`                             | The cdeq value type    |
-| `cdeq_X_raw`       | `i_valraw`                          | The raw value type     |
-| `cdeq_X_iter`      | `struct { cdeq_X_value* ref; }`   | The iterator type      |
+| `cdeq_X`           | `struct { cdeq_X_value* data; }`    | The cdeq type          |
+| `cdeq_X_value`     | `i_key`                             | The cdeq value type    |
+| `cdeq_X_raw`       | `i_keyraw`                          | The raw value type     |
+| `cdeq_X_iter`      | `struct { cdeq_X_value* ref; }`     | The iterator type      |
 
 ## Examples
 ```c
-#define i_val int
+#define i_key int
 #define i_tag i
 #include <stc/cdeq.h>
 
 #include <stdio.h>
 
-int main() {
+int main(void) {
     cdeq_i q = cdeq_i_init();
     cdeq_i_push_front(&q, 10);
     c_foreach (i, cdeq_i, q)