HELP DICT                                         Stephen Leach Sep 2021

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<           DICTS             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

Dicts are specialised tuples that map from names (or keys) to values. They are 
intended to represent ad hoc records with a fixed set of fields, where each 
field is associated with a word. Like records, they cannot have new fields
added after they are created (inextensible), can have the fields updated
(updateable), and do not have defaults.

--------------
1  Recognisers
--------------

is_null_dict(dict) -> bool
        Returns true if dict is empty, false otherwise.


isdict(item) -> bool
        Returns true if item is a dict, false otherwise.


is_key_in_dict( name, dict ) -> bool
        Return true if the word -name- is valid key of the dict.


---------------
2  Constructors
---------------

newdict_from_stack( key1, value1, ..., N ) -> newdict
        Creates a newdict object based a counted sequence of interleaved 
        key/value items on the stack. e.g.

                newdict_from_stack(#| "left", -1, "ahead", 0, "right", 1 |#)


newdict_from_assoclist(assoc_list) -> dict
        This constructs a dict from an assoc-list i.e. a list of key/values
        which are themselves a list of length 2 (or more). e.g.

                newdict_from_assoclist([[a 1] [b 2]])

        will return a dict that maps the word "a" to 1 and "b" to 2.


newdict_from_twinlists(keys_list, values_list) -> dict
        This constructs a dict from two lists, being a list of keys and
        a parallel list of values. The lists are not required to be of equal
        length, the first N items are taken when N is the lesser of the
        two lengths. e.g.

                newdict_from_twinlists([a b], [1 2])

        will return a dict that maps the word "a" to 1 and "b" to 2.


------------
3  Accessors
------------

dict_dest( dict ) -> key1, value1, ...., keyN, valueN, N )
        This returns a counted, interleaved sequence of key/value items.
        N is always an even integer.


dict_destkeys( dict ) -> ( key1, key2, ..., keyN, N )
        This returns all the keys of a dict on the stack and a count of
        the keys. The keys will be sorted in lexicographical order.


dist_destvalues( dict ) -> ( value1, value2, ..., valueN, N )
        This returns all the values of a dict on the stack and a count of
        the values returned. The values are returned in the same order as
        the keys.


dict( key ) -> value
value -> dict(key)
subscrdict(key, dict) -> value
value -> subscrdict(key, dict)
        This returns or updates the value associated with the key in the
        dict. subscrdict is the class_apply of the dict_key. The key must
        be a word.


----------------
4  Miscellaneous
----------------

appdict(dict, procedure )
        Applies the  procedure  p  to  each  entry  in  the  dict.  The
        procedure p is applied as:

            p(key, value)

        for each key/value association in dict.


dict_copy( dict ) -> newdict
        Creates a copy of an existing dict.

dict_key -> key
        Constant holding key structure for dict


dict_length(dict) -> N
        Returns the number N of key/values pairs in dict.


nulldict -> dict
        An instance of an empty dict object. N.B. ${} will return -nulldict-.


--- Copyright (c) GetPoplog Sep 2021 -------------------------------------------
