3 Copyright Daniel James 2005-2009
4 Distributed under the Boost Software License, Version 1.0. (See accompanying
5 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
9 <section id=
"hash.reference.specification">
10 <para>For the full specification, see section
6.3 of the
11 <ulink url=
"http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf">C++ Standard Library Technical Report
</ulink>
13 <ulink url=
"http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1837.pdf">Library Extension Technical Report Issues List
</ulink> (page
63).
16 <header name=
"boost/functional/hash.hpp">
18 Defines
<code><classname>boost::hash
</classname></code>,
22 <namespace name=
"boost">
30 <template-type-parameter name=
"T"/>
33 <inherit access=
"public">
34 <classname>std::unary_function
<T, std::size_t
></classname>
37 <purpose><simpara>A
<ulink url=
"http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf">TR1
</ulink> compliant hash function object.
</simpara></purpose>
39 <method name=
"operator()" cv=
"const">
40 <type>std::size_t
</type>
41 <parameter name=
"val">
42 <paramtype>T const
&</paramtype>
45 <programlisting><functionname>hash_value
</functionname>(val)
</programlisting>
49 The call to
<code><functionname>hash_value
</functionname></code>
50 is unqualified, so that custom overloads can be
51 found via argument dependent lookup.
54 This is not defined when the macro
<code>BOOST_HASH_NO_EXTENSIONS
</code>
55 is defined. The specializations are still defined, so only the specializations
56 required by TR1 are defined.
60 <code><boost/functional/hash_fwd.hpp
></code>
63 This hash function is not intended for general use, and isn't
64 guaranteed to be equal during separate runs of a program - so
65 please don't use it for any persistent storage or communication.
70 <code><functionname>hash_value
</functionname>(T)
</code> throws.
75 <struct-specialization name=
"hash">
78 <template-arg>bool
</template-arg>
80 <method name=
"operator()" cv=
"const">
81 <type>std::size_t
</type>
82 <parameter name=
"val">
83 <paramtype>bool
</paramtype>
86 <para>Unspecified in TR1, except that equal arguments yield the same result.
</para>
87 <para><functionname>hash_value
</functionname>(val) in Boost.
</para>
89 <throws><para>Doesn't throw
</para></throws>
91 </struct-specialization>
93 <struct-specialization name=
"hash">
96 <template-arg>char
</template-arg>
98 <method name=
"operator()" cv=
"const">
99 <type>std::size_t
</type>
100 <parameter name=
"val">
101 <paramtype>char
</paramtype>
104 <para>Unspecified in TR1, except that equal arguments yield the same result.
</para>
105 <para><functionname>hash_value
</functionname>(val) in Boost.
</para>
107 <throws><para>Doesn't throw
</para></throws>
109 </struct-specialization>
111 <struct-specialization name=
"hash">
112 <template></template>
114 <template-arg>signed char
</template-arg>
116 <method name=
"operator()" cv=
"const">
117 <type>std::size_t
</type>
118 <parameter name=
"val">
119 <paramtype>signed char
</paramtype>
122 <para>Unspecified in TR1, except that equal arguments yield the same result.
</para>
123 <para><functionname>hash_value
</functionname>(val) in Boost.
</para>
125 <throws><para>Doesn't throw
</para></throws>
127 </struct-specialization>
129 <struct-specialization name=
"hash">
130 <template></template>
132 <template-arg>unsigned char
</template-arg>
134 <method name=
"operator()" cv=
"const">
135 <type>std::size_t
</type>
136 <parameter name=
"val">
137 <paramtype>unsigned char
</paramtype>
140 <para>Unspecified in TR1, except that equal arguments yield the same result.
</para>
141 <para><functionname>hash_value
</functionname>(val) in Boost.
</para>
143 <throws><para>Doesn't throw
</para></throws>
145 </struct-specialization>
147 <struct-specialization name=
"hash">
148 <template></template>
150 <template-arg>wchar_t
</template-arg>
152 <method name=
"operator()" cv=
"const">
153 <type>std::size_t
</type>
154 <parameter name=
"val">
155 <paramtype>wchar_t
</paramtype>
158 <para>Unspecified in TR1, except that equal arguments yield the same result.
</para>
159 <para><functionname>hash_value
</functionname>(val) in Boost.
</para>
161 <throws><para>Doesn't throw
</para></throws>
163 </struct-specialization>
165 <struct-specialization name=
"hash">
166 <template></template>
168 <template-arg>short
</template-arg>
170 <method name=
"operator()" cv=
"const">
171 <type>std::size_t
</type>
172 <parameter name=
"val">
173 <paramtype>short
</paramtype>
176 <para>Unspecified in TR1, except that equal arguments yield the same result.
</para>
177 <para><functionname>hash_value
</functionname>(val) in Boost.
</para>
179 <throws><para>Doesn't throw
</para></throws>
181 </struct-specialization>
183 <struct-specialization name=
"hash">
184 <template></template>
186 <template-arg>unsigned short
</template-arg>
188 <method name=
"operator()" cv=
"const">
189 <type>std::size_t
</type>
190 <parameter name=
"val">
191 <paramtype>unsigned short
</paramtype>
194 <para>Unspecified in TR1, except that equal arguments yield the same result.
</para>
195 <para><functionname>hash_value
</functionname>(val) in Boost.
</para>
197 <throws><para>Doesn't throw
</para></throws>
199 </struct-specialization>
201 <struct-specialization name=
"hash">
202 <template></template>
204 <template-arg>int
</template-arg>
206 <method name=
"operator()" cv=
"const">
207 <type>std::size_t
</type>
208 <parameter name=
"val">
209 <paramtype>int
</paramtype>
212 <para>Unspecified in TR1, except that equal arguments yield the same result.
</para>
213 <para><functionname>hash_value
</functionname>(val) in Boost.
</para>
215 <throws><para>Doesn't throw
</para></throws>
217 </struct-specialization>
219 <struct-specialization name=
"hash">
220 <template></template>
222 <template-arg>unsigned int
</template-arg>
224 <method name=
"operator()" cv=
"const">
225 <type>std::size_t
</type>
226 <parameter name=
"val">
227 <paramtype>unsigned int
</paramtype>
230 <para>Unspecified in TR1, except that equal arguments yield the same result.
</para>
231 <para><functionname>hash_value
</functionname>(val) in Boost.
</para>
233 <throws><para>Doesn't throw
</para></throws>
235 </struct-specialization>
237 <struct-specialization name=
"hash">
238 <template></template>
240 <template-arg>long
</template-arg>
242 <method name=
"operator()" cv=
"const">
243 <type>std::size_t
</type>
244 <parameter name=
"val">
245 <paramtype>long
</paramtype>
248 <para>Unspecified in TR1, except that equal arguments yield the same result.
</para>
249 <para><functionname>hash_value
</functionname>(val) in Boost.
</para>
251 <throws><para>Doesn't throw
</para></throws>
253 </struct-specialization>
255 <struct-specialization name=
"hash">
256 <template></template>
258 <template-arg>unsigned long
</template-arg>
260 <method name=
"operator()" cv=
"const">
261 <type>std::size_t
</type>
262 <parameter name=
"val">
263 <paramtype>unsigned long
</paramtype>
266 <para>Unspecified in TR1, except that equal arguments yield the same result.
</para>
267 <para><functionname>hash_value
</functionname>(val) in Boost.
</para>
269 <throws><para>Doesn't throw
</para></throws>
271 </struct-specialization>
273 <struct-specialization name=
"hash">
274 <template></template>
276 <template-arg>long long
</template-arg>
278 <method name=
"operator()" cv=
"const">
279 <type>std::size_t
</type>
280 <parameter name=
"val">
281 <paramtype>long long
</paramtype>
284 <para>Unspecified in TR1, except that equal arguments yield the same result.
</para>
285 <para><functionname>hash_value
</functionname>(val) in Boost.
</para>
287 <throws><para>Doesn't throw
</para></throws>
289 </struct-specialization>
291 <struct-specialization name=
"hash">
292 <template></template>
294 <template-arg>unsigned long long
</template-arg>
296 <method name=
"operator()" cv=
"const">
297 <type>std::size_t
</type>
298 <parameter name=
"val">
299 <paramtype>unsigned long long
</paramtype>
302 <para>Unspecified in TR1, except that equal arguments yield the same result.
</para>
303 <para><functionname>hash_value
</functionname>(val) in Boost.
</para>
305 <throws><para>Doesn't throw
</para></throws>
307 </struct-specialization>
309 <struct-specialization name=
"hash">
310 <template></template>
312 <template-arg>float
</template-arg>
314 <method name=
"operator()" cv=
"const">
315 <type>std::size_t
</type>
316 <parameter name=
"val">
317 <paramtype>float
</paramtype>
320 <para>Unspecified in TR1, except that equal arguments yield the same result.
</para>
321 <para><functionname>hash_value
</functionname>(val) in Boost.
</para>
323 <throws><para>Doesn't throw
</para></throws>
325 </struct-specialization>
327 <struct-specialization name=
"hash">
328 <template></template>
330 <template-arg>double
</template-arg>
332 <method name=
"operator()" cv=
"const">
333 <type>std::size_t
</type>
334 <parameter name=
"val">
335 <paramtype>double
</paramtype>
338 <para>Unspecified in TR1, except that equal arguments yield the same result.
</para>
339 <para><functionname>hash_value
</functionname>(val) in Boost.
</para>
341 <throws><para>Doesn't throw
</para></throws>
343 </struct-specialization>
345 <struct-specialization name=
"hash">
346 <template></template>
348 <template-arg>long double
</template-arg>
350 <method name=
"operator()" cv=
"const">
351 <type>std::size_t
</type>
352 <parameter name=
"val">
353 <paramtype>long double
</paramtype>
356 <para>Unspecified in TR1, except that equal arguments yield the same result.
</para>
357 <para><functionname>hash_value
</functionname>(val) in Boost.
</para>
359 <throws><para>Doesn't throw
</para></throws>
361 </struct-specialization>
363 <struct-specialization name=
"hash">
364 <template></template>
366 <template-arg>std::string
</template-arg>
368 <method name=
"operator()" cv=
"const">
369 <type>std::size_t
</type>
370 <parameter name=
"val">
371 <paramtype>std::string const
&</paramtype>
374 <para>Unspecified in TR1, except that equal arguments yield the same result.
</para>
375 <para><functionname>hash_value
</functionname>(val) in Boost.
</para>
377 <throws><para>Doesn't throw
</para></throws>
379 </struct-specialization>
381 <struct-specialization name=
"hash">
382 <template></template>
384 <template-arg>std::wstring
</template-arg>
386 <method name=
"operator()" cv=
"const">
387 <type>std::size_t
</type>
388 <parameter name=
"val">
389 <paramtype>std::wstring const
&</paramtype>
392 <para>Unspecified in TR1, except that equal arguments yield the same result.
</para>
393 <para><functionname>hash_value
</functionname>(val) in Boost.
</para>
395 <throws><para>Doesn't throw
</para></throws>
397 </struct-specialization>
399 <struct-specialization name=
"hash">
401 <template-type-parameter name=
"T"/>
404 <template-arg>T*
</template-arg>
406 <method name=
"operator()" cv=
"const">
407 <type>std::size_t
</type>
408 <parameter name=
"val">
409 <paramtype>T*
</paramtype>
412 <para>Unspecified in TR1, except that equal arguments yield the same result.
</para>
414 <throws><para>Doesn't throw
</para></throws>
416 </struct-specialization>
418 <struct-specialization name=
"hash">
419 <template></template>
421 <template-arg>std::type_index
</template-arg>
423 <method name=
"operator()" cv=
"const">
424 <type>std::size_t
</type>
425 <parameter name=
"val">
426 <paramtype>std::type_index
</paramtype>
429 <para><code>val.hash_code()
</code></para>
431 <throws><para>Doesn't throw
</para></throws>
435 Only available if it's in your standard library and Boost.Config
439 </struct-specialization>
441 <free-function-group name=
"Support functions (Boost extension).">
447 <function name=
"hash_combine">
449 <template-type-parameter name=
"T"/>
452 <parameter name=
"seed"><paramtype>size_t
&</paramtype></parameter>
453 <parameter name=
"v"><paramtype>T const
&</paramtype></parameter>
455 Called repeatedly to incrementally create a hash value from
459 Updates
<code>seed
</code> with a new hash value generated by
460 combining it with the result of
461 <code><functionname>hash_value
</functionname>(v)
</code>. Will
462 always produce the same result for the same combination of
463 <code>seed
</code> and
464 <code><functionname>hash_value
</functionname>(v)
</code> during
465 the single run of a program.
468 <para><functionname>hash_value
</functionname> is called without
469 qualification, so that overloads can be found via ADL.
</para>
470 <para>This is an extension to TR1
</para>
473 <code><boost/functional/hash_fwd.hpp
></code>
476 This hash function is not intended for general use, and isn't
477 guaranteed to be equal during separate runs of a program - so
478 please don't use it for any persistent storage or communication.
482 Only throws if
<functionname>hash_value
</functionname>(T) throws.
483 Strong exception safety, as long as
<functionname>hash_value
</functionname>(T)
484 also has strong exception safety.
492 <overloaded-function name=
"hash_range">
495 <template-type-parameter name=
"It"/>
497 <type>std::size_t
</type>
498 <parameter name=
"first"><paramtype>It
</paramtype></parameter>
499 <parameter name=
"last"><paramtype>It
</paramtype></parameter>
504 <template-type-parameter name=
"It"/>
507 <parameter name=
"seed"><paramtype>std::size_t
&</paramtype></parameter>
508 <parameter name=
"first"><paramtype>It
</paramtype></parameter>
509 <parameter name=
"last"><paramtype>It
</paramtype></parameter>
513 Calculate the combined hash value of the elements of an iterator
517 <para>For the two argument overload:
521 for(; first != last; ++first)
523 <functionname>hash_combine
</functionname>(seed, *first);
529 <para>For the three arguments overload:
</para>
531 for(; first != last; ++first)
533 <functionname>hash_combine
</functionname>(seed, *first);
539 <code>hash_range
</code> is sensitive to the order of the elements
540 so it wouldn't be appropriate to use this with an unordered
543 <para>This is an extension to TR1
</para>
546 <code><boost/functional/hash_fwd.hpp
></code>
549 This hash function is not intended for general use, and isn't
550 guaranteed to be equal during separate runs of a program - so
551 please don't use it for any persistent storage or communication.
555 Only throws if
<code><functionname>hash_value
</functionname>(std::iterator_traits
<It
>::value_type)
</code>
556 throws.
<code>hash_range(std::size_t
&, It, It)
</code> has basic exception safety as long as
557 <code><functionname>hash_value
</functionname>(std::iterator_traits
<It
>::value_type)
</code>
558 has basic exception safety.
560 </overloaded-function>
562 </free-function-group>
564 <free-function-group name=
"Overloadable hash implementation (Boost extension).">
567 boost::hash_value - integers
570 <overloaded-function name=
"hash_value">
572 Implementation of the hash function.
576 <type>std::size_t
</type>
577 <parameter name=
"val"><paramtype>bool
</paramtype></parameter>
581 <type>std::size_t
</type>
582 <parameter name=
"val"><paramtype>char
</paramtype></parameter>
586 <type>std::size_t
</type>
587 <parameter name=
"val"><paramtype>signed char
</paramtype></parameter>
591 <type>std::size_t
</type>
592 <parameter name=
"val"><paramtype>unsigned char
</paramtype></parameter>
596 <type>std::size_t
</type>
597 <parameter name=
"val"><paramtype>wchar_t
</paramtype></parameter>
601 <type>std::size_t
</type>
602 <parameter name=
"val"><paramtype>short
</paramtype></parameter>
606 <type>std::size_t
</type>
607 <parameter name=
"val"><paramtype>unsigned short
</paramtype></parameter>
611 <type>std::size_t
</type>
612 <parameter name=
"val"><paramtype>int
</paramtype></parameter>
616 <type>std::size_t
</type>
617 <parameter name=
"val"><paramtype>unsigned int
</paramtype></parameter>
621 <type>std::size_t
</type>
622 <parameter name=
"val"><paramtype>long
</paramtype></parameter>
626 <type>std::size_t
</type>
627 <parameter name=
"val"><paramtype>unsigned long
</paramtype></parameter>
631 <type>std::size_t
</type>
632 <parameter name=
"val"><paramtype>long long
</paramtype></parameter>
636 <type>std::size_t
</type>
637 <parameter name=
"val"><paramtype>unsigned long long
</paramtype></parameter>
641 <type>std::size_t
</type>
642 <parameter name=
"val"><paramtype>float
</paramtype></parameter>
646 <type>std::size_t
</type>
647 <parameter name=
"val"><paramtype>double
</paramtype></parameter>
651 <type>std::size_t
</type>
652 <parameter name=
"val"><paramtype>long double
</paramtype></parameter>
656 <template><template-type-parameter name=
"T"/></template>
657 <type>std::size_t
</type>
658 <parameter name=
"val"><paramtype>T* const
&</paramtype></parameter>
663 <template-type-parameter name=
"T"/>
664 <template-nontype-parameter name=
"N"><type>unsigned
</type></template-nontype-parameter>
666 <type>std::size_t
</type>
667 <parameter><paramtype>T (
&val)[N]
</paramtype></parameter>
672 <template-type-parameter name=
"T"/>
673 <template-nontype-parameter name=
"N"><type>unsigned
</type></template-nontype-parameter>
675 <type>std::size_t
</type>
676 <parameter><paramtype>const T (
&val)[N]
</paramtype></parameter>
681 <template-type-parameter name=
"Ch"/>
682 <template-type-parameter name=
"A"/>
684 <type>std::size_t
</type>
685 <parameter name=
"val">
686 <paramtype>std::basic_string
<Ch, std::char_traits
<Ch
>, A
> const
&</paramtype>
692 <template-type-parameter name=
"A"/>
693 <template-type-parameter name=
"B"/>
695 <type>std::size_t
</type>
696 <parameter name=
"val"><paramtype>std::pair
<A, B
> const
&</paramtype></parameter>
701 <template-type-parameter name=
"T"/>
702 <template-type-parameter name=
"A"/>
704 <type>std::size_t
</type>
705 <parameter name=
"val"><paramtype>std::vector
<T, A
> const
&</paramtype></parameter>
710 <template-type-parameter name=
"T"/>
711 <template-type-parameter name=
"A"/>
713 <type>std::size_t
</type>
714 <parameter name=
"val"><paramtype>std::list
<T, A
> const
&</paramtype></parameter>
719 <template-type-parameter name=
"T"/>
720 <template-type-parameter name=
"A"/>
722 <type>std::size_t
</type>
723 <parameter name=
"val"><paramtype>std::deque
<T, A
> const
&</paramtype></parameter>
728 <template-type-parameter name=
"K"/>
729 <template-type-parameter name=
"C"/>
730 <template-type-parameter name=
"A"/>
732 <type>std::size_t
</type>
733 <parameter name=
"val"><paramtype>std::set
<K, C, A
> const
&</paramtype></parameter>
738 <template-type-parameter name=
"K"/>
739 <template-type-parameter name=
"C"/>
740 <template-type-parameter name=
"A"/>
742 <type>std::size_t
</type>
743 <parameter name=
"val"><paramtype>std::multiset
<K, C, A
> const
&</paramtype></parameter>
748 <template-type-parameter name=
"K"/>
749 <template-type-parameter name=
"T"/>
750 <template-type-parameter name=
"C"/>
751 <template-type-parameter name=
"A"/>
753 <type>std::size_t
</type>
754 <parameter name=
"val"><paramtype>std::map
<K, T, C, A
> const
&</paramtype></parameter>
759 <template-type-parameter name=
"K"/>
760 <template-type-parameter name=
"T"/>
761 <template-type-parameter name=
"C"/>
762 <template-type-parameter name=
"A"/>
764 <type>std::size_t
</type>
765 <parameter name=
"val"><paramtype>std::multimap
<K, T, C, A
> const
&</paramtype></parameter>
770 <template-type-parameter name=
"T"/>
772 <type>std::size_t
</type>
773 <parameter name=
"val"><paramtype>std::complex
<T
> const
&</paramtype></parameter>
777 <type>std::size_t
</type>
778 <parameter name=
"val"><paramtype>std::type_index
</paramtype></parameter>
783 <template-type-parameter name=
"T"/>
784 <template-nontype-parameter name=
"N">
785 <type>std::size_t
</type>
786 </template-nontype-parameter>
788 <type>std::size_t
</type>
789 <parameter name=
"val"><paramtype>std::array
<T, N
> const
&</paramtype></parameter>
794 <template-type-parameter name=
"T" pack=
"1"/>
796 <type>std::size_t
</type>
797 <parameter name=
"val"><paramtype>std::tuple
<T...
></paramtype></parameter>
801 Generally shouldn't be called directly by users, instead they should use
802 <classname>boost::hash
</classname>,
<functionname>boost::hash_range
</functionname>
803 or
<functionname>boost::hash_combine
</functionname> which
804 call
<code>hash_value
</code> without namespace qualification so that overloads
805 for custom types are found via ADL.
806 </para></description>
809 <para>This is an extension to TR1
</para>
811 This hash function is not intended for general use, and isn't
812 guaranteed to be equal during separate runs of a program - so
813 please don't use it for any persistent storage or communication.
818 Only throws if a user supplied version of
819 <code><functionname>hash_value
</functionname></code>
820 throws for an element of a container, or
821 one of the types stored in a pair.
830 <entry>Returns
</entry>
835 <entry><code>bool
</code>,
836 <code>char
</code>,
<code>signed char
</code>,
<code>unsigned char
</code>,
<code>wchar_t
</code>,
837 <code>short
</code>,
<code>unsigned short
</code>,
838 <code>int
</code>,
<code>unsigned int
</code>,
<code>long
</code>,
<code>unsigned long
</code>
840 <entry><code>val
</code></entry>
843 <entry><code>long long
</code>,
<code>unsigned long long
</code></entry>
844 <entry><code>val
</code> when
<code>abs(val)
<= std::numeric_limits
<std::size_t
>::max()
</code>.
</entry>
847 <entry><code>float
</code>,
<code>double
</code>,
<code>long double
</code></entry>
848 <entry>An unspecified value, except that equal arguments shall yield the same result.
</entry>
851 <entry><code>T*
</code></entry>
852 <entry>An unspecified value, except that equal arguments shall yield the same result.
</entry>
856 <code>T
 val[N]
</code>,
857 <code>const
 T
 val[N]
</code>
859 <entry><code>hash_range(val, val+N)
</code></entry>
863 <code>std:basic_string
<Ch,
 std::char_traits
<Ch
>,
 A
></code>,
864 <code>std::vector
<T,
 A
></code>,
865 <code>std::list
<T,
 A
></code>,
866 <code>std::deque
<T,
 A
></code>,
867 <code>std::set
<K,
 C,
 A
></code>,
868 <code>std::multiset
<K,
 C,
 A
></code>,
869 <code>std::map
<K,
 T,
 C,
 A
></code>,
870 <code>std::multimap
<K,
 T,
 C,
 A
></code>,
871 <code>std::array
<T,
 N
></code>
873 <entry><code>hash_range(val.begin(), val.end())
</code></entry>
876 <entry><code>std::pair
<A, B
></code></entry>
877 <entry><programlisting>size_t seed =
0;
878 <functionname>hash_combine
</functionname>(seed, val.first);
879 <functionname>hash_combine
</functionname>(seed, val.second);
880 return seed;
</programlisting></entry>
883 <entry><code>std::tuple
<T...
></code></entry>
884 <entry><programlisting>size_t seed =
0;
885 <functionname>hash_combine
</functionname>(seed, get
<0>(val));
886 <functionname>hash_combine
</functionname>(seed, get
<1>(val));
888 return seed;
</programlisting></entry>
892 <code>std::complex
<T
></code>
894 <entry>When
<code>T
</code> is a built in type and
<code>val.imag() ==
0</code>, the result is equal to
<code>hash_value(val.real())
</code>. Otherwise an unspecified value, except that equal arguments shall yield the same result.
</entry>
898 <code>std::type_index
</code>
900 <entry><code>val.hash_code()
</code></entry>
906 </overloaded-function>
907 </free-function-group>