Update clist_api.md

1 files changed, 38 insertions, 7 deletions

diff --git a/docs/clist_api.md b/docs/clist_api.md
index ab8a6e98..267361d6 100644
--- a/docs/clist_api.md
+++ b/docs/clist_api.md
@@ -69,21 +69,23 @@ 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);
+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: return 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);
 
 size_t              clist_X_remove(clist_X* self, RawValue raw);
 
@@ -152,3 +154,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
+```