generic-library/boost
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
main
boost/doc/html/hash/combine.html
Edouard DUPIN d0115b733d [DEV] add v1.76.0
2021-10-05 21:37:46 +02:00

143 lines
12 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Combining hash values</title>
<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="../hash.html" title="Chapter 10. Boost.ContainerHash">
<link rel="prev" href="custom.html" title="Extending boost::hash for a custom data type">
<link rel="next" href="portability.html" title="Portability">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
<td align="center"><a href="../../../index.html">Home</a></td>
<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="custom.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../hash.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="portability.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="hash.combine"></a><a class="link" href="combine.html" title="Combining hash values">Combining hash values</a>
</h2></div></div></div>
<p>
Say you have a point class, representing a two dimensional location:
</p>
<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">point</span>
<span class="special">{</span>
<span class="keyword">int</span> <span class="identifier">x</span><span class="special">;</span>
<span class="keyword">int</span> <span class="identifier">y</span><span class="special">;</span>
<span class="keyword">public</span><span class="special">:</span>
<span class="identifier">point</span><span class="special">()</span> <span class="special">:</span> <span class="identifier">x</span><span class="special">(</span><span class="number">0</span><span class="special">),</span> <span class="identifier">y</span><span class="special">(</span><span class="number">0</span><span class="special">)</span> <span class="special">{}</span>
<span class="identifier">point</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">y</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">x</span><span class="special">(</span><span class="identifier">x</span><span class="special">),</span> <span class="identifier">y</span><span class="special">(</span><span class="identifier">y</span><span class="special">)</span> <span class="special">{}</span>
<span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">==(</span><span class="identifier">point</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">other</span><span class="special">)</span> <span class="keyword">const</span>
<span class="special">{</span>
<span class="keyword">return</span> <span class="identifier">x</span> <span class="special">==</span> <span class="identifier">other</span><span class="special">.</span><span class="identifier">x</span> <span class="special">&amp;&amp;</span> <span class="identifier">y</span> <span class="special">==</span> <span class="identifier">other</span><span class="special">.</span><span class="identifier">y</span><span class="special">;</span>
<span class="special">}</span>
<span class="special">};</span>
</pre>
<p>
and you wish to use it as the key for an <code class="computeroutput"><span class="identifier">unordered_map</span></code>.
You need to customise the hash for this structure. To do this we need to combine
the hash values for <code class="computeroutput"><span class="identifier">x</span></code> and
<code class="computeroutput"><span class="identifier">y</span></code>. The function <code class="computeroutput"><a class="link" href="reference.html#boost.hash_combine">boost::hash_combine</a></code> is supplied for
this purpose:
</p>
<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">point</span>
<span class="special">{</span>
<span class="special">...</span>
<span class="keyword">friend</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">hash_value</span><span class="special">(</span><span class="identifier">point</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">p</span><span class="special">)</span>
<span class="special">{</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">seed</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
<code class="computeroutput"><a class="link" href="reference.html#boost.hash_combine">boost::hash_combine</a></code><span class="special">(</span><span class="identifier">seed</span><span class="special">,</span> <span class="identifier">p</span><span class="special">.</span><span class="identifier">x</span><span class="special">);</span>
<code class="computeroutput"><a class="link" href="reference.html#boost.hash_combine">boost::hash_combine</a></code><span class="special">(</span><span class="identifier">seed</span><span class="special">,</span> <span class="identifier">p</span><span class="special">.</span><span class="identifier">y</span><span class="special">);</span>
<span class="keyword">return</span> <span class="identifier">seed</span><span class="special">;</span>
<span class="special">}</span>
<span class="special">...</span>
<span class="special">};</span>
</pre>
<p>
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
<code class="computeroutput"><a class="link" href="reference.html#boost.hash_va_1_3_11_11_2_2_27_1">hash_value</a></code> on the supplied
element, and combines it with the seed.
</p>
<p>
Full code for this example is at <a href="../../../libs/container_hash/examples/point.cpp" target="_top">/libs/container_hash/examples/point.cpp</a>.
</p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top">
<p>
When using <code class="computeroutput"><a class="link" href="reference.html#boost.hash_combine">boost::hash_combine</a></code>
the order of the calls matters. </p>
<pre class="programlisting">
std::size_t seed = 0;
boost::hash_combine(seed, 1);
boost::hash_combine(seed, 2);
</pre>
<p>
results in a different seed to:
</p>
<pre class="programlisting">
std::size_t seed = 0;
boost::hash_combine(seed, 2);
boost::hash_combine(seed, 1);
</pre>
<p>
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.
</p>
</td></tr>
</table></div>
<p>
To calculate the hash of an iterator range you can use <code class="computeroutput"><a class="link" href="reference.html#boost.hash_range">boost::hash_range</a></code>:
</p>
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;</span> <span class="identifier">some_strings</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">hash</span> <span class="special">=</span> <code class="computeroutput"><a class="link" href="reference.html#boost.hash_range">boost::hash_range</a></code><span class="special">(</span><span class="identifier">some_strings</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">some_strings</span><span class="special">.</span><span class="identifier">end</span><span class="special">());</span>
</pre>
<p>
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 <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">container_hash</span><span class="special">/</span><span class="identifier">hash_fwd</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></code>
header which forward declares <code class="computeroutput"><a class="link" href="../boost/hash.html" title="Struct template hash">boost::hash</a></code>,
<code class="computeroutput"><a class="link" href="reference.html#boost.hash_range">boost::hash_range</a></code> and
<code class="computeroutput"><a class="link" href="reference.html#boost.hash_combine">boost::hash_combine</a></code>.
You'll need to include the main header before instantiating <code class="computeroutput"><a class="link" href="../boost/hash.html" title="Struct template hash">boost::hash</a></code>.
When using a container that uses <code class="computeroutput"><a class="link" href="../boost/hash.html" title="Struct template hash">boost::hash</a></code>
it should do that for you, so your type will work fine with the boost hash
containers. There's an example of this in <a href="../../../libs/container_hash/examples/template.hpp" target="_top">template.hpp</a>
and <a href="../../../libs/container_hash/examples/template.cpp" target="_top">template.cpp</a>.
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2005-2008 Daniel
James<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="custom.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../hash.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="portability.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink