Safe Haskell | Safe-Inferred |
---|---|

Language | Haskell2010 |

When `IO`

is the monad of a monadic fold, each step in the evaluation of the
fold might throw an exception, thus causing the entire evaluation to fail. This
module provides some functions for capturing the results from *part of* a fold
even if some of the steps did not succeed.

This module uses `try`

from the `safe-exceptions`

package and will not catch
async exceptions.

## Synopsis

- exHalt_ :: forall m a b. (Monad m, MonadCatch m) => FoldM m a b -> FoldM m a b
- exHalt :: forall e m a b. (Exception e, Monad m, MonadCatch m) => FoldM m a b -> FoldM m a (Maybe e, b)
- exSkip_ :: forall m a b. (Monad m, MonadCatch m) => FoldM m a b -> FoldM m a b
- exSkip :: forall e m a b. (Exception e, Monad m, MonadCatch m) => FoldM m a b -> FoldM m a ([e], b)

# Stopping at the first exception

exHalt_ :: forall m a b. (Monad m, MonadCatch m) => FoldM m a b -> FoldM m a b Source #

Performs the steps of a fold up until the first step that throws an exception, then produces the result obtained thus far.

#### Example

`>>>`

`import Control.Exception`

`>>>`

`f x = if x < 10 then return x else throw Overflow`

`>>>`

`xs = [1, 2, 500, 4] :: [Integer]`

Since `f 500`

produces an exception, the following fold fails:

`>>>`

`fold1 = premapM f (generalize list)`

`>>>`

*** Exception: arithmetic overflow`foldM fold1 xs`

By applying `untilFirstException`

, we can produce a new fold that returns
the intermediate result at the point where the exception occurs.

`>>>`

`fold2 = exHalt_ fold1`

`>>>`

[1,2]`foldM fold2 xs`

exHalt :: forall e m a b. (Exception e, Monad m, MonadCatch m) => FoldM m a b -> FoldM m a (Maybe e, b) Source #

Performs the steps of a fold up until the first step that throws an exception, then produces a tuple containing:

- The exception that was thrown, if any.
- The result obtained thus far.

The first type parameter lets you specify what type of exception to catch. Any other type of exception will still cause the entire fold's evaluation to fail.

#### Example

`>>>`

`import Control.Exception`

`>>>`

`f x = if x < 10 then return x else throw Overflow`

`>>>`

`xs = [1, 2, 500, 4] :: [Integer]`

`>>>`

`fold1 = premapM f (generalize list)`

`>>>`

`:set -XTypeApplications`

`>>>`

`fold2 = exHalt @ArithException fold1`

`>>>`

(Just arithmetic overflow,[1,2])`foldM fold2 xs`

# Continuing past failed steps

exSkip_ :: forall m a b. (Monad m, MonadCatch m) => FoldM m a b -> FoldM m a b Source #

Perform only steps of a fold that succeed, ignoring any steps that fail.

#### Example

`>>>`

`import Control.Exception`

`>>>`

`f x = if x < 10 then return x else throw Overflow`

`>>>`

`xs = [1, 2, 500, 4] :: [Integer]`

Since `f 500`

produces an exception, the following fold fails:

`>>>`

`fold1 = premapM f (generalize list)`

`>>>`

*** Exception: arithmetic overflow`foldM fold1 xs`

By applying `exSkip_`

, we can produce a new fold that produces a result from all
steps that *don't* fail:

`>>>`

`fold2 = exSkip_ fold1`

`>>>`

[1,2,4]`foldM fold2 xs`

exSkip :: forall e m a b. (Exception e, Monad m, MonadCatch m) => FoldM m a b -> FoldM m a ([e], b) Source #

Perform only steps of a fold that succeed, collecting the exceptions thrown from each step that fail. Produces a tuple containing:

- A list of any exceptions thrown.
- The result obtained from the steps that succeeded.

The first type parameter lets you specify what type of exception to catch. Any other type of exception will still cause the entire fold's evaluation to fail.

#### Example

`>>>`

`import Control.Exception`

`>>>`

`f x = if x < 10 then return x else throw Overflow`

`>>>`

`xs = [1, 2, 500, 4] :: [Integer]`

Since `f 500`

produces an exception, the following fold fails:

`>>>`

`fold1 = premapM f (generalize list)`

`>>>`

*** Exception: arithmetic overflow`foldM fold1 xs`

By applying `exSkip`

, we can produce a new fold that produces a result from all
steps that *don't* fail:

`>>>`

`:set -XTypeApplications`

`>>>`

`fold2 = exSkip @ArithException fold1`

`>>>`

([arithmetic overflow],[1,2,4])`foldM fold2 xs`