-- | '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
-- $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
-- ** 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.
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
-- 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:
%*********************************************************
\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
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
\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}
%*********************************************************
\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
\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
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
%*********************************************************
\begin{code}
+-- | general coercion from integral types
fromIntegral :: (Integral a, Num b) => a -> b
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
odd = not . even
-------------------------------------------------------
+-- | raise a number to a non-negative integral power
{-# SPECIALISE (^) ::
Integer -> Integer -> Integer,
Integer -> Int -> Integer,
| 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
-------------------------------------------------------
+-- | @'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
-- 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 ()
projects / ghc-base.git / commitdiff