Crate fmap

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

Applicative

An applicative Functor

Contravariant

Contravariant functor

ContravariantMut

Same as ContravariantSelf but works on &mut self

ContravariantSelf

A Contravariant functor that can be mapped to itself

Functor

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

FunctorMut

Same as Functor but works on &mut self

FunctorSelf

A Functor that can be mapped to itself

Monad

A Functor that is also a monad

MonadWithMapper

A Monad that can have a boxed mapping closure as an inner value

NestedMonad

Nested monad that can be joined

Pure

A Functor that provides a pure operation to wrap a single inner value

Functions

applicative_fmap

Generic implementation of Functor::fmap for Applicative functors

monad_apply

Generic implementation of Applicative::apply for Monads

monad_fmap

Generic implementation of Functor::fmap for Monads

Type Aliases

BoxMapper

A boxed closure argument to <T as Functor<'a, B>>::fmap, needed for Applicative