205 lines
8.3 KiB
Racket
205 lines
8.3 KiB
Racket
#lang scribble/doc
|
|
@(require "mz.rkt" (for-label racket/extflonum
|
|
racket/flonum))
|
|
|
|
@title[#:tag "extflonums"]{Extflonums}
|
|
|
|
@defmodule[racket/extflonum]
|
|
|
|
An @deftech{extflonum} is an extended-precision (80-bit)
|
|
floating-point number. extflonum arithmetic is supported on
|
|
platforms with extended-precision hardware and where the
|
|
extflonum implementation does not conflict with normal
|
|
double-precision arithmetic (i.e., on x86 and x86_64 platforms when
|
|
Racket is compiled to use SSE instructions for floating-point
|
|
operations, and on Windows when @as-index{@filepath{longdouble.dll}}
|
|
is available).
|
|
|
|
A extflonum is @bold{not} a @tech{number} in the sense of
|
|
@racket[number?]. Only extflonum-specific operations such as
|
|
@racket[extfl+] perform extflonum arithmetic.
|
|
|
|
A literal extflonum is written like an @tech{inexact number},
|
|
but using an explicit @litchar{t} or @litchar{T} exponent marker (see
|
|
@secref["parse-extflonum"]). For example, @racket[3.5t0] is an
|
|
extflonum. The extflonum infinities and non-a-number values are
|
|
@as-index{@racket[+inf.t]}, @as-index{@racket[-inf.t]},
|
|
and @as-index{@racket[+nan.t]}.
|
|
|
|
If @racket[(extflonum-available?)] produces @racket[#f], then all
|
|
operations exported by @racketmodname[racket/extflonum] raise
|
|
@racket[exn:fail:unsupported], except for @racket[extflonum?],
|
|
@racket[extflonum-available?], and @racket[extflvector?] (which always
|
|
work). The reader (see @secref["reader"]) always accepts extflonum
|
|
input; when extflonum operations are not supported, printing an
|
|
extflonum from the reader uses its source notation (as opposed to
|
|
normalizing the format).
|
|
|
|
Two extflonums are @racket[equal?] if @racket[extfl=]
|
|
produces @racket[#t] for the extflonums. If extflonums
|
|
are not supported in a platform, extflonums are @racket[equal?]
|
|
only if they are @racket[eq?].
|
|
|
|
@defproc[(extflonum? [v any/c]) boolean?]{
|
|
|
|
Returns @racket[#t] if @racket[v] is an extflonum, @racket[#f]
|
|
otherwise.}
|
|
|
|
@defproc[(extflonum-available?) boolean?]{
|
|
|
|
Returns @racket[#t] if @tech{extflonum} operations are supported on the
|
|
current platform, @racket[#f] otherwise.}
|
|
|
|
@; ------------------------------------------------------------------------
|
|
|
|
@section{Extflonum Arithmetic}
|
|
|
|
@deftogether[(
|
|
@defproc[(extfl+ [a extflonum?] [b extflonum?]) extflonum?]
|
|
@defproc[(extfl- [a extflonum?] [b extflonum?]) extflonum?]
|
|
@defproc[(extfl* [a extflonum?] [b extflonum?]) extflonum?]
|
|
@defproc[(extfl/ [a extflonum?] [b extflonum?]) extflonum?]
|
|
@defproc[(extflabs [a extflonum?]) extflonum?]
|
|
)]{
|
|
|
|
Like @racket[fl+], @racket[fl-], @racket[fl*], @racket[fl/], and @racket[flabs],
|
|
but for @tech{extflonums}.}
|
|
|
|
@deftogether[(
|
|
@defproc[(extfl= [a extflonum?] [b extflonum?]) boolean?]
|
|
@defproc[(extfl< [a extflonum?] [b extflonum?]) boolean?]
|
|
@defproc[(extfl> [a extflonum?] [b extflonum?]) boolean?]
|
|
@defproc[(extfl<= [a extflonum?] [b extflonum?]) boolean?]
|
|
@defproc[(extfl>= [a extflonum?] [b extflonum?]) boolean?]
|
|
@defproc[(extflmin [a extflonum?] [b extflonum?]) extflonum?]
|
|
@defproc[(extflmax [a extflonum?] [b extflonum?]) extflonum?]
|
|
)]{
|
|
|
|
Like @racket[fl=], @racket[fl<], @racket[fl>], @racket[fl<=], @racket[fl>=],
|
|
@racket[flmin], and @racket[flmax], but for @tech{extflonums}.}
|
|
|
|
@deftogether[(
|
|
@defproc[(extflround [a extflonum?]) extflonum?]
|
|
@defproc[(extflfloor [a extflonum?]) extflonum?]
|
|
@defproc[(extflceiling [a extflonum?]) extflonum?]
|
|
@defproc[(extfltruncate [a extflonum?]) extflonum?]
|
|
)]{
|
|
|
|
Like @racket[flround], @racket[flfloor], @racket[flceiling], and
|
|
@racket[fltruncate], but for @tech{extflonums}.}
|
|
|
|
@deftogether[(
|
|
@defproc[(extflsin [a extflonum?]) extflonum?]
|
|
@defproc[(extflcos [a extflonum?]) extflonum?]
|
|
@defproc[(extfltan [a extflonum?]) extflonum?]
|
|
@defproc[(extflasin [a extflonum?]) extflonum?]
|
|
@defproc[(extflacos [a extflonum?]) extflonum?]
|
|
@defproc[(extflatan [a extflonum?]) extflonum?]
|
|
@defproc[(extfllog [a extflonum?]) extflonum?]
|
|
@defproc[(extflexp [a extflonum?]) extflonum?]
|
|
@defproc[(extflsqrt [a extflonum?]) extflonum?]
|
|
@defproc[(extflexpt [a extflonum?] [b extflonum?]) extflonum?]
|
|
)]{
|
|
|
|
Like @racket[flsin], @racket[flcos], @racket[fltan], @racket[flasin],
|
|
@racket[flacos], @racket[flatan], @racket[fllog], @racket[flexp], and
|
|
@racket[flsqrt], and @racket[flexpt], but for @tech{extflonums}.}
|
|
|
|
@deftogether[(
|
|
@defproc[(->extfl [a exact-integer?]) extflonum?]
|
|
@defproc[(extfl->exact-integer [a extflonum?]) exact-integer?]
|
|
@defproc[(real->extfl [a real?]) extflonum?]
|
|
@defproc[(extfl->exact [a real?]) (and/c real? exact?)]
|
|
@defproc[(extfl->inexact [a real?]) flonum?]
|
|
)]{
|
|
|
|
The first four are like @racket[->fl], @racket[fl->exact],
|
|
@racket[fl->real], @racket[inexact->exact], but for @tech{extflonums}.
|
|
The @racket[extfl->inexact] function converts a @tech{extflonum} to
|
|
its closest @racket{flonum} approximation.}
|
|
|
|
@; ------------------------------------------------------------------------
|
|
|
|
@section[#:tag "extflvectors"]{Extflonum Vectors}
|
|
|
|
An @deftech{extflvector} is like an @tech{flvector}, but it holds only
|
|
@tech{extflonums}. See also @secref["unsafeextfl"].
|
|
|
|
Two @tech{extflvectors} are @racket[equal?] if they have the same length,
|
|
and if the values in corresponding slots of the @tech{extflvectors} are
|
|
@racket[equal?].
|
|
|
|
@deftogether[(
|
|
@defproc[(extflvector? [v any/c]) boolean?]
|
|
@defproc[(extflvector [x extflonum?] ...) extflvector?]
|
|
@defproc[(make-extflvector [size exact-nonnegative-integer?]
|
|
[x extflonum? 0.0l0])
|
|
extflvector?]
|
|
@defproc[(extflvector-length [vec extflvector?]) exact-nonnegative-integer?]
|
|
@defproc[(extflvector-ref [vec extflvector?] [pos exact-nonnegative-integer?])
|
|
extflonum?]
|
|
@defproc[(extflvector-set! [vec extflvector?] [pos exact-nonnegative-integer?]
|
|
[x extflonum?])
|
|
extflonum?]
|
|
@defproc[(extflvector-copy [vec extflvector?]
|
|
[start exact-nonnegative-integer? 0]
|
|
[end exact-nonnegative-integer? (vector-length v)])
|
|
extflvector?]
|
|
)]{
|
|
|
|
Like @racket[flvector?], @racket[flvector], @racket[make-flvector],
|
|
@racket[flvector-length], @racket[flvector-ref], @racket[flvector-set],
|
|
and @racket[flvector-copy], but for @tech{extflvectors}.}
|
|
|
|
@deftogether[(
|
|
@defproc[(in-extflvector [vec extflvector?]
|
|
[start exact-nonnegative-integer? 0]
|
|
[stop (or/c exact-integer? #f) #f]
|
|
[step (and/c exact-integer? (not/c zero?)) 1])
|
|
sequence?]
|
|
@defform[(for/extflvector maybe-length (for-clause ...) body ...)]
|
|
@defform/subs[(for*/extflvector maybe-length (for-clause ...) body ...)
|
|
([maybe-length (code:line)
|
|
(code:line #:length length-expr)
|
|
(code:line #:length length-expr #:fill fill-expr)])
|
|
#:contracts ([length-expr exact-nonnegative-integer?]
|
|
[fill-expr extflonum?])]
|
|
)]{
|
|
|
|
Like @racket[in-flvector], @racket[for/flvector], and @racket[for*/flvector],
|
|
but for @tech{extflvectors}.}
|
|
|
|
@defproc[(make-shared-extflvector [size exact-nonnegative-integer?]
|
|
[x extflonum? 0.0l0])
|
|
extflvector?]{
|
|
|
|
Like @racket[make-shared-flvector], but for @tech{extflvectors}.}
|
|
|
|
@; ------------------------------------------------------------
|
|
|
|
@section[#:tag "extflutils"]{Extflonum Byte Strings}
|
|
|
|
@defproc[(floating-point-bytes->extfl [bstr bytes?]
|
|
[big-endian? any/c (system-big-endian?)]
|
|
[start exact-nonnegative-integer? 0]
|
|
[end exact-nonnegative-integer? (bytes-length bstr)])
|
|
extflonum?]{
|
|
|
|
Like @racket[floating-point-bytes->real], but for @tech{extflonums}:
|
|
Converts the extended-precision floating-point number encoded in
|
|
@racket[bstr] from position @racket[start] (inclusive) to @racket[end]
|
|
(exclusive) to an @tech{extflonum}. The difference between
|
|
@racket[start] an @racket[end] must be 10 bytes.}
|
|
|
|
|
|
@defproc[(extfl->floating-point-bytes [x extflonum?]
|
|
[big-endian? any/c (system-big-endian?)]
|
|
[dest-bstr (and/c bytes? (not/c immutable?))
|
|
(make-bytes 10)]
|
|
[start exact-nonnegative-integer? 0])
|
|
bytes?]{
|
|
|
|
Like @racket[real->floating-point-bytes], but for @tech{extflonums}:
|
|
Converts @racket[x] to its representation in a byte
|
|
string of length 10.}
|