hana/fwd/comparing.hpp

0001 /*!
0002 @file
0003 Forward declares `boost::hana::comparing`.
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_COMPARING_HPP
0011 #define BOOST_HANA_FWD_COMPARING_HPP
0012
0013 #include <boost/hana/config.hpp>
0014
0015
0016 namespace boost { namespace hana {
0017     //! Returns a function performing `equal` after applying a transformation
0018     //! to both arguments.
0019     //! @ingroup group-Comparable
0020     //!
0021     //! `comparing` creates an equivalence relation based on the result of
0022     //! applying a function to some objects, which is especially useful in
0023     //! conjunction with algorithms that accept a custom predicate that must
0024     //! represent an equivalence relation.
0025     //!
0026     //! Specifically, `comparing` is such that
0027     //! @code
0028     //!     comparing(f) == equal ^on^ f
0029     //! @endcode
0030     //! or, equivalently,
0031     //! @code
0032     //!     comparing(f)(x, y) == equal(f(x), f(y))
0033     //! @endcode
0034     //!
0035     //! @note
0036     //! This is not a tag-dispatched method (hence it can't be customized),
0037     //! but just a convenience function provided with the `Comparable` concept.
0038     //!
0039     //!
0040     //! Signature
0041     //! ---------
0042     //! Given a Logical `Bool` and a Comparable `B`, the signature is
0043     //! @f$ \mathtt{comparing} : (A \to B) \to (A \times A \to Bool) @f$.
0044     //!
0045     //!
0046     //! Example
0047     //! -------
0048     //! @include example/comparing.cpp
0049 #ifdef BOOST_HANA_DOXYGEN_INVOKED
0050     constexpr auto comparing = [](auto&& f) {
0051         return [perfect-capture](auto&& x, auto&& y) {
0052             return equal(f(forwarded(x)), f(forwarded(y)));
0053         };
0054     };
0055 #else
0056     struct comparing_t {
0057         template <typename F>
0058         constexpr auto operator()(F&& f) const;
0059     };
0060
0061     BOOST_HANA_INLINE_VARIABLE constexpr comparing_t comparing{};
0062 #endif
0063 }} // end namespace boost::hana
0064
0065 #endif // !BOOST_HANA_FWD_COMPARING_HPP