3.2.2 Generic Numerics
Most Racket numeric operations work on any kind of number.
3.2.2.1 Arithmetic
Returns the sum of the zs, adding pairwise from left to
right. If no arguments are provided, the result is 0.
Examples: |
| > (+ 1 2) | 3 | | > (+ 1.0 2+3i 5) | 8.0+3.0i | | > (+) | 0 |
|
When no
ws are supplied, returns
(- 0 z).
Otherwise, returns the subtraction of the
ws from
z
working pairwise from left to right.
Examples: |
| > (- 5 3.0) | 2.0 | | > (- 1) | -1 | | > (- 2+7i 1 3) | -2+7i |
|
Returns the product of the zs, multiplying pairwise from left
to right. If no arguments are provided, the result is
1. Multiplying any number by exact 0 produces exact
0.
Examples: |
| > (* 2 3) | 6 | | > (* 8.0 9) | 72.0 | | > (* 1+2i 3+4i) | -5+10i |
|
When no
ws are supplied, returns
(/ 1 z).
Otherwise, returns the division of
z by the
ws working
pairwise from left to right.
If z is exact 0 and no w is exact
0, then the result is exact 0. If any w is
exact 0, the exn:fail:contract:divide-by-zero exception is raised.
Examples: |
| > (/ 3 4) | 3/4 | | > (/ 81 3 3) | 9 | | > (/ 10.0) | 0.1 | | > (/ 1+2i 3+4i) | 11/25+2/25i |
|
Examples: |
| > (quotient 10 3) | 3 | | > (quotient -10.0 3) | -3.0 | | > (quotient +inf.0 3) | quotient: expects type <integer> as 1st argument, given: | +inf.0; other arguments were: 3 |
|
Returns q with the same sign as n such that
If m is exact 0, the
exn:fail:contract:divide-by-zero exception is raised.
Returns q with the same sign as m where
(abs q) is between 0 (inclusive) and (abs m) (exclusive), and
the difference between q and (- n (* m (quotient n m))) is a multiple of m.
If m is exact 0, the
exn:fail:contract:divide-by-zero exception is raised.
Examples: |
| > (modulo 10 3) | 1 | | > (modulo -10.0 3) | 2.0 | | > (modulo 10.0 -3) | -2.0 | | > (modulo -10 -3) | -1 | | > (modulo +inf.0 3) | modulo: expects type <integer> as 1st argument, given: | +inf.0; other arguments were: 3 |
|
Returns the absolute value of
x.
Returns the largest of the xs, or +nan.0 if any
x is +nan.0. If any x is inexact, the
result is coerced to inexact.
Examples: |
| > (max 1 3 2) | 3 | | > (max 1 3 2.0) | 3.0 |
|
Returns the smallest of the xs, or +nan.0 if any
x is +nan.0. If any x is inexact, the
result is coerced to inexact.
Examples: |
| > (min 1 3 2) | 1 | | > (min 1 3 2.0) | 1.0 |
|
Returns the
greatest common divisor (a non-negative
number) of the
ns; for non-integer
ns, the result
is the
gcd of the numerators divided
by the
lcm of the denominators.
If no arguments are provided, the result
is
0. If all arguments are zero, the result is zero.
Examples: |
| > (gcd 10) | 10 | | > (gcd 12 81.0) | 3.0 | | > (gcd 1/2 1/3) | 1/6 |
|
Returns the
least common multiple (a non-negative number)
of the
ns; non-integer
ns, the result is
the absolute value of the product divided by the
gcd. If no arguments are provided, the result is
1. If any argument is zero, the result is zero; furthermore,
if any argument is exact
0, the result is exact
0.
Examples: |
| > (lcm 10) | 10 | | > (lcm 3 4.0) | 12.0 | | > (lcm 1/2 2/3) | 2 |
|
Returns the integer closest to x, resolving ties in favor of
an even number, but +inf.0, -inf.0, and +nan.0
round to themselves.
Returns the largest integer that is no more than x, but
+inf.0, -inf.0, and +nan.0 floor to
themselves.
Returns the smallest integer that is at least as large as x,
but +inf.0, -inf.0, and +nan.0 ceiling to
themselves.
Returns the integer farthest from 0 that is not farther from
0 than x, but +inf.0, -inf.0, and
+nan.0 truncate to themselves.
Coerces q to an exact number, finds the numerator of the
number expressed in its simplest fractional form, and returns this
number coerced to the exactness of q.
Coerces q to an exact number, finds the numerator of the
number expressed in its simplest fractional form, and returns this
number coerced to the exactness of q.
Among the real numbers within
(abs tolerance) of
x,
returns the one corresponding to an exact number whose
denominator is the smallest. If multiple integers are within
tolerance of
x, the one closest to
0 is
used.
3.2.2.2 Number Comparison
Returns
#t if all of the arguments are numerically equal,
#f otherwise. An inexact number is numerically equal to an
exact number when the exact coercion of the inexact number is the
exact number. Also, 0.0 and -0.0 are numerically
equal, but +nan.0 is not numerically equal to itself.
Examples: |
| > (= 1 1.0) | #t | | > (= 1 2) | #f | | > (= 2+3i 2+3i 2+3i) | #t |
|
Returns #t if
the arguments in the given order are strictly increasing,
#f otherwise.
Examples: |
| > (< 1 1) | #f | | > (< 1 2 3) | #t | | > (< 1 +inf.0) | #t | | > (< 1 +nan.0) | #f |
|
Returns #t
if the arguments in the given order are non-decreasing,
#f otherwise.
Examples: |
| > (<= 1 1) | #t | | > (<= 1 2 1) | #f |
|
Returns #t if
the arguments in the given order are strictly decreasing,
#f otherwise.
Examples: |
| > (> 1 1) | #f | | > (> 3 2 1) | #t | | > (> +inf.0 1) | #t | | > (< +nan.0 1) | #f |
|
Returns #t
if the arguments in the given order are non-increasing,
#f otherwise.
Examples: |
| > (>= 1 1) | #t | | > (>= 1 2 1) | #f |
|
3.2.2.3 Powers and Roots
Returns the principal
square root of
z. The
result is exact if
z is exact and
z’s square root
is rational. See also
integer-sqrt.
Returns
z raised to the power of
w. If
w is
exact
0, the result is exact
1. If
z is
exact
0 and
w is negative, the
exn:fail:contract:divide-by-zero exception is raised.
Returns Euler’s number raised to the power of z. The result
is normally inexact, but it is exact 1 when z is an
exact 0.
Examples: |
| > (exp 1) | 2.718281828459045 | | > (exp 2+3i) | -7.315110094901103+1.0427436562359045i | | > (exp 0) | 1 |
|
Returns the natural logarithm of
z. The result is normally
inexact, but it is exact
0 when
z is an exact
1. When
z is exact
0,
exn:fail:contract:divide-by-zero exception is raised.
Examples: |
| > (log (exp 1)) | 1.0 | | > (log 2+3i) | 1.2824746787307684+0.982793723247329i | | > (log 1) | 0 |
|
3.2.2.4 Trignometric Functions
Returns the sine of z, where z is in radians. The
result is normally inexact, but it is exact 0 if z
is exact 0.
Examples: |
| > (sin 3.14159) | 2.65358979335273e-06 | | > (sin 1.0+5.0i) | 62.44551846769653+40.0921657779984i |
|
Returns the cosine of z, where z is in radians.
Examples: |
| > (cos 3.14159) | -0.9999999999964793 | | > (cos 1.0+5.0i) | 40.095806306298826-62.43984868079963i |
|
Returns the tangent of z, where z is in radians. The
result is normally inexact, but it is exact 0 if z
is exact 0.
Examples: |
| > (tan 0.7854) | 1.0000036732118496 | | > (tan 1.0+5.0i) | 8.256719834227411e-05+1.0000377833796008i |
|
Returns the arcsine in radians of z. The result is normally
inexact, but it is exact 0 if z is exact 0.
Examples: |
| > (asin 0.25) | 0.25268025514207865 | | > (asin 1.0+5.0i) | 0.1937931365549321+2.3309746530493123i |
|
Returns the arccosine in radians of z.
Examples: |
| > (acos 0.25) | 1.318116071652818 | | > (acos 1.0+5.0i) | 1.3770031902399644-2.3309746530493123i |
|
In the one-argument case, returns the arctangent of the inexact
approximation of z, except that the result is an exact
0 for an exact 0 argument.
In the two-argument case, the result is roughly the same as (atan (/ (exact->inexact y)) (exact->inexact x)), but the signs of y
and x determine the quadrant of the result. Moreover, a
suitable angle is returned when y divided by x
produces +nan.0 in the case that neither y nor
x is +nan.0. Finally, if y is exact
0 and x is an exact positive number, the result is
exact 0. If both x and y are exact
0, the exn:fail:contract:divide-by-zero exception is raised.
Examples: |
| > (atan 0.5) | 0.4636476090008061 | | > (atan 2 1) | 1.1071487177940904 | | > (atan -2 -1) | -2.0344439357957027 | | > (atan 1.0+5.0i) | 1.530881333938778+0.19442614214700213i | | > (atan +inf.0 -inf.0) | 2.356194490192345 |
|
3.2.2.5 Complex Numbers
Returns
(+ x (* y 0+1i)).
Returns
(+ (* magnitude (cos angle)) (* magnitude (sin angle) 0+1i)).
Returns the real part of the complex number z in rectangle
coordinates.
Returns the imaginary part of the complex number z in
rectangle coordinates.
Returns the magnitude of the complex number z in polar
coordinates.
Returns the angle of
the complex number z in polar coordinates.
Examples: |
| > (angle -3) | 3.141592653589793 | | > (angle 3.0) | 0 | | > (angle 3+4i) | 0.9272952180016122 | | > (angle +inf.0+inf.0i) | 0.7853981633974483 |
|
3.2.2.6 Bitwise Operations
Returns
the bitwise “inclusive or” of the ns in their (semi-infinite)
two’s complement representation. If no arguments are provided, the
result is 0.
Returns
the bitwise “and” of the ns in their (semi-infinite) two’s
complement representation. If no arguments are provided, the result
is -1.
Returns
the bitwise “exclusive or” of the ns in their (semi-infinite)
two’s complement representation. If no arguments are provided, the
result is 0.
Returns the
bitwise “not” of n in its (semi-infinite) two’s complement
representation.
Returns #t when the mth bit of n is set in n’s
(semi-infinite) two’s complement representation.
This operation is equivalent to
(not (zero? (bitwise-and n (arithmetic-shift 1 m)))),
but it is faster and runs in constant time when n is positive.
Extracts the bits between position
start and
(- end 1) (inclusive)
from
n and shifts them down to the least significant portion of the number.
This operation is equivalent to the computation
but it runs in constant time when n is positive, start and
end are fixnums, and (- end start) is no more than
the maximum width of a fixnum.
Each pair of examples below uses the same numbers, showing the result
both in binary and as integers.
Returns the bitwise “shift” of
n in its
(semi-infinite) two’s complement representation. If
m is
non-negative, the integer
n is shifted left by
m bits;
i.e.,
m new zeros are introduced as rightmost digits. If
m is negative,
n is shifted right by
(- m)
bits; i.e., the rightmost
m digits are dropped.
Returns
the number of bits in the (semi-infinite) two’s complement
representation of n after removing all leading zeros (for
non-negative n) or ones (for negative n).
3.2.2.7 Random Numbers
When called with an integer argument k, returns a random
exact integer in the range 0 to k-1. When
called with zero arguments, returns a random inexact number between
0 and 1, exclusive.
In each case, the number is provided by the given pseudo-random number
generator (which defaults to the current one, as produced by
current-pseudo-random-generator). The generator maintains an
internal state for generating numbers. The random number generator
uses a 54-bit version of L’Ecuyer’s MRG32k3a algorithm
[L'Ecuyer02].
Seeds the current pseudo-random number generator with
k. Seeding a generator sets its internal state
deterministically; that is, seeding a generator with a particular
number forces it to produce a sequence of pseudo-random numbers that
is the same across runs and across platforms.
The random-seed function is convenient for some purposes, but
note that the space of states for a pseudo-random number generator is
much larger that the space of allowed values for k. Use
vector->pseudo-random-generator! to set a pseudo-random
number generator to any of its possible states.
Returns a new pseudo-random number generator. The new generator is
seeded with a number derived from
(current-milliseconds).
Returns #t if v is a pseudo-random number generator,
#f otherwise.
A parameter that determines the pseudo-random number generator
used by
random.
Produces a vector that represents the complete internal state of
generator. The vector is suitable as an argument to
vector->pseudo-random-generator to recreate the generator in
its current state (across runs and across platforms).
Produces a pseudo-random number generator whose internal state
corresponds to vec.
Returns #t if v is a vector of six exact integers,
where the first three integers are in the range 0 to
4294967086, inclusive; the last three integers are in the
range 0 to 4294944442, inclusive; at least one of
the first three integers is non-zero; and at least one of the last
three integers is non-zero. Otherwise, the result is #f.
3.2.2.8 Number–String Conversions
Returns a string that is the printed form of
z
in the base specified by
radix. If
z is inexact,
radix must be
10, otherwise the
exn:fail:contract exception is raised.
Reads and returns a number datum from
s (see
Reading Numbers), returning
#f if
s does not
parse exactly as a number datum (with no whitespace). The optional
radix argument specifies the default base for the number,
which can be overridden by
#b,
#o,
#d, or
#x in the string. The
read-decimal-as-inexact
parameter affects
string->number in the same as way as
read.
Prints n into a string and returns the string. The printed
form of n shows exactly decimal-digits digits after
the decimal point. The printed form uses a minus sign if n is
negative, and it does not use a plus sign if n is positive.
Before printing, n is converted to an exact number,
multiplied by (expt 10 decimal-digits), rounded, and then
divided again by (expt 10 decimal-digits). The result of this
process is an exact number whose decimal representation has no more
than decimal-digits digits after the decimal (and it is
padded with trailing zeros if necessary).
Converts the machine-format number encoded in
bstr to an
exact integer. The
start and
end arguments specify
the substring to decode, where
(- end start) must be
2,
4, or
8. If
signed? is true,
then the bytes are decoded as a two’s-complement number, otherwise it
is decoded as an unsigned integer. If
big-endian? is true,
then the first character’s ASCII value provides the most significant
eight bits of the number, otherwise the first character provides the
least-significant eight bits, and so on.
Converts the exact integer n to a machine-format number
encoded in a byte string of length size-n, which must be
2, 4, or 8. If signed? is true,
then the number is encoded as two’s complement, otherwise it is
encoded as an unsigned bit stream. If big-endian? is true,
then the most significant eight bits of the number are encoded in the
first character of the resulting byte string, otherwise the
least-significant bits are encoded in the first byte, and so on.
The dest-bstr argument must be a mutable byte string of
length size-n. The encoding of n is written into
dest-bstr starting at offset start, and
dest-bstr is returned as the result.
If n cannot be encoded in a string of the requested size and
format, the exn:fail:contract exception is raised. If dest-bstr is not
of length size-n, the exn:fail:contract exception is raised.
Converts the IEEE floating-point number encoded in bstr from
position start (inclusive) to end (exclusive) to an
inexact real number. The difference between start an
end must be either 4 or 8 bytes. If big-endian? is
true, then the first byte’s ASCII value provides the most significant
eight bits of the IEEE representation, otherwise the first byte
provides the least-significant eight bits, and so on.
Converts the real number x to its IEEE representation in a
byte string of length size-n, which must be 4 or
8. If big-endian? is true, then the most significant
eight bits of the number are encoded in the first byte of the
resulting byte string, otherwise the least-significant bits are
encoded in the first character, and so on.
The dest-bstr argument must be a mutable byte string of
length size-n. The encoding of n is written into
dest-bstr starting with byte start, and
dest-bstr is returned as the result.
If dest-bstr is provided and it has less than start
plus size-n bytes, the exn:fail:contract exception is raised.
Returns #t if the native encoding of numbers is big-endian
for the machine running Racket, #f if the native encoding
is little-endian.
3.2.2.9 Extra Constants and Functions
An approximation to the ratio of a circle’s circumference to its
diameter: 3.141592653589793.
Returns the sign of x as either -1, 0, or
1.
Returns the complex conjugate of z.
Returns the hyperbolic sine of z.
Returns the hyperbolic cosine of z.
Returns the hyperbolic tangent of z.
Computes the greatest exact integer m such that:
Hence also: