= The `HashTable` structure
:Author: John Reppy
:Date: {release-date}
:stem: latexmath
:source-highlighter: pygments
:VERSION: {smlnj-version}

The `HashTable` structure implements hash tables that are polymorphic
in the key type.

== Synopsis

[source,sml]
------------
structure HashTable
------------

== Interface

[source,sml]
------------
    type ('a, 'b) hash_table
	(* type of hash table mapping 'a to 'b *)

    val mkTable : (('a -> word) * (('a * 'a) -> bool)) -> (int * exn)
	  -> ('a,'b) hash_table
	(* Given a hashing function and an equality predicate, create a new table;
	 * the int is a size hint and the exception is to be raised by find.
	 *)

    val clear : ('a, 'b) hash_table -> unit
	(* remove all elements from the table *)

    val insert : ('a, 'b) hash_table -> ('a * 'b) -> unit
	(* Insert an item.  If the key already has an item associated with it,
	 * then the old item is discarded.
	 *)

    val inDomain : ('a, 'b) hash_table -> 'a -> bool
	(* return true, if the key is in the domain of the table *)

    val lookup : ('a, 'b) hash_table -> 'a -> 'b
	(* Find an item, the table's exception is raised if the item doesn't exist *)

    val find : ('a, 'b) hash_table -> 'a -> 'b option
	(* Look for an item, return NONE if the item doesn't exist *)

    val remove : ('a, 'b) hash_table -> 'a -> 'b
	(* Remove an item, returning the item.  The table's exception is raised if
	 * the item doesn't exist.
	 *)

    val numItems : ('a, 'b) hash_table ->  int
	(* Return the number of items in the table *)

    val listItems  : ('a, 'b) hash_table -> 'b list
    val listItemsi : ('a, 'b) hash_table -> ('a * 'b) list
	(* Return a list of the items (and their keys) in the table *)

    val app  : ('b -> unit) -> ('a, 'b) hash_table -> unit
    val appi : (('a * 'b) -> unit) -> ('a, 'b) hash_table -> unit
	(* Apply a function to the entries of the table *)

    val map  : ('b -> 'c) -> ('a, 'b) hash_table -> ('a, 'c) hash_table
    val mapi : (('a * 'b) -> 'c) -> ('a, 'b) hash_table -> ('a, 'c) hash_table
	(* Map a table to a new table that has the same keys *)

    val fold  : (('b *'c) -> 'c) -> 'c -> ('a, 'b) hash_table -> 'c
    val foldi : (('a * 'b * 'c) -> 'c) -> 'c -> ('a, 'b) hash_table -> 'c
	(* Fold a function over the elements of a table *)

    val modify  : ('b -> 'b) -> ('a, 'b) hash_table -> unit
    val modifyi : (('a * 'b) -> 'b) -> ('a, 'b) hash_table -> unit
	(* modify the hash-table items in place *)

    val filter  : ('b -> bool) -> ('a, 'b) hash_table -> unit
    val filteri : (('a * 'b) -> bool) -> ('a, 'b) hash_table -> unit
	(* remove any hash table items that do not satisfy the given
	 * predicate.
	 *)

    val copy : ('a, 'b) hash_table -> ('a, 'b) hash_table
	(* Create a copy of a hash table *)

    val bucketSizes : ('a, 'b) hash_table -> int list
	(* returns a list of the sizes of the various buckets.  This is to
	 * allow users to gauge the quality of their hashing function.
	 *)
------------

== Description

`[.kw]#type# ('a, 'b) hash_table`::
  something
	(* type of hash table mapping 'a to 'b *)

`[.kw]#val# mkTable : (('a \-> word) * (('a * 'a) \-> bool)) \-> (int * exn)`::
  something
	  \-> ('a,'b) hash_table
	(* Given a hashing function and an equality predicate, create a new table;
	 * the int is a size hint and the exception is to be raised by find.
	 *)

`[.kw]#val# clear : ('a, 'b) hash_table \-> unit`::
  something
	(* remove all elements from the table *)

`[.kw]#val# insert : ('a, 'b) hash_table \-> ('a * 'b) \-> unit`::
  something
	(* Insert an item.  If the key already has an item associated with it,
	 * then the old item is discarded.
	 *)

`[.kw]#val# inDomain : ('a, 'b) hash_table \-> 'a \-> bool`::
  something
	(* return true, if the key is in the domain of the table *)

`[.kw]#val# lookup : ('a, 'b) hash_table \-> 'a \-> 'b`::
  something
	(* Find an item, the table's exception is raised if the item doesn't exist *)

`[.kw]#val# find : ('a, 'b) hash_table \-> 'a \-> 'b option`::
  something
	(* Look for an item, return NONE if the item doesn't exist *)

`[.kw]#val# remove : ('a, 'b) hash_table \-> 'a \-> 'b`::
  something
	(* Remove an item, returning the item.  The table's exception is raised if
	 * the item doesn't exist.
	 *)

`[.kw]#val# numItems : ('a, 'b) hash_table \->  int`::
  something
	(* Return the number of items in the table *)

`[.kw]#val# listItems  : ('a, 'b) hash_table \-> 'b list`::
  something
`[.kw]#val# listItemsi : ('a, 'b) hash_table \-> ('a * 'b) list`::
  something
	(* Return a list of the items (and their keys) in the table *)

`[.kw]#val# app  : ('b \-> unit) \-> ('a, 'b) hash_table \-> unit`::
  something
`[.kw]#val# appi : (('a * 'b) \-> unit) \-> ('a, 'b) hash_table \-> unit`::
  something
	(* Apply a function to the entries of the table *)

`[.kw]#val# map  : ('b \-> 'c) \-> ('a, 'b) hash_table \-> ('a, 'c) hash_table`::
  something
`[.kw]#val# mapi : (('a * 'b) \-> 'c) \-> ('a, 'b) hash_table \-> ('a, 'c) hash_table`::
  something
	(* Map a table to a new table that has the same keys *)

`[.kw]#val# fold  : (('b *'c) \-> 'c) \-> 'c \-> ('a, 'b) hash_table \-> 'c`::
  something
`[.kw]#val# foldi : (('a * 'b * 'c) \-> 'c) \-> 'c \-> ('a, 'b) hash_table \-> 'c`::
  something
	(* Fold a function over the elements of a table *)

`[.kw]#val# modify  : ('b \-> 'b) \-> ('a, 'b) hash_table \-> unit`::
  something
`[.kw]#val# modifyi : (('a * 'b) \-> 'b) \-> ('a, 'b) hash_table \-> unit`::
  something
	(* modify the hash-table items in place *)

`[.kw]#val# filter  : ('b \-> bool) \-> ('a, 'b) hash_table \-> unit`::
  something
`[.kw]#val# filteri : (('a * 'b) \-> bool) \-> ('a, 'b) hash_table \-> unit`::
  something
	(* remove any hash table items that do not satisfy the given
	 * predicate.
	 *)

`[.kw]#val# copy : ('a, 'b) hash_table \-> ('a, 'b) hash_table`::
  something
	(* Create a copy of a hash table *)

`[.kw]#val# bucketSizes : ('a, 'b) hash_table \-> int list`::
  something
	(* returns a list of the sizes of the various buckets.  This is to
	 * allow users to gauge the quality of their hashing function.
	 *)

== See Also

xref:smlnj-lib.adoc[__The Util Library__]
