Merge branch 'stclib:master' into modifiedHEADmodified

1 files changed, 48 insertions, 48 deletions

diff --git a/docs/cvec_api.md b/docs/cvec_api.md
index 5879bc1f..8997ed51 100644
--- a/docs/cvec_api.md
+++ b/docs/cvec_api.md
@@ -12,17 +12,18 @@ See the c++ class [std::vector](https://en.cppreference.com/w/cpp/container/vect
 ## 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: cvec_{i_tag}. i_tag defaults to i_val
+#define i_type <t>     // container type name
+#define i_key <t>      // element type: REQUIRED. Note: i_val* may be specified instead of i_key*.
+#define i_cmp <f>      // three-way compare 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 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: cvec_{i_tag}. i_tag defaults to i_key
 #include <stc/cvec.h>
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.
@@ -31,16 +32,15 @@ See the c++ class [std::vector](https://en.cppreference.com/w/cpp/container/vect
 
 ```c
 cvec_X              cvec_X_init(void);
-cvec_X              cvec_X_with_size(intptr_t size, i_val null);
+cvec_X              cvec_X_with_size(intptr_t size, i_key null);
 cvec_X              cvec_X_with_capacity(intptr_t size);
 cvec_X              cvec_X_clone(cvec_X vec);
 
 void                cvec_X_clear(cvec_X* self);
 void                cvec_X_copy(cvec_X* self, const cvec_X* other);
-cvec_X_iter         cvec_X_copy_range(cvec_X* self, i_val* pos, const i_val* p1, const i_val* p2);
+cvec_X_iter         cvec_X_copy_n(cvec_X* self, intptr_t idx, const i_key* arr, intptr_t n);
 bool                cvec_X_reserve(cvec_X* self, intptr_t cap);
-bool                cvec_X_resize(cvec_X* self, intptr_t size, i_val null);
-cvec_X_iter         cvec_X_insert_uninit(cvec_X* self, i_val* pos, intptr_t n); // return pos iter 
+bool                cvec_X_resize(cvec_X* self, intptr_t size, i_key null);
 void                cvec_X_shrink_to_fit(cvec_X* self);
 void                cvec_X_drop(cvec_X* self);                              // destructor
 
@@ -49,55 +49,53 @@ intptr_t            cvec_X_size(const cvec_X* self);
 intptr_t            cvec_X_capacity(const cvec_X* self);
 
 const cvec_X_value* cvec_X_at(const cvec_X* self, intptr_t idx);
-const cvec_X_value* cvec_X_get(const cvec_X* self, i_valraw raw);           // return NULL if not found
-cvec_X_value*       cvec_X_at_mut(cvec_X* self, intptr_t idx);
-cvec_X_value*       cvec_X_get_mut(cvec_X* self, i_valraw raw);             // find mutable value, return value ptr
-cvec_X_iter         cvec_X_find(const cvec_X* self, i_valraw raw);
-cvec_X_iter         cvec_X_find_in(cvec_X_iter i1, cvec_X_iter i2, i_valraw raw); // return cvec_X_end() if not found
+const cvec_X_value* cvec_X_get(const cvec_X* self, i_keyraw raw);           // return NULL if not found
+cvec_X_value*       cvec_X_at_mut(cvec_X* self, intptr_t idx);              // return mutable at idx
+cvec_X_value*       cvec_X_get_mut(cvec_X* self, i_keyraw raw);             // find mutable value
+cvec_X_iter         cvec_X_find(const cvec_X* self, i_keyraw raw);
+cvec_X_iter         cvec_X_find_in(cvec_X_iter i1, cvec_X_iter i2, i_keyraw raw); // return cvec_X_end() if not found
                     // On sorted vectors:
-cvec_X_iter         cvec_X_binary_search(const cvec_X* self, i_valraw raw); // at elem == raw, else end
-cvec_X_iter         cvec_X_lower_bound(const cvec_X* self, i_valraw raw);   // at first elem >= raw, else end
+cvec_X_iter         cvec_X_binary_search(const cvec_X* self, i_keyraw raw); // at elem == raw, else end
+cvec_X_iter         cvec_X_lower_bound(const cvec_X* self, i_keyraw raw);   // at first elem >= raw, else end
 cvec_X_iter         cvec_X_binary_search_in(cvec_X_iter i1, cvec_X_iter i2,
-                                            i_valraw raw, cvec_X_iter* lower_bound);
+                                            i_keyraw raw, cvec_X_iter* lower_bound);
 
 cvec_X_value*       cvec_X_front(const cvec_X* self);
 cvec_X_value*       cvec_X_back(const cvec_X* self);
 
-cvec_X_value*       cvec_X_push(cvec_X* self, i_val value);
-cvec_X_value*       cvec_X_emplace(cvec_X* self, i_valraw raw);
-cvec_X_value*       cvec_X_push_back(cvec_X* self, i_val value);            // alias for push
-cvec_X_value*       cvec_X_emplace_back(cvec_X* self, i_valraw raw);        // alias for emplace
+cvec_X_value*       cvec_X_push(cvec_X* self, i_key value);
+cvec_X_value*       cvec_X_emplace(cvec_X* self, i_keyraw raw);
+cvec_X_value*       cvec_X_push_back(cvec_X* self, i_key value);            // alias for push
+cvec_X_value*       cvec_X_emplace_back(cvec_X* self, i_keyraw raw);        // alias for emplace
 
-void                cvec_X_pop(cvec_X* self);
+void                cvec_X_pop(cvec_X* self);                               // destroy last element
 void                cvec_X_pop_back(cvec_X* self);                          // alias for pop
+cvec_X_value        cvec_X_pull(cvec_X* self);                              // move out last element
 
-cvec_X_iter         cvec_X_insert(cvec_X* self, intptr_t idx, i_val value); // move value 
-cvec_X_iter         cvec_X_insert_n(cvec_X* self, intptr_t idx, const i_val[] arr, intptr_t n);  // move n values
-cvec_X_iter         cvec_X_insert_at(cvec_X* self, cvec_X_iter it, i_val value);  // move value 
-cvec_X_iter         cvec_X_insert_range(cvec_X* self, i_val* pos,
-                                        const i_val* p1, const i_val* p2);
+cvec_X_iter         cvec_X_insert_n(cvec_X* self, intptr_t idx, const i_key arr[], intptr_t n); // move values
+cvec_X_iter         cvec_X_insert_at(cvec_X* self, cvec_X_iter it, i_key value);  // move value 
+cvec_X_iter         cvec_X_insert_uninit(cvec_X* self, intptr_t idx, intptr_t n); // return iter at idx 
 
-cvec_X_iter         cvec_X_emplace_n(cvec_X* self, intptr_t idx, const i_valraw[] arr, intptr_t n); // clone values
-cvec_X_iter         cvec_X_emplace_at(cvec_X* self, cvec_X_iter it, i_valraw raw);
-cvec_X_iter         cvec_X_emplace_range(cvec_X* self, i_val* pos,
-                                         const i_valraw* p1, const i_valraw* p2);
+cvec_X_iter         cvec_X_emplace_n(cvec_X* self, intptr_t idx, const i_keyraw raw[], intptr_t n);
+cvec_X_iter         cvec_X_emplace_at(cvec_X* self, cvec_X_iter it, i_keyraw raw);
 
 cvec_X_iter         cvec_X_erase_n(cvec_X* self, intptr_t idx, intptr_t n);
 cvec_X_iter         cvec_X_erase_at(cvec_X* self, cvec_X_iter it);
 cvec_X_iter         cvec_X_erase_range(cvec_X* self, cvec_X_iter it1, cvec_X_iter it2);
-cvec_X_iter         cvec_X_erase_range_p(cvec_X* self, i_val* p1, i_val* p2);
 
 void                cvec_X_sort(cvec_X* self);
 void                cvec_X_sort_range(cvec_X_iter i1, cvec_X_iter i2,
-                                      int(*cmp)(const i_val*, const i_val*));
+                                      int(*cmp)(const i_key*, const i_key*));
 
 cvec_X_iter         cvec_X_begin(const cvec_X* self);
 cvec_X_iter         cvec_X_end(const cvec_X* self);
 void                cvec_X_next(cvec_X_iter* iter);
 cvec_X_iter         cvec_X_advance(cvec_X_iter it, size_t n);
 
-cvec_X_raw          cvec_X_value_toraw(cvec_X_value* pval);
+bool                cvec_X_eq(const cvec_X* c1, const cvec_X* c2); // equality comp.
 cvec_X_value        cvec_X_value_clone(cvec_X_value val);
+cvec_X_raw          cvec_X_value_toraw(const cvec_X_value* pval);
+cvec_X_raw          cvec_X_value_drop(cvec_X_value* pval);
 ```
 
 ## Types
@@ -105,18 +103,18 @@ cvec_X_value        cvec_X_value_clone(cvec_X_value val);
 | Type name          | Type definition                   | Used to represent...   |
 |:-------------------|:----------------------------------|:-----------------------|
 | `cvec_X`           | `struct { cvec_X_value* data; }`  | The cvec type          |
-| `cvec_X_value`     | `i_val`                           | The cvec value type    |
-| `cvec_X_raw`       | `i_valraw`                        | The raw value type     |
+| `cvec_X_value`     | `i_key`                           | The cvec value type    |
+| `cvec_X_raw`       | `i_keyraw`                        | The raw value type     |
 | `cvec_X_iter`      | `struct { cvec_X_value* ref; }`   | The iterator type      |
 
 ## Examples
 ```c
-#define i_val int
+#define i_key int
 #include <stc/cvec.h>
 
 #include <stdio.h>
 
-int main()
+int main(void)
 {
     // Create a vector containing integers
     cvec_int vec = {0};
@@ -151,12 +149,13 @@ sorted: 5 7 8 13 16 25
 ```
 ### Example 2
 ```c
+#define i_implement
 #include <stc/cstr.h>
 
-#define i_val_str
+#define i_key_str
 #include <stc/cvec.h>
 
-int main() {
+int main(void) {
     cvec_str names = cvec_str_init();
 
     cvec_str_emplace(&names, "Mary");
@@ -187,6 +186,7 @@ item: 2 elements so far
 
 Container with elements of structs:
 ```c
+#define i_implement
 #include <stc/cstr.h>
 
 typedef struct {
@@ -208,7 +208,7 @@ User User_clone(User user) {
 
 // Declare a managed, clonable vector of users.
 #define i_type UVec
-#define i_valclass User // User is a "class" as it has _cmp, _clone and _drop functions.
+#define i_keyclass User // User is a "class" as it has _cmp, _clone and _drop functions.
 #include <stc/cvec.h>
 
 int main(void) {
@@ -224,4 +224,4 @@ int main(void) {
 
     c_drop(UVec, &vec, &vec2); // cleanup
 }
-```
\ No newline at end of file
+```