safe-numeric (empty) → 0.1
raw patch · 5 files changed
+903/−0 lines, 5 filesdep +basedep +containersdep +doctest
Dependencies added: base, containers, doctest, safe, wide-word
Files
- CHANGELOG.md +6/−0
- LICENSE +202/−0
- safe-numeric.cabal +47/−0
- src/Safe/Numeric.hs +637/−0
- test/DocTests.hs +11/−0
+ CHANGELOG.md view
@@ -0,0 +1,6 @@+# Revision history for safe-numeric++## 0.1 -- 2021-04-21++* Initial version, with safe versions of conversion, arithmetic and division+ operators and functions.
+ LICENSE view
@@ -0,0 +1,202 @@++ Apache License+ Version 2.0, January 2004+ http://www.apache.org/licenses/++ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION++ 1. Definitions.++ "License" shall mean the terms and conditions for use, reproduction,+ and distribution as defined by Sections 1 through 9 of this document.++ "Licensor" shall mean the copyright owner or entity authorized by+ the copyright owner that is granting the License.++ "Legal Entity" shall mean the union of the acting entity and all+ other entities that control, are controlled by, or are under common+ control with that entity. For the purposes of this definition,+ "control" means (i) the power, direct or indirect, to cause the+ direction or management of such entity, whether by contract or+ otherwise, or (ii) ownership of fifty percent (50%) or more of the+ outstanding shares, or (iii) beneficial ownership of such entity.++ "You" (or "Your") shall mean an individual or Legal Entity+ exercising permissions granted by this License.++ "Source" form shall mean the preferred form for making modifications,+ including but not limited to software source code, documentation+ source, and configuration files.++ "Object" form shall mean any form resulting from mechanical+ transformation or translation of a Source form, including but+ not limited to compiled object code, generated documentation,+ and conversions to other media types.++ "Work" shall mean the work of authorship, whether in Source or+ Object form, made available under the License, as indicated by a+ copyright notice that is included in or attached to the work+ (an example is provided in the Appendix below).++ "Derivative Works" shall mean any work, whether in Source or Object+ form, that is based on (or derived from) the Work and for which the+ editorial revisions, annotations, elaborations, or other modifications+ represent, as a whole, an original work of authorship. For the purposes+ of this License, Derivative Works shall not include works that remain+ separable from, or merely link (or bind by name) to the interfaces of,+ the Work and Derivative Works thereof.++ "Contribution" shall mean any work of authorship, including+ the original version of the Work and any modifications or additions+ to that Work or Derivative Works thereof, that is intentionally+ submitted to Licensor for inclusion in the Work by the copyright owner+ or by an individual or Legal Entity authorized to submit on behalf of+ the copyright owner. For the purposes of this definition, "submitted"+ means any form of electronic, verbal, or written communication sent+ to the Licensor or its representatives, including but not limited to+ communication on electronic mailing lists, source code control systems,+ and issue tracking systems that are managed by, or on behalf of, the+ Licensor for the purpose of discussing and improving the Work, but+ excluding communication that is conspicuously marked or otherwise+ designated in writing by the copyright owner as "Not a Contribution."++ "Contributor" shall mean Licensor and any individual or Legal Entity+ on behalf of whom a Contribution has been received by Licensor and+ subsequently incorporated within the Work.++ 2. Grant of Copyright License. Subject to the terms and conditions of+ this License, each Contributor hereby grants to You a perpetual,+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable+ copyright license to reproduce, prepare Derivative Works of,+ publicly display, publicly perform, sublicense, and distribute the+ Work and such Derivative Works in Source or Object form.++ 3. Grant of Patent License. Subject to the terms and conditions of+ this License, each Contributor hereby grants to You a perpetual,+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable+ (except as stated in this section) patent license to make, have made,+ use, offer to sell, sell, import, and otherwise transfer the Work,+ where such license applies only to those patent claims licensable+ by such Contributor that are necessarily infringed by their+ Contribution(s) alone or by combination of their Contribution(s)+ with the Work to which such Contribution(s) was submitted. If You+ institute patent litigation against any entity (including a+ cross-claim or counterclaim in a lawsuit) alleging that the Work+ or a Contribution incorporated within the Work constitutes direct+ or contributory patent infringement, then any patent licenses+ granted to You under this License for that Work shall terminate+ as of the date such litigation is filed.++ 4. Redistribution. You may reproduce and distribute copies of the+ Work or Derivative Works thereof in any medium, with or without+ modifications, and in Source or Object form, provided that You+ meet the following conditions:++ (a) You must give any other recipients of the Work or+ Derivative Works a copy of this License; and++ (b) You must cause any modified files to carry prominent notices+ stating that You changed the files; and++ (c) You must retain, in the Source form of any Derivative Works+ that You distribute, all copyright, patent, trademark, and+ attribution notices from the Source form of the Work,+ excluding those notices that do not pertain to any part of+ the Derivative Works; and++ (d) If the Work includes a "NOTICE" text file as part of its+ distribution, then any Derivative Works that You distribute must+ include a readable copy of the attribution notices contained+ within such NOTICE file, excluding those notices that do not+ pertain to any part of the Derivative Works, in at least one+ of the following places: within a NOTICE text file distributed+ as part of the Derivative Works; within the Source form or+ documentation, if provided along with the Derivative Works; or,+ within a display generated by the Derivative Works, if and+ wherever such third-party notices normally appear. The contents+ of the NOTICE file are for informational purposes only and+ do not modify the License. You may add Your own attribution+ notices within Derivative Works that You distribute, alongside+ or as an addendum to the NOTICE text from the Work, provided+ that such additional attribution notices cannot be construed+ as modifying the License.++ You may add Your own copyright statement to Your modifications and+ may provide additional or different license terms and conditions+ for use, reproduction, or distribution of Your modifications, or+ for any such Derivative Works as a whole, provided Your use,+ reproduction, and distribution of the Work otherwise complies with+ the conditions stated in this License.++ 5. Submission of Contributions. Unless You explicitly state otherwise,+ any Contribution intentionally submitted for inclusion in the Work+ by You to the Licensor shall be under the terms and conditions of+ this License, without any additional terms or conditions.+ Notwithstanding the above, nothing herein shall supersede or modify+ the terms of any separate license agreement you may have executed+ with Licensor regarding such Contributions.++ 6. Trademarks. This License does not grant permission to use the trade+ names, trademarks, service marks, or product names of the Licensor,+ except as required for reasonable and customary use in describing the+ origin of the Work and reproducing the content of the NOTICE file.++ 7. Disclaimer of Warranty. Unless required by applicable law or+ agreed to in writing, Licensor provides the Work (and each+ Contributor provides its Contributions) on an "AS IS" BASIS,+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or+ implied, including, without limitation, any warranties or conditions+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A+ PARTICULAR PURPOSE. You are solely responsible for determining the+ appropriateness of using or redistributing the Work and assume any+ risks associated with Your exercise of permissions under this License.++ 8. Limitation of Liability. In no event and under no legal theory,+ whether in tort (including negligence), contract, or otherwise,+ unless required by applicable law (such as deliberate and grossly+ negligent acts) or agreed to in writing, shall any Contributor be+ liable to You for damages, including any direct, indirect, special,+ incidental, or consequential damages of any character arising as a+ result of this License or out of the use or inability to use the+ Work (including but not limited to damages for loss of goodwill,+ work stoppage, computer failure or malfunction, or any and all+ other commercial damages or losses), even if such Contributor+ has been advised of the possibility of such damages.++ 9. Accepting Warranty or Additional Liability. While redistributing+ the Work or Derivative Works thereof, You may choose to offer,+ and charge a fee for, acceptance of support, warranty, indemnity,+ or other liability obligations and/or rights consistent with this+ License. However, in accepting such obligations, You may act only+ on Your own behalf and on Your sole responsibility, not on behalf+ of any other Contributor, and only if You agree to indemnify,+ defend, and hold each Contributor harmless for any liability+ incurred by, or claims asserted against, such Contributor by reason+ of your accepting any such warranty or additional liability.++ END OF TERMS AND CONDITIONS++ APPENDIX: How to apply the Apache License to your work.++ To apply the Apache License to your work, attach the following+ boilerplate notice, with the fields enclosed by brackets "[]"+ replaced with your own identifying information. (Don't include+ the brackets!) The text should be enclosed in the appropriate+ comment syntax for the file format. We also recommend that a+ file or class name and description of purpose be included on the+ same "printed page" as the copyright notice for easier+ identification within third-party archives.++ Copyright [yyyy] [name of copyright owner]++ Licensed under the Apache License, Version 2.0 (the "License");+ you may not use this file except in compliance with the License.+ You may obtain a copy of the License at++ http://www.apache.org/licenses/LICENSE-2.0++ Unless required by applicable law or agreed to in writing, software+ distributed under the License is distributed on an "AS IS" BASIS,+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+ See the License for the specific language governing permissions and+ limitations under the License.
+ safe-numeric.cabal view
@@ -0,0 +1,47 @@+cabal-version: 2.4+name: safe-numeric+version: 0.1+synopsis: Safe arithmetic operations.+description:+ @safe-numeric@ provides safer numeric operators, that have more explicit+ behaviour in terms of overflow and underflow, and are harder to misuse.+homepage: https://github.com/infinity0/hs-safe-numeric+bug-reports: https://github.com/infinity0/hs-safe-numeric/issues+license: Apache-2.0+license-file: LICENSE+author: Ximin Luo+maintainer: infinity0@pwned.gg+copyright: (c) 2021 by Ximin Luo+category: Arithmetic, Numeric, Safe+extra-source-files: CHANGELOG.md+tested-with:+ GHC ==8.0.2+ || ==8.2.2+ || ==8.4.4+ || ==8.6.5+ || ==8.8.3+ || ==8.10.4+ || ==9.0.1++library+ exposed-modules: Safe.Numeric+ -- other-modules:+ -- other-extensions:+ build-depends:+ base >=4.9.0.0 && <5+ , safe >=0.3.12 && <4+ , wide-word >=0.1.1.0 && <0.2+ hs-source-dirs: src+ default-language: Haskell2010+ ghc-options: -Wall++test-suite doctests+ build-depends:+ base >=4.5.0.0+ , doctest+ , containers+ hs-source-dirs: test+ type: exitcode-stdio-1.0+ main-is: DocTests.hs+ default-language: Haskell2010+ ghc-options: -Wall
+ src/Safe/Numeric.hs view
@@ -0,0 +1,637 @@+{-# LANGUAGE AllowAmbiguousTypes #-}+{-# LANGUAGE DefaultSignatures #-}+{-# LANGUAGE MultiParamTypeClasses #-}+{-# LANGUAGE ScopedTypeVariables #-}+{-# LANGUAGE TypeSynonymInstances #-}++{- | Safe numeric operations.++We take a fairly conservative approach here - this module is an extension not+a replacement for "Prelude". Our suffix naming conventions are as follows:++- @\@@ or @W@ -- wrap - same as "Prelude", but confirms explicitly to the+ reader that you thought about the issue+- @%@ or @E@ -- explicit error (@'Either' 'ArithException'@)+- @:@ or @S@ -- saturate at 'minBound' or 'maxBound'+- @!@ or @X@ -- runtime exception. This is suitable only for trusted inputs,+ since otherwise you allow the attacker to crash your code arbitrarily.++Currently we provide replacements for:++- conversion functions 'fromIntegral' and 'fromInteger'; instead use++ - 'ex' for cost-free conversions to a bigger or same-sized type, or+ - 'ctW', 'ctE', 'ctS', or 'ctX' for checked conversions to a smaller type++- arithmetic functions '+', '-', '*', '^'; instead use++ - '+@', '+%', '+:', '+!', etc++- division functions 'div', 'mod', 'divMod', 'quot', 'rem', 'quotRem'; instead use++ - 'divE', 'divX', etc++When using this module, you might also like to ban the unsafe functions from+your codebase, e.g. via hlint:++@+- functions:+ - {name: [fromIntegral, fromInteger, +, \'-\', \'*\', ^], within: [], message: "Use safe versions from Safe.Numeric"}+ - {name: [div, mod, divMod, quot, rem, quotRem], within: [], message: "Use safe versions from Safe.Numeric"}+@++-}+module Safe.Numeric+ (+ -- * Conversions+ NumExpand(..)+ , NumConvert(..)+ -- ** Summary of instances+ -- $instances+ , Word29_+ , Int29_+ -- * Arithmetic+ , (+@)+ , (+%)+ , (+:)+ , (+!)+ , (-@)+ , (-%)+ , (-:)+ , (-!)+ , (*@)+ , (*%)+ , (*:)+ , (*!)+ , (^@)+ , (^%)+ , (^:)+ , (^!)+ -- * Division+ , DivResult+ , divE+ , divX+ , modE+ , modX+ , divModE+ , divModX+ , quotE+ , quotX+ , remE+ , remX+ , quotRemE+ , quotRemX+ ) where++-- external+import Control.Exception (ArithException (..))+import Data.Int+import Data.WideWord+import Data.Word+import Safe.Partial (Partial)+++class NumExpand b a where+ {- | Safely expand type @b@ into type @a@, with no runtime bounds checking.++ a.k.a. "'fromIntegral' hurts my fingers and my eyes"++ The value is statically guaranteed to remain the same relative to 0 in both+ directions, i.e. not overflow or underflow, without any runtime checks.+ -}+ ex :: b -> a+ default ex :: (Num a, Integral b) => b -> a+ ex = fromIntegral+ {-# INLINE ex #-}++checkE+ :: forall a . (Integral a, Bounded a) => Integer -> Either ArithException a+checkE v | v < toInteger (minBound :: a) = Left Underflow+ | v > toInteger (maxBound :: a) = Left Overflow+ | otherwise = Right (fromInteger v)+{-# INLINE checkE #-}++checkS :: forall a . (Integral a, Bounded a) => Integer -> a+checkS v | v < toInteger (minBound :: a) = minBound+ | v > toInteger (maxBound :: a) = maxBound+ | otherwise = fromInteger v+{-# INLINE checkS #-}++checkX :: forall a . (Integral a, Bounded a) => Partial => Integer -> a+checkX v | v < toInteger (minBound :: a) = error "Underflow"+ | v > toInteger (maxBound :: a) = error "Overflow"+ | otherwise = fromInteger v+{-# INLINE checkX #-}++-- | Convert from a type into a smaller type+class NumConvert b a where++ -- | Wrap around if the input is out-of-bounds.+ ctW :: b -> a+ default ctW :: (Num a, Integral b) => b -> a+ ctW b = fromIntegral b+ {-# INLINE ctW #-}++ -- | Explicit error if the input is out-of-bounds.+ ctE :: b -> Either ArithException a+ default ctE :: (Integral a, Bounded a, Integral b) => b -> Either ArithException a+ ctE = checkE . toInteger+ {-# INLINE ctE #-}++ -- | Output 'minBound' if the input is too small, or 'maxBound' if too large.+ ctS :: b -> a+ default ctS :: (Integral a, Bounded a, Integral b) => b -> a+ ctS = checkS . toInteger+ {-# INLINE ctS #-}++ -- | Runtime (async) exception if the input is out-of-bounds.+ ctX :: Partial => b -> a+ default ctX :: (Integral a, Bounded a, Integral b) => Partial => b -> a+ ctX = checkX . toInteger+ {-# INLINE ctX #-}++{- | Type alias for 'Word' that explicitly states its lower-bound size. -}+type Word29_ = Word++{- | Type alias for 'Int' that explicitly states its lower-bound size. -}+type Int29_ = Int++{- $instances++@+Fr\\To W8 W16 W29_ W32 W64 W128 W256 I8 I16 I29_ I32 I64 I128 I256 Itgr+W8 X X X X X X X X X X X X X X+W16 X X X X X X X X X X X X+W29_ X X+W32 X X X X X X X X+W64 X X X X X X+W128 X X X X+W256 X X+I8 X X X X X X X X+I16 X X X X X X X+I29_ X X+I32 X X X X X+I64 X X X X+I128 X X X+I256 X X+Itgr X+@++In the above table, X means 'NumExpand', empty means 'NumConvert'.++Safe, free 'NumExpand' from @W29_@ and @I29_@ to other bounded types are not+guaranteed since there is no specified upper bound on the sizes of the former.++Generally, we cannot have @NumExpand a b@ /and/ @NumExpand b a@ unless @b = a@.+-}++-- note: wide-word does not yet define Int256, so references to it below are+-- commented out++{- | -}+instance NumExpand Word8 Word8+instance NumExpand Word8 Word16+instance NumExpand Word8 Word29_+instance NumExpand Word8 Word32+instance NumExpand Word8 Word64+instance NumExpand Word8 Word128+instance NumExpand Word8 Word256+instance NumConvert Word8 Int8+instance NumExpand Word8 Int16+instance NumExpand Word8 Int29_+instance NumExpand Word8 Int32+instance NumExpand Word8 Int64+instance NumExpand Word8 Int128+--instance NumExpand Word8 Int256+instance NumExpand Word8 Integer++instance NumConvert Word16 Word8+instance NumExpand Word16 Word16+instance NumExpand Word16 Word29_+instance NumExpand Word16 Word32+instance NumExpand Word16 Word64+instance NumExpand Word16 Word128+instance NumExpand Word16 Word256+instance NumConvert Word16 Int8+instance NumConvert Word16 Int16+instance NumExpand Word16 Int29_+instance NumExpand Word16 Int32+instance NumExpand Word16 Int64+instance NumExpand Word16 Int128+--instance NumExpand Word16 Int256+instance NumExpand Word16 Integer++instance NumConvert Word29_ Word8+instance NumConvert Word29_ Word16+instance NumExpand Word29_ Word29_+instance NumConvert Word29_ Word32+instance NumConvert Word29_ Word64+instance NumConvert Word29_ Word128+instance NumConvert Word29_ Word256+instance NumConvert Word29_ Int8+instance NumConvert Word29_ Int16+instance NumConvert Word29_ Int29_+instance NumConvert Word29_ Int32+instance NumConvert Word29_ Int64+instance NumConvert Word29_ Int128+--instance NumConvert Word29_ Int256+instance NumExpand Word29_ Integer++instance NumConvert Word32 Word8+instance NumConvert Word32 Word16+instance NumConvert Word32 Word29_+instance NumExpand Word32 Word32+instance NumExpand Word32 Word64+instance NumExpand Word32 Word128+instance NumExpand Word32 Word256+instance NumConvert Word32 Int8+instance NumConvert Word32 Int16+instance NumConvert Word32 Int29_+instance NumConvert Word32 Int32+instance NumExpand Word32 Int64+instance NumExpand Word32 Int128+--instance NumExpand Word32 Int256+instance NumExpand Word32 Integer++instance NumConvert Word64 Word8+instance NumConvert Word64 Word16+instance NumConvert Word64 Word29_+instance NumConvert Word64 Word32+instance NumExpand Word64 Word64+instance NumExpand Word64 Word128+instance NumExpand Word64 Word256+instance NumConvert Word64 Int8+instance NumConvert Word64 Int16+instance NumConvert Word64 Int29_+instance NumConvert Word64 Int32+instance NumConvert Word64 Int64+instance NumExpand Word64 Int128+--instance NumExpand Word64 Int256+instance NumExpand Word64 Integer++instance NumConvert Word128 Word8+instance NumConvert Word128 Word16+instance NumConvert Word128 Word29_+instance NumConvert Word128 Word32+instance NumConvert Word128 Word64+instance NumExpand Word128 Word128+instance NumExpand Word128 Word256+instance NumConvert Word128 Int8+instance NumConvert Word128 Int16+instance NumConvert Word128 Int29_+instance NumConvert Word128 Int32+instance NumConvert Word128 Int64+instance NumConvert Word128 Int128+--instance NumExpand Word128 Int256+instance NumExpand Word128 Integer++instance NumConvert Word256 Word8+instance NumConvert Word256 Word16+instance NumConvert Word256 Word29_+instance NumConvert Word256 Word32+instance NumConvert Word256 Word64+instance NumConvert Word256 Word128+instance NumExpand Word256 Word256+instance NumConvert Word256 Int8+instance NumConvert Word256 Int16+instance NumConvert Word256 Int29_+instance NumConvert Word256 Int32+instance NumConvert Word256 Int64+instance NumConvert Word256 Int128+--instance NumConvert Word256 Int256+instance NumExpand Word256 Integer++instance NumConvert Int8 Word8+instance NumConvert Int8 Word16+instance NumConvert Int8 Word29_+instance NumConvert Int8 Word32+instance NumConvert Int8 Word64+instance NumConvert Int8 Word128+instance NumConvert Int8 Word256+instance NumExpand Int8 Int8+instance NumExpand Int8 Int16+instance NumExpand Int8 Int29_+instance NumExpand Int8 Int32+instance NumExpand Int8 Int64+instance NumExpand Int8 Int128+--instance NumExpand Int8 Int256+instance NumExpand Int8 Integer++instance NumConvert Int16 Word8+instance NumConvert Int16 Word16+instance NumConvert Int16 Word29_+instance NumConvert Int16 Word32+instance NumConvert Int16 Word64+instance NumConvert Int16 Word128+instance NumConvert Int16 Word256+instance NumConvert Int16 Int8+instance NumExpand Int16 Int16+instance NumExpand Int16 Int29_+instance NumExpand Int16 Int32+instance NumExpand Int16 Int64+instance NumExpand Int16 Int128+--instance NumExpand Int16 Int256+instance NumExpand Int16 Integer++instance NumConvert Int29_ Word8+instance NumConvert Int29_ Word16+instance NumConvert Int29_ Word29_+instance NumConvert Int29_ Word32+instance NumConvert Int29_ Word64+instance NumConvert Int29_ Word128+instance NumConvert Int29_ Word256+instance NumConvert Int29_ Int8+instance NumConvert Int29_ Int16+instance NumExpand Int29_ Int29_+instance NumConvert Int29_ Int32+instance NumConvert Int29_ Int64+instance NumConvert Int29_ Int128+--instance NumConvert Int29_ Int256+instance NumExpand Int29_ Integer++instance NumConvert Int32 Word8+instance NumConvert Int32 Word16+instance NumConvert Int32 Word29_+instance NumConvert Int32 Word32+instance NumConvert Int32 Word64+instance NumConvert Int32 Word128+instance NumConvert Int32 Word256+instance NumConvert Int32 Int8+instance NumConvert Int32 Int16+instance NumConvert Int32 Int29_+instance NumExpand Int32 Int32+instance NumExpand Int32 Int64+instance NumExpand Int32 Int128+--instance NumExpand Int32 Int256+instance NumExpand Int32 Integer++instance NumConvert Int64 Word8+instance NumConvert Int64 Word16+instance NumConvert Int64 Word29_+instance NumConvert Int64 Word32+instance NumConvert Int64 Word64+instance NumConvert Int64 Word128+instance NumConvert Int64 Word256+instance NumConvert Int64 Int8+instance NumConvert Int64 Int16+instance NumConvert Int64 Int29_+instance NumConvert Int64 Int32+instance NumExpand Int64 Int64+instance NumExpand Int64 Int128+--instance NumExpand Int64 Int256+instance NumExpand Int64 Integer++instance NumConvert Int128 Word8+instance NumConvert Int128 Word16+instance NumConvert Int128 Word29_+instance NumConvert Int128 Word32+instance NumConvert Int128 Word64+instance NumConvert Int128 Word128+instance NumConvert Int128 Word256+instance NumConvert Int128 Int8+instance NumConvert Int128 Int16+instance NumConvert Int128 Int29_+instance NumConvert Int128 Int32+instance NumConvert Int128 Int64+instance NumExpand Int128 Int128+--instance NumExpand Int128 Int256+instance NumExpand Int128 Integer++{-instance NumConvert Int256 Word8+instance NumConvert Int256 Word16+instance NumConvert Int256 Word29_+instance NumConvert Int256 Word32+instance NumConvert Int256 Word64+instance NumConvert Int256 Word128+instance NumConvert Int256 Word256+instance NumConvert Int256 Int8+instance NumConvert Int256 Int16+instance NumConvert Int256 Int29_+instance NumConvert Int256 Int32+instance NumConvert Int256 Int64+instance NumConvert Int256 Int128+instance NumExpand Int256 Int256+instance NumExpand Int256 Integer-}++instance NumConvert Integer Word8+instance NumConvert Integer Word16+instance NumConvert Integer Word29_+instance NumConvert Integer Word32+instance NumConvert Integer Word64+instance NumConvert Integer Word128+instance NumConvert Integer Word256+instance NumConvert Integer Int8+instance NumConvert Integer Int16+instance NumConvert Integer Int29_+instance NumConvert Integer Int32+instance NumConvert Integer Int64+instance NumConvert Integer Int128+--instance NumConvert Integer Int256+instance NumExpand Integer Integer++{- | Add with wrap-around.++Same as 'Prelude.+' but indicates to the reader that you explicitly thought+about this issue and decided that wrap-around is the correct behaviour.+-}+(+@) :: Num a => a -> a -> a+(+@) = (+)+infixl 6 +@+{-# INLINE (+@) #-}++-- | Add with explicit error on overflow or underflow.+(+%) :: (Integral a, Bounded a) => a -> a -> Either ArithException a+(+%) a b = checkE $ toInteger a + toInteger b+infixl 6 +%+{-# INLINE (+%) #-}++-- | Add with output 'maxBound' on overflow or 'minBound' on underflow.+(+:) :: (Integral a, Bounded a) => a -> a -> a+(+:) a b = checkS $ toInteger a + toInteger b+infixl 6 +:+{-# INLINE (+:) #-}++-- | Add with runtime (async) exception on overflow or underflow.+(+!) :: (Integral a, Bounded a) => Partial => a -> a -> a+(+!) a b = checkX $ toInteger a + toInteger b+infixl 6 +!+{-# INLINE (+!) #-}++{- | Subtract with wrap-around.++Same as 'Prelude.-' but indicates to the reader that you explicitly thought+about this issue and decided that wrap-around is the correct behaviour.+-}+(-@) :: Num a => a -> a -> a+(-@) = (-)+infixl 6 -@+{-# INLINE (-@) #-}++-- | Subtract with explicit error on overflow or underflow.+(-%) :: (Integral a, Bounded a) => a -> a -> Either ArithException a+(-%) a b = checkE $ toInteger a - toInteger b+infixl 6 -%+{-# INLINE (-%) #-}++-- | Subtract with output 'maxBound' on overflow or 'minBound' on underflow.+(-:) :: (Integral a, Bounded a) => a -> a -> a+(-:) a b = checkS $ toInteger a - toInteger b+infixl 6 -:+{-# INLINE (-:) #-}++-- | Subtract with runtime (async) exception on overflow or underflow.+(-!) :: (Integral a, Bounded a) => Partial => a -> a -> a+(-!) a b = checkX $ toInteger a - toInteger b+infixl 6 -!+{-# INLINE (-!) #-}++{- | Multiply with wrap-around.++Same as 'Prelude.*' but indicates to the reader that you explicitly thought+about this issue and decided that wrap-around is the correct behaviour.+-}+(*@) :: Num a => a -> a -> a+(*@) = (*)+infixl 7 *@+{-# INLINE (*@) #-}++-- | Multiply with explicit error on overflow or underflow.+(*%) :: (Integral a, Bounded a) => a -> a -> Either ArithException a+(*%) a b = checkE $ toInteger a * toInteger b+infixl 7 *%+{-# INLINE (*%) #-}++-- | Multiply with output 'maxBound' on overflow or 'minBound' on underflow.+(*:) :: (Integral a, Bounded a) => a -> a -> a+(*:) a b = checkS $ toInteger a * toInteger b+infixl 7 *:+{-# INLINE (*:) #-}++-- | Multiply with runtime (async) exception on overflow or underflow.+(*!) :: (Integral a, Bounded a) => Partial => a -> a -> a+(*!) a b = checkX $ toInteger a * toInteger b+infixl 7 *!+{-# INLINE (*!) #-}++{- | Power with wrap-around.++Same as 'Prelude.^' but indicates to the reader that you explicitly thought+about this issue and decided that wrap-around is the correct behaviour.+-}+(^@) :: Integral a => a -> a -> a+(^@) = (^)+infixr 8 ^@+{-# INLINE (^@) #-}++-- | Power with explicit error on overflow or underflow.+(^%) :: (Integral a, Bounded a) => a -> a -> Either ArithException a+(^%) a b = checkE $ toInteger a ^ toInteger b+infixr 8 ^%+{-# INLINE (^%) #-}++-- | Power with output 'maxBound' on overflow or 'minBound' on underflow.+(^:) :: (Integral a, Bounded a) => a -> a -> a+(^:) a b = checkS $ toInteger a ^ toInteger b+infixr 8 ^:+{-# INLINE (^:) #-}++-- | Power with runtime (async) exception on overflow or underflow.+(^!) :: (Integral a, Bounded a) => Partial => a -> a -> a+(^!) a b = checkX $ toInteger a ^ toInteger b+infixr 8 ^!+{-# INLINE (^!) #-}++{- | Type alias for a division-operation result with explicit error.++The @Left@ case means /division by zero/, and its parameter represents the+sign of the nominator operand.+-}+type DivResult a = Either Ordering a++explicitDiv :: (Eq a, Ord a, Num a) => (a -> a -> b) -> a -> a -> DivResult b+explicitDiv op x y = if y == 0 then Left $ compare x 0 else Right $ x `op` y+{-# INLINE explicitDiv #-}++-- | Division (truncated towards -Inf) with explicit error on division-by-zero.+divE :: Integral a => a -> a -> DivResult a+divE = explicitDiv div+{-# INLINE divE #-}++{- | Division (truncated towards -Inf) with runtime (async) exception on division-by-zero.++Same as 'Prelude.div' but indicates to the reader that you explicitly thought+about this issue and decided that runtime exception is the correct behaviour.+-}+divX :: Integral a => a -> a -> a+divX = div+{-# INLINE divX #-}++-- | Modulus (truncated towards -Inf) with explicit error on division-by-zero.+modE :: Integral a => a -> a -> DivResult a+modE = explicitDiv mod+{-# INLINE modE #-}++{- | Modulus (truncated towards -Inf) with runtime (async) exception on division-by-zero.++Same as 'Prelude.mod' but indicates to the reader that you explicitly thought+about this issue and decided that runtime exception is the correct behaviour.+-}+modX :: Integral a => a -> a -> a+modX = mod+{-# INLINE modX #-}++-- | Division-and-modulus (truncated towards -Inf) with explicit error on division-by-zero.+divModE :: Integral a => a -> a -> DivResult (a, a)+divModE = explicitDiv divMod+{-# INLINE divModE #-}++{- | Division-and-modulus (truncated towards -Inf) with runtime (async) exception on division-by-zero.++Same as 'Prelude.divMod' but indicates to the reader that you explicitly thought+about this issue and decided that runtime exception is the correct behaviour.+-}+divModX :: Integral a => a -> a -> (a, a)+divModX = divMod+{-# INLINE divModX #-}++-- | Division (truncated towards 0) with explicit error on division-by-zero.+quotE :: Integral a => a -> a -> DivResult a+quotE = explicitDiv quot+{-# INLINE quotE #-}++{- | Division (truncated towards 0) with runtime (async) exception on division-by-zero.++Same as 'Prelude.quot' but indicates to the reader that you explicitly thought+about this issue and decided that runtime exception is the correct behaviour.+-}+quotX :: Integral a => a -> a -> a+quotX = quot+{-# INLINE quotX #-}++-- | Modulus (truncated towards 0) with explicit error on division-by-zero.+remE :: Integral a => a -> a -> DivResult a+remE = explicitDiv rem+{-# INLINE remE #-}++{- | Modulus (truncated towards 0) with runtime (async) exception on division-by-zero.++Same as 'Prelude.rem' but indicates to the reader that you explicitly thought+about this issue and decided that runtime exception is the correct behaviour.+-}+remX :: Integral a => a -> a -> a+remX = rem+{-# INLINE remX #-}++-- | Division-and-modulus (truncated towards 0) with explicit error on division-by-zero.+quotRemE :: Integral a => a -> a -> DivResult (a, a)+quotRemE = explicitDiv quotRem+{-# INLINE quotRemE #-}++{- | Division-and-modulus (truncated towards 0) with runtime (async) exception on division-by-zero.++Same as 'Prelude.quotRem' but indicates to the reader that you explicitly thought+about this issue and decided that runtime exception is the correct behaviour.+-}+quotRemX :: Integral a => a -> a -> (a, a)+quotRemX = quotRem+{-# INLINE quotRemX #-}
+ test/DocTests.hs view
@@ -0,0 +1,11 @@+{-# LANGUAGE CPP #-}+import Test.DocTest++main :: IO ()+#if __GLASGOW_HASKELL__ >= 800+-- GHC before this version doesn't support MIN_VERSION_*+-- so doctest doesn't work since it runs outside of cabal+main = doctest ["-i", "src"]+#else+main = return ()+#endif