// 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 // // http://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_ #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include "absl/base/internal/endian.h" #include "absl/base/port.h" #include "absl/container/fixed_array.h" #include "absl/meta/type_traits.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" #include "absl/hash/internal/city.h" namespace absl { namespace hash_internal { // HashStateBase // // A hash state object 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() // // A derived hash state class of type `H` must provide a static member function // with a signature similar to the following: // // `static H combine_contiguous(H state, const unsigned char*, size_t)`. // // `HashStateBase` will provide a complete implementations for a hash state // object in terms of this method. // // Example: // // // Use CRTP to define your derived class. // struct MyHashState : HashStateBase { // static H combine_contiguous(H state, const unsigned char*, size_t); // using MyHashState::HashStateBase::combine; // using MyHashState::HashStateBase::combine_contiguous; // }; template class HashStateBase { public: // HashStateBase::combine() // // Combines an arbitrary number of values into a hash state, returning the // updated state. // // Each of the value types `T` must be separately hashable by the Abseil // hashing framework. // // NOTE: // // state = H::combine(std::move(state), value1, value2, value3); // // is guaranteed to produce the same hash expansion as: // // state = H::combine(std::move(state), value1); // state = H::combine(std::move(state), value2); // state = H::combine(std::move(state), value3); template static H combine(H state, const T& value, const Ts&... values); static H combine(H state) { return state; } // HashStateBase::combine_contiguous() // // Combines a contiguous array of `size` elements into a hash state, returning // the updated state. // // NOTE: // // state = H::combine_contiguous(std::move(state), data, size); // // is NOT guaranteed to produce the same hash expansion as a for-loop (it may // perform internal optimizations). If you need this guarantee, use the // for-loop instead. template static H combine_contiguous(H state, const T* data, size_t size); }; // is_uniquely_represented // // `is_uniquely_represented` 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` 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 struct is_uniquely_represented : std::false_type {}; // is_uniquely_represented // // unsigned char is a synonym for "byte", so it is guaranteed to be // uniquely represented. template <> struct is_uniquely_represented : 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. template struct is_uniquely_represented< Integral, typename std::enable_if::value>::type> : std::true_type {}; // is_uniquely_represented // // template <> struct is_uniquely_represented : std::false_type {}; // hash_bytes() // // Convenience function that combines `hash_state` with the byte representation // of `value`. template H hash_bytes(H hash_state, const T& value) { const unsigned char* start = reinterpret_cast(&value); return H::combine_contiguous(std::move(hash_state), start, sizeof(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 std::enable_if::value, H>::type AbslHashValue( H hash_state, B value) { return H::combine(std::move(hash_state), static_cast(value ? 1 : 0)); } // AbslHashValue() for hashing enum values template typename std::enable_if::value, H>::type AbslHashValue( H hash_state, Enum e) { // In practice, we could almost certainly just invoke hash_bytes directly, // but it's possible that a sanitizer might one day want to // store data in the unused bits of an enum. To avoid that risk, we // convert to the underlying type before hashing. Hopefully this will get // optimized away; if not, we can reopen discussion with c-toolchain-team. return H::combine(std::move(hash_state), static_cast::type>(e)); } // AbslHashValue() for hashing floating-point values template typename std::enable_if::value, H>::type AbslHashValue(H hash_state, Float value) { return hash_internal::hash_bytes(std::move(hash_state), value == 0 ? 0 : 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 H AbslHashValue(H hash_state, long double value) { const int category = std::fpclassify(value); switch (category) { case FP_INFINITE: // Add the sign bit to differentiate between +Inf and -Inf hash_state = H::combine(std::move(hash_state), std::signbit(value)); break; case FP_NAN: case FP_ZERO: default: // Category is enough for these. break; case FP_NORMAL: case FP_SUBNORMAL: // We can't convert `value` directly to double because this would have // undefined behavior if the value is out of range. // std::frexp gives us a value in the range (-1, -.5] or [.5, 1) that is // guaranteed to be in range for `double`. The truncation is // implementation defined, but that works as long as it is deterministic. int exp; auto mantissa = static_cast(std::frexp(value, &exp)); hash_state = H::combine(std::move(hash_state), mantissa, exp); } return H::combine(std::move(hash_state), category); } // AbslHashValue() for hashing pointers template H AbslHashValue(H hash_state, T* ptr) { return hash_internal::hash_bytes(std::move(hash_state), ptr); } // AbslHashValue() for hashing nullptr_t template H AbslHashValue(H hash_state, std::nullptr_t) { return H::combine(std::move(hash_state), static_cast(nullptr)); } // ----------------------------------------------------------------------------- // AbslHashValue for Composite Types // ----------------------------------------------------------------------------- // 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 struct is_hashable; // AbslHashValue() for hashing pairs template typename std::enable_if::value && is_hashable::value, H>::type AbslHashValue(H hash_state, const std::pair& p) { return H::combine(std::move(hash_state), p.first, p.second); } // hash_tuple() // // Helper function for hashing a tuple. The third argument should // be an index_sequence running from 0 to tuple_size - 1. template H hash_tuple(H hash_state, const Tuple& t, absl::index_sequence) { return H::combine(std::move(hash_state), std::get(t)...); } // AbslHashValue for hashing tuples template #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...>::value, H>::type #endif // _MSC_VER AbslHashValue(H hash_state, const std::tuple& t) { return hash_internal::hash_tuple(std::move(hash_state), t, absl::make_index_sequence()); } // ----------------------------------------------------------------------------- // AbslHashValue for Pointers // ----------------------------------------------------------------------------- // AbslHashValue for hashing unique_ptr template H AbslHashValue(H hash_state, const std::unique_ptr& ptr) { return H::combine(std::move(hash_state), ptr.get()); } // AbslHashValue for hashing shared_ptr template H AbslHashValue(H hash_state, const std::shared_ptr& ptr) { return H::combine(std::move(hash_state), ptr.get()); } // ----------------------------------------------------------------------------- // 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: // // - `std::string` (and std::basic_string, A> for // any allocator A) // - `absl::string_view` and `std::string_view` // // For simplicity, we currently support only `char` strings. 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 H AbslHashValue(H hash_state, absl::string_view str) { return H::combine( H::combine_contiguous(std::move(hash_state), str.data(), str.size()), str.size()); } // ----------------------------------------------------------------------------- // AbslHashValue for Sequence Containers // ----------------------------------------------------------------------------- // AbslHashValue for hashing std::array template typename std::enable_if::value, H>::type AbslHashValue( H hash_state, const std::array& array) { return H::combine_contiguous(std::move(hash_state), array.data(), array.size()); } // AbslHashValue for hashing std::deque template typename std::enable_if::value, H>::type AbslHashValue( H hash_state, const std::deque& deque) { // TODO(gromer): investigate a more efficient implementation taking // advantage of the chunk structure. for (const auto& t : deque) { hash_state = H::combine(std::move(hash_state), t); } return H::combine(std::move(hash_state), deque.size()); } // AbslHashValue for hashing std::forward_list template typename std::enable_if::value, H>::type AbslHashValue( H hash_state, const std::forward_list& list) { size_t size = 0; for (const T& t : list) { hash_state = H::combine(std::move(hash_state), t); ++size; } return H::combine(std::move(hash_state), size); } // AbslHashValue for hashing std::list template typename std::enable_if::value, H>::type AbslHashValue( H hash_state, const std::list& list) { for (const auto& t : list) { hash_state = H::combine(std::move(hash_state), t); } return H::combine(std::move(hash_state), list.size()); } // AbslHashValue for hashing std::vector // // Do not use this for vector. It does not have a .data(), and a fallback // for std::hash<> is most likely faster. template typename std::enable_if::value && !std::is_same::value, H>::type AbslHashValue(H hash_state, const std::vector& vector) { return H::combine(H::combine_contiguous(std::move(hash_state), vector.data(), vector.size()), vector.size()); } // ----------------------------------------------------------------------------- // AbslHashValue for Ordered Associative Containers // ----------------------------------------------------------------------------- // AbslHashValue for hashing std::map template typename std::enable_if::value && is_hashable::value, H>::type AbslHashValue(H hash_state, const std::map& map) { for (const auto& t : map) { hash_state = H::combine(std::move(hash_state), t); } return H::combine(std::move(hash_state), map.size()); } // AbslHashValue for hashing std::multimap template typename std::enable_if::value && is_hashable::value, H>::type AbslHashValue(H hash_state, const std::multimap& map) { for (const auto& t : map) { hash_state = H::combine(std::move(hash_state), t); } return H::combine(std::move(hash_state), map.size()); } // AbslHashValue for hashing std::set template typename std::enable_if::value, H>::type AbslHashValue( H hash_state, const std::set& set) { for (const auto& t : set) { hash_state = H::combine(std::move(hash_state), t); } return H::combine(std::move(hash_state), set.size()); } // AbslHashValue for hashing std::multiset template typename std::enable_if::value, H>::type AbslHashValue( H hash_state, const std::multiset& set) { for (const auto& t : set) { hash_state = H::combine(std::move(hash_state), t); } return H::combine(std::move(hash_state), set.size()); } // ----------------------------------------------------------------------------- // AbslHashValue for Wrapper Types // ----------------------------------------------------------------------------- // AbslHashValue for hashing absl::optional template typename std::enable_if::value, H>::type AbslHashValue( H hash_state, const absl::optional& opt) { if (opt) hash_state = H::combine(std::move(hash_state), *opt); return H::combine(std::move(hash_state), opt.has_value()); } // VariantVisitor template struct VariantVisitor { H&& hash_state; template H operator()(const T& t) const { return H::combine(std::move(hash_state), t); } }; // AbslHashValue for hashing absl::variant template typename std::enable_if...>::value, H>::type AbslHashValue(H hash_state, const absl::variant& v) { if (!v.valueless_by_exception()) { hash_state = absl::visit(VariantVisitor{std::move(hash_state)}, v); } return H::combine(std::move(hash_state), v.index()); } // ----------------------------------------------------------------------------- // AbslHashValue for Other Types // ----------------------------------------------------------------------------- // AbslHashValue for hashing std::bitset is not defined, for the same reason as // for vector (see std::vector above): It does not expose the raw bytes, // and a fallback to std::hash<> is most likely faster. // ----------------------------------------------------------------------------- // 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 std::enable_if::value, H>::type hash_range_or_bytes(H hash_state, const T* data, size_t size) { const auto* bytes = reinterpret_cast(data); return H::combine_contiguous(std::move(hash_state), bytes, sizeof(T) * size); } // hash_range_or_bytes() template typename std::enable_if::value, H>::type hash_range_or_bytes(H hash_state, const T* data, size_t size) { for (const auto end = data + size; data < end; ++data) { hash_state = H::combine(std::move(hash_state), *data); } return hash_state; } // InvokeHashTag // // InvokeHash(H, const T&) invokes the appropriate hash implementation for a // hasher of type `H` and a value of type `T`. If `T` is not hashable, there // will be no matching overload of InvokeHash(). // Note: Some platforms (eg MSVC) do not support the detect idiom on // std::hash. In those platforms the last fallback will be std::hash and // InvokeHash() will always have a valid overload even if std::hash is not // valid. // // We try the following options in order: // * If is_uniquely_represented, hash bytes directly. // * ADL AbslHashValue(H, const T&) call. // * std::hash #if defined(ABSL_INTERNAL_LEGACY_HASH_NAMESPACE) && \ ABSL_META_INTERNAL_STD_HASH_SFINAE_FRIENDLY_ #define ABSL_HASH_INTERNAL_SUPPORT_LEGACY_HASH_ 1 #else #define ABSL_HASH_INTERNAL_SUPPORT_LEGACY_HASH_ 0 #endif enum class InvokeHashTag { kUniquelyRepresented, kHashValue, #if ABSL_HASH_INTERNAL_SUPPORT_LEGACY_HASH_ kLegacyHash, #endif // ABSL_HASH_INTERNAL_SUPPORT_LEGACY_HASH_ kStdHash, kNone }; // HashSelect // // Type trait to select the appropriate hash implementation to use. // HashSelect::value is an instance of InvokeHashTag that indicates the best // available hashing mechanism. // See `Note` above about MSVC. template struct HashSelect { private: struct State : HashStateBase { static State combine_contiguous(State hash_state, const unsigned char*, size_t); using State::HashStateBase::combine_contiguous; }; // `Probe::value` evaluates to `V::value` if it is a valid // expression, and `false` otherwise. // `Probe::tag` always evaluates to `Tag`. template