diff --git a/Changelog.md b/Changelog.md --- a/Changelog.md +++ b/Changelog.md @@ -1,6 +1,12 @@ # Change log for unwitch project -## Version 2.0.0 +## Version 2.0.1 ++ Add haddock section headers separating boxed and unboxed conversions ++ Each module with unboxed functions now has "Conversions" and + "Unboxed conversions" sections with documentation explaining + zero-allocation failure handling and required GHC extensions. + +## Version 2.0.0 + fix cabal file links + delete complex module which made no sense. diff --git a/src/Unwitch/Convert/Char.hs b/src/Unwitch/Convert/Char.hs --- a/src/Unwitch/Convert/Char.hs +++ b/src/Unwitch/Convert/Char.hs @@ -1,8 +1,11 @@ module Unwitch.Convert.Char - ( toInt + ( -- * Conversions + toInt , toWord , fromInt , fromWord + -- * Unboxed conversions + -- $unboxed , fromInt# , fromWord# ) @@ -11,6 +14,12 @@ import Data.Char (ord, chr) import GHC.Exts (Int(..), Word(..), Char(..), chr#, word2Int#, (>=#), (<=#), leWord#, gtWord#) + +-- $unboxed +-- These use GHC unboxed types and unboxed sums for zero-allocation +-- failure handling. Requires the @MagicHash@, @UnboxedSums@ and +-- @UnboxedTuples@ language extensions. +-- See the . -- | Converts a Char to its Unicode codepoint as Int. Infallible. toInt :: Char -> Int 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 @@ -1,27 +1,30 @@ module Unwitch.Convert.Int - ( toInt8 - , toInt8# + ( -- * Conversions + toInt8 , toInt16 - , toInt16# , toInt32 - , toInt32# , toInt64 , toInteger , toWord8 - , toWord8# , toWord16 - , toWord16# , toWord32 - , toWord32# , toWord64 - , toWord64# , toWord - , toWord# , toNatural - , toNatural# , toFloat - , toFloat# , toDouble + -- * Unboxed conversions + -- $unboxed + , toInt8# + , toInt16# + , toInt32# + , toWord8# + , toWord16# + , toWord32# + , toWord64# + , toWord# + , toNatural# + , toFloat# , toDouble# ) where @@ -46,6 +49,12 @@ import GHC.Int (Int8(..), Int16(..), Int32(..)) import GHC.Word (Word8(..), Word16(..), Word32(..), Word64(..)) import GHC.Num.Natural (Natural(NS)) + +-- $unboxed +-- These use GHC unboxed types and unboxed sums for zero-allocation +-- failure handling. Requires the @MagicHash@, @UnboxedSums@ and +-- @UnboxedTuples@ language extensions. +-- See the . toInt8 :: Int -> Maybe Int8 toInt8 = Bits.toIntegralSized 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 @@ -1,5 +1,6 @@ module Unwitch.Convert.Int16 - ( toInt8 + ( -- * Conversions + toInt8 , toInt32 , toInt64 , toInt @@ -12,6 +13,8 @@ , toNatural , toFloat , toDouble + -- * Unboxed conversions + -- $unboxed , toInt8# , toWord8# , toWord16# @@ -36,6 +39,12 @@ import GHC.Int (Int8(..), Int16(..)) import GHC.Word (Word8(..), Word16(..), Word32(..), Word64(..)) import GHC.Num.Natural (Natural(NS)) + +-- $unboxed +-- These use GHC unboxed types and unboxed sums for zero-allocation +-- failure handling. Requires the @MagicHash@, @UnboxedSums@ and +-- @UnboxedTuples@ language extensions. +-- See the . toInt8 :: Int16 -> Maybe Int8 toInt8 = Bits.toIntegralSized 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 @@ -1,5 +1,6 @@ module Unwitch.Convert.Int32 - ( toInt8 + ( -- * Conversions + toInt8 , toInt16 , toInt64 , toInt @@ -12,6 +13,8 @@ , toNatural , toFloat , toDouble + -- * Unboxed conversions + -- $unboxed , toInt8# , toInt16# , toInt# @@ -44,6 +47,12 @@ import GHC.Int (Int8(..), Int16(..), Int32(..)) import GHC.Word (Word8(..), Word16(..), Word32(..), Word64(..)) import GHC.Num.Natural (Natural(NS)) + +-- $unboxed +-- These use GHC unboxed types and unboxed sums for zero-allocation +-- failure handling. Requires the @MagicHash@, @UnboxedSums@ and +-- @UnboxedTuples@ language extensions. +-- See the . toInt8 :: Int32 -> Maybe Int8 toInt8 = Bits.toIntegralSized 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 @@ -1,5 +1,6 @@ module Unwitch.Convert.Int64 - ( toInt8 + ( -- * Conversions + toInt8 , toInt16 , toInt32 , toInt @@ -12,6 +13,8 @@ , toNatural , toFloat , toDouble + -- * Unboxed conversions + -- $unboxed , toInt8# , toInt16# , toInt32# @@ -50,6 +53,12 @@ import GHC.Int (Int8(..), Int16(..), Int32(..), Int64(..)) import GHC.Word (Word8(..), Word16(..), Word32(..), Word64(..)) import GHC.Num.Natural (Natural(NS)) + +-- $unboxed +-- These use GHC unboxed types and unboxed sums for zero-allocation +-- failure handling. Requires the @MagicHash@, @UnboxedSums@ and +-- @UnboxedTuples@ language extensions. +-- See the . toInt8 :: Int64 -> Maybe Int8 toInt8 = Bits.toIntegralSized 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 @@ -1,5 +1,6 @@ module Unwitch.Convert.Int8 - ( toInt16 + ( -- * Conversions + toInt16 , toInt32 , toInt64 , toInt @@ -12,6 +13,8 @@ , toNatural , toFloat , toDouble + -- * Unboxed conversions + -- $unboxed , toWord8# , toWord16# , toWord32# @@ -33,6 +36,12 @@ import GHC.Int (Int8(..)) import GHC.Word (Word8(..), Word16(..), Word32(..), Word64(..)) import GHC.Num.Natural (Natural(NS)) + +-- $unboxed +-- These use GHC unboxed types and unboxed sums for zero-allocation +-- failure handling. Requires the @MagicHash@, @UnboxedSums@ and +-- @UnboxedTuples@ language extensions. +-- See the . toInt16 :: Int8 -> Int16 toInt16 = fromIntegral 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 @@ -1,29 +1,32 @@ module Unwitch.Convert.Integer - ( toDouble - , toDouble# + ( -- * Conversions + toDouble , toFloat - , toFloat# , toNatural - , toNatural# , toInt8 - , toInt8# , toInt16 - , toInt16# , toInt32 - , toInt32# , toInt64 - , toInt64# , toInt - , toInt# , toWord8 - , toWord8# , toWord16 - , toWord16# , toWord32 - , toWord32# , toWord64 - , toWord64# , toWord + -- * Unboxed conversions + -- $unboxed + , toDouble# + , toFloat# + , toNatural# + , toInt8# + , toInt16# + , toInt32# + , toInt64# + , toInt# + , toWord8# + , toWord16# + , toWord32# + , toWord64# , toWord# ) where @@ -52,6 +55,11 @@ integerFromWord#, integerEq#) import GHC.Num.Natural (Natural(NS, NB)) +-- $unboxed +-- These use GHC unboxed types and unboxed sums for zero-allocation +-- failure handling. Requires the @MagicHash@, @UnboxedSums@ and +-- @UnboxedTuples@ language extensions. +-- See the . toDouble :: Integer -> Either Overflows Double toDouble integer = if 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 @@ -1,5 +1,6 @@ module Unwitch.Convert.Natural - ( toWord8 + ( -- * Conversions + toWord8 , toWord16 , toWord32 , toWord64 @@ -12,6 +13,8 @@ , toInteger , toFloat , toDouble + -- * Unboxed conversions + -- $unboxed , toWord8# , toWord16# , toWord32# @@ -49,6 +52,12 @@ import GHC.Int (Int8(..), Int16(..), Int32(..), Int64(..)) import GHC.Word (Word8(..), Word16(..), Word32(..), Word64(..)) import GHC.Num.Natural (naturalToWordMaybe#) + +-- $unboxed +-- These use GHC unboxed types and unboxed sums for zero-allocation +-- failure handling. Requires the @MagicHash@, @UnboxedSums@ and +-- @UnboxedTuples@ language extensions. +-- See the . toWord8 :: Natural -> Maybe Word8 toWord8 = Bits.toIntegralSized 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 @@ -1,5 +1,6 @@ module Unwitch.Convert.Word - ( toWord8 + ( -- * Conversions + toWord8 , toWord16 , toWord32 , toWord64 @@ -12,6 +13,8 @@ , toInteger , toFloat , toDouble + -- * Unboxed conversions + -- $unboxed , toWord8# , toWord16# , toWord32# @@ -43,6 +46,12 @@ eqWord#, leWord#, (>=#)) import GHC.Int (Int8(..), Int16(..), Int32(..), Int64(..)) import GHC.Word (Word8(..), Word16(..), Word32(..)) + +-- $unboxed +-- These use GHC unboxed types and unboxed sums for zero-allocation +-- failure handling. Requires the @MagicHash@, @UnboxedSums@ and +-- @UnboxedTuples@ language extensions. +-- See the . toWord8 :: Word -> Maybe Word8 toWord8 = Bits.toIntegralSized diff --git a/src/Unwitch/Convert/Word16.hs b/src/Unwitch/Convert/Word16.hs --- a/src/Unwitch/Convert/Word16.hs +++ b/src/Unwitch/Convert/Word16.hs @@ -1,5 +1,6 @@ module Unwitch.Convert.Word16 - ( toWord8 + ( -- * Conversions + toWord8 , toWord32 , toWord64 , toWord @@ -12,6 +13,8 @@ , toInteger , toFloat , toDouble + -- * Unboxed conversions + -- $unboxed , toWord8# , toInt8# , toInt16# @@ -30,6 +33,12 @@ eqWord#, (==#)) import GHC.Int (Int8(..), Int16(..)) import GHC.Word (Word8(..), Word16(..)) + +-- $unboxed +-- These use GHC unboxed types and unboxed sums for zero-allocation +-- failure handling. Requires the @MagicHash@, @UnboxedSums@ and +-- @UnboxedTuples@ language extensions. +-- See the . toWord8 :: Word16 -> Maybe Word8 toWord8 = Bits.toIntegralSized 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 @@ -1,5 +1,6 @@ module Unwitch.Convert.Word32 - ( toWord8 + ( -- * Conversions + toWord8 , toWord16 , toWord64 , toWord @@ -12,6 +13,8 @@ , toInteger , toFloat , toDouble + -- * Unboxed conversions + -- $unboxed , toWord8# , toWord16# , toWord# @@ -41,6 +44,12 @@ eqWord#, leWord#, (==#), (>=#)) import GHC.Int (Int8(..), Int16(..), Int32(..)) import GHC.Word (Word8(..), Word16(..), Word32(..)) + +-- $unboxed +-- These use GHC unboxed types and unboxed sums for zero-allocation +-- failure handling. Requires the @MagicHash@, @UnboxedSums@ and +-- @UnboxedTuples@ language extensions. +-- See the . toWord8 :: Word32 -> Maybe Word8 toWord8 = Bits.toIntegralSized 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 @@ -1,5 +1,6 @@ module Unwitch.Convert.Word64 - ( toWord8 + ( -- * Conversions + toWord8 , toWord16 , toWord32 , toWord @@ -12,6 +13,8 @@ , toInteger , toFloat , toDouble + -- * Unboxed conversions + -- $unboxed , toWord8# , toWord16# , toWord32# @@ -46,6 +49,12 @@ (>=#)) import GHC.Int (Int8(..), Int16(..), Int32(..), Int64(..)) import GHC.Word (Word8(..), Word16(..), Word32(..), Word64(..)) + +-- $unboxed +-- These use GHC unboxed types and unboxed sums for zero-allocation +-- failure handling. Requires the @MagicHash@, @UnboxedSums@ and +-- @UnboxedTuples@ language extensions. +-- See the . toWord8 :: Word64 -> Maybe Word8 toWord8 = Bits.toIntegralSized diff --git a/src/Unwitch/Convert/Word8.hs b/src/Unwitch/Convert/Word8.hs --- a/src/Unwitch/Convert/Word8.hs +++ b/src/Unwitch/Convert/Word8.hs @@ -1,5 +1,6 @@ module Unwitch.Convert.Word8 - ( toWord16 + ( -- * Conversions + toWord16 , toWord32 , toWord64 , toWord @@ -12,6 +13,8 @@ , toInteger , toFloat , toDouble + -- * Unboxed conversions + -- $unboxed , toInt8# ) where @@ -25,6 +28,12 @@ (==#)) import GHC.Int (Int8(..)) import GHC.Word (Word8(..)) + +-- $unboxed +-- These use GHC unboxed types and unboxed sums for zero-allocation +-- failure handling. Requires the @MagicHash@, @UnboxedSums@ and +-- @UnboxedTuples@ language extensions. +-- See the . toWord16 :: Word8 -> Word16 toWord16 = fromIntegral 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.0 +version: 2.0.1 homepage: https://github.com/jappeace/unwitch#readme synopsis: converts between primitives description: