maximum.hpp 4.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116
  1. /*!
  2. @file
  3. Forward declares `boost::hana::maximum`.
  4. @copyright Louis Dionne 2013-2017
  5. Distributed under the Boost Software License, Version 1.0.
  6. (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
  7. */
  8. #ifndef BOOST_HANA_FWD_MAXIMUM_HPP
  9. #define BOOST_HANA_FWD_MAXIMUM_HPP
  10. #include <boost/hana/config.hpp>
  11. #include <boost/hana/core/when.hpp>
  12. #include <boost/hana/detail/nested_by_fwd.hpp>
  13. BOOST_HANA_NAMESPACE_BEGIN
  14. //! Return the greatest element of a non-empty structure with respect to
  15. //! a `predicate`, by default `less`.
  16. //! @ingroup group-Foldable
  17. //!
  18. //! Given a non-empty structure and an optional binary predicate
  19. //! (`less` by default), `maximum` returns the greatest element of
  20. //! the structure, i.e. an element which is greater than or equal to
  21. //! every other element in the structure, according to the predicate.
  22. //!
  23. //! If the structure contains heterogeneous objects, then the predicate
  24. //! must return a compile-time `Logical`. If no predicate is provided,
  25. //! the elements in the structure must be Orderable, or compile-time
  26. //! Orderable if the structure is heterogeneous.
  27. //!
  28. //!
  29. //! Signature
  30. //! ---------
  31. //! Given a Foldable `F`, a Logical `Bool` and a predicate
  32. //! \f$ \mathtt{pred} : T \times T \to Bool \f$, `maximum` has the
  33. //! following signatures. For the variant with a provided predicate,
  34. //! \f[
  35. //! \mathtt{maximum} : F(T) \times (T \times T \to Bool) \to T
  36. //! \f]
  37. //!
  38. //! for the variant without a custom predicate, `T` is required to be
  39. //! Orderable. The signature is then
  40. //! \f[
  41. //! \mathtt{maximum} : F(T) \to T
  42. //! \f]
  43. //!
  44. //! @param xs
  45. //! The structure to find the greatest element of.
  46. //!
  47. //! @param predicate
  48. //! A function called as `predicate(x, y)`, where `x` and `y` are elements
  49. //! of the structure. `predicate` should be a strict weak ordering on the
  50. //! elements of the structure and its return value should be a Logical,
  51. //! or a compile-time Logical if the structure is heterogeneous.
  52. //!
  53. //! ### Example
  54. //! @include example/maximum.cpp
  55. //!
  56. //!
  57. //! Syntactic sugar (`maximum.by`)
  58. //! ------------------------------
  59. //! `maximum` can be called in a third way, which provides a nice syntax
  60. //! especially when working with the `ordering` combinator:
  61. //! @code
  62. //! maximum.by(predicate, xs) == maximum(xs, predicate)
  63. //! maximum.by(predicate) == maximum(-, predicate)
  64. //! @endcode
  65. //!
  66. //! where `maximum(-, predicate)` denotes the partial application of
  67. //! `maximum` to `predicate`.
  68. //!
  69. //! ### Example
  70. //! @include example/maximum_by.cpp
  71. //!
  72. //!
  73. //! Tag dispatching
  74. //! ---------------
  75. //! Both the non-predicated version and the predicated versions of
  76. //! `maximum` are tag-dispatched methods, and hence they can be
  77. //! customized independently. One reason for this is that some
  78. //! structures are able to provide a much more efficient implementation
  79. //! of `maximum` when the `less` predicate is used. Here is how the
  80. //! different versions of `maximum` are dispatched:
  81. //! @code
  82. //! maximum(xs) -> maximum_impl<tag of xs>::apply(xs)
  83. //! maximum(xs, pred) -> maximum_pred_impl<tag of xs>::apply(xs, pred)
  84. //! @endcode
  85. //!
  86. //! Also note that `maximum.by` is not tag-dispatched on its own, since it
  87. //! is just syntactic sugar for calling the corresponding `maximum`.
  88. #ifdef BOOST_HANA_DOXYGEN_INVOKED
  89. constexpr auto maximum = [](auto&& xs[, auto&& predicate]) -> decltype(auto) {
  90. return tag-dispatched;
  91. };
  92. #else
  93. template <typename T, typename = void>
  94. struct maximum_impl : maximum_impl<T, when<true>> { };
  95. template <typename T, typename = void>
  96. struct maximum_pred_impl : maximum_pred_impl<T, when<true>> { };
  97. struct maximum_t : detail::nested_by<maximum_t> {
  98. template <typename Xs>
  99. constexpr decltype(auto) operator()(Xs&& xs) const;
  100. template <typename Xs, typename Predicate>
  101. constexpr decltype(auto) operator()(Xs&& xs, Predicate&& pred) const;
  102. };
  103. constexpr maximum_t maximum{};
  104. #endif
  105. BOOST_HANA_NAMESPACE_END
  106. #endif // !BOOST_HANA_FWD_MAXIMUM_HPP