--- a/share/local-bsdtools/farray.sh	Sun Sep 15 11:36:38 2024 +0200
+++ b/share/local-bsdtools/farray.sh	Sun Sep 15 21:26:55 2024 +0200
@@ -1334,6 +1334,61 @@
 
 
 #:
+#: Try to get the key-value item that is associated with a storage index and
+#: store it into variables.
+#:
+#: Use this for iteration over key-value items.
+#:
+#: Args:
+#:   $1 (str): The name of the variable where to put the key into.
+#:   $2 (str): The name of the variable where to put the value into.
+#:   $3 (str): The name of an existing alist.
+#:   $4 (int): The index.
+#:
+#: Returns:
+#:   0 (truthy) on success,
+#:   1 (falsy) if the given index is out of bounds.
+#:
+#: Exit:
+#:   Other errors (missing array name, missing index value) are considered
+#:   fatal and call `_farr_fatal` (i.e. `exit`).
+#:
+falist_tryget_item_at_index() {
+    local __farr_key_varname __farr_value_varname __farr_name __farr_index
+
+    local __farr_token __farr_objname __farr_keyname __farr_valname __farr_len
+    local __farr_idx __farr_getikey __farr_getival
+
+    __farr_key_varname=${1-}
+    [ -z "${__farr_key_varname}" ] && _farr_fatal "missing variable name for key"
+    __farr_value_varname=${2-}
+    [ -z "${__farr_value_varname}" ] && _farr_fatal "missing variable name for value"
+    shift 2
+    _farr_alist_get_meta "$@"
+    [ $# -lt 2 ] && _farr_fatal "missing index"
+    __farr_index=$(($2 + 0))
+
+    if [ \( ${__farr_index} -ge 1 \) -a \( ${__farr_index} -le ${__farr_len} \) ]; then
+        eval __farr_getikey=\"\$\{${__farr_keyname}_${__farr_index}+SET\}\"
+        if [ -n "${__farr_getikey}" ]; then
+            eval __farr_getival=\"\$\{${__farr_valname}_${__farr_index}+SET\}\"
+            if [ -n "${__farr_getival}" ]; then
+                eval "${__farr_key_varname}"=\"\$\{${__farr_keyname}_${__farr_index}\}\"
+                eval "${__farr_value_varname}"=\"\$\{${__farr_valname}_${__farr_index}\}\"
+                return 0
+            else
+                _farr_fatal "value unexpectedly unset (index ${__farr_index})"
+            fi
+        else
+            _farr_fatal "key unexpectedly unset (index ${__farr_index})"
+        fi
+    else
+        return 1
+    fi
+}
+
+
+#:
 #: Determine whether a key is found within the alist.
 #:
 #: Args:
@@ -1699,7 +1754,7 @@
         echo "VALID LENGTH (ERROR)"
     fi
 
-    # Iteration by indexing
+    # Iteration by indexing key and values separately
     echo "ITERATE (manual indexing):"
     _i=1
     while falist_tryget_key_at_index _k LIST ${_i}; do
@@ -1709,6 +1764,14 @@
         _i=$((${_i} + 1))
     done
 
+    # Iteration by indexing key and values separately
+    echo "ITERATE (manual indexing over items):"
+    _i=1
+    while falist_tryget_item_at_index _k _v LIST ${_i}; do
+        printf "  KEY: \`%s', VAL: \`%s'\\n" "${_k}" "${_v}"
+        _i=$((${_i} + 1))
+    done
+
     # Iteration with for each
     echo "ITERATE (for each):"
     falist_for_each LIST $'printf "EACH: %s key \\`%s\\\', value \\`%s\\\' at idx %d\\n"'   # `