-- Stability : experimental
-- Portability : portable
--
--- Sized Integer types.
+-- Signed integer types
--
-----------------------------------------------------------------------------
module Data.Int
- ( Int8
- , Int16
- , Int32
- , Int64
- -- instances: Eq, Ord, Num, Bounded, Real, Integral, Ix, Enum, Read,
- -- Show, Bits, CCallable, CReturnable (last two are GHC specific.)
+ (
+ -- * Signed integer types
+ Int,
+ Int8, Int16, Int32, Int64,
+
+ -- * Notes
+
+ -- $notes
) where
#ifdef __GLASGOW_HASKELL__
import GHC.Int
#endif
+
+{- $notes
+
+* All arithmetic is performed modulo 2^n, where @n@ is the number of
+ bits in the type.
+
+* For coercing between any two integer types, use 'fromIntegral',
+ which is specialized for all the common cases so should be fast
+ enough. Coercing word types (see "Data.Word") to and from integer
+ types preserves representation, not sign.
+
+* The rules that hold for 'Enum' instances over a
+ bounded type such as 'Int' (see the section of the
+ Haskell report dealing with arithmetic sequences) also hold for the
+ 'Enum' instances over the various
+ 'Int' types defined here.
+
+* Right and left shifts by amounts greater than or equal to the width
+ of the type result in either zero or -1, depending on the sign of
+ the value being shifted. This is contrary to the behaviour in C,
+ which is undefined; a common interpretation is to truncate the shift
+ count to the width of the type, for example @1 \<\< 32
+ == 1@ in some C implementations.
+-}
{-# OPTIONS -fno-implicit-prelude #-}
-----------------------------------------------------------------------------
-- |
--- Module :
+-- Module : Data.Word
-- Copyright : (c) The University of Glasgow 2001
-- License : BSD-style (see the file libraries/base/LICENSE)
--
-- Stability : experimental
-- Portability : portable
--
--- Sized unsigned integer types.
+-- Unsigned integer types.
--
-----------------------------------------------------------------------------
module Data.Word
- ( Word
- , Word8
- , Word16
- , Word32
- , Word64
- -- instances: Eq, Ord, Num, Bounded, Real, Integral, Ix, Enum, Read,
- -- Show, Bits, CCallable, CReturnable (last two are GHC specific.)
+ (
+ -- * Unsigned integral types
+
+ Word,
+ Word8, Word16, Word32, Word64,
+
+ -- * Notes
+
+ -- $notes
) where
#ifdef __GLASGOW_HASKELL__
import GHC.Word
#endif
+
+{- $notes
+
+* All arithmetic is performed modulo 2^n, where n is the number of
+ bits in the type. One non-obvious consequence of this is that 'negate'
+ should /not/ raise an error on negative arguments.
+
+* For coercing between any two integer types, use
+ 'fromIntegral', which is specialized for all the
+ common cases so should be fast enough. Coercing word types to and
+ from integer types preserves representation, not sign.
+
+* It would be very natural to add a type 'Natural' providing an unbounded
+ size unsigned integer, just as 'Integer' provides unbounded
+ size signed integers. We do not do that yet since there is no demand
+ for it.
+
+* The rules that hold for 'Enum' instances over a bounded type
+ such as 'Int' (see the section of the Haskell report dealing
+ with arithmetic sequences) also hold for the 'Enum' instances
+ over the various 'Word' types defined here.
+
+* Right and left shifts by amounts greater than or equal to the width
+ of the type result in a zero result. This is contrary to the
+ behaviour in C, which is undefined; a common interpretation is to
+ truncate the shift count to the width of the type, for example @1 \<\<
+ 32 == 1@ in some C implementations.
+-}
-- Stability : provisional
-- Portability : portable
--
--- The trace function.
+-- The 'trace' function.
--
-----------------------------------------------------------------------------
module Debug.Trace (
+ -- * Tracing
trace -- :: String -> a -> a
) where
#ifdef __GLASGOW_HASKELL__
{-# NOINLINE trace #-}
+{-|
+When called, 'trace' prints the string in its first argument to
+standard error, before returning the second argument as its result.
+The 'trace' function is not referentially transparent, and should only
+be used for debugging, or for monitoring execution. Some
+implementations of 'trace' may decorate the string that\'s output to
+indicate that you\'re tracing.
+-}
trace :: String -> a -> a
trace string expr = unsafePerformIO $ do
hPutStr stderr string
\begin{code}
data Int = I# Int#
+-- ^A fixed-precision integer type with at least the range @[-2^29
+-- .. 2^29-1]@. The exact range for a given implementation can be
+-- determined by using 'minBound' and 'maxBound' from the 'Bounded'
+-- class.
zeroInt, oneInt, twoInt, maxInt, minInt :: Int
zeroInt = I# 0#
-- ---------------------------------------------------------------------------
-- Unsafe IO operations
+{-|
+This is the "back door" into the 'IO' monad, allowing
+'IO' computation to be performed at any time. For
+this to be safe, the 'IO' computation should be
+free of side effects and independent of its environment.
+
+If the I\/O computation wrapped in 'unsafePerformIO'
+performs side effects, then the relative order in which those side
+effects take place (relative to the main I\/O trunk, or other calls to
+'unsafePerformIO') is indeterminate.
+
+However, it is less well known that
+'unsafePerformIO' is not type safe. For example:
+
+> test :: IORef [a]
+> test = unsafePerformIO $ newIORef []
+>
+> main = do
+> writeIORef test [42]
+> bang \<- readIORef test
+> print (bang :: [Char])
+
+This program will core dump. This problem with polymorphic references
+is well known in the ML community, and does not arise with normal
+monadic use of references. There is no easy way to make it impossible
+once you use 'unsafePerformIO'. Indeed, it is
+possible to write @coerce :: a -> b@ with the
+help of 'unsafePerformIO'. So be careful!
+-}
{-# NOINLINE unsafePerformIO #-}
unsafePerformIO :: IO a -> a
unsafePerformIO (IO m) = case m realWorld# of (# _, r #) -> r
+{-|
+'unsafeInterleaveIO' allows 'IO' computation to be deferred lazily.
+When passed a value of type @IO a@, the 'IO' will only be performed
+when the value of the @a@ is demanded. This is used to implement lazy
+file reading, see 'IO.hGetContents'.
+-}
{-# NOINLINE unsafeInterleaveIO #-}
unsafeInterleaveIO :: IO a -> IO a
unsafeInterleaveIO (IO m)
-- and must ensure that it holds only values from its logical range.
data Int8 = I8# Int# deriving (Eq, Ord)
+-- ^ 8-bit signed integer type
instance CCallable Int8
instance CReturnable Int8
-- and must ensure that it holds only values from its logical range.
data Int16 = I16# Int# deriving (Eq, Ord)
+-- ^ 16-bit signed integer type
instance CCallable Int16
instance CReturnable Int16
#if WORD_SIZE_IN_BITS < 32
data Int32 = I32# Int32#
+-- ^ 32-bit signed integer type
instance Eq Int32 where
(I32# x#) == (I32# y#) = x# `eqInt32#` y#
#endif
data Int32 = I32# Int# deriving (Eq, Ord)
+-- ^ 32-bit signed integer type
instance Show Int32 where
showsPrec p x = showsPrec p (fromIntegral x :: Int)
#if WORD_SIZE_IN_BITS < 64
data Int64 = I64# Int64#
+-- ^ 64-bit signed integer type
instance Eq Int64 where
(I64# x#) == (I64# y#) = x# `eqInt64#` y#
-- from its logical range.
data Int64 = I64# Int# deriving (Eq, Ord)
+-- ^ 64-bit signed integer type
instance Show Int64 where
showsPrec p x = showsPrec p (fromIntegral x :: Int)
-- type Word
------------------------------------------------------------------------
--- A Word is an unsigned integral type, with the same size as Int.
-
+-- |A 'Word' is an unsigned integral type, with the same size as 'Int'.
data Word = W# Word# deriving (Eq, Ord)
instance CCallable Word
-- and must ensure that it holds only values from its logical range.
data Word8 = W8# Word# deriving (Eq, Ord)
+-- ^ 8-bit unsigned integer type
instance CCallable Word8
instance CReturnable Word8
-- and must ensure that it holds only values from its logical range.
data Word16 = W16# Word# deriving (Eq, Ord)
+-- ^ 16-bit unsigned integer type
instance CCallable Word16
instance CReturnable Word16
#if WORD_SIZE_IN_BITS < 32
data Word32 = W32# Word32#
+-- ^ 32-bit unsigned integer type
instance Eq Word32 where
(W32# x#) == (W32# y#) = x# `eqWord32#` y#
#endif
data Word32 = W32# Word# deriving (Eq, Ord)
+-- ^ 32-bit unsigned integer type
instance Num Word32 where
(W32# x#) + (W32# y#) = W32# (narrow32Word# (x# `plusWord#` y#))
#if WORD_SIZE_IN_BITS < 64
data Word64 = W64# Word64#
+-- ^ 64-bit unsigned integer type
instance Eq Word64 where
(W64# x#) == (W64# y#) = x# `eqWord64#` y#
-- from its logical range.
data Word64 = W64# Word# deriving (Eq, Ord)
+-- ^ 64-bit unsigned integer type
instance Num Word64 where
(W64# x#) + (W64# y#) = W64# (x# `plusWord#` y#)
-- Stability : provisional
-- Portability : portable
--
--- "Unsafe" IO operations.
+-- \"Unsafe\" IO operations.
--
-----------------------------------------------------------------------------
module System.IO.Unsafe (
+ -- * Unsafe 'IO' operations
unsafePerformIO, -- :: IO a -> a
unsafeInterleaveIO, -- :: IO a -> IO a
) where
projects / ghc-base.git / commitdiff