]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | /*! |
2 | @file | |
3 | Forward declares `boost::hana::monadic_fold_right`. | |
4 | ||
b32b8144 | 5 | @copyright Louis Dionne 2013-2017 |
7c673cae FG |
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_MONADIC_FOLD_RIGHT_HPP | |
11 | #define BOOST_HANA_FWD_MONADIC_FOLD_RIGHT_HPP | |
12 | ||
13 | #include <boost/hana/config.hpp> | |
14 | #include <boost/hana/core/when.hpp> | |
15 | ||
16 | ||
1e59de90 | 17 | namespace boost { namespace hana { |
7c673cae FG |
18 | //! Monadic right-fold of a structure with a binary operation and an |
19 | //! optional initial reduction state. | |
20 | //! @ingroup group-Foldable | |
21 | //! | |
22 | //! @note | |
23 | //! This assumes the reader to be accustomed to non-monadic right-folds as | |
24 | //! explained by `hana::fold_right`, and to have read the [primer] | |
25 | //! (@ref monadic-folds) on monadic folds. | |
26 | //! | |
27 | //! `monadic_fold_right<M>` is a right-associative monadic fold. Given a | |
28 | //! structure containing `x1, ..., xn`, a function `f` and an optional | |
29 | //! initial state, `monadic_fold_right<M>` applies `f` as follows | |
30 | //! @code | |
31 | //! // with state | |
32 | //! (f(x1, -) | (f(x2, -) | (f(x3, -) | (... | f(xn, state))))) | |
33 | //! | |
34 | //! // without state | |
35 | //! (f(x1, -) | (f(x2, -) | (f(x3, -) | (... | f(xn-1, xn))))) | |
36 | //! @endcode | |
37 | //! | |
38 | //! where `f(xk, -)` denotes the partial application of `f` to `xk`, | |
39 | //! and `|` is just the operator version of the monadic `chain`. | |
40 | //! It is worth noting that the order in which the binary function should | |
41 | //! expect its arguments is reversed from `monadic_fold_left<M>`. | |
42 | //! | |
43 | //! When the structure is empty, one of two things may happen. If an | |
44 | //! initial state was provided, it is lifted to the given Monad and | |
45 | //! returned as-is. Otherwise, if the no-state version of the function | |
46 | //! was used, an error is triggered. When the stucture contains a single | |
47 | //! element and the no-state version of the function was used, that | |
48 | //! single element is lifted into the given Monad and returned as is. | |
49 | //! | |
50 | //! | |
51 | //! Signature | |
52 | //! --------- | |
53 | //! Given a `Monad` `M`, a `Foldable` `F`, an initial state of tag `S`, | |
54 | //! and a function @f$ f : T \times S \to M(S) @f$, the signatures of | |
55 | //! `monadic_fold_right<M>` are | |
56 | //! \f[ | |
57 | //! \mathtt{monadic\_fold\_right}_M : | |
58 | //! F(T) \times S \times (T \times S \to M(S)) \to M(S) | |
59 | //! \f] | |
60 | //! | |
61 | //! for the version with an initial state, and | |
62 | //! \f[ | |
63 | //! \mathtt{monadic\_fold\_right}_M : | |
64 | //! F(T) \times (T \times T \to M(T)) \to M(T) | |
65 | //! \f] | |
66 | //! | |
67 | //! for the version without an initial state. | |
68 | //! | |
69 | //! @tparam M | |
70 | //! The Monad representing the monadic context in which the fold happens. | |
71 | //! The return type of `f` must be in that Monad. | |
72 | //! | |
73 | //! @param xs | |
74 | //! The structure to fold. | |
75 | //! | |
76 | //! @param state | |
77 | //! The initial value used for folding. If the structure is empty, this | |
78 | //! value is lifted in to the `M` Monad and then returned as-is. | |
79 | //! | |
80 | //! @param f | |
81 | //! A binary function called as `f(x, state)`, where `state` is the result | |
82 | //! accumulated so far and `x` is an element in the structure. The | |
83 | //! function must return its result inside the `M` Monad. | |
84 | //! | |
85 | //! | |
86 | //! Example | |
87 | //! ------- | |
88 | //! @include example/monadic_fold_right.cpp | |
89 | #ifdef BOOST_HANA_DOXYGEN_INVOKED | |
90 | template <typename M> | |
91 | constexpr auto monadic_fold_right = [](auto&& xs[, auto&& state], auto&& f) -> decltype(auto) { | |
92 | return tag-dispatched; | |
93 | }; | |
94 | #else | |
95 | template <typename T, typename = void> | |
96 | struct monadic_fold_right_impl : monadic_fold_right_impl<T, when<true>> { }; | |
97 | ||
98 | template <typename M> | |
92f5a8d4 TL |
99 | struct monadic_fold_right_t { |
100 | template <typename Xs, typename State, typename F> | |
101 | constexpr decltype(auto) operator()(Xs&& xs, State&& state, F&& f) const; | |
102 | ||
103 | template <typename Xs, typename F> | |
104 | constexpr decltype(auto) operator()(Xs&& xs, F&& f) const; | |
105 | }; | |
7c673cae FG |
106 | |
107 | template <typename M> | |
1e59de90 | 108 | BOOST_HANA_INLINE_VARIABLE constexpr monadic_fold_right_t<M> monadic_fold_right{}; |
7c673cae | 109 | #endif |
1e59de90 | 110 | }} // end namespace boost::hana |
7c673cae FG |
111 | |
112 | #endif // !BOOST_HANA_FWD_MONADIC_FOLD_RIGHT_HPP |