boost/hana/fwd/equal.hpp

   1 /*!
   2 @file
   3 Forward declares `boost::hana::equal`.
   4
   5 @copyright Louis Dionne 2013-2017
   6 Distributed under the Boost Software License, Version 1.0.
   7 (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
   8  */
   9
  10 #ifndef BOOST_HANA_FWD_EQUAL_HPP
  11 #define BOOST_HANA_FWD_EQUAL_HPP
  12
  13 #include <boost/hana/config.hpp>
  14 #include <boost/hana/core/when.hpp>
  15 #include <boost/hana/detail/nested_to_fwd.hpp>
  16
  17
  18 BOOST_HANA_NAMESPACE_BEGIN
  19     //! Returns a `Logical` representing whether `x` is equal to `y`.
  20     //! @ingroup group-Comparable
  21     //!
  22     //! The `equal` function can be called in two different ways. First, it
  23     //! can be called like a normal function:
  24     //! @code
  25     //!     equal(x, y)
  26     //! @endcode
  27     //!
  28     //! However, it may also be partially applied to an argument by using
  29     //! `equal.to`:
  30     //! @code
  31     //!     equal.to(x)(y) == equal(x, y)
  32     //! @endcode
  33     //!
  34     //! In other words, `equal.to(x)` is a function object that is equivalent
  35     //! to `partial(equal, x)`. This is provided to enhance the readability of
  36     //! some constructs, especially when using higher order algorithms.
  37     //!
  38     //!
  39     //! Signature
  40     //! ---------
  41     //! Given a Logical `Bool` and two Comparables `A` and `B` that
  42     //! share a common embedding, the signature is
  43     //! @f$ \mathtt{equal} : A \times B \to Bool @f$.
  44     //!
  45     //! @param x, y
  46     //! Two objects to compare for equality.
  47     //!
  48     //!
  49     //! Example
  50     //! -------
  51     //! @include example/equal.cpp
  52     //!
  53     //!
  54     //! > #### Rationale for the arity of `equal`
  55     //! > It is a valid question whether `equal` should accept more than 2
  56     //! > arguments and have semantics matching those of Python's `==`. This
  57     //! > is not supported right now for the following reasons:
  58     //! > - It was implemented in the MPL11, but it was not shown to be useful
  59     //! >   so far.
  60     //! > - It does not make sense for `not_equal` to have an arity of more
  61     //! >   than 2, only `equal` could maybe have those semantics, which would
  62     //! >   break symmetry.
  63 #ifdef BOOST_HANA_DOXYGEN_INVOKED
  64     constexpr auto equal = [](auto&& x, auto&& y) {
  65         return tag-dispatched;
  66     };
  67 #else
  68     template <typename T, typename U, typename = void>
  69     struct equal_impl : equal_impl<T, U, when<true>> { };
  70
  71     struct equal_t : detail::nested_to<equal_t> {
  72         template <typename X, typename Y>
  73         constexpr auto operator()(X&& x, Y&& y) const;
  74     };
  75
  76     constexpr equal_t equal{};
  77 #endif
  78 BOOST_HANA_NAMESPACE_END
  79
  80 #endif // !BOOST_HANA_FWD_EQUAL_HPP