---

6.2.6 Numerical operations ¶

The reader is referred to section 1.3.3 (Entry format) for a summary of the naming conventions used to specify restrictions on the types of arguments to numerical routines. The examples used in this section assume that any numerical constant written using an exact notation is indeed represented as an exact number. Some examples also assume that certain numerical constants written using an inexact notation can be represented without loss of accuracy; the inexact constants were chosen so that this is likely to be true in implementations that use IEEE binary doubles to represent inexact numbers.

procedure: (number? obj) ¶

procedure: (complex? obj) ¶

procedure: (real? obj) ¶

procedure: (rational? obj) ¶

procedure: (integer? obj) ¶

These numerical type predicates can be applied to any kind of argument, including non-numbers. They return #t if the object is of the named type, and otherwise they return #f. In general, if a type predicate is true of a number then all higher type predicates are also true of that number. Consequently, if a type predicate is false of a number, then all lower type predicates are also false of that number.

If z is a complex number, then (real? z) is true if and only if (zero? (imag-part z)) is true. If x is an inexact real number, then (integer? x) is true if and only if (= x (round x)).

The numbers +inf.0, -inf.0, and +nan.0 are real but not rational.

(complex? 3+4i)    ⇒ #t
(complex? 3)       ⇒ #t
(real? 3)          ⇒ #t
(real? -2.5+0i)    ⇒ #t
(real? -2.5+0.0i)  ⇒ #f
(real? #e1e10)     ⇒ #t
(real? +inf.0)     ⇒ #t
(real? +nan.0)     ⇒ #t
(rational? -inf.0) ⇒ #f
(rational? 3.5)    ⇒ #t
(rational? 6/10)   ⇒ #t
(rational? 6/3)    ⇒ #t
(integer? 3+0i)    ⇒ #t
(integer? 3.0)     ⇒ #t
(integer? 8/4)     ⇒ #t

Note: The behavior of these type predicates on inexact numbers is unreliable, since any inaccuracy might affect the result.

Note: In many implementations the complex? procedure will be the same as number?, but unusual implementations may represent some irrational numbers exactly or may extend the number system to support some kind of non-complex numbers.

procedure: (exact? z) ¶

procedure: (inexact? z) ¶

These numerical predicates provide tests for the exactness of a quantity. For any Scheme number, precisely one of these predicates is true.

(exact? 3.0)   ⇒ #f
(exact? #e3.0) ⇒ #t
(inexact? 3.)  ⇒ #t

procedure: (exact-integer? z) ¶

Returns #t if z is both exact and an integer; otherwise returns #f.

(exact-integer? 32)   ⇒ #t
(exact-integer? 32.0) ⇒ #f
(exact-integer? 32/5) ⇒ #f

inexact library procedure: (finite? z) ¶

The finite? procedure returns #t on all real numbers except +inf.0, -inf.0, and +nan.0, and on complex numbers if their real and imaginary parts are both finite. Otherwise it returns #f.

(finite? 3)          ⇒ #t
(finite? +inf.0)     ⇒ #f
(finite? 3.0+inf.0i) ⇒ #f

inexact library procedure: (infinite? z) ¶

The infinite? procedure returns #t on the real numbers +inf.0 and -inf.0, and on complex numbers if their real or imaginary parts or both are infinite. Otherwise it returns #f.

(infinite? 3)          ⇒ #f
(infinite? +inf.0)     ⇒ #t
(infinite? +nan.0)     ⇒ #f
(infinite? 3.0+inf.0i) ⇒ #t

inexact library procedure: (nan? z) ¶

The nan? procedure returns #t on +nan.0, and on complex numbers if their real or imaginary parts or both are +nan.0. Otherwise it returns #f.

(nan? +nan.0)      ⇒ #t
(nan? 32)          ⇒ #f
(nan? +nan.0+5.0i) ⇒ #t
(nan? 1+2i)        ⇒ #f

procedure: (= z₁ z₂ z₃ …) ¶

procedure: (< x₁ x₂ x₃ …) ¶

procedure: (> x₁ x₂ x₃ …) ¶

procedure: (<= x₁ x₂ x₃ …) ¶

procedure: (>= x₁ x₂ x₃ …) ¶

These procedures return #t if their arguments are (respectively): equal, monotonically increasing, monotonically decreasing, monotonically non-decreasing, or monotonically non-increasing, and #f otherwise. If any of the arguments are +nan.0, all the predicates return #f. They do not distinguish between inexact zero and inexact negative zero.

These predicates are required to be transitive.

Note: The implementation approach of converting all arguments to inexact numbers if any argument is inexact is not transitive. For example, let big be (expt 2 1000), and assume that big is exact and that inexact numbers are represented by 64-bit IEEE binary floating point numbers. Then (= (- big 1) (inexact big)) and (= (inexact big) (+ big 1)) would both be true with this approach, because of the limitations of IEEE representations of large integers, whereas (= (- big 1) (+ big 1)) is false. Converting inexact values to exact numbers that are the same (in the sense of =) to them will avoid this problem, though special care must be taken with infinities.

Note: While it is not an error to compare inexact numbers using these predicates, the results are unreliable because a small inaccuracy can affect the result; this is especially true of = and zero?. When in doubt, consult a numerical analyst.

procedure: (zero? z) ¶

procedure: (positive? x) ¶

procedure: (negative? x) ¶

procedure: (odd? n) ¶

procedure: (even? n) ¶

These numerical predicates test a number for a particular property, returning #t or #f. See note above.

procedure: (max x₁ x₂ …) ¶

procedure: (min x₁ x₂ …) ¶

These procedures return the maximum or minimum of their arguments.

(max 3 4)   ⇒ 4    ; exact
(max 3.9 4) ⇒ 4.0  ; inexact

Note: If any argument is inexact, then the result will also be inexact (unless the procedure can prove that the inaccuracy is not large enough to affect the result, which is possible only in unusual implementations). If min or max is used to compare numbers of mixed exactness, and the numerical value of the result cannot be represented as an inexact number without loss of accuracy, then the procedure may report a violation of an implementation restriction.

procedure: (+ z₁ …) ¶

procedure: (* z₁ …) ¶

These procedures return the sum or product of their arguments.

(+ 3 4) ⇒ 7
(+ 3)   ⇒ 3
(+)     ⇒ 0
(* 4)   ⇒ 4
(*)     ⇒ 1

procedure: (- z) ¶

procedure: (- z₁ z₂ …) ¶

procedure: (/ z) ¶

procedure: (/ z₁ z₂ …) ¶

With two or more arguments, these procedures return the difference or quotient of their arguments, associating to the left. With one argument, however, they return the additive or multiplicative inverse of their argument.

It is an error if any argument of / other than the first is an exact zero. If the first argument is an exact zero, an implementation may return an exact zero unless one of the other arguments is a NaN.

(- 3 4)   ⇒ -1
(- 3 4 5) ⇒ -6
(- 3)     ⇒ -3
(/ 3 4 5) ⇒ 3/20
(/ 3)     ⇒ 1/3

procedure: (abs x) ¶

The abs procedure returns the absolute value of its argument.

(abs -7) ⇒ 7

procedure: (floor/ n₁ n₂) ¶

procedure: (floor-quotient n₁ n₂) ¶

procedure: (floor-remainder n₁ n₂) ¶

procedure: (truncate/ n₁ n₂) ¶

procedure: (truncate-quotient n₁ n₂) ¶

procedure: (truncate-remainder n₁ n₂) ¶

These procedures implement number-theoretic (integer) division. It is an error if n is zero. The procedures ending in ‘/’ return two integers; the other procedures return an integer. All the procedures compute a quotient $n_q$ and remainder $n_r$ such that $n_1=n_2{n}_q+n_r$. For each of the division operators, there are three procedures defined as follows:

(⟨operator⟩/ n1 n2)          ⇒ $n_q$ $n_r$
(⟨operator⟩-quotient n1 n2)  ⇒ $n_q$
(⟨operator⟩-remainder n1 n2) ⇒ $n_r$

The remainder $n_r$ is determined by the choice of integer $n_q$: $n_r=n_1-n_2{n}_q$. Each set of operators uses a different choice of $n_q$:

$\begin{array}{lll}\mathrm{floor}& & n_q=\lfloor n_1∕n_2\rfloor \\ \mathrm{truncate}& & n_q=\mathrm{truncate}(n_1∕n_2)\end{array}$

For any of the operators, and for integers n₁ and n₂ with n₂ not equal to 0,

(= n1 (+ (* n2 (⟨operator⟩-quotient n1 n2))
      (⟨operator⟩-remainder n1 n2)))        ⇒ #t

provided all numbers involved in that computation are exact.

Examples:

(floor/ 5 2)        ⇒ 2    1
(floor/ -5 2)       ⇒ 3    1
(floor/ 5 -2)       ⇒ 3   -1
(floor/ -5 -2)      ⇒ 2   -1
(truncate/ 5 2)     ⇒ 2    1
(truncate/ -5 2)    ⇒ 2   -1
(truncate/ 5 -2)    ⇒ 2    1
(truncate/ -5 -2)   ⇒ 2   -1
(truncate/ -5.0 -2) ⇒ 2.0 -1.0

procedure: (quotient n₁ n₂) ¶

procedure: (remainder n₁ n₂) ¶

procedure: (modulo n₁ n₂) ¶

The quotient and remainder procedures are equivalent to truncate-quotient and truncate-remainder, respectively, and modulo is equivalent to floor-remainder.

Note: These procedures are provided for backward compatibility with earlier versions of this report.

procedure: (gcd n₁ …) ¶

procedure: (lcm n₁ …) ¶

These procedures return the greatest common divisor or least common multiple of their arguments. The result is always non-negative.

(gcd 32 -36)   ⇒ 4
(gcd)          ⇒ 0
(lcm 32 -36)   ⇒ 288
(lcm 32.0 -36) ⇒ 288.0  ; inexact
(lcm)          ⇒ 1

procedure: (numerator q) ¶

procedure: (denominator q) ¶

These procedures return the numerator or denominator of their argument; the result is computed as if the argument was represented as a fraction in lowest terms. The denominator is always positive. The denominator of 0 is defined to be 1.

(numerator (/ 6 4))   ⇒ 3
(denominator (/ 6 4)) ⇒ 2
(denominator
  (inexact (/ 6 4)))  ⇒ 2.0

procedure: (floor x) ¶

procedure: (ceiling x) ¶

procedure: (truncate x) ¶

procedure: (round x) ¶

These procedures return integers. The floor procedure returns the largest integer not larger than x. The ceiling procedure returns the smallest integer not smaller than x, truncate returns the integer closest to x whose absolute value is not larger than the absolute value of x, and round returns the closest integer to x, rounding to even when x is halfway between two integers.

Rationale: The round procedure rounds to even for consistency with the default rounding mode specified by the IEEE 754 IEEE floating-point standard.

Note: If the argument to one of these procedures is inexact, then the result will also be inexact. If an exact value is needed, the result can be passed to the exact procedure. If the argument is infinite or a NaN, then it is returned.

(floor -4.3)          ⇒ -5.0
(ceiling -4.3)        ⇒ -4.0
(truncate -4.3)       ⇒ -4.0
(round -4.3)          ⇒ -4.0

(floor 3.5)           ⇒ 3.0
(ceiling 3.5)         ⇒ 4.0
(truncate 3.5)        ⇒ 3.0
(round 3.5)           ⇒ 4.0  ; inexact

(round 7/2)           ⇒ 4    ; exact
(round 7)             ⇒ 7

procedure: (rationalize x y) ¶

The rationalize procedure returns the simplest rational number differing from x by no more than y. A rational number r₁ is simpler than another rational number r₂ if r₁ = p₁q₁ and r₂ = p₂q₂ (in lowest terms) and |p₁| ≤ |p₂| and |q₁| ≤ |q₂|. Thus 3$∕$5 is simpler than 4$∕$7. Although not all rationals are comparable in this ordering (consider 2$∕$7 and 3$∕$5), any interval contains a rational number that is simpler than every other rational number in that interval (the simpler 2$∕$5 lies between 2$∕$7 and 3$∕$5). Note that 0 = 0$∕$1 is the simplest rational of all.

(rationalize (exact .3) 1/10) ⇒ 1/3    ; exact
(rationalize .3 1/10)         ⇒ #i1/3  ; inexact

inexact library procedure: (exp z) ¶

inexact library procedure: (log z) ¶

inexact library procedure: (log z₁ z₂) ¶

inexact library procedure: (sin z) ¶

inexact library procedure: (cos z) ¶

inexact library procedure: (tan z) ¶

inexact library procedure: (asin z) ¶

inexact library procedure: (acos z) ¶

inexact library procedure: (atan z) ¶

inexact library procedure: (atan y x) ¶

These procedures compute the usual transcendental functions. The log procedure computes the natural logarithm of z (not the base ten logarithm) if a single argument is given, or the base-z₂ logarithm of z₁ if two arguments are given. The asin, acos, and atan procedures compute arcsine (${\sin }^{-1}$), arc-cosine (${\cos }^{-1}$), and arctangent (${\tan }^{-1}$), respectively. The two-argument variant of atan computes (angle (make-rectangular x y)) (see below), even in implementations that don’t support complex numbers.

In general, the mathematical functions log, arcsine, arc-cosine, and arctangent are multiply defined. The value of $\log z$ is defined to be the one whose imaginary part lies in the range from −$\pi$ (inclusive if -0.0 is distinguished, exclusive otherwise) to $\pi$ (inclusive). The value of $\log 0$ is mathematically undefined. With log defined this way, the values of ${\sin }^{-1}z$, ${\cos }^{-1}z$, and ${\tan }^{-1}z$ are according to the following formulæ:

$$\begin{array}{c}{\sin }^{-1}z=-i\log (iz+\sqrt{1-z^2})\\ {\cos }^{-1}z=\frac{\pi }{2}-{\sin }^{-1}z\\ {\tan }^{-1}z=\frac{\log (1+iz)-\log (1-iz)}{2i}\end{array}$$

However, (log 0.0) returns -inf.0 (and (log -0.0) returns -inf.0+$\pi$i) if the implementation supports infinities (and -0.0).

The range of (atan y x) is as in the following table. The asterisk (‘$*$’) indicates that the entry applies to implementations that distinguish minus zero.

$\begin{array}{cccc}& y\text{condition}& x\text{condition}& \text{range of result}r\\ & y=0.0\hfill & x>0.0\hfill & 0.0\\ *& y=+0.0\hfill & x>0.0\hfill & +0.0\\ *& y=-0.0\hfill & x>0.0\hfill & -0.0\\ & y>0.0\hfill & x>0.0\hfill & 0.0<r<\frac{\pi }{2}\\ & y>0.0\hfill & x=0.0\hfill & \frac{\pi }{2}\\ & y>0.0\hfill & x<0.0\hfill & \frac{\pi }{2}<r<\pi \\ & y=0.0\hfill & x<0\hfill & \pi \\ *& y=+0.0\hfill & x<0.0\hfill & \pi \\ *& y=-0.0\hfill & x<0.0\hfill & -\pi \\ & y<0.0\hfill & x<0.0\hfill & -\pi <r<-\frac{\pi }{2}\\ & y<0.0\hfill & x=0.0\hfill & -\frac{\pi }{2}\\ & y<0.0\hfill & x>0.0\hfill & -\frac{\pi }{2}<r<0.0\\ & y=0.0\hfill & x=0.0\hfill & \mathrm{undefined}\\ *& y=+0.0\hfill & x=+0.0\hfill & +0.0\\ *& y=-0.0\hfill & x=+0.0\hfill & -0.0\\ *& y=+0.0\hfill & x=-0.0\hfill & \pi \\ *& y=-0.0\hfill & x=-0.0\hfill & -\pi \\ *& y=+0.0\hfill & x=0\hfill & \frac{\pi }{2}\\ *& y=-0.0\hfill & x=0\hfill & -\frac{\pi }{2}\end{array}$

The above specification follows Common LISP: The Language, second edition³², which in turn cites Principal values and branch cuts in complex APL³³; refer to these sources for more detailed discussion of branch cuts, boundary conditions, and implementation of these functions. When it is possible, these procedures produce a real result from a real argument.

procedure: (square z) ¶

Returns the square of z. This is equivalent to (* z z).

(square 42)  ⇒ 1764
(square 2.0) ⇒ 4.0

inexact library procedure: (sqrt z) ¶

Returns the principal square root of z. The result will have either a positive real part, or a zero real part and a non-negative imaginary part.

(sqrt 9)  ⇒ 3
(sqrt -1) ⇒ +i

procedure: (exact-integer-sqrt k) ¶

Returns two non-negative exact integers s and r where

$$k=s^2+r\mathrm{and}k<{(s+1)}^2$$

(exact-integer-sqrt 4) ⇒ 2 0
(exact-integer-sqrt 5) ⇒ 2 1

procedure: (expt z₁ z₂) ¶

Returns z₁ raised to the power z₂. For nonzero z₁, this is

$${z_1}^{z_2}=e^{z_2\log z_1}$$

The value of 0^z is 1 if (zero? z), 0 if (real-part z) is positive, and an error otherwise. Similarly for 0.0^z, with inexact results.

complex library procedure: (make-rectangular x₁ x₂) ¶

complex library procedure: (make-polar x₃ x₄) ¶

complex library procedure: (real-part z) ¶

complex library procedure: (imag-part z) ¶

complex library procedure: (magnitude z) ¶

complex library procedure: (angle z) ¶

Let x₁, x₂, x₃, and x₄ be real numbers and z be a complex number such that

$$z=x_1+x_{2}i=x_3\cdot e^{i{x}_4}$$

Then all of

(make-rectangular x1 x2)	⇒ z
(make-polar x1 x2)	⇒ z
(real-part z)	⇒ x1
(imag-part z)	⇒ x2
(magnitude z)	⇒ |x3|
(angle z)	⇒ xangle

are true, where −$\pi$ ≤ x_angle ≤ $\pi$ with x_angle = x₄ + $2\pi n$ for some integer $n$.

The make-polar procedure may return an inexact complex number even if its arguments are exact. The real-part and imag-part procedures may return exact real numbers when applied to an inexact complex number if the corresponding argument passed to make-rectangular was exact.

The magnitude procedure is the same as abs for a real argument, but abs is in the base library, whereas magnitude is in the optional complex library.

procedure: (inexact z) ¶

procedure: (exact z) ¶

The procedure inexact returns an inexact representation of z. The value returned is the inexact number that is numerically closest to the argument. For inexact arguments, the result is the same as the argument. For exact complex numbers, the result is a complex number whose real and imaginary parts are the result of applying inexact to the real and imaginary parts of the argument, respectively. If an exact argument has no reasonably close inexact equivalent (in the sense of =), then a violation of an implementation restriction may be reported.

The procedure exact returns an exact representation of z. The value returned is the exact number that is numerically closest to the argument. For exact arguments, the result is the same as the argument. For inexact non-integral real arguments, the implementation may return a rational approximation, or may report an implementation violation. For inexact complex arguments, the result is a complex number whose real and imaginary parts are the result of applying exact to the real and imaginary parts of the argument, respectively. If an inexact argument has no reasonably close exact equivalent, (in the sense of =), then a violation of an implementation restriction may be reported.

These procedures implement the natural one-to-one correspondence between exact and inexact integers throughout an implementation-dependent range. See Implementation restrictions.

Note: These procedures were known in R⁵RS as exact->inexact and inexact->exact, respectively, but they have always accepted arguments of any exactness. The new names are clearer and shorter, as well as being compatible with R⁶RS.