Next: Numerical input and output, Previous: Syntax of numerical constants, Up: Numbers [Contents][Index]
See Entry Format, for a summary of the naming conventions used to specify restrictions on the types of arguments to numerical routines. The examples used in this section assume that any numerical constant written using an exact notation is indeed represented as an exact number. Some examples also assume that certain numerical constants written using an inexact notation can be represented without loss of accuracy; the inexact constants were chosen so that this is likely to be true in implementations that use flonums to represent inexact numbers.
These numerical type predicates can be applied to any kind of argument,
including non-numbers. They return #t
if the object is of the
named type, and otherwise they return #f
. In general, if a type
predicate is true of a number then all higher type predicates are also
true of that number. Consequently, if a type predicate is false of a
number, then all lower type predicates are also false of that
number.^{3}
If z is an inexact complex number, then (real? z)
is
true if and only if (zero? (imag-part z))
is true. If
x is an inexact real number, then (integer? x)
is
true if and only if (= x (round x))
.
(complex? 3+4i) ⇒ #t (complex? 3) ⇒ #t (real? 3) ⇒ #t (real? -2.5+0.0i) ⇒ #t (real? #e1e10) ⇒ #t (rational? 6/10) ⇒ #t (rational? 6/3) ⇒ #t (integer? 3+0i) ⇒ #t (integer? 3.0) ⇒ #t (integer? 8/4) ⇒ #t
Note: The behavior of these type predicates on inexact numbers is unreliable, since any inaccuracy may affect the result.
These numerical predicates provide tests for the exactness of a quantity. For any Scheme number, precisely one of these predicates is true.
These procedures test for some very common types of numbers. These tests could be written in terms of simpler predicates, but are more efficient.
These procedures return #t
if their arguments are (respectively):
equal, monotonically increasing, monotonically decreasing, monotonically
nondecreasing, or monotonically nonincreasing.
These predicates are transitive. Note that the traditional implementations of these predicates in Lisp-like languages are not transitive.
Note: While it is not an error to compare inexact numbers using these
predicates, the results may be unreliable because a small inaccuracy may
affect the result; this is especially true of =
and zero?
.
When in doubt, consult a numerical analyst.
These numerical predicates test a number for a particular property,
returning #t
or #f
. See note above regarding inexact
numbers.
These procedures return the maximum or minimum of their arguments.
(max 3 4) ⇒ 4 ; exact (max 3.9 4) ⇒ 4.0 ; inexact
Note: If any argument is inexact, then the result will also be inexact
(unless the procedure can prove that the inaccuracy is not large enough
to affect the result, which is possible only in unusual
implementations). If min
or max
is used to compare
numbers of mixed exactness, and the numerical value of the result cannot
be represented as an inexact number without loss of accuracy, then the
procedure may report a violation of an implementation
restriction.^{4}
These procedures return the sum or product of their arguments.
(+ 3 4) ⇒ 7 (+ 3) ⇒ 3 (+) ⇒ 0 (* 4) ⇒ 4 (*) ⇒ 1
With two or more arguments, these procedures return the difference or quotient of their arguments, associating to the left. With one argument, however, they return the additive or multiplicative inverse of their argument.
(- 3 4) ⇒ -1 (- 3 4 5) ⇒ -6 (- 3) ⇒ -3 (/ 3 4 5) ⇒ 3/20 (/ 3) ⇒ 1/3
(1+ z)
is equivalent to (+ z 1)
; (-1+ z)
is
equivalent to (- z 1)
.
abs
returns the magnitude of its argument.
(abs -7) ⇒ 7
These procedures implement number-theoretic (integer) division: for positive integers n1 and n2, if n3 and n4 are integers such that then
(quotient n1 n2) ⇒ n3 (remainder n1 n2) ⇒ n4 (modulo n1 n2) ⇒ n4
For integers n1 and n2 with n2 not equal to 0,
(= n1 (+ (* n2 (quotient n1 n2)) (remainder n1 n2))) ⇒ #t
provided all numbers involved in that computation are exact.
The value returned by quotient
always has the sign of the product
of its arguments. remainder
and modulo
differ on negative
arguments — the remainder
always has the sign of the dividend,
the modulo
always has the sign of the divisor:
(modulo 13 4) ⇒ 1
(remainder 13 4) ⇒ 1
(modulo -13 4) ⇒ 3
(remainder -13 4) ⇒ -1
(modulo 13 -4) ⇒ -3
(remainder 13 -4) ⇒ 1
(modulo -13 -4) ⇒ -1
(remainder -13 -4) ⇒ -1
(remainder -13 -4.0) ⇒ -1.0 ; inexact
Note that quotient
is the same as integer-truncate
.
These procedures combine integer division with rounding. For example, the following are equivalent:
(integer-floor n1 n2) (floor (/ n1 n2))
However, the former is faster and does not produce an intermediate result.
Note that integer-truncate
is the same as quotient
.
integer-divide
is equivalent to performing both quotient
and remainder
at once. The result of integer-divide
is an
object with two components; the procedures
integer-divide-quotient
and integer-divide-remainder
select those components. These procedures are useful when both the
quotient and remainder are needed; often computing both of these numbers
simultaneously is much faster than computing them separately.
For example, the following are equivalent:
(lambda (n d) (cons (quotient n d) (remainder n d))) (lambda (n d) (let ((qr (integer-divide n d))) (cons (integer-divide-quotient qr) (integer-divide-remainder qr))))
These procedures return the greatest common divisor or least common multiple of their arguments. The result is always non-negative.
(gcd 32 -36) ⇒ 4
(gcd) ⇒ 0
(lcm 32 -36) ⇒ 288
(lcm 32.0 -36) ⇒ 288.0 ; inexact
(lcm) ⇒ 1
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.
(numerator (/ 6 4)) ⇒ 3 (denominator (/ 6 4)) ⇒ 2 (denominator (inexact (/ 6 4))) ⇒ 2.0
These procedures return integers. floor
returns the largest
integer not larger than x. ceiling
returns the smallest
integer not smaller than x. truncate
returns the integer
closest to x whose absolute value is not larger than the absolute
value of x. round
returns the closest integer to x,
rounding to even when x is halfway between two integers.
Rationale: round
rounds to even for consistency with the rounding
modes required by the IEEE floating point standard.
Note: If the argument to one of these procedures is inexact, then the
result will also be inexact. If an exact value is needed, the result
should be passed to the exact
procedure (or use one of the
procedures below).
(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 ; inexact (round 7/2) ⇒ 4 ; exact (round 7) ⇒ 7
These procedures are similar to the preceding procedures except that they always return an exact result. For example, the following are equivalent
(floor->exact x) (exact (floor x))
except that the former is faster and has fewer range restrictions.
rationalize
returns the simplest rational number differing
from x by no more than y. A rational number r1 is
simpler than another rational number 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.
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 ; exact (rationalize .3 1/10) ⇒ #i1/3 ; inexact
rationalize->exact
is similar to rationalize
except that
it always returns an exact result.
simplest-rational
returns the simplest rational number between
x and y inclusive; simplest-exact-rational
is similar
except that it always returns an exact result.
These procedures implement the same functionality as rationalize
and rationalize->exact
, except that they specify the input range
by its endpoints; rationalize
specifies the range by its center
point and its (half-) width.
These procedures compute the usual transcendental functions. log
computes the natural logarithm of z (not the base ten logarithm).
asin
, acos
, and atan
compute arcsine, arccosine,
and arctangent, respectively. The two-argument variant of atan
computes (angle (make-rectangular x y))
(see
below).
In general, the mathematical functions log, arcsine, arccosine, and arctangent are multiply defined. For nonzero real x, the value of log x is defined to be the one whose imaginary part lies in the range minus pi (exclusive) to pi (inclusive). log 0 is undefined. The value of log z when z is complex is defined according to the formula With log defined this way, the values of arcsine, arccosine, and arctangent are according to the following formulae: The above specification follows Common Lisp: the Language, which in turn cites Principal Values and Branch Cuts in Complex APL; refer to these sources for more detailed discussion of branch cuts, boundary conditions, and implementation of these functions. When it is possible these procedures produce a real result from a real argument.
Equivalent to:
log1p z = log(1 + z). expm1 z = exp(z) - 1,
However, for real numbers close to zero, these provide better
approximations than (log (+ 1 z))
or (- (exp
z) 1)
:
x f'(x)/f(x) = [x/(1 + x)]/log(1 + x).
(Conversely, the condition number of log near 0 approaches 0, while the condition number of log1p near -1 is unbounded, so for inputs near 0 it is better to compute them via log rather than via log1p.)
(exp z)
may be amplified arbitrarily by then computing (- (exp z)
1)
.
In contrast, the condition number of expm1 itself near 0 is
near 1, so it does not inherently amplify errors:
x f'(x)/f(x) = x e^x/(e^x - 1).
The forward relative error of this implementation is determined by the system’s math library, usually below 1ulp.
Equivalent to:
log1mexp x = log (1 - e^x), log1pexp x = log (1 + e^x).
Like log1p and expm1, these avoid numerical pathologies with the intermediate quantities 1 - e^x and 1 + e^x and inputs to log near 1.
This implementation gives forward relative error bounded by ten times the forward relative error bound of the system math library’s log and exp, which is usually below 1ulp.
Beware that although the forward relative error of the MIT/GNU Scheme implementations of these functions is bounded, these functions are ill-conditioned for large negative inputs:
x f'(x)/f(x) = (+/- x exp(x))/((1 +/- e^x) log(1 +/- e^x)), --> x, for x << 0.
Logistic and logit functions. Equivalent to:
logistic x = exp(x)/[1 + exp(x)] = 1/[1 + exp(-x)], logit p = log p/(1 - p).
These functions are inverses of one another. The logit function maps a probablity p in [0, 1] into log-odds x in the extended real line, and the logistic function maps back from log-odds to probabilities.
x f'(x)/f(x) = x exp(-x)/[1 + exp(-x)].
The identity
logistic(-x) = 1 - logistic(x)
may help to rearrange a computation, along with the logistic-1/2 function which ranges from -1/2 to +1/2 and centered at zero rather than from 0 to 1 and centered at 1/2.
This implementation gives forward relative error bounded by at most seven times the forward relative error bound of the system math library’s exp, which is usually below 1ulp.
x f'(x)/f(x) = 1/[(1 - p) log(p/(1 - p))].
The identity
logit(1 - p) = -logit(p)
may help to rearrange a computation, along with the logit1/2+ function which is defined on -1/2 to +1/2 and centered at zero rather than on 0 to 1 and centered at 1/2.
This implementation gives forward relative error bounded by at most ten times the forward relative error bound of the system math library’s log, which is usually below 1ulp.
Equivalent to:
logistic-1/2 x = logistic(x) - 1/2, logit1/2+ p = logit(1/2 + p).
Like logistic
and logit
, these functions are inverses of
one another; unlike logistic
and logit
, their domains
and codomains are both centered at zero.
x f'(x)/f(x) = 2 x e^-x / (1 - (e^-x)^2).
This implementation gives forward relative error bounded by 5 times the forward relative error bound of the system math library’s exp, which is usually below 1ulp.
x f'(x)/f(x) = x/[(1 - 4 x^2) logit(1/2 + x)].
For points near -1/2 or +1/2, it may be better to compute logit of a point near 0 instead. This implementation gives forward relative error bounded by 34 times the forward relative error bound of the system math library’s log, which is usually below 1ulp.
Equivalent to:
log-logistic x = log(logistic(x)) = log [1/(1 + exp(-x))] logit-exp x = logit(exp(x)) = log [exp(x)/(1 - exp(x))]
Like logistic
and logit
, these functions are inverses of
one another.
x f'(x)/f(x) = (-x exp(-x))/[(1 + exp(-x)) log(1 + exp(-x))]
x f'(x)/f(x) = x/[(1 - exp(x)) log(exp(x)/(1 - exp(x)))]
This implementation gives forward relative error bounded by ten times the forward relative error bound of the system math library’s log and exp, which is usually below 1ulp.
List must be a list of real numbers x1, x2, …, xn. Returns an approximation to:
log(exp(x1) + exp(x2) + … + exp(xn)).
The approximation avoids intermediate overflow and underflow. To minimize error, the caller should arrange for the numbers to be sorted from least to greatest.
Edge cases:
-inf
, as if the
intermediate sum were zero.
-inf
, the
-inf
elements are ignored, since the exponential of -inf
is zero.
+inf
, the result
is +inf
as if the sum had overflowed.
(Otherwise, overflow is not possible.)
-inf
and +inf
, or if
list contains any NaNs, the result is a NaN.
Logsumexp
never raises any of the standard IEEE 754-2008
floating-point exceptions other than invalid-operation.
Returns the principal square root of z. The result will have either positive real part, or zero real part and non-negative imaginary part.
Returns z1 raised to the power z2:
Suppose x1, x2, x3, and x4 are real numbers and
z is a complex number such that
Then make-rectangular
and make-polar
return z,
real-part
returns x1, imag-part
returns x2,
magnitude
returns x3, and angle
returns x4.
In the case of angle
, whose value is not uniquely determined by
the preceding rule, the value returned will be the one in the range
minus pi (exclusive) to pi (inclusive).
conjugate
returns the complex conjugate of z.
The procedures exact
and inexact
implement the natural
one-to-one correspondence between exact and inexact integers
throughout an implementation-dependent range.
inexact
returns an inexact representation of z. The
value returned is the inexact number that is numerically closest to
the argument. For inexact arguments, the result is the same as the
argument. For exact complex numbers, the result is a complex number
whose real and imaginary parts are the result of applying
inexact
to the real and imaginary parts of the argument,
respectively. If an exact argument has no reasonably close inexact
equivalent (in the sense of =
), then a violation of an
implementation restriction may be reported.
The procedure exact->inexact
has been deprecated by R7RS.
exact
returns an exact representation of z. The value
returned is the exact number that is numerically closest to the
argument. For exact arguments, the result is the same as the
argument. For inexact non-integral real arguments, the implementation
may return a rational approximation, or may report an implementation
violation. For inexact complex arguments, the result is a complex
number whose real and imaginary parts are the result of applying
exact
to the real and imaginary parts of the argument,
respectively. If an inexact argument has no reasonably close exact
equivalent (in the sense of =
), then a violation of an
implementation restriction may be reported.
The procedure inexact->exact
has been deprecated by R7RS.
Returns a real number with the magnitude of x1 and the sign of x2.
(copysign 123 -1) ⇒ -123 (copysign 0. -1) ⇒ -0. (copysign -0. 0.) ⇒ 0. (copysign -nan.123 0.) ⇒ +nan.123
In MIT/GNU Scheme the rational?
procedure is the
same as real?
, and the complex?
procedure is the same as
number?
.
MIT/GNU Scheme signals an error of type
condition-type:bad-range-argument
in this case.
Next: Numerical input and output, Previous: Syntax of numerical constants, Up: Numbers [Contents][Index]