Merge unordered+hash documentation updates.

[SVN r75015]

doc/Jamfile.v2

@@ -3,6 +3,9 @@
 # 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)
 
+using boostbook ;
+using quickbook ;
+
 xml hash : hash.qbk ;
 boostbook standalone : hash :
     <xsl:param>boost.root=../../../..

doc/changes.qbk

@@ -119,4 +119,8 @@
   it's opt-in for now. This, or something like it, will become the
   default in a future version.
 
+[h2 Boost 1.46.0]
+
+* Avoid warning due with gcc's `-Wconversion` flag.
+
 [endsect]

doc/hash.qbk

@@ -14,11 +14,16 @@
     ]
 ]
 
+[def __issues__
+    [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1837.pdf
+    Library Extension Technical Report Issues List]]
+
 [include:hash intro.qbk]
 [include:hash tutorial.qbk]
 [include:hash portability.qbk]
 [include:hash disable.qbk]
 [include:hash changes.qbk]
+[include:hash rationale.qbk]
 [xinclude ref.xml]
 [include:hash links.qbk]
 [include:hash thanks.qbk]

doc/intro.qbk

@@ -18,9 +18,6 @@
 [def __multi-index-short__ [@boost:/libs/multi_index/doc/index.html
     Boost.MultiIndex]]
 [def __bimap__ [@boost:/libs/bimap/index.html Boost.Bimap]]
-[def __issues__
-    [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1837.pdf
-    Library Extension Technical Report Issues List]]
 [def __hash-function__ [@http://en.wikipedia.org/wiki/Hash_function hash function]]
 [def __hash-table__ [@http://en.wikipedia.org/wiki/Hash_table hash table]]
 
@@ -44,5 +41,12 @@ __issues__ (page 63), this adds support for:
 * the standard containers.
 * extending [classref boost::hash] for custom types.
 
+[note
+This hash function is designed to be used in containers based on
+the STL and is not suitable as a general purpose hash function.
+For more details see the [link hash.rationale rationale].
+]
+
+
 [endsect]
 

doc/portability.qbk

@@ -90,16 +90,4 @@ boost namespace:
 Full code for this example is at
 [@boost:/libs/functional/hash/examples/portable.cpp /libs/functional/hash/examples/portable.cpp].
 
-[h2 Other Issues]
-
-On Visual C++ versions 6.5 and 7.0, `hash_value` isn't overloaded for built in
-arrays. __boost_hash__, [funcref boost::hash_combine] and [funcref boost::hash_range] all use a workaround to
-support built in arrays so this shouldn't be a problem in most cases.
-
-On Visual C++ versions 6.5 and 7.0, function pointers aren't currently supported.
-
-When using GCC on Solaris, `boost::hash_value(long double)` treats
-`long double`s as `double`s - so the hash function doesn't take into account the
-full range of values.
-
 [endsect]

doc/rationale.qbk

@@ -0,0 +1,50 @@
+
+[/ Copyright 2011 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) ]
+
+[section:rationale Rationale]
+
+The rationale for the design can be found in the original design
+[footnote issue 6.18 of the __issues__ (page 63)], but an issue that
+occasionally comes up is the quality of the hash function, so that
+demands some more attention.
+
+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
+preform poorly.
+
+So why not implement a higher quality hash function? Well, the standard
+makes no such guarantee, 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.
+
+For other use cases, if you do need a higher quality hash function,
+there are several options
+available. One is to use a second hash on the output of this hash
+function, such as [@http://www.concentric.net/~ttwang/tech/inthash.htm
+Thomas Wang's hash function]. This this may not work as
+well as a hash algorithm tailored for the input.
+
+For strings that are several fast, high quality hash functions
+available (for example [@http://code.google.com/p/smhasher/ MurmurHash3]
+and [@http://code.google.com/p/cityhash/ Google's CityHash]),
+although they tend to be more machine specific.
+These may also be appropriate for hashing a binary representation of
+your data - providing that all equal values have an equal
+representation, which is not always the case (e.g. for floating point
+values).
+
+[endsect]

doc/ref.xml

@@ -406,6 +406,29 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
         </method>
       </struct-specialization>
 
+      <struct-specialization name="hash">
+        <template></template>
+        <specialization>
+          <template-arg>std::type_index</template-arg>
+        </specialization>
+        <method name="operator()" cv="const">
+          <type>std::size_t</type>
+          <parameter name="val">
+            <paramtype>std::type_index</paramtype>
+          </parameter>
+          <returns>
+            <para><code>val.hash_code()</code></para>
+          </returns>
+          <throws><para>Doesn't throw</para></throws>
+        </method>
+        <notes>
+          <para>
+            Only available if it's in your standard library and Boost.Config
+            is aware of it.
+          </para>
+        </notes>
+      </struct-specialization>
+
       <free-function-group name="Support functions (Boost extension)."> 
 
       <!--
@@ -716,6 +739,11 @@ for(; first != last; ++first)
           <parameter name="val"><paramtype>std::complex&lt;T&gt; const&amp;</paramtype></parameter>
         </signature>
 
+        <signature>
+          <type>std::size_t</type>
+          <parameter name="val"><paramtype>std::type_index</paramtype></parameter>
+        </signature>
+
         <description><para>
           Generally shouldn't be called directly by users, instead they should use
           <classname>boost::hash</classname>, <functionname>boost::hash_range</functionname>
@@ -798,6 +826,12 @@ return seed;</programlisting></entry>
                   </entry>
                   <entry>When <code>T</code> is a built in type and <code>val.imag() == 0</code>, the result is equal to <code>hash_value(val.real())</code>. Otherwise an unspecified value, except that equal arguments shall yield the same result.</entry>
                 </row>
+                <row>
+                  <entry>
+                    <code>std::type_index</code>
+                  </entry>
+                  <entry><code>val.hash_code()</code></entry>
+                </row>
               </tbody>
             </tgroup>
           </informaltable>

include/boost/functional/hash/detail/hash_float_generic.hpp

@@ -53,7 +53,7 @@ namespace boost
 
             v = ldexp(v, limits<std::size_t>::digits);
             std::size_t seed = static_cast<std::size_t>(v);
-            v -= seed;
+            v -= static_cast<T>(seed);
 
             // ceiling(digits(T) * log2(radix(T))/ digits(size_t)) - 1;
             std::size_t const length
@@ -66,7 +66,7 @@ namespace boost
             {
                 v = ldexp(v, limits<std::size_t>::digits);
                 std::size_t part = static_cast<std::size_t>(v);
-                v -= part;
+                v -= static_cast<T>(part);
                 hash_float_combine(seed, part);
             }
 

include/boost/functional/hash/hash.hpp

@@ -24,6 +24,10 @@
 #include <boost/type_traits/is_pointer.hpp>
 #endif
 
+#if !defined(BOOST_NO_0X_HDR_TYPEINDEX)
+#include <typeindex>
+#endif
+
 #if BOOST_WORKAROUND(__GNUC__, < 3) \
     && !defined(__SGI_STL_PORT) && !defined(_STLPORT_VERSION)
 #define BOOST_HASH_CHAR_TRAITS string_char_traits
@@ -87,6 +91,10 @@ namespace boost
     std::size_t hash_value(
         std::basic_string<Ch, std::BOOST_HASH_CHAR_TRAITS<Ch>, A> const&);
 
+#if !defined(BOOST_NO_0X_HDR_TYPEINDEX)
+    std::size_t hash_value(std::type_index);
+#endif
+
     // Implementation
 
     namespace hash_detail
@@ -209,9 +217,15 @@ namespace boost
     template <class T> std::size_t hash_value(T* v)
 #endif
     {
+#if defined(__VMS) && __INITIAL_POINTER_SIZE == 64
+    // for some reason ptrdiff_t on OpenVMS compiler with
+    // 64 bit is not 64 bit !!!
+        std::size_t x = static_cast<std::size_t>(
+           reinterpret_cast<long long int>(v));
+#else
         std::size_t x = static_cast<std::size_t>(
            reinterpret_cast<std::ptrdiff_t>(v));
-
+#endif
         return x + (x >> 3);
     }
 
@@ -325,6 +339,13 @@ namespace boost
         return boost::hash_detail::float_hash_value(v);
     }
 
+#if !defined(BOOST_NO_0X_HDR_TYPEINDEX)
+    inline std::size_t hash_value(std::type_index v)
+    {
+        return v.hash_code();
+    }
+#endif
+
     //
     // boost::hash
     //
@@ -429,6 +450,10 @@ namespace boost
     BOOST_HASH_SPECIALIZE(boost::ulong_long_type)
 #endif
 
+#if !defined(BOOST_NO_0X_HDR_TYPEINDEX)
+    BOOST_HASH_SPECIALIZE(std::type_index)
+#endif
+
 #undef BOOST_HASH_SPECIALIZE
 #undef BOOST_HASH_SPECIALIZE_REF
 

test/Jamfile.v2

@@ -1,5 +1,5 @@
 
-# Copyright 2005-2008 Daniel James.
+# Copyright 2005-2011 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)
 
@@ -7,12 +7,11 @@ import testing ;
 
 project hash-tests
     : requirements
-        <define>BOOST_HASH_NO_IMPLICIT_CASTS
         <warnings>all
         <toolset>intel:<warnings>on
         <toolset>intel:<cxxflags>-strict-ansi
-        <toolset>gcc:<cxxflags>"-pedantic -Wstrict-aliasing -fstrict-aliasing -Wextra -Wsign-promo -Wunused-parameter"
-        <toolset>darwin:<cxxflags>"-pedantic -Wstrict-aliasing -fstrict-aliasing -Wextra -Wsign-promo -Wunused-parameter"
+        <toolset>gcc:<cxxflags>"-pedantic -Wstrict-aliasing -fstrict-aliasing -Wextra -Wsign-promo -Wunused-parameter -Wconversion"
+        <toolset>darwin:<cxxflags>"-pedantic -Wstrict-aliasing -fstrict-aliasing -Wextra -Wsign-promo -Wunused-parameter -Wconversion"
         <toolset>msvc:<warnings-as-errors>on
         #<toolset>gcc:<warnings-as-errors>on
         #<toolset>darwin:<warnings-as-errors>on
@@ -20,41 +19,49 @@ project hash-tests
 
 test-suite functional/hash
     :
-        [ run hash_fwd_test_1.cpp ]
-        [ run hash_fwd_test_2.cpp ]
-        [ run hash_number_test.cpp ]
-        [ run hash_pointer_test.cpp ]
-        [ run hash_function_pointer_test.cpp ]
-        [ run hash_float_test.cpp : : : <test-info>always_show_run_output ]
-        [ run hash_long_double_test.cpp : : : <test-info>always_show_run_output ]
-        [ run hash_string_test.cpp ]
-        [ run hash_range_test.cpp ]
-        [ run hash_custom_test.cpp ]
-        [ run hash_global_namespace_test.cpp ]
-        [ run hash_friend_test.cpp ]
-        [ run hash_built_in_array_test.cpp ]
-        [ run hash_value_array_test.cpp ]
-        [ run hash_vector_test.cpp ]
-        [ run hash_list_test.cpp ]
-        [ run hash_deque_test.cpp ]
-        [ run hash_set_test.cpp ]
-        [ run hash_map_test.cpp ]
-        [ run hash_complex_test.cpp ]
-        [ run link_test.cpp link_test_2.cpp ]
-        [ run link_ext_test.cpp link_no_ext_test.cpp ]
-        [ run extensions_hpp_test.cpp ]
-        [ run container_fwd_test.cpp ]
-        [ run container_fwd_test.cpp : :
-            :   <toolset>gcc:<define>_GLIBCXX_DEBUG
-                <toolset>darwin:<define>_GLIBCXX_DEBUG
-            :   container_fwd_gcc_debug ]
-        [ run container_no_fwd_test.cpp ]
-        [ compile-fail hash_no_ext_fail_test.cpp ]
-        [ compile-fail namespace_fail_test.cpp ]
-        [ compile-fail implicit_fail_test.cpp ]
-        [ compile-fail shared_ptr_fail_test.cpp ]
-        [ run hash_no_ext_macro_1.cpp ]
-        [ run hash_no_ext_macro_2.cpp ]
+        [ run hash_fwd_test_1.cpp : : : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
+        [ run hash_fwd_test_2.cpp : : : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
+        [ run hash_number_test.cpp : : : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
+        [ run hash_pointer_test.cpp : : : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
+        [ run hash_function_pointer_test.cpp : : : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
+        [ run hash_float_test.cpp : : : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
+        [ run hash_long_double_test.cpp : : : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
+        [ run hash_string_test.cpp : : : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
+        [ run hash_range_test.cpp : : : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
+        [ run hash_custom_test.cpp : : : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
+        [ run hash_global_namespace_test.cpp : : : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
+        [ run hash_friend_test.cpp : : : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
+        [ run hash_built_in_array_test.cpp : : : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
+        [ run hash_value_array_test.cpp : : : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
+        [ run hash_vector_test.cpp : : : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
+        [ run hash_list_test.cpp : : : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
+        [ run hash_deque_test.cpp : : : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
+        [ run hash_set_test.cpp : : : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
+        [ run hash_map_test.cpp : : : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
+        [ run hash_complex_test.cpp : : : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
+        [ run hash_type_index_test.cpp : : : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
+        [ run link_test.cpp link_test_2.cpp : : : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
+        [ run link_ext_test.cpp link_no_ext_test.cpp : : : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
+        [ run extensions_hpp_test.cpp : : : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
+        [ compile-fail hash_no_ext_fail_test.cpp : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
+        [ compile-fail namespace_fail_test.cpp : <define>BOOST_HASH_NO_IMPLICIT_CASTS ]
+        [ 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 ]
+    ;
+
+test-suite functional/hash_implicit_casts
+    :
+        [ run hash_number_test.cpp : : : : implicit_number ]
+        [ run hash_pointer_test.cpp : : : : implicit_pointer ]
+        [ run hash_function_pointer_test.cpp : : : : implicit_function_pointer ]
+        [ run hash_float_test.cpp : : : : implicit_float ]
+        [ run hash_string_test.cpp : : : : implicit_string ]
+        [ run hash_range_test.cpp : : : : implicit_range ]
+        [ run hash_custom_test.cpp : : : : implicit_custom ]
+        [ run hash_built_in_array_test.cpp : : : : implicit_built_in_array ]
+        [ run link_test.cpp link_test_2.cpp : : : : implicit_link ]
+        [ run implicit_fail_test.cpp : : : : implicit_test ]
     ;
 
 test-suite functional/hash_no_ext

test/container_fwd_test.cpp

@@ -1,114 +0,0 @@
-
-// Copyright 2005-2009 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 "./config.hpp"
-
-#include <boost/functional/detail/container_fwd.hpp>
-
-#if BOOST_WORKAROUND(__GNUC__, < 3) && \
-    !defined(__SGI_STL_PORT) && !defined(_STLPORT_VERSION)
-template <class charT, class Allocator>
-static void test(
-    std::basic_string<charT, std::string_char_traits<charT>, Allocator> const&)
-{
-}
-#else
-template <class charT, class Allocator>
-static void test(
-    std::basic_string<charT, std::char_traits<charT>, Allocator> const&)
-{
-}
-#endif
-    
-template <class T, class Allocator>
-static void test(std::deque<T, Allocator> const&)
-{
-}
-
-template <class T, class Allocator>
-static void test(std::list<T, Allocator> const&)
-{
-}
-
-template <class T, class Allocator>
-static void test(std::vector<T, Allocator> const&)
-{
-}
-
-template <class Key, class T, class Compare, class Allocator>
-static void test(std::map<Key, T, Compare, Allocator> const&)
-{
-}
-
-template <class Key, class T, class Compare, class Allocator>
-static void test(std::multimap<Key, T, Compare, Allocator> const&)
-{
-}
-
-template <class Key, class Compare, class Allocator>
-static void test(std::set<Key, Compare, Allocator> const&)
-{
-}
-
-template <class Key, class Compare, class Allocator>
-static void test(std::multiset<Key, Compare, Allocator> const&)
-{
-}
-
-template <std::size_t N>
-static void test(std::bitset<N> const&)
-{
-}
-
-template <class T>
-static void test(std::complex<T> const&)
-{
-}
-
-template <class X, class Y>
-static void test(std::pair<X, Y> const&)
-{
-}
-
-#include <deque>
-#include <list>
-#include <vector>
-#include <map>
-#include <set>
-#include <bitset>
-#include <string>
-#include <complex>
-#include <utility>
-
-int main()
-{
-    std::deque<int> x1;
-    std::list<std::string> x2;
-    std::vector<float> x3;
-    std::vector<bool> x4;
-    std::map<int, int> x5;
-    std::multimap<float, int*> x6;
-    std::set<std::string> x7;
-    std::multiset<std::vector<int> > x8;
-    std::bitset<10> x9;
-    std::string x10;
-    std::complex<double> x11;
-    std::pair<std::list<int>, char***> x12;
-
-    test(x1);
-    test(x2);
-    test(x3);
-    test(x4);
-    test(x5);
-    test(x6);
-    test(x7);
-    test(x8);
-    test(x9);
-    test(x10);
-    test(x11);
-    test(x12);
-
-    return 0;
-}

test/container_no_fwd_test.cpp

@@ -1,14 +0,0 @@
-
-// Copyright 2010 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)
-
-#define BOOST_DETAIL_NO_CONTAINER_FWD
-
-#include <boost/detail/container_fwd.hpp>
-
-int main()
-{
-    std::set<int> x;
-    std::vector<std::string> y;
-}

test/hash_complex_test.cpp

@@ -69,7 +69,7 @@ void complex_float_tests(Float*)
     generic_complex_tests(complex(0.5,0));
     generic_complex_tests(complex(25,0));
     generic_complex_tests(complex(25,0));
-    generic_complex_tests(complex(-67.5324535,56.23578678));
+    generic_complex_tests(complex(static_cast<Float>(-67.5324535),static_cast<Float>(56.23578678)));
 }
 
 template <class Integer>

test/hash_number_test.cpp

@@ -113,7 +113,8 @@ void poor_quality_tests(T*)
     if(T(1) != T(2))
         BOOST_TEST(x1(T(1)) !=  x2(T(2)));
     if((limits::max)() != (limits::max)() - 1)
-        BOOST_TEST(x1((limits::max)()) != x2((limits::max)() - 1));
+        BOOST_TEST(x1(static_cast<T>((limits::max)()))
+            != x2(static_cast<T>((limits::max)() - 1)));
 }
 
 void bool_test()

test/hash_type_index_test.cpp

@@ -0,0 +1,48 @@
+
+// Copyright 2011 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 "./config.hpp"
+
+#ifdef TEST_STD_INCLUDES
+#  include <functional>
+#else
+#  include <boost/functional/hash.hpp>
+#endif
+#include <boost/config.hpp>
+#include <boost/detail/lightweight_test.hpp>
+
+#if !defined(BOOST_NO_0X_HDR_TYPEINDEX)
+
+#include <typeindex>
+
+void test_type_index() {
+    std::type_index int_index = typeid(int);
+    std::type_index int2_index = typeid(int);
+    std::type_index char_index = typeid(char);
+    
+    HASH_NAMESPACE::hash<std::type_index> hasher;
+    
+    BOOST_TEST(hasher(int_index) == int_index.hash_code());
+    BOOST_TEST(hasher(int_index) == int2_index.hash_code());
+    BOOST_TEST(hasher(char_index) == char_index.hash_code());
+    BOOST_TEST(HASH_NAMESPACE::hash_value(int_index) == int_index.hash_code());
+    BOOST_TEST(HASH_NAMESPACE::hash_value(int_index) == int2_index.hash_code());
+    BOOST_TEST(HASH_NAMESPACE::hash_value(char_index) == char_index.hash_code());
+
+    BOOST_TEST(hasher(int_index) == hasher(int2_index));
+    BOOST_TEST(hasher(int_index) != hasher(char_index));
+}
+#endif
+
+int main()
+{
+#if !defined(BOOST_NO_0X_HDR_TYPEINDEX)
+    test_type_index();
+#else
+    std::cout<<"<type_index> not available."<<std::endl;
+#endif
+
+    return boost::report_errors();
+}

test/shared_ptr_fail_test.cpp

@@ -1,16 +0,0 @@
-
-// Copyright 2010 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/hash.hpp>
-#include <boost/shared_ptr.hpp>
-
-// This should obviously pass if shared_ptr ever supports Boost.Hash.
-
-int main() {
-    boost::hash<boost::shared_ptr<int> > hash;
-    boost::shared_ptr<int> x(new int(10));
-    
-    hash(x);
-}