111 lines
4.0 KiB
C++
111 lines
4.0 KiB
C++
/*!
|
|
@file
|
|
Forward declares `boost::hana::monadic_fold_left`.
|
|
|
|
@copyright Louis Dionne 2013-2017
|
|
Distributed under the Boost Software License, Version 1.0.
|
|
(See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
|
|
*/
|
|
|
|
#ifndef BOOST_HANA_FWD_MONADIC_FOLD_LEFT_HPP
|
|
#define BOOST_HANA_FWD_MONADIC_FOLD_LEFT_HPP
|
|
|
|
#include <boost/hana/config.hpp>
|
|
#include <boost/hana/core/when.hpp>
|
|
|
|
|
|
namespace boost { namespace hana {
|
|
//! Monadic left-fold of a structure with a binary operation and an
|
|
//! optional initial reduction state.
|
|
//! @ingroup group-Foldable
|
|
//!
|
|
//! @note
|
|
//! This assumes the reader to be accustomed to non-monadic left-folds as
|
|
//! explained by `hana::fold_left`, and to have read the [primer]
|
|
//! (@ref monadic-folds) on monadic folds.
|
|
//!
|
|
//! `monadic_fold_left<M>` is a left-associative monadic fold. Given a
|
|
//! `Foldable` with linearization `[x1, ..., xn]`, a function `f` and an
|
|
//! optional initial state, `monadic_fold_left<M>` applies `f` as follows:
|
|
//! @code
|
|
//! // with state
|
|
//! ((((f(state, x1) | f(-, x2)) | f(-, x3)) | ...) | f(-, xn))
|
|
//!
|
|
//! // without state
|
|
//! ((((f(x1, x2) | f(-, x3)) | f(-, x4)) | ...) | f(-, xn))
|
|
//! @endcode
|
|
//!
|
|
//! where `f(-, xk)` denotes the partial application of `f` to `xk`, and
|
|
//! `|` is just the operator version of the monadic `chain`.
|
|
//!
|
|
//! When the structure is empty, one of two things may happen. If an
|
|
//! initial state was provided, it is lifted to the given Monad and
|
|
//! returned as-is. Otherwise, if the no-state version of the function
|
|
//! was used, an error is triggered. When the stucture contains a single
|
|
//! element and the no-state version of the function was used, that
|
|
//! single element is lifted into the given Monad and returned as is.
|
|
//!
|
|
//!
|
|
//! Signature
|
|
//! ---------
|
|
//! Given a `Monad` `M`, a `Foldable` `F`, an initial state of tag `S`,
|
|
//! and a function @f$ f : S \times T \to M(S) @f$, the signatures of
|
|
//! `monadic_fold_left<M>` are
|
|
//! \f[
|
|
//! \mathtt{monadic\_fold\_left}_M :
|
|
//! F(T) \times S \times (S \times T \to M(S)) \to M(S)
|
|
//! \f]
|
|
//!
|
|
//! for the version with an initial state, and
|
|
//! \f[
|
|
//! \mathtt{monadic\_fold\_left}_M :
|
|
//! F(T) \times (T \times T \to M(T)) \to M(T)
|
|
//! \f]
|
|
//!
|
|
//! for the version without an initial state.
|
|
//!
|
|
//! @tparam M
|
|
//! The Monad representing the monadic context in which the fold happens.
|
|
//! The return type of `f` must be in that Monad.
|
|
//!
|
|
//! @param xs
|
|
//! The structure to fold.
|
|
//!
|
|
//! @param state
|
|
//! The initial value used for folding. If the structure is empty, this
|
|
//! value is lifted in to the `M` Monad and then returned as-is.
|
|
//!
|
|
//! @param f
|
|
//! A binary function called as `f(state, x)`, where `state` is the result
|
|
//! accumulated so far and `x` is an element in the structure. The
|
|
//! function must return its result inside the `M` Monad.
|
|
//!
|
|
//!
|
|
//! Example
|
|
//! -------
|
|
//! @include example/monadic_fold_left.cpp
|
|
#ifdef BOOST_HANA_DOXYGEN_INVOKED
|
|
template <typename M>
|
|
constexpr auto monadic_fold_left = [](auto&& xs[, auto&& state], auto&& f) -> decltype(auto) {
|
|
return tag-dispatched;
|
|
};
|
|
#else
|
|
template <typename T, typename = void>
|
|
struct monadic_fold_left_impl : monadic_fold_left_impl<T, when<true>> { };
|
|
|
|
template <typename M>
|
|
struct monadic_fold_left_t {
|
|
template <typename Xs, typename State, typename F>
|
|
constexpr decltype(auto) operator()(Xs&& xs, State&& state, F&& f) const;
|
|
|
|
template <typename Xs, typename F>
|
|
constexpr decltype(auto) operator()(Xs&& xs, F&& f) const;
|
|
};
|
|
|
|
template <typename M>
|
|
BOOST_HANA_INLINE_VARIABLE constexpr monadic_fold_left_t<M> monadic_fold_left{};
|
|
#endif
|
|
}} // end namespace boost::hana
|
|
|
|
#endif // !BOOST_HANA_FWD_MONADIC_FOLD_LEFT_HPP
|