## Expand description

Functors and monads in Rust

*Note:* This crate has some limitations. Be sure to read the “Caveats”
section below.

## Functors

The following traits are provided to describe functors:

`Functor`

is a generic trait that provides an`fmap`

method, which is a generalization of`Option::map`

,`Result::map`

, and so on, and which is implemented for a variety of types in the standard library.`FunctorSelf`

is a special case of`Functor`

where types aren’t changed when mapping. It is automatically implemented through a blanket implementation and it must be added as a bound when mapping a type to itself.`FunctorMut`

is a special case of`FunctorSelf`

whose`fmap_mut`

method operates on`&mut self`

. It is not implemented automatically, but this crate provides implementations for all types in the standard library for which`Functor`

is implemented.

## Contravariant functors

The following traits are provided to describe contravariant functors, e.g.
a `Writer<B>`

that can be converted to a `Writer<A>`

using an `Fn(A) -> B`

.

`Contravariant`

(akin to`Functor`

)`ContravariantSelf`

(akin to`FunctorSelf`

)`ContravariantMut`

(akin to`FunctorMut`

)

## Monads

The `Monad`

trait describes functors which are also monads. Its
supertrait `Pure`

allows wrapping a single value. (`Pure::pure`

is
equivalent to what’s usually called “return” in the context of monads).
Nested monads implement `NestedMonad`

through a blanket implementation.

## Applicative functors

For applicative functors see the `Applicative`

trait.

## Caveats

From the trait definitions in this crate, Rust can’t always deduce type
equality or deduce the implemented traits automatically. This may result in
complex (possibly viral) type bounds being required, which may strongly
**limit the usability of this crate.** Consider the following examples:

```
fn foo1<'a, T>(functor: T) -> T
where
T: Functor<'a, u16, Inner = u8>,
{
functor.fmap(|x| x as u16).fmap(|x| x as u8) // works
}
```

```
fn foo2<'a, T>(functor: T)
where
T: Functor<'a, u16, Inner = u8>,
T: Functor<'a, u32, Inner = u16>,
{
let _ = functor.fmap(|x| x as u16).fmap(|x| x as u32); // fails
}
```

```
fn foo3<'a, T>(functor: T)
where
T: Functor<'a, u16, Inner = u8>,
T::Mapped: Functor<'a, u32, Inner = u16>, // this is needed instead
{
let _ = functor.fmap(|x| x as u16).fmap(|x| x as u32);
}
```

Also see `FunctorSelf`

for a workaround in the most simple cases.

## Traits

- An applicative
`Functor`

- Contravariant functor
- Same as
`ContravariantSelf`

but works on`&mut self`

- A
`Contravariant`

functor that can be mapped to itself - Generic type (e.g.
`T<A>`

) whose inner type can be mapped (e.g. resulting in`T<B>`

) - Same as
`Functor`

but works on`&mut self`

- A
`Functor`

that can be mapped to itself - A
`Functor`

that is also a monad - Nested monad that can be joined

## Functions

- Generic implementation of
`Functor::fmap`

for`Applicative`

functors - Generic implementation of
`Applicative::apply`

for`Monad`

s - Generic implementation of
`Functor::fmap`

for`Monad`

s