Module

Data.Either

Package
purescript-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)`
• `Invariant (Either a)`
• `Bifunctor Either`
• `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 x
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
``````
• `Monad (Either e)`

The `Monad` instance guarantees that there are both `Applicative` and `Bind` instances for `Either`. This also enables the `do` syntactic sugar:

``````do
x' <- x
y' <- y
pure (f x' y')
``````

Which is equivalent to:

``````x >>= (\x' -> y >>= (\y' -> pure (f x' y')))
``````
• `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)`
• `(Eq a) => Eq1 (Either a)`
• `(Ord a, Ord b) => Ord (Either a b)`
• `(Ord a) => Ord1 (Either a)`
• `(Bounded a, Bounded b) => Bounded (Either a b)`
• `Foldable (Either a)`
• `Bifoldable Either`
• `Traversable (Either a)`
• `Bitraversable Either`
• `(Semigroup b) => Semigroup (Either a b)`

#eitherSource

``either :: forall c b a. (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 b a m. Alt m => m a -> m b -> m (Either a b)``

Combine two alternatives.

#isLeftSource

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

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

#isRightSource

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

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

#fromLeftSource

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

A partial function that extracts the value from the `Left` data constructor. Passing a `Right` to `fromLeft` will throw an error at runtime.

#fromRightSource

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

A partial function that extracts the value from the `Right` data constructor. Passing a `Left` to `fromRight` will throw an error at runtime.

#noteSource

``note :: forall b a. 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 b a. (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 b a. 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
``````