// Copyright 2018 The Abseil Authors. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // https://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // ----------------------------------------------------------------------------- // File: hash.h // ----------------------------------------------------------------------------- // #ifndef ABSL_HASH_INTERNAL_HASH_H_ #define ABSL_HASH_INTERNAL_HASH_H_ #ifdef __APPLE__ #include <Availability.h> #include <TargetConditionals.h> #endif #include "absl/base/config.h" // For feature testing and determining which headers can be included. #if ABSL_INTERNAL_CPLUSPLUS_LANG >= 202002L #include <version> #else #include <ciso646> #endif #include <algorithm> #include <array> #include <bitset> #include <cmath> #include <cstddef> #include <cstring> #include <deque> #include <forward_list> #include <functional> #include <iterator> #include <limits> #include <list> #include <map> #include <memory> #include <set> #include <string> #include <tuple> #include <type_traits> #include <unordered_map> #include <unordered_set> #include <utility> #include <vector> #include "absl/base/internal/unaligned_access.h" #include "absl/base/port.h" #include "absl/container/fixed_array.h" #include "absl/hash/internal/city.h" #include "absl/hash/internal/low_level_hash.h" #include "absl/meta/type_traits.h" #include "absl/numeric/bits.h" #include "absl/numeric/int128.h" #include "absl/strings/string_view.h" #include "absl/types/optional.h" #include "absl/types/variant.h" #include "absl/utility/utility.h" #if defined(__cpp_lib_filesystem) && __cpp_lib_filesystem >= 201703L && \ !defined(_LIBCPP_HAS_NO_FILESYSTEM_LIBRARY) #include <filesystem> // NOLINT #endif #ifdef ABSL_HAVE_STD_STRING_VIEW #include <string_view> #endif namespace absl { ABSL_NAMESPACE_BEGIN class HashState; namespace hash_internal { // Internal detail: Large buffers are hashed in smaller chunks. This function // returns the size of these chunks. constexpr size_t PiecewiseChunkSize() { … } // PiecewiseCombiner // // PiecewiseCombiner is an internal-only helper class for hashing a piecewise // buffer of `char` or `unsigned char` as though it were contiguous. This class // provides two methods: // // H add_buffer(state, data, size) // H finalize(state) // // `add_buffer` can be called zero or more times, followed by a single call to // `finalize`. This will produce the same hash expansion as concatenating each // buffer piece into a single contiguous buffer, and passing this to // `H::combine_contiguous`. // // Example usage: // PiecewiseCombiner combiner; // for (const auto& piece : pieces) { // state = combiner.add_buffer(std::move(state), piece.data, piece.size); // } // return combiner.finalize(std::move(state)); class PiecewiseCombiner { … }; // is_hashable() // // Trait class which returns true if T is hashable by the absl::Hash framework. // Used for the AbslHashValue implementations for composite types below. template <typename T> struct is_hashable; // HashStateBase // // An internal implementation detail that contains common implementation details // for all of the "hash state objects" objects generated by Abseil. This is not // a public API; users should not create classes that inherit from this. // // A hash state object is the template argument `H` passed to `AbslHashValue`. // It represents an intermediate state in the computation of an unspecified hash // algorithm. `HashStateBase` provides a CRTP style base class for hash state // implementations. Developers adding type support for `absl::Hash` should not // rely on any parts of the state object other than the following member // functions: // // * HashStateBase::combine() // * HashStateBase::combine_contiguous() // * HashStateBase::combine_unordered() // // A derived hash state class of type `H` must provide a public member function // with a signature similar to the following: // // `static H combine_contiguous(H state, const unsigned char*, size_t)`. // // It must also provide a private template method named RunCombineUnordered. // // A "consumer" is a 1-arg functor returning void. Its argument is a reference // to an inner hash state object, and it may be called multiple times. When // called, the functor consumes the entropy from the provided state object, // and resets that object to its empty state. // // A "combiner" is a stateless 2-arg functor returning void. Its arguments are // an inner hash state object and an ElementStateConsumer functor. A combiner // uses the provided inner hash state object to hash each element of the // container, passing the inner hash state object to the consumer after hashing // each element. // // Given these definitions, a derived hash state class of type H // must provide a private template method with a signature similar to the // following: // // `template <typename CombinerT>` // `static H RunCombineUnordered(H outer_state, CombinerT combiner)` // // This function is responsible for constructing the inner state object and // providing a consumer to the combiner. It uses side effects of the consumer // and combiner to mix the state of each element in an order-independent manner, // and uses this to return an updated value of `outer_state`. // // This inside-out approach generates efficient object code in the normal case, // but allows us to use stack storage to implement the absl::HashState type // erasure mechanism (avoiding heap allocations while hashing). // // `HashStateBase` will provide a complete implementation for a hash state // object in terms of these two methods. // // Example: // // // Use CRTP to define your derived class. // struct MyHashState : HashStateBase<MyHashState> { // static H combine_contiguous(H state, const unsigned char*, size_t); // using MyHashState::HashStateBase::combine; // using MyHashState::HashStateBase::combine_contiguous; // using MyHashState::HashStateBase::combine_unordered; // private: // template <typename CombinerT> // static H RunCombineUnordered(H state, CombinerT combiner); // }; template <typename H> class HashStateBase { … }; // is_uniquely_represented // // `is_uniquely_represented<T>` is a trait class that indicates whether `T` // is uniquely represented. // // A type is "uniquely represented" if two equal values of that type are // guaranteed to have the same bytes in their underlying storage. In other // words, if `a == b`, then `memcmp(&a, &b, sizeof(T))` is guaranteed to be // zero. This property cannot be detected automatically, so this trait is false // by default, but can be specialized by types that wish to assert that they are // uniquely represented. This makes them eligible for certain optimizations. // // If you have any doubt whatsoever, do not specialize this template. // The default is completely safe, and merely disables some optimizations // that will not matter for most types. Specializing this template, // on the other hand, can be very hazardous. // // To be uniquely represented, a type must not have multiple ways of // representing the same value; for example, float and double are not // uniquely represented, because they have distinct representations for // +0 and -0. Furthermore, the type's byte representation must consist // solely of user-controlled data, with no padding bits and no compiler- // controlled data such as vptrs or sanitizer metadata. This is usually // very difficult to guarantee, because in most cases the compiler can // insert data and padding bits at its own discretion. // // If you specialize this template for a type `T`, you must do so in the file // that defines that type (or in this file). If you define that specialization // anywhere else, `is_uniquely_represented<T>` could have different meanings // in different places. // // The Enable parameter is meaningless; it is provided as a convenience, // to support certain SFINAE techniques when defining specializations. template <typename T, typename Enable = void> struct is_uniquely_represented : std::false_type { … }; // is_uniquely_represented<unsigned char> // // unsigned char is a synonym for "byte", so it is guaranteed to be // uniquely represented. template <> struct is_uniquely_represented<unsigned char> : std::true_type { … }; // is_uniquely_represented for non-standard integral types // // Integral types other than bool should be uniquely represented on any // platform that this will plausibly be ported to. is_uniquely_represented<Integral, typename std::enable_if<std::is_integral<Integral>::value>::type>; // is_uniquely_represented<bool> // // template <> struct is_uniquely_represented<bool> : std::false_type { … }; // hash_bytes() // // Convenience function that combines `hash_state` with the byte representation // of `value`. template <typename H, typename T> H hash_bytes(H hash_state, const T& value) { … } // ----------------------------------------------------------------------------- // AbslHashValue for Basic Types // ----------------------------------------------------------------------------- // Note: Default `AbslHashValue` implementations live in `hash_internal`. This // allows us to block lexical scope lookup when doing an unqualified call to // `AbslHashValue` below. User-defined implementations of `AbslHashValue` can // only be found via ADL. // AbslHashValue() for hashing bool values // // We use SFINAE to ensure that this overload only accepts bool, not types that // are convertible to bool. template <typename H, typename B> typename std::enable_if<std::is_same<B, bool>::value, H>::type AbslHashValue( H hash_state, B value) { … } // AbslHashValue() for hashing enum values template <typename H, typename Enum> typename std::enable_if<std::is_enum<Enum>::value, H>::type AbslHashValue( H hash_state, Enum e) { … } // AbslHashValue() for hashing floating-point values template <typename H, typename Float> typename std::enable_if<std::is_same<Float, float>::value || std::is_same<Float, double>::value, H>::type AbslHashValue(H hash_state, Float value) { … } // Long double has the property that it might have extra unused bytes in it. // For example, in x86 sizeof(long double)==16 but it only really uses 80-bits // of it. This means we can't use hash_bytes on a long double and have to // convert it to something else first. template <typename H, typename LongDouble> typename std::enable_if<std::is_same<LongDouble, long double>::value, H>::type AbslHashValue(H hash_state, LongDouble value) { … } // Without this overload, an array decays to a pointer and we hash that, which // is not likely to be what the caller intended. template <typename H, typename T, size_t N> H AbslHashValue(H hash_state, T (&)[N]) { … } // AbslHashValue() for hashing pointers template <typename H, typename T> std::enable_if_t<std::is_pointer<T>::value, H> AbslHashValue(H hash_state, T ptr) { … } // AbslHashValue() for hashing nullptr_t template <typename H> H AbslHashValue(H hash_state, std::nullptr_t) { … } // AbslHashValue() for hashing pointers-to-member template <typename H, typename T, typename C> H AbslHashValue(H hash_state, T C::*ptr) { … } // ----------------------------------------------------------------------------- // AbslHashValue for Composite Types // ----------------------------------------------------------------------------- // AbslHashValue() for hashing pairs template <typename H, typename T1, typename T2> typename std::enable_if<is_hashable<T1>::value && is_hashable<T2>::value, H>::type AbslHashValue(H hash_state, const std::pair<T1, T2>& p) { … } // hash_tuple() // // Helper function for hashing a tuple. The third argument should // be an index_sequence running from 0 to tuple_size<Tuple> - 1. template <typename H, typename Tuple, size_t... Is> H hash_tuple(H hash_state, const Tuple& t, absl::index_sequence<Is...>) { … } // AbslHashValue for hashing tuples template <typename H, typename... Ts> #if defined(_MSC_VER) // This SFINAE gets MSVC confused under some conditions. Let's just disable it // for now. H #else // _MSC_VER typename std::enable_if<absl::conjunction<is_hashable<Ts>...>::value, H>::type #endif // _MSC_VER AbslHashValue(H hash_state, const std::tuple<Ts...>& t) { … } // ----------------------------------------------------------------------------- // AbslHashValue for Pointers // ----------------------------------------------------------------------------- // AbslHashValue for hashing unique_ptr template <typename H, typename T, typename D> H AbslHashValue(H hash_state, const std::unique_ptr<T, D>& ptr) { … } // AbslHashValue for hashing shared_ptr template <typename H, typename T> H AbslHashValue(H hash_state, const std::shared_ptr<T>& ptr) { … } // ----------------------------------------------------------------------------- // AbslHashValue for String-Like Types // ----------------------------------------------------------------------------- // AbslHashValue for hashing strings // // All the string-like types supported here provide the same hash expansion for // the same character sequence. These types are: // // - `absl::Cord` // - `std::string` (and std::basic_string<T, std::char_traits<T>, A> for // any allocator A and any T in {char, wchar_t, char16_t, char32_t}) // - `absl::string_view`, `std::string_view`, `std::wstring_view`, // `std::u16string_view`, and `std::u32_string_view`. // // For simplicity, we currently support only strings built on `char`, `wchar_t`, // `char16_t`, or `char32_t`. This support may be broadened, if necessary, but // with some caution - this overload would misbehave in cases where the traits' // `eq()` member isn't equivalent to `==` on the underlying character type. template <typename H> H AbslHashValue(H hash_state, absl::string_view str) { … } // Support std::wstring, std::u16string and std::u32string. template <typename Char, typename Alloc, typename H, typename = absl::enable_if_t<std::is_same<Char, wchar_t>::value || std::is_same<Char, char16_t>::value || std::is_same<Char, char32_t>::value>> H AbslHashValue( H hash_state, const std::basic_string<Char, std::char_traits<Char>, Alloc>& str) { … } #ifdef ABSL_HAVE_STD_STRING_VIEW // Support std::wstring_view, std::u16string_view and std::u32string_view. template <typename Char, typename H, typename = absl::enable_if_t<std::is_same<Char, wchar_t>::value || std::is_same<Char, char16_t>::value || std::is_same<Char, char32_t>::value>> H AbslHashValue(H hash_state, std::basic_string_view<Char> str) { … } #endif // ABSL_HAVE_STD_STRING_VIEW #if defined(__cpp_lib_filesystem) && __cpp_lib_filesystem >= 201703L && \ !defined(_LIBCPP_HAS_NO_FILESYSTEM_LIBRARY) && \ (!defined(__ENVIRONMENT_IPHONE_OS_VERSION_MIN_REQUIRED__) || \ __ENVIRONMENT_IPHONE_OS_VERSION_MIN_REQUIRED__ >= 130000) && \ (!defined(__ENVIRONMENT_MAC_OS_X_VERSION_MIN_REQUIRED__) || \ __ENVIRONMENT_MAC_OS_X_VERSION_MIN_REQUIRED__ >= 101500) #define ABSL_INTERNAL_STD_FILESYSTEM_PATH_HASH_AVAILABLE … // Support std::filesystem::path. The SFINAE is required because some string // types are implicitly convertible to std::filesystem::path. template <typename Path, typename H, typename = absl::enable_if_t< std::is_same_v<Path, std::filesystem::path>>> H AbslHashValue(H hash_state, const Path& path) { … } #endif // ABSL_INTERNAL_STD_FILESYSTEM_PATH_HASH_AVAILABLE // ----------------------------------------------------------------------------- // AbslHashValue for Sequence Containers // ----------------------------------------------------------------------------- // AbslHashValue for hashing std::array template <typename H, typename T, size_t N> typename std::enable_if<is_hashable<T>::value, H>::type AbslHashValue( H hash_state, const std::array<T, N>& array) { … } // AbslHashValue for hashing std::deque template <typename H, typename T, typename Allocator> typename std::enable_if<is_hashable<T>::value, H>::type AbslHashValue( H hash_state, const std::deque<T, Allocator>& deque) { … } // AbslHashValue for hashing std::forward_list template <typename H, typename T, typename Allocator> typename std::enable_if<is_hashable<T>::value, H>::type AbslHashValue( H hash_state, const std::forward_list<T, Allocator>& list) { … } // AbslHashValue for hashing std::list template <typename H, typename T, typename Allocator> typename std::enable_if<is_hashable<T>::value, H>::type AbslHashValue( H hash_state, const std::list<T, Allocator>& list) { … } // AbslHashValue for hashing std::vector // // Do not use this for vector<bool> on platforms that have a working // implementation of std::hash. It does not have a .data(), and a fallback for // std::hash<> is most likely faster. template <typename H, typename T, typename Allocator> typename std::enable_if<is_hashable<T>::value && !std::is_same<T, bool>::value, H>::type AbslHashValue(H hash_state, const std::vector<T, Allocator>& vector) { … } // AbslHashValue special cases for hashing std::vector<bool> #if defined(ABSL_IS_BIG_ENDIAN) && \ (defined(__GLIBCXX__) || defined(__GLIBCPP__)) // std::hash in libstdc++ does not work correctly with vector<bool> on Big // Endian platforms therefore we need to implement a custom AbslHashValue for // it. More details on the bug: // https://gcc.gnu.org/bugzilla/show_bug.cgi?id=102531 template <typename H, typename T, typename Allocator> typename std::enable_if<is_hashable<T>::value && std::is_same<T, bool>::value, H>::type AbslHashValue(H hash_state, const std::vector<T, Allocator>& vector) { typename H::AbslInternalPiecewiseCombiner combiner; for (const auto& i : vector) { unsigned char c = static_cast<unsigned char>(i); hash_state = combiner.add_buffer(std::move(hash_state), &c, sizeof(c)); } return H::combine(combiner.finalize(std::move(hash_state)), vector.size()); } #else // When not working around the libstdc++ bug above, we still have to contend // with the fact that std::hash<vector<bool>> is often poor quality, hashing // directly on the internal words and on no other state. On these platforms, // vector<bool>{1, 1} and vector<bool>{1, 1, 0} hash to the same value. // // Mixing in the size (as we do in our other vector<> implementations) on top // of the library-provided hash implementation avoids this QOI issue. template <typename H, typename T, typename Allocator> typename std::enable_if<is_hashable<T>::value && std::is_same<T, bool>::value, H>::type AbslHashValue(H hash_state, const std::vector<T, Allocator>& vector) { … } #endif // ----------------------------------------------------------------------------- // AbslHashValue for Ordered Associative Containers // ----------------------------------------------------------------------------- // AbslHashValue for hashing std::map template <typename H, typename Key, typename T, typename Compare, typename Allocator> typename std::enable_if<is_hashable<Key>::value && is_hashable<T>::value, H>::type AbslHashValue(H hash_state, const std::map<Key, T, Compare, Allocator>& map) { … } // AbslHashValue for hashing std::multimap template <typename H, typename Key, typename T, typename Compare, typename Allocator> typename std::enable_if<is_hashable<Key>::value && is_hashable<T>::value, H>::type AbslHashValue(H hash_state, const std::multimap<Key, T, Compare, Allocator>& map) { … } // AbslHashValue for hashing std::set template <typename H, typename Key, typename Compare, typename Allocator> typename std::enable_if<is_hashable<Key>::value, H>::type AbslHashValue( H hash_state, const std::set<Key, Compare, Allocator>& set) { … } // AbslHashValue for hashing std::multiset template <typename H, typename Key, typename Compare, typename Allocator> typename std::enable_if<is_hashable<Key>::value, H>::type AbslHashValue( H hash_state, const std::multiset<Key, Compare, Allocator>& set) { … } // ----------------------------------------------------------------------------- // AbslHashValue for Unordered Associative Containers // ----------------------------------------------------------------------------- // AbslHashValue for hashing std::unordered_set template <typename H, typename Key, typename Hash, typename KeyEqual, typename Alloc> typename std::enable_if<is_hashable<Key>::value, H>::type AbslHashValue( H hash_state, const std::unordered_set<Key, Hash, KeyEqual, Alloc>& s) { … } // AbslHashValue for hashing std::unordered_multiset template <typename H, typename Key, typename Hash, typename KeyEqual, typename Alloc> typename std::enable_if<is_hashable<Key>::value, H>::type AbslHashValue( H hash_state, const std::unordered_multiset<Key, Hash, KeyEqual, Alloc>& s) { … } // AbslHashValue for hashing std::unordered_set template <typename H, typename Key, typename T, typename Hash, typename KeyEqual, typename Alloc> typename std::enable_if<is_hashable<Key>::value && is_hashable<T>::value, H>::type AbslHashValue(H hash_state, const std::unordered_map<Key, T, Hash, KeyEqual, Alloc>& s) { … } // AbslHashValue for hashing std::unordered_multiset template <typename H, typename Key, typename T, typename Hash, typename KeyEqual, typename Alloc> typename std::enable_if<is_hashable<Key>::value && is_hashable<T>::value, H>::type AbslHashValue(H hash_state, const std::unordered_multimap<Key, T, Hash, KeyEqual, Alloc>& s) { … } // ----------------------------------------------------------------------------- // AbslHashValue for Wrapper Types // ----------------------------------------------------------------------------- // AbslHashValue for hashing std::reference_wrapper template <typename H, typename T> typename std::enable_if<is_hashable<T>::value, H>::type AbslHashValue( H hash_state, std::reference_wrapper<T> opt) { … } // AbslHashValue for hashing absl::optional template <typename H, typename T> typename std::enable_if<is_hashable<T>::value, H>::type AbslHashValue( H hash_state, const absl::optional<T>& opt) { … } // VariantVisitor template <typename H> struct VariantVisitor { … }; // AbslHashValue for hashing absl::variant template <typename H, typename... T> typename std::enable_if<conjunction<is_hashable<T>...>::value, H>::type AbslHashValue(H hash_state, const absl::variant<T...>& v) { … } // ----------------------------------------------------------------------------- // AbslHashValue for Other Types // ----------------------------------------------------------------------------- // AbslHashValue for hashing std::bitset is not defined on Little Endian // platforms, for the same reason as for vector<bool> (see std::vector above): // It does not expose the raw bytes, and a fallback to std::hash<> is most // likely faster. #if defined(ABSL_IS_BIG_ENDIAN) && \ (defined(__GLIBCXX__) || defined(__GLIBCPP__)) // AbslHashValue for hashing std::bitset // // std::hash in libstdc++ does not work correctly with std::bitset on Big Endian // platforms therefore we need to implement a custom AbslHashValue for it. More // details on the bug: https://gcc.gnu.org/bugzilla/show_bug.cgi?id=102531 template <typename H, size_t N> H AbslHashValue(H hash_state, const std::bitset<N>& set) { typename H::AbslInternalPiecewiseCombiner combiner; for (size_t i = 0; i < N; i++) { unsigned char c = static_cast<unsigned char>(set[i]); hash_state = combiner.add_buffer(std::move(hash_state), &c, sizeof(c)); } return H::combine(combiner.finalize(std::move(hash_state)), N); } #endif // ----------------------------------------------------------------------------- // hash_range_or_bytes() // // Mixes all values in the range [data, data+size) into the hash state. // This overload accepts only uniquely-represented types, and hashes them by // hashing the entire range of bytes. template <typename H, typename T> typename std::enable_if<is_uniquely_represented<T>::value, H>::type hash_range_or_bytes(H hash_state, const T* data, size_t size) { … } // hash_range_or_bytes() template <typename H, typename T> typename std::enable_if<!is_uniquely_represented<T>::value, H>::type hash_range_or_bytes(H hash_state, const T* data, size_t size) { … } #if defined(ABSL_INTERNAL_LEGACY_HASH_NAMESPACE) && \ ABSL_META_INTERNAL_STD_HASH_SFINAE_FRIENDLY_ #define ABSL_HASH_INTERNAL_SUPPORT_LEGACY_HASH_ … #else #define ABSL_HASH_INTERNAL_SUPPORT_LEGACY_HASH_ … #endif // HashSelect // // Type trait to select the appropriate hash implementation to use. // HashSelect::type<T> will give the proper hash implementation, to be invoked // as: // HashSelect::type<T>::Invoke(state, value) // Also, HashSelect::type<T>::value is a boolean equal to `true` if there is a // valid `Invoke` function. Types that are not hashable will have a ::value of // `false`. struct HashSelect { … }; template <typename T> struct is_hashable : std::integral_constant<bool, HashSelect::template Apply<T>::value> { … }; // MixingHashState class ABSL_DLL MixingHashState : public HashStateBase<MixingHashState> { … }; // MixingHashState::CombineContiguousImpl() inline uint64_t MixingHashState::CombineContiguousImpl( uint64_t state, const unsigned char* first, size_t len, std::integral_constant<int, 4> /* sizeof_size_t */) { … } // Overload of MixingHashState::CombineContiguousImpl() inline uint64_t MixingHashState::CombineContiguousImpl( uint64_t state, const unsigned char* first, size_t len, std::integral_constant<int, 8> /* sizeof_size_t */) { … } struct AggregateBarrier { … }; // HashImpl // Add a private base class to make sure this type is not an aggregate. // Aggregates can be aggregate initialized even if the default constructor is // deleted. struct PoisonedHash : private AggregateBarrier { … }; template <typename T> struct HashImpl { … }; template <typename T> struct Hash : absl::conditional_t<is_hashable<T>::value, HashImpl<T>, PoisonedHash> { … }; template <typename H> template <typename T, typename... Ts> H HashStateBase<H>::combine(H state, const T& value, const Ts&... values) { … } // HashStateBase::combine_contiguous() template <typename H> template <typename T> H HashStateBase<H>::combine_contiguous(H state, const T* data, size_t size) { … } // HashStateBase::combine_unordered() template <typename H> template <typename I> H HashStateBase<H>::combine_unordered(H state, I begin, I end) { … } // HashStateBase::PiecewiseCombiner::add_buffer() template <typename H> H PiecewiseCombiner::add_buffer(H state, const unsigned char* data, size_t size) { … } // HashStateBase::PiecewiseCombiner::finalize() template <typename H> H PiecewiseCombiner::finalize(H state) { … } } // namespace hash_internal ABSL_NAMESPACE_END } // namespace absl #endif // ABSL_HASH_INTERNAL_HASH_H_