# HG changeset patch
# User Franz Glasner <fzglas.hg@dom66.de>
# Date 1725184701 -7200
# Node ID fb4ee1fab0461b0381f822ac4979882127c59262
# Parent  5cc6ea0ef9656663abc132eaa90f4333a4f955a1
array.sh: REFACTOR: helper functions renamed to have _farr_ prefix

diff -r 5cc6ea0ef965 -r fb4ee1fab046 share/local-bsdtools/array.sh
--- a/share/local-bsdtools/array.sh	Sun Sep 01 11:16:54 2024 +0200
+++ b/share/local-bsdtools/array.sh	Sun Sep 01 11:58:21 2024 +0200
@@ -22,19 +22,19 @@
 #: - Every array has a NAME
 #: - One-based indexing is used
 #: - Array elements are stored in a global variable named
-#:   ``_farr_<NAME>_<index-number>``
+#:   ``_farr_array_<NAME>_<index-number>``
 #: - The number of elements in the array ist stored in the global
-#:   variable ``_farr_<NAME>__``
+#:   variable ``_farr_array_<NAME>__``
 #: - An array name must conform to shell variable naming conventions
 #: - Currently the number of of elements of an array must be >= 0
-#: - An unset global variable ``_farr_<NAME>__`` variable is a severe
+#: - An unset global variable ``_farr_array_<NAME>__`` variable is a severe
 #:   error normally and forces an immediate error ``exit``.
 #:   Exceptions to this rule are documented.
 #:
 
 
-_farr_global_prefix=_farr_
-_farr_unset=__UNSET_d646c21167a611efa78174d435fd3892__
+_farr_global_prefix=_farr_array_
+_farr_unset=_farr__UNSET_d646c21167a611efa78174d435fd3892__
 
 
 #:
@@ -43,7 +43,7 @@
 #: Args:
 #:   $1 (str): The error message
 #:
-_array_fatal() {
+_farr_fatal() {
     echo "ERROR: ${1}" 1>&2
     exit 70    # EX_SOFTWARE
 }
@@ -72,7 +72,7 @@
 #:       ``\'``
 #:                Literal single-quote
 #:
-_quote_for_eval_dsq() {
+_farr_quote_for_eval_dsq() {
     printf "%s" "${1}" \
         | /usr/bin/sed -e $'s/\\\\/\\\\\\\\/g' -e $'s/\'/\\\\\'/g'
     #                       escape a backslash      escape a single quote
@@ -98,7 +98,7 @@
 
     local _gvrname _el _l
 
-    [ $# -lt 1 ] && _array_fatal "missing array name"
+    [ $# -lt 1 ] && _farr_fatal "missing array name"
     _name=$1
     _gvrname=${_farr_global_prefix}$1
     shift
@@ -106,7 +106,7 @@
     # Check whether the variable already exists
     eval _l=\${${_gvrname}__:-${_farr_unset}}
 
-    [ "${_l}" != ${_farr_unset} ] && _array_fatal "array \`${_name}' already exists"
+    [ "${_l}" != ${_farr_unset} ] && _farr_fatal "array \`${_name}' already exists"
     # Really create
     eval ${_gvrname}__=0
 
@@ -152,9 +152,9 @@
 
     local _gvrname _l
 
-    [ $# -lt 1 ] && _array_fatal "missing variable name"
+    [ $# -lt 1 ] && _farr_fatal "missing variable name"
     _varname=$1
-    [ $# -lt 2 ] && _array_fatal "missing array name"
+    [ $# -lt 2 ] && _farr_fatal "missing array name"
     _name=$2
     _gvrname=${_farr_global_prefix}$2
 
@@ -185,7 +185,7 @@
 
     local _vn
 
-    [ $# -lt 1 ] && _array_fatal "missing array name"
+    [ $# -lt 1 ] && _farr_fatal "missing array name"
     _name=$1
 
     if array_length _vn ${_name}; then
@@ -211,7 +211,7 @@
 
     local _gvrname _l _l1
 
-    [ $# -lt 1 ] && _array_fatal "missing array name"
+    [ $# -lt 1 ] && _farr_fatal "missing array name"
     _name=$1
     _gvrname=${_farr_global_prefix}$1
     _value="${2-}"
@@ -219,7 +219,7 @@
     # Check whether the variable already exists
     eval _l=\${${_gvrname}__:-${_farr_unset}}
     if [ "${_l}" = ${_farr_unset} ]; then
-	_array_fatal "array \`${_name}' does not exist"
+	_farr_fatal "array \`${_name}' does not exist"
     fi
 
     _l1=$((${_l} + 1))
@@ -228,7 +228,7 @@
     # Set value
     # Escape properly: use $' ' and escape any backslashes and single quotes.
     #
-    eval ${_gvrname}_${_l1}=\$\'"$(_quote_for_eval_dsq "${_value}")"\'
+    eval ${_gvrname}_${_l1}=\$\'"$(_farr_quote_for_eval_dsq "${_value}")"\'
     # the implementation below line does not escape properly
     #   eval ${_gvrname}_${_l1}="\"${_value}\""
 
@@ -255,32 +255,32 @@
 
     local _gvrname _l _l1
 
-    [ $# -lt 1 ] && _array_fatal "missing array name"
+    [ $# -lt 1 ] && _farr_fatal "missing array name"
     _name=$1
     _gvrname=${_farr_global_prefix}$1
-    [ $# -lt 2 ] && _array_fatal "missing array index"
+    [ $# -lt 2 ] && _farr_fatal "missing array index"
     _index=$2
     _value="${3-}"
 
     # Check whether the variable already exists
     eval _l=\${${_gvrname}__:-${_farr_unset}}
     if [ "${_l}" = ${_farr_unset} ]; then
-	_array_fatal "array \`${_name}' does not exist"
+	_farr_fatal "array \`${_name}' does not exist"
     fi
 
     # For proper quoting: see array_append
     if [ \( ${_index} -ge 1 \) -a \( ${_index} -le ${_l} \) ]; then
         # replace a value at an existing index
-        eval ${_gvrname}_${_l}=\$\'"$(_quote_for_eval_dsq "${_value}")"\'
+        eval ${_gvrname}_${_l}=\$\'"$(_farr_quote_for_eval_dsq "${_value}")"\'
     else
         _l1=$((${_l} + 1))
         if [ ${_index} -eq ${_l1} ]; then
             # append value
-            eval ${_gvrname}_${_l1}=\$\'"$(_quote_for_eval_dsq "${_value}")"\'
+            eval ${_gvrname}_${_l1}=\$\'"$(_farr_quote_for_eval_dsq "${_value}")"\'
             # and set new length
             eval ${_gvrname}__=${_l1}
         else
-            _array_fatal "array index out of bounds (cannot create holes)"
+            _farr_fatal "array index out of bounds (cannot create holes)"
         fi
     fi
 }
@@ -299,23 +299,23 @@
 
     local _gvrname _l _value
 
-    [ $# -lt 1 ] && _array_fatal "missing variable name"
+    [ $# -lt 1 ] && _farr_fatal "missing variable name"
     _varname=$1
-    [ $# -lt 2 ] && _array_fatal "missing array name"
+    [ $# -lt 2 ] && _farr_fatal "missing array name"
     _name=$2
     _gvrname=${_farr_global_prefix}$2
-    [ $# -lt 3 ] && _array_fatal "missing array index"
+    [ $# -lt 3 ] && _farr_fatal "missing array index"
     _index=$3
 
     # Check whether the variable already exists
     eval _l=\${${_gvrname}__:-${_farr_unset}}
     if [ "${_l}" = ${_farr_unset} ]; then
-	_array_fatal "array \`${_name}' does not exist"
+	_farr_fatal "array \`${_name}' does not exist"
     fi
 
     # check index range
     if [ \( "${_index}" -lt 1 \) -o \( "${_index}" -gt ${_l} \) ]; then
-	_array_fatal "array index out of bounds"
+	_farr_fatal "array index out of bounds"
     fi
 
     eval ${_varname}=\"\${${_gvrname}_${_index}}\"
@@ -336,25 +336,25 @@
 #:
 #: Exit:
 #:   Other errors (missing array name, missing index value) are considered
-#:   fatal and call `_array_fatal` (i.e. `exit`).
+#:   fatal and call `_farr_fatal` (i.e. `exit`).
 #:
 array_tryget() {
     local _varname _name _index
 
     local _gvrname _l _value
 
-    [ $# -lt 1 ] && _array_fatal "missing variable name"
+    [ $# -lt 1 ] && _farr_fatal "missing variable name"
     _varname=$1
-    [ $# -lt 2 ] && _array_fatal "missing array name"
+    [ $# -lt 2 ] && _farr_fatal "missing array name"
     _name=$2
     _gvrname=${_farr_global_prefix}$2
-    [ $# -lt 3 ] && _array_fatal "missing array index"
+    [ $# -lt 3 ] && _farr_fatal "missing array index"
     _index=$3
 
     # Check whether the variable already exists
     eval _l=\${${_gvrname}__:-${_farr_unset}}
     if [ "${_l}" = ${_farr_unset} ]; then
-	_array_fatal "array \`${_name}' does not exist"
+	_farr_fatal "array \`${_name}' does not exist"
     fi
 
     # check index range
@@ -379,21 +379,21 @@
 
     local _gvrname _l _new_l _idx _idx1 _value
 
-    [ $# -lt 1 ] && _array_fatal "missing array name"
+    [ $# -lt 1 ] && _farr_fatal "missing array name"
     _name=$1
     _gvrname=${_farr_global_prefix}$1
-    [ $# -lt 2 ] && _array_fatal "missing array index"
+    [ $# -lt 2 ] && _farr_fatal "missing array index"
     _index=$2
 
     # Check whether the variable already exists
     eval _l=\${${_gvrname}__:-${_farr_unset}}
     if [ "${_l}" = ${_farr_unset} ]; then
-	_array_fatal "array \`${_name}' does not exist"
+	_farr_fatal "array \`${_name}' does not exist"
     fi
 
     # check index range
     if [ \( "${_index}" -lt 1 \) -o \( "${_index}" -gt ${_l} \) ]; then
-	_array_fatal "array index out of bounds"
+	_farr_fatal "array index out of bounds"
     fi
 
     _new_l=$((${_l} - 1))
@@ -402,7 +402,7 @@
     while [ ${_idx} -lt ${_l} ]; do
         # copy the following value to the current index
         eval _value=\"\${${_gvrname}_${_idx1}}\"
-        eval ${_gvrname}_${_idx}=\$\'"$(_quote_for_eval_dsq "${_value}")"\'
+        eval ${_gvrname}_${_idx}=\$\'"$(_farr_quote_for_eval_dsq "${_value}")"\'
         _idx=$((${_idx} + 1))
         _idx1=$((${_idx} + 1))
     done
@@ -424,14 +424,14 @@
 
     local _gvrname _l _idx
 
-    [ $# -lt 1 ] && _array_fatal "missing array name"
+    [ $# -lt 1 ] && _farr_fatal "missing array name"
     _name=$1
     _gvrname=${_farr_global_prefix}$1
 
     # Check whether the variable already exists
     eval _l=\${${_gvrname}__:-${_farr_unset}}
     if [ "${_l}" = ${_farr_unset} ]; then
-	_array_fatal "array \`${_name}' does not exist"
+	_farr_fatal "array \`${_name}' does not exist"
     fi
 
     _idx=1
@@ -460,7 +460,7 @@
 
     local _gvrname _l _idx
 
-    [ $# -lt 1 ] && _array_fatal "missing array name"
+    [ $# -lt 1 ] && _farr_fatal "missing array name"
     _name=$1
     _gvrname=${_farr_global_prefix}$1
 
@@ -496,16 +496,16 @@
 
     local _gvrname _l _idx _existing_value
 
-    [ $# -lt 1 ] && _array_fatal "missing array name"
+    [ $# -lt 1 ] && _farr_fatal "missing array name"
     _name=$1
     _gvrname=${_farr_global_prefix}$1
-    [ $# -ne 2 ] && _array_fatal "missing value to search for"
+    [ $# -ne 2 ] && _farr_fatal "missing value to search for"
     _searched_value="$2"
 
     # Check whether the variable already exists
     eval _l=\${${_gvrname}__:-${_farr_unset}}
     if [ "${_l}" = ${_farr_unset} ]; then
-	_array_fatal "array \`${_name}' does not exist"
+	_farr_fatal "array \`${_name}' does not exist"
     fi
 
     _idx=1
@@ -541,18 +541,18 @@
 
     local _gvrname _l _sidx _existing_value
 
-    [ $# -lt 1 ] && _array_fatal "missing variable name"
+    [ $# -lt 1 ] && _farr_fatal "missing variable name"
     _varname=$1
-    [ $# -lt 2 ] && _array_fatal "missing array name"
+    [ $# -lt 2 ] && _farr_fatal "missing array name"
     _name=$2
     _gvrname=${_farr_global_prefix}$2
-    [ $# -lt 3 ] && _array_fatal "missing value to search for"
+    [ $# -lt 3 ] && _farr_fatal "missing value to search for"
     _searched_value="$3"
 
     # Check whether the variable already exists
     eval _l=\${${_gvrname}__:-${_farr_unset}}
     if [ "${_l}" = ${_farr_unset} ]; then
-	_array_fatal "array \`${_name}' does not exist"
+	_farr_fatal "array \`${_name}' does not exist"
     fi
 
     _start=${4-1}
@@ -597,16 +597,16 @@
 
     local _gvrname _l _idx _value _rv
 
-    [ $# -lt 1 ] && _array_fatal "missing array name"
+    [ $# -lt 1 ] && _farr_fatal "missing array name"
     _name=$1
     _gvrname=${_farr_global_prefix}$1
-    [ $# -lt 2 ] && _array_fatal "missing callback function name"
+    [ $# -lt 2 ] && _farr_fatal "missing callback function name"
     _cb="$2"
 
     # Check whether the variable already exists
     eval _l=\${${_gvrname}__:-${_farr_unset}}
     if [ "${_l}" = ${_farr_unset} ]; then
-	_array_fatal "array \`${_name}' does not exist"
+	_farr_fatal "array \`${_name}' does not exist"
     fi
 
     _idx=1
@@ -629,16 +629,16 @@
 
     local _gvrname _l _idx _value _rv
 
-    [ $# -lt 1 ] && _array_fatal "missing array name"
+    [ $# -lt 1 ] && _farr_fatal "missing array name"
     _name=$1
     _gvrname=${_farr_global_prefix}$1
-    [ $# -lt 2 ] && _array_fatal "missing callback function name"
+    [ $# -lt 2 ] && _farr_fatal "missing callback function name"
     _cb="$2"
 
     # Check whether the variable already exists
     eval _l=\${${_gvrname}__:-${_farr_unset}}
     if [ "${_l}" = ${_farr_unset} ]; then
-	_array_fatal "array \`${_name}' does not exist"
+	_farr_fatal "array \`${_name}' does not exist"
     fi
 
     _idx=${_l}
@@ -666,7 +666,7 @@
 
     local _gvrname _l
 
-    [ $# -lt 1 ] && _array_fatal "missing array name"
+    [ $# -lt 1 ] && _farr_fatal "missing array name"
     _name=$1
     _gvrname=${_farr_global_prefix}$1