--- 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