summaryrefslogtreecommitdiff
path: root/doc/html/hash/combine.html
blob: 11cd6cbfa2efdf202e32ce385d118a05e3b1269d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
<!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=US-ASCII">
<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&#160;15.&#160;Boost.Functional/Hash">
<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_value_idp528258032">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/functional/hash/examples/point.cpp" target="_top">/libs/functional/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_idp528238080">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_idp528238080">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">functional</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_idp528238080">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/functional/hash/examples/template.hpp" target="_top">template.hpp</a>
      and <a href="../../../libs/functional/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 &#169; 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>