From c1214408409fb41c5f50fb053a4572a561e9bb94 Mon Sep 17 00:00:00 2001 From: Daniel James Date: Wed, 20 Apr 2005 15:16:29 +0000 Subject: [PATCH] Various changes to the hash documentation including: - Updated for splitting the books example into books.hpp & books.cpp - Added the array overloads of hash_value, and the new signature for pointers. - Split up the overloads of hash_value in boost/hash/hash.hpp. [SVN r28341] --- hash/doc/hash.qbk | 352 ++++++++++++++++++++++++++++++---------------- 1 file changed, 233 insertions(+), 119 deletions(-) diff --git a/hash/doc/hash.qbk b/hash/doc/hash.qbk index bc5e9a9..9229282 100644 --- a/hash/doc/hash.qbk +++ b/hash/doc/hash.qbk @@ -47,24 +47,23 @@ As it is compliant with the __tr1-short__, it will work with: It also implements the extension proposed by Peter Dimov in issue 6.18 of the __issues__, this adds support for: +* arrays * `std::pair` * the standard containers. - -The extension also allows the user to customise the hash function for -user-defined types. Which means that you don't need to use a custom hash -function object with a container that uses [classref boost::hash] by default. +* extending [classref boost::hash] for custom types. [endsect] [section:tutorial Tutorial] -When using __multi-index-short__, you don't need to do anything, as it uses -[classref boost::hash] by default. To find out how to use a user-defined type, -read the [link section.tutorial.custom section on Extending Boost.Hash]. +When using a hash index with __multi-index-short__, you don't need to do +anything to use [classref boost::hash] as it uses it by default. +To find out how to use a user-defined type, read the +[link boost_hash.custom section on extending Boost.Hash]. If your standard library supplies its own implementation of the unordered associative containers and you wish to use -[classref boost::hash] you just supply the extra template parameter: +[classref boost::hash], just use an extra template parameter: std::unordered_multiset, boost::hash > set_of_ints; @@ -113,6 +112,8 @@ containing the hashes of the elements of a container: return hashes; } +[endsect] + [section:custom Extending Boost.Hash for a custom data type] [classref boost::hash] is implemented by calling the function @@ -147,7 +148,8 @@ Then all you would need to do is write the function `library::hash_value`: { std::size_t hash_value(book const& b) { - return boost::hash_value(b.id); + boost::hash hasher; + return hasher(b.id); } } @@ -160,7 +162,8 @@ And you can now use [classref boost::hash] with book: boost::hash book_hasher; std::size_t knife_hash_value = book_hasher(knife); - boost::unordered_set books; + // If std::unordered_set is available: + std::unordered_set > books; books.insert(knife); books.insert(library::book(2443, "Lindgren, Torgny", "Hash")); books.insert(library::book(1953, "Snyder, Bernadette M.", @@ -169,9 +172,10 @@ And you can now use [classref boost::hash] with book: assert(books.find(knife) != books.end()); assert(books.find(dandelion) == books.end()); -Full code for this example is at +The full example can be found in: +[@../../libs/functional/hash/examples/books.cpp /libs/functional/hash/examples/books.hpp] +and [@../../libs/functional/hash/examples/books.cpp /libs/functional/hash/examples/books.cpp]. - [blurb When writing a hash function, first look at how the equality function works. Objects that are equal must generate the same hash value. @@ -260,8 +264,6 @@ To calculate the hash of an iterator range you can use [endsect] -[endsect] - [section:portability Portability] Boost.Hash is written to be as portable as possible, but unfortunately, several @@ -378,7 +380,7 @@ but there you go. ] The call to hash_value - is always unqualified, so that custom overloads can be + is unqualified, so that custom overloads can be found via argument dependent lookup. @@ -388,108 +390,6 @@ but there you go. ] - - - - - - Implementation of a hash function for various types. - - - - Should never 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. - - - Overloads for other types supplied in other headers. - This is an extension to TR1 - - - - std::size_t - int - - - - std::size_t - unsigned int - - - - std::size_t - long - - - - std::size_t - unsigned long - - - - std::size_t - float - - - - std::size_t - double - - - - std::size_t - long double - - - - - std::size_t - T* - - - - - std::size_t - - std::basic_string<Ch, std::char_traits<Ch>, A> const& - - - - - - - - - - int, unsigned int, long, unsigned long - v - - - float, double, long double, T* - - An unspecified value, except that equal arguments shall yield the same - result - - - - std::basic_string<Ch, std::char_traits<Ch>, A> const& - hash_range(v.begin(), v.end()); - - - - - - - - - @@ -546,7 +446,9 @@ but there you go. ] Calculate the combined hash value of the elements of an iterator range. - + + For the two argument overload: + size_t seed = 0; for(; first != last; ++first) @@ -555,7 +457,17 @@ for(; first != last; ++first) } return seed; - + + For the three arguments overload: + +for(; first != last; ++first) +{ + hash_combine(seed, *first); +} + + + + hash_range is sensitive to the order of the elements @@ -571,6 +483,208 @@ return seed; has basic exception safety. + + + + + + Implementation of a hash function for integers. + + + + 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. + + + Overloads for other types supplied in other headers. + This is an extension to TR1 + + + + std::size_t + int + + + + std::size_t + unsigned int + + + + std::size_t + long + + + + std::size_t + unsigned long + + + + val + + + + + + + + Implementation of a hash function for floating point values. + + + + 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. + + + Overloads for other types supplied in other headers. + This is an extension to TR1 + + + + std::size_t + float + + + + std::size_t + double + + + + std::size_t + long double + + + + + An unspecified value, except that equal arguments shall yield the same + result + + + + + + + + + Implementation of a hash function for pointers. + + + + 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. + + + Overloads for other types supplied in other headers. + This is an extension to TR1 + + + + + std::size_t + T* const& + + + + + An unspecified value, except that equal arguments shall yield the same + result + + + + + + + + + Implementation of a hash function for built in arrays. + + + + 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. + + + Overloads for other types supplied in other headers. + This is an extension to TR1 + + + + + std::size_t + T (&val)[N] + + + + + std::size_t + const T (&val)[N] + + + hash_range(val, val+N) + + + + + + + Implementation of a hash function for std::basic_string. + + + + 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. + + + Overloads for other types supplied in other headers. + This is an extension to TR1 + + + + + std::size_t + + std::basic_string<Ch, std::char_traits<Ch>, A> const& + + + + hash_range(val.begin(), val.end()) +