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

source code of boost/libs/hana/include/boost/hana/fwd/minimum.hpp