fwd/concept/hashable.hpp

0001 /*!
0002 @file
0003 Forward declares `boost::hana::Hashable`.
0004
0005 Copyright Louis Dionne 2016
0006 Copyright Jason Rice 2016
0007 Distributed under the Boost Software License, Version 1.0.
0008 (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
0009  */
0010
0011 #ifndef BOOST_HANA_FWD_CONCEPT_HASHABLE_HPP
0012 #define BOOST_HANA_FWD_CONCEPT_HASHABLE_HPP
0013
0014 #include <boost/hana/config.hpp>
0015
0016
0017 namespace boost { namespace hana {
0018     //! @ingroup group-concepts
0019     //! @defgroup group-Hashable Hashable
0020     //! The `Hashable` concept represents objects that can be normalized to
0021     //! a type-level hash.
0022     //!
0023     //! In day to day programming, hashes are very important as a way to
0024     //! efficiently lookup objects in maps. While the implementation of
0025     //! maps is very different, the same idea of using hashes for efficient
0026     //! lookup applies in metaprogramming. The `Hashable` concept represents
0027     //! objects that can be summarized (possibly with loss of information) to
0028     //! a type, in a way suitable for use in hash-based data structures. Of
0029     //! course, in order for a hash to be well-behaved, it must obey some laws
0030     //! that are explained below.
0031     //!
0032     //!
0033     //! Minimal complete definition
0034     //! ---------------------------
0035     //! `hash`, satisfying the laws below
0036     //!
0037     //!
0038     //! Laws
0039     //! ----
0040     //! First, `hana::hash` must return a `hana::type`. Furthermore, for any
0041     //! two `Hashable` objects `x` and `y`, it must be the case that
0042     //! @code
0043     //!     x == y   implies   hash(x) == hash(y)
0044     //! @endcode
0045     //!
0046     //! where `==` denotes `hana::equal`. In other words, any two objects that
0047     //! compare equal (with `hana::equal`) must also have the same hash.
0048     //! However, the reverse is not true, and two different objects may have
0049     //! the same hash. This situation of two different objects having the same
0050     //! hash is called a _collision_.
0051     //!
0052     //!
0053     //! Concrete models
0054     //! ---------------
0055     //! `hana::integral_constant`, `hana::type`, `hana::string`
0056     //!
0057     //!
0058     //! Free model for `IntegralConstant`s
0059     //! ----------------------------------
0060     //! Any `IntegralConstant` is `Hashable`, by normalizing its value to a
0061     //! `hana::integral_constant`. The type of the value held in the normalized
0062     //! `integral_constant` is `unsigned long long` for unsigned integral
0063     //! types, and `signed long long` for signed integral types.
0064     template <typename T>
0065     struct Hashable;
0066 }} // end namespace boost::hana
0067
0068 #endif // !BOOST_HANA_FWD_CONCEPT_HASHABLE_HPP