# HG changeset patch
# User Franz Glasner <fzglas.hg@dom66.de>
# Date 1726759175 -7200
# Node ID a84ba696ffd844951fd0362dcc9bd6a091a78090
# Parent  398656a289096d52d73afc5fb1b9943d92956e99
farray.sh: docs: more on farray_splice() (examples)

diff -r 398656a28909 -r a84ba696ffd8 share/local-bsdtools/farray.sh
--- a/share/local-bsdtools/farray.sh	Thu Sep 19 13:28:01 2024 +0200
+++ b/share/local-bsdtools/farray.sh	Thu Sep 19 17:19:35 2024 +0200
@@ -666,6 +666,42 @@
 #:   $5 (str, null, optional): An array whose elements will be inserted at
 #:                             given index.
 #:
+#: Using this universal function you can insert, replace or delete items.
+#:
+#: Examples:
+#:
+#:   Using ARRAY for the array to be changed and INSERTED for the new
+#:   items and DELETED/POPPED for the returned items:
+#:
+#:   Prepend (insert at the start position)::
+#:
+#:     farray_splice "" ARRAY 1 0 INSERTED
+#:
+#:   Extend (insert after the end position)::
+#:
+#:     farray_splice "" ARRAY "" 0 INSERTED
+#:
+#:   Copy INSERTED into ARRAY, replacing the complete existing content::
+#:
+#:     farray_splice "" ARRAY 1 "" INSERTED
+#:
+#:   Copy INSERTED into ARRAY, replacing the complete existing content and
+#:   returning it in DELETED::
+#:
+#:     farray_splice DELETED ARRAY 1 "" INSERTED
+#:
+#:   Pop the first item::
+#:
+#:     farray_splice POPPED ARRAY 1 1
+#:
+#:   Pop the last item::
+#:
+#:     farray_splice POPPED ARRAY 0 1
+#:
+#:   Shift by one item (similar to pop the first item, but no return value)::
+#:
+#:     farray_splice "" ARRAY 1 1
+#:
 farray_splice() {
     local __farr_del_name __farr_del_token __farr_del_gvrname __farr_del_len
     local __farr_l_name __farr_l_token __farr_l_gvrname __farr_l_len