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 Definitions

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