diff --git a/doc/changes.qbk b/doc/changes.qbk deleted file mode 100644 index 459a15d..0000000 --- a/doc/changes.qbk +++ /dev/null @@ -1,222 +0,0 @@ - -[/ Copyright 2005-2008 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) ] - -[template ticket[number]''''''#[number]''''''] - -[section:changes Change Log] - -[h2 Boost 1.33.0] - -* Initial Release - -[h2 Boost 1.33.1] - -* Fixed the points example, as pointed out by 沈慧峰. - -[h2 Boost 1.34.0] - -* Use declarations for standard classes, so that the library - doesn't need to include all of their headers -* Deprecated the `` headers. Now a single header, - <[headerref boost/functional/hash.hpp]> is used. -* Add support for the `BOOST_HASH_NO_EXTENSIONS` macro, which - disables the extensions to TR1. - -* Minor improvements to the hash functions for floating point numbers. -* Update the portable example to hopefully be more generally portable. - -[h2 Boost 1.34.1] - -* [@http://svn.boost.org/trac/boost/ticket/952 Ticket 952]: - Suppress incorrect 64-bit warning on Visual C++. - -[h2 Boost 1.35.0] - -* Support for `long long`, `std::complex`. -* Improved algorithm for hashing floating point numbers: - * Improved portablity, as described by Daniel Krügler in - [@http://lists.boost.org/boost-users/2005/08/13418.php - a post to the boost users list]. - * Fits more information into each combine loop, which can reduce the - the number of times combine is called and hopefully give a better - quality hash function. - * Improved the algorithm for hashing floating point numbers. - * On Cygwin use a binary hash function for floating point numbers, as - Cygwin doesn't have decent floating point functions for `long double`. - * Never uses `fpclass` which doesn't support `long double`. - * [@http://svn.boost.org/trac/boost/ticket/1064 Ticket 1064]: - Removed unnecessary use of `errno`. -* Explicitly overload for more built in types. -* Minor improvements to the documentation. -* A few bug and warning fixes: - * [@http://svn.boost.org/trac/boost/ticket/1509 Ticket 1509]: - Suppress another Visual C++ warning. - * Some workarounds for the Sun compilers. - -[h2 Boost 1.36.0] - -* Stop using OpenBSD's dodgy `std::numeric_limits`. -* Using the boost typedefs for `long long` and `unsigned long long`. -* Move the extensions into their own header. - -[h2 Boost 1.37.0] - -* [@http://svn.boost.org/trac/boost/ticket/2264 Ticket 2264]: - In Visual C++, always use C99 float functions for `long double` and `float` as - the C++ overloads aren't always availables. - -[h2 Boost 1.38.0] - -* Changed the warnings in the deprecated headers from 1.34.0 to errors. These - will be removed in a future version of Boost. -* Moved detail headers out of `boost/container_hash/detail`, since they are part of - functional/hash, not container_hash. `boost/container_hash/detail/container_fwd.hpp` - has been moved to `boost/detail/container_fwd.hpp` as it's used outside of - this library, the others have been moved to `boost/functional/hash/detail`. - -[h2 Boost 1.39.0] - -* Move the hash_fwd.hpp implementation into the hash subdirectory, leaving a - forwarding header in the old location. You should still use the old location, - the new location is mainly for implementation and possible modularization. -* [@https://svn.boost.org/trac/boost/ticket/2412 Ticket 2412]: Removed deprecated - headers. -* [@https://svn.boost.org/trac/boost/ticket/2957 Ticket 2957]: Fix configuration - for vxworks. - -[h2 Boost 1.40.0] - -* Automatically configure the float functions using template metaprogramming - instead of trying to configure every possibility manually. -* Workaround for when STLport doesn't support long double. - -[h2 Boost 1.42.0] - -* Reduce the number of warnings for Visual C++ warning level 4. -* Some code formatting changes to fit lines into 80 characters. -* Rename an internal namespace. - -[h2 Boost 1.43.0] - -* [@https://svn.boost.org/trac/boost/ticket/3866 Ticket 3866]: - Don't foward declare containers when using gcc's parallel library, - allow user to stop forward declaration by defining the - `BOOST_DETAIL_NO_CONTAINER_FWD` macro. -* [@https://svn.boost.org/trac/boost/ticket/4038 Ticket 4038]: - Avoid hashing 0.5 and 0 to the same number. -* Stop using deprecated `BOOST_HAS_*` macros. - -[h2 Boost 1.44.0] - -* Add option to prevent implicit conversions when calling `hash_value` by - defining `BOOST_HASH_NO_IMPLICIT_CASTS`. When using `boost::hash` - for a type that does not have `hash_value` declared but does have - an implicit conversion to a type that does, it would use that - implicit conversion to hash it. Which can sometimes go very wrong, - e.g. using a conversion to bool and only hashing to 2 possible - values. Since fixing this is a breaking change and was only - approached quite late in the release cycle with little discussion - 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. - -[h2 Boost 1.50.0] - -* [@http://svn.boost.org/trac/boost/ticket/6771 Ticket 6771]: - 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/container_hash/detail/container_fwd.hpp`. - -[h2 Boost 1.51.0] - -* Support the standard smart pointers. -* `hash_value` now implemented using SFINAE to avoid implicit casts to built - in types when calling it. -* Updated to use the new config macros. - -[h2 Boost 1.52.0] - -* Restore `enum` support, which was accidentally removed in the last version. -* New floating point hasher - will hash the binary representation on more - platforms, which should be faster. - -[h2 Boost 1.53.0] - -* Add support for `boost::int128_type` and `boost::uint128_type` where - available - currently only `__int128` and `unsigned __int128` on some - versions of gcc. -* On platforms that are known to have the standard floating point functions, - don't use automatic detection - which can break if there are ambiguous - overloads. -* Fix undefined behaviour when using the binary float hash (Thomas Heller). - -[h2 Boost 1.54.0] - -* [@https://svn.boost.org/trac/boost/ticket/7957 Ticket 7957]: - Fixed a typo. - -[h2 Boost 1.55.0] - -* Simplify a SFINAE check so that it will hopefully work on Sun 5.9 - ([ticket 8822]). -* Suppress Visual C++ infinite loop warning ([ticket 8568]). - -[h2 Boost 1.56.0] - -* Removed some Visual C++ 6 workarounds. -* Ongoing work on improving `hash_combine`. This changes the combine function - which was previously defined in the reference documentation. - -[h2 Boost 1.58.0] - -* Fixed strict aliasing violation - ([@https://github.com/boostorg/container_hash/pull/3 GitHub #3]). - -[h2 Boost 1.63.0] - -* Fixed some warnings. -* Only define hash for `std::wstring` when we know we have a `wchar_t`. - Otherwise there's a compile error as there's no overload for hashing - the characters in wide strings ([ticket 8552]). - -[h2 Boost 1.64.0] - -* Fix for recent versions of Visual C++ which have removed `std::unary_function` - and `std::binary_function` ([ticket 12353]). - -[h2 Boost 1.65.0] - -* Support for `char16_t`, `char32_t`, `u16string`, `u32string` - -[h2 Boost 1.66.0] - -* Avoid float comparison warning when using Clang - this workaround was - already in place for GCC, and was used when Clang pretends to be GCC, - but the warning was appearing when running Clang in other contexts. - -[h2 Boost 1.67.0] - -* Moved library into its own module, `container_hash`. -* Moved headers for new module name, now at: - ``, - ``, - ``. -* Added forwarding headers to support the old headers locations. -* Support `std::string_view`, `std::error_code`, `std::error_condition` - `std::optional`, `std::variant`, `std::monostate` where available. -* Update include paths from other Boost libraries. -* Manually write out tuple overloads, rather than using the - preprocessor to generate them. Should improve usability, due - to better error messages, and easier debugging. -* Fix tutorial example ([ticket 11017]). -* Quick fix for hashing `vector` when using libc++. Will try to introduce - a more general fix in the next release. - -[endsect] diff --git a/doc/disable.qbk b/doc/disable.qbk deleted file mode 100644 index 5373b42..0000000 --- a/doc/disable.qbk +++ /dev/null @@ -1,29 +0,0 @@ - -[/ Copyright 2005-2008 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:disable Disabling The Extensions] - -While [classref boost::hash]'s extensions are generally useful, you might want -to turn them of in order to check that your code will work with other -implementations of TR1. To do this define the macro `BOOST_HASH_NO_EXTENSIONS`. -When this macro is defined, only the specialisations detailed -in TR1 will be declared. But, if you later undefine the macro and include -<[headerref boost/container_hash/hash.hpp]> then the non-specialised form will be defined -- activating the extensions. - -It is strongly recommended that you never undefine the macro - and only define -it so that it applies to the complete translation unit, either by defining it -at the beginning of the main source file or, preferably, by using a compiler -switch or preference. And you really should never define it in header files. - -If you are writing a library which has code in the header which requires the -extensions, then the best action is to tell users not to define the macro. -Their code won't ['require] the macro. - -Translation units that are compiled with the macro defined will link with units -that were compiled without it. This feature has been designed to avoid ODR -violations. - -[endsect] diff --git a/doc/hash.qbk b/doc/hash.qbk deleted file mode 100644 index 3bcc80e..0000000 --- a/doc/hash.qbk +++ /dev/null @@ -1,29 +0,0 @@ -[library Boost.ContainerHash - [quickbook 1.5] - [authors [James, Daniel]] - [copyright 2005 2006 2007 2008 Daniel James] - [purpose A TR1 hash function object that can be extended to hash user - defined types] - [category higher-order] - [id hash] - [dirname container_hash] - [license - 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]) - ] -] - -[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] diff --git a/doc/intro.qbk b/doc/intro.qbk deleted file mode 100644 index 076e997..0000000 --- a/doc/intro.qbk +++ /dev/null @@ -1,52 +0,0 @@ - -[/ Copyright 2005-2008 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:intro Introduction] - -[def __tr1-full__ - [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf - Draft Technical Report on C++ Library Extensions]] -[def __tr1__ - [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf - TR1]] -[def __unordered__ [link unordered Boost.Unordered]] -[def __intrusive__ [link intrusive.unordered_set_unordered_multiset Boost.Intrusive]] -[def __multi-index__ [@boost:/libs/multi_index/doc/index.html - Boost Multi-Index Containers Library]] -[def __multi-index-short__ [@boost:/libs/multi_index/doc/index.html - Boost.MultiIndex]] -[def __bimap__ [@boost:/libs/bimap/index.html Boost.Bimap]] -[def __hash-function__ [@http://en.wikipedia.org/wiki/Hash_function hash function]] -[def __hash-table__ [@http://en.wikipedia.org/wiki/Hash_table hash table]] - -[classref boost::hash] is an implementation of the __hash-function__ object -specified by the __tr1-full__ (TR1). It is the default hash function for -__unordered__, __intrusive__'s unordered associative containers, and -__multi-index-short__'s hash indicies and __bimap__'s `unordered_set_of`. - -As it is compliant with __tr1__, it will work with: - -* integers -* floats -* pointers -* strings - -It also implements the extension proposed by Peter Dimov in issue 6.18 of the -__issues__ (page 63), this adds support for: - -* arrays -* `std::pair` -* 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] - diff --git a/doc/links.qbk b/doc/links.qbk deleted file mode 100644 index 405536e..0000000 --- a/doc/links.qbk +++ /dev/null @@ -1,27 +0,0 @@ - -[/ Copyright 2005-2008 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:links Links] - -[*A Proposal to Add Hash Tables to the Standard Library] -[@http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2003/n1456.html] -The hash table proposal explains much of the design. The hash function object -is discussed in Section D. - -[*The C++ Standard Library Technical Report.] -[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf] -Contains the hash function specification in section 6.3.2. - -[*Library Extension Technical Report Issues List.] -[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1837.pdf] -The library implements the extension described in Issue 6.18, pages 63-67. - -[*Methods for Identifying Versioned and Plagiarised Documents] -Timothy C. Hoad, Justin Zobel -[@http://www.cs.rmit.edu.au/~jz/fulltext/jasist-tch.pdf] -Contains the hash function that [funcref boost::hash_combine] is based on. - -[endsect] - diff --git a/doc/portability.qbk b/doc/portability.qbk deleted file mode 100644 index d667b89..0000000 --- a/doc/portability.qbk +++ /dev/null @@ -1,93 +0,0 @@ - -[/ Copyright 2005-2008 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:portability Portability] - -[def __boost_hash__ [classref boost::hash]] - -__boost_hash__ is written to be as portable as possible, but unfortunately, several -older compilers don't support argument dependent lookup (ADL) - the mechanism -used for customisation. On those compilers custom overloads for `hash_value` -needs to be declared in the boost namespace. - -On a strictly standards compliant compiler, an overload defined in the -boost namespace won't be found when __boost_hash__ is instantiated, -so for these compilers the overload should only be declared in the same -namespace as the class. - -Let's say we have a simple custom type: - - namespace foo - { - template - class custom_type - { - T value; - public: - custom_type(T x) : value(x) {} - - friend std::size_t hash_value(custom_type x) - { - __boost_hash__ hasher; - return hasher(x.value); - } - }; - } - -On a compliant compiler, when `hash_value` is called for this type, -it will look at the namespace inside the type and find `hash_value` -but on a compiler which doesn't support ADL `hash_value` won't be found. -To make things worse, some compilers which do support ADL won't find -a friend class defined inside the class. - -So first move the member function out of the class: - - namespace foo - { - template - class custom_type - { - T value; - public: - custom_type(T x) : value(x) {} - - std::size_t hash(custom_type x) - { - __boost_hash__ hasher; - return hasher(value); - } - }; - - template - inline std::size_t hash_value(custom_type x) - { - return x.hash(); - } - } - -Unfortunately, I couldn't declare hash_value as a friend, as some compilers -don't support template friends, so instead I declared a member function to -calculate the hash, and called it from hash_value. - -For compilers which don't support ADL, hash_value needs to be defined in the -boost namespace: - - #ifdef BOOST_NO_ARGUMENT_DEPENDENT_LOOKUP - namespace boost - #else - namespace foo - #endif - { - template - std::size_t hash_value(foo::custom_type x) - { - return x.hash(); - } - } - -Full code for this example is at -[@boost:/libs/container_hash/examples/portable.cpp /libs/container_hash/examples/portable.cpp]. - -[endsect] diff --git a/doc/rationale.qbk b/doc/rationale.qbk deleted file mode 100644 index 76ff6d1..0000000 --- a/doc/rationale.qbk +++ /dev/null @@ -1,50 +0,0 @@ - -[/ 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 can be found in the original design -[footnote issue 6.18 of the __issues__ (page 63)]. - -[heading Quality of the hash function] - -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. - -But the standard has no such requirement for the hash function, -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, -then neither the standard hash function or `boost::hash` are appropriate. -There are several options -available. One is to use a second hash on the output of this hash -function, such as [@http://web.archive.org/web/20121102023700/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 there 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] diff --git a/doc/ref.xml b/doc/ref.xml deleted file mode 100644 index 1c8bca9..0000000 --- a/doc/ref.xml +++ /dev/null @@ -1,994 +0,0 @@ - - - - -
- For the full specification, see section 6.3 of the - C++ Standard Library Technical Report - and issue 6.18 of the - Library Extension Technical Report Issues List (page 63). - -
-
- - Defines boost::hash, - and helper functions. - - - - - - - - - - - std::unary_function<T, std::size_t> - - - A TR1 compliant hash function object. - - - std::size_t - - T const& - - - hash_value(val) - - - - The call to hash_value - is unqualified, so that custom overloads can be - found via argument dependent lookup. - - - This is not defined when the macro BOOST_HASH_NO_EXTENSIONS - is defined. The specializations are still defined, so only the specializations - required by TR1 are defined. - - - Forward declared in - <boost/container_hash/hash_fwd.hpp> - - - This hash function is not intended for general use, and isn't - guaranteed to be equal during separate runs of a program - so - please don't use it for any persistent storage or communication. - - - - Only throws if - hash_value(T) throws. - - - - - - - - bool - - - std::size_t - - bool - - - Unspecified in TR1, except that equal arguments yield the same result. - hash_value(val) in Boost. - - Doesn't throw - - - - - - - char - - - std::size_t - - char - - - Unspecified in TR1, except that equal arguments yield the same result. - hash_value(val) in Boost. - - Doesn't throw - - - - - - - signed char - - - std::size_t - - signed char - - - Unspecified in TR1, except that equal arguments yield the same result. - hash_value(val) in Boost. - - Doesn't throw - - - - - - - unsigned char - - - std::size_t - - unsigned char - - - Unspecified in TR1, except that equal arguments yield the same result. - hash_value(val) in Boost. - - Doesn't throw - - - - - - - wchar_t - - - std::size_t - - wchar_t - - - Unspecified in TR1, except that equal arguments yield the same result. - hash_value(val) in Boost. - - Doesn't throw - - - - - - - char16_t - - - std::size_t - - char16_t - - - Unspecified in TR1, except that equal arguments yield the same result. - hash_value(val) in Boost. - - Doesn't throw - - - - - - - char32_t - - - std::size_t - - char32_t - - - Unspecified in TR1, except that equal arguments yield the same result. - hash_value(val) in Boost. - - Doesn't throw - - - - - - - short - - - std::size_t - - short - - - Unspecified in TR1, except that equal arguments yield the same result. - hash_value(val) in Boost. - - Doesn't throw - - - - - - - unsigned short - - - std::size_t - - unsigned short - - - Unspecified in TR1, except that equal arguments yield the same result. - hash_value(val) in Boost. - - Doesn't throw - - - - - - - int - - - std::size_t - - int - - - Unspecified in TR1, except that equal arguments yield the same result. - hash_value(val) in Boost. - - Doesn't throw - - - - - - - unsigned int - - - std::size_t - - unsigned int - - - Unspecified in TR1, except that equal arguments yield the same result. - hash_value(val) in Boost. - - Doesn't throw - - - - - - - long - - - std::size_t - - long - - - Unspecified in TR1, except that equal arguments yield the same result. - hash_value(val) in Boost. - - Doesn't throw - - - - - - - unsigned long - - - std::size_t - - unsigned long - - - Unspecified in TR1, except that equal arguments yield the same result. - hash_value(val) in Boost. - - Doesn't throw - - - - - - - long long - - - std::size_t - - long long - - - Unspecified in TR1, except that equal arguments yield the same result. - hash_value(val) in Boost. - - Doesn't throw - - - - - - - unsigned long long - - - std::size_t - - unsigned long long - - - Unspecified in TR1, except that equal arguments yield the same result. - hash_value(val) in Boost. - - Doesn't throw - - - - - - - float - - - std::size_t - - float - - - Unspecified in TR1, except that equal arguments yield the same result. - hash_value(val) in Boost. - - Doesn't throw - - - - - - - double - - - std::size_t - - double - - - Unspecified in TR1, except that equal arguments yield the same result. - hash_value(val) in Boost. - - Doesn't throw - - - - - - - long double - - - std::size_t - - long double - - - Unspecified in TR1, except that equal arguments yield the same result. - hash_value(val) in Boost. - - Doesn't throw - - - - - - - std::string - - - std::size_t - - std::string const& - - - Unspecified in TR1, except that equal arguments yield the same result. - hash_value(val) in Boost. - - Doesn't throw - - - - - - - std::wstring - - - std::size_t - - std::wstring const& - - - Unspecified in TR1, except that equal arguments yield the same result. - hash_value(val) in Boost. - - Doesn't throw - - - - - - - std::u16string - - - std::size_t - - std::u16string const& - - - Unspecified in TR1, except that equal arguments yield the same result. - hash_value(val) in Boost. - - Doesn't throw - - - - - - - std::u32string - - - std::size_t - - std::u32string const& - - - Unspecified in TR1, except that equal arguments yield the same result. - hash_value(val) in Boost. - - Doesn't throw - - - - - - - T* - - - std::size_t - - T* - - - Unspecified in TR1, except that equal arguments yield the same result. - - Doesn't throw - - - - - - - std::type_index - - - std::size_t - - std::type_index - - - val.hash_code() - - Doesn't throw - - - - Only available if it's in your standard library and Boost.Config - is aware of it. - - - - - - - - - - - void - size_t & - T const& - - Called repeatedly to incrementally create a hash value from - several variables. - - - Updates seed with a new hash value generated by - combining it with the result of - hash_value(v). Will - always produce the same result for the same combination of - seed and - hash_value(v) during - the single run of a program. - - - hash_value is called without - qualification, so that overloads can be found via ADL. - This is an extension to TR1 - - Forward declared in - <boost/container_hash/hash_fwd.hpp> - - - This hash function is not intended for general use, and isn't - guaranteed to be equal during separate runs of a program - so - please don't use it for any persistent storage or communication. - - - - Only throws if hash_value(T) throws. - Strong exception safety, as long as hash_value(T) - also has strong exception safety. - - - - - - - - - std::size_t - It - It - - - - - void - std::size_t& - It - It - - - - 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) -{ - hash_combine(seed, *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 - so it wouldn't be appropriate to use this with an unordered - container. - - This is an extension to TR1 - - Forward declared in - <boost/container_hash/hash_fwd.hpp> - - - This hash function is not intended for general use, and isn't - guaranteed to be equal during separate runs of a program - so - please don't use it for any persistent storage or communication. - - - - Only throws if hash_value(std::iterator_traits<It>::value_type) - throws. hash_range(std::size_t&, It, It) has basic exception safety as long as - hash_value(std::iterator_traits<It>::value_type) - has basic exception safety. - - - - - - - - - - - - Implementation of the hash function. - - - - std::size_t - bool - - - - std::size_t - char - - - - std::size_t - signed char - - - - std::size_t - unsigned char - - - - std::size_t - wchar_t - - - - std::size_t - char16_t - - - - std::size_t - char32_t - - - - std::size_t - short - - - - std::size_t - unsigned short - - - - std::size_t - int - - - - std::size_t - unsigned int - - - - std::size_t - long - - - - std::size_t - unsigned long - - - - std::size_t - long long - - - - std::size_t - unsigned long long - - - - std::size_t - float - - - - std::size_t - double - - - - std::size_t - long double - - - - - std::size_t - T* const& - - - - - std::size_t - T (&val)[N] - - - - - std::size_t - const T (&val)[N] - - - - - std::size_t - - std::basic_string<Ch, std::char_traits<Ch>, A> const& - - - - - - std::size_t - std::pair<A, B> const& - - - - - std::size_t - std::vector<T, A> const& - - - - - std::size_t - std::list<T, A> const& - - - - - std::size_t - std::deque<T, A> const& - - - - - std::size_t - std::set<K, C, A> const& - - - - - std::size_t - std::multiset<K, C, A> const& - - - - - std::size_t - std::map<K, T, C, A> const& - - - - - std::size_t - std::multimap<K, T, C, A> const& - - - - - std::size_t - std::complex<T> const& - - - - std::size_t - std::type_index - - - - - std::size_t - std::array<T, N> const& - - - - - std::size_t - std::tuple<T...> - - - - 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. - - - - This is an extension to TR1 - - This hash function is not intended for general use, and isn't - guaranteed to be equal during separate runs of a program - so - please don't use it for any persistent storage or communication. - - - - - Only throws if a user supplied version of - hash_value - throws for an element of a container, or - one of the types stored in a pair. - - - - - - - - Types - Returns - - - - - bool, - char, signed char, unsigned char, - wchar_t, char16_t, char32_t, - short, unsigned short, - int, unsigned int, long, unsigned long - - val - - - long long, unsigned long long - val when abs(val) <= std::numeric_limits<std::size_t>::max(). - - - float, double, long double - An unspecified value, except that equal arguments shall yield the same result. - - - T* - An unspecified value, except that equal arguments shall yield the same result. - - - - T val[N], - const T val[N] - - hash_range(val, val+N) - - - - std:basic_string<Ch, std::char_traits<Ch>, A>, - std::vector<T, A>, - std::list<T, A>, - std::deque<T, A>, - std::set<K, C, A>, - std::multiset<K, C, A>, - std::map<K, T, C, A>, - std::multimap<K, T, C, A>, - std::array<T, N> - - hash_range(val.begin(), val.end()) - - - std::pair<A, B> - size_t seed = 0; -hash_combine(seed, val.first); -hash_combine(seed, val.second); -return seed; - - - std::tuple<T...> - size_t seed = 0; -hash_combine(seed, get<0>(val)); -hash_combine(seed, get<1>(val)); -// .... -return seed; - - - - std::complex<T> - - When T is a built in type and val.imag() == 0, the result is equal to hash_value(val.real()). Otherwise an unspecified value, except that equal arguments shall yield the same result. - - - - std::type_index - - val.hash_code() - - - - - - - - -
- - diff --git a/doc/samples/tutorial.cpp b/doc/samples/tutorial.cpp deleted file mode 100644 index b11609b..0000000 --- a/doc/samples/tutorial.cpp +++ /dev/null @@ -1,27 +0,0 @@ -#include -#include -#include -#include -#include - -//[ get_hashes -template -std::vector get_hashes(Container const& x) -{ - std::vector hashes; - std::transform(x.begin(), x.end(), std::back_inserter(hashes), - boost::hash()); - - return hashes; -} -//] - -int main() { - std::vector values; - values.push_back(10); - values.push_back(20); - - std::vector hashes = get_hashes(values); - assert(hashes[0] = boost::hash()(values[0])); - assert(hashes[1] = boost::hash()(values[1])); -} diff --git a/doc/thanks.qbk b/doc/thanks.qbk deleted file mode 100644 index fcc5108..0000000 --- a/doc/thanks.qbk +++ /dev/null @@ -1,28 +0,0 @@ - -[/ Copyright 2005-2008 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:acknowledgements Acknowledgements] - -This library is based on the design by Peter Dimov. During the initial -development -Joaquín M López Muñoz made many useful suggestions and contributed fixes. - -The formal review was managed by Thorsten Ottosen, and the library reviewed by: -David Abrahams, Alberto Barbati, Topher Cooper, Caleb Epstein, Dave Harris, -Chris Jefferson, Bronek Kozicki, John Maddock, Tobias Swinger, Jaap Suter, -Rob Stewart and Pavel Vozenilek. Since then, further constructive criticism has -been made by Daniel Krügler, Alexander Nasonov and 沈慧峰. - -The implementation of the hash function for pointers is based on suggestions -made by Alberto Barbati and Dave Harris. Dave Harris also suggested an -important improvement to [funcref boost::hash_combine] that was taken up. - -Some useful improvements to the floating point hash algorithm were suggested -by Daniel Krügler. - -The original implementation came from Jeremy B. Maitin-Shepard's hash table -library, although this is a complete rewrite. - -[endsect] diff --git a/doc/tutorial.qbk b/doc/tutorial.qbk deleted file mode 100644 index 234b759..0000000 --- a/doc/tutorial.qbk +++ /dev/null @@ -1,207 +0,0 @@ - -[/ Copyright 2005-2008 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) ] - -[quickbook 1.7] -[import samples/tutorial.cpp] - -[def __multi-index-short__ [@boost:/libs/multi_index/doc/index.html - Boost.MultiIndex]] - -[section:tutorial Tutorial] - -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 hash.custom section on extending boost::hash for a custom data type]. - -If your standard library supplies its own implementation of the unordered -associative containers and you wish to use -[classref boost::hash], just use an extra template parameter: - - std::unordered_multiset > - set_of_ints; - - std::unordered_set, ``[classref boost::hash]`` > - set_of_pairs; - - std::unordered_map > map_int_to_string; - -To use [classref boost::hash] directly, create an instance and call it as a function: - - #include <``[headerref boost/container_hash/hash.hpp]``> - - int main() - { - ``[classref boost::hash]`` string_hash; - - std::size_t h = string_hash("Hash me"); - } - -For an example of generic use, here is a function to generate a vector -containing the hashes of the elements of a container: - -[get_hashes] - -[endsect] - -[section:custom Extending boost::hash for a custom data type] - -[classref boost::hash] is implemented by calling the function -[funcref boost::hash_value hash_value]. -The namespace isn't specified so that it can detect overloads via argument -dependant lookup. So if there is a free function `hash_value` in the same -namespace as a custom type, it will get called. - -If you have a structure `library::book`, where each `book` is uniquely -defined by it's member `id`: - - namespace library - { - struct book - { - int id; - std::string author; - std::string title; - - // .... - }; - - bool operator==(book const& a, book const& b) - { - return a.id == b.id; - } - } - -Then all you would need to do is write the function `library::hash_value`: - - namespace library - { - std::size_t hash_value(book const& b) - { - ``[classref boost::hash]`` hasher; - return hasher(b.id); - } - } - -And you can now use [classref boost::hash] with book: - - library::book knife(3458, "Zane Grey", "The Hash Knife Outfit"); - library::book dandelion(1354, "Paul J. Shanley", - "Hash & Dandelion Greens"); - - ``[classref boost::hash]`` book_hasher; - std::size_t knife_hash_value = book_hasher(knife); - - // 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.", - "Heavenly Hash: A Tasty Mix of a Mother's Meditations")); - - assert(books.find(knife) != books.end()); - assert(books.find(dandelion) == books.end()); - -The full example can be found in: -[@boost:/libs/container_hash/examples/books.hpp /libs/container_hash/examples/books.hpp] -and -[@boost:/libs/container_hash/examples/books.cpp /libs/container_hash/examples/books.cpp]. - -[tip -When writing a hash function, first look at how the equality function works. -Objects that are equal must generate the same hash value. -When objects are not equal they should generate different hash values. -In this object equality was based just on the id so the hash function -only hashes the id. If it was based on the object's name and author -then the hash function should take them into account -(how to do this is discussed in the next section). -] - -[endsect] - -[section:combine Combining hash values] - -Say you have a point class, representing a two dimensional location: - - class point - { - int x; - int y; - public: - point() : x(0), y(0) {} - point(int x, int y) : x(x), y(y) {} - - bool operator==(point const& other) const - { - return x == other.x && y == other.y; - } - }; - -and you wish to use it as the key for an `unordered_map`. You need to -customise the hash for this structure. To do this we need to combine -the hash values for `x` and `y`. The function -[funcref boost::hash_combine] is supplied for this purpose: - - class point - { - ... - - friend std::size_t hash_value(point const& p) - { - std::size_t seed = 0; - ``[funcref boost::hash_combine]``(seed, p.x); - ``[funcref boost::hash_combine]``(seed, p.y); - - return seed; - } - - ... - }; - -Calls to hash_combine incrementally build the hash from the different members -of point, it can be repeatedly called for any number of elements. It calls -[funcref boost::hash_value hash_value] on the supplied element, and combines it with the seed. - -Full code for this example is at -[@boost:/libs/container_hash/examples/point.cpp /libs/container_hash/examples/point.cpp]. - -[note -When using [funcref boost::hash_combine] the order of the -calls matters. -''' - - std::size_t seed = 0; - boost::hash_combine(seed, 1); - boost::hash_combine(seed, 2); - -results in a different seed to: - - std::size_t seed = 0; - boost::hash_combine(seed, 2); - boost::hash_combine(seed, 1); - -''' -If you are calculating a hash value for data where the order of the data -doesn't matter in comparisons (e.g. a set) you will have to ensure that the -data is always supplied in the same order. -] - -To calculate the hash of an iterator range you can use [funcref boost::hash_range]: - - std::vector some_strings; - std::size_t hash = ``[funcref boost::hash_range]``(some_strings.begin(), some_strings.end()); - -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 `` -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/container_hash/examples/template.hpp template.hpp] and -[@boost:/libs/container_hash/examples/template.cpp template.cpp]. - -[endsect]