From 773307fe1cc70b254b3534e2f9af89b5d708b558 Mon Sep 17 00:00:00 2001 From: Christian Mazakas Date: Thu, 3 Feb 2022 15:32:05 -0800 Subject: [PATCH] Add Reference section to AsciiDoc --- doc/hash/ref.adoc | 382 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 382 insertions(+) diff --git a/doc/hash/ref.adoc b/doc/hash/ref.adoc index 15a3169..ec3719a 100644 --- a/doc/hash/ref.adoc +++ b/doc/hash/ref.adoc @@ -2,3 +2,385 @@ = Reference :idprefix: ref_ + +For the full specification, see section 6.3 of the http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf[C++ Standard Library Technical Report^] and issue 6.18 of the http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1837.pdf[Library Extension Technical Report Issues List^] (page 63). + +== Header + +Defines xref:#ref_hash[boost::hash], and helper functions. + +[listing,subs="+quotes,+macros"] +---- +namespace boost { + template struct xref:#ref_hash[hash]; + + template<> struct xref:#ref_specializations[hash]; + template<> struct xref:#ref_specializations[hash]; + template<> struct xref:#ref_specializations[hash]; + template<> struct xref:#ref_specializations[hash]; + template<> struct xref:#ref_specializations[hash]; + template<> struct xref:#ref_specializations[hash]; + template<> struct xref:#ref_specializations[hash]; + template<> struct xref:#ref_specializations[hash]; + template<> struct xref:#ref_specializations[hash]; + template<> struct xref:#ref_specializations[hash]; + template<> struct xref:#ref_specializations[hash]; + template<> struct xref:#ref_specializations[hash]; + template<> struct xref:#ref_specializations[hash]; + template<> struct xref:#ref_specializations[hash]; + template<> struct xref:#ref_specializations[hash]; + template<> struct xref:#ref_specializations[hash]; + template<> struct xref:#ref_specializations[hash]; + template<> struct xref:#ref_specializations[hash]; + template<> struct xref:#ref_specializations[hash]; + template<> struct xref:#ref_specializations[hash]; + template<> struct xref:#ref_specializations[hash]; + template<> struct xref:#ref_specializations[hash]; + template<> struct xref:#ref_specializations[hash]; + + template struct xref:#ref_specializations[hash]; + + // xref:#ref_support_functions_boost_extension[Support functions (Boost extension).] + template + void xref:#ref_hash_combine[hash_combine](size_t &, T const&); + + template + std::size_t xref:#ref_hash_range[hash_range](It, It); + + template + void xref:#ref_hash_range[hash_range](std::size_t&, It, It); + + // xref:#ref_overloadable_hash_implementation_boost_extension[Overloadable hash implementation (Boost extension).] + std::size_t xref:#ref_hash_value[hash_value](bool); + std::size_t xref:#ref_hash_value[hash_value](char); + std::size_t xref:#ref_hash_value[hash_value](signed char); + std::size_t xref:#ref_hash_value[hash_value](unsigned char); + std::size_t xref:#ref_hash_value[hash_value](wchar_t); + std::size_t xref:#ref_hash_value[hash_value](char16_t); + std::size_t xref:#ref_hash_value[hash_value](char32_t); + std::size_t xref:#ref_hash_value[hash_value](short); + std::size_t xref:#ref_hash_value[hash_value](unsigned short); + std::size_t xref:#ref_hash_value[hash_value](int); + std::size_t xref:#ref_hash_value[hash_value](unsigned int); + std::size_t xref:#ref_hash_value[hash_value](long); + std::size_t xref:#ref_hash_value[hash_value](unsigned long); + std::size_t xref:#ref_hash_value[hash_value](long long); + std::size_t xref:#ref_hash_value[hash_value](unsigned long long); + std::size_t xref:#ref_hash_value[hash_value](float); + std::size_t xref:#ref_hash_value[hash_value](double); + std::size_t xref:#ref_hash_value[hash_value](long double); + + template + std::size_t xref:#ref_hash_value[hash_value](T* const&); + + template + std::size_t xref:#ref_hash_value[hash_value](T (&val)[N]); + + template + std::size_t xref:#ref_hash_value[hash_value](const T (&val)[N]); + + template + std::size_t xref:#ref_hash_value[hash_value](std::basic_string, A> const&); + + template + std::size_t xref:#ref_hash_value[hash_value](std::pair const&); + + template + std::size_t xref:#ref_hash_value[hash_value](std::vector const&); + + template + std::size_t xref:#ref_hash_value[hash_value](std::list const&); + + template + std::size_t xref:#ref_hash_value[hash_value](std::deque const&); + + template + std::size_t xref:#ref_hash_value[hash_value](std::set const&); + + template + std::size_t xref:#ref_hash_value[hash_value](std::multiset const&); + + template + std::size_t xref:#ref_hash_value[hash_value](std::map const&); + + template + std::size_t xref:#ref_hash_value[hash_value](std::multimap const&); + + template std::size_t xref:#ref_hash_value[hash_value](std::complex const&); + std::size_t xref:#ref_hash_value[hash_value](std::type_index); + + template + std::size_t xref:#ref_hash_value[hash_value](std::array const&); + + template + std::size_t xref:#ref_hash_value[hash_value](std::tuple); +} +---- + +== Struct template hash + +=== hash + +`boost::hash` — A http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf[TR1^] compliant hash function object. + +==== Synopsis + +[listing,subs="+quotes,+macros"] +---- +// xref:#ref_header_boostcontainer_hashhash_hpp[#include ] + +template +struct hash : public std::unary_function { + std::size_t operator()(T const&) const; +}; +---- + +==== Description + +[listing] +---- +std::size_t operator()(T const& val) const; +---- + +[horizontal] +Returns:: xref:#ref_hash_value[hash_value](val) + +Notes:: The call to xref:#ref_hash_value[hash_value] is unqualified, so that custom overloads can be found via argument dependent lookup. ++ +This is not defined when the macro `BOOST_HASH_NO_EXTENSIONS` is defined. The specializations are still defined, so only the specializations required by TR1 are defined. ++ +Forward declared in `` ++ +This hash function is not intended for general use, and isn't guaranteed to be equal during separate runs of a program - so please don't use it for any persistent storage or communication. + +Throws:: Only throws if xref:#ref_hash_value[hash_value](T) throws. + +== Specializations + +`boost::hash` + +=== Synopsis + +[listing] +---- +// #include + +struct hash { + std::size_t operator()(T const&) const; +}; +---- + +=== Description + +[listing] +---- +std::size_t operator()(T const val) const; +---- + +[horizontal] +Returns:: Unspecified in TR1, except that equal arguments yield the same result. ++ +xref:#ref_hash_value[hash_value](val) in Boost. + +[horizontal] +Throws:: Doesn't throw + +== Support functions (Boost extension). + +=== hash_combine + +[listing] +---- +template +void hash_combine(size_t &, T const&); +---- + +Called repeatedly to incrementally create a hash value from several variables. + +[horizontal] +Effects:: Updates seed with a new hash value generated by combining it with the result of xref:#ref_hash_value[hash_value](v). Will always produce the same result for the same combination of seed and xref:#ref_hash_value[hash_value](v) during the single run of a program. + +[horizontal] +Notes:: xref:#ref_hash_value[hash_value] is called without qualification, so that overloads can be found via ADL. + ++ +This is an extension to TR1 + ++ +Forward declared in `` + ++ +This hash function is not intended for general use, and isn't guaranteed to be equal during separate runs of a program - so please don't use it for any persistent storage or communication. + +[horizontal] +Throws:: Only throws if xref:#ref_hash_value[hash_value](T) throws. Strong exception safety, as long as xref:#ref_hash_value[hash_value](T) also has strong exception safety. + +=== hash_range + +[listing] +---- +template +std::size_t hash_range(It, It); + +template +void hash_range(std::size_t&, It, It); +---- + +Calculate the combined hash value of the elements of an iterator range. + +[horizontal] +Effects:: For the two argument overload: ++ +[listing,subs="+quotes,+macros"] +---- +size_t seed = 0; + +for(; first != last; ++first) +{ + xref:#ref_hash_combine[hash_combine](seed, *first); +} +return seed; +---- ++ +For the three arguments overload: ++ +[listing,subs="+quotes,+macros"] +---- +for(; first != last; ++first) +{ + xref:#ref_hash_combine[hash_combine](seed, *first); +} +---- + +[horizontal] +Notes:: `hash_range` is sensitive to the order of the elements so it wouldn't be appropriate to use this with an unordered container. ++ +This is an extension to TR1 ++ +Forward declared in `` ++ +This hash function is not intended for general use, and isn't guaranteed to be equal during separate runs of a program - so please don't use it for any persistent storage or communication. + +[horizontal] +Throws:: Only throws if xref:#ref_hash_value[hash_value]`(std::iterator_traits::value_type)` throws. `hash_range(std::size_t&, It, It)` has basic exception safety as long as xref:#ref_hash_value[hash_value]`(std::iterator_traits::value_type)` has basic exception safety. + +== Overloadable hash implementation (Boost extension). + +=== hash_value + +[listing] +---- +std::size_t hash_value(bool val); +std::size_t hash_value(char val); +std::size_t hash_value(signed char val); +std::size_t hash_value(unsigned char val); +std::size_t hash_value(wchar_t val); +std::size_t hash_value(char16_t val); +std::size_t hash_value(char32_t val); +std::size_t hash_value(short val); +std::size_t hash_value(unsigned short val); +std::size_t hash_value(int val); +std::size_t hash_value(unsigned int val); +std::size_t hash_value(long val); +std::size_t hash_value(unsigned long val); +std::size_t hash_value(long long val); +std::size_t hash_value(unsigned long long val); +std::size_t hash_value(float val); +std::size_t hash_value(double val); +std::size_t hash_value(long double val); + +template std::size_t hash_value(T* const& val); + +template std::size_t hash_value(T (&val)[N]); +template std::size_t hash_value(const T (&val)[N]); + +template + std::size_t hash_value(std::basic_string, A> const& val); +template + std::size_t hash_value(std::pair const& val); +template + std::size_t hash_value(std::vector const& val); +template + std::size_t hash_value(std::list const& val); +template + std::size_t hash_value(std::deque const& val); +template + std::size_t hash_value(std::set const& val); +template + std::size_t hash_value(std::multiset const& val); +template + std::size_t hash_value(std::map const& val); +template + std::size_t hash_value(std::multimap const& val); +template std::size_t hash_value(std::complex const& val); +std::size_t hash_value(std::type_index val); +template + std::size_t hash_value(std::array const& val); +template + std::size_t hash_value(std::tuple val); +---- + +Implementation of the hash function. + +Generally shouldn't be called directly by users, instead they should use xref:#ref_hash[boost::hash], xref:#ref_hash_range[boost::hash_range] or xref:#ref_hash_combine[boost::hash_combine] which call `hash_value` without namespace qualification so that overloads for custom types are found via ADL. + +[horizontal] +Notes:: This is an extension to TR1 ++ +This hash function is not intended for general use, and isn't guaranteed to be equal during separate runs of a program - so please don't use it for any persistent storage or communication. + +[horizontal] +Throws:: Only throws if a user supplied version of xref:#ref_hash_value[hash_value] throws for an element of a container, or one of the types stored in a pair. + +[vertical] +Returns:: ++ +[cols="1,1", frame=all, grid=rows] +|=== +|Types |Returns + +|`bool`, `char`, `signed char`, `unsigned char`, `wchar_t`, `char16_t`, `char32_t`, `short`, `unsigned short`, `int`, `unsigned int`, `long`, `unsigned long` +|val + +|`long long`, `unsigned long long` +|val when `abs(val) \<= std::numeric_limits::max()`. + +|`float`, `double`, `long double` +|An unspecified value, except that equal arguments shall yield the same result. + +|`T*` +|An unspecified value, except that equal arguments shall yield the same result. + +|`T val[N]`, `const T val[N]` +|`hash_range(val, val+N)` + +|`std:basic_string, A>`, `std::vector`, `std::list`, `std::deque`, `std::set`, `std::multiset`, `std::map`, `std::multimap`, `std::array` +|`hash_range(val.begin(), val.end())` + +|`std::pair` +a| + +[listing] +---- +size_t seed = 0; +hash_combine(seed, val.first); +hash_combine(seed, val.second); +return seed; +---- + +|`std::tuple` +a| + +[listing] +---- +size_t seed = 0; +hash_combine(seed, get<0>(val)); +hash_combine(seed, get<1>(val)); +// .... +return seed; +---- + +|`std::complex` +|When T is a built in type and `val.imag() == 0`, the result is equal to `hash_value(val.real())`. Otherwise an unspecified value, except that equal arguments shall yield the same result. + +|`std::type_index` +|`val.hash_code()` + +|===