feedc0de/boost_container_hash
1
0
Fork 0
forked from boostorg/container_hash
Code Pull Requests Activity

Add a note about the BOOST_HASH_NO_EXTENSIONS macro, and fix some typos and

Browse Source 
improve the markup in the hash documentation.


[SVN r33298]
This commit is contained in:
Daniel James
2006-03-09 23:59:19 +00:00
parent 49a87ce365
commit 7770a516fe
5 changed files with 40 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
doc/changes.qbk
View File

@@ -13,8 +13,8 @@
* Use declarations for standard classes, so that the library
doesn't need to include all of their headers
* Deprecated the `<boost/functional/hash/*.hpp>` headers. Now a single header,
`<boost/functional/hash.hpp>` 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.

24
doc/disable.qbk Normal file
View File

@@ -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]

1
doc/hash.qbk
View File

@@ -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]

2
doc/portability.qbk
View File

@@ -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

20
doc/tutorial.qbk
View File

@@ -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 <boost/functional/hash.hpp>
#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.
'''
<programlisting>
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);
</programlisting>
'''
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<std::string> 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]