pattern_guard_list_comprehension_footnote
[haskell-report.git] / report / numeric.verb
1 %**<title>The Haskell 98 Library Report: Numerics</title>
2 %**~header
3 \section{Numeric}
4 \label{lib-numeric}
5
6 \outline{
7 \inputHS{lib-hdrs/Numeric}
8 }
9 This library contains assorted numeric functions, many of which are
10 used in the standard Prelude.  
11
12 In what follows, recall the following type definitions from the @Prelude@:
13 \bprog
14
15   type ShowS = String -> String
16   type ReadS = String -> [(a,String)]
17 @
18 \eprog
19
20 \subsection{Showing functions}
21
22 \begin{itemize}
23 \item @showSigned :: (Real a) => (a -> ShowS) -> Int -> a -> ShowS@ \\ converts a
24 possibly-negative @Real@ value of type @a@ to a string.  In the call "(@showSigned@ ~show ~prec ~val)",
25 "val" is the value to show, "prec" is the precedence of the enclosing context, and "show" is
26 a function that can show unsigned values.
27
28 \item @showIntAtBase :: Integral a => a -> (Int -> Char) -> a -> ShowS@ \\
29 shows a {\em non-negative} @Integral@ number using the base specified by the first argument,
30 and the character representation specified by the second.
31
32 \item @showInt, showOct, showHex :: Integral a => a -> ShowS@ \\ 
33 show {\em non-negative} @Integral@ numbers in base 10, 8, and 16 respectively.
34
35 \item 
36 @showFFloat, showEFloat, showGFloat@ \\
37 @    :: (RealFloat a) => Maybe Int -> a -> ShowS@ \\
38 These three functions all show signed @RealFloat@ values:
39 \begin{itemize}
40 \item @showFFloat@ uses standard decimal notation (e.g. @245000@, @0.0015@).
41 \item @showEFloat@ uses scientific (exponential) notation (e.g. @2.45e2@, @1.5e-3@).
42 \item @showGFloat@ uses standard decimal notation for arguments whose absolute value lies 
43 between @0.1@ and @9,999,999@, and scientific notation otherwise.
44 \end{itemize}
45 In the call "(@showEFloat@ ~digs ~val)", if "digs" is @Nothing@, the value is shown to full
46 precision; if "digs" is "@Just@~ d", then at most "d" digits after the decimal point are shown.
47 Exactly the same applies to the "digs" argument of the other two functions.
48
49 \item @floatToDigits  :: (RealFloat a) => Integer -> a -> ([Int], Int)@ \\
50 converts a base and a value to the representation of the value in digits, plus
51 an exponent.  More specifically, if
52 $$
53 @floatToDigits@~b~r = @([@d_1, d_2, ... d_n@], @e@)@
54 $$
55 then the following properties hold:
56 \begin{itemize}
57 \item $r =  0.d_1 d_2 ..., d_n ~*~ b^e$
58 \item $n \geq 0$
59 \item $d_1 \neq 0 ~ \mbox{(when $n > 0$)}$
60 \item $0 \leq d_i \leq b-1$
61 \end{itemize}
62 \end{itemize}
63
64 \subsection{Reading functions}
65
66 \begin{itemize}
67 \item @readSigned :: (Real a) => ReadS a -> ReadS a@ \\ 
68 reads a {\em signed} @Real@ value,
69 given a reader for an unsigned value.
70
71 \item @readInt :: (Integral a) => a -> (Char->Bool) -> (Char->Int) -> ReadS a@ \\
72 reads an {\em unsigned} @Integral@ value in an arbitrary base.  In the call "(@readInt@~ base ~isdig ~d2i)",
73 "base" is the base, "isdig" is a predicate distinguishing valid digits in this base, and "d2i" converts
74 a valid digit character to an @Int@.
75
76 \item @readFloat :: (RealFrac a) => ReadS a@ \\ 
77 reads an {\em unsigned} @RealFrac@ value, expressed in decimal scientific notation.
78
79 \item @readDec, readOct, readHex :: (Integral a) => ReadS a@  \\
80 each read an unsigned number, in decimal, octal, and hexadecimal notation respectively.
81 In the hexadecimal case, both upper or lower case letters are allowed.
82
83 \item @lexDigits :: ReadS String@ reads a non-empty string of decimal digits.
84 \end{itemize}
85 (NB: @readInt@ is the ``dual'' of @showIntAtBase@, and @readDec@ is the ``dual'' of @showInt@.
86 The inconsistent naming is a historical accident.)
87
88 \subsection{Miscellaneous}
89
90 \begin{itemize}
91 \item @fromRat :: (RealFloat a) => Rational -> a@ converts a @Rational@ value
92 into any type in class @RealFloat@.
93 \end{itemize}
94
95 \subsection{Library {\tt Numeric}}
96 \inputHS{lib-code/Numeric}
97
98 %**~footer
99
100