boost/hana/fwd/ordering.hpp

   1 /*!
   2 @file
   3 Forward declares `boost::hana::ordering`.
   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_ORDERING_HPP
  11 #define BOOST_HANA_FWD_ORDERING_HPP
  12
  13 #include <boost/hana/config.hpp>
  14
  15
  16 BOOST_HANA_NAMESPACE_BEGIN
  17     //! Returns a function performing `less` after applying a transformation
  18     //! to both arguments.
  19     //! @ingroup group-Orderable
  20     //!
  21     //! `ordering` creates a total order based on the result of applying a
  22     //! function to some objects, which is especially useful in conjunction
  23     //! with algorithms that accept a custom predicate that must represent
  24     //! a total order.
  25     //!
  26     //! Specifically, `ordering` is such that
  27     //! @code
  28     //!     ordering(f) == less ^on^ f
  29     //! @endcode
  30     //! or, equivalently,
  31     //! @code
  32     //!     ordering(f)(x, y) == less(f(x), f(y))
  33     //! @endcode
  34     //!
  35     //! @note
  36     //! This is not a tag-dispatched method (hence it can't be customized),
  37     //! but just a convenience function provided with the `Orderable` concept.
  38     //!
  39     //!
  40     //! Signature
  41     //! ---------
  42     //! Given a Logical `Bool` and an Orderable `B`, the signature is
  43     //! @f$ \mathrm{ordering} : (A \to B) \to (A \times A \to Bool) @f$.
  44     //!
  45     //!
  46     //! Example
  47     //! -------
  48     //! @include example/ordering.cpp
  49 #ifdef BOOST_HANA_DOXYGEN_INVOKED
  50     constexpr auto ordering = [](auto&& f) {
  51         return [perfect-capture](auto&& x, auto&& y) -> decltype(auto) {
  52             return less(f(forwarded(x)), f(forwarded(y)));
  53         };
  54     };
  55 #else
  56     struct ordering_t {
  57         template <typename F>
  58         constexpr auto operator()(F&& f) const;
  59     };
  60
  61     constexpr ordering_t ordering{};
  62 #endif
  63 BOOST_HANA_NAMESPACE_END
  64
  65 #endif // !BOOST_HANA_FWD_ORDERING_HPP