Gitiles
Code Review Sign In
realtimeroboticsgroup.org / RealtimeRoboticsGroup / test / b67fe793c1214003b55d8c0bbcfc8dbc86d8bf26 / . / doc / ref.xml
blob: 1c8bca9ac4f8adeee50ed44f64a95fbe31e7d9a2 [file] [log] [blame]
Brian Silvermanb67fe792018-08-05 00:11:17 -0700[diff] [blame^]1
2<!--
3Copyright Daniel James 2005-2009
4Distributed under the Boost Software License, Version 1.0. (See accompanying
5file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6-->
7
8<library-reference>
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>
12 and issue 6.18 of the
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).
14 </para>
15 </section>
16 <header name="boost/container_hash/hash.hpp">
17 <para>
18 Defines <code><classname>boost::hash</classname></code>,
19 and helper functions.
20 </para>
21
22 <namespace name="boost">
23
24 <!--
25 boost::hash
26 -->
27
28 <struct name="hash">
29 <template>
30 <template-type-parameter name="T"/>
31 </template>
32
33 <inherit access="public">
34 <classname>std::unary_function&lt;T, std::size_t&gt;</classname>
35 </inherit>
36
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>
38
39 <method name="operator()" cv="const">
40 <type>std::size_t</type>
41 <parameter name="val">
42 <paramtype>T const&amp;</paramtype>
43 </parameter>
44 <returns><para>
45 <programlisting><functionname>hash_value</functionname>(val)</programlisting>
46 </para></returns>
47 <notes>
48 <para>
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.
52 </para>
53 <para>
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.
57 </para>
58 <para>
59 Forward declared in
60 <code>&lt;boost/container_hash/hash_fwd.hpp&gt;</code>
61 </para>
62 <para>
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.
66 </para>
67 </notes>
68 <throws><para>
69 Only throws if
70 <code><functionname>hash_value</functionname>(T)</code> throws.
71 </para></throws>
72 </method>
73 </struct>
74
75 <struct-specialization name="hash">
76 <template></template>
77 <specialization>
78 <template-arg>bool</template-arg>
79 </specialization>
80 <method name="operator()" cv="const">
81 <type>std::size_t</type>
82 <parameter name="val">
83 <paramtype>bool</paramtype>
84 </parameter>
85 <returns>
86 <para>Unspecified in TR1, except that equal arguments yield the same result.</para>
87 <para><functionname>hash_value</functionname>(val) in Boost.</para>
88 </returns>
89 <throws><para>Doesn't throw</para></throws>
90 </method>
91 </struct-specialization>
92
93 <struct-specialization name="hash">
94 <template></template>
95 <specialization>
96 <template-arg>char</template-arg>
97 </specialization>
98 <method name="operator()" cv="const">
99 <type>std::size_t</type>
100 <parameter name="val">
101 <paramtype>char</paramtype>
102 </parameter>
103 <returns>
104 <para>Unspecified in TR1, except that equal arguments yield the same result.</para>
105 <para><functionname>hash_value</functionname>(val) in Boost.</para>
106 </returns>
107 <throws><para>Doesn't throw</para></throws>
108 </method>
109 </struct-specialization>
110
111 <struct-specialization name="hash">
112 <template></template>
113 <specialization>
114 <template-arg>signed char</template-arg>
115 </specialization>
116 <method name="operator()" cv="const">
117 <type>std::size_t</type>
118 <parameter name="val">
119 <paramtype>signed char</paramtype>
120 </parameter>
121 <returns>
122 <para>Unspecified in TR1, except that equal arguments yield the same result.</para>
123 <para><functionname>hash_value</functionname>(val) in Boost.</para>
124 </returns>
125 <throws><para>Doesn't throw</para></throws>
126 </method>
127 </struct-specialization>
128
129 <struct-specialization name="hash">
130 <template></template>
131 <specialization>
132 <template-arg>unsigned char</template-arg>
133 </specialization>
134 <method name="operator()" cv="const">
135 <type>std::size_t</type>
136 <parameter name="val">
137 <paramtype>unsigned char</paramtype>
138 </parameter>
139 <returns>
140 <para>Unspecified in TR1, except that equal arguments yield the same result.</para>
141 <para><functionname>hash_value</functionname>(val) in Boost.</para>
142 </returns>
143 <throws><para>Doesn't throw</para></throws>
144 </method>
145 </struct-specialization>
146
147 <struct-specialization name="hash">
148 <template></template>
149 <specialization>
150 <template-arg>wchar_t</template-arg>
151 </specialization>
152 <method name="operator()" cv="const">
153 <type>std::size_t</type>
154 <parameter name="val">
155 <paramtype>wchar_t</paramtype>
156 </parameter>
157 <returns>
158 <para>Unspecified in TR1, except that equal arguments yield the same result.</para>
159 <para><functionname>hash_value</functionname>(val) in Boost.</para>
160 </returns>
161 <throws><para>Doesn't throw</para></throws>
162 </method>
163 </struct-specialization>
164
165 <struct-specialization name="hash">
166 <template></template>
167 <specialization>
168 <template-arg>char16_t</template-arg>
169 </specialization>
170 <method name="operator()" cv="const">
171 <type>std::size_t</type>
172 <parameter name="val">
173 <paramtype>char16_t</paramtype>
174 </parameter>
175 <returns>
176 <para>Unspecified in TR1, except that equal arguments yield the same result.</para>
177 <para><functionname>hash_value</functionname>(val) in Boost.</para>
178 </returns>
179 <throws><para>Doesn't throw</para></throws>
180 </method>
181 </struct-specialization>
182
183 <struct-specialization name="hash">
184 <template></template>
185 <specialization>
186 <template-arg>char32_t</template-arg>
187 </specialization>
188 <method name="operator()" cv="const">
189 <type>std::size_t</type>
190 <parameter name="val">
191 <paramtype>char32_t</paramtype>
192 </parameter>
193 <returns>
194 <para>Unspecified in TR1, except that equal arguments yield the same result.</para>
195 <para><functionname>hash_value</functionname>(val) in Boost.</para>
196 </returns>
197 <throws><para>Doesn't throw</para></throws>
198 </method>
199 </struct-specialization>
200
201 <struct-specialization name="hash">
202 <template></template>
203 <specialization>
204 <template-arg>short</template-arg>
205 </specialization>
206 <method name="operator()" cv="const">
207 <type>std::size_t</type>
208 <parameter name="val">
209 <paramtype>short</paramtype>
210 </parameter>
211 <returns>
212 <para>Unspecified in TR1, except that equal arguments yield the same result.</para>
213 <para><functionname>hash_value</functionname>(val) in Boost.</para>
214 </returns>
215 <throws><para>Doesn't throw</para></throws>
216 </method>
217 </struct-specialization>
218
219 <struct-specialization name="hash">
220 <template></template>
221 <specialization>
222 <template-arg>unsigned short</template-arg>
223 </specialization>
224 <method name="operator()" cv="const">
225 <type>std::size_t</type>
226 <parameter name="val">
227 <paramtype>unsigned short</paramtype>
228 </parameter>
229 <returns>
230 <para>Unspecified in TR1, except that equal arguments yield the same result.</para>
231 <para><functionname>hash_value</functionname>(val) in Boost.</para>
232 </returns>
233 <throws><para>Doesn't throw</para></throws>
234 </method>
235 </struct-specialization>
236
237 <struct-specialization name="hash">
238 <template></template>
239 <specialization>
240 <template-arg>int</template-arg>
241 </specialization>
242 <method name="operator()" cv="const">
243 <type>std::size_t</type>
244 <parameter name="val">
245 <paramtype>int</paramtype>
246 </parameter>
247 <returns>
248 <para>Unspecified in TR1, except that equal arguments yield the same result.</para>
249 <para><functionname>hash_value</functionname>(val) in Boost.</para>
250 </returns>
251 <throws><para>Doesn't throw</para></throws>
252 </method>
253 </struct-specialization>
254
255 <struct-specialization name="hash">
256 <template></template>
257 <specialization>
258 <template-arg>unsigned int</template-arg>
259 </specialization>
260 <method name="operator()" cv="const">
261 <type>std::size_t</type>
262 <parameter name="val">
263 <paramtype>unsigned int</paramtype>
264 </parameter>
265 <returns>
266 <para>Unspecified in TR1, except that equal arguments yield the same result.</para>
267 <para><functionname>hash_value</functionname>(val) in Boost.</para>
268 </returns>
269 <throws><para>Doesn't throw</para></throws>
270 </method>
271 </struct-specialization>
272
273 <struct-specialization name="hash">
274 <template></template>
275 <specialization>
276 <template-arg>long</template-arg>
277 </specialization>
278 <method name="operator()" cv="const">
279 <type>std::size_t</type>
280 <parameter name="val">
281 <paramtype>long</paramtype>
282 </parameter>
283 <returns>
284 <para>Unspecified in TR1, except that equal arguments yield the same result.</para>
285 <para><functionname>hash_value</functionname>(val) in Boost.</para>
286 </returns>
287 <throws><para>Doesn't throw</para></throws>
288 </method>
289 </struct-specialization>
290
291 <struct-specialization name="hash">
292 <template></template>
293 <specialization>
294 <template-arg>unsigned long</template-arg>
295 </specialization>
296 <method name="operator()" cv="const">
297 <type>std::size_t</type>
298 <parameter name="val">
299 <paramtype>unsigned long</paramtype>
300 </parameter>
301 <returns>
302 <para>Unspecified in TR1, except that equal arguments yield the same result.</para>
303 <para><functionname>hash_value</functionname>(val) in Boost.</para>
304 </returns>
305 <throws><para>Doesn't throw</para></throws>
306 </method>
307 </struct-specialization>
308
309 <struct-specialization name="hash">
310 <template></template>
311 <specialization>
312 <template-arg>long long</template-arg>
313 </specialization>
314 <method name="operator()" cv="const">
315 <type>std::size_t</type>
316 <parameter name="val">
317 <paramtype>long long</paramtype>
318 </parameter>
319 <returns>
320 <para>Unspecified in TR1, except that equal arguments yield the same result.</para>
321 <para><functionname>hash_value</functionname>(val) in Boost.</para>
322 </returns>
323 <throws><para>Doesn't throw</para></throws>
324 </method>
325 </struct-specialization>
326
327 <struct-specialization name="hash">
328 <template></template>
329 <specialization>
330 <template-arg>unsigned long long</template-arg>
331 </specialization>
332 <method name="operator()" cv="const">
333 <type>std::size_t</type>
334 <parameter name="val">
335 <paramtype>unsigned long long</paramtype>
336 </parameter>
337 <returns>
338 <para>Unspecified in TR1, except that equal arguments yield the same result.</para>
339 <para><functionname>hash_value</functionname>(val) in Boost.</para>
340 </returns>
341 <throws><para>Doesn't throw</para></throws>
342 </method>
343 </struct-specialization>
344
345 <struct-specialization name="hash">
346 <template></template>
347 <specialization>
348 <template-arg>float</template-arg>
349 </specialization>
350 <method name="operator()" cv="const">
351 <type>std::size_t</type>
352 <parameter name="val">
353 <paramtype>float</paramtype>
354 </parameter>
355 <returns>
356 <para>Unspecified in TR1, except that equal arguments yield the same result.</para>
357 <para><functionname>hash_value</functionname>(val) in Boost.</para>
358 </returns>
359 <throws><para>Doesn't throw</para></throws>
360 </method>
361 </struct-specialization>
362
363 <struct-specialization name="hash">
364 <template></template>
365 <specialization>
366 <template-arg>double</template-arg>
367 </specialization>
368 <method name="operator()" cv="const">
369 <type>std::size_t</type>
370 <parameter name="val">
371 <paramtype>double</paramtype>
372 </parameter>
373 <returns>
374 <para>Unspecified in TR1, except that equal arguments yield the same result.</para>
375 <para><functionname>hash_value</functionname>(val) in Boost.</para>
376 </returns>
377 <throws><para>Doesn't throw</para></throws>
378 </method>
379 </struct-specialization>
380
381 <struct-specialization name="hash">
382 <template></template>
383 <specialization>
384 <template-arg>long double</template-arg>
385 </specialization>
386 <method name="operator()" cv="const">
387 <type>std::size_t</type>
388 <parameter name="val">
389 <paramtype>long double</paramtype>
390 </parameter>
391 <returns>
392 <para>Unspecified in TR1, except that equal arguments yield the same result.</para>
393 <para><functionname>hash_value</functionname>(val) in Boost.</para>
394 </returns>
395 <throws><para>Doesn't throw</para></throws>
396 </method>
397 </struct-specialization>
398
399 <struct-specialization name="hash">
400 <template></template>
401 <specialization>
402 <template-arg>std::string</template-arg>
403 </specialization>
404 <method name="operator()" cv="const">
405 <type>std::size_t</type>
406 <parameter name="val">
407 <paramtype>std::string const&amp;</paramtype>
408 </parameter>
409 <returns>
410 <para>Unspecified in TR1, except that equal arguments yield the same result.</para>
411 <para><functionname>hash_value</functionname>(val) in Boost.</para>
412 </returns>
413 <throws><para>Doesn't throw</para></throws>
414 </method>
415 </struct-specialization>
416
417 <struct-specialization name="hash">
418 <template></template>
419 <specialization>
420 <template-arg>std::wstring</template-arg>
421 </specialization>
422 <method name="operator()" cv="const">
423 <type>std::size_t</type>
424 <parameter name="val">
425 <paramtype>std::wstring const&amp;</paramtype>
426 </parameter>
427 <returns>
428 <para>Unspecified in TR1, except that equal arguments yield the same result.</para>
429 <para><functionname>hash_value</functionname>(val) in Boost.</para>
430 </returns>
431 <throws><para>Doesn't throw</para></throws>
432 </method>
433 </struct-specialization>
434
435 <struct-specialization name="hash">
436 <template></template>
437 <specialization>
438 <template-arg>std::u16string</template-arg>
439 </specialization>
440 <method name="operator()" cv="const">
441 <type>std::size_t</type>
442 <parameter name="val">
443 <paramtype>std::u16string const&amp;</paramtype>
444 </parameter>
445 <returns>
446 <para>Unspecified in TR1, except that equal arguments yield the same result.</para>
447 <para><functionname>hash_value</functionname>(val) in Boost.</para>
448 </returns>
449 <throws><para>Doesn't throw</para></throws>
450 </method>
451 </struct-specialization>
452
453 <struct-specialization name="hash">
454 <template></template>
455 <specialization>
456 <template-arg>std::u32string</template-arg>
457 </specialization>
458 <method name="operator()" cv="const">
459 <type>std::size_t</type>
460 <parameter name="val">
461 <paramtype>std::u32string const&amp;</paramtype>
462 </parameter>
463 <returns>
464 <para>Unspecified in TR1, except that equal arguments yield the same result.</para>
465 <para><functionname>hash_value</functionname>(val) in Boost.</para>
466 </returns>
467 <throws><para>Doesn't throw</para></throws>
468 </method>
469 </struct-specialization>
470
471 <struct-specialization name="hash">
472 <template>
473 <template-type-parameter name="T"/>
474 </template>
475 <specialization>
476 <template-arg>T*</template-arg>
477 </specialization>
478 <method name="operator()" cv="const">
479 <type>std::size_t</type>
480 <parameter name="val">
481 <paramtype>T*</paramtype>
482 </parameter>
483 <returns>
484 <para>Unspecified in TR1, except that equal arguments yield the same result.</para>
485 </returns>
486 <throws><para>Doesn't throw</para></throws>
487 </method>
488 </struct-specialization>
489
490 <struct-specialization name="hash">
491 <template></template>
492 <specialization>
493 <template-arg>std::type_index</template-arg>
494 </specialization>
495 <method name="operator()" cv="const">
496 <type>std::size_t</type>
497 <parameter name="val">
498 <paramtype>std::type_index</paramtype>
499 </parameter>
500 <returns>
501 <para><code>val.hash_code()</code></para>
502 </returns>
503 <throws><para>Doesn't throw</para></throws>
504 </method>
505 <notes>
506 <para>
507 Only available if it's in your standard library and Boost.Config
508 is aware of it.
509 </para>
510 </notes>
511 </struct-specialization>
512
513 <free-function-group name="Support functions (Boost extension).">
514
515 <!--
516 boost::hash_combine
517 -->
518
519 <function name="hash_combine">
520 <template>
521 <template-type-parameter name="T"/>
522 </template>
523 <type>void</type>
524 <parameter name="seed"><paramtype>size_t &amp;</paramtype></parameter>
525 <parameter name="v"><paramtype>T const&amp;</paramtype></parameter>
526 <purpose><simpara>
527 Called repeatedly to incrementally create a hash value from
528 several variables.
529 </simpara></purpose>
530 <effects>
531 Updates <code>seed</code> with a new hash value generated by
532 combining it with the result of
533 <code><functionname>hash_value</functionname>(v)</code>. Will
534 always produce the same result for the same combination of
535 <code>seed</code> and
536 <code><functionname>hash_value</functionname>(v)</code> during
537 the single run of a program.
538 </effects>
539 <notes>
540 <para><functionname>hash_value</functionname> is called without
541 qualification, so that overloads can be found via ADL.</para>
542 <para>This is an extension to TR1</para>
543 <para>
544 Forward declared in
545 <code>&lt;boost/container_hash/hash_fwd.hpp&gt;</code>
546 </para>
547 <para>
548 This hash function is not intended for general use, and isn't
549 guaranteed to be equal during separate runs of a program - so
550 please don't use it for any persistent storage or communication.
551 </para>
552 </notes>
553 <throws>
554 Only throws if <functionname>hash_value</functionname>(T) throws.
555 Strong exception safety, as long as <functionname>hash_value</functionname>(T)
556 also has strong exception safety.
557 </throws>
558 </function>
559
560 <!--
561 boost::hash_range
562 -->
563
564 <overloaded-function name="hash_range">
565 <signature>
566 <template>
567 <template-type-parameter name="It"/>
568 </template>
569 <type>std::size_t</type>
570 <parameter name="first"><paramtype>It</paramtype></parameter>
571 <parameter name="last"><paramtype>It</paramtype></parameter>
572 </signature>
573
574 <signature>
575 <template>
576 <template-type-parameter name="It"/>
577 </template>
578 <type>void</type>
579 <parameter name="seed"><paramtype>std::size_t&amp;</paramtype></parameter>
580 <parameter name="first"><paramtype>It</paramtype></parameter>
581 <parameter name="last"><paramtype>It</paramtype></parameter>
582 </signature>
583
584 <purpose><simpara>
585 Calculate the combined hash value of the elements of an iterator
586 range.
587 </simpara></purpose>
588 <effects>
589 <para>For the two argument overload:
590<programlisting>
591size_t seed = 0;
592
593for(; first != last; ++first)
594{
595 <functionname>hash_combine</functionname>(seed, *first);
596}
597
598return seed;
599</programlisting>
600 </para>
601 <para>For the three arguments overload:</para>
602<programlisting>
603for(; first != last; ++first)
604{
605 <functionname>hash_combine</functionname>(seed, *first);
606}
607</programlisting>
608 </effects>
609 <notes>
610 <para>
611 <code>hash_range</code> is sensitive to the order of the elements
612 so it wouldn't be appropriate to use this with an unordered
613 container.
614 </para>
615 <para>This is an extension to TR1</para>
616 <para>
617 Forward declared in
618 <code>&lt;boost/container_hash/hash_fwd.hpp&gt;</code>
619 </para>
620 <para>
621 This hash function is not intended for general use, and isn't
622 guaranteed to be equal during separate runs of a program - so
623 please don't use it for any persistent storage or communication.
624 </para>
625 </notes>
626 <throws><para>
627 Only throws if <code><functionname>hash_value</functionname>(std::iterator_traits&lt;It&gt;::value_type)</code>
628 throws. <code>hash_range(std::size_t&amp;, It, It)</code> has basic exception safety as long as
629 <code><functionname>hash_value</functionname>(std::iterator_traits&lt;It&gt;::value_type)</code>
630 has basic exception safety.
631 </para></throws>
632 </overloaded-function>
633
634 </free-function-group>
635
636 <free-function-group name="Overloadable hash implementation (Boost extension).">
637
638 <!--
639 boost::hash_value - integers
640 -->
641
642 <overloaded-function name="hash_value">
643 <purpose><simpara>
644 Implementation of the hash function.
645 </simpara></purpose>
646
647 <signature>
648 <type>std::size_t</type>
649 <parameter name="val"><paramtype>bool</paramtype></parameter>
650 </signature>
651
652 <signature>
653 <type>std::size_t</type>
654 <parameter name="val"><paramtype>char</paramtype></parameter>
655 </signature>
656
657 <signature>
658 <type>std::size_t</type>
659 <parameter name="val"><paramtype>signed char</paramtype></parameter>
660 </signature>
661
662 <signature>
663 <type>std::size_t</type>
664 <parameter name="val"><paramtype>unsigned char</paramtype></parameter>
665 </signature>
666
667 <signature>
668 <type>std::size_t</type>
669 <parameter name="val"><paramtype>wchar_t</paramtype></parameter>
670 </signature>
671
672 <signature>
673 <type>std::size_t</type>
674 <parameter name="val"><paramtype>char16_t</paramtype></parameter>
675 </signature>
676
677 <signature>
678 <type>std::size_t</type>
679 <parameter name="val"><paramtype>char32_t</paramtype></parameter>
680 </signature>
681
682 <signature>
683 <type>std::size_t</type>
684 <parameter name="val"><paramtype>short</paramtype></parameter>
685 </signature>
686
687 <signature>
688 <type>std::size_t</type>
689 <parameter name="val"><paramtype>unsigned short</paramtype></parameter>
690 </signature>
691
692 <signature>
693 <type>std::size_t</type>
694 <parameter name="val"><paramtype>int</paramtype></parameter>
695 </signature>
696
697 <signature>
698 <type>std::size_t</type>
699 <parameter name="val"><paramtype>unsigned int</paramtype></parameter>
700 </signature>
701
702 <signature>
703 <type>std::size_t</type>
704 <parameter name="val"><paramtype>long</paramtype></parameter>
705 </signature>
706
707 <signature>
708 <type>std::size_t</type>
709 <parameter name="val"><paramtype>unsigned long</paramtype></parameter>
710 </signature>
711
712 <signature>
713 <type>std::size_t</type>
714 <parameter name="val"><paramtype>long long</paramtype></parameter>
715 </signature>
716
717 <signature>
718 <type>std::size_t</type>
719 <parameter name="val"><paramtype>unsigned long long</paramtype></parameter>
720 </signature>
721
722 <signature>
723 <type>std::size_t</type>
724 <parameter name="val"><paramtype>float</paramtype></parameter>
725 </signature>
726
727 <signature>
728 <type>std::size_t</type>
729 <parameter name="val"><paramtype>double</paramtype></parameter>
730 </signature>
731
732 <signature>
733 <type>std::size_t</type>
734 <parameter name="val"><paramtype>long double</paramtype></parameter>
735 </signature>
736
737 <signature>
738 <template><template-type-parameter name="T"/></template>
739 <type>std::size_t</type>
740 <parameter name="val"><paramtype>T* const&amp;</paramtype></parameter>
741 </signature>
742
743 <signature>
744 <template>
745 <template-type-parameter name="T"/>
746 <template-nontype-parameter name="N"><type>unsigned</type></template-nontype-parameter>
747 </template>
748 <type>std::size_t</type>
749 <parameter><paramtype>T (&amp;val)[N]</paramtype></parameter>
750 </signature>
751
752 <signature>
753 <template>
754 <template-type-parameter name="T"/>
755 <template-nontype-parameter name="N"><type>unsigned</type></template-nontype-parameter>
756 </template>
757 <type>std::size_t</type>
758 <parameter><paramtype>const T (&amp;val)[N]</paramtype></parameter>
759 </signature>
760
761 <signature>
762 <template>
763 <template-type-parameter name="Ch"/>
764 <template-type-parameter name="A"/>
765 </template>
766 <type>std::size_t</type>
767 <parameter name="val">
768 <paramtype>std::basic_string&lt;Ch, std::char_traits&lt;Ch&gt;, A&gt; const&amp;</paramtype>
769 </parameter>
770 </signature>
771
772 <signature>
773 <template>
774 <template-type-parameter name="A"/>
775 <template-type-parameter name="B"/>
776 </template>
777 <type>std::size_t</type>
778 <parameter name="val"><paramtype>std::pair&lt;A, B&gt; const&amp;</paramtype></parameter>
779 </signature>
780
781 <signature>
782 <template>
783 <template-type-parameter name="T"/>
784 <template-type-parameter name="A"/>
785 </template>
786 <type>std::size_t</type>
787 <parameter name="val"><paramtype>std::vector&lt;T, A&gt; const&amp;</paramtype></parameter>
788 </signature>
789
790 <signature>
791 <template>
792 <template-type-parameter name="T"/>
793 <template-type-parameter name="A"/>
794 </template>
795 <type>std::size_t</type>
796 <parameter name="val"><paramtype>std::list&lt;T, A&gt; const&amp;</paramtype></parameter>
797 </signature>
798
799 <signature>
800 <template>
801 <template-type-parameter name="T"/>
802 <template-type-parameter name="A"/>
803 </template>
804 <type>std::size_t</type>
805 <parameter name="val"><paramtype>std::deque&lt;T, A&gt; const&amp;</paramtype></parameter>
806 </signature>
807
808 <signature>
809 <template>
810 <template-type-parameter name="K"/>
811 <template-type-parameter name="C"/>
812 <template-type-parameter name="A"/>
813 </template>
814 <type>std::size_t</type>
815 <parameter name="val"><paramtype>std::set&lt;K, C, A&gt; const&amp;</paramtype></parameter>
816 </signature>
817
818 <signature>
819 <template>
820 <template-type-parameter name="K"/>
821 <template-type-parameter name="C"/>
822 <template-type-parameter name="A"/>
823 </template>
824 <type>std::size_t</type>
825 <parameter name="val"><paramtype>std::multiset&lt;K, C, A&gt; const&amp;</paramtype></parameter>
826 </signature>
827
828 <signature>
829 <template>
830 <template-type-parameter name="K"/>
831 <template-type-parameter name="T"/>
832 <template-type-parameter name="C"/>
833 <template-type-parameter name="A"/>
834 </template>
835 <type>std::size_t</type>
836 <parameter name="val"><paramtype>std::map&lt;K, T, C, A&gt; const&amp;</paramtype></parameter>
837 </signature>
838
839 <signature>
840 <template>
841 <template-type-parameter name="K"/>
842 <template-type-parameter name="T"/>
843 <template-type-parameter name="C"/>
844 <template-type-parameter name="A"/>
845 </template>
846 <type>std::size_t</type>
847 <parameter name="val"><paramtype>std::multimap&lt;K, T, C, A&gt; const&amp;</paramtype></parameter>
848 </signature>
849
850 <signature>
851 <template>
852 <template-type-parameter name="T"/>
853 </template>
854 <type>std::size_t</type>
855 <parameter name="val"><paramtype>std::complex&lt;T&gt; const&amp;</paramtype></parameter>
856 </signature>
857
858 <signature>
859 <type>std::size_t</type>
860 <parameter name="val"><paramtype>std::type_index</paramtype></parameter>
861 </signature>
862
863 <signature>
864 <template>
865 <template-type-parameter name="T"/>
866 <template-nontype-parameter name="N">
867 <type>std::size_t</type>
868 </template-nontype-parameter>
869 </template>
870 <type>std::size_t</type>
871 <parameter name="val"><paramtype>std::array&lt;T, N&gt; const&amp;</paramtype></parameter>
872 </signature>
873
874 <signature>
875 <template>
876 <template-type-parameter name="T" pack="1"/>
877 </template>
878 <type>std::size_t</type>
879 <parameter name="val"><paramtype>std::tuple&lt;T...&gt;</paramtype></parameter>
880 </signature>
881
882 <description><para>
883 Generally shouldn't be called directly by users, instead they should use
884 <classname>boost::hash</classname>, <functionname>boost::hash_range</functionname>
885 or <functionname>boost::hash_combine</functionname> which
886 call <code>hash_value</code> without namespace qualification so that overloads
887 for custom types are found via ADL.
888 </para></description>
889
890 <notes>
891 <para>This is an extension to TR1</para>
892 <para>
893 This hash function is not intended for general use, and isn't
894 guaranteed to be equal during separate runs of a program - so
895 please don't use it for any persistent storage or communication.
896 </para>
897 </notes>
898
899 <throws>
900 Only throws if a user supplied version of
901 <code><functionname>hash_value</functionname></code>
902 throws for an element of a container, or
903 one of the types stored in a pair.
904 </throws>
905
906 <returns>
907 <informaltable>
908 <tgroup cols="2">
909 <thead>
910 <row>
911 <entry>Types</entry>
912 <entry>Returns</entry>
913 </row>
914 </thead>
915 <tbody>
916 <row>
917 <entry><code>bool</code>,
918 <code>char</code>, <code>signed char</code>, <code>unsigned char</code>,
919 <code>wchar_t</code>, <code>char16_t</code>, <code>char32_t</code>,
920 <code>short</code>, <code>unsigned short</code>,
921 <code>int</code>, <code>unsigned int</code>, <code>long</code>, <code>unsigned long</code>
922 </entry>
923 <entry><code>val</code></entry>
924 </row>
925 <row>
926 <entry><code>long long</code>, <code>unsigned long long</code></entry>
927 <entry><code>val</code> when <code>abs(val) &lt;= std::numeric_limits&lt;std::size_t&gt;::max()</code>.</entry>
928 </row>
929 <row>
930 <entry><code>float</code>, <code>double</code>, <code>long double</code></entry>
931 <entry>An unspecified value, except that equal arguments shall yield the same result.</entry>
932 </row>
933 <row>
934 <entry><code>T*</code></entry>
935 <entry>An unspecified value, except that equal arguments shall yield the same result.</entry>
936 </row>
937 <row>
938 <entry>
939 <code>T&#160;val[N]</code>,
940 <code>const&#160;T&#160;val[N]</code>
941 </entry>
942 <entry><code>hash_range(val, val+N)</code></entry>
943 </row>
944 <row>
945 <entry>
946 <code>std:basic_string&lt;Ch,&#160;std::char_traits&lt;Ch&gt;,&#160;A&gt;</code>,
947 <code>std::vector&lt;T,&#160;A&gt;</code>,
948 <code>std::list&lt;T,&#160;A&gt;</code>,
949 <code>std::deque&lt;T,&#160;A&gt;</code>,
950 <code>std::set&lt;K,&#160;C,&#160;A&gt;</code>,
951 <code>std::multiset&lt;K,&#160;C,&#160;A&gt;</code>,
952 <code>std::map&lt;K,&#160;T,&#160;C,&#160;A&gt;</code>,
953 <code>std::multimap&lt;K,&#160;T,&#160;C,&#160;A&gt;</code>,
954 <code>std::array&lt;T,&#160;N&gt;</code>
955 </entry>
956 <entry><code>hash_range(val.begin(), val.end())</code></entry>
957 </row>
958 <row>
959 <entry><code>std::pair&lt;A, B&gt;</code></entry>
960 <entry><programlisting>size_t seed = 0;
961<functionname>hash_combine</functionname>(seed, val.first);
962<functionname>hash_combine</functionname>(seed, val.second);
963return seed;</programlisting></entry>
964 </row>
965 <row>
966 <entry><code>std::tuple&lt;T...&gt;</code></entry>
967 <entry><programlisting>size_t seed = 0;
968<functionname>hash_combine</functionname>(seed, get&lt;0&gt;(val));
969<functionname>hash_combine</functionname>(seed, get&lt;1&gt;(val));
970// ....
971return seed;</programlisting></entry>
972 </row>
973 <row>
974 <entry>
975 <code>std::complex&lt;T&gt;</code>
976 </entry>
977 <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>
978 </row>
979 <row>
980 <entry>
981 <code>std::type_index</code>
982 </entry>
983 <entry><code>val.hash_code()</code></entry>
984 </row>
985 </tbody>
986 </tgroup>
987 </informaltable>
988 </returns>
989 </overloaded-function>
990 </free-function-group>
991 </namespace>
992 </header>
993</library-reference>
994