7bc1774ebe0326dbf010836d776dbe5ee0d8a586
[haskell-report.git] / report / ratio.verb
1 %**<title>The Haskell 98 Library Report: Rational Numbers</title>
2 %**~header
3 \section{Rational Numbers}
4 \index{rational numbers}
5
6 \outline{
7 \inputHS{lib-hdrs/Ratio}
8 }
9
10 For each @Integral@ type $t$, there is
11 a type @Ratio@\indextycon{Ratio} $t$ of rational pairs with components of
12 type $t$.  The type name @Rational@\indexsynonym{Rational} is a synonym for
13 @Ratio Integer@.  
14
15 @Ratio@ is an instance of classes @Eq@, @Ord@, @Num@, @Real@, 
16 @Fractional@, @RealFrac@, @Enum@, @Read@, and @Show@.  In each case,
17 the instance for $@Ratio@~t$ simply ``lifts'' the corresponding operations
18 over $t$.  If $t$ is a bounded type, the results may be unpredictable;
19 for example @Ratio Int@ may give rise to integer overflow even for
20 rational numbers of small absolute size.
21
22 The operator @(%)@\index{%@@{\tt  {\char'045}}} forms the ratio of two
23 integral numbers, reducing the fraction to terms with no common factor
24 and such that the denominator is positive.  The functions
25 @numerator@\indextt{numerator}
26 and @denominator@\indextt{denominator} extract the components of a
27 ratio; these are in reduced form with a positive denominator.
28 @Ratio@ is an abstract type.  For example, @12 % 8@ is reduced to 3/2
29 and @12 % (-8)@ is reduced to (-3)/2.
30
31 The @approxRational@ function, applied to two real fractional numbers
32 @x@ and @epsilon@, returns the simplest rational number within the open
33 interval "(@x@-@epsilon@, @x@+@epsilon@)".
34 A rational number "n/d" in reduced form is said to
35 be simpler than another "n'/d'" if "|n| \leq |n'|" and "d \leq d'".
36 Note that it can be proved that any real interval contains a unique
37 simplest rational.
38
39
40 %% Deleted the following -- this is implementation detail -- KH/AD.
41 % ; here, for simplicity, we assume a closed rational
42 % interval.  If such an interval includes at least one whole number, then
43 % the simplest rational is the absolutely least whole number.  Otherwise,
44 % the bounds are of the form "q/1 + r/d" and "q/1 + r'/d'", where "|r| < d"
45 % and "|r'| < d'", and the simplest rational is "q/1" + the reciprocal of
46 % the simplest rational between "d'/r'" and "d/r".
47
48 \clearpage
49 \subsection{Library {\tt Ratio}}
50 \label{Ratio}
51 \inputHS{lib-code/Ratio}
52
53 %**~footer