Data.Either

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
  

• 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
• (Semiring b) => Semiring (Either a b)
• (Semigroup b) => Semigroup (Either a b)

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

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

Combine two alternatives.

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

Returns true when the Either value was constructed with Left.

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

Returns true when the Either value was constructed with Right.

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.

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.

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' :: 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

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 Justs.

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