mirror of
https://github.com/boostorg/container_hash.git
synced 2025-08-04 15:04:39 +02:00
Update documentation
This commit is contained in:
Peter Dimov
@@ -1,6 +1,13 @@
|
||||
////
|
||||
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
|
||||
////
|
||||
|
||||
= Boost.ContainerHash
|
||||
:toc: left
|
||||
:toclevels: 2
|
||||
:toclevels: 3
|
||||
:idprefix:
|
||||
:docinfo: private-footer
|
||||
:source-highlighter: rouge
|
||||
@@ -12,13 +19,11 @@
|
||||
|
||||
include::hash/intro.adoc[]
|
||||
include::hash/tutorial.adoc[]
|
||||
include::hash/custom.adoc[]
|
||||
include::hash/user.adoc[]
|
||||
include::hash/combine.adoc[]
|
||||
include::hash/portability.adoc[]
|
||||
include::hash/disable.adoc[]
|
||||
include::hash/changes.adoc[]
|
||||
include::hash/reference.adoc[]
|
||||
include::hash/rationale.adoc[]
|
||||
include::hash/ref.adoc[]
|
||||
include::hash/links.adoc[]
|
||||
include::hash/thanks.adoc[]
|
||||
include::hash/changes.adoc[]
|
||||
include::hash/copyright.adoc[]
|
||||
@@ -1,11 +1,18 @@
|
||||
////
|
||||
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
|
||||
////
|
||||
|
||||
[#changes]
|
||||
= Change Log
|
||||
|
||||
:cpp: C++
|
||||
:int128: __int128
|
||||
|
||||
:idprefix: changes_
|
||||
|
||||
:int128: __int128
|
||||
|
||||
[discrete]
|
||||
== Boost 1.67.0
|
||||
* Moved library into its own module, `container_hash`.
|
||||
* Moved headers for new module name, now at: `<boost/container_hash/hash.hpp>`, `<boost/container_hash/hash_fwd.hpp>`, `<boost/container_hash/extensions.hpp>`.
|
||||
@@ -14,91 +21,113 @@
|
||||
* Update include paths from other Boost libraries.
|
||||
* Manually write out tuple overloads, rather than using the preprocessor to generate them. Should improve usability, due to better error messages, and easier debugging.
|
||||
* Fix tutorial example (https://svn.boost.org/trac/boost/ticket/11017[#11017]).
|
||||
* Quick fix for hashing `vector<bool>` when using lib{cpp}. Will try to introduce a more general fix in the next release.
|
||||
* Quick fix for hashing `vector<bool>` when using libc++. Will try to introduce a more general fix in the next release.
|
||||
|
||||
[discrete]
|
||||
== Boost 1.66.0
|
||||
* Avoid float comparison warning when using Clang - this workaround was already in place for GCC, and was used when Clang pretends to be GCC, but the warning was appearing when running Clang in other contexts.
|
||||
|
||||
[discrete]
|
||||
== Boost 1.65.0
|
||||
* Support for `char16_t`, `char32_t`, `u16string`, `u32string`
|
||||
|
||||
[discrete]
|
||||
== Boost 1.64.0
|
||||
* Fix for recent versions of Visual {cpp} which have removed `std::unary_function` and `std::binary_function` (https://svn.boost.org/trac/boost/ticket/12353[#12353]).
|
||||
|
||||
[discrete]
|
||||
== Boost 1.63.0
|
||||
* Fixed some warnings.
|
||||
* Only define hash for `std::wstring` when we know we have a `wchar_t`. Otherwise there's a compile error as there's no overload for hashing the characters in wide strings (https://svn.boost.org/trac/boost/ticket/8552[#8552]).
|
||||
|
||||
[discrete]
|
||||
== Boost 1.58.0
|
||||
* Fixed strict aliasing violation (https://github.com/boostorg/container_hash/issues/3[GitHub #3]).
|
||||
|
||||
[discrete]
|
||||
== Boost 1.56.0
|
||||
* Removed some Visual {cpp} 6 workarounds.
|
||||
* Ongoing work on improving `hash_combine`. This changes the combine function which was previously defined in the reference documentation.
|
||||
|
||||
[discrete]
|
||||
== Boost 1.55.0
|
||||
* Simplify a SFINAE check so that it will hopefully work on Sun 5.9 (https://svn.boost.org/trac10/ticket/8822[#8822]).
|
||||
* Suppress Visual {cpp} infinite loop warning (https://svn.boost.org/trac10/ticket/8568[#8568]).
|
||||
|
||||
[discrete]
|
||||
== Boost 1.54.0
|
||||
* https://svn.boost.org/trac/boost/ticket/7957[Ticket 7957]: Fixed a typo.
|
||||
|
||||
[discrete]
|
||||
== Boost 1.53.0
|
||||
* Add support for `boost::int128_type` and `boost::uint128_type` where available - currently only `{int128}` and `unsigned {int128}` on some versions of gcc.
|
||||
* On platforms that are known to have the standard floating point functions, don't use automatic detection - which can break if there are ambiguous overloads.
|
||||
* Fix undefined behaviour when using the binary `float` hash (Thomas Heller).
|
||||
|
||||
[discrete]
|
||||
== Boost 1.52.0
|
||||
* Restore `enum` support, which was accidentally removed in the last version.
|
||||
* New floating point hasher - will hash the binary representation on more platforms, which should be faster.
|
||||
|
||||
[discrete]
|
||||
== Boost 1.51.0
|
||||
* Support the standard smart pointers.
|
||||
* `hash_value` now implemented using SFINAE to avoid implicit casts to built in types when calling it.
|
||||
* Updated to use the new config macros.
|
||||
|
||||
[discrete]
|
||||
== Boost 1.50.0
|
||||
* https://svn.boost.org/trac/boost/ticket/6771[Ticket 6771]: Avoid gcc's `-Wfloat-equal` warning.
|
||||
* https://svn.boost.org/trac/boost/ticket/6806[Ticket 6806]: Support `std::array` and `std::tuple` when available.
|
||||
* Add deprecation warning to the long deprecated `boost/container_hash/detail/container_fwd.hpp`.
|
||||
|
||||
[discrete]
|
||||
== Boost 1.46.0
|
||||
* Avoid warning due with gcc's `-Wconversion` flag.
|
||||
|
||||
[discrete]
|
||||
== Boost 1.44.0
|
||||
* Add option to prevent implicit conversions when calling `hash_value` by defining `BOOST_HASH_NO_IMPLICIT_CASTS`. When using `boost::hash` for a type that does not have `hash_value` declared but does have an implicit conversion to a type that does, it would use that implicit conversion to hash it. Which can sometimes go very wrong, e.g. using a conversion to `bool` and only hashing to 2 possible values. Since fixing this is a breaking change and was only approached quite late in the release cycle with little discussion it's opt-in for now. This, or something like it, will become the default in a future version.
|
||||
|
||||
[discrete]
|
||||
== Boost 1.43.0
|
||||
* https://svn.boost.org/trac/boost/ticket/3866[Ticket 3866]: Don't foward declare containers when using gcc's parallel library, allow user to stop forward declaration by defining the `BOOST_DETAIL_NO_CONTAINER_FWD` macro.
|
||||
* https://svn.boost.org/trac/boost/ticket/4038[Ticket 4038]: Avoid hashing `0.5` and `0` to the same number.
|
||||
* Stop using deprecated `BOOST_HAS_*` macros.
|
||||
|
||||
[discrete]
|
||||
== Boost 1.42.0
|
||||
* Reduce the number of warnings for Visual {cpp} warning level 4.
|
||||
* Some code formatting changes to fit lines into 80 characters.
|
||||
* Rename an internal namespace.
|
||||
|
||||
[discrete]
|
||||
== Boost 1.40.0
|
||||
* Automatically configure the `float` functions using template metaprogramming instead of trying to configure every possibility manually.
|
||||
* Workaround for when STLport doesn't support long double.
|
||||
|
||||
[discrete]
|
||||
== Boost 1.39.0
|
||||
* Move the `hash_fwd.hpp` implementation into the hash subdirectory, leaving a forwarding header in the old location. You should still use the old location, the new location is mainly for implementation and possible modularization.
|
||||
* https://svn.boost.org/trac/boost/ticket/2412[Ticket 2412]: Removed deprecated headers.
|
||||
* https://svn.boost.org/trac/boost/ticket/2957[Ticket 2957]: Fix configuration for vxworks.
|
||||
|
||||
[discrete]
|
||||
== Boost 1.38.0
|
||||
* Changed the warnings in the deprecated headers from 1.34.0 to errors. These will be removed in a future version of Boost.
|
||||
* Moved detail headers out of `boost/container_hash/detail`, since they are part of `functional/hash`, not `container_hash`. `boost/container_hash/detail/container_fwd.hpp` has been moved to `boost/detail/container_fwd.hpp` as it's used outside of this library, the others have been moved to `boost/functional/hash/detail`.
|
||||
|
||||
[discrete]
|
||||
== Boost 1.37.0
|
||||
* http://svn.boost.org/trac/boost/ticket/2264[Ticket 2264]: In Visual {cpp}, always use C99 float functions for long double and float as the {cpp} overloads aren't always availables.
|
||||
|
||||
[discrete]
|
||||
== Boost 1.36.0
|
||||
* Stop using OpenBSD's dodgy `std::numeric_limits`.
|
||||
* Using the boost typedefs for `long long` and `unsigned long long`.
|
||||
* Move the extensions into their own header.
|
||||
|
||||
[discrete]
|
||||
== Boost 1.35.0
|
||||
* Support for `long long`, `std::complex`.
|
||||
* Improved algorithm for hashing floating point numbers:
|
||||
@@ -114,9 +143,11 @@
|
||||
** http://svn.boost.org/trac/boost/ticket/1509[Ticket 1509]: Suppress another Visual {cpp} warning.
|
||||
** Some workarounds for the Sun compilers.
|
||||
|
||||
[discrete]
|
||||
== Boost 1.34.1
|
||||
* https://svn.boost.org/trac10/ticket/952[Ticket 952]: Suppress incorrect 64-bit warning on Visual {cpp}.
|
||||
|
||||
[discrete]
|
||||
== Boost 1.34.0
|
||||
* Use declarations for standard classes, so that the library doesn't need to include all of their headers
|
||||
* Deprecated the `<boost/functional/hash/*.hpp>` headers. Now a single header, `<boost/functional/hash.hpp>` is used.
|
||||
@@ -124,9 +155,10 @@
|
||||
* Minor improvements to the hash functions for floating point numbers.
|
||||
* Update the portable example to hopefully be more generally portable.
|
||||
|
||||
[discrete]
|
||||
== Boost 1.33.1
|
||||
* Fixed the points example, as pointed out by 沈慧峰.
|
||||
|
||||
[discrete]
|
||||
== Boost 1.33.0
|
||||
* Initial Release
|
||||
|
||||
|
||||
@@ -1,6 +1,13 @@
|
||||
[#combine]
|
||||
= Combining hash values
|
||||
////
|
||||
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
|
||||
////
|
||||
|
||||
[#combine]
|
||||
= Combining Hash Values
|
||||
:idprefix: combine_
|
||||
|
||||
Say you have a point class, representing a two dimensional location:
|
||||
@@ -11,7 +18,9 @@ class point
|
||||
{
|
||||
int x;
|
||||
int y;
|
||||
|
||||
public:
|
||||
|
||||
point() : x(0), y(0) {}
|
||||
point(int x, int y) : x(x), y(y) {}
|
||||
|
||||
@@ -22,7 +31,10 @@ public:
|
||||
};
|
||||
----
|
||||
|
||||
and you wish to use it as the key for an unordered_map. You need to customise the hash for this structure. To do this we need to combine the hash values for x and y. The function `boost::hash_combine` is supplied for this purpose:
|
||||
and you wish to use it as the key for an `unordered_map`. You need to
|
||||
customise the hash for this structure. To do this we need to combine the
|
||||
hash values for `x` and `y`. The function `boost::hash_combine` is supplied
|
||||
for this purpose:
|
||||
|
||||
[source]
|
||||
----
|
||||
@@ -33,6 +45,7 @@ class point
|
||||
friend std::size_t hash_value(point const& p)
|
||||
{
|
||||
std::size_t seed = 0;
|
||||
|
||||
boost::hash_combine(seed, p.x);
|
||||
boost::hash_combine(seed, p.y);
|
||||
|
||||
@@ -43,20 +56,22 @@ class point
|
||||
};
|
||||
----
|
||||
|
||||
Calls to `hash_combine` incrementally build the hash from the different members of `point`, it can be repeatedly called for any number of elements. It calls `hash_value` on the supplied element, and combines it with the seed.
|
||||
Calls to `hash_combine` incrementally build the hash from the different
|
||||
members of `point`, it can be repeatedly called for any number of elements.
|
||||
It calls `hash_value` on the supplied element, and combines it with the seed.
|
||||
|
||||
Full code for this example is at link:../../examples/point.cpp[/libs/container_hash/examples/point.cpp].
|
||||
Full code for this example is at link:../../examples/point.cpp[examples/point.cpp].
|
||||
|
||||
Note that when using `boost::hash_combine` the order of the calls matters.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
When using `boost::hash_combine` the order of the calls matters.
|
||||
[source]
|
||||
----
|
||||
std::size_t seed = 0;
|
||||
boost::hash_combine(seed, 1);
|
||||
boost::hash_combine(seed, 2);
|
||||
----
|
||||
results in a different seed to:
|
||||
|
||||
and
|
||||
|
||||
[source]
|
||||
----
|
||||
@@ -65,9 +80,7 @@ boost::hash_combine(seed, 2);
|
||||
boost::hash_combine(seed, 1);
|
||||
----
|
||||
|
||||
If you are calculating a hash value for data where the order of the data doesn't matter in comparisons (e.g. a set) you will have to ensure that the data is always supplied in the same order.
|
||||
|
||||
====
|
||||
result in a different values in `seed`.
|
||||
|
||||
To calculate the hash of an iterator range you can use `boost::hash_range`:
|
||||
|
||||
@@ -77,4 +90,34 @@ std::vector<std::string> some_strings;
|
||||
std::size_t hash = boost::hash_range(some_strings.begin(), some_strings.end());
|
||||
----
|
||||
|
||||
Note that when writing template classes, you might not want to include the main hash header as it's quite an expensive include that brings in a lot of other headers, so instead you can include the `<boost/container_hash/hash_fwd.hpp>` header which forward declares `boost::hash`, `boost::hash_range` and `boost::hash_combine`. You'll need to include the main header before instantiating `boost::hash`. When using a container that uses `boost::hash` it should do that for you, so your type will work fine with the boost hash containers. There's an example of this in link:../../examples/template.hpp[template.hpp] and link:../../examples/template.cpp[template.cpp].
|
||||
Since `hash_range` works by repeatedly invoking `hash_combine` on the elements
|
||||
of the range, the hash value will also be dependent on the element order.
|
||||
|
||||
If you are calculating a hash value for a range where the order of the data
|
||||
doesn't matter, such as `unordered_set`, you can use
|
||||
`boost::hash_unordered_range` instead.
|
||||
|
||||
[source]
|
||||
----
|
||||
std::unordered_set<std::string> set;
|
||||
std::size_t hash = boost::hash_unordered_range(set.begin(), set.end());
|
||||
----
|
||||
|
||||
When writing template classes, you might not want to include the main
|
||||
`hash.hpp` header as it's quite an expensive include that brings in a lot of
|
||||
other headers, so instead you can include the
|
||||
`<boost/container_hash/hash_fwd.hpp>` header which forward declares
|
||||
`boost::hash`, `boost::hash_combine`, `boost::hash_range`, and
|
||||
`boost::hash_unordered_range`. You'll need to include the main header before
|
||||
instantiating `boost::hash`. When using a container that uses `boost::hash` it
|
||||
should do that for you, so your type will work fine with the Boost hash
|
||||
containers. There's an example of this in
|
||||
link:../../examples/template.hpp[examples/template.hpp] and
|
||||
link:../../examples/template.cpp[examples/template.cpp].
|
||||
|
||||
To avoid including even `hash_fwd.hpp` - which still requires the contents
|
||||
of Boost.ContainerHash to be physically present - you are allowed to copy the
|
||||
declarations from `hash_fwd.hpp` (and only those) directly into your own
|
||||
header. This is a special exception guaranteed by the library; in general,
|
||||
you can't declare library functions, Boost or otherwise, without risk of
|
||||
breakage in a subsequent release.
|
||||
|
||||
@@ -1,10 +1,18 @@
|
||||
////
|
||||
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
|
||||
////
|
||||
|
||||
[#copyright]
|
||||
= Copyright and License
|
||||
:idprefix:
|
||||
|
||||
:idprefix: copyright_
|
||||
This documentation is
|
||||
|
||||
*Daniel James*
|
||||
* Copyright 2005-2008 Daniel James
|
||||
* Copyright 2022 Peter Dimov
|
||||
|
||||
Copyright (C) 2005-2008 Daniel James
|
||||
|
||||
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)
|
||||
and is distributed under the http://www.boost.org/LICENSE_1_0.txt[Boost Software License, Version 1.0].
|
||||
|
||||
@@ -1,12 +0,0 @@
|
||||
[#disable]
|
||||
= Disabling The Extensions
|
||||
|
||||
:idprefix: disable_
|
||||
|
||||
While ``boost::hash``'s extensions are generally useful, you might want to turn them of in order to check that your code will work with other implementations of TR1. To do this define the macro `BOOST_HASH_NO_EXTENSIONS`. When this macro is defined, only the specialisations detailed in TR1 will be declared. But, if you later undefine the macro and include `<boost/container_hash/hash.hpp>` then the non-specialised form will be defined - activating the extensions.
|
||||
|
||||
It is strongly recommended that you never undefine the macro - and only define it so that it applies to the complete translation unit, either by defining it at the beginning of the main source file or, preferably, by using a compiler switch or preference. And you really should never define it in header files.
|
||||
|
||||
If you are writing a library which has code in the header which requires the extensions, then the best action is to tell users not to define the macro. Their code won't _require_ the macro.
|
||||
|
||||
Translation units that are compiled with the macro defined will link with units that were compiled without it. This feature has been designed to avoid ODR violations.
|
||||
@@ -1,22 +1,60 @@
|
||||
////
|
||||
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 implementation of the https://en.wikipedia.org/wiki/Hash_function[hash function] object specified by the http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf[Draft Technical Report on C++ Library Extensions] (TR1). It is the default hash function for link:../../../unordered/index.html[Boost.Unordered], link:../../../intrusive/index.html[Boost.Intrusive]'s unordered associative containers, and link:../../../multi_index/index.html[Boost.MultiIndex]'s hash indicies and link:../../../bimap/index.html[Boost.Bimap]'s `unordered_set_of`.
|
||||
`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
|
||||
indicies, and link:../../../bimap/index.html[Boost.Bimap]'s `unordered_set_of`.
|
||||
|
||||
As it is compliant with http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf[TR1], it will work with:
|
||||
Out of the box, `boost::hash` supports
|
||||
|
||||
* integers
|
||||
* floats
|
||||
* pointers
|
||||
* strings
|
||||
* 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);
|
||||
* enumeration types;
|
||||
* C arrays;
|
||||
* `std::complex`;
|
||||
* `std::pair`, `std::tuple`;
|
||||
* 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`);
|
||||
* `std::unique_ptr`, `std::shared_ptr`;
|
||||
* `std::type_index`;
|
||||
* `std::error_code`, `std::error_condition`;
|
||||
* `std::optional`;
|
||||
* `std::variant`, `std::monostate`.
|
||||
|
||||
It also implements the extension proposed by Peter Dimov in issue 6.18 of the http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1837.pdf[Library Extension Technical Report Issues List] (page 63), this adds support for:
|
||||
`boost::hash` is extensible; it's possible for a user-defined type `X` to make
|
||||
iself hashable via `boost::hash<X>`. Many, if not most, Boost types already
|
||||
contain the necessary support.
|
||||
|
||||
* arrays
|
||||
* `std::pair`
|
||||
* the standard containers.
|
||||
* extending `boost::hash` for custom types.
|
||||
`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.
|
||||
|
||||
NOTE: This hash function is designed to be used in containers based on the STL and is not suitable as a general purpose hash function. For more details see the <<rationale,rationale>>.
|
||||
`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.
|
||||
|
||||
@@ -1,82 +0,0 @@
|
||||
[#portability]
|
||||
= Portability
|
||||
|
||||
:idprefix: portability_
|
||||
|
||||
`boost::hash` is written to be as portable as possible, but unfortunately, several older compilers don't support argument dependent lookup (ADL) - the mechanism used for customisation. On those compilers custom overloads for `hash_value` needs to be declared in the `boost` namespace.
|
||||
|
||||
On a strictly standards compliant compiler, an overload defined in the `boost` namespace won't be found when `boost::hash` is instantiated, so for these compilers the overload should only be declared in the same namespace as the class.
|
||||
|
||||
Let's say we have a simple custom type:
|
||||
|
||||
[source]
|
||||
----
|
||||
namespace foo
|
||||
{
|
||||
template <class T>
|
||||
class custom_type
|
||||
{
|
||||
T value;
|
||||
public:
|
||||
custom_type(T x) : value(x) {}
|
||||
|
||||
friend std::size_t hash_value(custom_type x)
|
||||
{
|
||||
boost::hash<int> hasher;
|
||||
return hasher(x.value);
|
||||
}
|
||||
};
|
||||
}
|
||||
----
|
||||
|
||||
On a compliant compiler, when `hash_value` is called for this type, it will look at the namespace inside the type and find `hash_value` but on a compiler which doesn't support ADL `hash_value` won't be found. To make things worse, some compilers which do support ADL won't find a friend class defined inside the class.
|
||||
|
||||
So first move the member function out of the class:
|
||||
|
||||
[source]
|
||||
----
|
||||
namespace foo
|
||||
{
|
||||
template <class T>
|
||||
class custom_type
|
||||
{
|
||||
T value;
|
||||
public:
|
||||
custom_type(T x) : value(x) {}
|
||||
|
||||
std::size_t hash(custom_type x)
|
||||
{
|
||||
boost::hash<T> hasher;
|
||||
return hasher(value);
|
||||
}
|
||||
};
|
||||
|
||||
template <class T>
|
||||
inline std::size_t hash_value(custom_type<T> x)
|
||||
{
|
||||
return x.hash();
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
Unfortunately, I couldn't declare `hash_value` as a friend, as some compilers don't support template friends, so instead I declared a member function to calculate the hash, and called it from `hash_value`.
|
||||
|
||||
For compilers which don't support ADL, `hash_value` needs to be defined in the `boost` namespace:
|
||||
|
||||
[source]
|
||||
----
|
||||
#ifdef BOOST_NO_ARGUMENT_DEPENDENT_LOOKUP
|
||||
namespace boost
|
||||
#else
|
||||
namespace foo
|
||||
#endif
|
||||
{
|
||||
template <class T>
|
||||
std::size_t hash_value(foo::custom_type<T> x)
|
||||
{
|
||||
return x.hash();
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
Full code for this example is at link:../../examples/portable.cpp[/libs/container_hash/examples/portable.cpp].
|
||||
@@ -1,386 +0,0 @@
|
||||
[#ref]
|
||||
= Reference
|
||||
|
||||
:idprefix: ref_
|
||||
|
||||
For the full specification, see section 6.3 of the http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf[C++ Standard Library Technical Report] and issue 6.18 of the http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1837.pdf[Library Extension Technical Report Issues List] (page 63).
|
||||
|
||||
== Header <boost/container_hash/hash.hpp>
|
||||
|
||||
Defines `boost::hash`, and helper functions.
|
||||
|
||||
[source]
|
||||
----
|
||||
namespace boost {
|
||||
template<typename T> struct hash;
|
||||
|
||||
template<> struct hash<bool>;
|
||||
template<> struct hash<char>;
|
||||
template<> struct hash<signed char>;
|
||||
template<> struct hash<unsigned char>;
|
||||
template<> struct hash<wchar_t>;
|
||||
template<> struct hash<char16_t>;
|
||||
template<> struct hash<char32_t>;
|
||||
template<> struct hash<short>;
|
||||
template<> struct hash<unsigned short>;
|
||||
template<> struct hash<int>;
|
||||
template<> struct hash<unsigned int>;
|
||||
template<> struct hash<long>;
|
||||
template<> struct hash<unsigned long>;
|
||||
template<> struct hash<long long>;
|
||||
template<> struct hash<unsigned long long>;
|
||||
template<> struct hash<float>;
|
||||
template<> struct hash<double>;
|
||||
template<> struct hash<long double>;
|
||||
template<> struct hash<std::string>;
|
||||
template<> struct hash<std::wstring>;
|
||||
template<> struct hash<std::u16string>;
|
||||
template<> struct hash<std::u32string>;
|
||||
template<> struct hash<std::type_index>;
|
||||
|
||||
template<typename T> struct hash<T*>;
|
||||
|
||||
// Support functions (Boost extension).
|
||||
template<typename T>
|
||||
void hash_combine(size_t &, T const&);
|
||||
|
||||
template<typename It>
|
||||
std::size_t hash_range(It, It);
|
||||
|
||||
template<typename It>
|
||||
void hash_range(std::size_t&, It, It);
|
||||
|
||||
// Overloadable hash implementation (Boost extension).
|
||||
std::size_t hash_value(bool);
|
||||
std::size_t hash_value(char);
|
||||
std::size_t hash_value(signed char);
|
||||
std::size_t hash_value(unsigned char);
|
||||
std::size_t hash_value(wchar_t);
|
||||
std::size_t hash_value(char16_t);
|
||||
std::size_t hash_value(char32_t);
|
||||
std::size_t hash_value(short);
|
||||
std::size_t hash_value(unsigned short);
|
||||
std::size_t hash_value(int);
|
||||
std::size_t hash_value(unsigned int);
|
||||
std::size_t hash_value(long);
|
||||
std::size_t hash_value(unsigned long);
|
||||
std::size_t hash_value(long long);
|
||||
std::size_t hash_value(unsigned long long);
|
||||
std::size_t hash_value(float);
|
||||
std::size_t hash_value(double);
|
||||
std::size_t hash_value(long double);
|
||||
|
||||
template<typename T>
|
||||
std::size_t hash_value(T* const&);
|
||||
|
||||
template<typename T, unsigned N>
|
||||
std::size_t hash_value(T (&val)[N]);
|
||||
|
||||
template<typename T, unsigned N>
|
||||
std::size_t hash_value(const T (&val)[N]);
|
||||
|
||||
template<typename Ch, typename A>
|
||||
std::size_t hash_value(std::basic_string<Ch, std::char_traits<Ch>, A> const&);
|
||||
|
||||
template<typename A, typename B>
|
||||
std::size_t hash_value(std::pair<A, B> const&);
|
||||
|
||||
template<typename T, typename A>
|
||||
std::size_t hash_value(std::vector<T, A> const&);
|
||||
|
||||
template<typename T, typename A>
|
||||
std::size_t hash_value(std::list<T, A> const&);
|
||||
|
||||
template<typename T, typename A>
|
||||
std::size_t hash_value(std::deque<T, A> const&);
|
||||
|
||||
template<typename K, typename C, typename A>
|
||||
std::size_t hash_value(std::set<K, C, A> const&);
|
||||
|
||||
template<typename K, typename C, typename A>
|
||||
std::size_t hash_value(std::multiset<K, C, A> const&);
|
||||
|
||||
template<typename K, typename T, typename C, typename A>
|
||||
std::size_t hash_value(std::map<K, T, C, A> const&);
|
||||
|
||||
template<typename K, typename T, typename C, typename A>
|
||||
std::size_t hash_value(std::multimap<K, T, C, A> const&);
|
||||
|
||||
template<typename T> std::size_t hash_value(std::complex<T> const&);
|
||||
std::size_t hash_value(std::type_index);
|
||||
|
||||
template<typename T, std::size_t N>
|
||||
std::size_t hash_value(std::array<T, N> const&);
|
||||
|
||||
template<typename... T>
|
||||
std::size_t hash_value(std::tuple<T...>);
|
||||
}
|
||||
----
|
||||
|
||||
== Struct template hash
|
||||
|
||||
=== hash
|
||||
|
||||
`boost::hash` — A http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf[TR1] compliant hash function object.
|
||||
|
||||
==== Synopsis
|
||||
|
||||
[source]
|
||||
----
|
||||
// #include <boost/container_hash/hash.hpp>
|
||||
|
||||
template<typename T>
|
||||
struct hash : public std::unary_function<T, std::size_t> {
|
||||
std::size_t operator()(T const&) const;
|
||||
};
|
||||
----
|
||||
|
||||
==== Description
|
||||
|
||||
[source]
|
||||
----
|
||||
std::size_t operator()(T const& val) const;
|
||||
----
|
||||
|
||||
[horizontal]
|
||||
Returns:: `hash_value(val)`
|
||||
|
||||
Notes:: The call to `hash_value` is unqualified, so that custom overloads can be found via argument dependent lookup.
|
||||
+
|
||||
This is not defined when the macro `BOOST_HASH_NO_EXTENSIONS` is defined. The specializations are still defined, so only the specializations required by TR1 are defined.
|
||||
+
|
||||
Forward declared in `<boost/container_hash/hash_fwd.hpp>`
|
||||
+
|
||||
This hash function is not intended for general use, and isn't guaranteed to be equal during separate runs of a program - so please don't use it for any persistent storage or communication.
|
||||
|
||||
Throws:: Only throws if `hash_value(T)` throws.
|
||||
|
||||
== Specializations
|
||||
|
||||
`boost::hash<T>`
|
||||
|
||||
=== Synopsis
|
||||
|
||||
[source]
|
||||
----
|
||||
// #include <boost/container_hash/hash.hpp>
|
||||
|
||||
struct hash<T> {
|
||||
std::size_t operator()(T const&) const;
|
||||
};
|
||||
----
|
||||
|
||||
=== Description
|
||||
|
||||
[source]
|
||||
----
|
||||
std::size_t operator()(T const val) const;
|
||||
----
|
||||
|
||||
[horizontal]
|
||||
Returns:: Unspecified in TR1, except that equal arguments yield the same result.
|
||||
+
|
||||
`hash_value(val)` in Boost.
|
||||
|
||||
[horizontal]
|
||||
Throws:: Doesn't throw
|
||||
|
||||
== Support functions (Boost extension).
|
||||
|
||||
=== hash_combine
|
||||
|
||||
[source]
|
||||
----
|
||||
template<typename T>
|
||||
void hash_combine(size_t &, T const&);
|
||||
----
|
||||
|
||||
Called repeatedly to incrementally create a hash value from several variables.
|
||||
|
||||
[horizontal]
|
||||
Effects:: Updates seed with a new hash value generated by combining it with the result of `hash_value(v)`. Will always produce the same result for the same combination of seed and `hash_value(v)` during the single run of a program.
|
||||
|
||||
[horizontal]
|
||||
Notes:: `hash_value` is called without qualification, so that overloads can be found via ADL. +
|
||||
+
|
||||
This is an extension to TR1 +
|
||||
+
|
||||
Forward declared in `<boost/container_hash/hash_fwd.hpp>` +
|
||||
+
|
||||
This hash function is not intended for general use, and isn't guaranteed to be equal during separate runs of a program - so please don't use it for any persistent storage or communication.
|
||||
|
||||
[horizontal]
|
||||
Throws:: Only throws if `hash_value(T)` throws. Strong exception safety, as long as `hash_value(T)` also has strong exception safety.
|
||||
|
||||
=== hash_range
|
||||
|
||||
[source]
|
||||
----
|
||||
template<typename It>
|
||||
std::size_t hash_range(It, It);
|
||||
|
||||
template<typename It>
|
||||
void hash_range(std::size_t&, It, It);
|
||||
----
|
||||
|
||||
Calculate the combined hash value of the elements of an iterator range.
|
||||
|
||||
[horizontal]
|
||||
Effects:: For the two argument overload:
|
||||
+
|
||||
[source]
|
||||
----
|
||||
size_t seed = 0;
|
||||
|
||||
for(; first != last; ++first)
|
||||
{
|
||||
hash_combine(seed, *first);
|
||||
}
|
||||
return seed;
|
||||
----
|
||||
+
|
||||
For the three arguments overload:
|
||||
+
|
||||
[source]
|
||||
----
|
||||
for(; first != last; ++first)
|
||||
{
|
||||
hash_combine(seed, *first);
|
||||
}
|
||||
----
|
||||
|
||||
[horizontal]
|
||||
Notes:: `hash_range` is sensitive to the order of the elements so it wouldn't be appropriate to use this with an unordered container.
|
||||
+
|
||||
This is an extension to TR1
|
||||
+
|
||||
Forward declared in `<boost/container_hash/hash_fwd.hpp>`
|
||||
+
|
||||
This hash function is not intended for general use, and isn't guaranteed to be equal during separate runs of a program - so please don't use it for any persistent storage or communication.
|
||||
|
||||
[horizontal]
|
||||
Throws:: Only throws if `hash_value(std::iterator_traits<It>::value_type)` throws. `hash_range(std::size_t&, It, It)` has basic exception safety as long as `hash_value(std::iterator_traits<It>::value_type)` has basic exception safety.
|
||||
|
||||
== Overloadable hash implementation (Boost extension).
|
||||
|
||||
=== hash_value
|
||||
|
||||
[source]
|
||||
----
|
||||
std::size_t hash_value(bool val);
|
||||
std::size_t hash_value(char val);
|
||||
std::size_t hash_value(signed char val);
|
||||
std::size_t hash_value(unsigned char val);
|
||||
std::size_t hash_value(wchar_t val);
|
||||
std::size_t hash_value(char16_t val);
|
||||
std::size_t hash_value(char32_t val);
|
||||
std::size_t hash_value(short val);
|
||||
std::size_t hash_value(unsigned short val);
|
||||
std::size_t hash_value(int val);
|
||||
std::size_t hash_value(unsigned int val);
|
||||
std::size_t hash_value(long val);
|
||||
std::size_t hash_value(unsigned long val);
|
||||
std::size_t hash_value(long long val);
|
||||
std::size_t hash_value(unsigned long long val);
|
||||
std::size_t hash_value(float val);
|
||||
std::size_t hash_value(double val);
|
||||
std::size_t hash_value(long double val);
|
||||
|
||||
template<typename T> std::size_t hash_value(T* const& val);
|
||||
|
||||
template<typename T, unsigned N> std::size_t hash_value(T (&val)[N]);
|
||||
template<typename T, unsigned N> std::size_t hash_value(const T (&val)[N]);
|
||||
|
||||
template<typename Ch, typename A>
|
||||
std::size_t hash_value(std::basic_string<Ch, std::char_traits<Ch>, A> const& val);
|
||||
template<typename A, typename B>
|
||||
std::size_t hash_value(std::pair<A, B> const& val);
|
||||
template<typename T, typename A>
|
||||
std::size_t hash_value(std::vector<T, A> const& val);
|
||||
template<typename T, typename A>
|
||||
std::size_t hash_value(std::list<T, A> const& val);
|
||||
template<typename T, typename A>
|
||||
std::size_t hash_value(std::deque<T, A> const& val);
|
||||
template<typename K, typename C, typename A>
|
||||
std::size_t hash_value(std::set<K, C, A> const& val);
|
||||
template<typename K, typename C, typename A>
|
||||
std::size_t hash_value(std::multiset<K, C, A> const& val);
|
||||
template<typename K, typename T, typename C, typename A>
|
||||
std::size_t hash_value(std::map<K, T, C, A> const& val);
|
||||
template<typename K, typename T, typename C, typename A>
|
||||
std::size_t hash_value(std::multimap<K, T, C, A> const& val);
|
||||
template<typename T> std::size_t hash_value(std::complex<T> const& val);
|
||||
std::size_t hash_value(std::type_index val);
|
||||
template<typename T, std::size_t N>
|
||||
std::size_t hash_value(std::array<T, N> const& val);
|
||||
template<typename... T>
|
||||
std::size_t hash_value(std::tuple<T...> val);
|
||||
----
|
||||
|
||||
Implementation of the hash function.
|
||||
|
||||
Generally shouldn't be called directly by users, instead they should use `boost::hash`, `boost::hash_range` or `boost::hash_combine` which call `hash_value` without namespace qualification so that overloads for custom types are found via ADL.
|
||||
|
||||
[horizontal]
|
||||
Notes:: This is an extension to TR1
|
||||
+
|
||||
This hash function is not intended for general use, and isn't guaranteed to be equal during separate runs of a program - so please don't use it for any persistent storage or communication.
|
||||
|
||||
[horizontal]
|
||||
Throws:: Only throws if a user supplied version of `hash_value` throws for an element of a container, or one of the types stored in a pair.
|
||||
|
||||
[vertical]
|
||||
Returns::
|
||||
+
|
||||
[cols="1,1", frame=all, grid=rows]
|
||||
|===
|
||||
|Types |Returns
|
||||
|
||||
|`bool`, `char`, `signed char`, `unsigned char`, `wchar_t`, `char16_t`, `char32_t`, `short`, `unsigned short`, `int`, `unsigned int`, `long`, `unsigned long`
|
||||
|val
|
||||
|
||||
|`long long`, `unsigned long long`
|
||||
|val when `abs(val) \<= std::numeric_limits<std::size_t>::max()`.
|
||||
|
||||
|`float`, `double`, `long double`
|
||||
|An unspecified value, except that equal arguments shall yield the same result.
|
||||
|
||||
|`T*`
|
||||
|An unspecified value, except that equal arguments shall yield the same result.
|
||||
|
||||
|`T val[N]`, `const T val[N]`
|
||||
|`hash_range(val, val+N)`
|
||||
|
||||
|`std:basic_string<Ch, std::char_traits<Ch>, A>`, `std::vector<T, A>`, `std::list<T, A>`, `std::deque<T, A>`, `std::set<K, C, A>`, `std::multiset<K, C, A>`, `std::map<K, T, C, A>`, `std::multimap<K, T, C, A>`, `std::array<T, N>`
|
||||
|`hash_range(val.begin(), val.end())`
|
||||
|
||||
|`std::pair<A, B>`
|
||||
a|
|
||||
|
||||
[source]
|
||||
----
|
||||
size_t seed = 0;
|
||||
hash_combine(seed, val.first);
|
||||
hash_combine(seed, val.second);
|
||||
return seed;
|
||||
----
|
||||
|
||||
|`std::tuple<T...>`
|
||||
a|
|
||||
|
||||
[source]
|
||||
----
|
||||
size_t seed = 0;
|
||||
hash_combine(seed, get<0>(val));
|
||||
hash_combine(seed, get<1>(val));
|
||||
// ....
|
||||
return seed;
|
||||
----
|
||||
|
||||
|`std::complex<T>`
|
||||
|When T is a built in type and `val.imag() == 0`, the result is equal to `hash_value(val.real())`. Otherwise an unspecified value, except that equal arguments shall yield the same result.
|
||||
|
||||
|`std::type_index`
|
||||
|`val.hash_code()`
|
||||
|
||||
|===
|
||||
611
doc/hash/reference.adoc
Normal file
611
doc/hash/reference.adoc
Normal file
@@ -0,0 +1,611 @@
|
||||
////
|
||||
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
|
||||
////
|
||||
|
||||
[#reference]
|
||||
= Reference
|
||||
:idprefix: ref_
|
||||
|
||||
== <boost/container_hash/{zwsp}hash_fwd.hpp>
|
||||
|
||||
This header contains forward declarations for the library primitives.
|
||||
These declarations are guaranteed to be relatively stable, that is,
|
||||
best effort will be expended on their not changing from release to
|
||||
release, allowing their verbatim copy into user headers that do not
|
||||
wish to physically depend on Boost.ContainerHash.
|
||||
|
||||
[source]
|
||||
----
|
||||
namespace boost
|
||||
{
|
||||
|
||||
namespace container_hash
|
||||
{
|
||||
|
||||
template<class T> struct is_range;
|
||||
template<class T> struct is_contiguous_range;
|
||||
template<class T> struct is_unordered_range;
|
||||
|
||||
} // namespace container_hash
|
||||
|
||||
template<class T> struct hash;
|
||||
|
||||
template<class T> void hash_combine( std::size_t& seed, T const& v );
|
||||
|
||||
template<class It> void hash_range( std::size_t& seed, It first, It last );
|
||||
template<class It> std::size_t hash_range( It first, It last );
|
||||
|
||||
template<class It> void hash_unordered_range( std::size_t& seed, It first, It last );
|
||||
template<class It> std::size_t hash_unordered_range( It first, It last );
|
||||
|
||||
} // namespace boost
|
||||
----
|
||||
|
||||
== <boost/container_hash/{zwsp}hash.hpp>
|
||||
|
||||
Defines `boost::hash`, and helper functions.
|
||||
|
||||
[source]
|
||||
----
|
||||
namespace boost
|
||||
{
|
||||
|
||||
template<class T> struct hash;
|
||||
|
||||
template<class T> void hash_combine( std::size_t& seed, T const& v );
|
||||
|
||||
template<class It> void hash_range( std::size_t& seed, It first, It last );
|
||||
template<class It> std::size_t hash_range( It first, It last );
|
||||
|
||||
template<class It> void hash_unordered_range( std::size_t& seed, It first, It last );
|
||||
template<class It> std::size_t hash_unordered_range( It first, It last );
|
||||
|
||||
// Enabled only when T is an integral type
|
||||
template<class T>
|
||||
std::size_t hash_value( T v );
|
||||
|
||||
// Enabled only when T is an enumeration type
|
||||
template<class T>
|
||||
std::size_t hash_value( T v );
|
||||
|
||||
// Enabled only when T is a floating point type
|
||||
template<class T>
|
||||
std::size_t hash_value( T v );
|
||||
|
||||
template<class T>
|
||||
std::size_t hash_value( T* const& v );
|
||||
|
||||
template<class T, std::size_t N>
|
||||
std::size_t hash_value( T const (&v)[N] );
|
||||
|
||||
template<class T>
|
||||
std::size_t hash_value( std::complex<T> const& v );
|
||||
|
||||
template<class A, class B>
|
||||
std::size_t hash_value( std::pair<A, B> const& v );
|
||||
|
||||
template<class... T>
|
||||
std::size_t hash_value( std::tuple<T...> const& v );
|
||||
|
||||
// Enabled only when container_hash::is_range<T>::value is true
|
||||
template<class T>
|
||||
std::size_t hash_value( T const& v );
|
||||
|
||||
// Enabled only when container_hash::is_contiguous_range<T>::value is true
|
||||
template<class T>
|
||||
std::size_t hash_value( T const& v );
|
||||
|
||||
// Enabled only when container_hash::is_unordered_range<T>::value is true
|
||||
template<class T>
|
||||
std::size_t hash_value( T const& v );
|
||||
|
||||
template<class T>
|
||||
std::size_t hash_value( std::shared_ptr<T> const& v );
|
||||
|
||||
template<class T, class D>
|
||||
std::size_t hash_value( std::unique_ptr<T, D> const& v );
|
||||
|
||||
std::size_t hash_value( std::type_index const& v );
|
||||
|
||||
std::size_t hash_value( std::error_code const& v );
|
||||
std::size_t hash_value( std::error_condition const& v );
|
||||
|
||||
template<class T>
|
||||
std::size_t hash_value( std::optional<T> const& v );
|
||||
|
||||
std::size_t hash_value( std::monostate v );
|
||||
|
||||
template<class... T>
|
||||
std::size_t hash_value( std::variant<T...> const& v );
|
||||
|
||||
} // namespace boost
|
||||
----
|
||||
|
||||
=== hash<T>
|
||||
|
||||
[source]
|
||||
----
|
||||
template<class T> struct hash
|
||||
{
|
||||
std::size_t operator()( T const& v ) const;
|
||||
};
|
||||
----
|
||||
|
||||
==== operator()
|
||||
|
||||
[source]
|
||||
----
|
||||
std::size_t operator()( T const& v ) const;
|
||||
----
|
||||
|
||||
Returns: :: `hash_value( v )`.
|
||||
|
||||
Throws: :: Only throws if `hash_value( v )` throws.
|
||||
|
||||
Remarks: :: The call to `hash_value` is unqualified, so that user-supplied
|
||||
overloads will be found via argument dependent lookup.
|
||||
|
||||
=== hash_combine
|
||||
|
||||
[source]
|
||||
----
|
||||
template<class T> void hash_combine( std::size_t& seed, T const& v );
|
||||
----
|
||||
|
||||
Called repeatedly to incrementally create a hash value from several variables.
|
||||
|
||||
Effects: :: Updates `seed` with a new hash value generated by
|
||||
deterministically combining it with the result of `boost::hash<T>()( v )`.
|
||||
|
||||
Throws: :: Only throws if `boost::hash<T>()( v )` throws. On exception,
|
||||
`seed` is not updated.
|
||||
|
||||
Remarks: ::
|
||||
+
|
||||
--
|
||||
Equivalent to `seed = combine( seed, boost::hash<T>()( v ) )`,
|
||||
where `combine(s, v)` is a mixing function that takes two arguments of
|
||||
type `std::size_t` and returns `std::size_t`, with the following desirable
|
||||
properties:
|
||||
|
||||
* For a constant `s`, when `v` takes all possible `size_t` values,
|
||||
`combine(s, v)` should also take all possible `size_t` values, producing
|
||||
a sequence that is close to random; that is, it should be a random
|
||||
permutation.
|
||||
+
|
||||
This guarantees that for a given `seed`, `combine` does not introduce
|
||||
hash collisions when none were produced by `boost::hash<T>( v )`. It
|
||||
also implies that `combine(s, v)`, as a function of `v`, has good avalanche
|
||||
properties; that is, small (e.g. single bit) perturbations in the input `v`
|
||||
lead to large perturbations in the return value (half of the output bits
|
||||
changing, on average).
|
||||
|
||||
* For two different seeds `s1` and `s2`, `combine(s1, v)` and
|
||||
`combine(s2, v)`, treated as functions of `v`, should produce two
|
||||
different random permutations.
|
||||
|
||||
* `combine(0, 0)` should not be 0. Since a common initial value of `seed`
|
||||
is zero, `combine(0, 0) == 0` would imply that applying `hash_combine` on
|
||||
any sequence of zeroes, regardless of length, will produce zero. This is
|
||||
undesirable, as it would lead to e.g. `std::vector<int>()` and
|
||||
`std::vector<int>(4)` to have the same hash value.
|
||||
|
||||
The current implementation uses the function `mix(s + 0x9e3779b9 + v)` as
|
||||
`combine(s, v)`, where `mix` is a high quality random permutation over the
|
||||
`std::size_t` values (with the property that `mix(0)` is 0).
|
||||
--
|
||||
|
||||
=== hash_range
|
||||
|
||||
[source]
|
||||
----
|
||||
template<class It> void hash_range( std::size_t& seed, It first, It last );
|
||||
----
|
||||
|
||||
Effects: ::
|
||||
+
|
||||
[source]
|
||||
----
|
||||
for( ; first != last; ++first )
|
||||
{
|
||||
hash_combine<typename std::iterator_traits<It>::value_type>( seed, *first );
|
||||
}
|
||||
----
|
||||
|
||||
[source]
|
||||
----
|
||||
template<class It> std::size_t hash_range( It first, It last );
|
||||
----
|
||||
|
||||
Effects: ::
|
||||
+
|
||||
[source]
|
||||
----
|
||||
size_t seed = 0;
|
||||
hash_range( seed, first, last );
|
||||
return seed;
|
||||
----
|
||||
|
||||
=== hash_unordered_range
|
||||
|
||||
[source]
|
||||
----
|
||||
template<class It> void hash_unordered_range( std::size_t& seed, It first, It last );
|
||||
----
|
||||
|
||||
Effects: :: Updates `seed` with the values of
|
||||
`boost::hash<typename std::iterator_traits<It>::value_type>()( *i )`
|
||||
for each `i` in `[first, last)`, such that the order of elements does
|
||||
not affect the final result.
|
||||
|
||||
[source]
|
||||
----
|
||||
template<class It> std::size_t hash_unordered_range( It first, It last );
|
||||
----
|
||||
|
||||
Effects: ::
|
||||
+
|
||||
[source]
|
||||
----
|
||||
size_t seed = 0;
|
||||
hash_unordered_range( seed, first, last );
|
||||
return seed;
|
||||
----
|
||||
|
||||
=== hash_value
|
||||
|
||||
[source]
|
||||
----
|
||||
// Enabled only when T is an integral type
|
||||
template<class T>
|
||||
std::size_t hash_value( T v );
|
||||
----
|
||||
|
||||
Returns: ::
|
||||
When the value of `v` fits into `std::size_t`, when `T` is an unsigned type,
|
||||
or into `ssize_t`, when `T` is a signed type, `static_cast<std::size_t>(v)`.
|
||||
+
|
||||
Otherwise, an unspecified value obtained by mixing the value bits of `v`.
|
||||
|
||||
[source]
|
||||
----
|
||||
// Enabled only when T is an enumeration type
|
||||
template<class T>
|
||||
std::size_t hash_value( T v );
|
||||
----
|
||||
|
||||
Returns: ::
|
||||
`static_cast<std::size_t>(v)`.
|
||||
|
||||
Remarks: ::
|
||||
`hash_value( std::to_underlying(v) )` would be better, but {cpp}03
|
||||
compatibility mandates the current implementation.
|
||||
|
||||
[source]
|
||||
----
|
||||
// Enabled only when T is a floating point type
|
||||
template<class T>
|
||||
std::size_t hash_value( T v );
|
||||
----
|
||||
|
||||
Returns: ::
|
||||
An unspecified value obtained by mixing the value bits of `v`.
|
||||
|
||||
Remarks: ::
|
||||
When `sizeof(v) \<= sizeof(std::size_t)`, the bits of `v` are returned
|
||||
as-is (except in the case of -0.0, which is treated as +0.0).
|
||||
|
||||
[source]
|
||||
----
|
||||
template<class T>
|
||||
std::size_t hash_value( T* const& v );
|
||||
----
|
||||
|
||||
Returns: ::
|
||||
An unspecified value derived from `reinterpret_cast<std::uintptr_t>(v)`.
|
||||
|
||||
[source]
|
||||
----
|
||||
template<class T, std::size_t N>
|
||||
std::size_t hash_value( T const (&v)[N] );
|
||||
----
|
||||
|
||||
Returns: ::
|
||||
`hash_range( v, v + N )`.
|
||||
|
||||
[source]
|
||||
----
|
||||
template<class T>
|
||||
std::size_t hash_value( std::complex<T> const& v );
|
||||
----
|
||||
|
||||
Returns: ::
|
||||
An unspecified value derived from `boost::hash<T>()(v.real())` and
|
||||
`boost::hash<T>()(v.imag())` such that, if `v.imag() == 0`, the value
|
||||
is equal to `boost::hash<T>()(v.real())`.
|
||||
|
||||
Remarks: ::
|
||||
A more straightforward implementation would just have used `hash_combine`
|
||||
on `v.real()` and `v.imag()`, but the historical guarantee that real-valued
|
||||
complex numbers should match the hash value of their real part precludes it.
|
||||
+
|
||||
This guarantee may be dropped in a future release, as it's of questionable
|
||||
utility.
|
||||
|
||||
[source]
|
||||
----
|
||||
template<class A, class B>
|
||||
std::size_t hash_value( std::pair<A, B> const& v );
|
||||
----
|
||||
|
||||
Effects: ::
|
||||
+
|
||||
[source]
|
||||
----
|
||||
std::size_t seed = 0;
|
||||
|
||||
boost::hash_combine( seed, v.first );
|
||||
boost::hash_combine( seed, v.second );
|
||||
|
||||
return seed;
|
||||
----
|
||||
|
||||
[source]
|
||||
----
|
||||
template<class... T>
|
||||
std::size_t hash_value( std::tuple<T...> const& v );
|
||||
----
|
||||
|
||||
Effects: ::
|
||||
+
|
||||
[source]
|
||||
----
|
||||
std::size_t seed = 0;
|
||||
|
||||
boost::hash_combine( seed, std::get<0>(v) );
|
||||
boost::hash_combine( seed, std::get<1>(v) );
|
||||
// ...
|
||||
boost::hash_combine( seed, std::get<N-1>(v) );
|
||||
|
||||
return seed;
|
||||
----
|
||||
+
|
||||
where `N` is `sizeof...(T)`.
|
||||
|
||||
[source]
|
||||
----
|
||||
// Enabled only when container_hash::is_range<T>::value is true
|
||||
template<class T>
|
||||
std::size_t hash_value( T const& v );
|
||||
----
|
||||
|
||||
Returns: ::
|
||||
`hash_range( v.begin(), v.end() )`.
|
||||
|
||||
Remarks: ::
|
||||
This overload is only enabled when
|
||||
`container_hash::is_contiguous_range<T>::value` and
|
||||
`container_hash::is_unordered_range<T>::value` are both `false`.
|
||||
+
|
||||
It handles all standard containers that aren't contiguous or unordered, such
|
||||
as `std::deque`, `std::list`, `std::set`, `std::map`.
|
||||
|
||||
[source]
|
||||
----
|
||||
// Enabled only when container_hash::is_contiguous_range<T>::value is true
|
||||
template<class T>
|
||||
std::size_t hash_value( T const& v );
|
||||
----
|
||||
|
||||
Returns: ::
|
||||
`hash_range( v.data(), v.data() + v.size() )`.
|
||||
|
||||
Remarks: ::
|
||||
This overload handles all standard contiguous containers, such as
|
||||
`std::string`, `std::vector`, `std::array`, `std::string_view`.
|
||||
|
||||
[source]
|
||||
----
|
||||
// Enabled only when container_hash::is_unordered_range<T>::value is true
|
||||
template<class T>
|
||||
std::size_t hash_value( T const& v );
|
||||
----
|
||||
|
||||
Returns: ::
|
||||
`hash_unordered_range( v.begin(), v.end() )`.
|
||||
|
||||
Remarks: ::
|
||||
This overload handles the standard unordered containers, such as
|
||||
`std::unordered_set` and `std::unordered_map`.
|
||||
|
||||
[source]
|
||||
----
|
||||
template<class T>
|
||||
std::size_t hash_value( std::shared_ptr<T> const& v );
|
||||
|
||||
template<class T, class D>
|
||||
std::size_t hash_value( std::unique_ptr<T, D> const& v );
|
||||
----
|
||||
|
||||
Returns: ::
|
||||
`hash<T*>( v.get() )`.
|
||||
|
||||
[source]
|
||||
----
|
||||
std::size_t hash_value( std::type_index const& v );
|
||||
----
|
||||
|
||||
Returns: ::
|
||||
`v.hash_code()`.
|
||||
|
||||
[source]
|
||||
----
|
||||
std::size_t hash_value( std::error_code const& v );
|
||||
std::size_t hash_value( std::error_condition const& v );
|
||||
----
|
||||
|
||||
Effects: ::
|
||||
+
|
||||
[source]
|
||||
----
|
||||
std::size_t seed = 0;
|
||||
|
||||
boost::hash_combine( seed, v.value() );
|
||||
boost::hash_combine( seed, &v.category() );
|
||||
|
||||
return seed;
|
||||
----
|
||||
|
||||
[source]
|
||||
----
|
||||
template<class T>
|
||||
std::size_t hash_value( std::optional<T> const& v );
|
||||
----
|
||||
|
||||
Returns: ::
|
||||
For a disengaged `v`, an unspecified constant value; otherwise,
|
||||
`hash<T>()( *v )`.
|
||||
|
||||
[source]
|
||||
----
|
||||
std::size_t hash_value( std::monostate v );
|
||||
----
|
||||
|
||||
Returns: ::
|
||||
An unspecified constant value.
|
||||
|
||||
[source]
|
||||
----
|
||||
template<class... T>
|
||||
std::size_t hash_value( std::variant<T...> const& v );
|
||||
----
|
||||
|
||||
Effects: ::
|
||||
+
|
||||
[source]
|
||||
----
|
||||
std::size_t seed = 0;
|
||||
|
||||
boost::hash_combine( seed, v.index() );
|
||||
boost::hash_combine( seed, x );
|
||||
|
||||
return seed;
|
||||
----
|
||||
+
|
||||
where `x` is the currently contained value in `v`.
|
||||
|
||||
Throws: ::
|
||||
`std::bad_variant_access` when `v.valueless_by_exception()` is `true`.
|
||||
|
||||
== <boost/container_hash/{zwsp}is_range.hpp>
|
||||
|
||||
Defines the trait `boost::container_hash::is_range`.
|
||||
|
||||
[source]
|
||||
----
|
||||
namespace boost
|
||||
{
|
||||
|
||||
namespace container_hash
|
||||
{
|
||||
|
||||
template<class T> struct is_range;
|
||||
|
||||
} // namespace container_hash
|
||||
|
||||
} // namespace boost
|
||||
----
|
||||
|
||||
=== is_range<T>
|
||||
|
||||
[source]
|
||||
----
|
||||
template<class T> struct is_range
|
||||
{
|
||||
static constexpr bool value = /* see below */;
|
||||
};
|
||||
----
|
||||
|
||||
`is_range<T>::value` is `true` when, for a const value `x` of type
|
||||
`T`, `x.begin()` and `x.end()` return iterators of the same type
|
||||
`It` (such that `std::iterator_traits<It>` is a valid specialization.)
|
||||
|
||||
Users are allowed to specialize `is_range` for their types if the
|
||||
default behavior does not deduce the correct value.
|
||||
|
||||
== <boost/container_hash/{zwsp}is_contiguous_range.hpp>
|
||||
|
||||
Defines the trait `boost::container_hash::is_contiguous_range`.
|
||||
|
||||
[source]
|
||||
----
|
||||
namespace boost
|
||||
{
|
||||
|
||||
namespace container_hash
|
||||
{
|
||||
|
||||
template<class T> struct is_contiguous_range;
|
||||
|
||||
} // namespace container_hash
|
||||
|
||||
} // namespace boost
|
||||
----
|
||||
|
||||
=== is_contiguous_range<T>
|
||||
|
||||
[source]
|
||||
----
|
||||
template<class T> struct is_contiguous_range
|
||||
{
|
||||
static constexpr bool value = /* see below */;
|
||||
};
|
||||
----
|
||||
|
||||
`is_contiguous_range<T>::value` is `true` when `is_range<T>::value` is
|
||||
`true` and when, for a const value `x` of type `T`, `x.data()` returns
|
||||
a pointer to a type that matches the `value_type` of the iterator returned
|
||||
by `x.begin()` and `x.end()`, and `x.size()` returns a value of an integral
|
||||
type.
|
||||
|
||||
Users are allowed to specialize `is_contiguous_range` for their types
|
||||
if the default behavior does not deduce the correct value.
|
||||
|
||||
== <boost/container_hash/{zwsp}is_unordered_range.hpp>
|
||||
|
||||
Defines the trait `boost::container_hash::is_unordered_range`.
|
||||
|
||||
[source]
|
||||
----
|
||||
namespace boost
|
||||
{
|
||||
|
||||
namespace container_hash
|
||||
{
|
||||
|
||||
template<class T> struct is_unordered_range;
|
||||
|
||||
} // namespace container_hash
|
||||
|
||||
} // namespace boost
|
||||
----
|
||||
|
||||
=== is_unordered_range<T>
|
||||
|
||||
[source]
|
||||
----
|
||||
template<class T> struct is_unordered_range
|
||||
{
|
||||
static constexpr bool value = /* see below */;
|
||||
};
|
||||
----
|
||||
|
||||
`is_unordered_range<T>::value` is `true` when `is_range<T>::value` is
|
||||
`true` and when `T::hasher` is a valid type.
|
||||
|
||||
Users are allowed to specialize `is_unordered_range` for their types
|
||||
if the default behavior does not deduce the correct value.
|
||||
@@ -1,11 +1,23 @@
|
||||
////
|
||||
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
|
||||
////
|
||||
|
||||
[#tutorial]
|
||||
= Tutorial
|
||||
|
||||
:idprefix: tutorial_
|
||||
|
||||
When using a hash index with link:../../../multi_index/index.html[Boost.MultiIndex], you don't need to do anything to use `boost::hash` as it uses it by default. To find out how to use a user-defined type, read the <<custom,section on extending boost::hash for a custom data type>>.
|
||||
When using a Boost container such as
|
||||
link:../../../unordered/index.html[Boost.Unordered], you don't need to do
|
||||
anything to use `boost::hash` as it's the default. To find out how to use
|
||||
a user-defined type, read the <<user,section on extending boost::hash
|
||||
for user types>>.
|
||||
|
||||
If your standard library supplies its own implementation of the unordered associative containers and you wish to use `boost::hash`, just use an extra template parameter:
|
||||
If you wish to use `boost::hash` with the standard unordered associative
|
||||
containers, pass it as a template parameter:
|
||||
|
||||
[source]
|
||||
----
|
||||
@@ -27,12 +39,24 @@ To use `boost::hash` directly, create an instance and call it as a function:
|
||||
int main()
|
||||
{
|
||||
boost::hash<std::string> string_hash;
|
||||
|
||||
std::size_t h = string_hash("Hash me");
|
||||
}
|
||||
----
|
||||
|
||||
For an example of generic use, here is a function to generate a vector containing the hashes of the elements of a container:
|
||||
or alternatively:
|
||||
|
||||
[source]
|
||||
----
|
||||
#include <boost/container_hash/hash.hpp>
|
||||
|
||||
int main()
|
||||
{
|
||||
std::size_t h = boost::hash<std::string>()("Hash me");
|
||||
}
|
||||
----
|
||||
|
||||
For an example of generic use, here is a function to generate a vector
|
||||
containing the hashes of the elements of a container:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
@@ -1,11 +1,22 @@
|
||||
[#custom]
|
||||
= Extending boost::hash for a custom data type
|
||||
////
|
||||
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
|
||||
////
|
||||
|
||||
:idprefix: custom_
|
||||
[#user]
|
||||
= Extending boost::hash for User Types
|
||||
:idprefix: user_
|
||||
|
||||
`boost::hash` is implemented by calling the function `hash_value`. The namespace isn't specified so that it can detect overloads via argument dependant lookup. So if there is a free function `hash_value` in the same namespace as a custom type, it will get called.
|
||||
`boost::hash` is implemented by calling the function `hash_value`. The
|
||||
namespace isn't specified so that it can detect overloads via argument
|
||||
dependant lookup. So if there is a free function `hash_value` in the same
|
||||
namespace as a user type, it will get called.
|
||||
|
||||
If you have a structure `library::book`, where each book is uniquely defined by its member `id`:
|
||||
If you have a structure `library::book`, where each book is uniquely defined
|
||||
by its member `id`:
|
||||
|
||||
[source]
|
||||
----
|
||||
@@ -63,6 +74,13 @@ assert(books.find(knife) != books.end());
|
||||
assert(books.find(dandelion) == books.end());
|
||||
----
|
||||
|
||||
The full example can be found in: link:../../examples/books.hpp[/libs/container_hash/examples/books.hpp] and link:../../examples/books.cpp[/libs/container_hash/examples/books.cpp].
|
||||
The full example can be found in:
|
||||
link:../../examples/books.hpp[examples/books.hpp] and
|
||||
link:../../examples/books.cpp[examples/books.cpp].
|
||||
|
||||
TIP: When writing a hash function, first look at how the equality function works. Objects that are equal must generate the same hash value. When objects are not equal they should generate different hash values. In this object equality was based just on the id so the hash function only hashes the id. If it was based on the object's name and author then the hash function should take them into account (how to do this is discussed in the next section).
|
||||
TIP: When writing a hash function, first look at how the equality function
|
||||
works. Objects that are equal must generate the same hash value. When objects
|
||||
are not equal they should generate different hash values. In this object
|
||||
equality was based just on `id` so the hash function only hashes `id`. If it
|
||||
was based on the object's name and author then the hash function should take
|
||||
them into account (how to do this is discussed in the next section).
|
||||
@@ -3,12 +3,20 @@
|
||||
// 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)
|
||||
|
||||
// Force use of assert.
|
||||
#if defined(NDEBUG)
|
||||
#undef NDEBUG
|
||||
#endif
|
||||
|
||||
#include "./books.hpp"
|
||||
#include <boost/container_hash/hash.hpp>
|
||||
#include <boost/config.hpp>
|
||||
#include <cassert>
|
||||
|
||||
// If std::unordered_set was available:
|
||||
//#include <unordered_set>
|
||||
// If std::unordered_set is available:
|
||||
#if !defined(BOOST_NO_CXX11_HDR_UNORDERED_SET)
|
||||
#include <unordered_set>
|
||||
#endif
|
||||
|
||||
// This example illustrates how to use boost::hash with a custom hash function.
|
||||
// For full details, see the tutorial.
|
||||
@@ -22,18 +30,19 @@ int main()
|
||||
std::size_t knife_hash_value = book_hasher(knife);
|
||||
(void)knife_hash_value; // suppress unused variable warning
|
||||
|
||||
// If std::unordered_set was available:
|
||||
//
|
||||
//std::unordered_set<library::book, boost::hash<library::book> > books;
|
||||
//books.insert(knife);
|
||||
//books.insert(library::book(2443, "Lindgren, Torgny", "Hash"));
|
||||
//books.insert(library::book(1953, "Snyder, Bernadette M.",
|
||||
// "Heavenly Hash: A Tasty Mix of a Mother's Meditations"));
|
||||
// If std::unordered_set is available:
|
||||
#if !defined(BOOST_NO_CXX11_HDR_UNORDERED_SET)
|
||||
|
||||
//assert(books.find(knife) != books.end());
|
||||
//assert(books.find(dandelion) == books.end());
|
||||
std::unordered_set<library::book, boost::hash<library::book> > books;
|
||||
books.insert(knife);
|
||||
books.insert(library::book(2443, "Lindgren, Torgny", "Hash"));
|
||||
books.insert(library::book(1953, "Snyder, Bernadette M.",
|
||||
"Heavenly Hash: A Tasty Mix of a Mother's Meditations"));
|
||||
|
||||
return 0;
|
||||
assert(books.find(knife) != books.end());
|
||||
assert(books.find(dandelion) == books.end());
|
||||
|
||||
#endif
|
||||
}
|
||||
|
||||
namespace library
|
||||
|
||||
@@ -19,7 +19,9 @@ class point
|
||||
{
|
||||
int x;
|
||||
int y;
|
||||
|
||||
public:
|
||||
|
||||
point() : x(0), y(0) {}
|
||||
point(int x, int y) : x(x), y(y) {}
|
||||
|
||||
@@ -31,6 +33,7 @@ public:
|
||||
friend std::size_t hash_value(point const& p)
|
||||
{
|
||||
std::size_t seed = 0;
|
||||
|
||||
boost::hash_combine(seed, p.x);
|
||||
boost::hash_combine(seed, p.y);
|
||||
|
||||
|
||||
@@ -3,9 +3,14 @@
|
||||
// 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)
|
||||
|
||||
// Force use of assert.
|
||||
#if defined(NDEBUG)
|
||||
#undef NDEBUG
|
||||
#endif
|
||||
|
||||
#include "template.hpp"
|
||||
#include <cassert>
|
||||
#include <boost/unordered_set.hpp>
|
||||
#include <cassert>
|
||||
|
||||
int main()
|
||||
{
|
||||
|
||||
@@ -13,7 +13,9 @@ class my_pair
|
||||
{
|
||||
A value1;
|
||||
B value2;
|
||||
|
||||
public:
|
||||
|
||||
my_pair(A const& v1, B const& v2)
|
||||
: value1(v1), value2(v2)
|
||||
{}
|
||||
@@ -27,10 +29,10 @@ public:
|
||||
friend std::size_t hash_value(my_pair const& p)
|
||||
{
|
||||
std::size_t seed = 0;
|
||||
|
||||
boost::hash_combine(seed, p.value1);
|
||||
boost::hash_combine(seed, p.value2);
|
||||
|
||||
return seed;
|
||||
}
|
||||
};
|
||||
|
||||
|
||||
Reference in New Issue
Block a user