3 Forward declares `boost::hana::monadic_fold_right`.
5 @copyright Louis Dionne 2013-2016
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)
10 #ifndef BOOST_HANA_FWD_MONADIC_FOLD_RIGHT_HPP
11 #define BOOST_HANA_FWD_MONADIC_FOLD_RIGHT_HPP
13 #include <boost/hana/config.hpp>
14 #include <boost/hana/core/when.hpp>
17 BOOST_HANA_NAMESPACE_BEGIN
18 //! Monadic right-fold of a structure with a binary operation and an
19 //! optional initial reduction state.
20 //! @ingroup group-Foldable
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.
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
32 //! (f(x1, -) | (f(x2, -) | (f(x3, -) | (... | f(xn, state)))))
35 //! (f(x1, -) | (f(x2, -) | (f(x3, -) | (... | f(xn-1, xn)))))
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>`.
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.
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
57 //! \mathtt{monadic\_fold\_right}_M :
58 //! F(T) \times S \times (T \times S \to M(S)) \to M(S)
61 //! for the version with an initial state, and
63 //! \mathtt{monadic\_fold\_right}_M :
64 //! F(T) \times (T \times T \to M(T)) \to M(T)
67 //! for the version without an initial state.
70 //! The Monad representing the monadic context in which the fold happens.
71 //! The return type of `f` must be in that Monad.
74 //! The structure to fold.
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.
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.
88 //! @include example/monadic_fold_right.cpp
89 #ifdef BOOST_HANA_DOXYGEN_INVOKED
91 constexpr auto monadic_fold_right = [](auto&& xs[, auto&& state], auto&& f) -> decltype(auto) {
92 return tag-dispatched;
95 template <typename T, typename = void>
96 struct monadic_fold_right_impl : monadic_fold_right_impl<T, when<true>> { };
99 struct monadic_fold_right_t;
101 template <typename M>
102 constexpr monadic_fold_right_t<M> monadic_fold_right{};
104 BOOST_HANA_NAMESPACE_END
106 #endif // !BOOST_HANA_FWD_MONADIC_FOLD_RIGHT_HPP