17b8092641
An extflonum is like a flonum, but with 80-bit precision and not a number in the sense of `number?': only operations such as `extfl+' work on extflonums, and only on platforms where extflonums can be implemented by hardware without interefering with flonums (i.e., on platforms where SSE instructions are used for double-precision floats). [Patch provided by Michael Filonenko and revised by Matthew.] The compiler tracks information about bindings that are known to hold extflonums, but the JIT does not yet exploit this information to unbox them (except as intermediate results).
1203 lines
42 KiB
Racket
1203 lines
42 KiB
Racket
#lang scribble/doc
|
|
@(require "mz.rkt" racket/math scribble/extract
|
|
(for-label racket/math
|
|
racket/flonum
|
|
racket/fixnum
|
|
racket/unsafe/ops
|
|
racket/require))
|
|
|
|
@(define math-eval (make-base-eval))
|
|
@(interaction-eval #:eval math-eval (require racket/math))
|
|
|
|
@title[#:tag "numbers" #:style '(toc)]{Numbers}
|
|
|
|
@guideintro["numbers"]{numbers}
|
|
|
|
All @deftech{numbers} are @deftech{complex numbers}. Some of them are
|
|
@deftech{real numbers}, and all of the real numbers that can be
|
|
represented are also @deftech{rational numbers}, except for
|
|
@as-index{@racket[+inf.0]} (positive @as-index{infinity}), @as-index{@racket[+inf.f]} (single-precision variant),
|
|
@as-index{@racket[-inf.0]} (negative infinity), @as-index{@racket[-inf.f]} (single-precision variant),
|
|
@as-index{@racket[+nan.0]} (@as-index{not-a-number}), and @as-index{@racket[+nan.f]} (single-precision variant). Among the
|
|
rational numbers, some are @deftech{integers}, because @racket[round]
|
|
applied to the number produces the same number.
|
|
|
|
@margin-note/ref{See @secref["parse-number"] for information on the
|
|
syntax of number literals.}
|
|
|
|
Orthogonal to those categories, each number is also either an
|
|
@deftech{exact number} or an @deftech{inexact number}. Unless
|
|
otherwise specified, computations that involve an inexact number
|
|
produce inexact results. Certain operations on inexact numbers,
|
|
however, produce an exact number, such as multiplying an inexact
|
|
number with an exact @racket[0]. Some operations, which can produce an
|
|
irrational number for rational arguments (e.g., @racket[sqrt]), may
|
|
produce inexact results even for exact arguments.
|
|
|
|
In the case of complex numbers, either the real and imaginary parts
|
|
are both exact or inexact, or the number has an exact zero real part
|
|
and an inexact imaginary part; a complex number with an exact zero
|
|
imaginary part is a real number.
|
|
|
|
Inexact real numbers are implemented as either single- or
|
|
double-precision @as-index{IEEE floating-point numbers}---the latter
|
|
by default, and the former only when a computation starts with
|
|
numerical constants specified as single-precision numbers. Inexact
|
|
real numbers that are represented as double-precision floating-point
|
|
numbers are @deftech{flonums}.
|
|
|
|
The precision and size of exact numbers is limited only by available
|
|
memory (and the precision of operations that can produce irrational
|
|
numbers). In particular, adding, multiplying, subtracting, and
|
|
dividing exact numbers always produces an exact result.
|
|
|
|
Inexact numbers can be coerced to exact form, except for the inexact
|
|
numbers @racket[+inf.0], @racket[+inf.f],
|
|
@racket[-inf.0], @racket[-inf.f], @racket[+nan.0], and @racket[+nan.f], which
|
|
have no exact form. @index["division by inexact zero"]{Dividing} a
|
|
number by exact zero raises an exception; dividing a non-zero number
|
|
other than @racket[+nan.0] or @racket[+nan.f] by an inexact zero returns @racket[+inf.0],
|
|
@racket[+inf.f], @racket[-inf.0]
|
|
or @racket[-inf.f], depending on the sign and precision of the dividend. The
|
|
@racket[+nan.0] value is not @racket[=] to itself, but @racket[+nan.0]
|
|
is @racket[eqv?] to itself, and @racket[+nan.f] is similarly @racket[eqv?] but
|
|
not @racket[=] to itself. Conversely, @racket[(= 0.0 -0.0)] is
|
|
@racket[#t], but @racket[(eqv? 0.0 -0.0)] is @racket[#f], and the
|
|
same for @racket[0.0f0] and @racket[-0.0f0] (which are single-precision variants). The datum
|
|
@racketvalfont{-nan.0} refers to the same constant as @racket[+nan.0],
|
|
and @racketvalfont{-nan.f} is the same as @racket[+nan.f].
|
|
|
|
Calculations with infinites produce results consistent with IEEE
|
|
double- or single-precision floating point where IEEE specifies the result; in
|
|
cases where IEEE provides no specification, such as @racket[(angle
|
|
+inf.0+inf.0i)], the result corresponds to the limit approaching
|
|
infinity, or @racket[+nan.0] or @racket[+nan.f] if no such limit exists.
|
|
|
|
A @deftech{fixnum} is an exact integer whose two's complement
|
|
representation fit into 31 bits on a 32-bit platform or 63 bits on a
|
|
64-bit platform; furthermore, no allocation is required when computing
|
|
with fixnums. See also the @racketmodname[racket/fixnum] module, below.
|
|
|
|
Two fixnums that are @racket[=] are also the same
|
|
according to @racket[eq?]. Otherwise, the result of @racket[eq?]
|
|
applied to two numbers is undefined, except that numbers produced
|
|
by the default reader in @racket[read-syntax] mode are @tech{interned} and therefore @racket[eq?]
|
|
when they are @racket[eqv?].
|
|
|
|
Two numbers are @racket[eqv?] when they are both inexact with the same precision or both
|
|
exact, and when they are @racket[=] (except for @racket[+nan.0], @racket[+nan.f],
|
|
@racket[+0.0], @racket[+0.0f0], @racket[-0.0], and @racket[-0.0f0], as noted above). Two numbers are
|
|
@racket[equal?] when they are @racket[eqv?].
|
|
|
|
@see-read-print["number"]{numbers}
|
|
|
|
@local-table-of-contents[]
|
|
|
|
@; ----------------------------------------
|
|
@section[#:tag "number-types"]{Number Types}
|
|
|
|
@defproc[(number? [v any/c]) boolean?]{Returns @racket[#t] if @racket[v]
|
|
is a number, @racket[#f] otherwise.
|
|
|
|
@mz-examples[(number? 1) (number? 2+3i) (number? "hello")]}
|
|
|
|
|
|
@defproc[(complex? [v any/c]) boolean?]{ Returns @racket[(number? v)],
|
|
because all numbers are @tech{complex numbers}.}
|
|
|
|
|
|
@defproc[(real? [v any/c]) boolean?]{ Returns @racket[#t] if @racket[v] is
|
|
a @techlink{real number}, @racket[#f] otherwise.
|
|
|
|
@mz-examples[(real? 1) (real? +inf.0) (real? 2+3i)
|
|
(real? 2+0.0i) (real? "hello")]}
|
|
|
|
|
|
@defproc[(rational? [v any/c]) boolean?]{ Returns @racket[#t] if
|
|
@racket[v] is a @techlink{rational number}, @racket[#f] otherwise.
|
|
|
|
@mz-examples[(rational? 1) (rational? +inf.0) (rational? "hello")]}
|
|
|
|
|
|
@defproc[(integer? [v any/c]) boolean?]{ Returns @racket[#t] if @racket[v]
|
|
is a number that is an @techlink{integer}, @racket[#f] otherwise.
|
|
|
|
@mz-examples[(integer? 1) (integer? 2.3) (integer? 4.0) (integer? +inf.0)
|
|
(integer? 2+3i) (integer? "hello")]}
|
|
|
|
|
|
@defproc[(exact-integer? [v any/c]) boolean?]{
|
|
|
|
Returns @racket[(and (integer? v) (exact? v))].
|
|
|
|
@mz-examples[(exact-integer? 1) (exact-integer? 4.0)]}
|
|
|
|
|
|
@defproc[(exact-nonnegative-integer? [v any/c]) boolean?]{
|
|
|
|
Returns @racket[(and (exact-integer? v) (not (negative? v)))].
|
|
|
|
@mz-examples[(exact-nonnegative-integer? 0) (exact-nonnegative-integer? -1)]}
|
|
|
|
|
|
@defproc[(exact-positive-integer? [v any/c]) boolean?]{
|
|
|
|
Returns @racket[(and (exact-integer? v) (positive? v))].
|
|
|
|
@mz-examples[(exact-positive-integer? 1) (exact-positive-integer? 0)]}
|
|
|
|
|
|
@defproc[(inexact-real? [v any/c]) boolean?]{
|
|
|
|
Returns @racket[(and (real? v) (inexact? v))].}
|
|
|
|
|
|
@defproc[(fixnum? [v any/c]) boolean?]{
|
|
|
|
Return @racket[#t] if @racket[v] is a @techlink{fixnum}, @racket[#f]
|
|
otherwise.
|
|
|
|
Note: the result of this function is platform-dependent, so using it in
|
|
syntax transformers can lead to platform-dependent bytecode files.}
|
|
|
|
|
|
@defproc[(flonum? [v any/c]) boolean?]{
|
|
|
|
Return @racket[#t] if @racket[v] is a @techlink{flonum}, @racket[#f]
|
|
otherwise.}
|
|
|
|
@defproc[(double-flonum? [v any/c]) boolean?]{
|
|
Identical to @racket[flonum?]}.
|
|
|
|
@defproc[(single-flonum? [v any/c]) boolean?]{
|
|
Return @racket[#t] if @racket[v] is a single-precision floating-point
|
|
number, @racket[#f] otherwise.}
|
|
|
|
@defproc[(zero? [z number?]) boolean?]{ Returns @racket[(= 0 z)].
|
|
|
|
@mz-examples[(zero? 0) (zero? -0.0)]}
|
|
|
|
|
|
@defproc[(positive? [x real?]) boolean?]{ Returns @racket[(> x 0)].
|
|
|
|
@mz-examples[(positive? 10) (positive? -10) (positive? 0.0)]}
|
|
|
|
|
|
@defproc[(negative? [x real?]) boolean?]{ Returns @racket[(< x 0)].
|
|
|
|
@mz-examples[(negative? 10) (negative? -10) (negative? -0.0)]}
|
|
|
|
|
|
@defproc[(even? [n integer?]) boolean?]{ Returns @racket[(zero? (modulo
|
|
n 2))].
|
|
|
|
@mz-examples[(even? 10.0) (even? 11) (even? +inf.0)]}
|
|
|
|
|
|
@defproc[(odd? [n integer?]) boolean?]{ Returns @racket[(not (even? n))].
|
|
|
|
@mz-examples[(odd? 10.0) (odd? 11) (odd? +inf.0)]}
|
|
|
|
|
|
@defproc[(exact? [z number?]) boolean?]{ Returns @racket[#t] if @racket[z]
|
|
is an exact number, @racket[#f] otherwise.
|
|
|
|
@mz-examples[(exact? 1) (exact? 1.0)]}
|
|
|
|
|
|
@defproc[(inexact? [z number?]) boolean?]{ Returns @racket[#t] if @racket[z]
|
|
is an inexact number, @racket[#f] otherwise.
|
|
|
|
@mz-examples[(inexact? 1) (inexact? 1.0)]}
|
|
|
|
|
|
@defproc[(inexact->exact [z number?]) exact?]{ Coerces @racket[z] to an
|
|
exact number. If @racket[z] is already exact, it is returned. If @racket[z]
|
|
is @racket[+inf.0], @racket[-inf.0], or @racket[+nan.0], then the
|
|
@exnraise[exn:fail:contract].
|
|
|
|
@mz-examples[(inexact->exact 1) (inexact->exact 1.0)]}
|
|
|
|
|
|
@defproc[(exact->inexact [z number?]) inexact?]{ Coerces @racket[z] to an
|
|
inexact number. If @racket[z] is already inexact, it is returned.
|
|
|
|
@mz-examples[(exact->inexact 1) (exact->inexact 1.0)]}
|
|
|
|
@defproc[(real->single-flonum [x real?]) single-flonum?]{ Coerces @racket[x]
|
|
to a single-precision floating-point number. If @racket[x] is already
|
|
a single-precision floating-point number, it is returned.}
|
|
|
|
@defproc[(real->double-flonum [x real?]) flonum?]{ Coerces @racket[x]
|
|
to a double-precision floating-point number. If @racket[x] is already
|
|
a double-precision floating-point number, it is returned.}
|
|
|
|
@; ----------------------------------------
|
|
@section[#:tag "generic-numbers"]{Generic Numerics}
|
|
|
|
Most Racket numeric operations work on any kind of number.
|
|
|
|
@; ----------------------------------------
|
|
@subsection{Arithmetic}
|
|
|
|
@defproc[(+ [z number?] ...) number?]{
|
|
|
|
Returns the sum of the @racket[z]s, adding pairwise from left to
|
|
right. If no arguments are provided, the result is @racket[0].
|
|
|
|
@mz-examples[(+ 1 2) (+ 1.0 2+3i 5) (+)]}
|
|
|
|
|
|
@defproc*[([(- [z number?]) number?]
|
|
[(- [z number?] [w number?] ...+) number?])]{
|
|
|
|
When no @racket[w]s are supplied, returns @racket[(- 0 z)].
|
|
Otherwise, returns the subtraction of the @racket[w]s from @racket[z]
|
|
working pairwise from left to right.}
|
|
|
|
@mz-examples[(- 5 3.0) (- 1) (- 2+7i 1 3)]
|
|
|
|
|
|
@defproc[(* [z number?] ...) number?]{
|
|
|
|
Returns the product of the @racket[z]s, multiplying pairwise from left
|
|
to right. If no arguments are provided, the result is
|
|
@racket[1]. Multiplying any number by exact @racket[0] produces exact
|
|
@racket[0].
|
|
|
|
@mz-examples[(* 2 3) (* 8.0 9) (* 1+2i 3+4i)]}
|
|
|
|
|
|
@defproc*[([(/ [z number?]) number?]
|
|
[(/ [z number?] [w number?] ...+) number?])]{
|
|
|
|
When no @racket[w]s are supplied, returns @racket[(/ 1 z)].
|
|
Otherwise, returns the division of @racket[z] by the @racket[w]s working
|
|
pairwise from left to right.
|
|
|
|
If @racket[z] is exact @racket[0] and no @racket[w] is exact
|
|
@racket[0], then the result is exact @racket[0]. If any @racket[w] is
|
|
exact @racket[0], the @exnraise[exn:fail:contract:divide-by-zero].
|
|
|
|
@mz-examples[(/ 3 4) (/ 81 3 3) (/ 10.0) (/ 1+2i 3+4i)]}
|
|
|
|
|
|
@defproc[(quotient [n integer?] [m integer?]) integer?]{
|
|
|
|
Returns @racket[(truncate (/ n m))].
|
|
|
|
@mz-examples[(quotient 10 3) (quotient -10.0 3) (quotient +inf.0 3)]}
|
|
|
|
|
|
@defproc[(remainder [n integer?] [m integer?]) integer?]{
|
|
|
|
Returns @racket[_q] with the same sign as @racket[n] such that
|
|
|
|
@itemize[
|
|
|
|
@item{@racket[(abs _q)] is between @racket[0] (inclusive) and @racket[(abs m)] (exclusive), and}
|
|
|
|
@item{@racket[(+ _q (* m (quotient n m)))] equals @racket[n].}
|
|
|
|
]
|
|
|
|
If @racket[m] is exact @racket[0], the
|
|
@exnraise[exn:fail:contract:divide-by-zero].
|
|
|
|
@mz-examples[(remainder 10 3) (remainder -10.0 3) (remainder 10.0 -3) (remainder -10 -3) (remainder +inf.0 3)]}
|
|
|
|
|
|
@defproc[(quotient/remainder [n integer?] [m integer?]) (values integer? integer?)]{
|
|
|
|
Returns @racket[(values (quotient n m) (remainder n m))], but the
|
|
combination may be computed more efficiently than separate calls to
|
|
@racket[quotient] and @racket[remainder].
|
|
|
|
@mz-examples[
|
|
(quotient/remainder 10 3)
|
|
]}
|
|
|
|
|
|
@defproc[(modulo [n integer?] [m integer?]) integer?]{
|
|
|
|
Returns @racket[_q] with the same sign as @racket[m] where
|
|
|
|
@itemize[
|
|
|
|
@item{@racket[(abs _q)] is between @racket[0] (inclusive) and @racket[(abs m)] (exclusive), and}
|
|
|
|
@item{the difference between @racket[_q] and @racket[(- n (* m (quotient n m)))] is a multiple of @racket[m].}
|
|
|
|
]
|
|
|
|
If @racket[m] is exact @racket[0], the
|
|
@exnraise[exn:fail:contract:divide-by-zero].
|
|
|
|
@mz-examples[(modulo 10 3) (modulo -10.0 3) (modulo 10.0 -3) (modulo -10 -3) (modulo +inf.0 3)]}
|
|
|
|
|
|
@defproc[(add1 [z number?]) number?]{ Returns @racket[(+ z 1)].}
|
|
|
|
@defproc[(sub1 [z number?]) number?]{ Returns @racket[(- z 1)].}
|
|
|
|
@defproc[(abs [x real?]) number?]{ Returns the absolute value of
|
|
@racket[x].
|
|
|
|
@mz-examples[(abs 1.0) (abs -1)]}
|
|
|
|
@defproc[(max [x real?] ...+) real?]{
|
|
|
|
Returns the largest of the @racket[x]s, or @racket[+nan.0] if any
|
|
@racket[x] is @racket[+nan.0]. If any @racket[x] is inexact, the
|
|
result is coerced to inexact.
|
|
|
|
@mz-examples[(max 1 3 2) (max 1 3 2.0)]}
|
|
|
|
|
|
@defproc[(min [x real?] ...+) real?]{
|
|
|
|
Returns the smallest of the @racket[x]s, or @racket[+nan.0] if any
|
|
@racket[x] is @racket[+nan.0]. If any @racket[x] is inexact, the
|
|
result is coerced to inexact.
|
|
|
|
@mz-examples[(min 1 3 2) (min 1 3 2.0)]}
|
|
|
|
|
|
@defproc[(gcd [n rational?] ...) rational?]{
|
|
|
|
Returns the @as-index{greatest common divisor} (a non-negative
|
|
number) of the @racket[n]s; for non-integer @racket[n]s, the result
|
|
is the @racket[gcd] of the numerators divided
|
|
by the @racket[lcm] of the denominators.
|
|
If no arguments are provided, the result
|
|
is @racket[0]. If all arguments are zero, the result is zero.
|
|
|
|
@mz-examples[(gcd 10) (gcd 12 81.0) (gcd 1/2 1/3)]}
|
|
|
|
|
|
@defproc[(lcm [n rational?] ...) rational?]{
|
|
|
|
Returns the @as-index{least common multiple} (a non-negative number)
|
|
of the @racket[n]s; non-integer @racket[n]s, the result is
|
|
the absolute value of the product divided by the
|
|
@racket[gcd]. If no arguments are provided, the result is
|
|
@racket[1]. If any argument is zero, the result is zero; furthermore,
|
|
if any argument is exact @racket[0], the result is exact @racket[0].
|
|
|
|
@mz-examples[(lcm 10) (lcm 3 4.0) (lcm 1/2 2/3)]}
|
|
|
|
|
|
@defproc[(round [x real?]) (or/c integer? +inf.0 -inf.0 +nan.0)]{
|
|
|
|
Returns the integer closest to @racket[x], resolving ties in favor of
|
|
an even number, but @racket[+inf.0], @racket[-inf.0], and @racket[+nan.0]
|
|
round to themselves.
|
|
|
|
@mz-examples[(round 17/4) (round -17/4) (round 2.5) (round -2.5) (round +inf.0)]}
|
|
|
|
|
|
@defproc[(floor [x real?]) (or/c integer? +inf.0 -inf.0 +nan.0)]{
|
|
|
|
Returns the largest integer that is no more than @racket[x], but
|
|
@racket[+inf.0], @racket[-inf.0], and @racket[+nan.0] floor to
|
|
themselves.
|
|
|
|
@mz-examples[(floor 17/4) (floor -17/4) (floor 2.5) (floor -2.5) (floor +inf.0)]}
|
|
|
|
|
|
@defproc[(ceiling [x real?]) (or/c integer? +inf.0 -inf.0 +nan.0)]{
|
|
|
|
Returns the smallest integer that is at least as large as @racket[x],
|
|
but @racket[+inf.0], @racket[-inf.0], and @racket[+nan.0] ceiling to
|
|
themselves.
|
|
|
|
@mz-examples[(ceiling 17/4) (ceiling -17/4) (ceiling 2.5) (ceiling -2.5) (ceiling +inf.0)]}
|
|
|
|
|
|
@defproc[(truncate [x real?]) (or/c integer? +inf.0 -inf.0 +nan.0)]{
|
|
|
|
Returns the integer farthest from @racket[0] that is not farther from
|
|
@racket[0] than @racket[x], but @racket[+inf.0], @racket[-inf.0], and
|
|
@racket[+nan.0] truncate to themselves.
|
|
|
|
@mz-examples[(truncate 17/4) (truncate -17/4) (truncate 2.5) (truncate -2.5) (truncate +inf.0)]}
|
|
|
|
|
|
@defproc[(numerator [q rational?]) integer?]{
|
|
|
|
Coerces @racket[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 @racket[q].
|
|
|
|
@mz-examples[(numerator 5) (numerator 34/8) (numerator 2.3)]}
|
|
|
|
|
|
@defproc[(denominator [q rational?]) integer?]{
|
|
|
|
Coerces @racket[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 @racket[q].
|
|
|
|
@mz-examples[(denominator 5) (denominator 34/8) (denominator 2.3)]}
|
|
|
|
|
|
@defproc[(rationalize [x real?] [tolerance real?]) real?]{
|
|
|
|
Among the real numbers within @racket[(abs tolerance)] of @racket[x],
|
|
returns the one corresponding to an exact number whose
|
|
@racket[denominator] is the smallest. If multiple integers are within
|
|
@racket[tolerance] of @racket[x], the one closest to @racket[0] is
|
|
used.
|
|
|
|
@mz-examples[
|
|
(rationalize 1/4 1/10)
|
|
(rationalize -1/4 1/10)
|
|
(rationalize 1/4 1/4)
|
|
(rationalize 11/40 1/4)
|
|
]}
|
|
|
|
@; ----------------------------------------
|
|
@subsection{Number Comparison}
|
|
|
|
@defproc[(= [z number?] [w number?] ...+) boolean?]{ Returns
|
|
@racket[#t] if all of the arguments are numerically equal,
|
|
@racket[#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, @racket[0.0] and @racket[-0.0] are numerically
|
|
equal, but @racket[+nan.0] is not numerically equal to itself.
|
|
|
|
@mz-examples[(= 1 1.0) (= 1 2) (= 2+3i 2+3i 2+3i)]}
|
|
|
|
|
|
@defproc[(< [x real?] [y real?] ...+) boolean?]{ Returns @racket[#t] if
|
|
the arguments in the given order are strictly increasing,
|
|
@racket[#f] otherwise.
|
|
|
|
@mz-examples[(< 1 1) (< 1 2 3) (< 1 +inf.0) (< 1 +nan.0)]}
|
|
|
|
|
|
@defproc[(<= [x real?] [y real?] ...+) boolean?]{ Returns @racket[#t]
|
|
if the arguments in the given order are non-decreasing,
|
|
@racket[#f] otherwise.
|
|
|
|
@mz-examples[(<= 1 1) (<= 1 2 1)]}
|
|
|
|
|
|
@defproc[(> [x real?] [y real?] ...+) boolean?]{ Returns @racket[#t] if
|
|
the arguments in the given order are strictly decreasing,
|
|
@racket[#f] otherwise.
|
|
|
|
@mz-examples[(> 1 1) (> 3 2 1) (> +inf.0 1) (> +nan.0 1)]}
|
|
|
|
|
|
@defproc[(>= [x real?] [y real?] ...+) boolean?]{ Returns @racket[#t]
|
|
if the arguments in the given order are non-increasing,
|
|
@racket[#f] otherwise.
|
|
|
|
@mz-examples[(>= 1 1) (>= 1 2 1)]}
|
|
|
|
|
|
@; ------------------------------------------------------------------------
|
|
@subsection{Powers and Roots}
|
|
|
|
@defproc[(sqrt [z number?]) number?]{
|
|
|
|
Returns the principal @as-index{square root} of @racket[z]. The
|
|
result is exact if @racket[z] is exact and @racket[z]'s square root
|
|
is rational. See also @racket[integer-sqrt].
|
|
|
|
@mz-examples[(sqrt 4/9) (sqrt 2) (sqrt -1)]}
|
|
|
|
|
|
@defproc[(integer-sqrt [n integer?]) complex?]{
|
|
|
|
Returns @racket[(floor (sqrt n))] for positive @racket[n]. For
|
|
negative @racket[n], the result is @racket[(* (integer-sqrt (- n))
|
|
0+i)].
|
|
|
|
@mz-examples[(integer-sqrt 4.0) (integer-sqrt 5)]}
|
|
|
|
|
|
@defproc[(integer-sqrt/remainder [n integer?])
|
|
(values complex? integer?)]{
|
|
|
|
Returns @racket[(integer-sqrt n)] and @racket[(- n (expt
|
|
(integer-sqrt n) 2))].
|
|
|
|
@mz-examples[(integer-sqrt/remainder 4.0) (integer-sqrt/remainder 5)]}
|
|
|
|
|
|
@defproc[(expt [z number?] [w number?]) number?]{
|
|
|
|
Returns @racket[z] raised to the power of @racket[w].
|
|
|
|
If @racket[w] is
|
|
exact @racket[0], the result is exact @racket[1].
|
|
If @racket[w] is @racket[0.0] or @racket[-0.0] and @racket[z] is a @tech{real number}, the
|
|
result is @racket[1.0] (even if @racket[z] is @racket[+nan.0]).
|
|
|
|
If @racket[z] is exact @racket[1], the result is exact @racket[1].
|
|
If @racket[z] is @racket[1.0] and @racket[w] is a @tech{real number}, the
|
|
result is @racket[1.0] (even if @racket[w] is @racket[+nan.0]).
|
|
|
|
If @racket[z] is
|
|
exact @racket[0] and @racket[w] is negative, the
|
|
@exnraise[exn:fail:contract:divide-by-zero].
|
|
|
|
Further special cases when @racket[w] is a @tech{real number}:
|
|
@margin-note*{These special cases correspond to @tt{pow} in C99 @cite["C99"],
|
|
except when @racket[z] is negative and @racket[w] is a not an
|
|
integer.}
|
|
@;
|
|
@itemlist[#:style 'compact
|
|
|
|
@item{@racket[(expt 0.0 w)]:
|
|
@itemlist[#:style 'compact
|
|
@item{@racket[w] is negative --- @racket[+inf.0]}
|
|
@item{@racket[w] is positive --- @racket[0.0]}]}
|
|
|
|
@item{@racket[(expt -0.0 w)]:
|
|
@itemlist[#:style 'compact
|
|
@item{@racket[w] is negative:
|
|
@itemlist[#:style 'compact
|
|
@item{@racket[w] is an odd integer --- @racket[-inf.0]}
|
|
@item{@racket[w] otherwise rational --- @racket[+inf.0]}]}
|
|
@item{@racket[w] is positive:
|
|
@itemlist[#:style 'compact
|
|
@item{@racket[w] is an odd integer --- @racket[-0.0]}
|
|
@item{@racket[w] otherwise rational --- @racket[+0.0]}]}]}
|
|
|
|
@item{@racket[(expt z -inf.0)] for positive @racket[z]:
|
|
@itemlist[#:style 'compact
|
|
@item{@racket[z] is less than @racket[1.0] --- @racket[+inf.0]}
|
|
@item{@racket[z] is greater than @racket[1.0] --- @racket[+0.0]}]}
|
|
|
|
@item{@racket[(expt z +inf.0)] for positive @racket[z]:
|
|
@itemlist[#:style 'compact
|
|
@item{@racket[z] is less than @racket[1.0] --- @racket[+0.0]}
|
|
@item{@racket[z] is greater than @racket[1.0] --- @racket[+inf.0]}]}
|
|
|
|
@item{@racket[(expt -inf.0 w)] for integer @racket[w]:
|
|
@itemlist[#:style 'compact
|
|
@item{@racket[w] is negative:
|
|
@itemlist[#:style 'compact
|
|
@item{@racket[w] is odd --- @racket[-0.0]}
|
|
@item{@racket[w] is even --- @racket[+0.0]}]}
|
|
@item{@racket[w] is positive:
|
|
@itemlist[#:style 'compact
|
|
@item{@racket[w] is odd --- @racket[-inf.0]}
|
|
@item{@racket[w] is even --- @racket[+inf.0]}]}]}
|
|
|
|
@item{@racket[(expt +inf.0 w)]:
|
|
@itemlist[#:style 'compact
|
|
@item{@racket[w] is negative --- @racket[+0.0]}
|
|
@item{@racket[w] is positive --- @racket[+inf.0]}]}
|
|
]
|
|
|
|
@mz-examples[(expt 2 3) (expt 4 0.5) (expt +inf.0 0)]}
|
|
|
|
|
|
@defproc[(exp [z number?]) number?]{
|
|
|
|
Returns Euler's number raised to the power of @racket[z]. The result
|
|
is normally inexact, but it is exact @racket[1] when @racket[z] is an
|
|
exact @racket[0].
|
|
|
|
@mz-examples[(exp 1) (exp 2+3i) (exp 0)]}
|
|
|
|
|
|
@defproc[(log [z number?]) number?]{
|
|
|
|
Returns the natural logarithm of @racket[z]. The result is normally
|
|
inexact, but it is exact @racket[0] when @racket[z] is an exact
|
|
@racket[1]. When @racket[z] is exact @racket[0],
|
|
@exnraise[exn:fail:contract:divide-by-zero].
|
|
|
|
@mz-examples[(log (exp 1)) (log 2+3i) (log 1)]}
|
|
|
|
|
|
@; ------------------------------------------------------------------------
|
|
@subsection{Trigonometric Functions}
|
|
|
|
@defproc[(sin [z number?]) number?]{
|
|
|
|
Returns the sine of @racket[z], where @racket[z] is in radians. The
|
|
result is normally inexact, but it is exact @racket[0] if @racket[z]
|
|
is exact @racket[0].
|
|
|
|
@mz-examples[(sin 3.14159) (sin 1+05.i)]}
|
|
|
|
|
|
@defproc[(cos [z number?]) number?]{
|
|
|
|
Returns the cosine of @racket[z], where @racket[z] is in radians.
|
|
|
|
@mz-examples[(cos 3.14159) (cos 1+05.i)]}
|
|
|
|
|
|
@defproc[(tan [z number?]) number?]{
|
|
|
|
Returns the tangent of @racket[z], where @racket[z] is in radians. The
|
|
result is normally inexact, but it is exact @racket[0] if @racket[z]
|
|
is exact @racket[0].
|
|
|
|
@mz-examples[(tan 0.7854) (tan 1+05.i)]}
|
|
|
|
|
|
@defproc[(asin [z number?]) number?]{
|
|
|
|
Returns the arcsine in radians of @racket[z]. The result is normally
|
|
inexact, but it is exact @racket[0] if @racket[z] is exact @racket[0].
|
|
|
|
@mz-examples[(asin 0.25) (asin 1+05.i)]}
|
|
|
|
|
|
@defproc[(acos [z number?]) number?]{
|
|
|
|
Returns the arccosine in radians of @racket[z].
|
|
|
|
@mz-examples[(acos 0.25) (acos 1+05.i)]}
|
|
|
|
|
|
@defproc*[([(atan [z number?]) number?]
|
|
[(atan [y real?] [x real?]) number?])]{
|
|
|
|
In the one-argument case, returns the arctangent of the inexact
|
|
approximation of @racket[z], except that the result is an exact
|
|
@racket[0] for an exact @racket[0] argument.
|
|
|
|
In the two-argument case, the result is roughly the same as @racket[
|
|
(atan (/ (exact->inexact y)) (exact->inexact x))], but the signs of @racket[y]
|
|
and @racket[x] determine the quadrant of the result. Moreover, a
|
|
suitable angle is returned when @racket[y] divided by @racket[x]
|
|
produces @racket[+nan.0] in the case that neither @racket[y] nor
|
|
@racket[x] is @racket[+nan.0]. Finally, if @racket[y] is exact
|
|
@racket[0] and @racket[x] is an exact positive number, the result is
|
|
exact @racket[0]. If both @racket[x] and @racket[y] are exact
|
|
@racket[0], the @exnraise[exn:fail:contract:divide-by-zero].
|
|
|
|
@mz-examples[(atan 0.5) (atan 2 1) (atan -2 -1) (atan 1+05.i) (atan +inf.0 -inf.0)]}
|
|
|
|
@; ------------------------------------------------------------------------
|
|
@subsection{Complex Numbers}
|
|
|
|
@defproc[(make-rectangular [x real?] [y real?]) number?]{
|
|
|
|
Returns @racket[(+ x (* y 0+1i))].
|
|
|
|
@mz-examples[(make-rectangular 3 4.0)]}
|
|
|
|
|
|
@defproc[(make-polar [magnitude real?] [angle real?]) number?]{
|
|
|
|
Returns @racket[(+ (* magnitude (cos angle)) (* magnitude (sin angle)
|
|
0+1i))].
|
|
|
|
@mz-examples[#:eval math-eval
|
|
(make-polar 10 (* pi 1/2))
|
|
(make-polar 10 (* pi 1/4))]}
|
|
|
|
|
|
@defproc[(real-part [z number?]) real?]{
|
|
|
|
Returns the real part of the complex number @racket[z] in rectangle
|
|
coordinates.
|
|
|
|
@mz-examples[(real-part 3+4i) (real-part 5.0)]}
|
|
|
|
|
|
@defproc[(imag-part [z number?]) real?]{
|
|
|
|
Returns the imaginary part of the complex number @racket[z] in
|
|
rectangle coordinates.
|
|
|
|
@mz-examples[(imag-part 3+4i) (imag-part 5.0) (imag-part 5.0+0.0i)]}
|
|
|
|
|
|
@defproc[(magnitude [z number?]) (and/c real? (not/c negative?))]{
|
|
|
|
Returns the magnitude of the complex number @racket[z] in polar
|
|
coordinates.
|
|
|
|
@mz-examples[(magnitude -3) (magnitude 3.0) (magnitude 3+4i)]}
|
|
|
|
|
|
@defproc[(angle [z number?]) real?]{ Returns the angle of
|
|
the complex number @racket[z] in polar coordinates.
|
|
|
|
The result is guaranteed to be between @racket[(- pi)] and
|
|
@racket[pi], possibly equal to @racket[pi] (but never equal
|
|
to @racket[(- pi)]).
|
|
|
|
@mz-examples[(angle -3) (angle 3.0) (angle 3+4i) (angle +inf.0+inf.0i) (angle -1)]}
|
|
|
|
@; ------------------------------------------------------------------------
|
|
@subsection{Bitwise Operations}
|
|
|
|
@section-index{logical operators}
|
|
|
|
@defproc[(bitwise-ior [n exact-integer?] ...) exact-integer?]{ Returns
|
|
the bitwise ``inclusive or'' of the @racket[n]s in their (semi-infinite)
|
|
two's complement representation. If no arguments are provided, the
|
|
result is @racket[0].
|
|
|
|
@mz-examples[(bitwise-ior 1 2) (bitwise-ior -32 1)]}
|
|
|
|
|
|
@defproc[(bitwise-and [n exact-integer?] ...) exact-integer?]{ Returns
|
|
the bitwise ``and'' of the @racket[n]s in their (semi-infinite) two's
|
|
complement representation. If no arguments are provided, the result
|
|
is @racket[-1].
|
|
|
|
@mz-examples[(bitwise-and 1 2) (bitwise-and -32 -1)]}
|
|
|
|
|
|
@defproc[(bitwise-xor [n exact-integer?] ...) exact-integer?]{ Returns
|
|
the bitwise ``exclusive or'' of the @racket[n]s in their (semi-infinite)
|
|
two's complement representation. If no arguments are provided, the
|
|
result is @racket[0].
|
|
|
|
@mz-examples[(bitwise-xor 1 5) (bitwise-xor -32 -1)]}
|
|
|
|
|
|
@defproc[(bitwise-not [n exact-integer?]) exact-integer?]{ Returns the
|
|
bitwise ``not'' of @racket[n] in its (semi-infinite) two's complement
|
|
representation.
|
|
|
|
@mz-examples[(bitwise-not 5) (bitwise-not -1)]}
|
|
|
|
|
|
@defproc[(bitwise-bit-set? [n exact-integer?] [m exact-nonnegative-integer?])
|
|
boolean?]{
|
|
|
|
Returns @racket[#t] when the @racket[m]th bit of @racket[n] is set in @racket[n]'s
|
|
(semi-infinite) two's complement representation.
|
|
|
|
This operation is equivalent to
|
|
@racket[(not (zero? (bitwise-and n (arithmetic-shift 1 m))))],
|
|
but it is faster and runs in constant time when @racket[n] is positive.
|
|
|
|
@mz-examples[(bitwise-bit-set? 5 0) (bitwise-bit-set? 5 2) (bitwise-bit-set? -5 (expt 2 700))]}
|
|
|
|
|
|
@defproc[(bitwise-bit-field [n exact-integer?]
|
|
[start exact-nonnegative-integer?]
|
|
[end (and/c exact-nonnegative-integer?
|
|
(start . <= . end))])
|
|
exact-integer?]{
|
|
|
|
Extracts the bits between position @racket[start] and @racket[(- end 1)] (inclusive)
|
|
from @racket[n] and shifts them down to the least significant portion of the number.
|
|
|
|
This operation is equivalent to the computation
|
|
|
|
@racketblock[
|
|
(bitwise-and (sub1 (arithmetic-shift 1 (- end start)))
|
|
(arithmetic-shift n (- start)))
|
|
]
|
|
|
|
but it runs in constant time when @racket[n] is positive, @racket[start] and
|
|
@racket[end] are fixnums, and @racket[(- 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.
|
|
|
|
@mz-examples[(format "~b" (bitwise-bit-field (string->number "1101" 2) 1 1))
|
|
(bitwise-bit-field 13 1 1)
|
|
(format "~b" (bitwise-bit-field (string->number "1101" 2) 1 3))
|
|
(bitwise-bit-field 13 1 3)
|
|
(format "~b" (bitwise-bit-field (string->number "1101" 2) 1 4))
|
|
(bitwise-bit-field 13 1 4)]
|
|
}
|
|
|
|
|
|
@defproc[(arithmetic-shift [n exact-integer?] [m exact-integer?])
|
|
exact-integer?]{ Returns the bitwise ``shift'' of @racket[n] in its
|
|
(semi-infinite) two's complement representation. If @racket[m] is
|
|
non-negative, the integer @racket[n] is shifted left by @racket[m] bits;
|
|
i.e., @racket[m] new zeros are introduced as rightmost digits. If
|
|
@racket[m] is negative, @racket[n] is shifted right by @racket[(- m)]
|
|
bits; i.e., the rightmost @racket[m] digits are dropped.
|
|
|
|
@mz-examples[(arithmetic-shift 1 10) (arithmetic-shift 255 -3)]}
|
|
|
|
@defproc[(integer-length [n exact-integer?]) exact-integer?]{ Returns
|
|
the number of bits in the (semi-infinite) two's complement
|
|
representation of @racket[n] after removing all leading zeros (for
|
|
non-negative @racket[n]) or ones (for negative @racket[n]).
|
|
|
|
@mz-examples[(integer-length 8) (integer-length -8)]}
|
|
|
|
@; ------------------------------------------------------------------------
|
|
@subsection{Random Numbers}
|
|
|
|
@defproc*[([(random [k (integer-in 1 4294967087)]
|
|
[generator pseudo-random-generator?
|
|
(current-pseudo-random-generator)])
|
|
exact-nonnegative-integer?]
|
|
[(random [generator pseudo-random-generator?
|
|
(current-pseudo-random-generator)])
|
|
(and/c real? inexact? (>/c 0) (</c 1))])]{
|
|
|
|
When called with an integer argument @racket[k], returns a random
|
|
exact integer in the range @racket[0] to @math{@racket[k]-1}. When
|
|
called with zero arguments, returns a random inexact number between
|
|
@racket[0] and @racket[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
|
|
@racket[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
|
|
@cite["L'Ecuyer02"].}
|
|
|
|
|
|
@defproc[(random-seed [k (integer-in 1 (sub1 (expt 2 31)))])
|
|
void?]{
|
|
|
|
Seeds the current pseudo-random number generator with
|
|
@racket[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 @racket[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 @racket[k]. Use
|
|
@racket[vector->pseudo-random-generator!] to set a pseudo-random
|
|
number generator to any of its possible states.}
|
|
|
|
|
|
@defproc[(make-pseudo-random-generator) pseudo-random-generator?]{
|
|
|
|
Returns a new pseudo-random number generator. The new generator is
|
|
seeded with a number derived from @racket[(current-milliseconds)].}
|
|
|
|
|
|
@defproc[(pseudo-random-generator? [v any/c]) boolean?]{
|
|
|
|
Returns @racket[#t] if @racket[v] is a pseudo-random number generator,
|
|
@racket[#f] otherwise.}
|
|
|
|
|
|
@defparam[current-pseudo-random-generator generator pseudo-random-generator?]{
|
|
|
|
A @tech{parameter} that determines the pseudo-random number generator
|
|
used by @racket[random].}
|
|
|
|
|
|
@defproc[(pseudo-random-generator->vector [generator pseudo-random-generator?])
|
|
pseudo-random-generator-vector?]{
|
|
|
|
Produces a vector that represents the complete internal state of
|
|
@racket[generator]. The vector is suitable as an argument to
|
|
@racket[vector->pseudo-random-generator] to recreate the generator in
|
|
its current state (across runs and across platforms).}
|
|
|
|
|
|
@defproc[(vector->pseudo-random-generator [vec pseudo-random-generator-vector?])
|
|
pseudo-random-generator?]{
|
|
|
|
Produces a pseudo-random number generator whose internal state
|
|
corresponds to @racket[vec].}
|
|
|
|
@defproc[(vector->pseudo-random-generator! [generator pseudo-random-generator?]
|
|
[vec pseudo-random-generator-vector?])
|
|
void?]{
|
|
|
|
Like @racket[vector->pseudo-random-generator], but changes
|
|
@racket[generator] to the given state, instead of creating a new
|
|
generator.}
|
|
|
|
|
|
@defproc[(pseudo-random-generator-vector? [v any/c]) boolean?]{
|
|
|
|
Returns @racket[#t] if @racket[v] is a vector of six exact integers,
|
|
where the first three integers are in the range @racket[0] to
|
|
@racket[4294967086], inclusive; the last three integers are in the
|
|
range @racket[0] to @racket[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 @racket[#f].}
|
|
|
|
@; ------------------------------------------------------------------------
|
|
@subsection{Number--String Conversions}
|
|
|
|
@section-index["numbers" "machine representations"]
|
|
@section-index["numbers" "floating-point"]
|
|
@section-index["numbers" "big-endian"]
|
|
@section-index["numbers" "little-endian"]
|
|
@section-index["numbers" "converting"]
|
|
|
|
@defproc[(number->string [z number?] [radix (or/c 2 8 10 16) 10])
|
|
string?]{
|
|
Returns a string that is the printed form of @racket[z]
|
|
in the base specified by @racket[radix]. If @racket[z] is inexact,
|
|
@racket[radix] must be @racket[10], otherwise the
|
|
@exnraise[exn:fail:contract].
|
|
|
|
@mz-examples[(number->string 3.0) (number->string 255 8)]}
|
|
|
|
|
|
@defproc[(string->number [s string?] [radix (integer-in 2 16) 10])
|
|
(or/c number? #f)]{
|
|
|
|
Reads and returns a number datum from @racket[s] (see
|
|
@secref["parse-number"]), returning @racket[#f] if @racket[s] does not
|
|
parse exactly as a number datum (with no whitespace). The optional
|
|
@racket[radix] argument specifies the default base for the number,
|
|
which can be overridden by @litchar{#b}, @litchar{#o}, @litchar{#d}, or
|
|
@litchar{#x} in the string. The @racket[read-decimal-as-inexact]
|
|
parameter affects @racket[string->number] in the same as way as @racket[read].
|
|
|
|
@mz-examples[(string->number "3.0+2.5i") (string->number "hello")
|
|
(string->number "111" 7) (string->number "#b111" 7)]
|
|
}
|
|
|
|
@defproc[(real->decimal-string [n real?] [decimal-digits exact-nonnegative-integer? 2])
|
|
string?]{
|
|
|
|
Prints @racket[n] into a string and returns the string. The printed
|
|
form of @racket[n] shows exactly @racket[decimal-digits] digits after
|
|
the decimal point. The printed form uses a minus sign if @racket[n] is
|
|
negative, and it does not use a plus sign if @racket[n] is positive.
|
|
|
|
Before printing, @racket[n] is converted to an exact number,
|
|
multiplied by @racket[(expt 10 decimal-digits)], rounded, and then
|
|
divided again by @racket[(expt 10 decimal-digits)]. The result of this
|
|
process is an exact number whose decimal representation has no more
|
|
than @racket[decimal-digits] digits after the decimal (and it is
|
|
padded with trailing zeros if necessary).
|
|
|
|
@mz-examples[
|
|
#:eval math-eval
|
|
(real->decimal-string pi)
|
|
(real->decimal-string pi 5)
|
|
]}
|
|
|
|
@defproc[(integer-bytes->integer [bstr bytes?]
|
|
[signed? any/c]
|
|
[big-endian? any/c (system-big-endian?)]
|
|
[start exact-nonnegative-integer? 0]
|
|
[end exact-nonnegative-integer? (bytes-length bstr)])
|
|
exact-integer?]{
|
|
|
|
Converts the machine-format number encoded in @racket[bstr] to an
|
|
exact integer. The @racket[start] and @racket[end] arguments specify
|
|
the substring to decode, where @racket[(- end start)] must be
|
|
@racket[2], @racket[4], or @racket[8]. If @racket[signed?] is true,
|
|
then the bytes are decoded as a two's-complement number, otherwise it
|
|
is decoded as an unsigned integer. If @racket[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.}
|
|
|
|
|
|
@defproc[(integer->integer-bytes [n exact-integer?]
|
|
[size-n (or/c 2 4 8)]
|
|
[signed? any/c]
|
|
[big-endian? any/c (system-big-endian?)]
|
|
[dest-bstr (and/c bytes? (not/c immutable?))
|
|
(make-bytes size-n)]
|
|
[start exact-nonnegative-integer? 0])
|
|
bytes?]{
|
|
|
|
Converts the exact integer @racket[n] to a machine-format number
|
|
encoded in a byte string of length @racket[size-n], which must be
|
|
@racket[2], @racket[4], or @racket[8]. If @racket[signed?] is true,
|
|
then the number is encoded as two's complement, otherwise it is
|
|
encoded as an unsigned bit stream. If @racket[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 @racket[dest-bstr] argument must be a mutable byte string of
|
|
length @racket[size-n]. The encoding of @racket[n] is written into
|
|
@racket[dest-bstr] starting at offset @racket[start], and
|
|
@racket[dest-bstr] is returned as the result.
|
|
|
|
If @racket[n] cannot be encoded in a string of the requested size and
|
|
format, the @exnraise[exn:fail:contract]. If @racket[dest-bstr] is not
|
|
of length @racket[size-n], the @exnraise[exn:fail:contract].}
|
|
|
|
|
|
@defproc[(floating-point-bytes->real [bstr bytes?]
|
|
[big-endian? any/c (system-big-endian?)]
|
|
[start exact-nonnegative-integer? 0]
|
|
[end exact-nonnegative-integer? (bytes-length bstr)])
|
|
flonum?]{
|
|
|
|
Converts the IEEE floating-point number encoded in @racket[bstr] from
|
|
position @racket[start] (inclusive) to @racket[end] (exclusive) to an
|
|
inexact real number. The difference between @racket[start] an
|
|
@racket[end] must be either 4 or 8 bytes. If @racket[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.}
|
|
|
|
|
|
@defproc[(real->floating-point-bytes [x real?]
|
|
[size-n (or/c 4 8)]
|
|
[big-endian? any/c (system-big-endian?)]
|
|
[dest-bstr (and/c bytes? (not/c immutable?))
|
|
(make-bytes size-n)]
|
|
[start exact-nonnegative-integer? 0])
|
|
bytes?]{
|
|
|
|
Converts the real number @racket[x] to its IEEE representation in a
|
|
byte string of length @racket[size-n], which must be @racket[4] or
|
|
@racket[8]. If @racket[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 @racket[dest-bstr] argument must be a mutable byte string of
|
|
length @racket[size-n]. The encoding of @racket[n] is written into
|
|
@racket[dest-bstr] starting with byte @racket[start], and
|
|
@racket[dest-bstr] is returned as the result.
|
|
|
|
If @racket[dest-bstr] is provided and it has less than @racket[start]
|
|
plus @racket[size-n] bytes, the @exnraise[exn:fail:contract].}
|
|
|
|
|
|
@defproc[(system-big-endian?) boolean?]{
|
|
|
|
Returns @racket[#t] if the native encoding of numbers is big-endian
|
|
for the machine running Racket, @racket[#f] if the native encoding
|
|
is little-endian.}
|
|
|
|
@; ------------------------------------------------------------------------
|
|
@subsection{Extra Constants and Functions}
|
|
|
|
@note-lib[racket/math]
|
|
|
|
@defthing[pi flonum?]{
|
|
|
|
An approximation of π, the ratio of a circle's circumference to its
|
|
diameter.
|
|
@examples[
|
|
#:eval math-eval
|
|
pi
|
|
(cos pi)
|
|
]}
|
|
|
|
@defthing[pi.f single-flonum?]{
|
|
|
|
Like @racket[pi], but in single precision.
|
|
@examples[
|
|
#:eval math-eval
|
|
pi.f
|
|
(* 2.0f0 pi)
|
|
(* 2.0f0 pi.f)
|
|
]}
|
|
|
|
@defproc[(degrees->radians [x real?]) real?]{
|
|
|
|
Converts an @racket[x]-degree angle to radians.
|
|
@mz-examples[
|
|
#:eval math-eval
|
|
(degrees->radians 180)
|
|
(sin (degrees->radians 45))
|
|
]}
|
|
|
|
@defproc[(radians->degrees [x real?]) real?]{
|
|
|
|
Converts @racket[x] radians to degrees.
|
|
@mz-examples[
|
|
#:eval math-eval
|
|
(radians->degrees pi)
|
|
(radians->degrees (* 1/4 pi))
|
|
]}
|
|
|
|
@defproc[(sqr [z number?]) number?]{
|
|
|
|
Returns @racket[(* z z)].}
|
|
|
|
@defproc[(sgn [x real?]) (or/c 1 0 -1 1.0 0.0 -1.0)]{
|
|
|
|
Returns the sign of @racket[x] as either @math{-1}, @math{0}, or
|
|
@math{1}.
|
|
|
|
@mz-examples[
|
|
#:eval math-eval
|
|
(sgn 10)
|
|
(sgn -10.0)
|
|
(sgn 0)
|
|
]}
|
|
|
|
@defproc[(conjugate [z number?]) number?]{
|
|
|
|
Returns the complex conjugate of @racket[z].
|
|
|
|
@mz-examples[
|
|
#:eval math-eval
|
|
(conjugate 1)
|
|
(conjugate 3+4i)
|
|
]}
|
|
|
|
@defproc[(sinh [z number?]) number?]{
|
|
|
|
Returns the hyperbolic sine of @racket[z].}
|
|
|
|
@defproc[(cosh [z number?]) number?]{
|
|
|
|
Returns the hyperbolic cosine of @racket[z].}
|
|
|
|
@defproc[(tanh [z number?]) number?]{
|
|
|
|
Returns the hyperbolic tangent of @racket[z].}
|
|
|
|
@defproc[(exact-round [x rational?]) exact-integer?]{
|
|
|
|
Equivalent to @racket[(inexact->exact (round x))].
|
|
}
|
|
|
|
@defproc[(exact-floor [x rational?]) exact-integer?]{
|
|
|
|
Equivalent to @racket[(inexact->exact (floor x))].
|
|
}
|
|
|
|
@defproc[(exact-ceiling [x rational?]) exact-integer?]{
|
|
|
|
Equivalent to @racket[(inexact->exact (ceiling x))].
|
|
}
|
|
|
|
@defproc[(exact-truncate [x rational?]) exact-integer?]{
|
|
|
|
Equivalent to @racket[(inexact->exact (truncate x))].
|
|
}
|
|
|
|
@defproc[(order-of-magnitude [r (and/c real? positive?)]) (and/c exact? integer?)]{
|
|
Computes the greatest exact integer @racket[m] such that:
|
|
@racketblock[(<= (expt 10 m)
|
|
(inexact->exact r))]
|
|
Hence also:
|
|
@racketblock[(< (inexact->exact r)
|
|
(expt 10 (add1 m)))]
|
|
|
|
@mz-examples[#:eval math-eval
|
|
(order-of-magnitude 999)
|
|
(order-of-magnitude 1000)
|
|
(order-of-magnitude 1/100)
|
|
(order-of-magnitude 1/101)]
|
|
}
|
|
|
|
@defproc[(nan? [x real?]) boolean?]{
|
|
|
|
Returns @racket[#t] if @racket[x] is @racket[eqv?] to @racket[+nan.0] or @racket[+nan.f]; otherwise @racket[#f].}
|
|
|
|
@defproc[(infinite? [x real?]) boolean?]{
|
|
|
|
Returns @racket[#t] if @racket[z] is @racket[+inf.0], @racket[-inf.0], @racket[+inf.f], @racket[-inf.f]; otherwise @racket[#f].}
|
|
|
|
@; ----------------------------------------------------------------------
|
|
@close-eval[math-eval]
|
|
@; ----------------------------------------------------------------------
|
|
|
|
@include-section["flonums.scrbl"]
|
|
@include-section["fixnums.scrbl"]
|
|
@include-section["extflonums.scrbl"]
|
|
|
|
@; ----------------------------------------------------------------------
|
|
|