Module

# Data.Either

Package
either
Repository
purescript/purescript-either

### #EitherSource

``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

• `Left a`
• `Right b`

#### Instances

• `Functor (Either a)`

The `Functor` instance allows functions to transform the contents of a `Right` with the `<\$>` operator:

``````f <\$> Right x == Right (f x)
``````

`Left` values are untouched:

``````f <\$> Left y == Left y
``````
• `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)`

### #eitherSource

``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
``````

### #chooseSource

``choose :: forall m a b. Alt m => m a -> m b -> m (Either a b)``

Combine two alternatives.

### #isLeftSource

``isLeft :: forall a b. Either a b -> Boolean``

Returns `true` when the `Either` value was constructed with `Left`.

### #isRightSource

``isRight :: forall a b. Either a b -> Boolean``

Returns `true` when the `Either` value was constructed with `Right`.

### #fromLeftSource

``fromLeft :: forall a b. a -> Either a b -> a``

A function that extracts the value from the `Left` data constructor. The first argument is a default value, which will be returned in the case where a `Right` is passed to `fromLeft`.

### #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`.

### #fromRightSource

``fromRight :: forall a b. b -> Either a b -> b``

A function that extracts the value from the `Right` data constructor. The first argument is a default value, which will be returned in the case where a `Left` is passed to `fromRight`.

### #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`.

### #noteSource

``note :: forall a b. a -> Maybe b -> Either a b``

Takes a default and a `Maybe` value, if the value is a `Just`, turn it into a `Right`, if the value is a `Nothing` use the provided default as a `Left`

``````note "default" Nothing = Left "default"
note "default" (Just 1) = Right 1
``````

### #note'Source

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

Similar to `note`, but for use in cases where the default value may be expensive to compute.

``````note' (\_ -> "default") Nothing = Left "default"
note' (\_ -> "default") (Just 1) = Right 1
``````

### #hushSource

``hush :: forall a b. Either a b -> Maybe b``

Turns an `Either` into a `Maybe`, by throwing eventual `Left` values away and converting them into `Nothing`. `Right` values get turned into `Just`s.

``````hush (Left "ParseError") = Nothing
hush (Right 42) = Just 42
``````