diff --git a/hash/doc/changes.qbk b/hash/doc/changes.qbk index 5ca422d..fdb5b32 100644 --- a/hash/doc/changes.qbk +++ b/hash/doc/changes.qbk @@ -13,8 +13,8 @@ * 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, - `` is used. -* Add support for the BOOST_HASH_NO_EXTENSIONS macro, which + <[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. diff --git a/hash/doc/disable.qbk b/hash/doc/disable.qbk new file mode 100644 index 0000000..609e4d5 --- /dev/null +++ b/hash/doc/disable.qbk @@ -0,0 +1,24 @@ +[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/functional/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/hash/doc/hash.qbk b/hash/doc/hash.qbk index 611ba73..fa8c618 100644 --- a/hash/doc/hash.qbk +++ b/hash/doc/hash.qbk @@ -17,6 +17,7 @@ [include:hash intro.qbk] [include:hash tutorial.qbk] [include:hash portability.qbk] +[include:hash disable.qbk] [include:hash changes.qbk] [xinclude ref.xml] [include:hash links.qbk] diff --git a/hash/doc/portability.qbk b/hash/doc/portability.qbk index ef3d977..04cafc2 100644 --- a/hash/doc/portability.qbk +++ b/hash/doc/portability.qbk @@ -4,7 +4,7 @@ __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 +used for customisation. On those compilers custom overloads for `hash_value` need to be declared in the boost namespace. On a strictly standards compliant compiler, an overload defined in the diff --git a/hash/doc/tutorial.qbk b/hash/doc/tutorial.qbk index cda8df5..b054411 100644 --- a/hash/doc/tutorial.qbk +++ b/hash/doc/tutorial.qbk @@ -1,3 +1,6 @@ +[def __multi-index-short__ [@../../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 @@ -19,7 +22,7 @@ associative containers and you wish to use To use [classref boost::hash] directly, create an instance and call it as a function: - #include + #include <``[headerref boost/functional/hash.hpp]``> int main() { @@ -45,7 +48,8 @@ containing the hashes of the elements of a container: [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]. +[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. @@ -108,7 +112,7 @@ and [blurb 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 the should generate different hash values. +When objects are not equal they should generate different hash values. In this object equality was based just on the id, if it was based on the objects name and author the hash function should take them into account (how to do this is discussed in the next section). @@ -146,8 +150,8 @@ the hash values for `x` and `y`. The function 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); + ``[funcref boost::hash_combine]``(seed, p.x); + ``[funcref boost::hash_combine]``(seed, p.y); return seed; } @@ -163,9 +167,9 @@ Full code for this example is at [@../../libs/functional/hash/examples/point.cpp /libs/functional/hash/examples/point.cpp]. [blurb -''' When using [funcref boost::hash_combine] the order of the calls matters. +''' std::size_t seed = 0; boost::hash_combine(seed, 1); @@ -177,16 +181,16 @@ results in a different seed to: 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()); + std::size_t hash = ``[funcref boost::hash_range]``(some_strings.begin(), some_strings.end()); [endsect]