Merge branch 'master' of https://github.com/tylo-work/C99Containers into master

1 files changed, 45 insertions, 12 deletions

diff --git a/docs/clist_api.md b/docs/clist_api.md
index ab8a6e98..767d5f24 100644
--- a/docs/clist_api.md
+++ b/docs/clist_api.md
@@ -61,30 +61,34 @@ size_t              clist_X_size(clist_X list); // note: O(n)
 clist_X_value_t*    clist_X_front(clist_X* self);
 clist_X_value_t*    clist_X_back(clist_X* self);
 
-void                clist_X_push_n(clist_X *self, const clist_X_rawvalue_t arr[], size_t size);
-void                clist_X_emplace_back(clist_X* self, RawValue ref);
-void                clist_X_push_back(clist_X* self, Value value);
-
 void                clist_X_emplace_front(clist_X* self, RawValue raw);
 void                clist_X_push_front(clist_X* self, Value value);
 void                clist_X_pop_front(clist_X* self);
 
-clist_X_iter_t      clist_X_emplace_after(clist_X* self, clist_X_iter_t pos, RawValue raw);
-clist_X_iter_t      clist_X_insert_after(clist_X* self, clist_X_iter_t pos, Value raw);
+                    // non-std: push back, complexity O(1)
+void                clist_X_push_n(clist_X *self, const clist_X_rawvalue_t arr[], size_t size);
+void                clist_X_emplace_back(clist_X* self, RawValue ref);
+void                clist_X_push_back(clist_X* self, Value value);
+
+clist_X_iter_t      clist_X_emplace_after(clist_X* self, clist_X_iter_t it, RawValue raw);
+clist_X_iter_t      clist_X_insert_after(clist_X* self, clist_X_iter_t it, Value raw);
 
-clist_X_iter_t      clist_X_erase_after(clist_X* self, clist_X_iter_t pos);
-clist_X_iter_t      clist_X_erase_range_after(clist_X* self, clist_X_iter_t pos, clist_X_iter_t finish);
+clist_X_iter_t      clist_X_erase_after(clist_X* self, clist_X_iter_t it);
+clist_X_iter_t      clist_X_erase_range_after(clist_X* self, clist_X_iter_t it1, clist_X_iter_t it2);
 
-clist_X_iter_t      clist_X_splice_after(clist_X* self, clist_X_iter_t pos, clist_X* other);
+clist_X_iter_t      clist_X_splice_after(clist_X* self, clist_X_iter_t it, clist_X* other);
+                    // non-std:
 clist_X_iter_t      clist_X_splice_front(clist_X* self, clist_X* other);
 clist_X_iter_t      clist_X_splice_back(clist_X* self, clist_X* other);
 
-clist_X             clist_X_splice_out(clist_X* self, clist_X_iter_t pos1, clist_X_iter_t pos2);
+                    // non-std: note: returns range (it1, it2] - excluding it1, including it2:
+clist_X             clist_X_splice_out(clist_X* self, clist_X_iter_t it1, clist_X_iter_t it2);
 
 clist_X_iter_t      clist_X_find(const clist_X* self, RawValue raw);
 clist_X_iter_t      clist_X_find_before(const clist_X* self,
-                                        clist_X_iter_t first, clist_X_iter_t finish, RawValue ref);
+                                        clist_X_iter_t it1, clist_X_iter_t it2, RawValue raw);
 
+                    // std: removes all elements equal to raw
 size_t              clist_X_remove(clist_X* self, RawValue raw);
 
 void                clist_X_sort(clist_X* self);
@@ -99,7 +103,7 @@ clist_X_iter_t      clist_X_fwd(clist_X_iter it, size_t n);
 
 clist_X_value_t     clist_X_value_clone(clist_X_value_t val);
 ```
-The `clist_X_splice_out(self, it1, it2)` can be combined with `clist_X_splice_after(self, pos, other)` to mimic c++ `std::forward_list::splice_after(pos, other, it1, it2)`. Note however, that `it2` is included in elements to be spliced, unlike with `std::forward_list()`. E.g, splice in 2, 3 after 10 in L2:
+The `clist_X_splice_out(self, it1, it2)` can be combined with `clist_X_splice_after(self, it, other)` to mimic c++ `std::forward_list::splice_after(it, other, it1, it2)`. Note however that *it2* is included in elements to be spliced, unlike with *std::forward_list()*. Example: splice in `[2, 3]` from *L1* after `10` in *L2*:
 ```c
 c_init (clist_i, L1, {1, 2, 3, 4, 5});
 c_init (clist_i, L2, {10, 20, 30, 40, 50});
@@ -152,3 +156,32 @@ Output:
 initial:  9 7 5 3 1 10 20 30 40 50 60 70 80 90 2 4 6 8
 sorted:  1 2 3 4 5 6 7 8 9 10 20 30 40 50 60 70 80 90
 ```
+### Example 2
+```c
+// erasing from clist
+#include <stc/clist.h>
+#include <stdio.h>
+
+using_clist(i, int);
+
+int main ()
+{
+  c_init (clist_i, L, {10, 20, 30, 40, 50});
+                                               // 10 20 30 40 50
+  clist_i_iter_t it = clist_i_begin(&L);       // ^
+  it = clist_i_erase_after(&L, it);            // 10 30 40 50
+                                               //    ^
+  clist_i_iter_t end = clist_i_end(&L);        //
+  it = clist_i_erase_range_after(&L, it, end); // 10 30
+                                               //       ^
+  printf("mylist contains:");
+  c_foreach (x, clist_i, L) printf(" %d", *x.ref);
+  puts("");
+
+  clist_i_del(&L);
+}
+```
+Output:
+```
+mylist contains: 10 30
+```