Reference

| Home | Libraries | People | FAQ | More

## Reference

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

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

2.     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 `<boost/functional/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(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).

1.     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<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>`

       size_t seed = 0;
       hash_combine(seed, val.first);
       hash_combine(seed, val.second);
       return seed;

   `std::tuple<T...>`

       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()`