ceph/src/boost/libs/hana/include/boost/hana/fwd/concept/monad_plus.hpp

   1 /*!
   2 @file
   3 Forward declares `boost::hana::MonadPlus`.
   4
   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)
   8  */
   9
  10 #ifndef BOOST_HANA_FWD_CONCEPT_MONAD_PLUS_HPP
  11 #define BOOST_HANA_FWD_CONCEPT_MONAD_PLUS_HPP
  12
  13 #include <boost/hana/config.hpp>
  14
  15
  16 BOOST_HANA_NAMESPACE_BEGIN
  17     //! @ingroup group-concepts
  18     //! @defgroup group-MonadPlus MonadPlus
  19     //! The `MonadPlus` concept represents Monads with a monoidal structure.
  20     //!
  21     //! Intuitively, whereas a Monad can be seen as some kind of container
  22     //! or context, a MonadPlus can be seen as a container or a context that
  23     //! can be concatenated with other containers or contexts. There must
  24     //! also be an identity element for this combining operation. For example,
  25     //! a tuple is a MonadPlus, because tuples can be concatenated and the
  26     //! empty tuple would act as an identity for concatenation. How is this
  27     //! different from a Monad which is also a Monoid? The answer is that the
  28     //! monoidal structure on a MonadPlus must _not_ depend of the contents
  29     //! of the structure; it must not require the contents to be a Monoid
  30     //! in order to work.
  31     //!
  32     //! While sequences are not the only possible model for MonadPlus, the
  33     //! method names used here refer to the MonadPlus of sequences under
  34     //! concatenation. Several useful functions generalizing operations on
  35     //! sequences are included with this concept, like `append`, `prepend`
  36     //! and `filter`.
  37     //!
  38     //! @note
  39     //! This documentation does not go into much details about the nature
  40     //! of the MonadPlus concept. However, there is a nice Haskell-oriented
  41     //! [WikiBook][1] going into further details.
  42     //!
  43     //!
  44     //! Minimal complete definition
  45     //! ---------------------------
  46     //! `concat` and `empty`
  47     //!
  48     //!
  49     //! Laws
  50     //! ----
  51     //! First, a MonadPlus is required to have a monoidal structure. Hence, it
  52     //! is no surprise that for any MonadPlus `M`, we require `M(T)` to be a
  53     //! valid monoid. However, we do not enforce that `M(T)` actually models
  54     //! the Monoid concept provided by Hana. Further, for all objects `a, b, c`
  55     //! of data type `M(T)`,
  56     //! @code
  57     //!     // identity
  58     //!     concat(empty<M(T)>(), a) == a
  59     //!     concat(a, empty<M(T)>()) == a
  60     //!
  61     //!     // associativity
  62     //!     concat(a, concat(b, c)) == concat(concat(a, b), c)
  63     //! @endcode
  64     //!
  65     //! Secondly, a MonadPlus is also required to obey the following laws,
  66     //! which represent the fact that `empty<M(T)>()` must be some kind of
  67     //! absorbing element for the `chain` operation. For all objects `a` of
  68     //! data type `M(T)` and functions @f$ f : T \to M(U) @f$,
  69     //! @code
  70     //!     chain(empty<M(T)>(), f)         == empty<M(U)>()
  71     //!     chain(a, always(empty<M(T)>())) == empty<M(U)>()
  72     //! @endcode
  73     //!
  74     //!
  75     //! Refined concepts
  76     //! ----------------
  77     //! `Functor`, `Applicative` and `Monad`
  78     //!
  79     //!
  80     //! Concrete models
  81     //! ---------------
  82     //! `hana::optional`, `hana::tuple`
  83     //!
  84     //! [1]: https://en.wikibooks.org/wiki/Haskell/MonadPlus
  85     template <typename M>
  86     struct MonadPlus;
  87 BOOST_HANA_NAMESPACE_END
  88
  89 #endif // !BOOST_HANA_FWD_CONCEPT_MONAD_PLUS_HPP