diff options
author | nikshalark <nks@nk5.nl> | 2022-02-11 09:50:03 -0600 |
---|---|---|
committer | Marge Bot <ben+marge-bot@smart-cactus.org> | 2022-02-13 03:26:16 -0500 |
commit | ef5cf55d71e84a0a42596b4ec253ecb0d63f149b (patch) | |
tree | 95fcbaa58bec75e80f9f10f02bb758612451052f | |
parent | 95fab83f3af2e3b54fb59d761b38466344608ed8 (diff) | |
download | haskell-ef5cf55d71e84a0a42596b4ec253ecb0d63f149b.tar.gz |
(#21044) Documented arithmetic functions in base.
Didn't get it right the ninth time. Now everything's formatted correctly.
-rw-r--r-- | libraries/base/GHC/Arr.hs | 11 | ||||
-rw-r--r-- | libraries/base/GHC/Base.hs | 68 | ||||
-rw-r--r-- | libraries/base/GHC/Float.hs | 9 | ||||
-rw-r--r-- | libraries/base/GHC/Integer.hs | 180 |
4 files changed, 264 insertions, 4 deletions
diff --git a/libraries/base/GHC/Arr.hs b/libraries/base/GHC/Arr.hs index 63d79237c5..307b31e9ff 100644 --- a/libraries/base/GHC/Arr.hs +++ b/libraries/base/GHC/Arr.hs @@ -231,7 +231,16 @@ lessSafeIndex :: Ix i => (i, i) -> Int -> i -> Int lessSafeIndex (l,u) _ i = index (l,u) i -- Don't inline this long error message everywhere!! -badSafeIndex :: Int -> Int -> Int +-- | Used to throw exceptions in array bounds-checking functions. +-- +-- ⚠ This function throws 'SomeException' in all cases. +-- +-- ==== __Examples__ +-- >>> badSafeIndex 2 5 +-- *** Exception: Error in array index; 2 not in range [0..5) +badSafeIndex :: Int -- ^ Index searched for. + -> Int -- ^ Max bound of the array. + -> Int -- ^ This isn't an Int. It's an exception. badSafeIndex i' n = errorWithoutStackTrace ("Error in array index; " ++ show i' ++ " not in range [0.." ++ show n ++ ")") diff --git a/libraries/base/GHC/Base.hs b/libraries/base/GHC/Base.hs index bf1527076c..9463570d46 100644 --- a/libraries/base/GHC/Base.hs +++ b/libraries/base/GHC/Base.hs @@ -1629,17 +1629,83 @@ getTag x = dataToTag# x {-# INLINE quotRemInt #-} {-# INLINE divModInt #-} -quotInt, remInt, divInt, modInt :: Int -> Int -> Int +-- | Used to implement `quot` for the `Integral` typeclass. +-- This performs integer division on its two parameters, truncated towards zero. +-- +-- ==== __Example__ +-- >>> quotInt 10 2 +-- 5 +-- +-- >>> quot 10 2 +-- 5 +quotInt :: Int -> Int -> Int (I# x) `quotInt` (I# y) = I# (x `quotInt#` y) +-- | Used to implement `rem` for the `Integral` typeclass. +-- This gives the remainder after integer division of its two parameters, satisfying +-- +-- > ((x `quot` y) * y) + (x `rem` y) == x +-- +-- ==== __Example__ +-- >>> remInt 3 2 +-- 1 +-- +-- >>> rem 3 2 +-- 1 +remInt :: Int -> Int -> Int (I# x) `remInt` (I# y) = I# (x `remInt#` y) +-- | Used to implement `div` for the `Integral` typeclass. +-- This performs integer division on its two parameters, truncated towards negative infinity. +-- +-- ==== __Example__ +-- >>> 10 `divInt` 2 +-- 5 +-- +-- >>> 10 `div` 2 +-- 5 +divInt :: Int -> Int -> Int (I# x) `divInt` (I# y) = I# (x `divInt#` y) +-- | Used to implement `mod` for the `Integral` typeclass. +-- This performs the modulo operation, satisfying +-- +-- > ((x `div` y) * y) + (x `mod` y) == x +-- +-- ==== __Example__ +-- >>> 7 `modInt` 3 +-- 1 +-- +-- >>> 7 `mod` 3 +-- 1 +modInt :: Int -> Int -> Int (I# x) `modInt` (I# y) = I# (x `modInt#` y) + +-- | Used to implement `quotRem` for the `Integral` typeclass. +-- This gives a tuple equivalent to +-- +-- > (quot x y, mod x y) +-- +-- ==== __Example__ +-- >>> quotRemInt 10 2 +-- (5,0) +-- +-- >>> quotRem 10 2 +-- (5,0) quotRemInt :: Int -> Int -> (Int, Int) (I# x) `quotRemInt` (I# y) = case x `quotRemInt#` y of (# q, r #) -> (I# q, I# r) +-- | Used to implement `divMod` for the `Integral` typeclass. +-- This gives a tuple equivalent to +-- +-- > (div x y, mod x y) +-- +-- ==== __Example__ +-- >>> divModInt 10 2 +-- (5,0) +-- +-- >>> divMod 10 2 +-- (5,0) divModInt :: Int -> Int -> (Int, Int) (I# x) `divModInt` (I# y) = case x `divModInt#` y of (# q, r #) -> (I# q, I# r) diff --git a/libraries/base/GHC/Float.hs b/libraries/base/GHC/Float.hs index b73a5994a5..ffe9fdc7b9 100644 --- a/libraries/base/GHC/Float.hs +++ b/libraries/base/GHC/Float.hs @@ -1502,6 +1502,15 @@ called from scaleFloat, hence we clamp the scaling parameter. We must have a large enough range to cover the maximum difference of exponents returned by decodeFloat. -} + +-- | Used to prevent exponent over/underflow when encoding floating point numbers. +-- This is also the same as +-- +-- > \(x,y) -> max (-x) (min x y) +-- +-- ==== __Example__ +-- >>> clamp (-10) 5 +-- 10 clamp :: Int -> Int -> Int clamp bd k = max (-bd) (min bd k) diff --git a/libraries/base/GHC/Integer.hs b/libraries/base/GHC/Integer.hs index 070bd8fb61..70784b98fa 100644 --- a/libraries/base/GHC/Integer.hs +++ b/libraries/base/GHC/Integer.hs @@ -100,62 +100,238 @@ encodeDoubleInteger = I.integerEncodeDouble# decodeDoubleInteger :: Double# -> (# Integer, Int# #) decodeDoubleInteger = I.integerDecodeDouble# - +-- | Used to implement `(+)` for the `Num` typeclass. +-- This gives the sum of two integers. +-- +-- ==== __Example__ +-- >>> plusInteger 3 2 +-- 5 +-- +-- >>> (+) 3 2 +-- 5 plusInteger :: Integer -> Integer -> Integer plusInteger = I.integerAdd +-- | Used to implement `(-)` for the `Num` typeclass. +-- This gives the difference of two integers. +-- +-- ==== __Example__ +-- >>> minusInteger 3 2 +-- 1 +-- +-- >>> (-) 3 2 +-- 1 minusInteger :: Integer -> Integer -> Integer minusInteger = I.integerSub +-- | Used to implement `(*)` for the `Num` typeclass. +-- This gives the product of two integers. +-- +-- ==== __Example__ +-- >>> timesInteger 3 2 +-- 6 +-- +-- >>> (*) 3 2 +-- 6 timesInteger :: Integer -> Integer -> Integer timesInteger = I.integerMul +-- | Used to implement `negate` for the `Num` typeclass. +-- This changes the sign of whatever integer is passed into it. +-- +-- ==== __Example__ +-- >>> negateInteger (-6) +-- 6 +-- +-- >>> negate (-6) +-- 6 negateInteger :: Integer -> Integer negateInteger = I.integerNegate +-- | Used to implement `abs` for the `Num` typeclass. +-- This gives the absolute value of whatever integer is passed into it. +-- +-- ==== __Example__ +-- >>> absInteger (-6) +-- 6 +-- +-- >>> abs (-6) +-- 6 absInteger :: Integer -> Integer absInteger = I.integerAbs +-- | Used to implement `signum` for the `Num` typeclass. +-- This gives 1 for a positive integer, and -1 for a negative integer. +-- +-- ==== __Example__ +-- >>> signumInteger 5 +-- 1 +-- +-- >>> signum 5 +-- 1 signumInteger :: Integer -> Integer signumInteger = I.integerSignum +-- | Used to implement `divMod` for the `Integral` typeclass. +-- This gives a tuple equivalent to +-- +-- >(div x y, mod x y) +-- +-- ==== __Example__ +-- >>> divModInteger 10 2 +-- (5,0) +-- +-- >>> divMod 10 2 +-- (5,0) divModInteger :: Integer -> Integer -> (# Integer, Integer #) divModInteger = I.integerDivMod# +-- | Used to implement `div` for the `Integral` typeclass. +-- This performs integer division on its two parameters, truncated towards negative infinity. +-- +-- ==== __Example__ +-- >>> 10 `divInteger` 2 +-- 5 +-- +-- >>> 10 `div` 2 divInteger :: Integer -> Integer -> Integer divInteger = I.integerDiv +-- | Used to implement `mod` for the `Integral` typeclass. +-- This performs the modulo operation, satisfying +-- +-- > ((x `div` y) * y) + (x `mod` y) == x +-- +-- ==== __Example__ +-- >>> 7 `modInteger` 3 +-- 1 +-- +-- >>> 7 `mod` 3 +-- 1 modInteger :: Integer -> Integer -> Integer modInteger = I.integerMod +-- | Used to implement `quotRem` for the `Integral` typeclass. +-- This gives a tuple equivalent to +-- +-- > (quot x y, mod x y) +-- +-- ==== __Example__ +-- >>> quotRemInteger 10 2 +-- (5,0) +-- +-- >>> quotRem 10 2 +-- (5,0) quotRemInteger :: Integer -> Integer -> (# Integer, Integer #) quotRemInteger = I.integerQuotRem# +-- | Used to implement `quot` for the `Integral` typeclass. +-- This performs integer division on its two parameters, truncated towards zero. +-- +-- ==== __Example__ +-- >>> quotInteger 10 2 +-- 5 +-- +-- >>> quot 10 2 +-- 5 quotInteger :: Integer -> Integer -> Integer quotInteger = I.integerQuot +-- | Used to implement `rem` for the `Integral` typeclass. +-- This gives the remainder after integer division of its two parameters, satisfying +-- +-- > ((x `quot` y) * y) + (x `rem` y) == x +-- +-- ==== __Example__ +-- >>> remInteger 3 2 +-- 1 +-- +-- >>> rem 3 2 +-- 1 remInteger :: Integer -> Integer -> Integer remInteger = I.integerRem - +-- | Used to implement `(==)` for the `Eq` typeclass. +-- Outputs `True` if two integers are equal to each other. +-- +-- ==== __Example__ +-- >>> 6 `eqInteger` 6 +-- True +-- +-- >>> 6 == 6 +-- True eqInteger :: Integer -> Integer -> Bool eqInteger = I.integerEq +-- | Used to implement `(/=)` for the `Eq` typeclass. +-- Outputs `True` if two integers are not equal to each other. +-- +-- ==== __Example__ +-- >>> 6 `neqInteger` 7 +-- True +-- +-- >>> 6 /= 7 +-- True neqInteger :: Integer -> Integer -> Bool neqInteger = I.integerNe +-- | Used to implement `(<=)` for the `Ord` typeclass. +-- Outputs `True` if the first argument is less than or equal to the second. +-- +-- ==== __Example__ +-- >>> 3 `leInteger` 5 +-- True +-- +-- >>> 3 <= 5 +-- True leInteger :: Integer -> Integer -> Bool leInteger = I.integerLe +-- | Used to implement `(>)` for the `Ord` typeclass. +-- Outputs `True` if the first argument is greater than the second. +-- +-- ==== __Example__ +-- >>> 5 `gtInteger` 3 +-- True +-- +-- >>> 5 > 3 +-- True gtInteger :: Integer -> Integer -> Bool gtInteger = I.integerGt +-- | Used to implement `(<)` for the `Ord` typeclass. +-- Outputs `True` if the first argument is less than the second. +-- +-- ==== __Example__ +-- >>> 3 `ltInteger` 5 +-- True +-- +-- >>> 3 < 5 +-- True ltInteger :: Integer -> Integer -> Bool ltInteger = I.integerLt +-- | Used to implement `(>=)` for the `Ord` typeclass. +-- Outputs `True` if the first argument is greater than or equal to the second. +-- +-- ==== __Example__ +-- >>> 5 `geInteger` 3 +-- True +-- +-- >>> 5 >= 3 +-- True geInteger :: Integer -> Integer -> Bool geInteger = I.integerGe +-- | Used to implement `compare` for the `Integral` typeclass. +-- This takes two integers, and outputs whether the first is less than, equal to, or greater than the second. +-- +-- ==== __Example__ +-- >>> compareInteger 2 10 +-- LT +-- +-- >>> compare 2 10 +-- LT compareInteger :: Integer -> Integer -> Ordering compareInteger = I.integerCompare |