hash.qbk

C++的一个好库。。。现在很流行

    #else
            std::size_t hash() const
            {
                __boost_hash<int> hasher;
                return hasher(value);
            }
    #endif

which will be called from the `boost` namespace:

    #ifdef BOOST_NO_ARGUMENT_DEPENDENT_LOOKUP
    namespace boost
    {
        std::size_t hash_value(foo::custom_type x)
        {
            return x.hash();
        }
    }
    #endif

Full code for this example is at
[@../../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, __hash_combine and __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.

`boost::hash_value(long double)` on GCC on Solaris appears to treat
`long double`s as doubles - so the hash function doesn't take into account the
full range of values.

[endsect]

[/ Quickbook insists on putting a paragraph around the escaped code, which
messes up the library section, so I wrap it in another section. This is no good,
but there you go. ]

[section:reference_ Reference]
'''
<library-reference>
  <section id="hash.reference.specification">
    <para>For the full specification, see section 6.3 of the
        <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1745.pdf">C++ Standard Library Technical Report</ulink>
        and issue 6.18 of the
        <ulink url="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1756.pdf">Library Extension Technical Report Issues List</ulink>.
    </para>
  </section>
  <header name="boost/functional/hash.hpp">
    <para>Includes all the following headers.</para>
  </header>
  <header name="boost/functional/hash/hash.hpp">
    <para>
      Defines <code><classname>boost::hash</classname></code>,
      the implementation for built in types and
      <code>std::string</code> and customisation functions.
    </para>

    <namespace name="boost">

      <!--
        boost::hash
        -->

      <struct name="hash">
        <template>
          <template-type-parameter name="T"/>
        </template>

        <inherit access="public">
          <classname>std::unary_function&lt;T, std::size_t&gt;</classname>
        </inherit>

        <purpose>An STL compliant hash function object.</purpose>

        <method name="operator()" cv="const">
          <type>std::size_t</type>
          <parameter name="val">
            <paramtype>T const&amp;</paramtype>
          </parameter>
          <returns><para>
            <programlisting><functionname>hash_value</functionname>(val)</programlisting>
          </para></returns>
          <notes><para>
            The call to <code><functionname>hash_value</functionname></code>
            is unqualified, so that custom overloads can be
            found via argument dependent lookup.
          </para></notes>
          <throws><para>
            Only throws if
            <code><functionname>hash_value</functionname>(T)</code> throws.
          </para></throws>
        </method>
      </struct>

      <!--
        boost::hash_combine
        -->

      <function name="hash_combine">
        <template>
          <template-type-parameter name="T"/>
        </template>
        <type>void</type>
        <parameter name="seed"><paramtype>size_t &amp;</paramtype></parameter>
        <parameter name="v"><paramtype>T const &amp;</paramtype></parameter>
        <purpose>
            Called repeatedly to incrementally create a hash value from
            several variables.
        </purpose>
        <effects><programlisting>seed ^= <functionname>hash_value</functionname>(v) + 0x9e3779b9 + (seed &lt;&lt; 6) + (seed &gt;&gt; 2);</programlisting></effects>
        <notes>
          <para><functionname>hash_value</functionname> is called without
          qualification, so that overloads can be found via ADL.</para>
          <para>This is an extension to TR1</para>
        </notes>
        <throws>
          Only throws if <functionname>hash_value</functionname>(T) throws.
          Strong exception safety, as long as <functionname>hash_value</functionname>(T)
          also has strong exception safety.
        </throws>
      </function>

      <!--
        boost::hash_range
        -->

      <overloaded-function name="hash_range">
        <signature>
          <template>
            <template-type-parameter name="It"/>
          </template>
          <type>std::size_t</type>
          <parameter name="first"><paramtype>It</paramtype></parameter>
          <parameter name="last"><paramtype>It</paramtype></parameter>
        </signature>

        <signature>
          <template>
            <template-type-parameter name="It"/>
          </template>
          <type>void</type>
          <parameter name="seed"><paramtype>std::size_t&amp;</paramtype></parameter>
          <parameter name="first"><paramtype>It</paramtype></parameter>
          <parameter name="last"><paramtype>It</paramtype></parameter>
        </signature>

        <purpose>
            Calculate the combined hash value of the elements of an iterator
            range.
        </purpose>
        <effects>
          <para>For the two argument overload:
<programlisting>
size_t seed = 0;

for(; first != last; ++first)
{
    <functionname>hash_combine</functionname>(seed, *first);
}

return seed;
</programlisting>
          </para>For the three arguments overload:
<programlisting>
for(; first != last; ++first)
{
    <functionname>hash_combine</functionname>(seed, *first);
}
</programlisting>
          <para>
          </para>
        </effects>
        <notes>
          <para>
            <code>hash_range</code> is sensitive to the order of the elements
            so it wouldn't be appropriate to use this with an unordered
            container.
          </para>
          <para>This is an extension to TR1</para>
        </notes>
        <throws><para>
          Only throws if <code><functionname>hash_value</functionname>(std::iterator_traits&lt;It&gt;::value_type)</code>
          throws. <code>hash_range(std::size_t&amp;, It, It)</code> has basic exception safety as long as
          <code><functionname>hash_value</functionname>(std::iterator_traits&lt;It&gt;::value_type)</code>
          has basic exception safety.
        </para></throws>
      </overloaded-function>

      <!--
        boost::hash_value - integers
        -->

      <overloaded-function name="hash_value">
        <purpose>
            Implementation of a hash function for integers.
        </purpose>

        <description><para>
          Generally shouldn't be called directly by users, instead they should use
          <classname>boost::hash</classname>, <functionname>boost::hash_range</functionname>
          or <functionname>boost::hash_combine</functionname> which
          call hash_value without namespace qualification so that overloads
          for custom types are found via ADL.
        </para></description>
        <notes>
          <para>Overloads for other types supplied in other headers.</para>
          <para>This is an extension to TR1</para>
        </notes>

        <signature>
          <type>std::size_t</type>
          <parameter name="val"><paramtype>int</paramtype></parameter>
        </signature>

        <signature>
          <type>std::size_t</type>
          <parameter name="val"><paramtype>unsigned int</paramtype></parameter>
        </signature>

        <signature>
          <type>std::size_t</type>
          <parameter name="val"><paramtype>long</paramtype></parameter>
        </signature>

        <signature>
          <type>std::size_t</type>
          <parameter name="val"><paramtype>unsigned long</paramtype></parameter>
        </signature>

        <returns>
          <code>val</code>
        </returns>
      </overloaded-function>

      <!--
        boost::hash_value - floating point
        -->

      <overloaded-function name="hash_value">
        <purpose>
            Implementation of a hash function for floating point values.
        </purpose>

        <description><para>
          Generally shouldn't be called directly by users, instead they should use
          <classname>boost::hash</classname>, <functionname>boost::hash_range</functionname>
          or <functionname>boost::hash_combine</functionname> which
          call hash_value without namespace qualification so that overloads
          for custom types are found via ADL.
        </para></description>
        <notes>
          <para>Overloads for other types supplied in other headers.</para>
          <para>This is an extension to TR1</para>
        </notes>

        <signature>
          <type>std::size_t</type>
          <parameter name="val"><paramtype>float</paramtype></parameter>
        </signature>

        <signature>
          <type>std::size_t</type>
          <parameter name="val"><paramtype>double</paramtype></parameter>
        </signature>

        <signature>
          <type>std::size_t</type>
          <parameter name="val"><paramtype>long double</paramtype></parameter>
        </signature>

        <returns>
          <para>
            An unspecified value, except that equal arguments shall yield the same
            result
          </para>
        </returns>
      </overloaded-function>

      <!--
        boost::hash_value - pointers
        -->

      <overloaded-function name="hash_value">
        <purpose>
            Implementation of a hash function for pointers.
        </purpose>

        <description><para>
          Generally shouldn't be called directly by users, instead they should use
          <classname>boost::hash</classname>, <functionname>boost::hash_range</functionname>
          or <functionname>boost::hash_combine</functionname> which
          call hash_value without namespace qualification so that overloads
          for custom types are found via ADL.
        </para></description>
        <notes>
          <para>Overloads for other types supplied in other headers.</para>
          <para>This is an extension to TR1</para>
        </notes>

        <signature>
          <template><template-type-parameter name="T"/></template>
          <type>std::size_t</type>
          <parameter name="val"><paramtype>T* const&amp;</paramtype></parameter>
        </signature>

        <returns>
          <para>