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).

NOTE: I'm not really sure about this description...

— 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).

NOTE: I'm not really sure about this description...

— 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.