.. include:: ../../global.rst

.. _`hash table type`:

Hash Table Type
===============

Hash tables are arbitrary value indexed collections of references to
values.  The only value you cannot use as an index is ``#n``.

Reader Form
-----------

Hash tables of simple key and value types can be constructed with the
reader form

    :samp:`#\\{ [({key} & {value}) ...] }`

degenerating to ``#{}``.

Any :samp:`{key}` or :samp:`{value}` will not be evaluated, only
simple type construction (numbers, strings, symbols etc.) will occur.

This reader form ultimately calls :ref:`alist-\>hash <alist-\>hash>`
meaning the equivalence function will be the :lname:`C` implementation
of :ref:`equal? <equal?>` and the hashing function will be the default
:lname:`C` implementation.


Hash Table Predicates
---------------------


.. _`hash?`:

.. idio:function:: hash? o


   test if `o` is an hash				
   						
   :param o: object to test			
   :return: ``#t`` if `o` is an hash, ``#f`` otherwise	
   :rtype: boolean					


Hash Table Constructors
-----------------------


.. _`make-hash`:

.. idio:function:: make-hash [ equiv-func [ hash-func [size]]]


   create a hash table					
   							
   :param equiv-func: defaults to ``equal?``		
   :type equiv-func: function or symbol, optional		
   :param hash-func: defaults to ``hash-table-hash``	
   :type hash-func: function, optional			
   :param size: defaults to 32				
   :type size: fixnum, optional				
   :return: hash table					
   :rtype: hash table					
   							
   If either of `hash-func` or `equiv-func` is ``#n``	
   use the default.					
   							
   As an accelerator if `equiv-comp` is one of the		
   symbols ``'eq?``, ``'eqv?`` or ``'equal?`` then use the	
   underlying C function.					


.. _`alist->hash`:

.. idio:function:: alist->hash al [args]


   convert association list `al` into a hash table		
   							
   :param al: association list				
   :type al: association list				
   :param args: arguments for ``make-hash``		
   :type args: list, optional				
   :return: hash table					
   :rtype: hash table					
   							
   ``alist->hash`` will use :ref:`equal? <equal?>` as its	
   equivalence function and the default hashing function	
   							
   .. seealso:: :ref:`make-hash <make-hash>`		


.. _`copy-hash`:

.. idio:function:: copy-hash orig [depth]


   copy hash table `orig`					
   							
   :param orig: initial hash table				
   :type orig: hash table					
   :param depth: ``'shallow`` or ``'deep`` (default)	
   :type depth: symbol, optional				
   :return: the new hash table				
   :rtype: hash table					


.. _`merge-hash!`:

.. idio:function:: merge-hash! ht1 ht2


   merge the key/value pairs in hash table `ht2` into hash		
   table `ht1`							
   								
   duplicate keys in `ht2` will overwrite keys in `ht1`		
   								
   :param ht1: hash table						
   :type ht1: hash table						
   :param ht2: hash table						
   :type ht2: hash table						
   :return: `ht1`							
   :rtype: hash table						


Hash Table Attributes
---------------------


.. _`hash-size`:

.. idio:function:: hash-size h


   return the key count of `h`				
   							
   :param h: hash table					
   :type h: hash table					
   :return: key count					
   :rtype: integer						


.. _`hash-equivalence-function`:

.. idio:function:: hash-equivalence-function h


   return the `equiv-func` of `h`				
   							
   :param h: hash table					
   :type h: hash table					
   :return: equivalence function				
   :rtype: function or symbol (``eq?``, ``eqv?`` or ``equal?``)	


.. _`hash-hash-function`:

.. idio:function:: hash-hash-function h


   return the `hash-func` of `h`				
   							
   :param h: hash table					
   :type h: hash table					
   :return: hashing function				
   :rtype: function or ``#n`` if using the default		


.. _`hash-ref`:

.. idio:function:: hash-ref ht key [default]


   return the value indexed by `key` in hash table `ht`	
   							
   :param ht: hash table					
   :type ht: hash table					
   :param key: non-``#n`` value				
   :type key: any non-``#n``				
   :param default: a default value if `key` not found	
   :type default: a thunk or a simple value, optional	
   :return: value						
   :rtype: any						
   :raises ^rt-hash-key-not-found-error: if `key` not found	
   	and no `default` supplied			


.. _`hash-set!`:

.. idio:function:: hash-set! ht key v


   set the index of `key` in hash table `ht` to `v`	
   							
   :param ht: hash table					
   :type ht: hash table					
   :param key: non-``#n`` value				
   :type key: any non-``#n``				
   :param v: value						
   :type v: any						
   :return: ``#<unspec>``					


.. _`hash-delete!`:

.. idio:function:: hash-delete! ht key


   delete the value associated with index of `key` in	
   hash table `ht`					
   							
   :param ht: hash table					
   :type ht: hash table					
   :param key: non-``#n`` value				
   :type key: any non-``#n``				
   :return: ``#<unspec>``					


Hash Table Functions
--------------------


.. _`hash-exists?`:

.. idio:function:: hash-exists? ht key


   assert whether index of `key` in hash table `ht` exists	
   							
   :param ht: hash table					
   :type ht: hash table					
   :param key: non-``#n`` value				
   :type key: any non-``#n``				
   :return: ``#t`` or ``#f``				
   :rtype: boolean						


.. _`hash-update!`:

.. idio:function:: hash-update! ht key func [default]


   update the value indexed by `key` in hash table `ht`		
   								
   SRFI-69:							
   								
   Semantically equivalent to, but may be implemented more		
   efficiently than, the following code:				
   								
   .. code-block:: idio						
   								
      hash-set! ht key (func (hash-ref ht key [default])))		
   								
   That is, call `func` on the existing value and set the		
   key to the returned value					
   								
   :param ht: hash table						
   :type ht: hash table						
   :param key: non-``#n`` value					
   :type key: any non-``#n``					
   :param func: func to generate replacement value			
   :type func: 1-ary function					
   :param default: see ``hash-ref``				
   :type default: see ``hash-ref``					
   :return: ``#<unspec>``						
   								
   .. seealso:: :ref:`hash-ref <hash-ref>`				


.. _`hash-keys`:

.. idio:function:: hash-keys ht


   return a list of the keys of the hash table `ht`	
   							
   no order can be presumed				
   							
   :param ht: hash table					
   :type ht: hash table					
   :return: list of keys					
   :rtype: list						


.. _`hash-values`:

.. idio:function:: hash-values ht


   return a list of the values of the hash table `ht`	
   							
   no order can be presumed				
   							
   :param ht: hash table					
   :type ht: hash table					
   :return: list of values					
   :rtype: list						


.. _`hash-walk`:

.. idio:function:: hash-walk ht func


   call `func` for each `key` in hash table `ht`			
   								
   :param ht: hash table						
   :type ht: hash table						
   :param func: func to be called with each key, value pair	
   :type func: 2-ary function					
   :return: ``#<unspec>``						


.. _`fold-hash`:

.. idio:function:: fold-hash ht func val


   call `func` for each `key` in hash table `ht` with		
   arguments: `key`, the value indexed by `key` and `val`		
   								
   `val` is updated to the value returned by `func`		
   								
   The final value of `val` is returned				
   								
   :param ht: hash table						
   :type ht: hash table						
   :param func: func to be called with each key, value, val tuple	
   :type func: 3-ary function					
   :param val: initial value for `val`				
   :type val: any							
   :return: final value of `val`					
   :rtype: any							




.. include:: ../../commit.rst