1 /*! 2 @file 3 Forward declares `boost::hana::monadic_fold_right`. 4 5 @copyright Louis Dionne 2013-2017 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 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 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 constexpr monadic_fold_right_t<M> monadic_fold_right{}; 109 #endif 110 BOOST_HANA_NAMESPACE_END 111 112 #endif // !BOOST_HANA_FWD_MONADIC_FOLD_RIGHT_HPP 113