hana/fwd/equal.hpp

0001 /*!
0002 @file
0003 Forward declares `boost::hana::equal`.
0004
0005 Copyright Louis Dionne 2013-2022
0006 Distributed under the Boost Software License, Version 1.0.
0007 (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
0008  */
0009
0010 #ifndef BOOST_HANA_FWD_EQUAL_HPP
0011 #define BOOST_HANA_FWD_EQUAL_HPP
0012
0013 #include <boost/hana/config.hpp>
0014 #include <boost/hana/core/when.hpp>
0015 #include <boost/hana/detail/nested_to_fwd.hpp>
0016
0017
0018 namespace boost { namespace hana {
0019     //! Returns a `Logical` representing whether `x` is equal to `y`.
0020     //! @ingroup group-Comparable
0021     //!
0022     //! The `equal` function can be called in two different ways. First, it
0023     //! can be called like a normal function:
0024     //! @code
0025     //!     equal(x, y)
0026     //! @endcode
0027     //!
0028     //! However, it may also be partially applied to an argument by using
0029     //! `equal.to`:
0030     //! @code
0031     //!     equal.to(x)(y) == equal(x, y)
0032     //! @endcode
0033     //!
0034     //! In other words, `equal.to(x)` is a function object that is equivalent
0035     //! to `partial(equal, x)`. This is provided to enhance the readability of
0036     //! some constructs, especially when using higher order algorithms.
0037     //!
0038     //!
0039     //! Signature
0040     //! ---------
0041     //! Given a Logical `Bool` and two Comparables `A` and `B` that
0042     //! share a common embedding, the signature is
0043     //! @f$ \mathtt{equal} : A \times B \to Bool @f$.
0044     //!
0045     //! @param x, y
0046     //! Two objects to compare for equality.
0047     //!
0048     //!
0049     //! Example
0050     //! -------
0051     //! @include example/equal.cpp
0052     //!
0053     //!
0054     //! > #### Rationale for the arity of `equal`
0055     //! > It is a valid question whether `equal` should accept more than 2
0056     //! > arguments and have semantics matching those of Python's `==`. This
0057     //! > is not supported right now for the following reasons:
0058     //! > - It was implemented in the MPL11, but it was not shown to be useful
0059     //! >   so far.
0060     //! > - It does not make sense for `not_equal` to have an arity of more
0061     //! >   than 2, only `equal` could maybe have those semantics, which would
0062     //! >   break symmetry.
0063 #ifdef BOOST_HANA_DOXYGEN_INVOKED
0064     constexpr auto equal = [](auto&& x, auto&& y) {
0065         return tag-dispatched;
0066     };
0067 #else
0068     template <typename T, typename U, typename = void>
0069     struct equal_impl : equal_impl<T, U, when<true>> { };
0070
0071     struct equal_t : detail::nested_to<equal_t> {
0072         template <typename X, typename Y>
0073         constexpr auto operator()(X&& x, Y&& y) const;
0074     };
0075
0076     BOOST_HANA_INLINE_VARIABLE constexpr equal_t equal{};
0077 #endif
0078 }} // end namespace boost::hana
0079
0080 #endif // !BOOST_HANA_FWD_EQUAL_HPP