Copyright | (c) 2010-2014 Gregory Crosswhite Chris Done Edward Kmett |
---|---|

License | BSD-style |

Maintainer | ekmett@gmail.com |

Stability | provisional |

Portability | portable |

Safe Haskell | Safe |

Language | Haskell2010 |

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

- isLeft :: Either a b -> Bool
- isRight :: Either a b -> Bool
- fromLeft :: a -> Either a b -> a
- fromRight :: b -> Either a b -> b
- fromLeft' :: Either a b -> a
- fromRight' :: Either a b -> b
- mapBoth :: (a -> c) -> (b -> d) -> Either a b -> Either c d
- mapLeft :: (a -> c) -> Either a b -> Either c b
- mapRight :: (b -> c) -> Either a b -> Either a c
- whenLeft :: Applicative m => Either a b -> (a -> m ()) -> m ()
- whenRight :: Applicative m => Either a b -> (b -> m ()) -> m ()
- unlessLeft :: Applicative m => Either a b -> (b -> m ()) -> m ()
- unlessRight :: Applicative m => Either a b -> (a -> m ()) -> m ()
- leftToMaybe :: Either a b -> Maybe a
- rightToMaybe :: Either a b -> Maybe b
- maybeToLeft :: b -> Maybe a -> Either a b
- maybeToRight :: b -> Maybe a -> Either b a
- eitherToError :: MonadError e m => Either e a -> m a
- swapEither :: Either e a -> Either a e

# Documentation

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

`>>>`

12`fromRight' (Right 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

and the second if the value takes the form `Left`

_

.`Right`

_

Using `Data.Bifunctor`

:

`mapBoth`

= bimap

Using `Control.Arrow`

:

`mapBoth`

= (`+++`

)

`>>>`

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

`>>>`

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

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

`>>>`

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

`>>>`

Right "hello"`mapLeft (*2) (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

`>>>`

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

`>>>`

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

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

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

, otherwise
it does nothing.`Right`

_

Using `Data.Foldable`

:

`whenRight`

≡`forM_`

Using `Control.Lens`

:

`whenRight`

≡ forOf_ _Right

`>>>`

12`whenRight (Right 12) print`

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`

.

`leftToMaybe`

≡`either`

`Just`

(`const`

`Nothing`

)

Using `Control.Lens`

:

`leftToMaybe`

≡ preview _Left`leftToMaybe`

x ≡ x^?_Left

`>>>`

Just 12`leftToMaybe (Left 12)`

`>>>`

Nothing`leftToMaybe (Right 12)`

rightToMaybe :: Either a b -> Maybe b Source #

Maybe get the `Right`

side of an `Either`

.

`rightToMaybe`

≡`either`

(`const`

`Nothing`

)`Just`

Using `Control.Lens`

:

`rightToMaybe`

≡ preview _Right`rightToMaybe`

x ≡ x^?_Right

`>>>`

Nothing`rightToMaybe (Left 12)`

`>>>`

Just 12`rightToMaybe (Right 12)`

maybeToLeft :: b -> Maybe a -> Either a b Source #

maybeToRight :: b -> Maybe a -> Either b a Source #

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.