# Data.Either

- Package
- purescript-either
- Repository
- purescript/purescript-either

### #Either Source

`data Either a b`

The `Either`

type is used to represent a choice between two types of value.

A common use case for `Either`

is error handling, where `Left`

is used to
carry an error value and `Right`

is used to carry a success value.

#### Constructors

#### Instances

`Functor (Either a)`

`Generic (Either a b) _`

`Invariant (Either a)`

`Apply (Either e)`

The

`Apply`

instance allows functions contained within a`Right`

to transform a value contained within a`Right`

using the`(<*>)`

operator:`Right f <*> Right x == Right (f x)`

`Left`

values are left untouched:`Left f <*> Right x == Left f Right f <*> Left y == Left y`

Combining

`Functor`

's`<$>`

with`Apply`

's`<*>`

can be used to transform a pure function to take`Either`

-typed arguments so`f :: a -> b -> c`

becomes`f :: Either l a -> Either l b -> Either l c`

:`f <$> Right x <*> Right y == Right (f x y)`

The

`Left`

-preserving behaviour of both operators means the result of an expression like the above but where any one of the values is`Left`

means the whole result becomes`Left`

also, taking the first`Left`

value found:`f <$> Left x <*> Right y == Left x f <$> Right x <*> Left y == Left y f <$> Left x <*> Left y == Left x`

`Applicative (Either e)`

The

`Applicative`

instance enables lifting of values into`Either`

with the`pure`

function:`pure x :: Either _ _ == Right x`

Combining

`Functor`

's`<$>`

with`Apply`

's`<*>`

and`Applicative`

's`pure`

can be used to pass a mixture of`Either`

and non-`Either`

typed values to a function that does not usually expect them, by using`pure`

for any value that is not already`Either`

typed:`f <$> Right x <*> pure y == Right (f x y)`

Even though

`pure = Right`

it is recommended to use`pure`

in situations like this as it allows the choice of`Applicative`

to be changed later without having to go through and replace`Right`

with a new constructor.`Alt (Either e)`

The

`Alt`

instance allows for a choice to be made between two`Either`

values with the`<|>`

operator, where the first`Right`

encountered is taken.`Right x <|> Right y == Right x Left x <|> Right y == Right y Left x <|> Left y == Left y`

`Bind (Either e)`

The

`Bind`

instance allows sequencing of`Either`

values and functions that return an`Either`

by using the`>>=`

operator:`Left x >>= f = Left x Right x >>= f = f x`

`Either`

's "do notation" can be understood to work like this:`x :: forall e a. Either e a x = -- y :: forall e b. Either e b y = -- foo :: forall e a. (a -> b -> c) -> Either e c foo f = do x' <- x y' <- y pure (f x' y')`

...which is equivalent to...

`x >>= (\x' -> y >>= (\y' -> pure (f x' y')))`

...and is the same as writing...

`foo :: forall e a. (a -> b -> c) -> Either e c foo f = case x of Left e -> Left e Right x -> case y of Left e -> Left e Right y -> Right (f x y)`

`Monad (Either e)`

The

`Monad`

instance guarantees that there are both`Applicative`

and`Bind`

instances for`Either`

.`Extend (Either e)`

The

`Extend`

instance allows sequencing of`Either`

values and functions that accept an`Either`

and return a non-`Either`

result using the`<<=`

operator.`f <<= Left x = Left x f <<= Right x = Right (f (Right x))`

`(Show a, Show b) => Show (Either a b)`

The

`Show`

instance allows`Either`

values to be rendered as a string with`show`

whenever there is an`Show`

instance for both type the`Either`

can contain.`(Eq a, Eq b) => Eq (Either a b)`

The

`Eq`

instance allows`Either`

values to be checked for equality with`==`

and inequality with`/=`

whenever there is an`Eq`

instance for both types the`Either`

can contain.`(Eq a) => Eq1 (Either a)`

`(Ord a, Ord b) => Ord (Either a b)`

The

`Ord`

instance allows`Either`

values to be compared with`compare`

,`>`

,`>=`

,`<`

and`<=`

whenever there is an`Ord`

instance for both types the`Either`

can contain.Any

`Left`

value is considered to be less than a`Right`

value.`(Ord a) => Ord1 (Either a)`

`(Bounded a, Bounded b) => Bounded (Either a b)`

`(Semigroup b) => Semigroup (Either a b)`

### #either Source

`either :: forall a b c. (a -> c) -> (b -> c) -> Either a b -> c`

Takes two functions and an `Either`

value, if the value is a `Left`

the
inner value is applied to the first function, if the value is a `Right`

the inner value is applied to the second function.

```
either f g (Left x) == f x
either f g (Right y) == g y
```

### #fromLeft' Source

`fromLeft' :: forall a b. (Unit -> a) -> Either a b -> a`

Similar to `fromLeft`

but for use in cases where the default value may be
expensive to compute. As PureScript is not lazy, the standard `fromLeft`

has to evaluate the default value before returning the result,
whereas here the value is only computed when the `Either`

is known
to be `Right`

.

### #fromRight' Source

`fromRight' :: forall a b. (Unit -> b) -> Either a b -> b`

Similar to `fromRight`

but for use in cases where the default value may be
expensive to compute. As PureScript is not lazy, the standard `fromRight`

has to evaluate the default value before returning the result,
whereas here the value is only computed when the `Either`

is known
to be `Left`

.

The

`Functor`

instance allows functions to transform the contents of a`Right`

with the`<$>`

operator:`Left`

values are untouched: