diff --git a/Data/IntCast.hs b/Data/IntCast.hs --- a/Data/IntCast.hs +++ b/Data/IntCast.hs @@ -1,4 +1,8 @@ -{-# LANGUAGE CPP, DataKinds, TypeFamilies, TypeOperators, UndecidableInstances #-} +{-# LANGUAGE CPP #-} +{-# LANGUAGE DataKinds #-} +{-# LANGUAGE TypeFamilies #-} +{-# LANGUAGE TypeOperators #-} +{-# LANGUAGE UndecidableInstances #-} #if __GLASGOW_HASKELL__ < 707 #error This code requires GHC 7.7+ @@ -9,7 +13,7 @@ -- | -- Module: Data.IntCast --- Copyright: © 2014 Herbert Valerio Riedel +-- Copyright: © 2014-2018 Herbert Valerio Riedel -- License: BSD-style (see the LICENSE file) -- -- Maintainer: Herbert Valerio Riedel @@ -21,6 +25,26 @@ module Data.IntCast ( -- * Conversion functions -- ** statically checked + -- + -- | In the table below each cell denotes which of the three + -- 'intCast', 'intCastIso' and 'intCastEq' conversion operations + -- are allowed (i.e. by the type-checker). The rows represent + -- the domain @a@ while the columns represent the codomain @b@ + -- of the @a->b@-typed conversion functions. + -- + -- +-----------+-----------------+--------------+----------------------------------------+------------------------------------------+ + -- | | 'Natural' | 'Word32' | 'Word64' | 'Int' | + -- +-----------+-----------------+--------------+----------------------------------------+------------------------------------------+ + -- | 'Word' | 'intCast' | | 'intCast' & 'intCastEq' & 'intCastIso' | 'intCastIso' | + -- +-----------+-----------------+--------------+----------------------------------------+------------------------------------------+ + -- | 'Word16' | 'intCast' | 'intCast' | 'intCast' | 'intCast' | + -- +-----------+-----------------+--------------+----------------------------------------+------------------------------------------+ + -- | 'Int64' | | | 'intCastIso' | 'intCast' & 'intCastEq' & 'intCastIso' | + -- +-----------+-----------------+--------------+----------------------------------------+------------------------------------------+ + -- | 'Int8' | | | | 'intCast' | + -- +-----------+-----------------+--------------+----------------------------------------+------------------------------------------+ + -- + -- __Note:__ The table above assumes a 64-bit platform (i.e. where @finiteBitSize (0 :: Word) == 64@). intCast , intCastIso , intCastEq @@ -50,15 +74,14 @@ ) where -- Haskell 2010+ -import Data.Int -import Data.Word -import Foreign.C.Types +import Data.Bits +import Data.Int +import Data.Word +import Foreign.C.Types -- non-Haskell 2010 -import GHC.TypeLits -import Data.Bits -import Data.Type.Equality -import Numeric.Natural (Natural) +import GHC.TypeLits +import Numeric.Natural (Natural) -- | (Kind) Meta-information about integral types. -- @@ -67,13 +90,13 @@ -- is conveyed by the 'Bits' class' 'isSigned' and 'bitSizeMaybe' -- methods. data IntBaseTypeK - -- | fixed-width /n/-bit integers with value range [-2ⁿ⁻¹, 2ⁿ⁻¹-1]. + -- | fixed-width \(n\)-bit integers with value range \( \left[ -2^{n-1}, 2^{n-1}-1 \right] \). = FixedIntTag Nat - -- | fixed-width /n/-bit integers with value range [0, 2ⁿ-1]. + -- | fixed-width \(n\)-bit integers with value range \( \left[ 0, 2^{n} \right] \). | FixedWordTag Nat - -- | integers with value range ]-∞,+∞[. + -- | integers with value range \( \left] -\infty, +\infty \right[ \). | BigIntTag - -- | naturals with value range [0,+∞[. + -- | naturals with value range \( \left[ 0, +\infty \right[ \). | BigWordTag -- | The (open) type family 'IntBaseType' encodes type-level @@ -91,13 +114,13 @@ -- data Nibble = … -- -- /-- declare meta-information/ --- type instance 'IntBaseType' MyWord7 = 'FixedIntTag' 4 +-- type instance 'IntBaseType' Nibble = 'FixedWordTag' 4 -- -- /-- user-implemented signed 7-bit integer/ -- data MyInt7 = … -- -- /-- declare meta-information/ --- type instance 'IntBaseType' MyWord7 = 'FixedIntTag' 7 +-- type instance 'IntBaseType' MyInt7 = 'FixedIntTag' 7 -- @ -- -- The type-level predicate 'IsIntSubType' provides a partial @@ -144,7 +167,9 @@ type instance IntBaseType CULong = IntBaseType HTYPE_UNSIGNED_LONG type instance IntBaseType CUShort = IntBaseType HTYPE_UNSIGNED_SHORT --- Internal class providing the partial order of (improper) subtype-relations +-- | Closed type family providing the partial order of (improper) subtype-relations +-- +-- 'IsIntSubType' provides a more convenient entry point. type family IsIntBaseSubType a b :: Bool where -- this relation is reflexive IsIntBaseSubType a a = 'True @@ -166,7 +191,13 @@ type IsIntSubType a b = IsIntBaseSubType (IntBaseType a) (IntBaseType b) --- Same bit-size predicate +-- | Closed type family representing an equality-relation on bit-width +-- +-- This is a superset of the 'IsIntBaseTypeEq' relation, as it ignores +-- the signedness of fixed-size integers (i.e. 'Int32' is considered +-- equal to 'Word32'). +-- +-- 'IsIntTypeIso' provides a more convenient entry point. type family IsIntBaseTypeIso a b :: Bool where IsIntBaseTypeIso a a = 'True IsIntBaseTypeIso ('FixedIntTag n) ('FixedWordTag n) = 'True @@ -175,19 +206,27 @@ type IsIntTypeIso a b = IsIntBaseTypeIso (IntBaseType a) (IntBaseType b) +-- | Closed type family representing an equality-relation on the integer base-type. +-- +-- 'IsIntBaseTypeEq' provides a more convenient entry point. type family IsIntBaseTypeEq (a :: IntBaseTypeK) (b :: IntBaseTypeK) :: Bool where IsIntBaseTypeEq a a = 'True IsIntBaseTypeEq a b = 'False type IsIntTypeEq a b = IsIntBaseTypeEq (IntBaseType a) (IntBaseType b) -type instance a == b = IsIntBaseTypeEq a b +-- Starting w/ GHC 8.4, (==) became a closed type-family, so the +-- following convenience instance isn't possibly anymore +-- +-- type instance a == b = IsIntBaseTypeEq a b +-- +-- https://github.com/haskell-hvr/int-cast/issues/3 -- | Statically checked integer conversion which satisfies the property -- -- * @'toInteger' ≡ 'toInteger' . intCast@ -- --- Note: This is just a type-restricted alias of 'fromIntegral' and +-- __Note:__ This is just a type-restricted alias of 'fromIntegral' and -- should therefore lead to the same compiled code as if -- 'fromIntegral' had been used instead of 'intCast'. intCast :: (Integral a, Integral b, IsIntSubType a b ~ 'True) => a -> b @@ -200,14 +239,22 @@ -- -- * @'toInteger' ('intCastIso' a) == 'toInteger' b (__if__ 'toInteger' a == 'toInteger' b)@ -- --- Note: This is just a type-restricted alias of 'fromIntegral' and +-- __Note:__ This is just a type-restricted alias of 'fromIntegral' and -- should therefore lead to the same compiled code as if --- 'fromIntegral' had been used instead of 'intCast'. +-- 'fromIntegral' had been used instead of 'intCastIso'. intCastIso :: (Integral a, Integral b, IsIntTypeIso a b ~ 'True) => a -> b intCastIso = fromIntegral {-# INLINE intCastIso #-} -- | Version of 'intCast' restricted to casts between types with same value domain. +-- +-- 'intCastEq' is the most constrained of the three conversions: The +-- existence of a 'intCastEq' conversion implies the existence of the +-- other two, i.e. 'intCastIso' and 'intCast'. +-- +-- __Note:__ This is just a type-restricted alias of 'fromIntegral' and +-- should therefore lead to the same compiled code as if +-- 'fromIntegral' had been used instead of 'intCastIso'. intCastEq :: (Integral a, Integral b, IsIntTypeEq a b ~ 'True) => a -> b intCastEq = fromIntegral {-# INLINE intCastEq #-} @@ -271,6 +318,10 @@ -- > ; True -> Just (W16# (narrow16Word# (int2Word# b1))) -- > } -- > } +-- +-- __Note:__ Starting with @base-4.8@, this function has been added to "Data.Bits" +-- under the name 'Data.Bits.toIntegralSized'. +-- intCastMaybe :: (Integral a, Integral b, Bits a, Bits b) => a -> Maybe b -- the code below relies on GHC optimizing away statically decidable branches intCastMaybe x diff --git a/changelog.md b/changelog.md --- a/changelog.md +++ b/changelog.md @@ -1,3 +1,13 @@ +# 0.2.0.0 + + - Add support for GHC 8.4 + + - Removed `type instance a == b = IsIntBaseTypeEq a b` as GHC 8.4 made `(==)` a closed type-family ([#3](https://github.com/hvr/int-cast/issues/3)) + + - Improved Haddock documentation + +---- + ## 0.1.2.0 - Add support for GHC 7.10 @@ -12,6 +22,8 @@ * Add `Data.Type.Equality.(==)` instance for `IntBaseTypeK` -## 0.1.0.0 +# 0.1.0.0 * initial release + +---- diff --git a/int-cast.cabal b/int-cast.cabal --- a/int-cast.cabal +++ b/int-cast.cabal @@ -1,5 +1,7 @@ +cabal-version: 1.12 name: int-cast -version: 0.1.2.0 +version: 0.2.0.0 + synopsis: Checked conversions between integral types homepage: https://github.com/hvr/int-cast bug-reports: https://github.com/hvr/int-cast/issues @@ -9,9 +11,8 @@ maintainer: hvr@gnu.org category: Data build-type: Simple -cabal-version: >=1.10 description: - Provides statically or dynamically checked conversions between integral types. + Provides statically or dynamically checked conversions between integral types. See documentation in "Data.IntCast" for more details. extra-source-files: changelog.md @@ -20,25 +21,32 @@ location: https://github.com/hvr/int-cast.git library + exposed-modules: Data.IntCast + default-language: Haskell2010 - other-extensions: - CPP - DataKinds - TypeFamilies - TypeOperators - UndecidableInstances - build-depends: base >=4.7 && <4.9 + other-extensions: CPP + DataKinds + TypeFamilies + TypeOperators + UndecidableInstances + + build-depends: base >=4.7 && <4.12 if !impl(ghc>=7.10) - build-depends: nats >=0.1 && <1.1 + build-depends: nats >=0.1 && <1.1 - exposed-modules: Data.IntCast + ghc-options: -Wall test-suite int-cast-test default-language: Haskell2010 type: exitcode-stdio-1.0 - hs-source-dirs: test . + hs-source-dirs: test main-is: Suite.hs ghc-options: -Wall - build-depends: int-cast, base, QuickCheck ==2.7.*, test-framework ==0.8.*, test-framework-quickcheck2 ==0.3.* + build-depends: int-cast + , base + , QuickCheck ==2.11.* + , test-framework ==0.8.* + , test-framework-quickcheck2 ==0.3.* + if !impl(ghc>=7.10) build-depends: nats