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
  

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

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

Combine two alternatives.

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

Returns true when the Either value was constructed with Left.

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

Returns true when the Either value was constructed with Right.

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

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

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

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