diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 --- /dev/null +++ b/CHANGELOG.md @@ -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. diff --git a/LICENSE b/LICENSE new file mode 100644 --- /dev/null +++ b/LICENSE @@ -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. diff --git a/safe-numeric.cabal b/safe-numeric.cabal new file mode 100644 --- /dev/null +++ b/safe-numeric.cabal @@ -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 diff --git a/src/Safe/Numeric.hs b/src/Safe/Numeric.hs new file mode 100644 --- /dev/null +++ b/src/Safe/Numeric.hs @@ -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 #-} diff --git a/test/DocTests.hs b/test/DocTests.hs new file mode 100644 --- /dev/null +++ b/test/DocTests.hs @@ -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