diff --git a/ChangeLog.md b/ChangeLog.md --- a/ChangeLog.md +++ b/ChangeLog.md @@ -1,29 +1,26 @@ # Changelog for collect-errors -## v0.1.4.0 +## v0.1.4 -* Add clearPotentialErrors +* Add clearPotentialErrors for removing harmless errors +* Improve documentation -## v0.1.3.0 +## v0.1.3 * Add CanTakeCNErrors type shortcut -## v0.1.2.0 +## v0.1.2 * Add CanTakeErrors type class and liftTakeErrors function - * Add instance of deepseq's NFData -## v0.1.1.0 +## v0.1.1 * Add removeValue functions -## v0.1.0.0 +## v0.1.0 * Initial port of CollectErrors and CN from mixed-types-num-0.4.1 - * Simplify the code by abandoning EnsureCE and related type functions and utilities - * NumErrors within CN are now a set to prevent multiple occurrences of the same error - * Add CollectError or CN instances for various Prelude type classes, including Num and Floating, checking for domain violations diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -1,84 +1,106 @@ -# collect-errors +# collect-errors +This package provides an error collecting mechanism. Using `CN Double` instead of `Double` replaces NaNs and infinities with more informative error descriptions. + +API documentation available on the [Hackage page](https://hackage.haskell.org/package/collect-errors). + +## Table of contents + +- [1. Feature highlights](#1-feature-highlights) + - [1.1. Error collecting](#11-error-collecting) + - [1.2. Error investigation](#12-error-investigation) + - [1.3. Undecided comparisons](#13-undecided-comparisons) + - [1.4. Potential errors](#14-potential-errors) + +## 1. Feature highlights + `CollectErrors es t` is a monad wrapper around values of type `t` which can accommodate (a list of) (potential) errors of type `es` that have (maybe) occurred during the computation of a value. A value may be missing, leaving only the error(s). The wrapper `CN t` is a special case of `CollectErrors es t` with `es` = `NumErrors`. -## Generated API documentation - -See the [Hackage page](https://hackage.haskell.org/package/collect-errors). - -## Feature highlights - -### Error collecting +### 1.1. Error collecting The `CN` wrapper propagates instances of `Floating`, allowing us to write expressions with partial functions (ie functions that fail for some inputs) instead of branching after each application of such function: - $ stack ghci collect-errors:lib --no-load --ghci-options Numeric.CollectErrors - *Numeric.CollectErrors> a = 1 :: CN Double - *Numeric.CollectErrors> (1/(a-1))+(sqrt (a-2)) - {{ERROR: division by 0; ERROR: out of domain: sqrt for negative arg -1.0}} +```Text +$ stack ghci collect-errors:lib --no-load --ghci-options Numeric.CollectErrors +*Numeric.CollectErrors> a = 1 :: CN Double +*Numeric.CollectErrors> (1/(a-1))+(sqrt (a-2)) +{{ERROR: division by 0; ERROR: out of domain: sqrt for negative arg -1.0}} +``` as opposed to: - *Prelude> a = 1 :: Double - *Prelude> (1/(a-1))+(sqrt (a-2)) - NaN +```Text +*Prelude> a = 1 :: Double +*Prelude> (1/(a-1))+(sqrt (a-2)) +NaN +``` -### Error investigation +### 1.2. Error investigation Dealing with the errors can be moved outside the expression: - *Numeric.CollectErrors> a = 1 :: CN Double - *Numeric.CollectErrors> toEither $ 1/(a-1) - Left {ERROR: division by 0} +```Text +*Numeric.CollectErrors> a = 1 :: CN Double +*Numeric.CollectErrors> toEither $ 1/(a-1) +Left {ERROR: division by 0} - *Numeric.CollectErrors> toEither $ 1/a+(sqrt a) - Right 2.0 +*Numeric.CollectErrors> toEither $ 1/a+(sqrt a) +Right 2.0 +``` An alternative way to branch based on errors is provided by the function `withErrorOrValue`: - ...> a = 2 :: CN Double - ...> withErrorOrValue (const 0) id (1/a) - 0.5 +```Text +...> a = 2 :: CN Double +...> withErrorOrValue (const 0) id (1/a) +0.5 +``` The `CN` wrapper can be forcibly removed as follows: - ...> :t unCN (1/a) - ... :: Double +```Text +...> :t unCN (1/a) +... :: Double - ...> unCN (1/a) - 0.5 +...> unCN (1/a) +0.5 - ...> unCN (1/(a-2)) - *** Exception: CollectErrors: {ERROR: division by 0} +...> unCN (1/(a-2)) +*** Exception: CollectErrors: {ERROR: division by 0} +``` -### Undecided comparisons +### 1.3. Undecided comparisons -The following examples require the interval arithmetic package [aern2-mp](https://github.com/michalkonecny/aern2) and its dependency [mixed-types-num](https://hackage.haskell.org/package/mixed-types-num): +The following examples require the interval arithmetic package [aern2-mp](https://hackage.haskell.org/package/aern2-mp) and its dependency [mixed-types-num](https://hackage.haskell.org/package/mixed-types-num): - $ stack ghci aern2-mp:lib --no-load --ghci-options AERN2.MP - *AERN2.MP> import MixedTypesNumPrelude - *AERN2.MP MixedTypesNumPrelude> +```Text +$ stack ghci aern2-mp:lib --no-load --ghci-options AERN2.MP +*AERN2.MP> import MixedTypesNumPrelude +*AERN2.MP MixedTypesNumPrelude> +``` Comparisons involving sets (such as intervals) are undecided when the intervals overlap: - ...> pi100 = piBallP (prec 100) - ...> :t pi100 - pi100 :: MPBall - ...> pi100 - [3.1415926535897932384626433832793333156439620213... ± ~7.8886e-31 ~2^(-100)] +```Text +...> pi100 = piBallP (prec 100) +...> :t pi100 +pi100 :: MPBall +...> pi100 +[3.1415926535897932384626433832793333156439620213... ± ~7.8886e-31 ~2^(-100)] - ...> 0 < pi100 - CertainTrue +...> 0 < pi100 +CertainTrue - ...> pi100 == pi100 - TrueOrFalse +...> pi100 == pi100 +TrueOrFalse +``` The values `CertainTrue` and `TrueOrFalse` are part of the three-valued type `Kleenean` provided by [mixed-types-num](https://hackage.haskell.org/package/mixed-types-num). @@ -87,35 +109,44 @@ The Prelude `Floating` instance for `CN` cannot be used reliably with interval arithmetic because the instance relies on true/false comparisons: - ...> import qualified Prelude as P - ... P> (cn pi100) P./ (cn pi100 - cn pi100) - *** Exception: Failed to decide equality of MPBalls. If you switch to MixedTypesNumPrelude instead of Prelude, comparison of MPBalls returns Kleenean instead of Bool. +```Text +...> import qualified Prelude as P +... P> (cn pi100) P./ (cn pi100 - cn pi100) +*** Exception: Failed to decide equality of MPBalls. If you switch to MixedTypesNumPrelude instead of Prelude, comparison of MPBalls returns Kleenean instead of Bool. +``` Using its Kleenean comparisons, package [mixed-types-num](https://hackage.haskell.org/package/mixed-types-num) provides alternative numerical type classes in which errors are detected and collected correctly when using the `CN` wrapper: - ...> (cn pi100) / (cn pi100 - cn pi100) - {{POTENTIAL ERROR: division by 0}} +```Text +...> (cn pi100) / (cn pi100 - cn pi100) +{{POTENTIAL ERROR: division by 0}} +``` -### Potential errors +### 1.4. Potential errors As we see in the above example, the `CN` wrapper supports potential errors that sometimes arise as a consequence of undecided comparisons. When an error is present (which can be checked using `hasError`), the function `hasCertainError` can be used to further distinguish cases where the error is certain or potential: - ...> import qualified Numeric.CollectErrors as CN - ...> CN.hasCertainError $ (cn pi100) / (cn 0) - True +```Text +...> import qualified Numeric.CollectErrors as CN +...> CN.hasCertainError $ (cn pi100) / (cn 0) +True - ...> CN.hasCertainError $ (cn pi100) / (cn pi100 - cn pi100) - False +...> CN.hasCertainError $ (cn pi100) / (cn pi100 - cn pi100) +False +``` Sometimes the potential errors are *harmless*: - ...> sqrt (cn pi100 - cn pi100) - [0.0000000000000006280369834735100420368561502297... ± ~6.2804e-16 ~2^(-50)]{{POTENTIAL ERROR: out of domain: negative sqrt argument}} +```Text +...> sqrt (cn pi100 - cn pi100) +[0.0000000000000006280369834735100420368561502297... ± ~6.2804e-16 ~2^(-50)]{{POTENTIAL ERROR: out of domain: negative sqrt argument}} +``` Such harmless potential errors can be ignored using `clearPotentialErrors`: - ...> clearPotentialErrors $ sqrt (cn pi100 - cn pi100) - [0.0000000000000006280369834735100420368561502297... ± ~6.2804e-16 ~2^(-50)] - +```Text +...> clearPotentialErrors $ sqrt (cn pi100 - cn pi100) +[0.0000000000000006280369834735100420368561502297... ± ~6.2804e-16 ~2^(-50)] +``` diff --git a/collect-errors.cabal b/collect-errors.cabal --- a/collect-errors.cabal +++ b/collect-errors.cabal @@ -4,10 +4,10 @@ -- -- see: https://github.com/sol/hpack -- --- hash: f06d023c94a4b6215cd2d20c3a3ba16388f36ee65e84b34ebfe8a0b0007b9ce8 +-- hash: 08277c279263dce2bad0694059098e8f02e2271dd9c718b7f76f9ab3bddbd18a name: collect-errors -version: 0.1.4.0 +version: 0.1.4.1 synopsis: Error monad with a Float instance description: Please see the README on GitHub at category: Math