unwitch 2.0.2 → 2.1.0

raw patch · 16 files changed

+58/−2 lines, 16 filesPVP ok

version bump matches the API change (PVP)

API changes (from Hackage documentation)

Files

• Changelog.md +8/−0
• src/Unwitch/Convert/Double.hs +14/−1
• src/Unwitch/Convert/Float.hs +13/−0
• src/Unwitch/Convert/Int.hs +3/−0
• src/Unwitch/Convert/Int16.hs +1/−0
• src/Unwitch/Convert/Int32.hs +2/−0
• src/Unwitch/Convert/Int64.hs +3/−0
• src/Unwitch/Convert/Int8.hs +1/−0
• src/Unwitch/Convert/Integer.hs +3/−0
• src/Unwitch/Convert/LazyText.hs +1/−0
• src/Unwitch/Convert/Natural.hs +2/−0
• src/Unwitch/Convert/Text.hs +1/−0
• src/Unwitch/Convert/Word.hs +2/−0
• src/Unwitch/Convert/Word32.hs +1/−0
• src/Unwitch/Convert/Word64.hs +2/−0
• unwitch.cabal +1/−1

@@ -1,5 +1,13 @@ # Change log for unwitch project +## Version 2.1.0++ Add Haddock documentation to partial conversion functions across+  all Convert modules — docs focus on non-obvious information only:+  float/double precision limits, via-Integer failure modes (NaN,+  infinity, fractional values), Underflow for negative-to-Natural,+  and Latin-1 encoding constraints++ Remove redundant docs that merely restated the type signature+ ## Version 2.0.2 + Wire up 9 missing test specs that existed but were not included in the test runner + Add module-level haddock to all Convert modules, Errors, and Constant

@@ -34,7 +34,7 @@ import Data.Int import Numeric.Natural (Natural) --- loses precision?!+-- | Lossy narrowing conversion, may lose precision. toFloat :: Double -> Float toFloat = F.double2Float @@ -53,36 +53,47 @@                       | BitConversionFailed Integer   deriving (Show, Eq) +-- | Converts via 'Integer', fails if not a whole number or out of range. toInt8 :: Double -> Either ViaIntegerErrors Int8 toInt8 = toViaInteger Integer.toInt8 +-- | Converts via 'Integer', fails if not a whole number or out of range. toInt16 :: Double -> Either ViaIntegerErrors Int16 toInt16 = toViaInteger Integer.toInt16 +-- | Converts via 'Integer', fails if not a whole number or out of range. toInt32 :: Double -> Either ViaIntegerErrors Int32 toInt32 = toViaInteger Integer.toInt32 +-- | Converts via 'Integer', fails if not a whole number or out of range. toInt64 :: Double -> Either ViaIntegerErrors Int64 toInt64 = toViaInteger Integer.toInt64 +-- | Converts via 'Integer', fails if not a whole number or out of range. toInt :: Double -> Either ViaIntegerErrors Int toInt = toViaInteger Integer.toInt +-- | Converts via 'Integer', fails if not a whole number or out of range. toWord8 :: Double -> Either ViaIntegerErrors Word8 toWord8 = toViaInteger Integer.toWord8 +-- | Converts via 'Integer', fails if not a whole number or out of range. toWord16 :: Double -> Either ViaIntegerErrors Word16 toWord16 = toViaInteger Integer.toWord16 +-- | Converts via 'Integer', fails if not a whole number or out of range. toWord32 :: Double -> Either ViaIntegerErrors Word32 toWord32 = toViaInteger Integer.toWord32 +-- | Converts via 'Integer', fails if not a whole number or out of range. toWord64 :: Double -> Either ViaIntegerErrors Word64 toWord64 = toViaInteger Integer.toWord64 +-- | Converts via 'Integer', fails if not a whole number or out of range. toWord :: Double -> Either ViaIntegerErrors Word toWord = toViaInteger Integer.toWord +-- | Converts via 'Integer', fails if not a whole number, out of range, or negative. toNatural :: Double -> Either ViaIntegerErrors Natural toNatural double = do   integer <- first MkInteger $ toInteger double@@ -90,11 +101,13 @@     Left err -> Left $ MkInteger $ IntegerFlow integer err     Right n -> Right n +-- | Convert via 'Integer' then narrow, combining errors. toViaInteger :: (Integer -> Maybe a) -> Double -> Either ViaIntegerErrors a toViaInteger fun x = do   integer <- first MkInteger $ toInteger x   maybe (Left $ BitConversionFailed integer) Right $ fun integer +-- | Converts to 'Integer', fails if NaN, infinite, or has a fractional part. toInteger :: Double -> Either IntegerErrors Integer toInteger double = do   rational <- first RationalConversion $ toRational double

@@ -44,42 +44,53 @@                       | BitConversionFailed Integer   deriving (Show, Eq) +-- | Converts via 'Integer', fails if not a whole number or out of range. toInt8 :: Float -> Either ViaIntegerErrors Int8 toInt8 = toViaInteger Integer.toInt8  +-- | Converts via 'Integer', fails if not a whole number or out of range. toInt16 :: Float -> Either ViaIntegerErrors Int16 toInt16 = toViaInteger Integer.toInt16  +-- | Converts via 'Integer', fails if not a whole number or out of range. toInt32 :: Float -> Either ViaIntegerErrors Int32 toInt32 = toViaInteger Integer.toInt32  +-- | Converts via 'Integer', fails if not a whole number or out of range. toInt64 :: Float -> Either ViaIntegerErrors Int64 toInt64 = toViaInteger Integer.toInt64  +-- | Converts via 'Integer', fails if not a whole number or out of range. toInt :: Float -> Either ViaIntegerErrors Int toInt = toViaInteger Integer.toInt  +-- | Converts via 'Integer', fails if not a whole number or out of range. toWord8 :: Float -> Either ViaIntegerErrors Word8 toWord8 = toViaInteger Integer.toWord8  +-- | Converts via 'Integer', fails if not a whole number or out of range. toWord16 :: Float -> Either ViaIntegerErrors Word16 toWord16 = toViaInteger Integer.toWord16 +-- | Converts via 'Integer', fails if not a whole number or out of range. toWord32 :: Float -> Either ViaIntegerErrors Word32 toWord32 = toViaInteger Integer.toWord32 +-- | Converts via 'Integer', fails if not a whole number or out of range. toWord64 :: Float -> Either ViaIntegerErrors Word64 toWord64 = toViaInteger Integer.toWord64 +-- | Converts via 'Integer', fails if not a whole number or out of range. toWord :: Float -> Either ViaIntegerErrors Word toWord = toViaInteger Integer.toWord +-- | Converts via 'Integer', fails if not a whole number, out of range, or negative. toNatural :: Float -> Either ViaIntegerErrors Natural toNatural float = do   integer <- first MkInteger $ toInteger float@@ -87,11 +98,13 @@     Left err -> Left $ MkInteger $ IntegerFlow integer err     Right n -> Right n +-- | Convert via 'Integer' then narrow, combining errors. toViaInteger :: (Integer -> Maybe a) -> Float -> Either ViaIntegerErrors a toViaInteger fun x = do   integer <- first MkInteger $ toInteger x   maybe (Left $ BitConversionFailed integer) Right $ fun integer +-- | Converts to 'Integer', fails if NaN, infinite, or has a fractional part. toInteger :: Float -> Either IntegerErrors Integer toInteger float = do   rational <- first RationalConversion $ toRational float

@@ -87,17 +87,20 @@ toWord :: Int -> Maybe Word toWord = Bits.toIntegralSized +-- | Signed-to-unsigned conversion, returns 'Left' 'Underflow' for negative values. toNatural :: Int -> Either Overflows Natural toNatural x = if   | x < 0     -> Left Underflow   | otherwise  -> Right $ fromIntegral x +-- | Checked conversion, fails if outside exact float integer range (+/-16777215). toFloat :: Int -> Either Overflows Float toFloat x = if   | x < -maxIntegralRepFloat -> Left Underflow   | x > maxIntegralRepFloat  -> Left Overflow   | otherwise                -> Right $ fromIntegral x +-- | Checked conversion, fails if outside exact double integer range (+/-9007199254740991). toDouble :: Int -> Either Overflows Double toDouble x = if   | fromIntegral x < (-maxIntegralRepDouble :: Integer) -> Left Underflow

@@ -77,6 +77,7 @@ toWord :: Int16 -> Maybe Word toWord = Bits.toIntegralSized +-- | Signed-to-unsigned conversion, returns 'Left' 'Underflow' for negative values. toNatural :: Int16 -> Either Overflows Natural toNatural x = if   | x < 0     -> Left Underflow

@@ -85,11 +85,13 @@ toWord :: Int32 -> Maybe Word toWord = Bits.toIntegralSized +-- | Signed-to-unsigned conversion, returns 'Left' 'Underflow' for negative values. toNatural :: Int32 -> Either Overflows Natural toNatural x = if   | x < 0     -> Left Underflow   | otherwise  -> Right $ fromIntegral x +-- | Checked conversion, fails if outside exact float integer range (+-16777215). toFloat :: Int32 -> Either Overflows Float toFloat x = if   | x < -maxIntegralRepFloat -> Left Underflow

@@ -91,17 +91,20 @@ toWord :: Int64 -> Maybe Word toWord = Bits.toIntegralSized +-- | Signed-to-unsigned conversion, returns 'Left' 'Underflow' for negative values. toNatural :: Int64 -> Either Overflows Natural toNatural x = if   | x < 0     -> Left Underflow   | otherwise  -> Right $ fromIntegral x +-- | Checked conversion, fails if outside exact float integer range (+-16777215). toFloat :: Int64 -> Either Overflows Float toFloat x = if   | x < -maxIntegralRepFloat -> Left Underflow   | x > maxIntegralRepFloat  -> Left Overflow   | otherwise                -> Right $ fromIntegral x +-- | Checked conversion, fails if outside exact double integer range (+-9007199254740991). toDouble :: Int64 -> Either Overflows Double toDouble x = if   | x < -maxIntegralRepDouble -> Left Underflow

@@ -74,6 +74,7 @@ toWord :: Int8 -> Maybe Word toWord = Bits.toIntegralSized +-- | Signed-to-unsigned conversion, returns 'Left' 'Underflow' for negative values. toNatural :: Int8 -> Either Overflows Natural toNatural x = if   | x < 0     -> Left Underflow

@@ -62,18 +62,21 @@ -- @UnboxedTuples@ language extensions. -- See the <https://downloads.haskell.org/ghc/latest/docs/users_guide/exts/primitives.html GHC manual on unboxed types>. +-- | Checked conversion, fails if outside exact double integer range (\u00b19007199254740991). toDouble :: Integer -> Either Overflows Double toDouble integer = if     | integer < -maxIntegralRepDouble -> Left Underflow     | integer > maxIntegralRepDouble -> Left Overflow     | otherwise -> Right $ Prelude.fromIntegral integer +-- | Checked conversion, fails if outside exact float integer range (\u00b116777215). toFloat :: Integer -> Either Overflows Float toFloat integer = if     | integer < -maxIntegralRepFloat -> Left Underflow     | integer > maxIntegralRepFloat -> Left Overflow     | otherwise -> Right $ Prelude.fromIntegral integer +-- | Returns 'Left' 'Underflow' for negative values. toNatural :: Integer -> Either Overflows Natural toNatural integer = if     | integer < 0 -> Left Underflow

@@ -42,6 +42,7 @@ toLazyByteStringUtf32BE :: LT.Text -> LBS.ByteString toLazyByteStringUtf32BE = LTE.encodeUtf32BE +-- | Returns 'Nothing' if any character exceeds @\xFF@. toLazyByteStringLatin1 :: LT.Text -> Maybe LBS.ByteString toLazyByteStringLatin1 t = if LT.all isLatin1 t   then Just $ LBSC8.pack (LT.unpack t)

@@ -93,11 +93,13 @@ toInteger :: Natural -> Integer toInteger = fromIntegral +-- | Checked conversion, fails if outside exact float integer range (\u00b116777215). toFloat :: Natural -> Either Overflows Float toFloat x = if   | x > maxIntegralRepFloat -> Left Overflow   | otherwise               -> Right $ fromIntegral x +-- | Checked conversion, fails if outside exact double integer range (\u00b19007199254740991). toDouble :: Natural -> Either Overflows Double toDouble x = if   | x > maxIntegralRepDouble -> Left Overflow

@@ -43,6 +43,7 @@ toByteStringUtf32BE :: Text -> ByteString toByteStringUtf32BE = TE.encodeUtf32BE +-- | Returns 'Nothing' if any character exceeds @\xFF@. toByteStringLatin1 :: Text -> Maybe ByteString toByteStringLatin1 t = if T.all isLatin1 t   then Just $ BSC8.pack (T.unpack t)

@@ -87,11 +87,13 @@ toInteger :: Word -> Integer toInteger = fromIntegral +-- | Checked conversion, fails if outside exact float integer range (+-16777215). toFloat :: Word -> Either Overflows Float toFloat x = if   | x > maxIntegralRepFloat -> Left Overflow   | otherwise               -> Right $ fromIntegral x +-- | Checked conversion, fails if outside exact double integer range (+-9007199254740991). toDouble :: Word -> Either Overflows Double toDouble x = if   | fromIntegral x > (maxIntegralRepDouble :: Integer) -> Left Overflow

@@ -85,6 +85,7 @@ toInteger :: Word32 -> Integer toInteger = fromIntegral +-- | Checked conversion, fails with 'Overflow' if outside exact float integer range. toFloat :: Word32 -> Either Overflows Float toFloat x = if   | x > maxIntegralRepFloat -> Left Overflow

@@ -90,11 +90,13 @@ toInteger :: Word64 -> Integer toInteger = fromIntegral +-- | Checked conversion, fails with 'Overflow' if outside exact float integer range. toFloat :: Word64 -> Either Overflows Float toFloat x = if   | x > maxIntegralRepFloat -> Left Overflow   | otherwise               -> Right $ fromIntegral x +-- | Checked conversion, fails with 'Overflow' if outside exact double integer range. toDouble :: Word64 -> Either Overflows Double toDouble x = if   | x > maxIntegralRepDouble -> Left Overflow

@@ -1,7 +1,7 @@ cabal-version:      3.0  name:           unwitch-version:        2.0.2+version:        2.1.0 homepage:       https://github.com/jappeace/unwitch#readme synopsis:  converts between primitives description: