r7rs-small-texinfo

R7RS-small Scheme converted to Texinfo.
git clone https://kaka.farm/~git/r7rs-small-texinfo
Log | Files | Refs | README | LICENSE

numbers.texinfo (41212B)


      1 @node Numbers
      2 @section Numbers
      3 
      4 @cindex number
      5 
      6 It is important to distinguish between mathematical numbers, the Scheme
      7 numbers that attempt to model them, the machine representations used to
      8 implement the Scheme numbers, and notations used to write numbers. This
      9 report uses the types number, complex, real, rational, and integer to
     10 refer to both mathematical numbers and Scheme numbers.
     11 
     12 @menu
     13 * Numerical types::
     14 * Exactness::
     15 * Implementation restrictions::
     16 * Implementation extensions::
     17 * Syntax of numerical constants::
     18 * Numerical operations::
     19 * Numerical input and output::
     20 @end menu
     21 
     22 @node Numerical types
     23 @subsection Numerical types
     24 
     25 Mathematically, numbers are arranged into a tower of subtypes in which
     26 each level is a subset of the level above it:
     27 
     28 @display
     29 number
     30 complex number
     31 real number
     32 rational number
     33 integer
     34 @end display
     35 
     36 For example, 3 is an integer. Therefore 3 is also a rational, a real, and
     37 a complex number. The same is true of the Scheme numbers that model 3. For
     38 Scheme numbers, these types are defined by the predicates @code{number?},
     39 @code{complex?}, @code{real?}, @code{rational?}, and @code{integer?}.
     40 
     41 There is no simple relationship between a number's type and its
     42 representation inside a computer. Although most implementations of Scheme
     43 will offer at least two different representations of 3, these different
     44 representations denote the same integer.
     45 
     46 Scheme's numerical operations treat numbers as abstract data,
     47 as independent of their representation as possible. Although an
     48 implementation of Scheme may use multiple internal representations of
     49 numbers, this ought not to be apparent to a casual programmer writing
     50 simple programs.
     51 
     52 @node Exactness
     53 @subsection Exactness
     54 
     55 It is useful to distinguish between numbers that are represented exactly
     56 and those that might not be. For example, indexes into data structures
     57 must be known exactly, as must some polynomial coefficients in a
     58 symbolic algebra system. On the other hand, the results of measurements
     59 are inherently inexact, and irrational numbers may be approximated by
     60 rational and therefore inexact approximations. In order to catch uses
     61 of inexact numbers where exact numbers are required, Scheme explicitly
     62 distinguishes exact from inexact numbers. This distinction is orthogonal
     63 to the dimension of type.
     64 
     65 A Scheme number is @define{exact} if it was written as an exact constant
     66 or was derived from exact numbers using only exact operations. A number
     67 is @define{inexact} if it was written as an inexact constant, if it was
     68 derived using @define{inexact} ingredients, or if it was derived using
     69 @define{inexact} operations. Thus inexactness is a contagious property of
     70 a number.  In particular, an @define{exact complex number} has an exact
     71 real part and an exact imaginary part; all other complex numbers are
     72 @define{inexact complex numbers}.
     73 
     74 If two implementations produce exact results for a computation that
     75 did not involve inexact intermediate results, the two ultimate results
     76 will be mathematically equal. This is generally not true of computations
     77 involving inexact numbers since approximate methods such as floating-point
     78 arithmetic may be used, but it is the duty of each implementation to
     79 make the result as close as practical to the mathematically ideal result.
     80 
     81 Rational operations such as @code{+} should always produce exact
     82 results when given exact arguments. If the operation is unable to
     83 produce an exact result, then it may either report the violation of an
     84 implementation restriction or it may silently coerce its result to an
     85 inexact value. However, @code{(/ 3 4)} must not return the mathematically
     86 incorrect value @code{0}.  @xref{Implementation restrictions}.
     87 
     88 Except for @code{exact}, the operations described in this section must
     89 generally return inexact results when given any inexact arguments. An
     90 operation may, however, return an exact result if it can prove that the
     91 value of the result is unaffected by the inexactness of its arguments. For
     92 example, multiplication of any number by an exact zero may produce an
     93 exact zero result, even if the other argument is inexact.
     94 
     95 Specifically, the expression @code{(* 0 +inf.0)} may return @code{0},
     96 or @code{+nan.0}, or report that inexact numbers are not supported,
     97 or report that non-rational real numbers are not supported, or fail
     98 silently or noisily in other implementation-specific ways.
     99 
    100 @node Implementation restrictions
    101 @subsection Implementation restrictions
    102 
    103 Implementations of Scheme are not required to implement the whole tower
    104 of subtypes given in @ref{Numerical types}, but they must implement a
    105 coherent subset consistent with both the purposes of the implementation
    106 and the spirit of the Scheme language. For example, implementations
    107 in which all numbers are real, or in which non-real numbers are always
    108 inexact, or in which exact numbers are always integer, are still quite
    109 useful.
    110 
    111 Implementations may also support only a limited range of numbers of any
    112 type, subject to the requirements of this section. The supported range
    113 for exact numbers of any type may be different from the supported range
    114 for inexact numbers of that type. For example, an implementation that uses
    115 IEEE binary double-precision floating-point numbers to represent all its
    116 inexact real numbers may also support a practically unbounded range of
    117 exact integers and rationals while limiting the range of inexact reals
    118 (and therefore the range of inexact integers and rationals) to the dynamic
    119 range of the IEEE binary double format. Furthermore, the gaps between the
    120 representable inexact integers and rationals are likely to be very large
    121 in such an implementation as the limits of this range are approached.
    122 
    123 An implementation of Scheme must support exact integers throughout the
    124 range of numbers permitted as indexes of lists, vectors, bytevectors, and
    125 strings or that result from computing the length of one of these. The
    126 @code{length}, @code{vector-length}, @code{bytevector-length}, and
    127 @code{string-length} procedures must return an exact integer, and it is
    128 an error to use anything but an exact integer as an index. Furthermore,
    129 any integer constant within the index range, if expressed by an exact
    130 integer syntax, must be read as an exact integer, regardless of any
    131 implementation restrictions that apply outside this range. Finally, the
    132 procedures listed below will always return exact integer results provided
    133 all their arguments are exact integers and the mathematically expected
    134 results are representable as exact integers within the implementation:
    135 
    136 @itemize @w{}
    137 @item
    138 @code{-}
    139 
    140 @item
    141 @code{*}
    142 
    143 @item
    144 @code{+}
    145 
    146 @item
    147 @code{abs}
    148 
    149 @item
    150 @code{ceiling}
    151 
    152 @item
    153 @code{denominator}
    154 
    155 @item
    156 @code{exact-integer-sqrt}
    157 
    158 @item
    159 @code{expt}
    160 
    161 @item
    162 @code{floor}
    163 
    164 @item
    165 @code{floor/}
    166 
    167 @item
    168 @code{floor-quotient}
    169 
    170 @item
    171 @code{floor-remainder}
    172 
    173 @item
    174 @code{gcd}
    175 
    176 @item
    177 @code{lcm}
    178 
    179 @item
    180 @code{max}
    181 
    182 @item
    183 @code{min}
    184 
    185 @item
    186 @code{modulo}
    187 
    188 @item
    189 @code{numerator}
    190 
    191 @item
    192 @code{quotient}
    193 
    194 @item
    195 @code{rationalize}
    196 
    197 @item
    198 @code{remainder}
    199 
    200 @item
    201 @code{round}
    202 
    203 @item
    204 @code{square}
    205 
    206 @item
    207 @code{truncate}
    208 
    209 @item
    210 @code{truncate/}
    211 
    212 @item
    213 @code{truncate-quotient}
    214 
    215 @item
    216 @code{truncate-remainder}
    217 
    218 @end itemize
    219 
    220 It is recommended, but not required, that implementations support
    221 exact integers and exact rationals of practically unlimited size and
    222 precision, and to implement the above procedures and the @code{/}
    223 procedure in such a way that they always return exact results when
    224 given exact arguments. If one of these procedures is unable to deliver
    225 an exact result when given exact arguments, then it may either report
    226 a violation of an implementation restriction or it may silently coerce
    227 its result to an inexact number; such a coercion can cause an error
    228 later. Nevertheless, implementations that do not provide exact rational
    229 numbers should return inexact rational numbers rather than reporting an
    230 implementation restriction.
    231 
    232 An implementation may use floating-point and other approximate
    233 representation strategies for inexact numbers. This report recommends,
    234 but does not require, that implementations that use floating-point
    235 representations follow the IEEE 754 standard, and that implementations
    236 using other representations should match or exceed the precision
    237 achievable using these floating-point standards [@ref{IEEE}]. In particular,
    238 the description of transcendental functions in IEEE 754-2008 should be
    239 followed by such implementations, particularly with respect to infinities
    240 and NaNs.
    241 
    242 Although Scheme allows a variety of written notations for numbers, any
    243 particular implementation may support only some of them. For example,
    244 an implementation in which all numbers are real need not support the
    245 rectangular and polar notations for complex numbers. If an implementation
    246 encounters an exact numerical constant that it cannot represent as an
    247 exact number, then it may either report a violation of an implementation
    248 restriction or it may silently represent the constant by an inexact
    249 number.
    250 
    251 @node Implementation extensions
    252 @subsection Implementation extensions
    253 
    254 Implementations may provide more than one representation of floating-point
    255 numbers with differing precisions. In an implementation which does so, an
    256 inexact result must be represented with at least as much precision as is
    257 used to express any of the inexact arguments to that operation. Although
    258 it is desirable for potentially inexact operations such as @code{sqrt}
    259 to produce exact answers when applied to exact arguments, if an exact
    260 number is operated upon so as to produce an inexact result, then the
    261 most precise representation available must be used. For example, the
    262 value of @code{(sqrt 4)} should be @code{2}, but in an implementation
    263 that provides both single and double precision floating point numbers
    264 it may be the latter but must not be the former.
    265 
    266 It is the programmer's responsibility to avoid using inexact number
    267 objects with magnitude or significand too large to be represented in
    268 the implementation.
    269 
    270 In addition, implementations may distinguish special numbers called
    271 positive infinity, negative infinity, NaN, and negative zero.
    272 
    273 Positive infinity is regarded as an inexact real (but not rational)
    274 number that represents an indeterminate value greater than the numbers
    275 represented by all rational numbers.  Negative infinity is regarded as an
    276 inexact real (but not rational) number that represents an indeterminate
    277 value less than the numbers represented by all rational numbers.
    278 
    279 Adding or multiplying an infinite value by any finite real value results
    280 in an appropriately signed infinity; however, the sum of positive and
    281 negative infinities is a NaN. Positive infinity is the reciprocal of zero,
    282 and negative infinity is the reciprocal of negative zero.  The behavior
    283 of the transcendental functions is sensitive to infinity in accordance
    284 with IEEE 754.
    285 
    286 A NaN is regarded as an inexact real (but not rational) number so
    287 indeterminate that it might represent any real value, including positive
    288 or negative infinity, and might even be greater than positive infinity
    289 or less than negative infinity. An implementation that does not support
    290 non-real numbers may use NaN to represent non-real values like
    291 @code{(sqrt -1.0)} and @code{(asin 2.0)}.
    292 
    293 A NaN always compares false to any number, including a NaN. An arithmetic
    294 operation where one operand is NaN returns NaN, unless the implementation
    295 can prove that the result would be the same if the NaN were replaced by
    296 any rational number. Dividing zero by zero results in NaN unless both
    297 zeros are exact.
    298 
    299 Negative zero is an inexact real value written @code{-0.0} and is distinct
    300 (in the sense of @code{eqv?}) from @code{0.0}. A Scheme implementation
    301 is not required to distinguish negative zero. If it does, however, the
    302 behavior of the transcendental functions is sensitive to the distinction
    303 in accordance with IEEE 754. Specifically, in a Scheme implementing
    304 both complex numbers and negative zero, the branch cut of the complex
    305 logarithm function is such that @code{(imag-part (log -1.0-0.0i))}
    306 is @minus{}@greekpi{} rather than @greekpi{}.
    307 
    308 Furthermore, the negation of negative zero is ordinary zero and vice
    309 versa. This implies that the sum of two or more negative zeros is
    310 negative, and the result of subtracting (positive) zero from a negative
    311 zero is likewise negative. However, numerical comparisons treat negative
    312 zero as equal to zero.
    313 
    314 Note that both the real and the imaginary parts of a complex number can
    315 be infinities, NaNs, or negative zero.
    316 
    317 @node Syntax of numerical constants
    318 @subsection Syntax of numerical constants
    319 
    320 The syntax of the written representations for numbers is described
    321 formally in @ref{Formal syntax}.  Note that case is not significant in
    322 numerical constants.
    323 
    324 @sharpindex{b}
    325 @sharpindex{o}
    326 @sharpindex{d}
    327 @sharpindex{x}
    328 
    329 A number can be written in binary, octal, decimal, or hexadecimal by
    330 the use of a radix prefix. The radix prefixes are @code{#b} (binary),
    331 @code{#o} (octal), @code{#d} (decimal), and @code{#x} (hexadecimal). With
    332 no radix prefix, a number is assumed to be expressed in decimal.
    333 
    334 @sharpindex{e}
    335 @sharpindex{i}
    336 
    337 A numerical constant can be specified to be either exact or inexact
    338 by a prefix. The prefixes are @code{#e} for exact, and @code{#i} for
    339 inexact. An exactness prefix can appear before or after any radix prefix
    340 that is used. If the written representation of a number has no exactness
    341 prefix, the constant is inexact if it contains a decimal point or an
    342 exponent. Otherwise, it is exact.
    343 
    344 In systems with inexact numbers of varying precisions it can be useful to
    345 specify the precision of a constant. For this purpose, implementations
    346 may accept numerical constants written with an exponent marker that
    347 indicates the desired precision of the inexact representation. If so, the
    348 letter @code{s}, @code{f}, @code{d}, or @code{l}, meaning @define{short},
    349 @define{single}, @define{double}, or @define{long} precision, respectively, can
    350 be used in place of @code{e}. The default precision has at least as much
    351 precision as double, but implementations may allow this default to be
    352 set by the user.
    353 
    354 @display
    355 @code{3.14159265358979F0}
    356         Round to single --- @code{3.141593}
    357 @code{0.6L0}
    358         Extend to long --- @code{.600000000000000}
    359 @end display
    360 
    361 The numbers positive infinity, negative infinity, and NaN are written
    362 @code{+inf.0}, @code{-inf.0} and @define{+nan.0} respectively. NaN may
    363 also be written @code{-nan.0}. The use of signs in the written
    364 representation does not necessarily reflect the underlying sign of the
    365 NaN value, if any. Implementations are not required to support these
    366 numbers, but if they do, they must do so in general conformance with
    367 IEEE 754. However, implementations are not required to support
    368 signaling NaNs, nor to provide a way to distinguish between different
    369 NaNs.
    370 
    371 There are two notations provided for non-real complex numbers: the
    372 @define{rectangular notation} @var{a}@code{+}@var{b}@code{i}, where
    373 @var{a} is the real part and @var{b} is the imaginary part; and the
    374 @define{polar notation} @var{r}@code{@@}@var{@greektheta{}} where @var{r}
    375 is the magnitude and @var{@greektheta{}} is the phase (angle) in
    376 radians. These are related by the equation
    377 @math{a + bi = r \cos\theta + (r \sin\theta)i}. All of @var{a},
    378 @var{b}, @var{r}, and @var{@greektheta{}} are real numbers.
    379 
    380 @node Numerical operations
    381 @subsection Numerical operations
    382 
    383 The reader is referred to @ref{Error situations and unspecified
    384 behavior} for a summary of the naming conventions used to specify
    385 restrictions on the types of arguments to numerical routines. The
    386 examples used in this section assume that any numerical constant
    387 written using an exact notation is indeed represented as an exact
    388 number. Some examples also assume that certain numerical constants
    389 written using an inexact notation can be represented without loss of
    390 accuracy; the inexact constants were chosen so that this is likely to
    391 be true in implementations that use IEEE binary doubles to represent
    392 inexact numbers.
    393 
    394 @deffn  procedure number? obj
    395 @deffnx procedure complex? obj
    396 @deffnx procedure real? obj
    397 @deffnx procedure rational? obj
    398 @deffnx procedure integer? obj
    399 
    400 These numerical type predicates can be applied to any kind of argument,
    401 including non-numbers. They return @code{#t} if the object is of the
    402 named type, and otherwise they return @code{#f}.  In general, if a type
    403 predicate is true of a number then all higher type predicates are also
    404 true of that number. Consequently, if a type predicate is false of a
    405 number, then all lower type predicates are also false of that number.
    406 
    407 If @var{z} is a complex number, then @code{(real? }@var{z}@code{)} is
    408 true if and only if @code{(zero? (imag-part }@var{z}@code{))} is true. If
    409 @var{x} is an inexact real number, then @code{(integer? }@var{x}@code{)}
    410 is true if and only if @code{(= }@var{x}@code{ (round }@var{x}@code{))}.
    411 
    412 The numbers @code{+inf.0}, @code{-inf.0}, and @code{+nan.0} are real
    413 but not rational.
    414 
    415 @lisp
    416 (complex? 3+4i)    @result{} #t
    417 (complex? 3)       @result{} #t
    418 (real? 3)          @result{} #t
    419 (real? -2.5+0i)    @result{} #t
    420 (real? -2.5+0.0i)  @result{} #f
    421 (real? #e1e10)     @result{} #t
    422 (real? +inf.0)     @result{} #t
    423 (real? +nan.0)     @result{} #t
    424 (rational? -inf.0) @result{} #f
    425 (rational? 3.5)    @result{} #t
    426 (rational? 6/10)   @result{} #t
    427 (rational? 6/3)    @result{} #t
    428 (integer? 3+0i)    @result{} #t
    429 (integer? 3.0)     @result{} #t
    430 (integer? 8/4)     @result{} #t
    431 @end lisp
    432 
    433 Note: The behavior of these type predicates on inexact numbers is
    434 unreliable, since any inaccuracy might affect the result.
    435 
    436 Note: In many implementations the @code{complex?} procedure will be the
    437 same as @code{number?}, but unusual implementations may represent some
    438 irrational numbers exactly or may extend the number system to support
    439 some kind of non-complex numbers.
    440 
    441 @end deffn
    442 
    443 @deffn  procedure exact? z
    444 @deffnx procedure inexact? z
    445 
    446 These numerical predicates provide tests for the exactness of a
    447 quantity. For any Scheme number, precisely one of these predicates is
    448 true.
    449 
    450 @lisp
    451 (exact? 3.0)   @result{} #f
    452 (exact? #e3.0) @result{} #t
    453 (inexact? 3.)  @result{} #t
    454 @end lisp
    455 @end deffn
    456 
    457 @deffn procedure exact-integer? z
    458 
    459 Returns @code{#t} if @var{z} is both exact and an integer; otherwise
    460 returns @code{#f}.
    461 
    462 @lisp
    463 (exact-integer? 32)   @result{} #t
    464 (exact-integer? 32.0) @result{} #f
    465 (exact-integer? 32/5) @result{} #f
    466 @end lisp
    467 @end deffn
    468 
    469 @deffn {inexact library procedure} finite? z
    470 
    471 The @code{finite?} procedure returns @code{#t} on all real numbers
    472 except @code{+inf.0}, @code{-inf.0}, and @code{+nan.0}, and on complex
    473 numbers if their real and imaginary parts are both finite. Otherwise it
    474 returns @code{#f}.
    475 
    476 @lisp
    477 (finite? 3)          @result{} #t
    478 (finite? +inf.0)     @result{} #f
    479 (finite? 3.0+inf.0i) @result{} #f
    480 @end lisp
    481 @end deffn
    482 
    483 @deffn {inexact library procedure} infinite? z
    484 
    485 The @code{infinite?} procedure returns @code{#t} on the real numbers
    486 @code{+inf.0} and @code{-inf.0}, and on complex numbers if their real
    487 or imaginary parts or both are infinite. Otherwise it returns
    488 @code{#f}.
    489 
    490 @lisp
    491 (infinite? 3)          @result{} #f
    492 (infinite? +inf.0)     @result{} #t
    493 (infinite? +nan.0)     @result{} #f
    494 (infinite? 3.0+inf.0i) @result{} #t
    495 @end lisp
    496 @end deffn
    497 
    498 @deffn {inexact library procedure} nan? z
    499 
    500 The @code{nan?} procedure returns @code{#t} on @code{+nan.0}, and on
    501 complex numbers if their real or imaginary parts or both are
    502 @code{+nan.0}. Otherwise it returns @code{#f}.
    503 
    504 @lisp
    505 (nan? +nan.0)      @result{} #t
    506 (nan? 32)          @result{} #f
    507 (nan? +nan.0+5.0i) @result{} #t
    508 (nan? 1+2i)        @result{} #f
    509 @end lisp
    510 @end deffn
    511 
    512 @deffn  procedure = z@sub{1} z@sub{2} z@sub{3}@dots{}
    513 @deffnx procedure < x@sub{1} x@sub{2} x@sub{3}@dots{}
    514 @deffnx procedure > x@sub{1} x@sub{2} x@sub{3}@dots{}
    515 @deffnx procedure <= x@sub{1} x@sub{2} x@sub{3}@dots{}
    516 @deffnx procedure >= x@sub{1} x@sub{2} x@sub{3}@dots{}
    517 
    518 These procedures return @code{#t} if their arguments are (respectively):
    519 equal, monotonically increasing, monotonically decreasing, monotonically
    520 non-decreasing, or monotonically non-increasing, and @code{#f} otherwise.
    521 If any of the arguments are @code{+nan.0}, all the predicates return
    522 @code{#f}.  They do not distinguish between inexact zero and inexact
    523 negative zero.
    524 
    525 These predicates are required to be transitive.
    526 
    527 Note: The implementation approach of converting all arguments to inexact
    528 numbers if any argument is inexact is not transitive.  For example, let
    529 @code{big} be @code{(expt 2 1000)}, and assume that @code{big} is exact
    530 and that inexact numbers are represented by 64-bit IEEE binary floating
    531 point numbers.  Then @code{(= (- big 1) (inexact big))} and @code{(=
    532 (inexact big) (+ big 1))} would both be true with this approach, because
    533 of the limitations of IEEE representations of large integers, whereas
    534 @code{(= (- big 1) (+ big 1))} is false.  Converting inexact values to
    535 exact numbers that are the same (in the sense of @code{=}) to them will
    536 avoid this problem, though special care must be taken with infinities.
    537 
    538 Note: While it is not an error to compare inexact numbers using these
    539 predicates, the results are unreliable because a small inaccuracy can
    540 affect the result; this is especially true of @code{=} and @code{zero?}.
    541 When in doubt, consult a numerical analyst.
    542 
    543 @end deffn
    544 
    545 @deffn  procedure zero? z
    546 @deffnx procedure positive? x
    547 @deffnx procedure negative? x
    548 @deffnx procedure odd? n
    549 @deffnx procedure even? n
    550 
    551 These numerical predicates test a number for a particular property,
    552 returning @code{#t} or @code{#f}. See note above.
    553 
    554 @end deffn
    555 
    556 @deffn  procedure max x@sub{1} x@sub{2}@dots{}
    557 @deffnx procedure min x@sub{1} x@sub{2}@dots{}
    558 
    559 These procedures return the maximum or minimum of their arguments.
    560 
    561 @lisp
    562 (max 3 4)   @result{} 4    ; exact
    563 (max 3.9 4) @result{} 4.0  ; inexact
    564 @end lisp
    565 
    566 Note: If any argument is inexact, then the result will also be inexact
    567 (unless the procedure can prove that the inaccuracy is not large enough to
    568 affect the result, which is possible only in unusual implementations). If
    569 @code{min} or @code{max} is used to compare numbers of mixed exactness,
    570 and the numerical value of the result cannot be represented as an inexact
    571 number without loss of accuracy, then the procedure may report a violation
    572 of an implementation restriction.
    573 
    574 @end deffn
    575 
    576 @deffn  procedure + z@sub{1}@dots{}
    577 @deffnx procedure * z@sub{1}@dots{}
    578 
    579 These procedures return the sum or product of their arguments.
    580 
    581 @lisp
    582 (+ 3 4) @result{} 7
    583 (+ 3)   @result{} 3
    584 (+)     @result{} 0
    585 (* 4)   @result{} 4
    586 (*)     @result{} 1
    587 @end lisp
    588 @end deffn
    589 
    590 @deffn  procedure - z
    591 @deffnx procedure - z@sub{1} z@sub{2}@dots{}
    592 @deffnx procedure / z
    593 @deffnx procedure / z@sub{1} z@sub{2}@dots{}
    594 
    595 With two or more arguments, these procedures return the difference or
    596 quotient of their arguments, associating to the left. With one argument,
    597 however, they return the additive or multiplicative inverse of their
    598 argument.
    599 
    600 It is an error if any argument of @code{/} other than the first is an
    601 exact zero. If the first argument is an exact zero, an implementation
    602 may return an exact zero unless one of the other arguments is a NaN.
    603 
    604 @lisp
    605 (- 3 4)   @result{} -1
    606 (- 3 4 5) @result{} -6
    607 (- 3)     @result{} -3
    608 (/ 3 4 5) @result{} 3/20
    609 (/ 3)     @result{} 1/3
    610 @end lisp
    611 
    612 @end deffn
    613 
    614 @deffn procedure abs x
    615 
    616 The abs procedure returns the absolute value of its argument.
    617 
    618 @lisp
    619 (abs -7) @result{} 7
    620 @end lisp
    621 
    622 @end deffn
    623 
    624 @deffn  procedure floor/ n@sub{1} n@sub{2}
    625 @deffnx procedure floor-quotient n@sub{1} n@sub{2}
    626 @deffnx procedure floor-remainder n@sub{1} n@sub{2}
    627 @deffnx procedure truncate/ n@sub{1} n@sub{2}
    628 @deffnx procedure truncate-quotient n@sub{1} n@sub{2}
    629 @deffnx procedure truncate-remainder n@sub{1} n@sub{2}
    630 
    631 These procedures implement number-theoretic (integer) division. It is
    632 an error if @var{n} is zero.  The procedures ending in @code{/} return
    633 two integers; the other procedures return an integer. All the procedures
    634 compute a quotient @var{n@sub{q}} and remainder @var{n@sub{r}} such that
    635 @var{n@sub{1}} = @var{n@sub{2}}@var{n@sub{q}} + @var{n@sub{r}}. For each
    636 of the division operators, there are three procedures defined as follows:
    637 
    638 @c This is hideous. Can we do any better?
    639 @lisp
    640 (@r{@svar{operator}}/ @r{@var{n@sub{1}} @var{n@sub{2}}}) @result{} @r{@var{n@sub{q}} @var{n@sub{r}}}
    641 (@r{@svar{operator}}-quotient @r{@var{n@sub{1}} @var{n@sub{2}}}) @result{} @r{@var{n@sub{q}}}
    642 (@r{@svar{operator}}-remainder @r{@var{n@sub{1}} @var{n@sub{2}}}) @result{} @r{@var{n@sub{r}}}
    643 @end lisp
    644 
    645 The remainder @var{n@sub{r}} is determined by the choice of integer
    646 @var{n@sub{q}}: @var{n@sub{r}} = @var{n@sub{1}} @minus{}
    647 @var{n@sub{2}}@var{n@sub{q}}. Each set of operators uses a different
    648 choice of @var{n@sub{q}}:
    649 
    650 @table @code
    651 
    652 @item floor
    653 @math{n_q = \lfloor n_1 / n_2 \rfloor}
    654 
    655 @item truncate
    656 @math{n_q =} truncate@math{(n_1 / n_2)}
    657 
    658 @end table
    659 
    660 For any of the operators, and for integers @var{n@sub{1}} and
    661 @var{n@sub{2}} with @var{n@sub{2}} not equal to 0,
    662 
    663 @lisp
    664 (= @r{@var{n@sub{1}}}
    665    (+ (* @r{@var{n@sub{2}}} (@r{@svar{operator}}-quotient @r{@var{n@sub{1}} @var{n@sub{2}}}))
    666       (@r{@svar{operator}}-remainder @r{@var{n@sub{1}} @var{n@sub{2}}})))
    667         @result{} #t
    668 @end lisp
    669 
    670 provided all numbers involved in that computation are exact.
    671 
    672 Examples:
    673 
    674 @lisp
    675 (floor/ 5 2)        @result{}  2    1
    676 (floor/ -5 2)       @result{} -3    1
    677 (floor/ 5 -2)       @result{} -3   -1
    678 (floor/ -5 -2)      @result{}  2   -1
    679 (truncate/ 5 2)     @result{}  2    1
    680 (truncate/ -5 2)    @result{} -2   -1
    681 (truncate/ 5 -2)    @result{} -2    1
    682 (truncate/ -5 -2)   @result{}  2   -1
    683 (truncate/ -5.0 -2) @result{}  2.0 -1.0
    684 @end lisp
    685 
    686 @end deffn
    687 
    688 @deffn  procedure quotient n@sub{1} n@sub{2}
    689 @deffnx procedure remainder n@sub{1} n@sub{2}
    690 @deffnx procedure modulo n@sub{1} n@sub{2}
    691 
    692 The @code{quotient} and @code{remainder} procedures are equivalent to
    693 @code{truncate-quotient} and @code{truncate-remainder}, respectively,
    694 and @code{modulo} is equivalent to @code{floor-remainder}.
    695 
    696 Note: These procedures are provided for backward compatibility with
    697 earlier versions of this report.
    698 
    699 @end deffn
    700 
    701 @deffn  procedure gcd n@sub{1}@dots{}
    702 @deffnx procedure lcm n@sub{1}@dots{}
    703 
    704 These procedures return the greatest common divisor or least common
    705 multiple of their arguments. The result is always non-negative.
    706 
    707 @lisp
    708 (gcd 32 -36)   @result{} 4
    709 (gcd)          @result{} 0
    710 (lcm 32 -36)   @result{} 288
    711 (lcm 32.0 -36) @result{} 288.0  ; inexact
    712 (lcm)          @result{} 1
    713 @end lisp
    714 
    715 @end deffn
    716 
    717 @deffn  procedure numerator q
    718 @deffnx procedure denominator q
    719 
    720 These procedures return the numerator or denominator of their argument;
    721 the result is computed as if the argument was represented as a fraction
    722 in lowest terms. The denominator is always positive. The denominator of
    723 0 is defined to be 1.
    724 
    725 @lisp
    726 (numerator (/ 6 4))   @result{} 3
    727 (denominator (/ 6 4)) @result{} 2
    728 (denominator
    729   (inexact (/ 6 4)))  @result{} 2.0
    730 @end lisp
    731 
    732 @end deffn
    733 
    734 @deffn  procedure floor x
    735 @deffnx procedure ceiling x
    736 @deffnx procedure truncate x
    737 @deffnx procedure round x
    738 
    739 These procedures return integers.  The @code{floor} procedure returns the
    740 largest integer not larger than @var{x}.  The @code{ceiling} procedure
    741 returns the smallest integer not smaller than @var{x}, @code{truncate}
    742 returns the integer closest to @var{x} whose absolute value is not larger
    743 than the absolute value of @var{x}, and @code{round} returns the closest
    744 integer to @var{x}, rounding to even when @var{x} is halfway between
    745 two integers.
    746 
    747 @rationale{}
    748 
    749 The @code{round} procedure rounds to even for consistency with
    750 the default rounding mode specified by the IEEE 754 IEEE floating-point
    751 standard.
    752 
    753 Note: If the argument to one of these procedures is inexact, then the
    754 result will also be inexact. If an exact value is needed, the result can
    755 be passed to the @code{exact} procedure. If the argument is infinite or
    756 a NaN, then it is returned.
    757 
    758 @lisp
    759 (floor -4.3)          @result{} -5.0
    760 (ceiling -4.3)        @result{} -4.0
    761 (truncate -4.3)       @result{} -4.0
    762 (round -4.3)          @result{} -4.0
    763 
    764 (floor 3.5)           @result{} 3.0
    765 (ceiling 3.5)         @result{} 4.0
    766 (truncate 3.5)        @result{} 3.0
    767 (round 3.5)           @result{} 4.0  ; inexact
    768 
    769 (round 7/2)           @result{} 4    ; exact
    770 (round 7)             @result{} 7
    771 @end lisp
    772 
    773 @end deffn
    774 
    775 @deffn procedure rationalize x y
    776 
    777 @cindex simplest rational
    778 
    779 @c TODO: Math mode is probably overkill here. Use normal insertions?
    780 The @code{rationalize} procedure returns the @emph{simplest} rational
    781 number differing from @var{x} by no more than @var{y}. A rational
    782 number @var{r@sub{1}} is @emph{simpler} than another rational number
    783 @var{r@sub{2}} if @math{r_1 = p_1/q_1} and @math{r_2 = p_2/q_2} (in
    784 lowest terms) and @math{|p_1| \leq |p_2|} and @math{|q_1| \leq |q_2|}.
    785 Thus 3/5 is simpler than 4/7. Although not all rationals are comparable
    786 in this ordering (consider 2/7 and 3/5), any interval contains a
    787 rational number that is simpler than every other rational number in
    788 that interval (the simpler 2/5 lies between 2/7 and 3/5). Note that 0 =
    789 0/1 is the simplest rational of all.
    790 
    791 @lisp
    792 (rationalize (exact .3) 1/10) @result{} 1/3    ; exact
    793 (rationalize .3 1/10)         @result{} #i1/3  ; inexact
    794 @end lisp
    795 
    796 @end deffn
    797 
    798 @deffn  {inexact library procedure} exp z
    799 @deffnx {inexact library procedure} log z
    800 @deffnx {inexact library procedure} log z@sub{1} z@sub{2}
    801 @deffnx {inexact library procedure} sin z
    802 @deffnx {inexact library procedure} cos z
    803 @deffnx {inexact library procedure} tan z
    804 @deffnx {inexact library procedure} asin z
    805 @deffnx {inexact library procedure} acos z
    806 @deffnx {inexact library procedure} atan z
    807 @deffnx {inexact library procedure} atan y x
    808 
    809 These procedures compute the usual transcendental functions. The
    810 @code{log} procedure computes the natural logarithm of @var{z} (not the
    811 base ten logarithm) if a single argument is given, or the
    812 base-@var{z@sub{2}} logarithm of @var{z@sub{1}} if two arguments are
    813 given. The @code{asin}, @code{acos}, and @code{atan} procedures compute
    814 arcsine (sin@sup{@minus{}1}), arc-cosine (cos@sup{@minus{}1}), and
    815 arctangent (tan@sup{@minus{}1}), respectively. The two-argument variant
    816 of @code{atan} computes @code{(angle (make-rectangular @var{x}
    817 @var{y}))} (see below), even in implementations that don't support
    818 complex numbers.
    819 
    820 In general, the mathematical functions log, arcsine, arc-cosine, and
    821 arctangent are multiply defined. The value of log @var{z} is defined to
    822 be the one whose imaginary part lies in the range from @minus{}@greekpi
    823 (inclusive if @code{-0.0} is distinguished, exclusive otherwise) to
    824 @greekpi (inclusive). The value of log 0 is mathematically undefined.
    825 With log defined this way, the values of sin@sup{@minus{}1} @var{z},
    826 cos@sup{@minus{}1} @var{z}, and tan@sup{@minus{}1} @var{z} are
    827 according to the following formul@ae{}:
    828 
    829 @displaymath
    830 \sin^{-1} z = -i \log (i z + \sqrt{1 - z^2})
    831 @end displaymath
    832 
    833 @displaymath
    834 \cos^{-1} z = \pi / 2 - \sin^{-1} z
    835 @end displaymath
    836 
    837 @displaymath
    838 \tan^{-1} z = (\log (1 + i z) - \log (1 - i z)) / (2 i)
    839 @end displaymath
    840 
    841 However, @code{(log 0.0)} returns @code{-inf.0} (and @code{(log -0.0)}
    842 returns @code{-inf.0+@greekpi{}i}) if the implementation supports
    843 infinities (and @code{-0.0}).
    844 
    845 The range of @code{(atan }@var{y} @var{x}@code{)} is as in the
    846 following table. The asterisk (*) indicates that the entry applies to
    847 implementations that distinguish minus zero.
    848 
    849 @multitable @columnfractions .16 .24 .24 .36
    850 @headitem @tab @var{y} condition @tab @var{x} condition @tab
    851   range of result @var{r}
    852 @item @tab @var{y} = 0.0 @tab @var{x} > 0.0 @tab 0.0
    853 @item * @tab @var{y} = +0.0 @tab @var{x} > 0.0 @tab +0.0
    854 @item * @tab @var{y} = @minus{}0.0 @tab @var{x} > 0.0 @tab @minus{}0.0
    855 @item @tab @var{y} > 0.0 @tab @var{x} > 0.0 @tab
    856   0.0 < @var{r} < @greekpi/2
    857 @item @tab @var{y} > 0.0 @tab @var{x} = 0.0 @tab @greekpi/2
    858 @item @tab @var{y} > 0.0 @tab @var{x} < 0.0 @tab
    859   @greekpi/2 < @var{r} < @greekpi
    860 @item @tab @var{y} = 0.0 @tab @var{x} < 0 @tab @greekpi
    861 @item * @tab @var{y} = +0.0 @tab @var{x} < 0.0 @tab @greekpi
    862 @item * @tab @var{y} = @minus{}0.0 @tab @var{x} < 0.0 @tab
    863   @minus{}@greekpi
    864 @item @tab @var{y} < 0.0 @tab @var{x} < 0.0 @tab
    865   @minus{}@greekpi < @var{r} < @minus{}@greekpi/2
    866 @item @tab @var{y} < 0.0 @tab @var{x} = 0.0 @tab @minus{}@greekpi/2
    867 @item @tab @var{y} < 0.0 @tab @var{x} > 0.0 @tab
    868   @minus{}@greekpi/2 < @var{r}< 0.0
    869 @item @tab @var{y} = 0.0 @tab @var{x} = 0.0 @tab undefined
    870 @item * @tab @var{y} = +0.0 @tab @var{x} = +0.0 @tab +0.0
    871 @item * @tab @var{y} = @minus{}0.0 @tab @var{x} = +0.0 @tab @minus{}0.0
    872 @item * @tab @var{y} = +0.0 @tab @var{x} = @minus{}0.0 @tab @greekpi
    873 @item * @tab @var{y} = @minus{}0.0 @tab @var{x} = @minus{}0.0 @tab
    874   @minus{}@greekpi
    875 @item * @tab @var{y} = +0.0 @tab @var{x} = 0 @tab
    876   @greekpi/2
    877 @item * @tab @var{y} = @minus{}0.0 @tab @var{x} = 0 @tab
    878   @minus{}@greekpi/2
    879 @end multitable
    880 
    881 The above specification follows [@ref{CLtL}], which in turn cites [@ref{Penfield81}]; refer
    882 to these sources for more detailed discussion of branch cuts, boundary
    883 conditions, and implementation of these functions. When it is possible,
    884 these procedures produce a real result from a real argument.
    885 
    886 @end deffn
    887 
    888 @deffn procedure square z
    889 
    890 Returns the square of z. This is equivalent to
    891 @code{(* }@var{z} @var{z}@code{)}.
    892 
    893 @lisp
    894 (square 42)  @result{} 1764
    895 (square 2.0) @result{} 4.0
    896 @end lisp
    897 
    898 @end deffn
    899 
    900 @deffn {inexact library procedure} sqrt z
    901 
    902 Returns the principal square root of @var{z}. The result will have
    903 either a positive real part, or a zero real part and a non-negative
    904 imaginary part.
    905 
    906 @lisp
    907 (sqrt 9)  @result{} 3
    908 (sqrt -1) @result{} +i
    909 @end lisp
    910 
    911 @end deffn
    912 
    913 @deffn procedure exact-integer-sqrt k
    914 
    915 Returns two non-negative exact integers @var{s} and @var{r} where
    916 @var{k} = @var{s}@sup{2} + @var{r} and @var{k} < (@var{s} + 1)@sup{2}.
    917 
    918 @lisp
    919 (exact-integer-sqrt 4) @result{} 2 0
    920 (exact-integer-sqrt 5) @result{} 2 1
    921 @end lisp
    922 
    923 @end deffn
    924 
    925 @deffn procedure expt z@sub{1} z@sub{2}
    926 
    927 Returns z@sub{1} raised to the power z@sub{2}. For nonzero
    928 z@sub{1}, this is
    929 
    930 @displaymath
    931 {z_1}^{z_2} = e^{z_2 \log {z_1}}
    932 @end displaymath
    933 
    934 The value of 0@sup{@var{z}} is 1 if @code{(zero? }@var{z}@code{)}, 0 if
    935 @code{(real-part }@var{z}@code{)} is positive, and an error otherwise.
    936 Similarly for 0.0@sup{@var{z}}, with inexact results.
    937 
    938 @end deffn
    939 
    940 @deffn  {complex library procedure} make-rectangular x@sub{1} x@sub{2}
    941 @deffnx {complex library procedure} make-polar x@sub{3} x@sub{4}
    942 @deffnx {complex library procedure} real-part z
    943 @deffnx {complex library procedure} imag-part z
    944 @deffnx {complex library procedure} magnitude z
    945 @deffnx {complex library procedure} angle z
    946 
    947 Let @var{x@sub{1}}, @var{x@sub{2}}, @var{x@sub{3}}, and @var{x@sub{4}}
    948 be real numbers and @var{z} be a complex number such that
    949 
    950 @displaymath
    951 z = x_1 + x_{2}i = x_3 \cdot e^{i x_4}
    952 @end displaymath
    953 
    954 Then all of
    955 
    956 @lisp
    957 (make-rectangular @r{@var{x@sub{1}} @var{x@sub{2}}}) @result{} z
    958 (make-polar @r{@var{x@sub{3}} @var{x@sub{4}}})       @result{} z
    959 (real-part @r{@var{z}})                  @result{} @r{@var{x@sub{1}}}
    960 (imag-part @r{@var{z}})                  @result{} @r{@var{x@sub{2}}}
    961 (magnitude @r{@var{z}})                  @result{} |@r{@var{x@sub{3}}}|
    962 (angle @r{@var{z}})                      @result{} @r{@var{x}@sub{angle}}
    963 @end lisp
    964 
    965 are true, where @minus{}@greekpi{} @leq{} @var{x@sub{angle}} @leq{}
    966 @greekpi{} with @var{x@sub{angle}} = @var{x@sub{4}} + 2@greekpi{}@var{n}
    967 for some integer @var{n}.
    968 
    969 The @code{make-polar} procedure may return an inexact complex
    970 number even if its arguments are exact. The @code{real-part} and
    971 @code{imag-part} procedures may return exact real numbers when applied
    972 to an inexact complex number if the corresponding argument passed to
    973 @code{make-rectangular} was exact.
    974 
    975 The @code{magnitude} procedure is the same as @code{abs} for a real
    976 argument, but @code{abs} is in the base library, whereas @code{magnitude}
    977 is in the optional complex library.
    978 
    979 @end deffn
    980 
    981 @deffn  procedure inexact z
    982 @deffnx procedure exact z
    983 
    984 The procedure @code{inexact} returns an inexact representation of @var{z}.
    985 The value returned is the inexact number that is numerically closest
    986 to the argument.  For inexact arguments, the result is the same as the
    987 argument. For exact complex numbers, the result is a complex number
    988 whose real and imaginary parts are the result of applying @code{inexact}
    989 to the real and imaginary parts of the argument, respectively.  If an
    990 exact argument has no reasonably close inexact equivalent (in the sense
    991 of @code{=}), then a violation of an implementation restriction may
    992 be reported.
    993 
    994 The procedure @code{exact} returns an exact representation of @var{z}. The
    995 value returned is the exact number that is numerically closest to
    996 the argument.  For exact arguments, the result is the same as the
    997 argument. For inexact non-integral real arguments, the implementation
    998 may return a rational approximation, or may report an implementation
    999 violation. For inexact complex arguments, the result is a complex number
   1000 whose real and imaginary parts are the result of applying @code{exact}
   1001 to the real and imaginary parts of the argument, respectively.  If an
   1002 inexact argument has no reasonably close exact equivalent, (in the
   1003 sense of @code{=}), then a violation of an implementation restriction
   1004 may be reported.
   1005 
   1006 These procedures implement the natural one-to-one correspondence between
   1007 exact and inexact integers throughout an implementation-dependent
   1008 range. @xref{Implementation restrictions}.
   1009 
   1010 Note: These procedures were known in @rfivers{} as @code{exact->inexact}
   1011 and @code{inexact->exact}, respectively, but they have always accepted
   1012 arguments of any exactness.  The new names are clearer and shorter,
   1013 as well as being compatible with @rsixrs{}.
   1014 
   1015 @end deffn
   1016 
   1017 @node Numerical input and output
   1018 @subsection Numerical input and output
   1019 
   1020 @deffn  procedure number->string z
   1021 @deffnx procedure number->string z radix
   1022 
   1023 It is an error if
   1024 @var{radix} is not one of 2, 8, 10, or 16.
   1025 
   1026 The procedure @code{number->string} takes a number and a radix and
   1027 returns as a string an external representation of the given number in
   1028 the given radix such that
   1029 
   1030 @lisp
   1031 (let ((number number)
   1032       (radix radix))
   1033   (eqv? number
   1034         (string->number (number->string number
   1035                                         radix)
   1036                         radix)))
   1037 @end lisp
   1038 
   1039 is true. It is an error if no possible result makes this expression
   1040 true. If omitted, @var{radix} defaults to 10.
   1041 
   1042 If @var{z} is inexact, the radix is 10, and the above expression can be
   1043 satisfied by a result that contains a decimal point, then the result
   1044 contains a decimal point and is expressed using the minimum number
   1045 of digits (exclusive of exponent and trailing zeroes) needed to make
   1046 the above expression true [@ref{howtoprint}, @ref{howtoread}]; otherwise the format of the result
   1047 is unspecified.
   1048 
   1049 The result returned by @code{number->string} never contains an explicit
   1050 radix prefix.
   1051 
   1052 Note: The error case can occur only when @var{z} is not a complex number
   1053 or is a complex number with a non-rational real or imaginary part.
   1054 
   1055 @rationale{}
   1056 
   1057 If @var{z} is an inexact number and the radix is 10, then
   1058 the above expression is normally satisfied by a result containing a
   1059 decimal point. The unspecified case allows for infinities, NaNs, and
   1060 unusual representations.
   1061 
   1062 @end deffn
   1063 
   1064 @deffn  procedure string->number string
   1065 @deffnx procedure string->number string radix
   1066 
   1067 Returns a number of the maximally precise representation expressed by the
   1068 given @var{string}.  It is an error if @var{radix} is not 2, 8, 10, or 16.
   1069 
   1070 If supplied, @var{radix} is a default radix that will be overridden if an
   1071 explicit radix prefix is present in string (e.g.@: @code{"#o177"}). If
   1072 @var{radix} is not supplied, then the default radix is 10. If
   1073 @var{string} is not a syntactically valid notation for a number, or
   1074 would result in a number that the implementation cannot represent, then
   1075 @code{string->number} returns @code{#f}. An error is never signaled due
   1076 to the content of @var{string}.
   1077 
   1078 @lisp
   1079 (string->number "100")    @result{} 100
   1080 (string->number "100" 16) @result{} 256
   1081 (string->number "1e2")    @result{} 100.0
   1082 @end lisp
   1083 
   1084 Note: The domain of @code{string->number} may be restricted by
   1085 implementations in the following ways.  If all numbers supported by an
   1086 implementation are real, then @code{string->number} is permitted to
   1087 return @code{#f} whenever @var{string} uses the polar or rectangular
   1088 notations for complex numbers. If all numbers are integers, then
   1089 @code{string->number} may return @code{#f} whenever the fractional
   1090 notation is used. If all numbers are exact, then @code{string->number} may
   1091 return @code{#f} whenever an exponent marker or explicit exactness prefix
   1092 is used.  If all inexact numbers are integers, then @code{string->number}
   1093 may return @code{#f} whenever a decimal point is used.
   1094 
   1095 The rules used by a particular implementation for @code{string->number}
   1096 must also be applied to @code{read} and to the routine that reads
   1097 programs, in order to maintain consistency between internal numeric
   1098 processing, I/O, and the processing of programs.  As a consequence,
   1099 the @rfivers{} permission to return @code{#f} when @var{string} has an
   1100 explicit radix prefix has been withdrawn.
   1101 
   1102 @end deffn