Bifunctor

Common instances of Bifunctor

Two-element tuples

(,) is an example of a type that has a Bifunctor instance.

instance Bifunctor (,) where
    bimap f g (x, y) = (f x, g y)

bimap takes a pair of functions and applies them to the tuple’s respective components.

bimap (+ 2) (++ "nie") (3, "john") --> (5,"johnnie")
bimap ceiling length (3.5 :: Double, "john" :: String) --> (4,4)

Either

Either’s instance of Bifunctor selects one of the two functions to apply depending on whether the value is Left or Right.

instance Bifunctor Either where
    bimap f g (Left x) = Left (f x)
    bimap f g (Right y) = Right (g y)

Definition of Bifunctor

Bifunctor is the class of types with two type parameters (f :: * -> * -> *), both of which can be covariantly mapped over simultaneously.

class Bifunctor f where
    bimap :: (a -> c) -> (b -> d) -> f a b -> f c d

bimap can be thought of as applying a pair of fmap operations to a datatype.

A correct instance of Bifunctor for a type f must satisfy the bifunctor laws, which are analogous to the functor laws:

bimap id id = id  -- identity
bimap (f . g) (h . i) = bimap f h . bimap g i  -- composition

The Bifunctor class is found in the Data.Bifunctor module. For GHC versions >7.10, this module is bundled with the compiler; for earlier versions you need to install the bifunctors package.

first and second

If mapping covariantly over only the first argument, or only the second argument, is desired, then first or second ought to be used (in lieu of bimap).

first :: Bifunctor f => (a -> c) -> f a b -> f c b
first f = bimap f id

second :: Bifunctor f => (b -> d) -> f a b -> f a d
second g = bimap id g

For example,

ghci> second (+ 2) (Right 40)
Right 42
ghci> second (+ 2) (Left "uh oh")
Left "uh oh"

Syntax

• bimap :: (a -> b) -> (c -> d) -> p a c -> p b d
• first :: (a -> b) -> p a c -> p b c
• second :: (b -> c) -> p a b -> p a c

Remarks

A run of the mill Functor is covariant in a single type parameter. For instance, if f is a Functor, then given an f a, and a function of the form a -> b, one can obtain an f b (through the use of fmap).

A Bifunctor is covariant in two type parameters. If f is a Bifunctor, then given an f a b, and two functions, one from a -> c, and another from b -> d, then one can obtain an f c d (using bimap).

first should be thought of as an fmap over the first type parameter, second as an fmap over the second, and bimap should be conceived as mapping two functions covariantly over the first and second type parameters, respectively.