The MonadPlus
concept represents Monads with a monoidal structure.
Intuitively, whereas a Monad can be seen as some kind of container or context, a MonadPlus can be seen as a container or a context that can be concatenated with other containers or contexts. There must also be an identity element for this combining operation. For example, a tuple is a MonadPlus, because tuples can be concatenated and the empty tuple would act as an identity for concatenation. How is this different from a Monad which is also a Monoid? The answer is that the monoidal structure on a MonadPlus must not depend of the contents of the structure; it must not require the contents to be a Monoid in order to work.
While sequences are not the only possible model for MonadPlus, the method names used here refer to the MonadPlus of sequences under concatenation. Several useful functions generalizing operations on sequences are included with this concept, like append
, prepend
and filter
.
concat
and empty
First, a MonadPlus is required to have a monoidal structure. Hence, it is no surprise that for any MonadPlus M
, we require M(T)
to be a valid monoid. However, we do not enforce that M(T)
actually models the Monoid concept provided by Hana. Further, for all objects a, b, c
of data type M(T)
,
Secondly, a MonadPlus is also required to obey the following laws, which represent the fact that empty<M(T)>()
must be some kind of absorbing element for the chain
operation. For all objects a
of data type M(T)
and functions \( f : T \to M(U) \),
Functor
, Applicative
and Monad
Variables | |
constexpr auto | boost::hana::append |
Append an element to a monadic structure.Given an element x and a monadic structure xs , append returns a new monadic structure which is the result of lifting x into the monadic structure and then combining that (to the right) with xs . In other words,. More... | |
constexpr auto | boost::hana::concat |
Combine two monadic structures together.Given two monadic structures, concat combines them together and returns a new monadic structure. The exact definition of concat will depend on the exact model of MonadPlus at hand, but for sequences it corresponds intuitively to simple concatenation. More... | |
constexpr auto | boost::hana::cycle |
Combine a monadic structure with itself n times.Given a monadic structure xs and a non-negative number n , cycle returns a new monadic structure which is the result of combining xs with itself n times using the concat operation. In other words,. More... | |
template<typename M > | |
constexpr auto | boost::hana::empty |
Identity of the monadic combination concat . More... | |
constexpr auto | boost::hana::filter |
Filter a monadic structure using a custom predicate.Given a monadic structure and a predicate, filter returns a new monadic structure containing only those elements that satisfy the predicate. This is a generalization of the usual filter function for sequences; it works for any MonadPlus. Intuitively, filter is somewhat equivalent to: More... | |
constexpr auto | boost::hana::prefix |
Inserts a value before each element of a monadic structure.Given a monadic structure xs and a value z called the prefix, prefix returns a new monadic structure. prefix satisfies. More... | |
constexpr auto | boost::hana::prepend |
Prepend an element to a monadic structure.Given a monadic structure xs and an element x , prepend returns a new monadic structure which is the result of lifting x into the monadic structure and then combining that (to the left) with xs . In other words,. More... | |
constexpr auto | boost::hana::remove |
Remove all the elements of a monadic structure that are equal to some value.Given a monadic structure xs and a value , remove returns a new monadic structure equal to xs without all its elements that are equal to the given value . remove is equivalent to remove_if with the equal.to(value) predicate, i.e. More... | |
constexpr auto | boost::hana::remove_if |
Remove all the elements of a monadic structure that satisfy some predicate.Given a monadic structure xs and a unary predicate, remove_if returns a new monadic structure equal to xs without all its elements that satisfy the predicate. This is equivalent to filter with a negated predicate, i.e. More... | |
template<typename M > | |
constexpr auto | boost::hana::replicate |
Create a monadic structure by combining a lifted value with itself n times.Given a value x , a non-negative IntegralConstant n and the tag of a monadic structure M , replicate creates a new monadic structure which is the result of combining x with itself n times inside the monadic structure. In other words, replicate simply lift s x into the monadic structure, and then combines that with itself n times: More... | |
constexpr auto | boost::hana::suffix |
Inserts a value after each element of a monadic structure.Given a monadic structure xs and a value z (called the suffix), suffix returns a new monadic structure such that. More... | |
constexpr auto boost::hana::append |
#include <boost/hana/fwd/append.hpp>
Append an element to a monadic structure.Given an element x
and a monadic structure xs
, append
returns a new monadic structure which is the result of lifting x
into the monadic structure and then combining that (to the right) with xs
. In other words,.
where Xs
is the tag of xs
. For sequences, this has the intuitive behavior of simply appending an element to the end of the sequence, hence the name.
Rationale for not calling this
push_back
See the rationale for using
prepend
instead ofpush_front
.
Given a MonadPlus M
, the signature is \( \mathtt{append} : M(T) \times T \to M(T) \).
xs | A monadic structure that will be combined to the left of the element. |
x | An element to combine to the right of the monadic structure. |
constexpr auto boost::hana::concat |
#include <boost/hana/fwd/concat.hpp>
Combine two monadic structures together.Given two monadic structures, concat
combines them together and returns a new monadic structure. The exact definition of concat
will depend on the exact model of MonadPlus at hand, but for sequences it corresponds intuitively to simple concatenation.
Also note that combination is not required to be commutative. In other words, there is no requirement that
and indeed it does not hold in general.
Given a MonadPlus
M
, the signature of concat
is \( \mathtt{concat} : M(T) \times M(T) \to M(T) \).
xs,ys | Two monadic structures to combine together. |
constexpr auto boost::hana::cycle |
#include <boost/hana/fwd/cycle.hpp>
Combine a monadic structure with itself n
times.Given a monadic structure xs
and a non-negative number n
, cycle
returns a new monadic structure which is the result of combining xs
with itself n
times using the concat
operation. In other words,.
Also note that since concat
is required to be associative, we could also have written
If n
is zero, then the identity of concat
, empty
, is returned. In the case of sequences, this boils down to returning a sequence containing n
copies of itself; for other models it might differ.
Given an IntegralConstant
C
and a MonadPlus
M
, the signature is \( \mathrm{cycle} : M(T) \times C \to M(T) \).
xs | A monadic structure to combine with itself a certain number of times. |
n | A non-negative IntegralConstant representing the number of times to combine the monadic structure with itself. If n is zero, cycle returns empty . |
constexpr auto boost::hana::empty |
#include <boost/hana/fwd/empty.hpp>
Identity of the monadic combination concat
.
Given a MonadPlus M
, the signature is \( \mathtt{empty}_M : \emptyset \to M(T) \).
M | The tag of the monadic structure to return. This must be a model of the MonadPlus concept. |
constexpr auto boost::hana::filter |
#include <boost/hana/fwd/filter.hpp>
Filter a monadic structure using a custom predicate.Given a monadic structure and a predicate, filter
returns a new monadic structure containing only those elements that satisfy the predicate. This is a generalization of the usual filter
function for sequences; it works for any MonadPlus. Intuitively, filter
is somewhat equivalent to:
In other words, we basically turn a monadic structure containing [x1, ..., xn]
into a monadic structure containing
and we then flatten
that.
Given a MonadPlus
M
and an IntegralConstant
Bool
holding a value of type bool
, the signature is \( \mathtt{filter} : M(T) \times (T \to \mathtt{Bool}) \to M(T) \).
xs | The monadic structure to filter. |
pred | A function called as pred(x) for each element x in the monadic structure and returning whether that element should be kept in the resulting structure. In the current version of the library, the predicate has to return an IntegralConstant holding a value convertible to a bool . |
constexpr auto boost::hana::prefix |
#include <boost/hana/fwd/prefix.hpp>
Inserts a value before each element of a monadic structure.Given a monadic structure xs
and a value z
called the prefix, prefix
returns a new monadic structure. prefix
satisfies.
For sequences, this simply corresponds to inserting the prefix before each element of the sequence. For example, given a sequence [x1, ..., xn]
, prefix
will return
As explained above, this can be generalized to other MonadPlus models, with various levels of interest.
Given a MonadPlus M
, the signature is \( \mathrm{prefix} : M(T) \times T \to M(T) \).
xs | A monadic structure. |
pref | A value (the prefix) to insert before each element of a monadic structure. |
constexpr auto boost::hana::prepend |
#include <boost/hana/fwd/prepend.hpp>
Prepend an element to a monadic structure.Given a monadic structure xs
and an element x
, prepend
returns a new monadic structure which is the result of lifting x
into the monadic structure and then combining that (to the left) with xs
. In other words,.
For sequences, this has the intuitive behavior of simply prepending an element to the beginning of the sequence, hence the name.
Rationale for not calling this
push_front
While
push_front
is the de-facto name used in the standard library, it also strongly suggests mutation of the underlying sequence, which is not the case here. The author also finds thatpush_front
suggests too strongly the sole interpretation of putting an element to the front of a sequence, whereasprepend
is slightly more nuanced and bears its name better for e.g.hana::optional
.
Given a MonadPlus M
, the signature is \( \mathtt{prepend} : M(T) \times T \to M(T) \).
xs | A monadic structure that will be combined to the right of the element. |
x | An element to combine to the left of the monadic structure. |
constexpr auto boost::hana::remove |
#include <boost/hana/fwd/remove.hpp>
Remove all the elements of a monadic structure that are equal to some value.Given a monadic structure xs
and a value
, remove
returns a new monadic structure equal to xs
without all its elements that are equal to the given value
. remove
is equivalent to remove_if
with the equal.to(value)
predicate, i.e.
Given a MonadPlus M
and a value of type T
, the signature is \( \mathrm{remove} : M(T) \times T \to M(T) \)
xs | A monadic structure to remove some elements from. |
value | A value that is compared to every element x of the structure. Elements of the structure that are equal to that value are removed from the structure. This requires every element to be Comparable with value . Furthermore, in the current version of the library, comparing value with any element of the structure must yield a compile-time Logical. |
constexpr auto boost::hana::remove_if |
#include <boost/hana/fwd/remove_if.hpp>
Remove all the elements of a monadic structure that satisfy some predicate.Given a monadic structure xs
and a unary predicate, remove_if
returns a new monadic structure equal to xs
without all its elements that satisfy the predicate. This is equivalent to filter
with a negated predicate, i.e.
Given a MonadPlus M
and a predicate of type \( T \to Bool \) for some compile-time Logical Bool
, the signature is \( \mathrm{remove\_if} : M(T) \times (T \to Bool) \to M(T) \)
xs | A monadic structure to remove some elements from. |
predicate | A unary predicate called as predicate(x) , where x is an element of the structure, and returning whether x should be removed from the structure. In the current version of the library, predicate must return a compile-time Logical. |
constexpr auto boost::hana::replicate |
#include <boost/hana/fwd/replicate.hpp>
Create a monadic structure by combining a lifted value with itself n
times.Given a value x
, a non-negative IntegralConstant
n
and the tag of a monadic structure M
, replicate
creates a new monadic structure which is the result of combining x
with itself n
times inside the monadic structure. In other words, replicate
simply lift
s x
into the monadic structure, and then combines that with itself n
times:
If n
is zero, then the identity of the concat
operation is returned. In the case of sequences, this corresponds to creating a new sequence holding n
copies of x
.
Given an IntegralConstant
C
and MonadPlus M
, the signature is \( \mathtt{replicate}_M : T \times C \to M(T) \).
M | The tag of the returned monadic structure. It must be a model of the MonadPlus concept. |
x | The value to lift into a monadic structure and then combine with itself. |
n | A non-negative IntegralConstant representing the number of times to combine lift<M>(x) with itself. If n == 0 , replicate returns empty<M>() . |
constexpr auto boost::hana::suffix |
#include <boost/hana/fwd/suffix.hpp>
Inserts a value after each element of a monadic structure.Given a monadic structure xs
and a value z
(called the suffix), suffix
returns a new monadic structure such that.
For sequences, this simply corresponds to inserting the suffix after each element of the sequence. For example, given a sequence [x1, ..., xn]
, suffix
will return
As explained above, this can be generalized to other MonadPlus models, with various levels of interest.
Given a MonadPlus M
, the signature is \( \mathtt{suffix} : M(T) \times T \to M(T) \).
xs | A monadic structure. |
sfx | A value (the suffix) to insert after each element of a monadic structure. |