Next: , Previous: , Up: Numbers   [Contents][Index]

### 12.2 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
```

Next: , Previous: , Up: Numbers   [Contents][Index]