collect-errors 0.1.4.0 → 0.1.4.1
raw patch · 3 files changed
+100/−72 lines, 3 filesPVP ok
version bump matches the API change (PVP)
API changes (from Hackage documentation)
Files
- ChangeLog.md +7/−10
- README.md +91/−60
- collect-errors.cabal +2/−2
ChangeLog.md view
@@ -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
README.md view
@@ -1,84 +1,106 @@-# collect-errors+# collect-errors <!-- omit in toc --> +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 <!-- omit in toc -->++- [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)]+```
collect-errors.cabal view
@@ -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 <https://github.com/michalkonecny/collect-errors#readme> category: Math