Merge branch 'stclib:master' into modifiedHEADmodified

1 files changed, 25 insertions, 16 deletions

diff --git a/docs/cqueue_api.md b/docs/cqueue_api.md
index 9ea4b148..ba4411b7 100644
--- a/docs/cqueue_api.md
+++ b/docs/cqueue_api.md
@@ -7,16 +7,16 @@ See the c++ class [std::queue](https://en.cppreference.com/w/cpp/container/queue
 
 ## Header file and declaration
 ```c
-#define i_type      // container type name (default: cset_{i_key})
-#define i_val       // value: REQUIRED
-#define i_valdrop   // destroy value func - defaults to empty destruct
-#define i_valclone  // REQUIRED IF i_valdrop defined
+#define i_key <t>      // element type: REQUIRED. Note: i_val* may be specified instead of i_key*.
+#define i_type <t>     // cqueue container type name
+#define i_keydrop <f>  // destroy value func - defaults to empty destruct
+#define i_keyclone <f> // REQUIRED IF i_keydrop 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_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       // alternative typename: cqueue_{i_tag}. i_tag defaults to i_val
+#define i_tag <s>      // alternative typename: cqueue_{i_tag}. i_tag defaults to i_key
 #include <stc/cqueue.h>
 ```
 `X` should be replaced by the value of `i_tag` in all of the following documentation.
@@ -26,27 +26,36 @@ See the c++ class [std::queue](https://en.cppreference.com/w/cpp/container/queue
 
 ```c
 cqueue_X            cqueue_X_init(void);
+cqueue_X            cqueue_X_with_capacity(intptr_t size);
 cqueue_X            cqueue_X_clone(cqueue_X q);
 
 void                cqueue_X_clear(cqueue_X* self);
 void                cqueue_X_copy(cqueue_X* self, const cqueue_X* other);
+bool                cqueue_X_reserve(cqueue_X* self, intptr_t cap);
+void                cqueue_X_shrink_to_fit(cqueue_X* self);
 void                cqueue_X_drop(cqueue_X* self);       // destructor
 
 intptr_t            cqueue_X_size(const cqueue_X* self);
+intptr_t            cqueue_X_capacity(const cqueue_X* self);
 bool                cqueue_X_empty(const cqueue_X* self);
+
 cqueue_X_value*     cqueue_X_front(const cqueue_X* self);
 cqueue_X_value*     cqueue_X_back(const cqueue_X* self);
 
-cqueue_X_value*     cqueue_X_push(cqueue_X* self, i_val value);
-cqueue_X_value*     cqueue_X_emplace(cqueue_X* self, i_valraw raw);
-
+cqueue_X_value*     cqueue_X_push(cqueue_X* self, i_key value);
+cqueue_X_value*     cqueue_X_emplace(cqueue_X* self, i_keyraw raw);
 void                cqueue_X_pop(cqueue_X* self);
+cqueue_X_value      cqueue_X_pull(cqueue_X* self);                       // move out last element
 
 cqueue_X_iter       cqueue_X_begin(const cqueue_X* self);
 cqueue_X_iter       cqueue_X_end(const cqueue_X* self);
 void                cqueue_X_next(cqueue_X_iter* it);
+cqueue_X_iter       cqueue_X_advance(cqueue_X_iter it, intptr_t n);
 
-i_val               cqueue_X_value_clone(i_val value);
+bool                cqueue_X_eq(const cqueue_X* c1, const cqueue_X* c2); //  require i_eq/i_cmp/i_less.
+i_key               cqueue_X_value_clone(i_key value);
+cqueue_X_raw        cqueue_X_value_toraw(const cqueue_X_value* pval);
+void                cqueue_X_value_drop(cqueue_X_value* pval);
 ```
 
 ## Types
@@ -54,19 +63,19 @@ i_val               cqueue_X_value_clone(i_val value);
 | Type name           | Type definition      | Used to represent...     |
 |:--------------------|:---------------------|:-------------------------|
 | `cqueue_X`          | `cdeq_X`             | The cqueue type          |
-| `cqueue_X_value`    | `i_val`              | The cqueue element type  |
-| `cqueue_X_raw`      | `i_valraw`           | cqueue raw value type    |
+| `cqueue_X_value`    | `i_key`              | The cqueue element type  |
+| `cqueue_X_raw`      | `i_keyraw`           | cqueue raw value type    |
 | `cqueue_X_iter`     | `cdeq_X_iter`        | cqueue iterator          |
 
 ## Examples
 ```c
-#define i_val int
+#define i_key int
 #define i_tag i
 #include <stc/cqueue.h>
 
 #include <stdio.h>
 
-int main() {
+int main(void) {
     cqueue_i Q = cqueue_i_init();
 
     // push() and pop() a few.