#lang scribble/manual

@(require scribble/eval
          racket/sandbox
          (for-label racket/base
                     math
                     (only-in typed/racket/base
                              Flonum Real Boolean Integer Exact-Rational Exact-Positive-Integer
                              Any U Listof String False Values Path-String))
          "utils.rkt")

@(define untyped-eval (make-untyped-math-eval))
@interaction-eval[#:eval untyped-eval (require math/bigfloat)]

@title[#:tag "bigfloat"]{Arbitrary-Precision Floating-Point Numbers (@deftech{Bigfloats})}
@(author-neil)

@defmodule[math/bigfloat]

This library provides a Typed Racket interface to @hyperlink["http://www.mpfr.org/"]{MPFR},
a C library that provides
@itemlist[@item{A C type of arbitrary-precision floating-point numbers.}
          @item{Elementary and special functions that are efficient and proved correct.}
          @item{Well-defined semantics that correspond with the latest IEEE 754 standard.}
]
The arbitrary-precision floating-point numbers MPFR provides and operates on are
represented by the type @racket[Bigfloat].

MPFR is free, license-compatible with commercial software, and
@hyperlink["http://www.mpfr.org/ports.html"]{easy to install} on all 
major platforms. Even so, not all systems have it, so @racketmodname[math/bigfloat] links
against MPFR lazily.

If you know MPFR is installed but can't use @racketmodname[math/bigfloat], see @secref{loading}.

@section[#:tag "quick"]{Quick Start}

@itemlist[#:style 'ordered
@item{Set the working precision using @racket[(bf-precision <some-number-of-bits>)].}
@item{Use @racket[bf] to convert real values and well-formed strings to bigfloats.}
@item{Operate on bigfloats using @racket[bf]-prefixed functions like @racket[bf+] and @racket[bfsin].}
@item{Convert bigfloats to real values using @racket[bigfloat->real], @racket[bigfloat->flonum],
      and @racket[bigfloat->integer]. Format them for display using @racket[bigfloat->string].}
]

For examples, continue through the FAQ.

@section{Fictionally Asked Questions}

@bold{Why use @racketmodname[math/bigfloat]}?

There are a few reasons.

@italic{Reason:} Flonums have either too much or too little precision for your application.

@examples[#:eval
          untyped-eval
          (flsqrt 3.0)
          pi
          (bf-precision 16)
          (eval:alts (bfsqrt (bf 3))
                     (eval:result @racketresultfont{(bf #e1.73206)}))
          (bf-precision 179)
          (eval:alts
           pi.bf
           (eval:result
            @racketresultfont{(bf #e3.141592653589793238462643383279502884197169399375105819)}))]

A flonum has a 53-bit significand (we'll say it has 53 bits of
@italic{precision}) and an 11-bit @italic{exponent}. A bigfloat
has an arbitrary precision of at least 2 bits and a 31-bit exponent.

@italic{Reason:} To compute ridiculously large or small numbers with confidence.

@examples[#:eval
          untyped-eval
          (bf-precision 128)
          (eval:alts
           (bfexp (bfexp (bfexp (bf 3))))
           (eval:result @racketresultfont{(bf "2.050986436051648895105860942072054674579e229520860")}))
          (eval:alts
           (bflog (bflog (bflog (bfexp (bfexp (bfexp (bf 3)))))))
           (eval:result @racketresultfont{(bf 3)}))]

@italic{Reason:} To verify your floating-point hardware.

@hyperlink["http://en.wikipedia.org/wiki/IEEE_754-2008"]{IEEE 754-2008} stipulates
that conforming implementations must correctly round the results of all operations.
Roughly speaking, results can't be more than half a bit off, where the bit in
question is the least significant in the significand.

Of course, implementations don't always adhere to standards. For example, on my old
laptop, evaluating @(racket (exp 400)) results in @(racket 5.221469689764346e+173).
Note the last four decimal digits in the significand: @(racket 4346). But they should be @racket[4144]:
@interaction[#:eval untyped-eval
                    (bf-precision 53)
                    (eval:alts
                     (bigfloat->flonum (bfexp (bf 400)))
                     (eval:result @racketresultfont{5.221469689764144e+173}))]
My new laptop computes @(racket 5.221469689764144e+173) as it should.

@italic{Reason:} To control rounding of the least significant bit.

IEEE 754 provides for different rounding modes for the smallest bit of
a flonum result, such as round to even and round toward zero. We might use
this to implement interval arithmetic correctly, by rounding lower bounds
downward and the upper bounds upward. But there isn't a portable way to set the
rounding mode!

MPFR allows the rounding mode to be set before any operation, and
@racketmodname[math/bigfloat] exposes this capability using the parameter
@racket[bf-rounding-mode].

@bold{When shouldn't I use @racketmodname[math/bigfloat]?}

When you need raw speed. Bigfloat functions can be hundreds to thousands of times slower
than flonum functions.

That's not to say that they're @italic{inefficient}. For example, @(racket bflog)
implements the algorithm with the best known asymptotic complexity. It just doesn't
run directly on hardware, and it can't take fixed-precision-only shortcuts.

@bold{Why are there junk digits on the end of @racket[(bf 1.1)]?}

That's approximately the value of the flonum @racket[1.1]. Use @code{(bf #e1.1)} or
@code{(bf "1.1")} to make the junk go away. In general, you should prefer to convert
exact rationals and strings to bigfloats.

@bold{Why is the last digit of @racket[pi.bf] not rounded correctly?}

All the @italic{bits} but the last is exact, and the last bit is correctly rounded.
This doesn't guarantee that the last digit will be.

A decimal digit represents at most log(10)/log(2) ≈ 3.3 bits. This is an irrational
number, so the decimal/bit boundary never lines up except at the decimal point.
Thus, the last decimal digit of any bigfloat must represent fewer than 3.3 bits,
so it's wrong more often than not. But it's the last @italic{bit} that counts.

@section{Bigfloat Type and Accessors}

@defidform[Bigfloat]{
An opaque type that represents an arbitrary-precision floating-point number, or a @tech{bigfloat}.
}

@defproc[(bigfloat? [v Any]) Boolean]{
Returns @racket[#t] when @racket[v] is a bigfloat.
}

@defproc[(bigfloat-precision [x Bigfloat]) Exact-Positive-Integer]{
Returns the number of bits in the significand of @racket[x]. This is almost always
the value of @racket[(bf-precision)] when @racket[x] was created.
}

@defproc[(bigfloat-sign [x Bigfloat]) (U 0 1)]{
Returns the @italic{sign bit} of the significand of @racket[x].
@examples[#:eval untyped-eval
                 (eval:alts
                  (bigfloat-sign -1.bf)
                  (eval:result @racketresultfont{1}))
                 (eval:alts
                  (bigfloat-sign 0.bf)
                  (eval:result @racketresultfont{0}))
                 (eval:alts
                  (bigfloat-sign -0.bf)
                  (eval:result @racketresultfont{1}))
                 (eval:alts
                  (bigfloat-sign -inf.bf)
                  (eval:result @racketresultfont{1}))]
}

@deftogether[(@defproc[(bigfloat-significand [x Bigfloat]) Integer]
              @defproc[(bigfloat-exponent [x Bigfloat]) Integer]
              @defproc[(bigfloat-sig+exp [x Bigfloat]) (Values Integer Integer)])]{
Return the @italic{signed} significand and exponent of @racket[x].

If @racket[(values sig exp) = (bigfloat-sig+exp x)], its value as an exact rational
is @racket[(* sig (expt 2 exp))]. In fact, @racket[bigfloat->rational] converts
bigfloats to rationals in exactly this way, after ensuring that @racket[(bfrational? x)]
is @racket[#t].
}

@section{Bigfloat Parameters}

@defparam[bf-precision bits Integer]{
A parameter that determines the precision of new @racket[Bigfloat] values.

With a few noted exceptions, bigfloat functions conceptually compute in infinite
precision, round the answers to @racket[(bf-precision)] bits using 
@racket[(bf-rounding-mode)], and return the rounded answers. (In practice,
they employ finite algorithms that have been painstakingly proved to be equivalent
to the aforementioned infinite process.)
                                                 
This parameter has a guard that ensures @racket[(bf-precision)] is between
@racket[bf-min-precision] and @racket[bf-max-precision].
}

@defparam[bf-rounding-mode mode (U 'nearest 'zero 'up 'down)]{
A parameter that determines the rounding mode used when producing new @racket[Bigfloat] values.
}

@defthing[bf-min-precision Exact-Positive-Integer]{
Equal to @racket[2], because single-bit bigfloats can't be correctly rounded.
}

@defthing[bf-max-precision Exact-Positive-Integer]{
The largest value of @racket[(bf-precision)]. This is platform-dependent, and probably much
larger than you'll ever need.
}

@section[#:tag "construction"]{Bigfloat Construction and Conversion}

@defproc*[([(bf [x (U String Real)]) Bigfloat]
           [(bf [sig Integer] [exp Integer]) Bigfloat])]{
The one-argument variant converts a string or real @racket[x] to a bigfloat.

@interaction[#:eval untyped-eval
                    (bf-precision 128)
                    (eval:alts (bf 4) (eval:result @racketresultfont{(bf 4)}))
                    (eval:alts
                     (bf 1/7)
                     (eval:result
                      @racketresultfont{(bf #e0.1428571428571428571428571428571428571426)}))
                    (eval:alts
                     (bf #e4.1)
                     (eval:result
                      @racketresultfont{(bf #e4.099999999999999999999999999999999999995)}))
                    (eval:alts
                     (bf "not a number")
                     (eval:result
                      ""
                      ""
                      "bf: expected a well-formed decimal number; given \"not a number\""))
                    (eval:alts
                     (bf "15e200000000")
                     (eval:result
                      @racketresultfont{(bf "1.499999999999999999999999999999999999998e200000001")}))]

In the last example, the result of @racket[(bf "15e200000000")] is displayed as a
string conversion because the exact rational number would be very large.

@margin-note{* It can be a good idea if you're testing a flonum implementation of a function
             against a bigfloat implementation.}
Converting from flonum literals is usually a bad idea* because flonums have only
53 bits precision. Prefer to pass exact rationals and strings to @racket[bf].

The two-argument variant converts a signed significand @racket[sig] and a power of
2 @racket[exp] to a bigfloat. Generally, @racket[(bf sig exp) = (bf (* sig (expt 2 exp)))],
but the two-argument variant is much faster, especially for large @racket[exp].
@examples[#:eval untyped-eval
                 (eval:alts
                  (bf 200 56)
                  (eval:result @racketresultfont{(bf 14411518807585587200)}))
                 (eval:alts
                  (bf (* 200 (expt 2 56)))
                  (eval:result @racketresultfont{(bf 14411518807585587200)}))]

The @racket[bfrandom] function generates random bigfloats between 0 and 1 using
the two-argument variant in this way:
@interaction[#:eval untyped-eval
                    (require (only-in math/base random-bits))
                    (bf-precision 64)
                    (eval:alts
                     (bf (random-bits 64) -64)
                     (eval:result @racketresultfont{(bf #e0.416872969910248753552)}))]
}

@defproc[(bfrandom) Bigfloat]{
Returns a uniformly distributed random bigfloat @racket[x] such that
@racket[(0.bf . bf<= . x)] and @racket[(x . bf< . 1.bf)].
}

@defproc[(bfcopy [x Bigfloat]) Bigfloat]{
Returns the @racket[(bf-precision)]-bit bigfloat closest to @racket[x],
under the current @racket[bf-rounding-mode].

A common pattern to compute bigfloats in higher precision is
@interaction[#:eval untyped-eval
                    (bf-precision 64)
                    (eval:alts
                     (bfcopy
                      (parameterize ([bf-precision  (+ (bf-precision) 10)])
                        (bf/ (bf+ 1.bf (bfsqrt 5.bf)) 2.bf)))
                     (eval:result @racketresultfont{(bf #e1.61803398874989484821)}))]
This example computes the golden ratio (@racket[phi.bf]) with 10 bits more than requested,
to make up for triple rounding error.
}

@deftogether[(@defproc[(bigfloat->integer [x Bigfloat]) Integer]
              @defproc[(bigfloat->rational [x Bigfloat]) Exact-Rational]
              @defproc[(bigfloat->real [x Bigfloat]) (U Exact-Rational Flonum)]
              @defproc[(bigfloat->flonum [x Bigfloat]) Flonum])]{
Convert bigfloats to integer, exact rational, real and flonum values respectively.

@racket[bigfloat->integer], @racket[bigfloat->rational] and @racket[bigfloat->real] return values
that can be converted exactly back to @racket[x] using @racket[bf]. For the first two, this is done
by raising an error if @racket[x] is not respectively integer or rational. On the other hand,
@racket[bigfloat->real] returns @racket[+inf.0], @racket[-inf.0] or @racket[+nan.0] when @racket[x]
is not a rational bigfloat.

@racket[bigfloat->flonum] rounds @racket[x] to 53 bits precision to fit the value into a flonum,
using the current value of @racket[bf-rounding-mode].

@interaction[#:eval untyped-eval
                    (bf-precision 64)
                    (eval:alts
                     (bigfloat->integer (bf 21/10))
                     (eval:result
                      ""
                      ""
                      "bigfloat->integer: contract violation
  expected: bfinteger?
  given: (bf #e2.09999999999999999991)"))
                    (eval:alts
                     (bigfloat->integer (bfround (bf 21/10)))
                     (eval:result @racketresultfont{2}))
                    (eval:alts (define x (bf 1/7)) (eval:result ""))
                    (eval:alts
                     (bigfloat->flonum x)
                     (eval:result @racketresultfont{0.14285714285714285}))
                    (eval:alts
                     (bigfloat->rational x)
                     (eval:result @racketresultfont{10540996613548315209/73786976294838206464}))
                    (eval:alts
                     (rationalize (bigfloat->rational x) (expt 2 (- (bf-precision))))
                     (eval:result @racketresultfont{1/7}))
                    (eval:alts
                     (bf= x (bf (bigfloat->rational x)))
                     (eval:result @racketresultfont{#t}))]

@bold{Be careful with exact conversions.} Bigfloats with large exponents may not fit in memory as
integers or exact rationals. Worse, they might fit, but have all your RAM and swap space for lunch.
}

@deftogether[(@defproc[(bigfloat->string [x Bigfloat]) String]
              @defproc[(string->bigfloat [s String]) (U Bigfloat False)])]{
Convert a bigfloat @racket[x] to a string @racket[s] and back.

The string returned by @racket[bigfloat->string] includes enough digits that
@racket[string->bigfloat] can reconstruct the bigfloat precisely. In other words,
@racket[string->bigfloat] is a left inverse of @racket[bigfloat->string].

If @racket[s] isn't a well-formed decimal number with an optional exponent part,
@racket[string->bigfloat] returns @racket[#f]. (In contrast, @racket[(bf s)] raises an error.)

@examples[#:eval untyped-eval
                 (bf-precision 64)
                 (eval:alts
                  (bigfloat->string (bf 4))
                  (eval:result @racketresultfont{"4"}))
                 (eval:alts
                  (bigfloat->string (bf #e0.0001))
                  (eval:result @racketresultfont{"1.00000000000000000001e-4"}))
                 (eval:alts
                  (string->bigfloat "0.14285714285714285714")
                  (eval:result @racketresultfont{(bf #e0.142857142857142857141)}))
                 (eval:alts
                  (string->bigfloat "square root of two")
                  (eval:result @racketresultfont{#f}))
                 (eval:alts
                  (string->bigfloat (bigfloat->string pi.bf))
                  (eval:result @racketresultfont{(bf #e3.14159265358979323851)}))
                 (eval:alts
                  pi.bf
                  (eval:result @racketresultfont{(bf #e3.14159265358979323851)}))]
}

@deftogether[(@defproc[(bftruncate [x Bigfloat]) Bigfloat]
              @defproc[(bffloor [x Bigfloat]) Bigfloat]
              @defproc[(bfceiling [x Bigfloat]) Bigfloat]
              @defproc[(bfround [x Bigfloat]) Bigfloat])]{
Like @racket[truncate], @racket[floor], @racket[ceiling] and @racket[round], but
for bigfloats.

Rounding is to the nearest integer, with ties broken by rounding to even.
@examples[#:eval untyped-eval
                 (eval:alts (bfround (bf 1.5)) (eval:result @racketresultfont{(bf 2)}))
                 (eval:alts (bfround (bf 2.5)) (eval:result @racketresultfont{(bf 2)}))
                 (eval:alts (bfround (bf -1.5)) (eval:result @racketresultfont{(bf -2)}))
                 (eval:alts (bfround (bf -2.5)) (eval:result @racketresultfont{(bf -2)}))]
}

@defproc[(bffrac [x Bigfloat]) Bigfloat]{
Returns the fractional part of @racket[x], with the same sign as @racket[x].
}

@defproc[(bfrint [x Bigfloat]) Bigfloat]{
Rounds @racket[x] to the nearest integer bigfloat, in the direction specified by
@racket[(bf-rounding-mode)].
}

@section[#:tag "constants"]{Bigfloat Constants}

Most bigfloat ``constants'' are actually identifier macros that expand to the application
of a zero-argument function. This allows, for example, @racket[pi.bf] to depend on the
current value of @racket[bf-precision], and allows all of them to be constructed lazily.
Most constants are memoized, possibly at multiple precisions.

@deftogether[(@defthing[pi.bf Bigfloat]
              @defthing[phi.bf Bigfloat]
              @defthing[gamma.bf Bigfloat]
              @defthing[catalan.bf Bigfloat]
              @defthing[log2.bf Bigfloat])]{
Approximations of π, φ, γ, G and log(2).
@examples[#:eval
          untyped-eval
          (bf-precision 10)
          (eval:alts pi.bf (eval:result @racketresultfont{(bf #e3.1406)}))
          (bf-precision 179)
          (eval:alts
           pi.bf
           (eval:result
            @racketresultfont{(bf #e3.141592653589793238462643383279502884197169399375105819)}))
          (eval:alts
           phi.bf
           (eval:result
            @racketresultfont{bf #e1.618033988749894848204586834365638117720309179805762863)}))
          (eval:alts
           gamma.bf
           (eval:result
            @racketresultfont{(bf #e0.5772156649015328606065120900824024310421593359399235988)}))
          (eval:alts
           catalan.bf
           (eval:result
            @racketresultfont{(bf #e0.9159655941772190150546035149323841107741493742816721343)}))
          (eval:alts
           log2.bf
           (eval:result
            @racketresultfont{(bf #e0.6931471805599453094172321214581765680755001343602552545)}))]
}

@deftogether[(@defthing[-inf.bf Bigfloat]
              @defthing[-max.bf Bigfloat]
              @defthing[-min.bf Bigfloat]
              @defthing[-0.bf Bigfloat]
              @defthing[0.bf Bigfloat]
              @defthing[+min.bf Bigfloat]
              @defthing[+max.bf Bigfloat]
              @defthing[+inf.bf Bigfloat]
              @defthing[+nan.bf Bigfloat]
              @defthing[epsilon.bf Bigfloat])]{
Bigfloat constants corresponding to
@racket[-inf.0], @racket[-max.0] @racket[-min.0], @racket[-0.0],
@racket[0.0], @racket[+min.0], @racket[+max.0], @racket[+inf.0],
@racket[+nan.0] and @racket[epsilon.0].

The constants @racket[-inf.bf], @racket[-0.bf], @racket[0.bf], @racket[+inf.bf],
and @racket[+nan.bf] have fixed precision.
}

@deftogether[(@defthing[-10.bf Bigfloat]
              @defthing[-9.bf Bigfloat]
              @defthing[-8.bf Bigfloat]
              @defthing[-7.bf Bigfloat]
              @defthing[-6.bf Bigfloat]
              @defthing[-5.bf Bigfloat]
              @defthing[-4.bf Bigfloat]
              @defthing[-3.bf Bigfloat]
              @defthing[-2.bf Bigfloat]
              @defthing[-1.bf Bigfloat]
              @defthing[1.bf Bigfloat]
              @defthing[2.bf Bigfloat]
              @defthing[3.bf Bigfloat]
              @defthing[4.bf Bigfloat]
              @defthing[5.bf Bigfloat]
              @defthing[6.bf Bigfloat]
              @defthing[7.bf Bigfloat]
              @defthing[8.bf Bigfloat]
              @defthing[9.bf Bigfloat]
              @defthing[10.bf Bigfloat])]{
More fixed-precision bigfloat constants.
}

@section[#:tag "predicates"]{Bigfloat Predicates}

@deftogether[(@defproc[(bfzero? [x Bigfloat]) Boolean]
              @defproc[(bfpositive? [x Bigfloat]) Boolean]
              @defproc[(bfnegative? [x Bigfloat]) Boolean]
              @defproc[(bfinteger? [x Bigfloat]) Boolean]
              @defproc[(bfeven? [x Bigfloat]) Boolean]
              @defproc[(bfodd? [x Bigfloat]) Boolean]
              @defproc[(bfrational? [x Bigfloat]) Boolean]
              @defproc[(bfinfinite? [x Bigfloat]) Boolean]
              @defproc[(bfnan? [x Bigfloat]) Boolean])]{
Unary predicates corresponding to @racket[zero?], @racket[positive?],
@racket[negative?], @racket[integer?], @racket[even?], @racket[odd?],
@racket[rational?], @racket[infinite?] and @racket[nan?].
}

@deftogether[(@defproc[(bf= [x Bigfloat] [y Bigfloat]) Boolean]
              @defproc[(bf> [x Bigfloat] [y Bigfloat]) Boolean]
              @defproc[(bf< [x Bigfloat] [y Bigfloat]) Boolean]
              @defproc[(bf>= [x Bigfloat] [y Bigfloat]) Boolean]
              @defproc[(bf<= [x Bigfloat] [y Bigfloat]) Boolean])]{
Standard comparison functions. As is usual, infinities are either greater or less
than any other bigfloat, and every comparison returns @racket[#f] when either argument
is @racket[+nan.bf].
}

@section[#:tag "ops"]{Bigfloat Operations}

@deftogether[(@defproc[(bfmax [x Bigfloat] ...) Bigfloat]
              @defproc[(bfmin [x Bigfloat] ...) Bigfloat])]{
Return the maximum and minimum of their arguments, respectively.

When given no arguments, @racket[bfmin] returns @racket[+inf.bf], and
@racket[bfmax] returns @racket[-inf.bf].
}

@deftogether[(@defproc[(bf+ [x Bigfloat] ...) Bigfloat]
              @defproc[(bf* [x Bigfloat] ...) Bigfloat]
              @defproc[(bf- [x Bigfloat] [y Bigfloat] ...) Bigfloat]
              @defproc[(bf/ [x Bigfloat] [y Bigfloat] ...) Bigfloat]
              @defproc[(bfsqr [x Bigfloat]) Bigfloat]
              @defproc[(bfabs [x Bigfloat]) Bigfloat]
              @defproc[(bfsgn [x Bigfloat]) Bigfloat])]{
Standard arithmetic functions, corresponding to @racket[+], @racket[*],
@racket[-], @racket[/], @racket[sqr], @racket[abs] and @racket[sgn].

When @racket[bf+] and @racket[bf-] are given more than two arguments, they compute
the answers in a way that incurs rounding error only once.
}

@deftogether[(@defproc[(bfsqrt [x Bigfloat]) Bigfloat]
              @defproc[(bf1/sqrt [x Bigfloat]) Bigfloat]
              @defproc[(bfcbrt [x Bigfloat]) Bigfloat])]{
Return the square root, @italic{reciprocal} square root, and cube root of @racket[x].
}

@defproc[(bfroot [x Bigfloat] [n Integer]) Bigfloat]{
Returns the @racket[n]th root of @racket[x]. @racket[n] must be a nonnegative fixnum.
}

@defproc[(bfhypot [x Bigfloat] [y Bigfloat]) Bigfloat]{
Computes @racket[(bfsqrt (bf+ (bfsqr x) (bfsqr y)))] without uncessary overflow,
incurring rounding error only once. See @racket[flhypot] for an example using flonums.
}

@deftogether[(@defproc[(bflog [x Bigfloat]) Bigfloat]
              @defproc[(bflog2 [x Bigfloat]) Bigfloat]
              @defproc[(bflog10 [x Bigfloat]) Bigfloat])]{
Return the log of @racket[x] in base @italic{e}, 2 and 10.
}

@deftogether[(@defproc[(bfexp [x Bigfloat]) Bigfloat]
              @defproc[(bfexp2 [x Bigfloat]) Bigfloat]
              @defproc[(bfexp10 [x Bigfloat]) Bigfloat])]{
Return the exponential of @racket[x] in base @italic{e}, 2 and 10.
}

@deftogether[(@defproc[(bflog1p [x Bigfloat]) Bigfloat]
              @defproc[(bfexpm1 [x Bigfloat]) Bigfloat])]{
Like @racket[(bflog (bf+ 1.bf x))] and @racket[(bf- (bfexp x) 1.bf)], but correct
when @racket[x] is near zero. See @racket[fllog1p] for motivation and examples.
}

@defproc[(bfexpt [x Bigfloat] [y Bigfloat]) Bigfloat]{
Computes @racket[x]@superscript{@racket[y]}. See @racket[flexpt] and @racket[expt].
}

@deftogether[(@defproc[(bfsin [x Bigfloat]) Bigfloat]
              @defproc[(bfcos [x Bigfloat]) Bigfloat]
              @defproc[(bftan [x Bigfloat]) Bigfloat]
              @defproc[(bfasin [x Bigfloat]) Bigfloat]
              @defproc[(bfacos [x Bigfloat]) Bigfloat]
              @defproc[(bfatan [x Bigfloat]) Bigfloat]
              @defproc[(bfatan2 [x Bigfloat] [y Bigfloat]) Bigfloat])]{
Standard trigonometric functions and their inverses.
}

@deftogether[(@defproc[(bfsinh [x Bigfloat]) Bigfloat]
              @defproc[(bfcosh [x Bigfloat]) Bigfloat]
              @defproc[(bftanh [x Bigfloat]) Bigfloat]
              @defproc[(bfasinh [x Bigfloat]) Bigfloat]
              @defproc[(bfacosh [x Bigfloat]) Bigfloat]
              @defproc[(bfatanh [x Bigfloat]) Bigfloat])]{
Standard hyperbolic functions and their inverses.
}

@deftogether[(@defproc[(bfsec [x Bigfloat]) Bigfloat]
              @defproc[(bfcsc [x Bigfloat]) Bigfloat]
              @defproc[(bfcot [x Bigfloat]) Bigfloat])]{
Standard @italic{reciprocal} trigonometric functions. MPFR does not implement their inverses.
}

@deftogether[(@defproc[(bfsech [x Bigfloat]) Bigfloat]
              @defproc[(bfcsch [x Bigfloat]) Bigfloat]
              @defproc[(bfcoth [x Bigfloat]) Bigfloat])]{
Standard @italic{reciprocal} hyperbolic functions. MPFR does not implement their inverses.
}

@defproc[(bfsin+cos [x Bigfloat]) (Values Bigfloat Bigfloat)]{
Simultaneously computes the sine and cosine of @racket[x].
}

@defproc[(bfsinh+cosh [x Bigfloat]) (Values Bigfloat Bigfloat)]{
Simultaneously computes the hyperbolic sine and cosine of @racket[x].
}

@defproc[(bffactorial [x Integer]) Bigfloat]{
Returns the factorial of @racket[x].
}

@defproc[(bfgamma [x Bigfloat]) Bigfloat]{
Computes the @hyperlink["http://en.wikipedia.org/wiki/Gamma_function"]{gamma function},
a generalization of the factorial function.
}

@deftogether[(@defproc[(bflog-gamma [x Bigfloat]) Bigfloat]
              @defproc[(bflog-gamma/sign [x Bigfloat]) (Values Bigfloat (U -1 1))])]{
Computes the @hyperlink["http://mathworld.wolfram.com/LogGammaFunction.html"]{log-gamma function},
or the log of the absolute value of the gamma function. @racket[bflog-gamma/sign] additionally
returns the sign of @racket[(bfgamma x)].
}

@defproc[(bfpsi0 [x Bigfloat]) Bigfloat]{
Computes the @hyperlink["http://en.wikipedia.org/wiki/Digamma_function"]{digamma function},
the logarithmic derivative of the gamma function.
}

@defproc[(bfeint [x Bigfloat]) Bigfloat]{
Returns the @hyperlink["http://en.wikipedia.org/wiki/Exponential_integral"]{exponential integral}
of @racket[x].
}

@defproc[(bfli2 [x Bigfloat]) Bigfloat]{
Returns the dilogarithm of @racket[x], or the
@hyperlink["http://en.wikipedia.org/wiki/Polylogarithm"]{polylogarithm} of order 2.
}

@defproc[(bfzeta [x Bigfloat]) Bigfloat]{
Computes the @hyperlink["http://en.wikipedia.org/wiki/Riemann_zeta_function"]{Riemann zeta function}.
}

@deftogether[(@defproc[(bferf [x Bigfloat]) Bigfloat]
              @defproc[(bferfc [x Bigfloat]) Bigfloat])]{
Compute the @hyperlink["http://en.wikipedia.org/wiki/Error_function"]{error function and
complementary error function}, respectively.
}

@deftogether[(@defproc[(bfbesj0 [x Bigfloat]) Bigfloat]
              @defproc[(bfbesj1 [x Bigfloat]) Bigfloat]
              @defproc[(bfbesj [n Integer] [x Bigfloat]) Bigfloat]
              @defproc[(bfbesy0 [x Bigfloat]) Bigfloat]
              @defproc[(bfbesy1 [x Bigfloat]) Bigfloat]
              @defproc[(bfbesy [n Integer] [x Bigfloat]) Bigfloat])]{
These compute @hyperlink["http://en.wikipedia.org/wiki/Bessel_function"]{Bessel functions}.

A ``@racket[j]'' in the name indicates that a function computes a Bessel function of the
first kind. A ``@racket[y]'' indicates the second kind.

The ``@racket[j]'' or ``@racket[y]'' is followed by the @italic{order}: zero, one, or
@racket[n] (user-specified).
}

@defproc[(bfagm [x Bigfloat] [y Bigfloat]) bigfloat]{
Returns the
@hyperlink["http://en.wikipedia.org/wiki/Arithmetic-geometric_mean"]{arithmetic-geometric mean}
of @racket[x] and @racket[y]. Typically, this isn't directly useful, but it's used in some
asymptotically fast algorithms such as the one that computes @racket[bflog].
}


@section[#:tag "misc"]{Low-level Bigfloat Functions}

@deftogether[(@defproc[(bigfloat->ordinal [x Bigfloat]) Integer]
              @defproc[(ordinal->bigfloat [n Integer]) Bigfloat]
              @defproc[(bigfloats-between [x Bigfloat] [y Bigfloat]) Integer]
              @defproc[(bfstep [x Bigfloat] [n Integer]) Bigfloat]
              @defproc[(bfnext [x Bigfloat]) Bigfloat]
              @defproc[(bfprev [x Bigfloat]) Bigfloat])]{
Like @racket[flonum->ordinal], @racket[ordinal->flonum], @racket[flonums-between],
@racket[flstep], @racket[flnext] and @racket[flprev], but for bigfloats.

The major difference is that these operate using @racket[(bf-precision)] bits.
Additionally, unlike other bigfloat functions, all of these convert their bigfloat arguments
to @racket[(bf-precision)] bits.
}

@defproc[(bfshift [x Bigfloat] [n Integer]) Bigfloat]{
Like @racket[arithmetic-shift], but for bigfloats. More precisely, this returns
@racket[(bf* x (bfexpt (bf 2) (bf n)))], but is much faster.
}

@defproc[(bfcanonicalize [x Bigfloat]) Bigfloat]{
@margin-note*{Bigfloats are canonicalized before hashing, to ensure that equality
              implies an equal hash.}
If @racket[x] is nonzero and rational, returns a new bigfloat with no more bits of
precision than are necessary to encode @racket[x] exactly, by removing all low-order
zeros from the significand and adjusting the exponent.

For zero or non-rational @racket[x], returns @racket[-inf.bf], @racket[-0.bf],
@racket[0.bf], @racket[+inf.bf], or @racket[+nan.bf], depending on the value of @racket[x].

Two nonzero, rational bigfloats are @racket[equal?] if and only if their canonicalized
significands and exponents are equal. Two zero or non-rational bigfloats are @racket[equal?]
if and only if their canonicalizations are @racket[eq?].

Canonicalizing bigfloats won't change answers computed from them.

@examples[#:eval untyped-eval
                 (bf-precision 64)
                 (eval:alts (define x (bf 1 -2)) (eval:result ""))
                 (eval:alts x (eval:result @racketresultfont{(bf #e0.25)}))
                 (eval:alts (bfcanonicalize x)
                            (eval:result @racketresultfont{(bf #e0.25)}))
                 (eval:alts (bigfloat-precision x)
                            (eval:result @racketresultfont{64}))
                 (eval:alts (bigfloat-precision (bfcanonicalize x))
                            (eval:result @racketresultfont{2}))]
}

@section[#:tag "loading"]{Loading the MPFR Library}

The @racketmodname[math/bigfloat] library depends directly on one library: MPFR, which on the filesystem is
named something like @filepath{libmpfr.so}, but with a platform-specific suffix.
MPFR itself depends on @hyperlink["http://gmplib.org/"]{GMP}, the
GNU Multiple Precision Arithmetic Library, which on the filesystem is named @filepath{libgmp.so}.

If @racket[(mpfr-available?)] is @racket[#t], both of these libraries have been loaded
by the Racket runtime, and everything in @racketmodname[math/bigfloat] should work.
(If something doesn't, it's likely an error in the foreign function interface. In that
case, please email the author of this library or submit a bug report.)

If @racket[(mpfr-available?)] is @racket[#f], one of these libraries can't be loaded. The
most common reason is that one or both needs to be installed. Another possibility is that
both are installed, but one is not in the operating system's search path. In this case,
see @racket[set-mpfr-lib-dirs!].

@defproc[(mpfr-available?) Boolean]{
Returns @racket[#t] when both GMP and MPFR are available; @racket[#f] otherwise.
}

@(close-eval untyped-eval)