[/
    Copyright (c) 2013-2016 Vinnie Falco (vinnie dot falco at gmail dot com)

    Distributed under the Boost Software License, Version 1.0. (See accompanying
    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]

[section:Hasher Hasher]

A [@Hasher] implements a hash algorithm. This is used to compute the small
digests NuDB needs to effectively implement a hash table. NuDB provides
the default implementation [link nudb.ref.nudb__xxhasher xxhasher], which is
suitable for most use cases. For advanced applications, a user supplied
hash function may be supplied which must meet these requirements.

In the table below:

* `X` denotes a hasher class
* `a` denotes a value of type `X const`
* `s` denotes a value of type `std::uint64_t`
* `p` denotes a value of type `void const*`
* `n` denotes a value of type `std::size_t`

[table Hasher requirements
[[operation] [type] [semantics, pre/post-conditions]]
[
    [`X a{s}`]
    [ ]
    [
        `a` is constructed with a seed value integer. To achieve resistance
        from algorithmic complexity attacks, an implementation of [*Hasher]
        should ensure that values returned from the hash function will be
        distinctly different for different values of `s` given the same
        inputs. If algorithmic complexity attack resistance is not a
        requirement, the seed may be ignored upon construction.
    ]
]
[
    [`a(p,n)`]
    [ `std::uint64_t` ]
    [
        Returns the digest of the memory `n` bytes in size and pointed
        to by `p`. `n` will never be zero. A good hash function will
        return values with these qualities:

* Values are uniformly distributed in the full range

* Values for the same input are distinctly different for different seeds

* Small changes in the input produce unpredictable output values

    ]
]
]

[endsect]
