@c ITEMS IN THIS FILE ARE IN NEED OF EXPANSION, CLARIFICATION, AND EXAMPLES

@menu
* Definitions for Floating Point::  
@end menu

@node Definitions for Floating Point,  , Floating Point, Floating Point
@section Definitions for Floating Point

@c FOLLOWING FUNCTIONS IN bffac.mac ARE NOT DESCRIBED IN .texi FILES: !!!
@c obfac, azetb, vonschtoonk, divrlst, obzeta, bfhzeta, bfpsi0 !!!
@c DON'T KNOW WHICH ONES ARE INTENDED FOR GENERAL USE !!!

@c FOLLOWING FUNCTIONS IN bffac.mac ARE DESCRIBED IN Number.texi: !!!
@c burn, bzeta, bfzeta !!!

@c FOLLOWING FUNCTIONS IN bffac.mac ARE DESCRIBED HERE: !!!
@c bfpsi, bffac, cbffac !!!

@deffn {Function} bffac (@var{expr}, @var{n})
Bigfloat version of the factorial (shifted gamma)
function.  The second argument is how many digits to retain and return,
it's a good idea to request a couple of extra.

@code{load ("bffac")} loads this function.

@end deffn

@defvr {Option variable} algepsilon
Default value: 10^8

@c WHAT IS algepsilon, EXACTLY ??? describe ("algsys") IS NOT VERY INFORMATIVE !!!
@code{algepsilon} is used by @code{algsys}.

@end defvr

@deffn {Function} bfloat (@var{expr})
Converts all numbers and functions of numbers in @var{expr} to bigfloat numbers.
The number of significant digits in the resulting bigfloats is specified by the global variable @code{fpprec}.

When @code{float2bf} is @code{false} a warning message is printed when
a floating point number is converted into a bigfloat number (since
this may lead to loss of precision).

@end deffn

@deffn {Function} bfloatp (@var{expr})
Returns @code{true} if @var{expr} is a bigfloat number, otherwise @code{false}.

@end deffn

@deffn {Function} bfpsi (@var{n}, @var{z}, @var{fpprec})
@deffnx {Function} bfpsi0 (@var{z}, @var{fpprec})
@code{bfpsi} is the polygamma function of real argument @var{z} and integer order @var{n}.
@code{bfpsi0} is the digamma function. 
@code{bfpsi0 (@var{z}, @var{fpprec})} is equivalent to @code{bfpsi (0, @var{z}, @var{fpprec})}.

These functions return bigfloat values.
@var{fpprec} is the bigfloat precision of the return value.

@c psi0(1) = -%gamma IS AN INTERESTING PROPERTY BUT IN THE ABSENCE OF ANY OTHER
@c DISCUSSION OF THE PROPERTIES OF THIS FUNCTION, THIS STATEMENT SEEMS OUT OF PLACE.
@c Note @code{-bfpsi0 (1, fpprec)} provides @code{%gamma} (Euler's constant) as a bigfloat.

@code{load ("bffac")} loads these functions.

@end deffn

@defvr {Option variable} bftorat
Default value: @code{false}

@code{bftorat} controls the conversion of bfloats to
rational numbers. 
When @code{bftorat} is @code{false},
@code{ratepsilon} will be used to
control the conversion (this results in relatively small rational
numbers).
When @code{bftorat} is @code{true},
the rational number generated will
accurately represent the bfloat.

@end defvr

@defvr {Option variable} bftrunc
Default value: @code{true}

@code{bftrunc} causes trailing zeroes in non-zero bigfloat
numbers not to be displayed.  Thus, if @code{bftrunc} is @code{false}, @code{bfloat (1)}
displays as @code{1.000000000000000B0}. Otherwise, this is displayed as
@code{1.0B0}.

@end defvr

@deffn {Function} cbffac (@var{z}, @var{fpprec})
Complex bigfloat factorial.

@code{load ("bffac")} loads this function.

@end deffn

@deffn {Function} float (@var{expr})
Converts integers, rational numbers and bigfloats in @var{expr}
to floating point numbers.  It is also an @code{evflag}, @code{float} causes
non-integral rational numbers and bigfloat numbers to be converted to
floating point.

@end deffn

@defvr {Option variable} float2bf
Default value: @code{false}
 
When @code{float2bf} is @code{false}, a warning message is printed when
a floating point number is converted into a bigfloat number (since
this may lead to loss of precision).

@end defvr

@deffn {Function} floatnump (@var{expr})
Returns @code{true} if @var{expr} is a floating point number, otherwise @code{false}.

@end deffn

@defvr {Option variable} fpprec
Default value: 16

@code{fpprec} is the number of significant digits for arithmetic on bigfloat numbers.
@code{fpprec} does not affect computations on ordinary floating point numbers.

See also @code{bfloat} and @code{fpprintprec}.

@end defvr

@defvr {Option variable} fpprintprec
Default value: 0

@code{fpprintprec} is the number of digits to print when printing an ordinary float or bigfloat number.

For ordinary floating point numbers,
when @code{fpprintprec} has a value between 2 and 16 (inclusive),
the number of digits printed is equal to @code{fpprintprec}.
Otherwise, @code{fpprintprec} is 0, or greater than 16,
and the number of digits printed is 16.

For bigfloat numbers,
when @code{fpprintprec} has a value between 2 and @code{fpprec} (inclusive),
the number of digits printed is equal to @code{fpprintprec}.
Otherwise, @code{fpprintprec} is 0, or greater than @code{fpprec},
and the number of digits printed is equal to @code{fpprec}.

@code{fpprintprec} cannot be 1.

@end defvr

@deffn {Lisp function} ?round (@var{x})
@deffnx {Lisp function} ?round (@var{x}, @var{divisor})
Round the floating point @var{x} to the nearest integer.   The argument
must be an ordinary float, not a bigfloat.   The @code{?} beginning the name
indicates this is a Lisp function.

@example
(%i1) ?round (-2.8);
(%o1)                            - 3
@end example

@end deffn

@deffn {Lisp function} ?truncate (@var{x})
@deffnx {Lisp function} ?truncate (@var{x}, @var{divisor})
Truncate the floating point @var{x} towards 0, to become an integer.   The argument
must be an ordinary float, not a bigfloat.  The @code{?} beginning the name
indicates this is a Lisp function.

@example
(%i1) ?truncate (-2.8);
(%o1)                            - 2
(%i2) ?truncate (2.4);
(%o2)                             2
(%i3) ?truncate (2.8);
(%o3)                             2
@end example

@end deffn