Reference


Header

For the full specification, see section 6.3 of the C++ Standard Library Technical Report and issue 6.18 of the Library Extension Technical Report Issues List (page 63).

Header <boost/functional/hash.hpp>

Defines boost::hash, and helper functions.

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<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<typename T> struct hash<T*>;
  template<> struct hash<std::type_index>;

  // 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(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...>);
}

Support functions (Boost extension).

template<typename T> void hash_combine(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 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.

Notes:

hash_value is called without qualification, so that overloads can be found via ADL.

This is an extension to TR1

Forward declared in

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. Strong exception safety, as long as hash_value(T) also has strong exception safety.

template<typename It> std::size_t hash_range(It first, It last);
template<typename It> void hash_range(std::size_t& seed, It first, It last);

Calculate the combined hash value of the elements of an iterator range.

Effects:

For the two argument overload:

size_t seed = 0;

for(; first != last; ++first)
{
    hash_combine(seed, *first);
}

return seed;

For the three arguments overload:

for(; first != last; ++first)
{
    hash_combine(seed, *first);
}

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

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(std::iterator_traits::value_type) throws. hash_range(std::size_t&, It, It) has basic exception safety as long as hash_value(std::iterator_traits::value_type) has basic exception safety.

Overloadable hash implementation (Boost extension).

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

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.

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.

Returns:

Types	Returns
`bool`, `char`, `signed char`, `unsigned char`, `wchar_t`, `short`, `unsigned short`, `int`, `unsigned int`, `long`, `unsigned long`	`val`
`long long`, `unsigned long long`	`val` when `abs(val) <= std::numeric_limits::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, A>`, `std::vector`, `std::list`, `std::deque`, `std::set`, `std::multiset`, `std::map`, `std::multimap`, `std::array`	`hash_range(val.begin(), val.end())`
`std::pair`	size_t seed = 0; hash_combine(seed, val.first); hash_combine(seed, val.second); return seed;
`std::tuple`	size_t seed = 0; hash_combine(seed, get<0>(val)); hash_combine(seed, get<1>(val)); // .... return seed;
`std::complex`	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()`

Boost C++ Libraries

Reference

Header <boost/functional/hash.hpp>

Support functions (Boost extension).

Overloadable hash implementation (Boost extension).