From 96327b0696bc28551fbdb303506c52b9ee70c95c Mon Sep 17 00:00:00 2001 From: ross Date: Wed, 28 Jul 2004 10:32:12 +0000 Subject: [PATCH] [project @ 2004-07-28 10:32:11 by ross] haddock food --- Data/Ratio.hs | 5 +++-- Foreign/C/Types.hs | 63 ++++++++++++++++++++++++++++------------------------ GHC/Enum.lhs | 4 +++- GHC/Float.lhs | 54 ++++++++++++++++++++++++++++++++++++++++++-- GHC/Num.lhs | 24 +++++++++++++++++++- GHC/Real.lhs | 63 ++++++++++++++++++++++++++++++++++++++++++++++++---- GHC/Stable.lhs | 6 ++--- 7 files changed, 177 insertions(+), 42 deletions(-) diff --git a/Data/Ratio.hs b/Data/Ratio.hs index f819343..22f3abe 100644 --- a/Data/Ratio.hs +++ b/Data/Ratio.hs @@ -52,13 +52,14 @@ import Ratio (Ratio(..), (%), numerator, denominator, approxRational) -- | 'approxRational', applied to two real fractional numbers @x@ and @epsilon@, -- returns the simplest rational number within @epsilon@ of @x@. --- A rational number @y@ is said to be simpler than another @y'@ if +-- A rational number @y@ is said to be /simpler/ than another @y'@ if -- -- * @'abs' ('numerator' y) <= 'abs' ('numerator' y')@, and -- -- * @'denominator' y <= 'denominator' y'@. -- --- Any real interval contains a unique simplest rational. +-- Any real interval contains a unique simplest rational; +-- in particular, note that @0\/1@ is the simplest rational of all. -- Implementation details: Here, for simplicity, we assume a closed rational -- interval. If such an interval includes at least one whole number, then diff --git a/Foreign/C/Types.hs b/Foreign/C/Types.hs index c4be5a7..f34b445 100644 --- a/Foreign/C/Types.hs +++ b/Foreign/C/Types.hs @@ -19,10 +19,12 @@ module Foreign.C.Types -- $ctypes -- ** Integral types - -- | These types are are represented as @newtype@s of types in - -- "Data.Int" and "Data.Word", and are instances of - -- 'Eq', 'Ord', 'Num', 'Read', 'Show', 'Enum', 'Typeable', - -- 'Storable', 'Bounded', 'Real', 'Integral' and 'Bits'. + -- | These types are are represented as @newtype@s of + -- types in "Data.Int" and "Data.Word", and are instances of + -- 'Prelude.Eq', 'Prelude.Ord', 'Prelude.Num', 'Prelude.Read', + -- 'Prelude.Show', 'Prelude.Enum', 'Typeable', 'Storable', + -- 'Prelude.Bounded', 'Prelude.Real', 'Prelude.Integral' and + -- 'Bits'. CChar, CSChar, CUChar , CShort, CUShort, CInt, CUInt , CLong, CULong @@ -32,16 +34,17 @@ module Foreign.C.Types -- ** Numeric types -- | These types are are represented as @newtype@s of basic -- foreign types, and are instances of - -- 'Eq', 'Ord', 'Num', 'Read', 'Show', 'Enum', 'Typeable' and - -- 'Storable'. + -- 'Prelude.Eq', 'Prelude.Ord', 'Prelude.Num', 'Prelude.Read', + -- 'Prelude.Show', 'Prelude.Enum', 'Typeable' and 'Storable'. , CClock, CTime -- ** Floating types - -- | These types are are represented as @newtype@s of 'Float' - -- and 'Double', and are instances of - -- 'Eq', 'Ord', 'Num', 'Read', 'Show', 'Enum', 'Typeable', - -- 'Storable', 'Real', 'Fractional', 'Floating', 'RealFrac' - -- and 'RealFloat'. + -- | These types are are represented as @newtype@s of + -- 'Prelude.Float' and 'Prelude.Double', and are instances of + -- 'Prelude.Eq', 'Prelude.Ord', 'Prelude.Num', 'Prelude.Read', + -- 'Prelude.Show', 'Prelude.Enum', 'Typeable', 'Storable', + -- 'Prelude.Real', 'Prelude.Fractional', 'Prelude.Floating', + -- 'Prelude.RealFrac' and 'Prelude.RealFloat'. , CFloat, CDouble, CLDouble #else -- Exported non-abstractly in nhc98 to fix an interface file problem. @@ -199,32 +202,34 @@ is not required to represent those types exactly as C does, but the following guarantees are provided concerning a Haskell type @CT@ representing a C type @t@: -* If a C function prototype has @t@ as an argument or result type, - the use of @CT@ in the corresponding position in a foreign declaration - permits the Haskell program to access the full range of values encoded by - the C type; and conversely, any Haskell value for @CT@ has a valid +* If a C function prototype has @t@ as an argument or result type, the + use of @CT@ in the corresponding position in a foreign declaration + permits the Haskell program to access the full range of values encoded + by the C type; and conversely, any Haskell value for @CT@ has a valid representation in C. -* @'sizeOf' ('undefined' :: CT)@ will yield the same value as +* @'sizeOf' ('Prelude.undefined' :: CT)@ will yield the same value as @sizeof (t)@ in C. -* @'alignment' ('undefined' :: CT)@ matches the alignment constraint - enforced by the C implementation for @t@. +* @'alignment' ('Prelude.undefined' :: CT)@ matches the alignment + constraint enforced by the C implementation for @t@. -* The members 'peek' and 'poke' of the 'Storable' class map all values of - @CT@ to the corresponding value of @t@ and vice versa. +* The members 'peek' and 'poke' of the 'Storable' class map all values + of @CT@ to the corresponding value of @t@ and vice versa. -* When an instance of 'Bounded' is defined for @CT@, the values of - 'minBound' and 'maxBound' coincide with @t_MIN@ and @t_MAX@ in C. +* When an instance of 'Prelude.Bounded' is defined for @CT@, the values + of 'Prelude.minBound' and 'Prelude.maxBound' coincide with @t_MIN@ + and @t_MAX@ in C. -* When an instance of 'Eq' or 'Ord' is defined for @CT@, the predicates - defined by the type class implement the same relation as the - corresponding predicate in C on @t@. +* When an instance of 'Prelude.Eq' or 'Prelude.Ord' is defined for @CT@, + the predicates defined by the type class implement the same relation + as the corresponding predicate in C on @t@. -* When an instance of 'Num', 'Read', 'Integral', 'Fractional', 'Floating', - 'RealFrac', or 'RealFloat' is defined for @CT@, the arithmetic - operations defined by the type class implement the same function as - the corresponding arithmetic operations (if available) in C on @t@. +* When an instance of 'Prelude.Num', 'Prelude.Read', 'Prelude.Integral', + 'Prelude.Fractional', 'Prelude.Floating', 'Prelude.RealFrac', or + 'Prelude.RealFloat' is defined for @CT@, the arithmetic operations + defined by the type class implement the same function as the + corresponding arithmetic operations (if available) in C on @t@. * When an instance of 'Bits' is defined for @CT@, the bitwise operation defined by the type class implement the same function as the diff --git a/GHC/Enum.lhs b/GHC/Enum.lhs index 0f8df4d..b0afbde 100644 --- a/GHC/Enum.lhs +++ b/GHC/Enum.lhs @@ -55,7 +55,9 @@ class Bounded a where -- arithmetic sequences. -- -- Instances of 'Enum' may be derived for any enumeration type (types --- whose constructors have no fields); see Chapter 10 of the /Haskell Report/. +-- whose constructors have no fields). The nullary constructors are +-- assumed to be numbered left-to-right by 'fromEnum' from @0@ through @n-1@. +-- See Chapter 10 of the /Haskell Report/ for more details. -- -- For any type that is an instance of class 'Bounded' as well as 'Enum', -- the following should hold: diff --git a/GHC/Float.lhs b/GHC/Float.lhs index f1779fc..41ea69a 100644 --- a/GHC/Float.lhs +++ b/GHC/Float.lhs @@ -38,6 +38,11 @@ infixr 8 ** %********************************************************* \begin{code} +-- | Trigonometric and hyperbolic functions and related functions. +-- +-- Minimal complete definition: +-- 'pi', 'exp', 'log', 'sin', 'cos', 'sinh', 'cosh' +-- 'asin', 'acos', 'atan', 'asinh', 'acosh' and 'atanh' class (Fractional a) => Floating a where pi :: a exp, log, sqrt :: a -> a @@ -53,17 +58,58 @@ class (Fractional a) => Floating a where tan x = sin x / cos x tanh x = sinh x / cosh x +-- | Efficient, machine-independent access to the components of a +-- floating-point number. +-- +-- Minimal complete definition: +-- all except 'exponent', 'significand', 'scaleFloat' and 'atan2' class (RealFrac a, Floating a) => RealFloat a where + -- | a constant function, returning the radix of the representation + -- (often @2@) floatRadix :: a -> Integer + -- | a constant function, returning the number of digits of + -- 'floatRadix' in the significand floatDigits :: a -> Int + -- | a constant function, returning the lowest and highest values + -- the exponent may assume floatRange :: a -> (Int,Int) + -- | The function 'decodeFloat' applied to a real floating-point + -- number returns the significand expressed as an 'Integer' and an + -- appropriately scaled exponent (an 'Int'). If @'decodeFloat' x@ + -- yields @(m,n)@, then @x@ is equal in value to @m*b^^n@, where @b@ + -- is the floating-point radix, and furthermore, either @m@ and @n@ + -- are both zero or else @b^(d-1) <= m < b^d@, where @d@ is the value + -- of @'floatDigits' x@. In particular, @'decodeFloat' 0 = (0,0)@. decodeFloat :: a -> (Integer,Int) + -- | 'encodeFloat' performs the inverse of 'decodeFloat' encodeFloat :: Integer -> Int -> a + -- | the second component of 'decodeFloat'. exponent :: a -> Int + -- | the first component of 'decodeFloat', scaled to lie in the open + -- interval (@-1@,@1@) significand :: a -> a + -- | multiplies a floating-point number by an integer power of the radix scaleFloat :: Int -> a -> a - isNaN, isInfinite, isDenormalized, isNegativeZero, isIEEE - :: a -> Bool + -- | 'True' if the argument is an IEEE \"not-a-number\" (NaN) value + isNaN :: a -> Bool + -- | 'True' if the argument is an IEEE infinity or negative infinity + isInfinite :: a -> Bool + -- | 'True' if the argument is too small to be represented in + -- normalized format + isDenormalized :: a -> Bool + -- | 'True' if the argument is an IEEE negative zero + isNegativeZero :: a -> Bool + -- | 'True' if the argument is an IEEE floating point number + isIEEE :: a -> Bool + -- | a version of arctangent taking two real floating-point arguments. + -- For real floating @x@ and @y@, @'atan2' y x@ computes the angle + -- (from the positive x-axis) of the vector from the origin to the + -- point @(x,y)@. @'atan2' y x@ returns a value in the range [@-pi@, + -- @pi@]. It follows the Common Lisp semantics for the origin when + -- signed zeroes are supported. @'atan2' y 1@, with @y@ in a type + -- that is 'RealFloat', should return the same value as @'atan' y@. + -- A default definition of 'atan2' is provided, but implementors + -- can provide a more accurate implementation. atan2 :: a -> a -> a @@ -99,9 +145,13 @@ class (RealFrac a, Floating a) => RealFloat a where \begin{code} -- | Single-precision floating point numbers. +-- It is desirable that this type be at least equal in range and precision +-- to the IEEE single-precision type. data Float = F# Float# -- | Double-precision floating point numbers. +-- It is desirable that this type be at least equal in range and precision +-- to the IEEE double-precision type. data Double = D# Double# \end{code} diff --git a/GHC/Num.lhs b/GHC/Num.lhs index 17d35ef..04cdd68 100644 --- a/GHC/Num.lhs +++ b/GHC/Num.lhs @@ -45,15 +45,37 @@ default () -- Double isn't available yet, %********************************************************* \begin{code} +-- | Basic numeric class. +-- +-- Minimal complete definition: all except 'negate' or @(-)@ class (Eq a, Show a) => Num a where (+), (-), (*) :: a -> a -> a + -- | Unary negation. negate :: a -> a - abs, signum :: a -> a + -- | Absolute value. + abs :: a -> a + -- | Sign of a number. + -- The functions 'abs' and 'signum' should satisfy the law: + -- + -- > abs x * signum x == x + -- + -- For real numbers, the 'signum' is either @-1@ (negative), @0@ (zero) + -- or @1@ (positive). + signum :: a -> a + -- | Conversion from an 'Integer'. + -- An integer literal represents the application of the function + -- 'fromInteger' to the appropriate value of type 'Integer', + -- so such literals have type @('Num' a) => a@. fromInteger :: Integer -> a x - y = x + negate y negate x = 0 - x +-- | the same as @'flip' ('-')@. +-- +-- Because @-@ is treated specially in the Haskell grammar, +-- @(-@ /e/@)@ is not a section, but an application of prefix negation. +-- However, @('subtract'@ /exp/@)@ is equivalent to the disallowed section. {-# INLINE subtract #-} subtract :: (Num a) => a -> a -> a subtract x y = y - x diff --git a/GHC/Real.lhs b/GHC/Real.lhs index 8986456..10feee9 100644 --- a/GHC/Real.lhs +++ b/GHC/Real.lhs @@ -105,11 +105,30 @@ denominator (_ :% y) = y \begin{code} class (Num a, Ord a) => Real a where + -- | the rational equivalent of its real argument with full precision toRational :: a -> Rational +-- | Integral numbers, supporting integer division. +-- +-- Minimal complete definition: 'quotRem' and 'toInteger' class (Real a, Enum a) => Integral a where - quot, rem, div, mod :: a -> a -> a - quotRem, divMod :: a -> a -> (a,a) + -- | integer division truncated toward zero + quot :: a -> a -> a + -- | integer remainder, satisfying + -- + -- > (x `quot` y)*y + (x `rem` y) == x + rem :: a -> a -> a + -- | integer division truncated toward negative infinity + div :: a -> a -> a + -- | integer modulus, satisfying + -- + -- > (x `div` y)*y + (x `mod` y) == x + mod :: a -> a -> a + -- | simultaneous 'quot' and 'rem' + quotRem :: a -> a -> (a,a) + -- | simultaneous 'div' and 'mod' + divMod :: a -> a -> (a,a) + -- | conversion to 'Integer' toInteger :: a -> Integer n `quot` d = q where (q,_) = quotRem n d @@ -119,18 +138,46 @@ class (Real a, Enum a) => Integral a where divMod n d = if signum r == negate (signum d) then (q-1, r+d) else qr where qr@(q,r) = quotRem n d +-- | Fractional numbers, supporting real division. +-- +-- Minimal complete definition: 'fromRational' and ('recip' or @('/')@) class (Num a) => Fractional a where + -- | fractional division (/) :: a -> a -> a + -- | reciprocal fraction recip :: a -> a + -- | Conversion from a 'Rational' (that is @'Ratio' 'Integer'@). + -- A floating literal stands for an application of 'fromRational' + -- to a value of type 'Rational', so such literals have type + -- @('Fractional' a) => a@. fromRational :: Rational -> a recip x = 1 / x x / y = x * recip y +-- | Extracting components of fractions. +-- +-- Minimal complete definition: 'properFraction' class (Real a, Fractional a) => RealFrac a where + -- | The function 'properFraction' takes a real fractional number @x@ + -- and returns a pair @(n,f)@ such that @x = n+f@, and: + -- + -- * @n@ is an integral number with the same sign as @x@; and + -- + -- * @f@ is a fraction with the same type and sign as @x@, + -- and with absolute value less than @1@. + -- + -- The default definitions of the 'ceiling', 'floor', 'truncate' + -- and 'round' functions are in terms of 'properFraction'. properFraction :: (Integral b) => a -> (b,a) - truncate, round :: (Integral b) => a -> b - ceiling, floor :: (Integral b) => a -> b + -- | @'truncate' x@ returns the integer nearest @x@ between zero and @x@ + truncate :: (Integral b) => a -> b + -- | @'round' x@ returns the nearest integer to @x@ + round :: (Integral b) => a -> b + -- | @'ceiling' x@ returns the least integer not less than @x@ + ceiling :: (Integral b) => a -> b + -- | @'floor' x@ returns the greatest integer not greater than @x@ + floor :: (Integral b) => a -> b truncate x = m where (m,_) = properFraction x @@ -299,6 +346,7 @@ instance (Integral a) => Enum (Ratio a) where %********************************************************* \begin{code} +-- | general coercion from integral types fromIntegral :: (Integral a, Num b) => a -> b fromIntegral = fromInteger . toInteger @@ -306,6 +354,7 @@ fromIntegral = fromInteger . toInteger "fromIntegral/Int->Int" fromIntegral = id :: Int -> Int #-} +-- | general coercion to fractional types realToFrac :: (Real a, Fractional b) => a -> b realToFrac = fromRational . toRational @@ -336,6 +385,7 @@ even n = n `rem` 2 == 0 odd = not . even ------------------------------------------------------- +-- | raise a number to a non-negative integral power {-# SPECIALISE (^) :: Integer -> Integer -> Integer, Integer -> Int -> Integer, @@ -349,6 +399,7 @@ x ^ n | n > 0 = f x (n-1) x | otherwise = f b (i-1) (b*y) _ ^ _ = error "Prelude.^: negative exponent" +-- | raise a number to an integral power {-# SPECIALISE (^^) :: Rational -> Int -> Rational #-} (^^) :: (Fractional a, Integral b) => a -> b -> a @@ -356,12 +407,16 @@ x ^^ n = if n >= 0 then x^n else recip (x^(negate n)) ------------------------------------------------------- +-- | @'gcd' x y@ is the greatest (positive) integer that divides both @x@ +-- and @y@; for example @'gcd' (-3) 6@ = @3@, @'gcd' (-3) (-6)@ = @3@, +-- @'gcd' 0 4@ = @4@. @'gcd' 0 0@ raises a runtime error. gcd :: (Integral a) => a -> a -> a gcd 0 0 = error "Prelude.gcd: gcd 0 0 is undefined" gcd x y = gcd' (abs x) (abs y) where gcd' a 0 = a gcd' a b = gcd' b (a `rem` b) +-- | @'lcm' x y@ is the smallest positive integer that both @x@ and @y@ divide. lcm :: (Integral a) => a -> a -> a {-# SPECIALISE lcm :: Int -> Int -> Int #-} lcm _ 0 = 0 diff --git a/GHC/Stable.lhs b/GHC/Stable.lhs index 75506f8..8ded1e4 100644 --- a/GHC/Stable.lhs +++ b/GHC/Stable.lhs @@ -65,9 +65,9 @@ deRefStablePtr (StablePtr sp) = IO $ \s -> deRefStablePtr# sp s -- value. Afterwards, if the stable pointer is passed to -- 'deRefStablePtr' or 'freeStablePtr', the behaviour is -- undefined. However, the stable pointer may still be passed to --- 'castStablePtrToPtr', but the @Ptr ()@ value returned by --- 'castStablePtrToPtr', in this case, is undefined (in --- particular, it may be 'Ptr.nullPtr'). Nevertheless, the call +-- 'castStablePtrToPtr', but the @'Foreign.Ptr.Ptr' ()@ value returned +-- by 'castStablePtrToPtr', in this case, is undefined (in particular, +-- it may be 'Foreign.Ptr.nullPtr'). Nevertheless, the call -- to 'castStablePtrToPtr' is guaranteed not to diverge. -- foreign import ccall unsafe freeStablePtr :: StablePtr a -> IO () -- 1.7.10.4