# HG changeset patch # User Franz Glasner # Date 1729423630 -7200 # Node ID a339666cb42187ed91f233a63afebe7f01512808 # Parent 33df05108ba15f99700a5d42cc5810f042eabc61 farray.sh: Update docs to be in sync with the new alist implementation. diff -r 33df05108ba1 -r a339666cb421 share/local-bsdtools/farray.sh --- 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*_``. +#: 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[?]:``. #: - Array elements for array NAME that has associated TOKEN are stored in #: global variables named ``_farr_A__`` (values) #: and ``_farr_A___`` (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*_``. -#: - The length of the alist is stored in a global ``_farr_KV___``. -#: - Every key-value pair is stored at an INDEX. -#: - Keys are stored in an associated global ``_farr_K__``. -#: - Values are stored in an associated global ``_farr_V__``. +#: 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[?,?]:``. +#: - The logical length of the alist (i.e. the number of key-value pairs) +#: is stored in a global ``_farr_KV___``. +#: - Every key-value pair has an associated storage "pointer" SPTR. +#: +#: * Keys are stored in an associated global ``_farr_Ks__``. +#: They are stored in the form ``;@``. +#: They make up a double-linked list and preserve information about +#: the insertion order. +#: * Values are stored in an associated global ``_farr_Vs__``. +#: 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__P`` in the form ``;``. +#: +#: - 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__. Its length is stored in +#: ``_farr_KV__B``. The form is ``;V@``. +#: Deletions are stored as "tombstones" in the form ``0;D@``. #: - 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___`` variable is a severe #: error normally and forces an immediate fatal error exit by calling #: ``exit``. -#: - The same is true if ``_farr_K__`` or -#: ``_farr_V__`` 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: #: