--- a/share/local-bsdtools/farray.sh	Sat Oct 19 22:40:11 2024 +0200
+++ b/share/local-bsdtools/farray.sh	Sun Oct 20 13:27:10 2024 +0200
@@ -23,9 +23,9 @@
 #: - Every array has a NAME.
 #: - One-based indexing is used.
 #: - The array with name NAME is associated with a primary global or local
-#:   shell variable with the same name. It contains a token TOKEN that is
-#:   used in variable names that make up the backing store of the array.
-#:   The value of this variable has the form ``_farr_A*_<TOKEN>``.
+#:   shell variable with the same name. Its value contains a token TOKEN that
+#:   is used in variable names that make up the backing store of the array.
+#:   The value of this variable has the form ``_farr_A[?]:<TOKEN>``.
 #: - Array elements for array NAME that has associated TOKEN are stored in
 #:   global variables named ``_farr_A_<TOKEN>_<index-number>`` (values)
 #:   and ``_farr_A_<TOKEN>__`` (length).
@@ -45,15 +45,31 @@
 #: Hints and rules for alists:
 #:
 #: - Every alist has a NAME.
-#: - One-based indexing is used internally.
 #: - The alist with name NAME is associated with a primary global or local
-#:   shell variable with the same name. It contains a token TOKEN that is
-#:   used in variable names that make up the backing stores of the alist.
-#:   The value of this variable is of the form ``_farr_KV*_<TOKEN>``.
-#: - The length of the alist is stored in a global ``_farr_KV_<token>__``.
-#: - Every key-value pair is stored at an INDEX.
-#: - Keys are stored in an associated global ``_farr_K_<TOKEN>_<INDEX>``.
-#: - Values are stored in an associated global ``_farr_V_<TOKEN>_<INDEX>``.
+#:   shell variable with the same name. Its value contains a token TOKEN that
+#:   is used in variable names that make up the backing stores of the alist.
+#:   The value of this variable is of the form ``_farr_KV[?,?]:<TOKEN>``.
+#: - The logical length of the alist (i.e. the number of key-value pairs)
+#:   is stored in a global ``_farr_KV_<TOKEN>__``.
+#: - Every key-value pair has an associated storage "pointer" SPTR.
+#:
+#:   * Keys are stored in an associated global ``_farr_Ks_<TOKEN>_<SPTR>``.
+#:     They are stored in the form ``<sptr-prev>;<sptr-next>@<key>``.
+#:     They make up a double-linked list and preserve information about
+#:     the insertion order.
+#:   * Values are stored in an associated global ``_farr_Vs_<TOKEN>_<SPTR>``.
+#:     They are stored in undecorated form.
+#:
+#:   Deleted entries are removed instantly from this lists.
+#:
+#:   "Pointers" to the first and last items are stored in a variabled named
+#:   ``_farr_KV_<TOKEN>_P`` in the form ``<sptr-first>;<sptr-last>``.
+#:
+#: - Additionally each key is stored in an array-like lexicographically ordered
+#:   structure at an index BSIDX. The name of the corresponding shell
+#:   variables are ``_farr_Kb_<TOKEN>_<BSIDX>. Its length is stored in
+#:   ``_farr_KV_<TOKEN>_B``. The form is ``<sptr>;V@<key>``.
+#:   Deletions are stored as "tombstones" in the form ``0;D@<key>``.
 #: - An alist name must conform to shell variable naming conventions.
 #: - Currently the number of of elements of an alist must be >= 0.
 #: - Variable NAME can also be a local variable. In this case it MUST
@@ -61,13 +77,12 @@
 #: - Any unset global variables ``_farr_KV_<TOKEN>__`` variable is a severe
 #:   error normally and forces an immediate fatal error exit by calling
 #:   ``exit``.
-#: - The same is true if ``_farr_K_<TOKEN>_<INDEX>`` or
-#:   ``_farr_V_<TOKEN>_<INDEX>`` is unexpectedly unset.
+#: - The same is true if other backing shell variables are unexpectedly unset.
 #:   Exceptions to this rule are documented.
 #: - An alist preserves insertion order. Note that updating a key does not
 #:   affect the order. Keys added after deletion are inserted at the end.
 #: - Alists compare equal if and only if they have the same (key, value) pairs
-#:   (regardless of ordering).
+#:   (regardless of insertion order).
 #:
 #: Hints and rules for indexes:
 #: