Statically checked integer conversion which satisfies the property

• toInteger ≡ toInteger . 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 intCast.

Statically checked integer conversion which satisfies the properties

• ∀β . intCastIso (intCastIso a ∷ β) == a

• toInteger (intCastIso a) == toInteger b     (if toInteger a == toInteger b)

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.

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.

Run-time-checked integer conversion

This is an optimized version of the following generic code below

intCastMaybeRef :: (Integral a, Integral b) => a -> Maybe b
intCastMaybeRef x
  | toInteger x == toInteger y = Just y
  | otherwise                  = Nothing
  where
    y = fromIntegral x

The code above is rather inefficient as it needs to go via the Integer type. The function intCastMaybe, however, is marked INLINEABLE and if both integral types are statically known, GHC will be able optimize the code signficantly (for -O1 and better).

For instance (as of GHC 7.8.1) the following definitions

w16_to_i32 = intCastMaybe :: Word16 -> Maybe Int32

i16_to_w16 = intCastMaybe :: Int16 -> Maybe Word16

are translated into the following (simplified) GHC Core language

w16_to_i32 = \x -> Just (case x of _ { W16# x# -> I32# (word2Int# x#) })

i16_to_w16 = \x -> case eta of _
  { I16# b1 -> case tagToEnum# (<=# 0 b1) of _
      { False -> Nothing
      ; True -> Just (W16# (narrow16Word# (int2Word# b1)))
      }
  }

Note: Starting with base-4.8, this function has been added to Data.Bits under the name toIntegralSized.

The (open) type family IntBaseType encodes type-level information about the value range of an integral type.

This module also provides type family instances for the standard Haskell 2010 integral types (including Foreign.C.Types) as well as the Natural type.

Here's a simple example for registering a custom type with the Data.IntCast facilities:

-- user-implemented unsigned 4-bit integer
data Nibble = …

-- declare meta-information
type instance IntBaseType Nibble = FixedWordTag 4

-- user-implemented signed 7-bit integer
data MyInt7 = …

-- declare meta-information
type instance IntBaseType MyInt7 = FixedIntTag 7

The type-level predicate IsIntSubType provides a partial ordering based on the types above. See also intCast.

(Kind) Meta-information about integral types.

If also a Bits instance is defined, the type-level information provided by IntBaseType ought to match the meta-information that is conveyed by the Bits class' isSigned and bitSizeMaybe methods.

Closed type family providing the partial order of (improper) subtype-relations

IsIntSubType provides a more convenient entry point.

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.

Closed type family representing an equality-relation on the integer base-type.

IsIntBaseTypeEq provides a more convenient entry point.