1 %**<title>The Haskell 98 Library Report: Numerics</title>
3 \section{Numeric}
4 \label{lib-numeric}
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.
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
20 \subsection{Showing functions}
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.
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.
32 \item @showInt, showOct, showHex :: Integral a => a -> ShowS@ \\
33 show {\em non-negative} @Integral@ numbers in base 10, 8, and 16 respectively.
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.
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}
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.
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@.
76 \item @readFloat :: (RealFrac a) => ReadS a@ \\
77 reads an {\em unsigned} @RealFrac@ value, expressed in decimal scientific notation.
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.
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.)
88 \subsection{Miscellaneous}
90 \begin{itemize}
91 \item @fromRat :: (RealFloat a) => Rational -> a@ converts a @Rational@ value
92 into any type in class @RealFloat@.
93 \end{itemize}
95 \subsection{Library {\tt Numeric}}
96 \inputHS{lib-code/Numeric}
98 %**~footer