Hash: Merge deprecated header warning + some documentation.

[SVN r78697]

doc/changes.qbk

@@ -129,5 +129,7 @@
   Avoid gcc's `-Wfloat-equal` warning.
 * [@http://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/functional/detail/container_fwd.hpp`.
 
 [endsect]

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>

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]

examples/Jamfile.v2

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

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

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;
+    }
+};
+

include/boost/functional/detail/container_fwd.hpp

@@ -1,11 +1,11 @@
 
-// Copyright 2005-2008 Daniel James.
+// Copyright 2005-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)
 
 // Forwarding header for container_fwd.hpp's new location.
-// This header is deprecated, I'll be adding a warning in a future release,
-// then converting it to an error and finally removing this header completely.
+// This header is deprecated, I'll change the warning to an error in a future
+// release, and then later remove the header completely.
 
 #if !defined(BOOST_FUNCTIONAL_DETAIL_CONTAINER_FWD_HPP)
 #define BOOST_FUNCTIONAL_DETAIL_CONTAINER_FWD_HPP
@@ -14,6 +14,14 @@
 # pragma once
 #endif
 
+#if defined(__EDG__)
+#elif defined(_MSC_VER) || defined(__BORLANDC__) || defined(__DMC__)
+#pragma message("Warning: boost/functional/detail/container_fwd.hpp is deprecated, use boost/detail/container_fwd.hpp instead.")
+#elif defined(__GNUC__) || defined(__HP_aCC) || \
+    defined(__SUNPRO_CC) || defined(__IBMCPP__)
+#warning "boost/functional/detail/container_fwd.hpp is deprecated, use boost/detail/container_fwd.hpp instead."
+#endif
+
 #include <boost/detail/container_fwd.hpp>
 
 #endif

test/Jamfile.v2

@@ -50,6 +50,7 @@ test-suite functional/hash
         [ compile-fail implicit_fail_test.cpp : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
         [ run hash_no_ext_macro_1.cpp : : : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
         [ run hash_no_ext_macro_2.cpp : : : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
+        [ compile deprecated_container_fwd.cpp ]
     ;
 
 test-suite functional/hash_implicit_casts

test/deprecated_container_fwd.cpp

@@ -0,0 +1,14 @@
+
+// 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 <boost/functional/detail/container_fwd.hpp>
+
+typedef std::vector<int, std::allocator<int> > int_vector;
+
+#include <vector>
+
+int main() {
+    int_vector x;
+}