Control.Error

A monad transformer that adds exceptions to other monads.

ExceptT constructs a monad parameterized over two things:

• e - The exception type.

• m - The inner monad.

The return function yields a computation that produces the given value, while >>= sequences two subcomputations, exiting on the first exception.

The inverse of ExceptT.

Signal an exception value e.

• runExceptT (throwE e) = return (Left e)

• throwE e >>= m = throwE e

Handle an exception.

• catchE (lift m) h = lift m

• catchE (throwE e) h = h e

Map the unwrapped computation using the given function.

• runExceptT (mapExceptT f m) = f (runExceptT m)

Transform any exceptions thrown by the computation using the given function.

The parameterizable maybe monad, obtained by composing an arbitrary monad with the Maybe monad.

Computations are actions that may produce a value or exit.

The return function yields a computation that produces that value, while >>= sequences two subcomputations, exiting if either computation does.

Transform the computation inside a MaybeT.

• runMaybeT (mapMaybeT f m) = f (runMaybeT m)

Lift a callCC operation to the new monad.

Lift a catchE operation to the new monad.

Lift a listen operation to the new monad.

Lift a pass operation to the new monad.

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 Prelude.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) s3>>> either length (*2) n6

Extracts from a list of Either all the Left elements. All the Left elements are extracted in order.

Examples

Basic usage:

>>> let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]>>> lefts list["foo","bar","baz"]

Extracts from a list of Either all the Right elements. All the Right elements are extracted in order.

Examples

Basic usage:

>>> let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]>>> rights list[3,7]

Partitions a list of Either into two lists. All the Left elements are extracted, in order, to the first component of the output. Similarly the Right elements are extracted to the second component of the output.

Examples

Basic usage:

>>> let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]>>> partitionEithers list(["foo","bar","baz"],[3,7])

The pair returned by partitionEithers x should be the same pair as (lefts x, rights x):

>>> let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]>>> partitionEithers list == (lefts list, rights list)True

The maybe function takes a default value, a function, and a Maybe value. If the Maybe value is Nothing, the function returns the default value. Otherwise, it applies the function to the value inside the Just and returns the result.

Examples

Basic usage:

>>> maybe False odd (Just 3)True

>>> maybe False odd NothingFalse

Read an integer from a string using readMaybe. If we succeed, return twice the integer; that is, apply (*2) to it. If instead we fail to parse an integer, return 0 by default:

>>> import GHC.Internal.Text.Read ( readMaybe )>>> maybe 0 (*2) (readMaybe "5")10>>> maybe 0 (*2) (readMaybe "")0

Apply show to a Maybe Int. If we have Just n, we want to show the underlying Int n. But if we have Nothing, we return the empty string instead of (for example) "Nothing":

>>> maybe "" show (Just 5)"5">>> maybe "" show Nothing""

The isJust function returns True iff its argument is of the form Just _.

Examples

Basic usage:

>>> isJust (Just 3)True

>>> isJust (Just ())True

>>> isJust NothingFalse

Only the outer constructor is taken into consideration:

>>> isJust (Just Nothing)True

The isNothing function returns True iff its argument is Nothing.

Examples

Basic usage:

>>> isNothing (Just 3)False

>>> isNothing (Just ())False

>>> isNothing NothingTrue

Only the outer constructor is taken into consideration:

>>> isNothing (Just Nothing)False

The fromMaybe function takes a default value and a Maybe value. If the Maybe is Nothing, it returns the default value; otherwise, it returns the value contained in the Maybe.

Examples

Basic usage:

>>> fromMaybe "" (Just "Hello, World!")"Hello, World!"

>>> fromMaybe "" Nothing""

Read an integer from a string using readMaybe. If we fail to parse an integer, we want to return 0 by default:

>>> import GHC.Internal.Text.Read ( readMaybe )>>> fromMaybe 0 (readMaybe "5")5>>> fromMaybe 0 (readMaybe "")0

The listToMaybe function returns Nothing on an empty list or Just a where a is the first element of the list.

Examples

Basic usage:

>>> listToMaybe []Nothing

>>> listToMaybe [9]Just 9

>>> listToMaybe [1,2,3]Just 1

Composing maybeToList with listToMaybe should be the identity on singleton/empty lists:

>>> maybeToList $ listToMaybe [5][5]>>> maybeToList $ listToMaybe [][]

But not on lists with more than one element:

>>> maybeToList $ listToMaybe [1,2,3][1]

The maybeToList function returns an empty list when given Nothing or a singleton list when given Just.

Examples

Basic usage:

>>> maybeToList (Just 7)[7]

>>> maybeToList Nothing[]

One can use maybeToList to avoid pattern matching when combined with a function that (safely) works on lists:

>>> import GHC.Internal.Text.Read ( readMaybe )>>> sum $ maybeToList (readMaybe "3")3>>> sum $ maybeToList (readMaybe "")0

The catMaybes function takes a list of Maybes and returns a list of all the Just values.

Examples

Basic usage:

>>> catMaybes [Just 1, Nothing, Just 3][1,3]

When constructing a list of Maybe values, catMaybes can be used to return all of the "success" results (if the list is the result of a map, then mapMaybe would be more appropriate):

>>> import GHC.Internal.Text.Read ( readMaybe )>>> [readMaybe x :: Maybe Int | x <- ["1", "Foo", "3"] ][Just 1,Nothing,Just 3]>>> catMaybes $ [readMaybe x :: Maybe Int | x <- ["1", "Foo", "3"] ][1,3]

The mapMaybe function is a version of map which can throw out elements. In particular, the functional argument returns something of type Maybe b. If this is Nothing, no element is added on to the result list. If it is Just b, then b is included in the result list.

Examples

Using mapMaybe f x is a shortcut for catMaybes $ map f x in most cases:

>>> import GHC.Internal.Text.Read ( readMaybe )>>> let readMaybeInt = readMaybe :: String -> Maybe Int>>> mapMaybe readMaybeInt ["1", "Foo", "3"][1,3]>>> catMaybes $ map readMaybeInt ["1", "Foo", "3"][1,3]

If we map the Just constructor, the entire list should be returned:

>>> mapMaybe Just [1,2,3][1,2,3]

New users are recommended to use minimumBound or maximumBound instead.

New users are recommended to use minimumBound or maximumBound instead.

An alternative name for fromMaybe, to fit the naming scheme of this package. Generally using fromMaybe directly would be considered better style.