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: 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: div x1 x2

Procedure: mod x1 x2

Procedure: div-and-mod x1 x2

These procedures implement number–theoretic integer division. They accept two real numbers x1 and x2 as operands, where x2 must be nonzero. (Kawa allows x2 to be zero for mod.) div returns an integer, and mod returns a real. Their results are specified by:

(div x1 x2) ⇒ nd
(mod x1 x2) ⇒ xm

such that:

x1 = nd * x2 + xm
0  <= xm < |x2|
(div-and-mod x1 x2)
  ⇒ (values (div x1 x2) (mod x1 x2))
(div 123 10)    ⇒  12
(mod 123 10)    ⇒  3
(div 123 -10)   ⇒  -12
(mod 123 -10)   ⇒  3
(div -123 10)   ⇒  -13
(mod -123 10)   ⇒  7
(div -123 -10)  ⇒  13
(mod -123 -10)  ⇒  7
(mod 123 0)     ⇒  123 ;; Kawa extension

Procedure: div0 x1 x2

Procedure: mod0 x1 x2

Procedure: div0-and-mod0 x1 x2

div0 and mod0 are like div and mod, except the result of mod0 lies within a half–open interval centered on zero. The results are specified by:

(div0 x1 x2) ⇒ nd
(mod0 x1 x2) ⇒ xm

such that:

x1 = nd * x2 + xm
-|x2| <= xm < |x2/2|
(div0-and-mod0 x1 x2)
  ⇒ (values (div0 x1 x2) (mod0 x1 x2))
(div0 123 10)   ⇒  12
(mod0 123 10)   ⇒  3
(div0 123 -10)  ⇒  -12
(mod0 123 -10)  ⇒  3
(div0 -123 10)  ⇒  -12
(mod0 -123 10)  ⇒  -3
(div0 -123 -10) ⇒  12
(mod0 -123 -10) ⇒  -3

Procedure: quotient x y

Kawa generalizes quotient to arbitrary real numbers, using the definition: (truncate (/ x y)).

Procedure: remainder x y

Generalized to arbitrary real numbers, using the definition: (- x (* y (truncate (/ x y)))). If y is 0, the result is x - i.e. we take (* 0 (quotient x 0)) to be 0. The result is inexact if either argument is inexact, even if x is exact and y is 0.

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

Procedure: modulo x y

Generalized to arbitrary real numbers, using the definition: (- x (* y (floor (/ x y)))). If y is 0, the result is x. The result is inexact if either argument is inexact, even if x is exact and y is 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. (R6RS allows inexact integer arguments; Kawa does not.)

(gcd 32 -36)                     ⇒  4
(gcd)                            ⇒  0
(lcm 32 -36)                     ⇒  288
(lcm 32.0 -36)                   ⇒  288.0
(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. (R6RS allows inexact integer arguments; Kawa does not.)

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

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: square z

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

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

Procedure: sqrt z

Return 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

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