The primary use case for this type over [`HashMap`] or [`HashSet`] is to
support types that do not implement the [`Hash`] and [`Eq`] traits, but
instead require additional data not contained in the key itself to compute a
hash and compare two elements for equality.

`HashTable` has some similarities with `RawTable`, but has a completely
safe API. It is intended as a replacement for the existing raw entry
API, with the intend of deprecating the latter and eventually removing
it.

Examples of when this can be useful include:
- An `IndexMap` implementation where indices into a `Vec` are stored as
  elements in a `HashTable<usize>`. Hashing and comparing the elements
  requires indexing the associated `Vec` to get the actual value referred to
  by the index.
- Avoiding re-computing a hash when it is already known.
- Mutating the key of an element in a way that doesn't affect its hash.

To achieve this, `HashTable` methods that search for an element in the table
require a hash value and equality function to be explicitly passed in as
arguments. The method will then iterate over the elements with the given
hash and call the equality function on each of them, until a match is found.

Co-authored-by: Josh Stone <cuviper@gmail.com>