either-4.4.1: An either monad transformer

Copyright(c) 2010-2014 Gregory Crosswhite, Chris Done, Edward Kmett
LicenseBSD-style
Maintainerekmett@gmail.com
Stabilityprovisional
Portabilityportable
Safe HaskellSafe-Inferred
LanguageHaskell98

Data.Either.Combinators

Description

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.

Synopsis

Documentation

isLeft :: Either a b -> Bool Source

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 Source

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 Source

Extract the left value or a default.

fromLefteither id
>>> fromLeft "hello" (Right 42)
"hello"
>>> fromLeft "hello" (Left "world")
"world"

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

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 Source

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 Source

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 Source

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 Source

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 Source

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 () Source

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 () Source

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:

whenRightforM_

Using Control.Lens:

whenRight ≡ forOf_ _Right
>>> whenRight (Right 12) print
12

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

A synonym of whenRight.

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

A synonym of whenLeft.

leftToMaybe :: Either a b -> Maybe a Source

Maybe get the Left side of an Either.

leftToMaybeeither 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 Source

Maybe get the Right side of an Either.

rightToMaybeeither (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 Source

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 Source

Swap the Left and Right sides of an Either.

>>> swapEither (Right 3)
Left 3

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