Data.Either.Combinators

Functions for probing and unwrapping values inside of Either.

Most of these combinators are provided for pedagogical purposes and exist in more general forms in other libraries. To that end alternative definitions are supplied below.

Documentation

isLeft :: Either a b -> Bool

The isLeft function returns True iff its argument is of the form Left _.

Using Control.Lens:

isLeft ≡ has _Left

>>> isLeft (Left 12)
True

>>> isLeft (Right 12)
False

isRight :: Either a b -> Bool

The isRight function returns True iff its argument is of the form Right _.

Using Control.Lens:

isRight ≡ has _Right

>>> isRight (Left 12)
False

>>> isRight (Right 12)
True

fromLeft :: a -> Either a b -> a

Extract the left value or a default.

fromLeft ≡ either id

>>> fromLeft "hello" (Right 42)
"hello"

>>> fromLeft "hello" (Left "world")
"world"

fromRight :: b -> Either a b -> b

Extract the right value or a default.

fromRight b ≡ either b id

>>> fromRight "hello" (Right "world")
"world"

>>> fromRight "hello" (Left 42)
"hello"

fromLeft' :: Either a b -> a

Extracts the element out of a Left and throws an error if its argument take the form Right _.

Using Control.Lens:

fromLeft' x ≡ x^?!_Left

>>> fromLeft' (Left 12)
12

fromRight' :: Either a b -> b

Extracts the element out of a Right and throws an error if its argument take the form Left _.

Using Control.Lens:

fromRight' x ≡ x^?!_Right

>>> fromRight' (Right 12)
12

mapBoth :: (a -> c) -> (b -> d) -> Either a b -> Either c d

The mapBoth function takes two functions and applies the first if iff the value takes the form Left _ and the second if the value takes the form Right _.

Using Data.Bifunctor:

mapBoth = bimap

Using Control.Arrow:

mapBoth = (+++)

>>> mapBoth (*2) (*3) (Left 4)
Left 8

>>> mapBoth (*2) (*3) (Right 4)
Right 12

mapLeft :: (a -> c) -> Either a b -> Either c b

The mapLeft function takes a function and applies it to an Either value iff the value takes the form Left _.

Using Data.Bifunctor:

mapLeft = first

Using Control.Arrow:

mapLeft = (left)

Using Control.Lens:

mapLeft = over _Left

>>> mapLeft (*2) (Left 4)
Left 8

>>> mapLeft (*2) (Right "hello")
Right "hello"

mapRight :: (b -> c) -> Either a b -> Either a c

The mapRight function takes a function and applies it to an Either value iff the value takes the form Right _.

Using Data.Bifunctor:

mapRight = second

Using Control.Arrow:

mapRight = (right)

Using Control.Lens:

mapRight = over _Right

>>> mapRight (*2) (Left "hello")
Left "hello"

>>> mapRight (*2) (Right 4)
Right 8

whenLeft :: Applicative m => Either a b -> (a -> m ()) -> m ()

The whenLeft function takes an Either value and a function which returns a monad. The monad is only executed when the given argument takes the form Left _, otherwise it does nothing.

Using Control.Lens:

whenLeft ≡ forOf_ _Left

>>> whenLeft (Left 12) print
12

whenRight :: Applicative m => Either a b -> (b -> m ()) -> m ()

The whenRight function takes an Either value and a function which returns a monad. The monad is only executed when the given argument takes the form Right _, otherwise it does nothing.

Using Data.Foldable:

whenRight ≡ forM_

Using Control.Lens:

whenRight ≡ forOf_ _Right

>>> whenRight (Right 12) print
12

unlessLeft :: Applicative m => Either a b -> (b -> m ()) -> m ()

A synonym of whenRight.

unlessRight :: Applicative m => Either a b -> (a -> m ()) -> m ()

A synonym of whenLeft.

leftToMaybe :: Either a b -> Maybe a

Maybe get the Left side of an Either.

leftToMaybe ≡ either Just (const Nothing)

Using Control.Lens:

leftToMaybe ≡ preview _Left
leftToMaybe x ≡ x^?_Left

>>> leftToMaybe (Left 12)
Just 12

>>> leftToMaybe (Right 12)
Nothing

rightToMaybe :: Either a b -> Maybe b

Maybe get the Right side of an Either.

rightToMaybe ≡ either (const Nothing) Just

Using Control.Lens:

rightToMaybe ≡ preview _Right
rightToMaybe x ≡ x^?_Right

>>> rightToMaybe (Left 12)
Nothing

>>> rightToMaybe (Right 12)
Just 12

eitherToError :: MonadError e m => Either e a -> m a

Generalize Either e as MonadError e m.

If the argument has form Left e, an error is produced in the monad via throwError. Otherwise, the Right a part is forwarded.

swapEither :: Either e a -> Either a e

Swap the Left and Right sides of an Either.

>>> swapEither (Right 3)
Left 3

>>> swapEither (Left "error")
Right "error"