1/*!
2@file
3Forward declares `boost::hana::monadic_fold_right`.
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_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
17namespace boost { namespace hana {
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>
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 };
106
107 template <typename M>
108 BOOST_HANA_INLINE_VARIABLE constexpr monadic_fold_right_t<M> monadic_fold_right{};
109#endif
110}} // end namespace boost::hana
111
112#endif // !BOOST_HANA_FWD_MONADIC_FOLD_RIGHT_HPP
113

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