Merge unordered+hash documentation updates.

[SVN r75015]

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]

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,7 +7,6 @@ import testing ;
 
 project hash-tests
     : requirements
-        <define>BOOST_HASH_NO_IMPLICIT_CASTS
         <warnings>all
         <toolset>intel:<warnings>on
         <toolset>intel:<cxxflags>-strict-ansi
@@ -20,42 +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 ]
-        [ run hash_long_double_test.cpp ]
-        [ 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 hash_type_index_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/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);
-}