diff options
Diffstat (limited to 'libraries/base')
| -rw-r--r-- | libraries/base/Data/Int.hs | 40 | ||||
| -rw-r--r-- | libraries/base/Data/Word.hs | 48 | ||||
| -rw-r--r-- | libraries/base/Debug/Trace.hs | 11 | ||||
| -rw-r--r-- | libraries/base/GHC/Base.lhs | 4 | ||||
| -rw-r--r-- | libraries/base/GHC/IOBase.lhs | 35 | ||||
| -rw-r--r-- | libraries/base/GHC/Int.hs | 6 | ||||
| -rw-r--r-- | libraries/base/GHC/Word.hs | 9 | ||||
| -rw-r--r-- | libraries/base/System/IO/Unsafe.hs | 3 |
8 files changed, 136 insertions, 20 deletions
diff --git a/libraries/base/Data/Int.hs b/libraries/base/Data/Int.hs index 182152c1e5..7b57ae4774 100644 --- a/libraries/base/Data/Int.hs +++ b/libraries/base/Data/Int.hs @@ -9,19 +9,45 @@ -- 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. +-} diff --git a/libraries/base/Data/Word.hs b/libraries/base/Data/Word.hs index 980de4d0a5..630855628b 100644 --- a/libraries/base/Data/Word.hs +++ b/libraries/base/Data/Word.hs @@ -1,7 +1,7 @@ {-# OPTIONS -fno-implicit-prelude #-} ----------------------------------------------------------------------------- -- | --- Module : +-- Module : Data.Word -- Copyright : (c) The University of Glasgow 2001 -- License : BSD-style (see the file libraries/base/LICENSE) -- @@ -9,20 +9,50 @@ -- 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. +-} diff --git a/libraries/base/Debug/Trace.hs b/libraries/base/Debug/Trace.hs index 6f1ce82676..ecaf39e2e5 100644 --- a/libraries/base/Debug/Trace.hs +++ b/libraries/base/Debug/Trace.hs @@ -8,11 +8,12 @@ -- Stability : provisional -- Portability : portable -- --- The trace function. +-- The 'trace' function. -- ----------------------------------------------------------------------------- module Debug.Trace ( + -- * Tracing trace -- :: String -> a -> a ) where @@ -27,6 +28,14 @@ import GHC.Handle #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 diff --git a/libraries/base/GHC/Base.lhs b/libraries/base/GHC/Base.lhs index ffc3b065a7..45138d2c19 100644 --- a/libraries/base/GHC/Base.lhs +++ b/libraries/base/GHC/Base.lhs @@ -509,6 +509,10 @@ eqString cs1 cs2 = False \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# diff --git a/libraries/base/GHC/IOBase.lhs b/libraries/base/GHC/IOBase.lhs index e82b2bc3fc..608d2b11cb 100644 --- a/libraries/base/GHC/IOBase.lhs +++ b/libraries/base/GHC/IOBase.lhs @@ -107,10 +107,45 @@ ioToST (IO m) = (ST m) -- --------------------------------------------------------------------------- -- 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) diff --git a/libraries/base/GHC/Int.hs b/libraries/base/GHC/Int.hs index cd1259475a..309542a61c 100644 --- a/libraries/base/GHC/Int.hs +++ b/libraries/base/GHC/Int.hs @@ -38,6 +38,7 @@ import GHC.Show -- 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 @@ -146,6 +147,7 @@ instance Bits Int8 where -- 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 @@ -255,6 +257,7 @@ instance Bits Int16 where #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# @@ -406,6 +409,7 @@ foreign import "stg_shiftRL32" unsafe shiftRL32# :: Word32# -> Int# -> W #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) @@ -523,6 +527,7 @@ instance Ix Int32 where #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# @@ -692,6 +697,7 @@ foreign import ccall unsafe "stg_integerToInt64" integerToInt64# :: Int# -> By -- 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) diff --git a/libraries/base/GHC/Word.hs b/libraries/base/GHC/Word.hs index 185016117a..0d0c60bce2 100644 --- a/libraries/base/GHC/Word.hs +++ b/libraries/base/GHC/Word.hs @@ -70,8 +70,7 @@ predError inst_ty = -- 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 @@ -188,6 +187,7 @@ instance Bits Word where -- 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 @@ -290,6 +290,7 @@ instance Bits Word8 where -- 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 @@ -392,6 +393,7 @@ instance Bits Word16 where #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# @@ -514,6 +516,7 @@ foreign import unsafe "stg_shiftRL32" shiftRL32# :: Word32# -> Int# -> W #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#)) @@ -650,6 +653,7 @@ instance Read Word32 where #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# @@ -787,6 +791,7 @@ foreign import ccall unsafe "stg_integerToWord64" integerToWord64# :: Int# -> By -- 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#) diff --git a/libraries/base/System/IO/Unsafe.hs b/libraries/base/System/IO/Unsafe.hs index 3e2ade7649..8fafec45e7 100644 --- a/libraries/base/System/IO/Unsafe.hs +++ b/libraries/base/System/IO/Unsafe.hs @@ -8,11 +8,12 @@ -- 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 |