Antelude.Either

Documentation

data Either a b

The Either type represents values with two possibilities: a value of type Either a b is either Left a or Right b.

The Either type is sometimes used to represent a value which is either correct or an error; by convention, the Left constructor is used to hold an error value and the Right constructor is used to hold a correct value (mnemonic: "right" also means "correct").

Examples

The type Either String Int is the type of values which can be either a String or an Int. The Left constructor can be used only on Strings, and the Right constructor can be used only on Ints:

>>> let s = Left "foo" :: Either String Int
>>> s
Left "foo"
>>> let n = Right 3 :: Either String Int
>>> n
Right 3
>>> :type s
s :: Either String Int
>>> :type n
n :: Either String Int

The fmap from our Functor instance will ignore Left values, but will apply the supplied function to values contained in a Right:

>>> let s = Left "foo" :: Either String Int
>>> let n = Right 3 :: Either String Int
>>> fmap (*2) s
Left "foo"
>>> fmap (*2) n
Right 6

The Monad instance for Either allows us to chain together multiple actions which may fail, and fail overall if any of the individual steps failed. First we'll write a function that can either parse an Int from a Char, or fail.

>>> import Data.Char ( digitToInt, isDigit )
>>> :{
    let parseEither :: Char -> Either String Int
        parseEither c
          | isDigit c = Right (digitToInt c)
          | otherwise = Left "parse error"
>>> :}

The following should work, since both '1' and '2' can be parsed as Ints.

>>> :{
    let parseMultiple :: Either String Int
        parseMultiple = do
          x <- parseEither '1'
          y <- parseEither '2'
          return (x + y)
>>> :}

>>> parseMultiple
Right 3

But the following should fail overall, since the first operation where we attempt to parse 'm' as an Int will fail:

>>> :{
    let parseMultiple :: Either String Int
        parseMultiple = do
          x <- parseEither 'm'
          y <- parseEither '2'
          return (x + y)
>>> :}

>>> parseMultiple
Left "parse error"

Constructors

Left a

Right b

Instances

Foldable (Either a)

Since: base-4.7.0.0

Defined in Data.Foldable

Methods

fold :: Monoid m => Either a m -> m

foldMap :: Monoid m => (a0 -> m) -> Either a a0 -> m

foldMap' :: Monoid m => (a0 -> m) -> Either a a0 -> m

foldr :: (a0 -> b -> b) -> b -> Either a a0 -> b

foldr' :: (a0 -> b -> b) -> b -> Either a a0 -> b

foldl :: (b -> a0 -> b) -> b -> Either a a0 -> b

foldl' :: (b -> a0 -> b) -> b -> Either a a0 -> b

foldr1 :: (a0 -> a0 -> a0) -> Either a a0 -> a0

foldl1 :: (a0 -> a0 -> a0) -> Either a a0 -> a0

toList :: Either a a0 -> [a0]

null :: Either a a0 -> Bool

length :: Either a a0 -> Int

elem :: Eq a0 => a0 -> Either a a0 -> Bool

maximum :: Ord a0 => Either a a0 -> a0

minimum :: Ord a0 => Either a a0 -> a0

sum :: Num a0 => Either a a0 -> a0

product :: Num a0 => Either a a0 -> a0

Traversable (Either a)

Since: base-4.7.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a0 -> f b) -> Either a a0 -> f (Either a b)

sequenceA :: Applicative f => Either a (f a0) -> f (Either a a0)

mapM :: Monad m => (a0 -> m b) -> Either a a0 -> m (Either a b)

sequence :: Monad m => Either a (m a0) -> m (Either a a0)

Applicative (Either e)

Since: base-3.0

Defined in Data.Either

Methods

pure :: a -> Either e a

(<*>) :: Either e (a -> b) -> Either e a -> Either e b

liftA2 :: (a -> b -> c) -> Either e a -> Either e b -> Either e c

(*>) :: Either e a -> Either e b -> Either e b

(<*) :: Either e a -> Either e b -> Either e a

Functor (Either a)

Since: base-3.0

Defined in Data.Either

Methods

fmap :: (a0 -> b) -> Either a a0 -> Either a b

(<$) :: a0 -> Either a b -> Either a a0

Monad (Either e)

Since: base-4.4.0.0

Defined in Data.Either

Methods

(>>=) :: Either e a -> (a -> Either e b) -> Either e b

(>>) :: Either e a -> Either e b -> Either e b

return :: a -> Either e a

Semigroup (Either a b)

Since: base-4.9.0.0

Defined in Data.Either

Methods

(<>) :: Either a b -> Either a b -> Either a b

sconcat :: NonEmpty (Either a b) -> Either a b

stimes :: Integral b0 => b0 -> Either a b -> Either a b

(Read a, Read b) => Read (Either a b)

Since: base-3.0

Defined in Data.Either

Methods

readsPrec :: Int -> ReadS (Either a b)

readList :: ReadS [Either a b]

readPrec :: ReadPrec (Either a b)

readListPrec :: ReadPrec [Either a b]

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

Since: base-3.0

Defined in Data.Either

Methods

showsPrec :: Int -> Either a b -> ShowS

show :: Either a b -> String

showList :: [Either a b] -> ShowS

(Eq a, Eq b) => Eq (Either a b)

Since: base-2.1

Defined in Data.Either

Methods

(==) :: Either a b -> Either a b -> Bool

(/=) :: Either a b -> Either a b -> Bool

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

Since: base-2.1

Defined in Data.Either

Methods

compare :: Either a b -> Either a b -> Ordering

(<) :: Either a b -> Either a b -> Bool

(<=) :: Either a b -> Either a b -> Bool

(>) :: Either a b -> Either a b -> Bool

(>=) :: Either a b -> Either a b -> Bool

max :: Either a b -> Either a b -> Either a b

min :: Either a b -> Either a b -> Either a b

Rexports

either :: (a -> c) -> (b -> c) -> Either a b -> c

Case analysis for the Either type. If the value is Left a, apply the first function to a; if it is Right b, apply the second function to b.

Examples

We create two values of type Either String Int, one using the Left constructor and another using the Right constructor. Then we apply "either" the length function (if we have a String) or the "times-two" function (if we have an Int):

>>> let s = Left "foo" :: Either String Int
>>> let n = Right 3 :: Either String Int
>>> either length (*2) s
3
>>> either length (*2) n
6

isLeft :: Either a b -> Bool

Return True if the given value is a Left-value, False otherwise.

Examples

Basic usage:

>>> isLeft (Left "foo")
True
>>> isLeft (Right 3)
False

Assuming a Left value signifies some sort of error, we can use isLeft to write a very simple error-reporting function that does absolutely nothing in the case of success, and outputs "ERROR" if any error occurred.

This example shows how isLeft might be used to avoid pattern matching when one does not care about the value contained in the constructor:

>>> import Control.Monad ( when )
>>> let report e = when (isLeft e) $ putStrLn "ERROR"
>>> report (Right 1)
>>> report (Left "parse error")
ERROR

Since: base-4.7.0.0

isRight :: Either a b -> Bool

Return True if the given value is a Right-value, False otherwise.

Examples

Basic usage:

>>> isRight (Left "foo")
False
>>> isRight (Right 3)
True

Assuming a Left value signifies some sort of error, we can use isRight to write a very simple reporting function that only outputs "SUCCESS" when a computation has succeeded.

This example shows how isRight might be used to avoid pattern matching when one does not care about the value contained in the constructor:

>>> import Control.Monad ( when )
>>> let report e = when (isRight e) $ putStrLn "SUCCESS"
>>> report (Left "parse error")
>>> report (Right 1)
SUCCESS

Since: base-4.7.0.0

New and Reconstructed for safety

filterLefts :: List (Either left right) -> List left

Take a List of 'Either a b' and return a List containing all of the values from the Left cases.

filterRights :: List (Either left right) -> List right

Take a List of 'Either a b' and return a List containing all of the values from the Right cases.

fromMaybe :: Maybe a -> Either () a

Convert a 'Maybe a' to an 'Either () a'.

fromResult :: Result err ok -> Either err ok

Convert a 'Result a b' to an 'Either a b'.

leftWithDefault :: a -> Either a b -> a

Get the Left case of an Either, or a default if the Either is Right.

mapLeft :: (left -> newLeft) -> Either left right -> Either newLeft right

Apply a function to the Left case of an Either.

mapRight :: (right -> newRight) -> Either left right -> Either left newRight

Apply a function to the Right case of an Either.

partition :: List (Either left right) -> (List left, List right)

Take a List of 'Either left right' and create a Tuple with 'List left' and 'List right'.

rightWithDefault :: b -> Either a b -> b

Get the Right case of an Either, or a default if the Either is Left.

swap :: Either left right -> Either right left

Swap the Left/Right in an Either