Hash: Add some notes about forwarding header. Refs #6849.

[SVN r78366]

hash/doc/ref.xml

@@ -55,6 +55,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
               is defined. The specializations are still defined, so only the specializations
               required by TR1 are defined.
             </para>
+            <para>
+              Forward declared in
+              <code>&lt;boost/functional/hash_fwd.hpp&gt;</code>
+            </para>
           </notes>
           <throws><para>
             Only throws if
@@ -451,6 +455,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
           <para><functionname>hash_value</functionname> is called without
           qualification, so that overloads can be found via ADL.</para>
           <para>This is an extension to TR1</para>
+          <para>
+            Forward declared in
+            <code>&lt;boost/functional/hash_fwd.hpp&gt;</code>
+          </para>
         </notes>
         <throws>
           Only throws if <functionname>hash_value</functionname>(T) throws.
@@ -499,15 +507,14 @@ for(; first != last; ++first)
 
 return seed;
 </programlisting>
-          </para>For the three arguments overload:
+          </para>
+          <para>For the three arguments overload:</para>
 <programlisting>
 for(; first != last; ++first)
 {
     <functionname>hash_combine</functionname>(seed, *first);
 }
 </programlisting>
-          <para>
-          </para>
         </effects>
         <notes>
           <para>
@@ -516,6 +523,10 @@ for(; first != last; ++first)
             container.
           </para>
           <para>This is an extension to TR1</para>
+          <para>
+            Forward declared in
+            <code>&lt;boost/functional/hash_fwd.hpp&gt;</code>
+          </para>
         </notes>
         <throws><para>
           Only throws if <code><functionname>hash_value</functionname>(std::iterator_traits&lt;It&gt;::value_type)</code>

hash/doc/tutorial.qbk

@@ -198,5 +198,15 @@ To calculate the hash of an iterator range you can use [funcref boost::hash_rang
     std::vector<std::string> some_strings;
     std::size_t hash = ``[funcref boost::hash_range]``(some_strings.begin(), some_strings.end());
 
-[endsect]
+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/functional/hash_fwd.hpp>`
+header which forward declares [classref boost::hash],
+[funcref boost::hash_range] and [funcref boost::hash_combine]. You'll need to
+include the main header before instantiating [classref boost::hash]. When using
+a container that uses [classref 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 [@boost:/libs/unordered/examples/template.hpp template.hpp] and
+[@boost:/libs/unordered/examples/template.cpp template.cpp].
 
+[endsect]

hash/examples/Jamfile.v2

@@ -6,3 +6,4 @@
 run books.cpp ;
 run point.cpp ;
 run portable.cpp ;
+run template.cpp ;

hash/examples/template.cpp

@@ -0,0 +1,18 @@
+
+// Copyright 2012 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)
+
+#include "template.hpp"
+#include <cassert>
+#include <boost/unordered_set.hpp>
+
+int main()
+{
+    typedef my_pair<int, float> pair;
+    boost::unordered_set<pair> pair_set;
+    pair_set.emplace(10, 0.5f);
+
+    assert(pair_set.find(pair(10, 0.5f)) != pair_set.end());
+    assert(pair_set.find(pair(10, 0.6f)) == pair_set.end());
+}

hash/examples/template.hpp

@@ -0,0 +1,36 @@
+
+// Copyright 2012 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)
+
+// This is an example of how to write a hash function for a template
+// class.
+
+#include <boost/functional/hash_fwd.hpp>
+
+template <typename A, typename B>
+class my_pair
+{
+    A value1;
+    B value2;
+public:
+    my_pair(A const& v1, B const& v2)
+        : value1(v1), value2(v2)
+    {}
+
+    bool operator==(my_pair const& other) const
+    {
+        return value1 == other.value1 &&
+            value2 == other.value2;
+    }
+
+    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;
+    }
+};
+