ceph/src/boost/boost/hana/fwd/monadic_fold_left.hpp

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