Next: , Previous: Keyed Variables, Up: Top

## 14 Numbers

All numbers are immutable, and `equal?` iff `eq?`. The number type is encapsulated.

The external representation of an undefined number is `#undefined`. The external representation of a real with no primary value is `#real` (but this may change in the future, the report is missing the output representation for reals with no primary values). All other rules for externally representing numbers pertain only to defined numbers with primary values.

An external representation of a real number consists of optional radix and/or exactness prefixes, optional sign (`+` or `-`), and magnitude. The radix prefixes are `#b` (binary), `#o` (octal), `#d` (decimal), and `#x` (hexadecimal); the default is decimal. The exactness prefixes are `#e` (exact) and `#i` (inexact); by default, the number is inexact iff the magnitude representation uses floating point. If both kinds of prefixes are used, they may occur in either order. The magnitude is either `infinity`; an unsigned integer (nonempty sequence of digits); a ratio of unsigned integers (two unsigned integers with a `/` between, of which the second is non-zero); or a floating point representation. If the magnitude is `infinity`, there must be an exactness prefix and a sign, and no radix prefix. Floating point representation can only be used with decimal radix; it consists of nonempty integer part, point (`.`), nonempty fraction part, and optional exponent part. The optional exponent part consists of an exponent letter, and an (optionally signed) integer indicating a power of ten by which to multiply the magnitude. The choice of exponent letter makes no difference in what mathematical number is indicated by the external representation, but does indicate internal representation precision. Exponent letters `s`, `f`, `d`, `f` indicate preference for successively higher internal precision - short, float, double, long. When reading an inexact real number, exponent letter `e` accepts the default internal precision, which must be at least double. When writeing an inexact real number, exponent letter `e` may be used for the default internal precision, and must be used for any internal number format not indicated by any of the other exponent letters. Float and double must provide, respectively, at least as much precision as IEEE 32-bit and 64-bit floating point standards [IE85]. For example, `#i#xa/c` represents an inexact number using hexadecimal notation, with signed magnitude positive five sixths (ten over twelve). `-3.5l-2` represents an inexact number using decimal notation, with signed magnitude negative thirty five thousandths, and requested long precision (which must be at least IEEE 64-bit floating point). When reading an external representation of an inexact real, the bounds on the resulting inexact number are chosen in accordance with the narrow-arithmetic keyed dynamic variable.

NOTE: in klisp, all inexact numbers are stored as IEEE 64-bit floating point. No bounding or robustness info is kept.

— Applicative: number? (number? . objects)

The primitive type predicate for type number. `number?` returns true iff all the objects in `objects` are of type number.

— Applicative: integer? (integer? . objects)

The primitive type predicate for number subtype integer. `integer?` returns true iff all the objects in `objects` are of type integer.

— Applicative: exact-integer? (exact-integer? . objects)

The primitive type predicate for number subtype exact integer. `exact-integer?` returns true iff all the objects in `objects` are of type integer and exact.

SOURCE NOTE: this is from r7rs.

— Applicative: u8? (u8? . objects)

The primitive type predicate for number subtype exact integer between 0 and 255. This is the subtype used in bytevectors. `u8?` returns true iff all the objects in `objects` are of type integer, are exact, and lie between 0 and 255 inclusive.

SOURCE NOTE: this is handy for use with bytevectors.

— Applicative: rational? (rational? . objects)

The primitive type predicate for number subtype rational. `rational?` returns true iff all the objects in `objects` are of type rational.

— Applicative: real? (real? . objects)

The primitive type predicate for number subtype real. `real?` returns true iff all the objects in `objects` are of type real.

— Applicative: finite? (finite? . numbers)

Predicate `finite?` returns true iff all the numbers in `numbers` are finite.

— Applicative: exact? (exact? . numbers)

Predicate `exact?` returns true iff all the numbers in `numbers` are exact.

— Applicative: inexact? (inexact? . numbers)

Predicate `inexact?` returns true iff all the numbers in `numbers` are inexact.

— Applicative: robust? (robust? . numbers)

Predicate `robust?` returns true iff all the numbers in `numbers` are robust.

— Applicative: undefined? (undefined? . numbers)

Predicate `undefined?` returns true iff all the numbers in `numbers` are undefined.

— Applicative: =? (=? . numbers)

Applicative `=?` is a predicate that returns true iff all its arguments are numerically equal to each other. If any of its arguments has no primary value, an error is signaled.

— Applicative: <? (<? . reals)
— Applicative: <=? (<=? . reals)
— Applicative: >? (>? . reals)
— Applicative: >=? (>=? . reals)

Each of these applicatives is a predicate that returns true iff every two consecutive elements of `reals` have primary values in the order indicated by the name of the applicative. If any element of `reals` has no primary value, an error is signaled.

— Applicative: + (+ . numbers)

Applicative `+` returns the sum of the elements of numbers. If numbers is empty, the sum of its elements is exact zero. If a positive infinity is added to a negative infinity, the result has no primary value. If all the elements of a cycle are zero, the sum of the cycle is zero. If the acyclic sum of the elements of a cycle (i.e., the sum of an acyclic list containing just those elements) is non-zero, the sum of the cycle is positive infinity times the acyclic sum of the elements. If the acyclic sum of the elements of a cycle is zero, but some of the elements of the cycle are non-zero, the sum of the cycle has no primary value.

— Applicative: * (* . numbers)

Applicative `*` returns the product of the elements of numbers. If numbers is empty, the product of its elements is exact one. If an infinity is multiplied by zero, the result has no primary value. If the acyclic product of the elements of a cycle is real greater than one, the product of the cycle is positive infinity. If all the elements of a cycle are positive one, the product of the cycle is positive one. If the acyclic product of the elements of a cycle is positive one, but some of the elements of the cycle are not positive one, the product of the cycle has no primary value. If the acyclic product of the elements of a cycle has magnitude less than one, the product of the cycle is zero. If the acyclic product of the elements of a cycle has magnitude greater than or equal to one, and is not positive real, the product of the cycle has no primary value.

— Applicative: - (- number . numbers)

`numbers` should be a nonempty list of numbers.

Applicative `-` returns the sum of `number` with the negation of the sum of `numbers`.

— Applicative: zero? (zero? . numbers)

Applicative `zero?` is a predicate that returns true iff every element of `numbers` is zero. For this purpose, a real number is zero if its primary value is zero. If any element of numbers has no primary value an error is signaled.

— Applicative: div (div real1 real2)
— Applicative: mod (mod real1 real2)
— Applicative: div-and-mod (div-and-mod real1 real2)

For all three applicatives, if `real1` is infinite or `real2` is zero, an error is signaled.

Let `n` be the greatest integer such that ```real2 * n <= real1```. Applicative `div` returns `n`. Applicative `mod` returns `real1 - (real2 * n)`. Applicative `div-and-mod` returns a freshly allocated list of length two, whose first element is `n` and whose second element is `real1 - (real2 * n)`.

— Applicative: div0 (div0 real1 real2)
— Applicative: mod0 (mod0 real1 real2)
— Applicative: div0-and-mod0 (div0-and-mod0 real1 real2)

For all three applicatives, if `real1` is infinite or `real2` is zero, an error is signaled.

Let `n` be the greatest integer such that ```real2 * n <= real1 + |real2/2|```. Applicative `div0` returns `n`. Applicative `mod0` returns `real1 - (real2 * n)`. Applicative `div0-and-mod0` returns a freshly allocated list of length two, whose first element is `n` and whose second element is `real1 - (real2 * n)`.

— Applicative: positive? (positive? . reals)
— Applicative: negative? (negative? . reals)

Applicative `positive?` is a predicate that returns true iff every element of `reals` is greater than zero. Applicative `negative?` is a predicate that returns true iff every element of `reals` is less than zero. If any argument to either applicative has no primary value an error is signaled.

— Applicative: odd? (odd? . integers)
— Applicative: even? (even? . integers)

Applicative `odd?` is a predicate that returns true iff every element of `integers` is odd. Applicative `even?` is a predicate that returns true iff every element of `integers` is even. If any argument to either applicative has no primary value an error is signaled.

— Applicative: abs (abs real)

Applicative `abs` returns the nonnegative real number with the same magnitude as `real`; that is, if `real` is nonnegative it returns `real`, otherwise it returns the negation of `real`.

— Applicative: max (max . reals)
— Applicative: min (min . reals)

If `reals` is nil, applicative `max` returns exact negative infinity, and applicative `min` returns exact positive infinity. If `reals` is non-nil, applicative `max` returns the largest number in `reals`, and applicative `min` returns the smallest number in `reals`.

— Applicative: lcm (lcm . impints)
— Applicative: gcd (gcd . impints)

`impints` should be a list of improper integers, that is, real numbers each of which is either an integer or an infinity.

Applicative `lcm` returns the smallest positive improper integer that is an improper0integer multiple of every element of `impints` (that is, smallest `n >= 1` such that for every argument `nk` there exists `n'k` with `nk * n'k = n`). If any of the arguments is zero, the result of `lcm` has no primary value. According to these rules, `lcm` with nil argument list returns `1`, and `lcm` with any infinite argument returns positive infinity.

Applicative `gcd` returns the largest positive improper integer such that every element of `impints` is an improper-integer multiple of it (that is, largest `n >= 1` such that for every argument `nk` there exists `n'k` with `n * n'k = nk`). `gcd` with nil argument list returns exact positive infinity. If `gcd` is called with one or more arguments, and at least one of the arguments is zero, but none of the arguments is a non-zero finite integer, its result has no primary value. According to these rules, if `gcd` is called with at least one finite non-zero argument, its result is the same as if all zero and infinite arguments were deleted.

— Applicative: get-real-internal-bounds (get-real-internal-bounds real)
— Applicative: get-real-exact-bounds (get-real-exact-bounds real)

Applicative `get-real-internal-bounds` returns a freshly allocated list of reals `(x1 x2)`, where the primary value of `x1` is the lower bound of `real`, using the same internal representation as the primary value of `real`, and the primary value of `x2` is the upper bound of `real`, using the same internal representation as the primary value of `real`. The `xk` are inexact iff real is inexact. The `xk` are robust (i.e., tagged if the implementation supports such), and the bounds of each `xk` are only required to contain its primary value (i.e., the implementation is allowed to make the bounds equal to the primary value).

Applicative `get-real-exact-bounds` returns a freshly allocated list of exact reals `(x1 x2)`, where `x1` is not greater than the lower bound of `real`, and `x2` is not less than the upper bound of `real`.

— Applicative: get-real-internal-primary (get-real-internal-primary real)
— Applicative: get-real-exact-primary (get-real-exact-primary real)

If `real` is exact, both applicatives return `real`. If `real` has no primary value, both applicatives signal an error.

If `real` is inexact with a primary value, applicative `get-real-internal-primary` returns a real number `x0` whose primary value is the same as, and has the same internal format as, the primary value of `real`. `x0` is robust, and its bounds are only required to contain its primary value.

If `real` is inexact with a primary value, applicative `get-real-exact-primary` returns an exact real number `x0` within the exact bounds that would be returned for `real` by applicative `get-real-exact-bounds`. Preferably, `x0` should be as close to the primary value of `real` as the implementation can reasonably arrange. If the implementation does not support any exact `real` that reasonably approximates `real`, an error may be signaled.

— Applicative: make-inexact (make-inexact real1 real2 real3)

Applicative `make-inexact` returns an inexact real number, as follows. If `real2` is inexact, the result has the same primary value as `real2`; and if `real2` has no primary value, the result has no primary value. The result has the same robustness as `real2`. If possible, the result uses the same internal representation as `real2`. If `real2` is exact, the primary value of the result is as close to `real2` as the implementation can reasonably arrange; overflow and underflow are handled as described in .... The lower bound of the result is no greater than the lower bound of `real1`, the primary value of `real2`, and the primary value of the result. The upper bound of the result is no less than the upper bound of `real3`, the primary value of `real2`, and the primary value of the result.

— Applicative: real->inexact (real->inexact real)
— Applicative: real->exact (real->exact real)

Applicative `real->exact` behaves just as `get-real-exact-primary`.

If `real` is inexact, applicative `real->inexact` returns `real`. If `real` is exact, applicative `real->inexact` returns an inexact real `x0` such that `real` would be a permissible result of passing `x0` to `real->exact`. If the implementation does not support any such `x0`, an error may be signaled. Otherwise, `x0` is robust, and its bounds are only required to contain its primary value and `real`.

— Applicative: with-strict-arithmetic (with-strict-arithmetic boolean combiner)
— Applicative: get-string-arithmetic (get-strict-arithmetic?)

These applicatives are the binder and accessor of the `strict-arithmetic` keyed dynamic variable. When this keyed variable is true, various survivable but dubious arithmetic events signal an error - notably, operation results with no primary value, and over- and underflows.

— Applicative: / (/ number . numbers)

`numbers` should be a nonempty list of numbers.

Applicative `/` returns `number` divided by the product of `numbers`. If the product of `numbers` is zero, an error is signaled. If `number` is infinite and the product of `numbers` is infinite, an error is signaled.

— Applicative: numerator (numerator rational)
— Applicative: denominator (denominator rational)

These applicatives return the numerator and denominator of `rational`, in least terms (i.e., chosen for the least positive denominator). Note that if `rational` is inexact, and either of its bounds is not its primary value, the denominator has upper bound positive infinity, and the numerator must have at least one infinite bound (two infinite bounds if the bounds of rational allow values of both signs).

— Applicative: floor (floor real)
— Applicative: ceiling (ceiling real)
— Applicative: truncate (truncate real)
— Applicative: round (round real)

Applicative `floor` returns the largest integer not greater than `real`.

Applicative `ceiling` returns the smallest integer not less than `real`.

Applicative `truncate` returns the integer closest to `real` whose absolute value is not greater than that of `real`.

Applicative `round` returns the closest integer to `real`, rounding to even when `real` is halfway between two integers.

— Applicative: rationalize (rationalize real1 real2)
— Applicative: simplest-rational (simplest-rational real1 real2)

A rational number `r1` is simpler than another rational `r2` if `r1 = p1 / q1` and `r2 = p2 / q2`, both in lowest terms, and `|p1| <= |p2|` and `|q1| <= |q2|`. Thus `3/5` is simpler than `4/7`. Not all rationals are comparable in this ordering, as for example `2/7` and `3/5`. However, any interval (that contains rational numbers) contains a rational number that is simpler than every other rational number in that interval. Note that `0 = 0/1` is simpler than any other rational (so that one never has to choose between `p/q` and `−p/q`).

For applicative `simplest-rational`, let `x0` be the simplest rational mathematically not less than the primary value of `real1` and not greater than the primary value of `real2`. If no such `x0` exists (because the primary value of `real1` is greater, or because the primary values of the arguments are equal and irrational), or if either argument does not have a primary value, an error is signaled.

For applicative `rationalize`, let `x0` be the simplest rational mathematical number within the interval bounded by the primary value of `real1` plus and minus the primary value of `real2`. If no such `x0` exists (because the primary value of `real1` is irrational and the primary value `real2` is zero), or if either argument does not have a primary value, an error is signaled.

If `real1` and `real2` are exact, the applicative (whichever it is) returns exact `x0`. If one or both of `real1` and `real2` are inexact, the applicative returns an inexact rational approximating `x0` (as by `real->inexact`. Note that an inexact result returned is not necessarily bounded by the primary values of the arguments; but the result is an approximation of `x0`, which is so bounded, and the bounds of the result include `x0`.

— Applicative: sqrt (sqrt number)

If `number` is negative, the result is undefined.

Applicative `sqrt` returns the positive square root of number. The result may be inexact even if `number` is exact and the square root is rational.

— Applicative: expt (expt number1 number2)

Applicative `expt` returns `number1` to the power of `number2`. If `number1` is zero, then the result is 1 if `number2` is zero and 0 otherwise.

— Applicative: exp (exp number)
— Applicative: log (log number)
— Applicative: sin (sin number)
— Applicative: cos (cos number)
— Applicative: tan (tan number)
— Applicative: asin (asin number)
— Applicative: acos (acos number)
— Applicative: atan (atan number1 [number2])

These applicatives compute the usual transcendental functions. `log` computes the natural logarithm (not the base-10 logarithm). The two argument version of `atan` computes ```(angle (make-recutangular number1 number2))``` even thou klisp doesn't support complex numbers.

All results may be inexact even if `number` is exact and the result of the transcendental function is rational. TODO add intervals returned for multidefined functions (inverses and log)

— Applicative: string->number (string->number string [radix])

`radix` should be an exact integer, either 2, 8, 10, or 16. `string` should be a string describing a number in the specified radix, but may contain a radix prefix to override it. The default `radix`, if not supplied, is 10.

Applicative `string->number` returns the best approximation of the number represented by `string`. If `string` is not a valid representation of a number in the given `radix` an error is signaled.

Examples:

```          (string->number "100") ⇒ 100
(string->number "100" 16) ⇒ 256
(string->number "#o100" 2) ⇒ 64
(string->number "1.0") ⇒ 1.0
```

SOURCE NOTE: this is taken from r7rs.

— Applicative: number->string (number->string number [radix])

`radix` should be an exact integer, either 2, 8, 10, or 16. The default `radix`, if not supplied, is 10.

Applicative `number->string` returns a string representing `number` in the given `radix`. No radix prefix is present in the returned string. If an inexact number is passed together with a radix other from 10, an error is signaled.

The returned string is such that

```          (string->number (number->string number radix) radix) == number
```

Examples:

```          (number->string 100) ⇒ "100"
(number->string 256 16) ⇒ "100"
(number->string 1.0) ⇒ "1.0"
```

SOURCE NOTE: this is taken from r7rs.