hana/fwd/ordering.hpp

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