math::bigfloat(3)

NAME

Math::BigFloat - Arbitrary size floating point math pack
age

SYNOPSIS

use Math::BigFloat;
# Number creation
$x = Math::BigFloat->new($str);       # defaults to 0
$nan  = Math::BigFloat->bnan();        #  create  a  NotANumber
$zero = Math::BigFloat->bzero();      # create a +0
$inf = Math::BigFloat->binf();        # create a +inf
$inf = Math::BigFloat->binf('-');     # create a -inf
$one = Math::BigFloat->bone();        # create a +1
$one = Math::BigFloat->bone('-');     # create a -1
# Testing
$x->is_zero();                # true if arg is +0
$x->is_nan();                 # true if arg is NaN
$x->is_one();                 # true if arg is +1
$x->is_one('-');              # true if arg is -1
$x->is_odd();                  #  true if odd, false for
even
$x->is_even();                # true if even, false  for
odd
$x->is_positive();            # true if >= 0
$x->is_negative();            # true if <  0
$x->is_inf(sign);              #  true  if +inf, or -inf
(default is '+')
$x->bcmp($y);                  #  compare  numbers  (undef,<0,=0,>0)
$x->bacmp($y);                 # compare absolutely (undef,<0,=0,>0)
$x->sign();                   # return the sign,  either
+,- or NaN
$x->digit($n);                 #  return  the nth digit,
counting from right
$x->digit(-$n);               # return  the  nth  digit,
counting from left
# The following all modify their first argument:
# set
$x->bzero();                  # set $i to 0
$x->bnan();                   # set $i to NaN
$x->bone();                   # set $x to +1
$x->bone('-');                # set $x to -1
$x->binf();                   # set $x to inf
$x->binf('-');                # set $x to -inf
$x->bneg();                   # negation
$x->babs();                   # absolute value
$x->bnorm();                  # normalize (no-op)
$x->bnot();                    #  two's  complement (bit
wise not)
$x->binc();                   # increment x by 1
$x->bdec();                   # decrement x by 1
$x->badd($y);                 # addition (add $y to $x)
$x->bsub($y);                 # subtraction (subtract $y
from $x)
$x->bmul($y);                 # multiplication (multiply
$x by $y)
$x->bdiv($y);                 # divide, set $i  to  quotient
                              #  return (quo,rem) or quo
if scalar
$x->bmod($y);                 # modulus
$x->bpow($y);                  #  power   of   arguments
(a**b)
$x->blsft($y);                # left shift
$x->brsft($y);                # right shift
                              #  return (quo,rem) or quo
if scalar
$x->blog($base);              # logarithm  of  $x,  base
defaults to e
                              #  (other bases than e not
supported yet)
$x->band($y);                 # bit-wise and
$x->bior($y);                 # bit-wise inclusive or
$x->bxor($y);                 # bit-wise exclusive or
$x->bnot();                   # bit-wise not (two's complement)
$x->bsqrt();                  # calculate square-root
$x->bfac();                      #   factorial   of   $x
(1*2*3*4*..$x)
$x->bround($N);               # accuracy:  preserver  $N
digits
$x->bfround($N);               # precision: round to the
$Nth digit
# The following do not modify their arguments:
bgcd(@values);                # greatest common divisor
blcm(@values);                # lowest common  multiplicator
$x->bstr();                   # return string
$x->bsstr();                   # return string in scientific notation
$x->bfloor();                 # return integer  less  or
equal than $x
$x->bceil();                   #  return integer greater
or equal than $x
$x->exponent();               # return exponent as  BigInt
$x->mantissa();                # return mantissa as BigInt
$x->parts();                  #  return  (mantissa,exponent) as BigInt
$x->length();                  #  number  of digits (w/o
sign and '.')
($l,$f) = $x->length();       # number  of  digits,  and
length of fraction
$x->precision();              # return P of $x (or global, if P of $x undef)
$x->precision($n);            # set P of $x to $n
$x->accuracy();               # return A of $x (or global, if A of $x undef)
$x->accuracy($n);             # set P $x to $n
Math::BigFloat->precision();  # get/set global P for all
BigFloat objects
Math::BigFloat->accuracy();   # get/set global A for all
BigFloat objects

DESCRIPTION

All operators (inlcuding basic math operations) are over
loaded if you declare your big floating point numbers as

$i = new Math::BigFloat '12_3.456_789_123_456_789E-2';

Operations with overloaded operators preserve the argu
ments, which is exactly what you expect.

Canonical notation

Input to these routines are either BigFloat objects, or
strings of the following four forms:

· "/^[+-]+$/"

· "/^[+-]+.*$/"

· "/^[+-]+E[+-]?+$/"

· "/^[+-]*.+E[+-]?+$/"

all with optional leading and trailing zeros and/or
spaces. Additonally, numbers are allowed to have an under
score between any two digits.

Empty strings as well as other illegal numbers results in
'NaN'.

bnorm() on a BigFloat object is now effectively a no-op, since the numbers are always stored in normalized form. On
a string, it creates a BigFloat object.

Output

Output values are BigFloat objects (normalized), except
for bstr() and bsstr().

The string output will always have leading and trailing
zeros stripped and drop a plus sign. "bstr()" will give
you always the form with a decimal point, while "bsstr()"
(for scientific) gives you the scientific notation.

Input bstr() bsstr()
'-0' '0' '0E1'
' -123 123 123' '-123123123'

'-123123123E0'
'00.0123' '0.0123' '123E-4'
'123.45E-2' '1.2345' '12345E-4'
'10E+3' '10000' '1E4'

Some routines ("is_odd()", "is_even()", "is_zero()",
"is_one()", "is_nan()") return true or false, while others
("bcmp()", "bacmp()") return either undef, <0, 0 or >0 and
are suited for sort.

Actual math is done by using BigInts to represent the man
tissa and exponent. The sign "/^[+-]$/" is stored sepa
rately. The string 'NaN' is used to represent the result
when input arguments are not numbers, as well as the
result of dividing by zero.

"mantissa()", "exponent()" and "parts()"

"mantissa()" and "exponent()" return the said parts of the
BigFloat as BigInts such that:

$m = $x->mantissa();
$e = $x->exponent();
$y = $m * ( 10 ** $e );
print "ok0 if $x == $y;

"($m,$e) = $x->parts();" is just a shortcut giving you
both of them.

A zero is represented and returned as 0E1, not 0E0 (after
Knuth).

Currently the mantissa is reduced as much as possible,
favouring higher exponents over lower ones (e.g. returning
1e7 instead of 10e6 or 10000000e0). This might change in
the future, so do not depend on it.

Accuracy vs. Precision

See also: Rounding.

Math::BigFloat supports both precision and accuracy. For a
full documentation, examples and tips on these topics
please see the large section in Math::BigInt.

Since things like sqrt(2) or 1/3 must presented with a
limited precision lest a operation consumes all resources,
each operation produces no more than
"Math::BigFloat::precision()" digits.

In case the result of one operation has more precision
than specified, it is rounded. The rounding mode taken is
either the default mode, or the one supplied to the opera
tion after the scale:

$x = Math::BigFloat->new(2);
Math::BigFloat::precision(5); # 5 digits

max
$y = $x->copy()->bdiv(3); # will

give 0.66666
$y = $x->copy()->bdiv(3,6); # will

give 0.666666
$y = $x->copy()->bdiv(3,6,'odd'); # will

give 0.666667
Math::BigFloat::round_mode('zero');
$y = $x->copy()->bdiv(3,6); # will

give 0.666666

Rounding

ffround ( +$scale )

Rounds to the $scale'th place left from the '.', count
ing from the dot. The first digit is numbered 1.

ffround ( -$scale )

Rounds to the $scale'th place right from the '.', count
ing from the dot.

ffround ( 0 )

Rounds to an integer.

fround ( +$scale )

Preserves accuracy to $scale digits from the left (aka
significant digits) and pads the rest with zeros. If the
number is between 1 and -1, the significant digits count
from the first non-zero after the '.'

fround ( -$scale ) and fround ( 0 )

These are effetively no-ops.

All rounding functions take as a second parameter a round
ing mode from one of the following: 'even', 'odd', '+inf',
'-inf', 'zero' or 'trunc'.

The default rounding mode is 'even'. By using
"Math::BigFloat::round_mode($round_mode);" you can get and
set the default mode for subsequent rounding. The usage of
"$Math::BigFloat::$round_mode" is no longer supported.
The second parameter to the round functions then overrides
the default temporarily.

The "as_number()" function returns a BigInt from a
Math::BigFloat. It uses 'trunc' as rounding mode to make
it equivalent to:

$x = 2.5;
$y = int($x) + 2;

You can override this by passing the desired rounding mode
as parameter to "as_number()":

$x = Math::BigFloat->new(2.5);
$y = $x->as_number('odd'); # $y = 3

EXAMPLES

# not ready yet

Autocreating constants

After "use Math::BigFloat ':constant'" all the floating
point constants in the given scope are converted to
"Math::BigFloat". This conversion happens at compile time.

In particular

perl -MMath::BigFloat=:constant -e 'print 2E-100,"0'

prints the value of "2E-100". Note that without conversion
of constants the expression 2E-100 will be calculated as
normal floating point number.

Please note that ':constant' does not affect integer con
stants, nor binary nor hexadecimal constants. Use bignum
or Math::BigInt to get this to work.

Math library

Math with the numbers is done (by default) by a module
called Math::BigInt::Calc. This is equivalent to saying:

use Math::BigFloat lib => 'Calc';

You can change this by using:

use Math::BigFloat lib => 'BitVect';

The following would first try to find Math::BigInt::Foo,
then Math::BigInt::Bar, and when this also fails, revert
to Math::BigInt::Calc:

use Math::BigFloat lib => 'Foo,Math::BigInt::Bar';

Calc.pm uses as internal format an array of elements of
some decimal base (usually 1e7, but this might be differen
for some systems) with the least significant digit first,
while BitVect.pm uses a bit vector of base 2, most signif
icant bit first. Other modules might use even different
means of representing the numbers. See the respective mod
ule documentation for further details.

Please note that Math::BigFloat does not use the denoted
library itself, but it merely passes the lib argument to
Math::BigInt. So, instead of the need to do:

use Math::BigInt lib => 'GMP';
use Math::BigFloat;

you can roll it all into one line:

use Math::BigFloat lib => 'GMP';

Use the lib, Luke! And see "Using Math::BigInt::Lite" for
more details.

Using Math::BigInt::Lite

It is possible to use Math::BigInt::Lite with
Math::BigFloat:

# 1
use Math::BigFloat with => 'Math::BigInt::Lite';

There is no need to "use Math::BigInt" or "use Math::Big
Int::Lite", but you can combine these if you want. For
instance, you may want to use Math::BigInt objects in your
main script, too.

# 2
use Math::BigInt;
use Math::BigFloat with => 'Math::BigInt::Lite';

Of course, you can combine this with the "lib" parameter.

# 3
use Math::BigFloat with => 'Math::BigInt::Lite',

lib => 'GMP,Pari';

If you want to use Math::BigInt's, too, simple add a
Math::BigInt before:

# 4
use Math::BigInt;
use Math::BigFloat with => 'Math::BigInt::Lite',

lib => 'GMP,Pari';

Notice that the module with the last "lib" will "win" and
thus it's lib will be used if the lib is available:

# 5
use Math::BigInt lib => 'Bar,Baz';
use Math::BigFloat with => 'Math::BigInt::Lite',

lib => 'Foo';

That would try to load Foo, Bar, Baz and Calc (in that
order). Or in other words, Math::BigFloat will try to
retain previously loaded libs when you don't specify it
one.

Actually, the lib loading order would be "Bar,Baz,Calc",
and then "Foo,Bar,Baz,Calc", but independend of which lib
exists, the result is the same as trying the latter load
alone, except for the fact that Bar or Baz might be loaded
needlessly in an intermidiate step

The old way still works though:

# 6
use Math::BigInt lib => 'Bar,Baz';
use Math::BigFloat;

But examples #3 and #4 are recommended for usage.

BUGS

· The following does not work yet:

$m = $x->mantissa();
$e = $x->exponent();
$y = $m * ( 10 ** $e );
print "ok0 if $x == $y;

· There is no fmod() function yet.

CAVEAT

stringify, bstr()

Both stringify and bstr() now drop the leading '+'. The
old code would return '+1.23', the new returns '1.23'.
See the documentation in Math::BigInt for reasoning and
details.

bdiv

The following will probably not do what you expect:

print $c->bdiv(123.456),"0;

It prints both quotient and reminder since print works in
list context. Also, bdiv() will modify $c, so be care
full. You probably want to use

print $c / 123.456,"0;
print scalar $c->bdiv(123.456),"0; # or if you

want to modify $c

instead.

Modifying and =

Beware of:

$x = Math::BigFloat->new(5);
$y = $x;

It will not do what you think, e.g. making a copy of $x.
Instead it just makes a second reference to the same
object and stores it in $y. Thus anything that modifies
$x will modify $y, and vice versa.

$x->bmul(2);
print "$x, $y0; # prints '10, 10'

If you want a true copy of $x, use:

$y = $x->copy();

See also the documentation in overload regarding "=".

bpow

"bpow()" now modifies the first argument, unlike the old
code which left it alone and only returned the result.
This is to be consistent with "badd()" etc. The first
will modify $x, the second one won't:

print bpow($x,$i),"0; # modify $x
print $x->bpow($i),"0; # ditto
print $x ** $i,"0; # leave $x alone

LICENSE

This program is free software; you may redistribute it
and/or modify it under the same terms as Perl itself.

AUTHORS

Mark Biggar, overloaded interface by Ilya Zakharevich.
Completely rewritten by Tels http://bloodgate.com in 2001.

perl v5.8.0 2002-07-07 Math::BigFloat(3)