--- a/share/local-bsdtools/farray.sh	Mon Oct 07 17:30:10 2024 +0200
+++ b/share/local-bsdtools/farray.sh	Mon Oct 07 23:39:01 2024 +0200
@@ -2049,7 +2049,7 @@
             __farr_idx=$((__farr_idx + 1))
         done
         #
-        # Not yet found: "append" ..
+        # Not yet found: "append" ...
         #
         # NOTE: __farr_idx here already is the new correct length
         #
@@ -2058,7 +2058,50 @@
         eval ${__farr_keyname}_${__farr_len}="$(_farr_quote_for_eval "${__farr_key}")"
         _farr_acquire_object "${__farr_value}"
         eval ${__farr_valname}_${__farr_len}="$(_farr_quote_for_eval "${__farr_value}")"
-        #   ... the new length
+        #   ... the new length to the storage
+        eval ${__farr_objname}__=${__farr_len}
+        shift 2
+    done
+    return 0
+}
+
+
+#:
+#: Map a key to a value while assuming that the given keys are not already
+#: in the alist.
+#:
+#: Args:
+#:   $1 (str): The name of an existing alist.
+#:   $2, $3 ... (optional): A sequence of key-value pairs the alist will be
+#:                          populated with.
+#:
+#: Exit:
+#:   If one of the underlying arrays that implement the alist does not exist
+#:   or if an internal inconsistency will be detected.
+#:
+falist_add() {
+    local __farr_name __farr_key __farr_value
+
+    local __farr_token __farr_objname __farr_keyname __farr_valname __farr_len
+
+    _farr_alist_get_meta "$@"
+    shift
+
+    while [ $# -ne 0 ]; do
+        [ $# -lt 1 ] && _farr_fatal "missing key"
+        __farr_key="$1"
+        [ $# -lt 2 ] && _farr_fatal "missing value"
+        __farr_value="$2"
+
+        #
+        # We do just append ...
+        #
+        __farr_len=$((__farr_len + 1))
+        #   ... the key/value pairs to storage
+        eval ${__farr_keyname}_${__farr_len}="$(_farr_quote_for_eval "${__farr_key}")"
+        _farr_acquire_object "${__farr_value}"
+        eval ${__farr_valname}_${__farr_len}="$(_farr_quote_for_eval "${__farr_value}")"
+        #   ... the new length to the storage
         eval ${__farr_objname}__=${__farr_len}
         shift 2
     done

--- a/tests/farray-alist.t	Mon Oct 07 17:30:10 2024 +0200
+++ b/tests/farray-alist.t	Mon Oct 07 23:39:01 2024 +0200
@@ -134,6 +134,32 @@
   $ check_no_alist_artifacts
 
 
+Add
+===
+
+  $ falist_create LIST
+  $ falist_add LIST K1 'V 1'
+  $ falist_add LIST K2 'V 2'
+  $ falist_add LIST K3 $'" 111222333" \\\'444555666 '    # '
+  $ falist_debug LIST
+  DEBUG: alist `LIST' has length 3
+  DEBUG:   the items:
+  DEBUG:     `K1' -> `V 1'
+  DEBUG:     `K2' -> `V 2'
+  DEBUG:     `K3' -> `" 111222333" \'444555666 '
+Yes: make a duplicate key
+  $ falist_add LIST K3 $'" 111222333" \\\'444555666 '    #
+  $ falist_debug LIST
+  DEBUG: alist `LIST' has length 4
+  DEBUG:   the items:
+  DEBUG:     `K1' -> `V 1'
+  DEBUG:     `K2' -> `V 2'
+  DEBUG:     `K3' -> `" 111222333" \'444555666 '
+  DEBUG:     `K3' -> `" 111222333" \'444555666 '
+  $ falist_release LIST
+  $ check_no_alist_artifacts
+
+
 Iteration
 =========