• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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
995