• Added the hash_is_avalanching trait class.

• C++03 is no longer supported.

• Added an overload of hash_value for std::nullptr_t.

• Added is_tuple_like and an overload of hash_value for tuple-like types.

• Changed string hashing to use mulxp1_hash, improving both quality and speed. This changes the hash values for string-like types (ranges of char, signed char, unsigned char, std::byte, char8_t).

Major update.

• The specializations of boost::hash have been removed; it now always calls hash_value.

• Support for BOOST_HASH_NO_EXTENSIONS has been removed. The extensions are always enabled.

• All standard containers are now supported. This includes std::forward_list and the unordered associative containers.

• User-defined containers (types that have begin() and end() member functions that return iterators) are now supported out of the box.

• Described structs and classes (those annotated with BOOST_DESCRIBE_STRUCT or BOOST_DESCRIBE_CLASS) are now supported out of the box.

• hash_combine has been improved. This changes the hash values of composite (container and tuple) types and of scalar types bigger than size_t.

• The performance (and quality, as a result of the above change) of string hashing has been improved. boost::hash for strings now passes SMHasher in 64 bit mode.

• The documentation has been substantially revised to reflect the changes.

• Fixed hash_combine so that its behavior no longer depends on whether size_t is the exact same type as boost::uint64_t (which wasn’t the case on macOS). This changes the hash values of composite (container and tuple) types on macOS.

std::unordered_multiset<int, boost::hash<int> >
 set_of_ints;

std::unordered_set<std::pair<int, int>, boost::hash<std::pair<int, int> > >
 set_of_pairs;

std::unordered_map<int, std::string, boost::hash<int> > map_int_to_string;

#include <boost/container_hash/hash.hpp>
int main()
{
 boost::hash<std::string> string_hash;
 std::size_t h = string_hash("Hash me");
}

#include <boost/container_hash/hash.hpp>
int main()
{
 std::size_t h = boost::hash<std::string>()("Hash me");
}

template <class Container>
std::vector<std::size_t> get_hashes(Container const& x)
{
 std::vector<std::size_t> hashes;
 std::transform(x.begin(), x.end(), std::back_inserter(hashes),
 boost::hash<typename Container::value_type>());

 return hashes;
}

namespace library
{
 struct book
 {
 int id;
 std::string author;
 std::string title;

 // ....
 };

 bool operator==(book const& a, book const& b)
 {
 return a.id == b.id;
 }
}

namespace library
{
 std::size_t hash_value(book const& b)
 {
 boost::hash<int> hasher;
 return hasher(b.id);
 }
}

library::book knife(3458, "Zane Grey", "The Hash Knife Outfit");
library::book dandelion(1354, "Paul J. Shanley",
 "Hash & Dandelion Greens");

boost::hash<library::book> book_hasher;
std::size_t knife_hash_value = book_hasher(knife);

// If std::unordered_set is 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"));

assert(books.find(knife) != books.end());
assert(books.find(dandelion) == books.end());

class point
{
 int x;
 int y;

public:

 point() : x(0), y(0) {}
 point(int x, int y) : x(x), y(y) {}

 bool operator==(point const& other) const
 {
 return x == other.x && y == other.y;
 }
};

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);

 return seed;
 }

 ...
};

std::size_t seed = 0;
boost::hash_combine(seed, 1);
boost::hash_combine(seed, 2);

std::size_t seed = 0;
boost::hash_combine(seed, 2);
boost::hash_combine(seed, 1);

std::vector<std::string> some_strings;
std::size_t hash = boost::hash_range(some_strings.begin(), some_strings.end());

std::unordered_set<std::string> set;
std::size_t hash = boost::hash_unordered_range(set.begin(), set.end());

class point
{
 int x;
 int y;

public:

 point() : x(0), y(0) {}
 point(int x, int y) : x(x), y(y) {}
};

#include <boost/describe/class.hpp>
#include <boost/describe/operators.hpp>
class point
{
 int x;
 int y;

 BOOST_DESCRIBE_CLASS(point, (), (), (), (x, y))

public:

 point() : x(0), y(0) {}
 point(int x, int y) : x(x), y(y) {}
};

using boost::describe::operators::operator==;
using boost::describe::operators::operator!=;

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.

Defines boost::hash, and helper functions.

hash<T>

template<class T> struct hash
{
 std::size_t operator()( T const& v ) const;
};

std::size_t operator()( T const& v ) const;

hash_combine

template<class T> void hash_combine( std::size_t& seed, T const& v );

hash_range

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 );

hash_unordered_range

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 );

hash_value

// 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 );

// Enabled only when container_hash::is_tuple_like<T>::value is true
template<class T>
 std::size_t hash_value( 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 );

// Enabled only when container_hash::is_described_class<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 );

Defines the trait boost::hash_is_avalanching.

hash_is_avalanching<Hash>

template<class Hash> struct hash_is_avalanching
{
 static constexpr bool value = /* see below */;
};

Defines the trait boost::container_hash::is_range.

is_range<T>

template<class T> struct is_range
{
 static constexpr bool value = /* see below */;
};

Defines the trait boost::container_hash::is_contiguous_range.

is_contiguous_range<T>

template<class T> struct is_contiguous_range
{
 static constexpr bool value = /* see below */;
};

Defines the trait boost::container_hash::is_unordered_range.

is_unordered_range<T>

template<class T> struct is_unordered_range
{
 static constexpr bool value = /* see below */;
};

Defines the trait boost::container_hash::is_described_class.

is_described_class<T>

template<class T> struct is_described_class
{
 static constexpr bool value = /* see below */;
};

Defines the trait boost::container_hash::is_tuple_like.

is_tuple_like<T>

template<class T> struct is_tuple_like
{
 static constexpr bool value = /* see below */;
};

Many hash functions strive to have little correlation between the input and output values. They attempt to uniformally distribute the output values for very similar inputs. This hash function makes no such attempt. In fact, for integers, the result of the hash function is often just the input value. So similar but different input values will often result in similar but different output values. This means that it is not appropriate as a general hash function. For example, a hash table may discard bits from the hash function resulting in likely collisions, or might have poor collision resolution when hash values are clustered together. In such cases this hash function will perform poorly.

But the standard has no such requirement for the hash function, it just requires that the hashes of two different values are unlikely to collide. Containers or algorithms designed to work with the standard hash function will have to be implemented to work well when the hash function’s output is correlated to its input. Since they are paying that cost a higher quality hash function would be wasteful.

The way one customizes the standard std::hash function object for user types is via a specialization. boost::hash chooses a different mechanism — an overload of a free function hash_value in the user namespace that is found via argument-dependent lookup.

Both approaches have their pros and cons. Specializing the function object is stricter in that it only applies to the exact type, and not to derived or convertible types. Defining a function, on the other hand, is easier and more convenient, as it can be done directly in the type definition as an inline friend.

The fact that overloads can be invoked via conversions did cause issues in an earlier iteration of the library that defined hash_value for all integral types separately, including bool. Especially under C++03, which doesn’t have explicit conversion operators, some types were convertible to bool to allow their being tested in e.g. if statements, which caused them to hash to 0 or 1, rarely what one expects or wants.

This, however, was fixed by declaring the built-in hash_value overloads to be templates constrained on e.g. std::is_integral or its moral equivalent. This causes types convertible to an integral to no longer match, avoiding the problem.

In general, the library does not promise that the hash values will stay the same from release to release (otherwise improvements would be impossible). However, historically values have been quite stable. Before release 1.81, the previous changes have been in 1.56 (a better hash_combine) and 1.78 (macOS-specific change to hash_combine.)

Code should generally not depend on specific hash values, but for those willing to take the risk of occasional breaks due to hash value changes, the library now has a test that checks hash values for a number of types against reference values (test/hash_reference_values.cpp), whose version history can be used as a rough guide to when hash values have changed, and for what types.

The initial implementation of the library was based on Issue 6.18 of the Library Extension Technical Report Issues List (pages 63-67) which proposed the following implementation of hash_combine:

taken from the paper "Methods for Identifying Versioned and Plagiarised Documents" by Timothy C. Hoad and Justin Zobel.

During the Boost formal review, Dave Harris pointed out that this suffers from the so-called "zero trap"; if seed is initially 0, and all the inputs are 0 (or hash to 0), seed remains 0 no matter how many input values are combined.

This is an undesirable property, because it causes containers of zeroes to have a zero hash value regardless of their sizes.

To fix this, the arbitrary constant 0x9e3779b9 (the golden ratio in a 32 bit fixed point representation) was added to the computation, yielding

This is what shipped in Boost 1.33, the first release containing the library.

This function was a reasonable compromise between quality and speed for its time, when the input consisted of chars, but it’s less suitable for combining arbitrary size_t inputs.

In Boost 1.56, it was replaced by functions derived from Austin Appleby’s MurmurHash2 hash function round.

In Boost 1.81, it was changed again — to the equivalent of mix(seed + 0x9e3779b9 + hash_value(v)), where mix(x) is a high quality mixing function that is a bijection over the size_t values, of the form

This type of mixing function was originally devised by Austin Appleby as the "final mix" part of his MurmurHash3 hash function. He used

as the 64 bit function fmix64 and

as the 32 bit function fmix32.

Several improvements of the 64 bit function have been subsequently proposed, by David Stafford, Pelle Evensen, and Jon Maiga. We currently use Jon Maiga’s function

Under 32 bit, we use a mixing function proposed by "TheIronBorn" in a Github issue in the repository of Hash Prospector by Chris Wellons:

With this improved hash_combine, boost::hash for strings now passes the SMHasher test suite by Austin Appleby (for a 64 bit size_t).

The traditional implementation of hash_range(seed, first, last) has been

(the explicit template parameter is needed to support iterators with proxy return types such as std::vector<bool>::iterator.)

This is logical, consistent and straightforward. In the common case where typename std::iterator_traits<It>::value_type is char — which it is in the common case of boost::hash<std::string> — this however leaves a lot of performance on the table, because processing each char individually is much less efficient than processing several in bulk.

In Boost 1.81, hash_range was changed to process elements of type char, signed char, unsigned char, std::byte, or char8_t, four of a time. A uint32_t is composed from first[0] to first[3], and that uint32_t is fed to hash_combine.

In Boost 1.82, hash_range for these types was changed to use mulxp1_hash. This improves both quality and speed of string hashing.

Note that hash_range has also traditionally guaranteed that the same element sequence yields the same hash value regardless of the iterator type. This property remains valid after the changes to char range hashing. hash_range, applied to the char sequence { 'a', 'b', 'c' }, results in the same value whether the sequence comes from char[3], std::string, std::deque<char>, or std::list<char>.

• 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>.

• Added forwarding headers to support the old headers locations.

• Support std::string_view, std::error_code, std::error_condition, std::optional, std::variant, std::monostate where available.

• 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 (#11017).

• Quick fix for hashing vector<bool> when using libc++. Will try to introduce a more general fix in the next release.

• 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.

• Support for char16_t, char32_t, u16string, u32string

• Fix for recent versions of Visual C++ which have removed std::unary_function and std::binary_function (#12353).

• 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 (#8552).

• Fixed strict aliasing violation (GitHub #3).

• Removed some Visual C++ 6 workarounds.

• Ongoing work on improving hash_combine. This changes the combine function which was previously defined in the reference documentation.

• Simplify a SFINAE check so that it will hopefully work on Sun 5.9 (#8822).

• Suppress Visual C++ infinite loop warning (#8568).

• Ticket 7957: Fixed a typo.

• 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).

• 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.

• 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.

• Ticket 6771: Avoid gcc’s -Wfloat-equal warning.

• Ticket 6806: Support std::array and std::tuple when available.

• Add deprecation warning to the long deprecated boost/container_hash/detail/container_fwd.hpp.

• Avoid warning due with gcc’s -Wconversion flag.

• 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.

• 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.

• Ticket 4038: Avoid hashing 0.5 and 0 to the same number.

• Stop using deprecated BOOST_HAS_* macros.

• Reduce the number of warnings for Visual C++ warning level 4.

• Some code formatting changes to fit lines into 80 characters.

• Rename an internal namespace.

• 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.

• 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.

• Ticket 2412: Removed deprecated headers.

• Ticket 2957: Fix configuration for vxworks.

• 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.

• Ticket 2264: In Visual C++, always use C99 float functions for long double and float as the C++ overloads aren’t always availables.

• 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.

• Support for long long, std::complex.

• Improved algorithm for hashing floating point numbers:

  • Improved portablity, as described by Daniel Krügler in a post to the boost users list.

  • Fits more information into each combine loop, which can reduce the the number of times combine is called and hopefully give a better quality hash function.

  • Improved the algorithm for hashing floating point numbers.

  • On Cygwin use a binary hash function for floating point numbers, as Cygwin doesn’t have decent floating point functions for long double.

  • Never uses fpclass which doesn’t support long double.

  • Ticket 1064: Removed unnecessary use of errno.

• Explicitly overload for more built in types.

• Minor improvements to the documentation.

• A few bug and warning fixes:

  • Ticket 1509: Suppress another Visual C++ warning.

  • Some workarounds for the Sun compilers.

• Ticket 952: Suppress incorrect 64-bit warning on Visual C++.

• 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.

• Add support for the BOOST_HASH_NO_EXTENSIONS macro, which disables the extensions to TR1.

• Minor improvements to the hash functions for floating point numbers.

• Update the portable example to hopefully be more generally portable.

• Fixed the points example, as pointed out by 沈慧峰.

• Initial Release