# HG changeset patch
# User Franz Glasner <fzglas.hg@dom66.de>
# Date 1726663887 -7200
# Node ID ce29bad1fd3be7ea5e6097736f47193b98db06c1
# Parent  d791601ac1beae203ae9e03d14ff7904a59344d9
farray.sh: Implement _farr_make_index().

This will be used to a more centralized and extended index computation that
also allows computing indexes relative to the length of an array.

diff -r d791601ac1be -r ce29bad1fd3b share/local-bsdtools/farray.sh
--- a/share/local-bsdtools/farray.sh	Wed Sep 18 13:13:26 2024 +0200
+++ b/share/local-bsdtools/farray.sh	Wed Sep 18 14:51:27 2024 +0200
@@ -141,6 +141,56 @@
 
 
 #:
+#: From an input index value compute an effective index value and store
+#: it into a variable with a given name.
+#:
+#: Args:
+#:   $1 (str): The name of a variable where to store the result
+#:   $2 (int, null): The index value to check.
+#:                   It must be a valid decimal number or the `null` value.
+#:                   If the argument is `null` then ``$3 + 1`` is used as the
+#:                   resulting effective index value. For this to work a
+#:                   valid length must be given in `$3`.
+#:                   If the argument is `<= 0` then -- if `$3` is given
+#:                   the effective index is computed as ``$3 + $2``.
+#:   $3 (int, optional): If given a length value that is used to compute
+#:                       effective index values in some cases (`$2` is null or
+#:                       `$2` <= 0).
+
+_farr_make_index() {
+    local __farr_mi_varname __farr_mi_index __farr_mi_length
+
+    __farr_mi_varname="$1"
+    __farr_mi_index="$2"
+    __farr_mi_length="${3-}"
+
+    # If it is given and non-null it must be a valid decimal length number
+    if [ -n "${__farr_mi_length}" ]; then
+        _farr_is_decimal_number "${__farr_mi_length}" || _farr_fatal "given length is not a valid decimal number"
+    fi
+
+    if [ -z "${__farr_mi_index}" ]; then
+        if [ -n "${__farr_mi_length}" ]; then
+            eval "${__farr_mi_varname}"="\$((__farr_mi_length + 1))"
+        else
+            _farr_fatal "length not given: cannot autocompute index"
+        fi
+    else
+        _farr_is_decimal_number "${__farr_mi_index}" || _farr_fatal "given index is not a valid decimal number"
+        if [ "${__farr_mi_index}" -le 0 ]; then
+            if [ -n "${__farr_mi_length}" ]; then
+                eval "${__farr_mi_varname}"="\$((__farr_mi_length + __farr_mi_index))"
+            else
+                _farr_fatal "cannot compute effective index because no length is given"
+            fi
+        else
+            eval "${__farr_mi_varname}"=\$\{__farr_mi_index\}
+        fi
+    fi
+}
+
+
+#:
 #: Quote the given input using "Dollar-Single-Quotes" to be safely used in
 #: evals.
 #:
diff -r d791601ac1be -r ce29bad1fd3b tests/farray-misc.t
--- a/tests/farray-misc.t	Wed Sep 18 13:13:26 2024 +0200
+++ b/tests/farray-misc.t	Wed Sep 18 14:51:27 2024 +0200
@@ -48,3 +48,51 @@
   [1]
   $ _farr_is_decimal_number 0123456789abcdef
   [1]
+
+
+Index Checks
+============
+
+  $ _farr_make_index _res 5
+  $ echo $_res
+  5
+
+  $ _farr_make_index _res "" 123
+  $ echo $_res
+  124
+
+  $ _farr_make_index _res 0 123
+  $ echo $_res
+  123
+
+  $ _farr_make_index _res -122 123
+  $ echo $_res
+  1
+
+  $ _farr_make_index _res -123 123
+  $ echo $_res
+  0
+
+  $ _farr_make_index _res 124 123
+  $ echo $_res
+  124
+
+  $ _farr_make_index _res 125 123
+  $ echo $_res
+  125
+
+  $ ( _farr_make_index _res 0 )
+  ERROR: cannot compute effective index because no length is given
+  [70]
+
+  $ ( _farr_make_index _res "" )
+  ERROR: length not given: cannot autocompute index
+  [70]
+
+  $ ( _farr_make_index _res 0x1 )
+  ERROR: given index is not a valid decimal number
+  [70]
+
+  $ ( _farr_make_index _res 0 0x1 )
+  ERROR: given length is not a valid decimal number
+  [70]