Arithmetic operations

Procedure: real-valued? obj

Procedure: rational-valued? obj

Procedure: integer-valued? obj

These numerical type predicates can be applied to any kind of argument. The real-valued? procedure returns #t if the object is a number object and is equal in the sense of = to some real number object, or if the object is a NaN, or a complex number object whose real part is a NaN and whose imaginary part is zero in the sense of zero?. The rational-valued? and integer-valued? procedures return #t if the object is a number object and is equal in the sense of = to some object of the named type, and otherwise they return #f.

(real-valued? +nan.0)                  ⇒ #t
(real-valued? +nan.0+0i)               ⇒ #t
(real-valued? -inf.0)                  ⇒ #t
(real-valued? 3)                       ⇒ #t
(real-valued? -2.5+0.0i)               ⇒ #t

(real-valued? -2.5+0i)                 ⇒ #t
(real-valued? -2.5)                    ⇒ #t
(real-valued? #e1e10)                  ⇒ #t

(rational-valued? +nan.0)              ⇒ #f
(rational-valued? -inf.0)              ⇒ #f
(rational-valued? 6/10)                ⇒ #t
(rational-valued? 6/10+0.0i)           ⇒ #t
(rational-valued? 6/10+0i)             ⇒ #t
(rational-valued? 6/3)                 ⇒ #t

(integer-valued? 3+0i)                 ⇒ #t
(integer-valued? 3+0.0i)               ⇒ #t
(integer-valued? 3.0)                  ⇒ #t
(integer-valued? 3.0+0.0i)             ⇒ #t
(integer-valued? 8/4)                  ⇒ #t

Note: These procedures test whether a given number object can be coerced to the specified type without loss of numerical accuracy. Specifically, the behavior of these predicates differs from the behavior of real?, rational?, and integer? on complex number objects whose imaginary part is inexact zero.

Note: The behavior of these type predicates on inexact number objects is unreliable, because any inaccuracy may affect the result.

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)                  ⇒ #t
(exact-integer? 32/5)                  ⇒ #f

Procedure: finite? z

Returns #t if z is finite real number (i.e. an infinity and not a NaN), or if z is a complex number whose real and imaginary parts are both finite.

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

Procedure: infinite? z

Return #t if z is an infinite real number (+int.0 or -inf.0), or if z is a complex number where either real or imaginary parts or both are infinite.

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

Procedure: nan? z

For a real numer returns whether its is a NaN; for a complex number if the real or imaginary parts or both is a NaN.

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

Procedure: + z

Procedure: * z

These procedures return the sum or product of their arguments.

(+ 3 4)                          ⇒  7
(+ 3)                            ⇒  3
(+)                              ⇒  0
(+ +inf.0 +inf.0)                ⇒  +inf.0
(+ +inf.0 -inf.0)                ⇒  +nan.0

(* 4)                            ⇒  4
(*)                              ⇒  1
(* 5 +inf.0)                     ⇒  +inf.0
(* -5 +inf.0)                    ⇒  -inf.0
(* +inf.0 +inf.0)                ⇒  +inf.0
(* +inf.0 -inf.0)                ⇒  -inf.0
(* 0 +inf.0)                     ⇒  +nan.0
(* 0 +nan.0)                     ⇒  +nan.0
(* 1.0 0)                        ⇒  0.0

For any real number object x that is neither infinite nor NaN:

(+ +inf.0 x)                   ⇒  +inf.0
(+ -inf.0 x)                   ⇒  -inf.0

For any real number object x:

(+ +nan.0 x)                   ⇒  +nan.0

For any real number object x that is not an exact 0:

(* +nan.0 x)                   ⇒  +nan.0

The behavior of -0.0 is illustrated by the following examples:

(+  0.0 -0.0)  ⇒  0.0
(+ -0.0  0.0)  ⇒  0.0
(+  0.0  0.0)  ⇒  0.0
(+ -0.0 -0.0)  ⇒ -0.0

Procedure: - z

Procedure: - z1 z2 z3

With two or more arguments, this procedures returns the difference of its arguments, associating to the left. With one argument, however, it returns the negation (additive inverse) of its argument.

(- 3 4)                               ⇒  -1
(- 3 4 5)                             ⇒  -6
(- 3)                                 ⇒  -3
(- +inf.0 +inf.0)                     ⇒  +nan.0

The behavior of -0.0 is illustrated by the following examples:

(-  0.0)       ⇒ -0.0
(- -0.0)       ⇒  0.0
(-  0.0 -0.0)  ⇒  0.0
(- -0.0  0.0)  ⇒ -0.0
(-  0.0  0.0)  ⇒  0.0
(- -0.0 -0.0)  ⇒  0.0

Procedure: / z

Procedure: / z1 z2 z3

If all of the arguments are exact, then the divisors must all be nonzero. With two or more arguments, this procedure returns the quotient of its arguments, associating to the left. With one argument, however, it returns the multiplicative inverse of its argument.

(/ 3 4 5)                         ⇒  3/20
(/ 3)                             ⇒  1/3
(/ 0.0)                           ⇒  +inf.0
(/ 1.0 0)                         ⇒  +inf.0
(/ -1 0.0)                        ⇒  -inf.0
(/ +inf.0)                        ⇒  0.0
(/ 0 0)                           ⇒  exception &assertion
(/ 3 0)                           ⇒  exception &assertion
(/ 0 3.5)                         ⇒  0.0
(/ 0 0.0)                         ⇒  +nan.0
(/ 0.0 0)                         ⇒  +nan.0
(/ 0.0 0.0)                       ⇒  +nan.0

If this procedure is applied to mixed non–rational real and non–real complex arguments, it either raises an exception with condition type &implementation-restriction or returns an unspecified number object.

Procedure: floor/ x y

Procedure: truncate/ x y

Procedure: div-and-mod x y

Procedure: div0-and-mod0 x y

These procedures implement number–theoretic integer division. They accept two real numbers x and y as operands, where y must be nonzero. In all cases the result is two values q (an integer) and r (a real) that satisfy the equations:

x = q * y + r
q = rounding-op(x/y)

The result is inexact if either argument is inexact.

For floor/ the rounding-op is the floor function (below).

(floor/ 123 10)         ⇒  12 3
(floor/ 123 -10)        ⇒  -13 -7
(floor/ -123 10)        ⇒  -13 7
(floor/ -123 -10)       ⇒  12 -3

For truncate/ the rounding-op is the truncate function.

(truncate/ 123 10)      ⇒  12 3
(truncate/ 123 -10)     ⇒  -12 3
(truncate/ -123 10)     ⇒  -12 -3
(truncate/ -123 -10)    ⇒  12 -3

For div-and-mod the rounding-op is either floor (if y is positive) or ceiling (if y is negative). We have:

0  <= r < |y|
(div-and-mod 123 10)    ⇒  12 3
(div-and-mod 123 -10)   ⇒  -12 3
(div-and-mod -123 10)   ⇒  -13 7
(div-and-mod -123 -10)  ⇒  13 7

For div0-and-mod0 the rounding-op is the round function, and r lies within a half–open interval centered on zero.

-|y/2| <= r < |y/2|
(div0-and-mod0 123 10)   ⇒  12 3
(div0-and-mod0 123 -10)  ⇒  -12 3
(div0-and-mod0 -123 10)  ⇒  -12 -3
(div0-and-mod0 -123 -10) ⇒  12 -3
(div0-and-mod0 127 10)   ⇒  13 -3
(div0-and-mod0 127 -10)  ⇒  -13 -3
(div0-and-mod0 -127 10)  ⇒  -13 3
(div0-and-mod0 -127 -10) ⇒  13 3

The inconsistent naming is for historical reasons: div-and-mod and div0-and-mod0 are from R6RS, while floor/ and truncate/ are from R7RS.

Procedure: floor-quotient x y

Procedure: truncate-quotient x y

Procedure: div x y

Procedure: div0 x y

These procedures return the quotient part (first value) of respectively floor/, truncate/, div-and-mod, and div0-and-mod0.

Procedure: floor-remainder x y

Procedure: truncate-remainder x y

Procedure: mod x y

Procedure: mod0 x y

These procedures return the remainder part (second value) of respectively floor/, truncate/, div-and-mod, and div0-and-mod0.

As a Kawa extension y may be zero, in which case the result is x:

(mod 123 0)     ⇒  123 ;; Kawa extension

Procedure: quotient x y

Procedure: remainder x y

Procedure: modulo x y

These are equivalent to truncate-quotient, truncate-remainder, and floor-remainder, respectively. These are provided for backward compatibility.

(remainder 13 4)     ⇒ 1
(remainder -13 4)    ⇒ -1
(remainder 13 -4)    ⇒ 1
(remainder -13 -4)   ⇒ -1
(remainder -13 -4.0) ⇒ -1.0
(modulo 13 4)   ⇒ 1
(modulo -13 4)  ⇒ 3
(modulo 13 -4)  ⇒ -4
(modulo -13 -4) ⇒ -1

Procedure: abs x

Returns the absolute value of its argument.

(abs -7)                         ⇒  7
(abs -inf.0)                     ⇒  +inf.0

Procedure: gcd n1

Procedure: lcm n1

These procedures return the greatest common divisor or least common multiple of their arguments. The result is always non–negative. The arguments must be integers; if an argument is inexact, so is the result.

(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. The arguments must be integers; if an argument is inexact, so is the result.

(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 inexact integer objects for inexact arguments that are not infinities or NaNs, and exact integer objects for exact rational arguments.

floor

Returns the largest integer object not larger than x.

ceiling

Returns the smallest integer object not smaller than x.

truncate

Returns the integer object closest to x whose absolute value is not larger than the absolute value of x.

round

Returns the closest integer object to x, rounding to even when x represents a number halfway between two integers.

If the argument to one of these procedures is inexact, then the result is also inexact. If an exact value is needed, the result should be passed to the exact procedure.

Although infinities and NaNs are not integer objects, these procedures return an infinity when given an infinity as an argument, and a NaN when given a NaN.

(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

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

(floor +inf.0)                   ⇒  +inf.0
(ceiling -inf.0)                 ⇒  -inf.0
(round +nan.0)                   ⇒  +nan.0

Procedure: rationalize x1 x2

The rationalize procedure returns a number object representing the simplest rational number differing from x1 by no more than x2.

A rational number r_1 is simpler than another rational number r_2 if r_1 = p_1/q_1 and r_2 = p_2/q_2 (in lowest terms) and |p_1| <= |p_2| and |q_1| <= |q_2|. 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
(rationalize .3 1/10)                  ⇒ #i1/3  ; approximately

(rationalize +inf.0 3)                 ⇒  +inf.0
(rationalize +inf.0 +inf.0)            ⇒  +nan.0

The first two examples hold only in implementations whose inexact real number objects have sufficient precision.

Procedure: exp z

Procedure: log z

Procedure: log z1 z2

Procedure: sin z

Procedure: cos z

Procedure: tan z

Procedure: asin z

Procedure: acos z

Procedure: atan z

Procedure: atan x1 x2

These procedures compute the usual transcendental functions.

The exp procedure computes the base–e exponential of z. The log procedure with a single argument computes the natural logarithm of z (not the base–10 logarithm); (log z1 z2) computes the base–z2 logarithm of z1.

The asin, acos, and atan procedures compute arcsine, arccosine, and arctangent, respectively. The two–argument variant of atan computes:

(angle (make-rectangular x2 x1))

These procedures may return inexact results even when given exact arguments.

(exp +inf.0)    ⇒ +inf.0
(exp -inf.0)    ⇒ 0.0
(log +inf.0)    ⇒ +inf.0
(log 0.0)       ⇒ -inf.0
(log 0)         ⇒ exception &assertion
(log -inf.0)    ⇒ +inf.0+3.141592653589793i    ; approximately
(atan -inf.0)   ⇒ -1.5707963267948965          ; approximately
(atan +inf.0)   ⇒ 1.5707963267948965           ; approximately
(log -1.0+0.0i) ⇒ 0.0+3.141592653589793i       ; approximately
(log -1.0-0.0i) ⇒ 0.0-3.141592653589793i       ; approximately
                                                ; if -0.0 is distinguished

Procedure: sinh z

Procedure: cosh z

Procedure: tanh z

Procedure: asinh z

Procedure: acosh z

Procedure: atanh z

The hyperbolic functions.

Procedure: square z

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

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

Procedure: sqrt z

Returns the principal square root of z. For rational z, the result has either positive real part, or zero real part and non–negative imaginary part. The value of (sqrt z) could be expressed as:

e^((log z)/2)

The sqrt procedure may return an inexact result even when given an exact argument.

(sqrt -5)                   ⇒  0.0+2.23606797749979i ; approximately
(sqrt +inf.0)               ⇒  +inf.0
(sqrt -inf.0)               ⇒  +inf.0i

Note that if the argument is a primitive number (such as double) or an instance of the corresponding boxed class (such as java.lang.Double) then we use the real-number version of sqrt:

(sqrt (->double -5))        ⇒  NaN

That is, we get different a result for java.lang.Double and gnu.math.DFloNum, even for arguments that are numerically equal in the sense of =. This is so that the compiler can use the java.lang.Math.sqrt method without object allocation when the argument is a double (and because we want double and java.lang.Double to behave consistently).

Procedure: exact-integer-sqrt k

The exact-integer-sqrt procedure returns two non–negative exact integer objects s and r where k = s^2 + r and k < (s+1)^2.

(exact-integer-sqrt 4)  ⇒ 2 0 ; two return values
(exact-integer-sqrt 5)  ⇒ 2 1 ; two return values

Procedure: expt z1 z2

Returns z1 raised to the power z2. For nonzero z1, this is z1z2 = ez2 log z1. The value of 0z is 1 if (zero? z), 0 if (real-part z) is positive, and an error otherwise. Similarly for 0.0z, with inexact results.