67 lines
3.0 KiB
Plaintext
67 lines
3.0 KiB
Plaintext
|
////
|
||
|
|
Copyright 2005-2008 Daniel James
|
||
|
|
Copyright 2022 Christian Mazakas
|
||
|
|
Copyright 2022 Peter Dimov
|
||
|
|
Distributed under the Boost Software License, Version 1.0.
|
||
|
|
https://www.boost.org/LICENSE_1_0.txt
|
||
|
|
////
|
||
|
|
|
||
|
|
[#intro]
|
||
|
|
= Introduction
|
||
|
|
:idprefix: intro_
|
||
|
|
|
||
|
|
`boost::hash` is an enhanced implementation of the
|
||
|
|
https://en.wikipedia.org/wiki/Hash_function[hash function] object specified by
|
||
|
|
{cpp}11 as `std::hash`. It is the default hash function for
|
||
|
|
link:../../../unordered/index.html[Boost.Unordered],
|
||
|
|
link:../../../intrusive/index.html[Boost.Intrusive]'s unordered associative
|
||
|
|
containers, link:../../../multi_index/index.html[Boost.MultiIndex]'s hash
|
||
|
|
indices, and link:../../../bimap/index.html[Boost.Bimap]'s `unordered_set_of`.
|
||
|
|
|
||
|
|
Out of the box, `boost::hash` supports
|
||
|
|
|
||
|
|
* standard integral types (integers, character types, and `bool`);
|
||
|
|
* standard floating point types (`float`, `double`, `long double`);
|
||
|
|
* pointers (to objects and to functions, but not pointers to members)
|
||
|
|
and `nullptr`;
|
||
|
|
* enumeration types;
|
||
|
|
* C arrays;
|
||
|
|
* `std::complex`;
|
||
|
|
* tuple-like types, such as `std::pair`, `std::tuple`, and user-defined
|
||
|
|
types that specialize `std::tuple_size` and provide `get<I>`;
|
||
|
|
* sequence-like types, both standard and user-defined (sequence-like types
|
||
|
|
have `begin()` and `end()` member functions returning iterators);
|
||
|
|
* unordered sequences, standard or user-defined (sequences for which the hash
|
||
|
|
value does not depend on the element order, such as `std::unordered_set` and
|
||
|
|
`std::unordered_map`);
|
||
|
|
* described structs and classes -- ones that have been annotated with the
|
||
|
|
`BOOST_DESCRIBE_STRUCT` or `BOOST_DESCRIBE_CLASS` macros from
|
||
|
|
link:../../../describe/index.html[Boost.Describe];
|
||
|
|
* `std::unique_ptr`, `std::shared_ptr`;
|
||
|
|
* `std::type_index`;
|
||
|
|
* `std::error_code`, `std::error_condition`;
|
||
|
|
* `std::optional`;
|
||
|
|
* `std::variant`, `std::monostate`.
|
||
|
|
|
||
|
|
`boost::hash` is extensible; it's possible for a user-defined type `X` to make
|
||
|
|
iself hashable via `boost::hash<X>` by defining an appropriate overload of the
|
||
|
|
function `hash_value`. Many, if not most, Boost types already contain the
|
||
|
|
necessary support.
|
||
|
|
|
||
|
|
`boost::hash` meets the requirements for `std::hash` specified in the {cpp}11
|
||
|
|
standard, namely, that for two different input values their corresponding hash
|
||
|
|
values are either guaranteed to be distinct, or the probability of their being
|
||
|
|
the same (a hash collision) is small. Standard unordered containers, and the
|
||
|
|
hash-based Boost containers, are designed to work well with such hash functions.
|
||
|
|
|
||
|
|
`boost::hash` does not meet the stronger requirements often placed on hash
|
||
|
|
functions in a more general context. In particular, the hash function is not
|
||
|
|
cryptographic, is not collision-resistant against a determined adversary, and
|
||
|
|
does not necessarily possess good "avalanche" properties; that is, small
|
||
|
|
(single bit) perturbations in the input do not necessarily result in large
|
||
|
|
(half bits changing) perturbations in the output.
|
||
|
|
|
||
|
|
In particular, `boost::hash` has traditionally been the identity function for
|
||
|
|
all integral types that fit into `std::size_t`, because this guarantees lack of
|
||
|
|
collisions and is as fast as possible.
|