--- a/share/local-bsdtools/farray.sh	Mon Oct 21 15:14:48 2024 +0200
+++ b/share/local-bsdtools/farray.sh	Mon Oct 21 15:38:01 2024 +0200
@@ -1013,6 +1013,45 @@
 
 
 #:
+#: Insert a value into an array at a given index.
+#:
+#: Args:
+#:   $1 (str): An existing array.
+#:   $2 (int): The index at which to insert into. If null then the value is
+#:             appended.
+#:   $3: The value to insert to
+#:
+farray_insert() {
+    local -
+    local __farr_name __farr_index   # $3
+
+    local __farr_token __farr_gvrname __farr_len __farr_idx
+
+    [ $# -lt 3 ] && _farr_fatal "missing value to insert"
+    _farr_array_get_meta "${1-}"
+    _farr_make_index __farr_index "${2-}" "${__farr_len}"
+
+    # Note: inserting at len + 1 is just an append
+    if [ "${__farr_index}" -lt 1 ] || [ "${__farr_index}" -gt $((__farr_len + 1)) ]; then
+	_farr_fatal "array index out of bounds"
+    fi
+
+    # Make room for the item
+    __farr_idx="${__farr_len}"
+    while [ "${__farr_idx}" -ge "${__farr_index}" ] ; do
+        eval "${__farr_gvrname}"_$((__farr_idx + 1))=\"\$\{"${__farr_gvrname}"_"${__farr_idx}"\}\"
+        __farr_idx=$((__farr_idx - 1))
+    done
+    # store
+    _farr_acquire_object "${3}"
+    setvar "${__farr_gvrname}_${__farr_index}" "${3}"
+
+    # Set the new length
+    setvar "${__farr_gvrname}__" $((__farr_len + 1))
+}
+
+
+#:
 #: Remove the elements designated by an index and a length from an array,
 #: and replace them with the elements of another array list, if any.
 #:

--- a/tests/farray-array.t	Mon Oct 21 15:14:48 2024 +0200
+++ b/tests/farray-array.t	Mon Oct 21 15:38:01 2024 +0200
@@ -348,6 +348,78 @@
   $ check_no_array_artifacts
 
 
+Inserting
+=========
+
+Append
+
+  $ farray_create TEST 0 1 2 '3  4   5' $'" 678" \\\'910 ' 11
+  $ farray_insert TEST "" $'the new appended value \\ \''
+  $ farray_debug TEST
+  DEBUG: array `TEST' has length 7
+  DEBUG:   the items:
+  DEBUG:     1: `0'
+  DEBUG:     2: `1'
+  DEBUG:     3: `2'
+  DEBUG:     4: `3  4   5'
+  DEBUG:     5: `" 678" \'910 '
+  DEBUG:     6: `11'
+  DEBUG:     7: `the new appended value \ ''
+  $ farray_release TEST
+  $ check_no_array_artifacts
+
+Prepend
+
+  $ farray_create TEST 0 1 2 '3  4   5' $'" 678" \\\'910 ' 11
+  $ farray_insert TEST 1 $'the new prepended value \\ \''
+  $ farray_debug TEST
+  DEBUG: array `TEST' has length 7
+  DEBUG:   the items:
+  DEBUG:     1: `the new prepended value \ ''
+  DEBUG:     2: `0'
+  DEBUG:     3: `1'
+  DEBUG:     4: `2'
+  DEBUG:     5: `3  4   5'
+  DEBUG:     6: `" 678" \'910 '
+  DEBUG:     7: `11'
+  $ farray_release TEST
+  $ check_no_array_artifacts
+
+In the middle
+
+  $ farray_create TEST 0 1 2 '3  4   5' $'" 678" \\\'910 ' 11
+  $ farray_insert TEST 2 $'the new inserted value \\ \''
+  $ farray_debug TEST
+  DEBUG: array `TEST' has length 7
+  DEBUG:   the items:
+  DEBUG:     1: `0'
+  DEBUG:     2: `the new inserted value \ ''
+  DEBUG:     3: `1'
+  DEBUG:     4: `2'
+  DEBUG:     5: `3  4   5'
+  DEBUG:     6: `" 678" \'910 '
+  DEBUG:     7: `11'
+  $ farray_release TEST
+  $ check_no_array_artifacts
+
+Out of bounds
+
+  $ farray_create TEST 0 1 2 '3  4   5' $'" 678" \\\'910 ' 11
+  $ (farray_insert TEST 8 $'the new inserted value \\ \'')
+  ERROR: array index out of bounds
+  [70]
+  $ farray_release TEST
+  $ check_no_array_artifacts
+
+Missing value
+
+  $ farray_create TEST 0 1 2 '3  4   5' $'" 678" \\\'910 ' 11
+  $ (farray_insert TEST 0)
+  ERROR: missing value to insert
+  [70]
+  $ farray_release TEST
+  $ check_no_array_artifacts
+
 Splicing
 ========