diff --git a/Changelog.md b/Changelog.md --- a/Changelog.md +++ b/Changelog.md @@ -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 diff --git a/src/Unwitch/Convert/Double.hs b/src/Unwitch/Convert/Double.hs --- a/src/Unwitch/Convert/Double.hs +++ b/src/Unwitch/Convert/Double.hs @@ -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 diff --git a/src/Unwitch/Convert/Float.hs b/src/Unwitch/Convert/Float.hs --- a/src/Unwitch/Convert/Float.hs +++ b/src/Unwitch/Convert/Float.hs @@ -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 diff --git a/src/Unwitch/Convert/Int.hs b/src/Unwitch/Convert/Int.hs --- a/src/Unwitch/Convert/Int.hs +++ b/src/Unwitch/Convert/Int.hs @@ -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 diff --git a/src/Unwitch/Convert/Int16.hs b/src/Unwitch/Convert/Int16.hs --- a/src/Unwitch/Convert/Int16.hs +++ b/src/Unwitch/Convert/Int16.hs @@ -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 diff --git a/src/Unwitch/Convert/Int32.hs b/src/Unwitch/Convert/Int32.hs --- a/src/Unwitch/Convert/Int32.hs +++ b/src/Unwitch/Convert/Int32.hs @@ -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 diff --git a/src/Unwitch/Convert/Int64.hs b/src/Unwitch/Convert/Int64.hs --- a/src/Unwitch/Convert/Int64.hs +++ b/src/Unwitch/Convert/Int64.hs @@ -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 diff --git a/src/Unwitch/Convert/Int8.hs b/src/Unwitch/Convert/Int8.hs --- a/src/Unwitch/Convert/Int8.hs +++ b/src/Unwitch/Convert/Int8.hs @@ -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 diff --git a/src/Unwitch/Convert/Integer.hs b/src/Unwitch/Convert/Integer.hs --- a/src/Unwitch/Convert/Integer.hs +++ b/src/Unwitch/Convert/Integer.hs @@ -62,18 +62,21 @@ -- @UnboxedTuples@ language extensions. -- See the . +-- | 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 diff --git a/src/Unwitch/Convert/LazyText.hs b/src/Unwitch/Convert/LazyText.hs --- a/src/Unwitch/Convert/LazyText.hs +++ b/src/Unwitch/Convert/LazyText.hs @@ -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) diff --git a/src/Unwitch/Convert/Natural.hs b/src/Unwitch/Convert/Natural.hs --- a/src/Unwitch/Convert/Natural.hs +++ b/src/Unwitch/Convert/Natural.hs @@ -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 diff --git a/src/Unwitch/Convert/Text.hs b/src/Unwitch/Convert/Text.hs --- a/src/Unwitch/Convert/Text.hs +++ b/src/Unwitch/Convert/Text.hs @@ -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) diff --git a/src/Unwitch/Convert/Word.hs b/src/Unwitch/Convert/Word.hs --- a/src/Unwitch/Convert/Word.hs +++ b/src/Unwitch/Convert/Word.hs @@ -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 diff --git a/src/Unwitch/Convert/Word32.hs b/src/Unwitch/Convert/Word32.hs --- a/src/Unwitch/Convert/Word32.hs +++ b/src/Unwitch/Convert/Word32.hs @@ -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 diff --git a/src/Unwitch/Convert/Word64.hs b/src/Unwitch/Convert/Word64.hs --- a/src/Unwitch/Convert/Word64.hs +++ b/src/Unwitch/Convert/Word64.hs @@ -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 diff --git a/unwitch.cabal b/unwitch.cabal --- a/unwitch.cabal +++ b/unwitch.cabal @@ -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: