forked from boostorg/container_hash
Add Reference section to AsciiDoc
This commit is contained in:
Christian Mazakas
@@ -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 <boost/container_hash/hash.hpp>
|
||||
|
||||
Defines xref:#ref_hash[boost::hash], and helper functions.
|
||||
|
||||
[listing,subs="+quotes,+macros"]
|
||||
----
|
||||
namespace boost {
|
||||
template<typename T> struct xref:#ref_hash[hash];
|
||||
|
||||
template<> struct xref:#ref_specializations[hash]<bool>;
|
||||
template<> struct xref:#ref_specializations[hash]<char>;
|
||||
template<> struct xref:#ref_specializations[hash]<signed char>;
|
||||
template<> struct xref:#ref_specializations[hash]<unsigned char>;
|
||||
template<> struct xref:#ref_specializations[hash]<wchar_t>;
|
||||
template<> struct xref:#ref_specializations[hash]<char16_t>;
|
||||
template<> struct xref:#ref_specializations[hash]<char32_t>;
|
||||
template<> struct xref:#ref_specializations[hash]<short>;
|
||||
template<> struct xref:#ref_specializations[hash]<unsigned short>;
|
||||
template<> struct xref:#ref_specializations[hash]<int>;
|
||||
template<> struct xref:#ref_specializations[hash]<unsigned int>;
|
||||
template<> struct xref:#ref_specializations[hash]<long>;
|
||||
template<> struct xref:#ref_specializations[hash]<unsigned long>;
|
||||
template<> struct xref:#ref_specializations[hash]<long long>;
|
||||
template<> struct xref:#ref_specializations[hash]<unsigned long long>;
|
||||
template<> struct xref:#ref_specializations[hash]<float>;
|
||||
template<> struct xref:#ref_specializations[hash]<double>;
|
||||
template<> struct xref:#ref_specializations[hash]<long double>;
|
||||
template<> struct xref:#ref_specializations[hash]<std::string>;
|
||||
template<> struct xref:#ref_specializations[hash]<std::wstring>;
|
||||
template<> struct xref:#ref_specializations[hash]<std::u16string>;
|
||||
template<> struct xref:#ref_specializations[hash]<std::u32string>;
|
||||
template<> struct xref:#ref_specializations[hash]<std::type_index>;
|
||||
|
||||
template<typename T> struct xref:#ref_specializations[hash]<T*>;
|
||||
|
||||
// xref:#ref_support_functions_boost_extension[Support functions (Boost extension).]
|
||||
template<typename T>
|
||||
void xref:#ref_hash_combine[hash_combine](size_t &, T const&);
|
||||
|
||||
template<typename It>
|
||||
std::size_t xref:#ref_hash_range[hash_range](It, It);
|
||||
|
||||
template<typename It>
|
||||
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<typename T>
|
||||
std::size_t xref:#ref_hash_value[hash_value](T* const&);
|
||||
|
||||
template<typename T, unsigned N>
|
||||
std::size_t xref:#ref_hash_value[hash_value](T (&val)[N]);
|
||||
|
||||
template<typename T, unsigned N>
|
||||
std::size_t xref:#ref_hash_value[hash_value](const T (&val)[N]);
|
||||
|
||||
template<typename Ch, typename A>
|
||||
std::size_t xref:#ref_hash_value[hash_value](std::basic_string<Ch, std::char_traits<Ch>, A> const&);
|
||||
|
||||
template<typename A, typename B>
|
||||
std::size_t xref:#ref_hash_value[hash_value](std::pair<A, B> const&);
|
||||
|
||||
template<typename T, typename A>
|
||||
std::size_t xref:#ref_hash_value[hash_value](std::vector<T, A> const&);
|
||||
|
||||
template<typename T, typename A>
|
||||
std::size_t xref:#ref_hash_value[hash_value](std::list<T, A> const&);
|
||||
|
||||
template<typename T, typename A>
|
||||
std::size_t xref:#ref_hash_value[hash_value](std::deque<T, A> const&);
|
||||
|
||||
template<typename K, typename C, typename A>
|
||||
std::size_t xref:#ref_hash_value[hash_value](std::set<K, C, A> const&);
|
||||
|
||||
template<typename K, typename C, typename A>
|
||||
std::size_t xref:#ref_hash_value[hash_value](std::multiset<K, C, A> const&);
|
||||
|
||||
template<typename K, typename T, typename C, typename A>
|
||||
std::size_t xref:#ref_hash_value[hash_value](std::map<K, T, C, A> const&);
|
||||
|
||||
template<typename K, typename T, typename C, typename A>
|
||||
std::size_t xref:#ref_hash_value[hash_value](std::multimap<K, T, C, A> const&);
|
||||
|
||||
template<typename T> std::size_t xref:#ref_hash_value[hash_value](std::complex<T> const&);
|
||||
std::size_t xref:#ref_hash_value[hash_value](std::type_index);
|
||||
|
||||
template<typename T, std::size_t N>
|
||||
std::size_t xref:#ref_hash_value[hash_value](std::array<T, N> const&);
|
||||
|
||||
template<typename... T>
|
||||
std::size_t xref:#ref_hash_value[hash_value](std::tuple<T...>);
|
||||
}
|
||||
----
|
||||
|
||||
== 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 <boost/container_hash/hash.hpp>]
|
||||
|
||||
template<typename T>
|
||||
struct hash : public std::unary_function<T, std::size_t> {
|
||||
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 `<boost/container_hash/hash_fwd.hpp>`
|
||||
+
|
||||
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<T>`
|
||||
|
||||
=== Synopsis
|
||||
|
||||
[listing]
|
||||
----
|
||||
// #include <boost/container_hash/hash.hpp>
|
||||
|
||||
struct hash<T> {
|
||||
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<typename T>
|
||||
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 `<boost/container_hash/hash_fwd.hpp>` +
|
||||
+
|
||||
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<typename It>
|
||||
std::size_t hash_range(It, It);
|
||||
|
||||
template<typename It>
|
||||
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 `<boost/container_hash/hash_fwd.hpp>`
|
||||
+
|
||||
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<It>::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<It>::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<typename T> std::size_t hash_value(T* const& val);
|
||||
|
||||
template<typename T, unsigned N> std::size_t hash_value(T (&val)[N]);
|
||||
template<typename T, unsigned N> std::size_t hash_value(const T (&val)[N]);
|
||||
|
||||
template<typename Ch, typename A>
|
||||
std::size_t hash_value(std::basic_string<Ch, std::char_traits<Ch>, A> const& val);
|
||||
template<typename A, typename B>
|
||||
std::size_t hash_value(std::pair<A, B> const& val);
|
||||
template<typename T, typename A>
|
||||
std::size_t hash_value(std::vector<T, A> const& val);
|
||||
template<typename T, typename A>
|
||||
std::size_t hash_value(std::list<T, A> const& val);
|
||||
template<typename T, typename A>
|
||||
std::size_t hash_value(std::deque<T, A> const& val);
|
||||
template<typename K, typename C, typename A>
|
||||
std::size_t hash_value(std::set<K, C, A> const& val);
|
||||
template<typename K, typename C, typename A>
|
||||
std::size_t hash_value(std::multiset<K, C, A> const& val);
|
||||
template<typename K, typename T, typename C, typename A>
|
||||
std::size_t hash_value(std::map<K, T, C, A> const& val);
|
||||
template<typename K, typename T, typename C, typename A>
|
||||
std::size_t hash_value(std::multimap<K, T, C, A> const& val);
|
||||
template<typename T> std::size_t hash_value(std::complex<T> const& val);
|
||||
std::size_t hash_value(std::type_index val);
|
||||
template<typename T, std::size_t N>
|
||||
std::size_t hash_value(std::array<T, N> const& val);
|
||||
template<typename... T>
|
||||
std::size_t hash_value(std::tuple<T...> 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<std::size_t>::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<Ch, std::char_traits<Ch>, A>`, `std::vector<T, A>`, `std::list<T, A>`, `std::deque<T, A>`, `std::set<K, C, A>`, `std::multiset<K, C, A>`, `std::map<K, T, C, A>`, `std::multimap<K, T, C, A>`, `std::array<T, N>`
|
||||
|`hash_range(val.begin(), val.end())`
|
||||
|
||||
|`std::pair<A, B>`
|
||||
a|
|
||||
|
||||
[listing]
|
||||
----
|
||||
size_t seed = 0;
|
||||
hash_combine(seed, val.first);
|
||||
hash_combine(seed, val.second);
|
||||
return seed;
|
||||
----
|
||||
|
||||
|`std::tuple<T...>`
|
||||
a|
|
||||
|
||||
[listing]
|
||||
----
|
||||
size_t seed = 0;
|
||||
hash_combine(seed, get<0>(val));
|
||||
hash_combine(seed, get<1>(val));
|
||||
// ....
|
||||
return seed;
|
||||
----
|
||||
|
||||
|`std::complex<T>`
|
||||
|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()`
|
||||
|
||||
|===
|
||||
|
||||
Reference in New Issue
Block a user