1Math::BigFloat(3)     User Contributed Perl Documentation    Math::BigFloat(3)
2
3
4

NAME

6       Math::BigFloat - Arbitrary size floating point math package
7

SYNOPSIS

9         use Math::BigFloat;
10
11         # Configuration methods (may be used as class methods and instance methods)
12
13         Math::BigFloat->accuracy();     # get class accuracy
14         Math::BigFloat->accuracy($n);   # set class accuracy
15         Math::BigFloat->precision();    # get class precision
16         Math::BigFloat->precision($n);  # set class precision
17         Math::BigFloat->round_mode();   # get class rounding mode
18         Math::BigFloat->round_mode($m); # set global round mode, must be one of
19                                         # 'even', 'odd', '+inf', '-inf', 'zero',
20                                         # 'trunc', or 'common'
21         Math::BigFloat->config("lib");  # name of backend math library
22
23         # Constructor methods (when the class methods below are used as instance
24         # methods, the value is assigned the invocand)
25
26         $x = Math::BigFloat->new($str);               # defaults to 0
27         $x = Math::BigFloat->new('0x123');            # from hexadecimal
28         $x = Math::BigFloat->new('0b101');            # from binary
29         $x = Math::BigFloat->from_hex('0xc.afep+3');  # from hex
30         $x = Math::BigFloat->from_hex('cafe');        # ditto
31         $x = Math::BigFloat->from_oct('1.3267p-4');   # from octal
32         $x = Math::BigFloat->from_oct('0377');        # ditto
33         $x = Math::BigFloat->from_bin('0b1.1001p-4'); # from binary
34         $x = Math::BigFloat->from_bin('0101');        # ditto
35         $x = Math::BigFloat->bzero();                 # create a +0
36         $x = Math::BigFloat->bone();                  # create a +1
37         $x = Math::BigFloat->bone('-');               # create a -1
38         $x = Math::BigFloat->binf();                  # create a +inf
39         $x = Math::BigFloat->binf('-');               # create a -inf
40         $x = Math::BigFloat->bnan();                  # create a Not-A-Number
41         $x = Math::BigFloat->bpi();                   # returns pi
42
43         $y = $x->copy();        # make a copy (unlike $y = $x)
44         $y = $x->as_int();      # return as BigInt
45
46         # Boolean methods (these don't modify the invocand)
47
48         $x->is_zero();          # if $x is 0
49         $x->is_one();           # if $x is +1
50         $x->is_one("+");        # ditto
51         $x->is_one("-");        # if $x is -1
52         $x->is_inf();           # if $x is +inf or -inf
53         $x->is_inf("+");        # if $x is +inf
54         $x->is_inf("-");        # if $x is -inf
55         $x->is_nan();           # if $x is NaN
56
57         $x->is_positive();      # if $x > 0
58         $x->is_pos();           # ditto
59         $x->is_negative();      # if $x < 0
60         $x->is_neg();           # ditto
61
62         $x->is_odd();           # if $x is odd
63         $x->is_even();          # if $x is even
64         $x->is_int();           # if $x is an integer
65
66         # Comparison methods
67
68         $x->bcmp($y);           # compare numbers (undef, < 0, == 0, > 0)
69         $x->bacmp($y);          # compare absolutely (undef, < 0, == 0, > 0)
70         $x->beq($y);            # true if and only if $x == $y
71         $x->bne($y);            # true if and only if $x != $y
72         $x->blt($y);            # true if and only if $x < $y
73         $x->ble($y);            # true if and only if $x <= $y
74         $x->bgt($y);            # true if and only if $x > $y
75         $x->bge($y);            # true if and only if $x >= $y
76
77         # Arithmetic methods
78
79         $x->bneg();             # negation
80         $x->babs();             # absolute value
81         $x->bsgn();             # sign function (-1, 0, 1, or NaN)
82         $x->bnorm();            # normalize (no-op)
83         $x->binc();             # increment $x by 1
84         $x->bdec();             # decrement $x by 1
85         $x->badd($y);           # addition (add $y to $x)
86         $x->bsub($y);           # subtraction (subtract $y from $x)
87         $x->bmul($y);           # multiplication (multiply $x by $y)
88         $x->bmuladd($y,$z);     # $x = $x * $y + $z
89         $x->bdiv($y);           # division (floored), set $x to quotient
90                                 # return (quo,rem) or quo if scalar
91         $x->btdiv($y);          # division (truncated), set $x to quotient
92                                 # return (quo,rem) or quo if scalar
93         $x->bmod($y);           # modulus (x % y)
94         $x->btmod($y);          # modulus (truncated)
95         $x->bmodinv($mod);      # modular multiplicative inverse
96         $x->bmodpow($y,$mod);   # modular exponentiation (($x ** $y) % $mod)
97         $x->bpow($y);           # power of arguments (x ** y)
98         $x->blog();             # logarithm of $x to base e (Euler's number)
99         $x->blog($base);        # logarithm of $x to base $base (e.g., base 2)
100         $x->bexp();             # calculate e ** $x where e is Euler's number
101         $x->bnok($y);           # x over y (binomial coefficient n over k)
102         $x->bsin();             # sine
103         $x->bcos();             # cosine
104         $x->batan();            # inverse tangent
105         $x->batan2($y);         # two-argument inverse tangent
106         $x->bsqrt();            # calculate square root
107         $x->broot($y);          # $y'th root of $x (e.g. $y == 3 => cubic root)
108         $x->bfac();             # factorial of $x (1*2*3*4*..$x)
109
110         $x->blsft($n);          # left shift $n places in base 2
111         $x->blsft($n,$b);       # left shift $n places in base $b
112                                 # returns (quo,rem) or quo (scalar context)
113         $x->brsft($n);          # right shift $n places in base 2
114         $x->brsft($n,$b);       # right shift $n places in base $b
115                                 # returns (quo,rem) or quo (scalar context)
116
117         # Bitwise methods
118
119         $x->band($y);           # bitwise and
120         $x->bior($y);           # bitwise inclusive or
121         $x->bxor($y);           # bitwise exclusive or
122         $x->bnot();             # bitwise not (two's complement)
123
124         # Rounding methods
125         $x->round($A,$P,$mode); # round to accuracy or precision using
126                                 # rounding mode $mode
127         $x->bround($n);         # accuracy: preserve $n digits
128         $x->bfround($n);        # $n > 0: round to $nth digit left of dec. point
129                                 # $n < 0: round to $nth digit right of dec. point
130         $x->bfloor();           # round towards minus infinity
131         $x->bceil();            # round towards plus infinity
132         $x->bint();             # round towards zero
133
134         # Other mathematical methods
135
136         $x->bgcd($y);            # greatest common divisor
137         $x->blcm($y);            # least common multiple
138
139         # Object property methods (do not modify the invocand)
140
141         $x->sign();              # the sign, either +, - or NaN
142         $x->digit($n);           # the nth digit, counting from the right
143         $x->digit(-$n);          # the nth digit, counting from the left
144         $x->length();            # return number of digits in number
145         ($xl,$f) = $x->length(); # length of number and length of fraction
146                                  # part, latter is always 0 digits long
147                                  # for Math::BigInt objects
148         $x->mantissa();          # return (signed) mantissa as BigInt
149         $x->exponent();          # return exponent as BigInt
150         $x->parts();             # return (mantissa,exponent) as BigInt
151         $x->sparts();            # mantissa and exponent (as integers)
152         $x->nparts();            # mantissa and exponent (normalised)
153         $x->eparts();            # mantissa and exponent (engineering notation)
154         $x->dparts();            # integer and fraction part
155
156         # Conversion methods (do not modify the invocand)
157
158         $x->bstr();         # decimal notation, possibly zero padded
159         $x->bsstr();        # string in scientific notation with integers
160         $x->bnstr();        # string in normalized notation
161         $x->bestr();        # string in engineering notation
162         $x->bdstr();        # string in decimal notation
163         $x->as_hex();       # as signed hexadecimal string with prefixed 0x
164         $x->as_bin();       # as signed binary string with prefixed 0b
165         $x->as_oct();       # as signed octal string with prefixed 0
166
167         # Other conversion methods
168
169         $x->numify();           # return as scalar (might overflow or underflow)
170

DESCRIPTION

172       Math::BigFloat provides support for arbitrary precision floating point.
173       Overloading is also provided for Perl operators.
174
175       All operators (including basic math operations) are overloaded if you
176       declare your big floating point numbers as
177
178         $x = Math::BigFloat -> new('12_3.456_789_123_456_789E-2');
179
180       Operations with overloaded operators preserve the arguments, which is
181       exactly what you expect.
182
183   Input
184       Input values to these routines may be any scalar number or string that
185       looks like a number and represents a floating point number.
186
187       ·   Leading and trailing whitespace is ignored.
188
189       ·   Leading and trailing zeros are ignored.
190
191       ·   If the string has a "0x" prefix, it is interpreted as a hexadecimal
192           number.
193
194       ·   If the string has a "0b" prefix, it is interpreted as a binary
195           number.
196
197       ·   For hexadecimal and binary numbers, the exponent must be separated
198           from the significand (mantissa) by the letter "p" or "P", not "e"
199           or "E" as with decimal numbers.
200
201       ·   One underline is allowed between any two digits, including
202           hexadecimal and binary digits.
203
204       ·   If the string can not be interpreted, NaN is returned.
205
206       Octal numbers are typically prefixed by "0", but since leading zeros
207       are stripped, these methods can not automatically recognize octal
208       numbers, so use the constructor from_oct() to interpret octal strings.
209
210       Some examples of valid string input
211
212           Input string                Resulting value
213           123                         123
214           1.23e2                      123
215           12300e-2                    123
216           0xcafe                      51966
217           0b1101                      13
218           67_538_754                  67538754
219           -4_5_6.7_8_9e+0_1_0         -4567890000000
220           0x1.921fb5p+1               3.14159262180328369140625e+0
221           0b1.1001p-4                 9.765625e-2
222
223   Output
224       Output values are usually Math::BigFloat objects.
225
226       Boolean operators "is_zero()", "is_one()", "is_inf()", etc. return true
227       or false.
228
229       Comparison operators "bcmp()" and "bacmp()") return -1, 0, 1, or undef.
230

METHODS

232       Math::BigFloat supports all methods that Math::BigInt supports, except
233       it calculates non-integer results when possible. Please see
234       Math::BigInt for a full description of each method. Below are just the
235       most important differences:
236
237   Configuration methods
238       accuracy()
239               $x->accuracy(5);           # local for $x
240               CLASS->accuracy(5);        # global for all members of CLASS
241                                          # Note: This also applies to new()!
242
243               $A = $x->accuracy();       # read out accuracy that affects $x
244               $A = CLASS->accuracy();    # read out global accuracy
245
246           Set or get the global or local accuracy, aka how many significant
247           digits the results have. If you set a global accuracy, then this
248           also applies to new()!
249
250           Warning! The accuracy sticks, e.g. once you created a number under
251           the influence of "CLASS->accuracy($A)", all results from math
252           operations with that number will also be rounded.
253
254           In most cases, you should probably round the results explicitly
255           using one of "round()" in Math::BigInt, "bround()" in Math::BigInt
256           or "bfround()" in Math::BigInt or by passing the desired accuracy
257           to the math operation as additional parameter:
258
259               my $x = Math::BigInt->new(30000);
260               my $y = Math::BigInt->new(7);
261               print scalar $x->copy()->bdiv($y, 2);           # print 4300
262               print scalar $x->copy()->bdiv($y)->bround(2);   # print 4300
263
264       precision()
265               $x->precision(-2);        # local for $x, round at the second
266                                         # digit right of the dot
267               $x->precision(2);         # ditto, round at the second digit
268                                         # left of the dot
269
270               CLASS->precision(5);      # Global for all members of CLASS
271                                         # This also applies to new()!
272               CLASS->precision(-5);     # ditto
273
274               $P = CLASS->precision();  # read out global precision
275               $P = $x->precision();     # read out precision that affects $x
276
277           Note: You probably want to use "accuracy()" instead. With
278           "accuracy()" you set the number of digits each result should have,
279           with "precision()" you set the place where to round!
280
281   Constructor methods
282       from_hex()
283               $x -> from_hex("0x1.921fb54442d18p+1");
284               $x = Math::BigFloat -> from_hex("0x1.921fb54442d18p+1");
285
286           Interpret input as a hexadecimal string.A prefix ("0x", "x",
287           ignoring case) is optional. A single underscore character ("_") may
288           be placed between any two digits. If the input is invalid, a NaN is
289           returned. The exponent is in base 2 using decimal digits.
290
291           If called as an instance method, the value is assigned to the
292           invocand.
293
294       from_oct()
295               $x -> from_oct("1.3267p-4");
296               $x = Math::BigFloat -> from_oct("1.3267p-4");
297
298           Interpret input as an octal string. A single underscore character
299           ("_") may be placed between any two digits. If the input is
300           invalid, a NaN is returned. The exponent is in base 2 using decimal
301           digits.
302
303           If called as an instance method, the value is assigned to the
304           invocand.
305
306       from_bin()
307               $x -> from_bin("0b1.1001p-4");
308               $x = Math::BigFloat -> from_bin("0b1.1001p-4");
309
310           Interpret input as a hexadecimal string. A prefix ("0b" or "b",
311           ignoring case) is optional. A single underscore character ("_") may
312           be placed between any two digits. If the input is invalid, a NaN is
313           returned. The exponent is in base 2 using decimal digits.
314
315           If called as an instance method, the value is assigned to the
316           invocand.
317
318       bpi()
319               print Math::BigFloat->bpi(100), "\n";
320
321           Calculate PI to N digits (including the 3 before the dot). The
322           result is rounded according to the current rounding mode, which
323           defaults to "even".
324
325           This method was added in v1.87 of Math::BigInt (June 2007).
326
327   Arithmetic methods
328       bmuladd()
329               $x->bmuladd($y,$z);
330
331           Multiply $x by $y, and then add $z to the result.
332
333           This method was added in v1.87 of Math::BigInt (June 2007).
334
335       bdiv()
336               $q = $x->bdiv($y);
337               ($q, $r) = $x->bdiv($y);
338
339           In scalar context, divides $x by $y and returns the result to the
340           given or default accuracy/precision. In list context, does floored
341           division (F-division), returning an integer $q and a remainder $r
342           so that $x = $q * $y + $r. The remainer (modulo) is equal to what
343           is returned by "$x-"bmod($y)>.
344
345       bmod()
346               $x->bmod($y);
347
348           Returns $x modulo $y. When $x is finite, and $y is finite and non-
349           zero, the result is identical to the remainder after floored
350           division (F-division). If, in addition, both $x and $y are
351           integers, the result is identical to the result from Perl's %
352           operator.
353
354       bexp()
355               $x->bexp($accuracy);            # calculate e ** X
356
357           Calculates the expression "e ** $x" where "e" is Euler's number.
358
359           This method was added in v1.82 of Math::BigInt (April 2007).
360
361       bnok()
362               $x->bnok($y);   # x over y (binomial coefficient n over k)
363
364           Calculates the binomial coefficient n over k, also called the
365           "choose" function. The result is equivalent to:
366
367               ( n )      n!
368               | - |  = -------
369               ( k )    k!(n-k)!
370
371           This method was added in v1.84 of Math::BigInt (April 2007).
372
373       bsin()
374               my $x = Math::BigFloat->new(1);
375               print $x->bsin(100), "\n";
376
377           Calculate the sinus of $x, modifying $x in place.
378
379           This method was added in v1.87 of Math::BigInt (June 2007).
380
381       bcos()
382               my $x = Math::BigFloat->new(1);
383               print $x->bcos(100), "\n";
384
385           Calculate the cosinus of $x, modifying $x in place.
386
387           This method was added in v1.87 of Math::BigInt (June 2007).
388
389       batan()
390               my $x = Math::BigFloat->new(1);
391               print $x->batan(100), "\n";
392
393           Calculate the arcus tanges of $x, modifying $x in place. See also
394           "batan2()".
395
396           This method was added in v1.87 of Math::BigInt (June 2007).
397
398       batan2()
399               my $y = Math::BigFloat->new(2);
400               my $x = Math::BigFloat->new(3);
401               print $y->batan2($x), "\n";
402
403           Calculate the arcus tanges of $y divided by $x, modifying $y in
404           place.  See also "batan()".
405
406           This method was added in v1.87 of Math::BigInt (June 2007).
407
408       as_float()
409           This method is called when Math::BigFloat encounters an object it
410           doesn't know how to handle. For instance, assume $x is a
411           Math::BigFloat, or subclass thereof, and $y is defined, but not a
412           Math::BigFloat, or subclass thereof. If you do
413
414               $x -> badd($y);
415
416           $y needs to be converted into an object that $x can deal with. This
417           is done by first checking if $y is something that $x might be
418           upgraded to. If that is the case, no further attempts are made. The
419           next is to see if $y supports the method "as_float()". The method
420           "as_float()" is expected to return either an object that has the
421           same class as $x, a subclass thereof, or a string that
422           "ref($x)->new()" can parse to create an object.
423
424           In Math::BigFloat, "as_float()" has the same effect as "copy()".
425
426   ACCURACY AND PRECISION
427       See also: Rounding.
428
429       Math::BigFloat supports both precision (rounding to a certain place
430       before or after the dot) and accuracy (rounding to a certain number of
431       digits). For a full documentation, examples and tips on these topics
432       please see the large section about rounding in Math::BigInt.
433
434       Since things like sqrt(2) or "1 / 3" must presented with a limited
435       accuracy lest a operation consumes all resources, each operation
436       produces no more than the requested number of digits.
437
438       If there is no global precision or accuracy set, and the operation in
439       question was not called with a requested precision or accuracy, and the
440       input $x has no accuracy or precision set, then a fallback parameter
441       will be used. For historical reasons, it is called "div_scale" and can
442       be accessed via:
443
444           $d = Math::BigFloat->div_scale();       # query
445           Math::BigFloat->div_scale($n);          # set to $n digits
446
447       The default value for "div_scale" is 40.
448
449       In case the result of one operation has more digits than specified, it
450       is rounded. The rounding mode taken is either the default mode, or the
451       one supplied to the operation after the scale:
452
453           $x = Math::BigFloat->new(2);
454           Math::BigFloat->accuracy(5);              # 5 digits max
455           $y = $x->copy()->bdiv(3);                 # gives 0.66667
456           $y = $x->copy()->bdiv(3,6);               # gives 0.666667
457           $y = $x->copy()->bdiv(3,6,undef,'odd');   # gives 0.666667
458           Math::BigFloat->round_mode('zero');
459           $y = $x->copy()->bdiv(3,6);               # will also give 0.666667
460
461       Note that "Math::BigFloat->accuracy()" and
462       "Math::BigFloat->precision()" set the global variables, and thus any
463       newly created number will be subject to the global rounding
464       immediately. This means that in the examples above, the 3 as argument
465       to "bdiv()" will also get an accuracy of 5.
466
467       It is less confusing to either calculate the result fully, and
468       afterwards round it explicitly, or use the additional parameters to the
469       math functions like so:
470
471           use Math::BigFloat;
472           $x = Math::BigFloat->new(2);
473           $y = $x->copy()->bdiv(3);
474           print $y->bround(5),"\n";               # gives 0.66667
475
476           or
477
478           use Math::BigFloat;
479           $x = Math::BigFloat->new(2);
480           $y = $x->copy()->bdiv(3,5);             # gives 0.66667
481           print "$y\n";
482
483   Rounding
484       bfround ( +$scale )
485           Rounds to the $scale'th place left from the '.', counting from the
486           dot.  The first digit is numbered 1.
487
488       bfround ( -$scale )
489           Rounds to the $scale'th place right from the '.', counting from the
490           dot.
491
492       bfround ( 0 )
493           Rounds to an integer.
494
495       bround  ( +$scale )
496           Preserves accuracy to $scale digits from the left (aka significant
497           digits) and pads the rest with zeros. If the number is between 1
498           and -1, the significant digits count from the first non-zero after
499           the '.'
500
501       bround  ( -$scale ) and bround ( 0 )
502           These are effectively no-ops.
503
504       All rounding functions take as a second parameter a rounding mode from
505       one of the following: 'even', 'odd', '+inf', '-inf', 'zero', 'trunc' or
506       'common'.
507
508       The default rounding mode is 'even'. By using
509       "Math::BigFloat->round_mode($round_mode);" you can get and set the
510       default mode for subsequent rounding. The usage of
511       "$Math::BigFloat::$round_mode" is no longer supported.  The second
512       parameter to the round functions then overrides the default
513       temporarily.
514
515       The "as_number()" function returns a BigInt from a Math::BigFloat. It
516       uses 'trunc' as rounding mode to make it equivalent to:
517
518           $x = 2.5;
519           $y = int($x) + 2;
520
521       You can override this by passing the desired rounding mode as parameter
522       to "as_number()":
523
524           $x = Math::BigFloat->new(2.5);
525           $y = $x->as_number('odd');      # $y = 3
526

Autocreating constants

528       After "use Math::BigFloat ':constant'" all the floating point constants
529       in the given scope are converted to "Math::BigFloat". This conversion
530       happens at compile time.
531
532       In particular
533
534           perl -MMath::BigFloat=:constant -e 'print 2E-100,"\n"'
535
536       prints the value of "2E-100". Note that without conversion of constants
537       the expression 2E-100 will be calculated as normal floating point
538       number.
539
540       Please note that ':constant' does not affect integer constants, nor
541       binary nor hexadecimal constants. Use bignum or Math::BigInt to get
542       this to work.
543
544   Math library
545       Math with the numbers is done (by default) by a module called
546       Math::BigInt::Calc. This is equivalent to saying:
547
548           use Math::BigFloat lib => 'Calc';
549
550       You can change this by using:
551
552           use Math::BigFloat lib => 'GMP';
553
554       Note: General purpose packages should not be explicit about the library
555       to use; let the script author decide which is best.
556
557       Note: The keyword 'lib' will warn when the requested library could not
558       be loaded. To suppress the warning use 'try' instead:
559
560           use Math::BigFloat try => 'GMP';
561
562       If your script works with huge numbers and Calc is too slow for them,
563       you can also for the loading of one of these libraries and if none of
564       them can be used, the code will die:
565
566           use Math::BigFloat only => 'GMP,Pari';
567
568       The following would first try to find Math::BigInt::Foo, then
569       Math::BigInt::Bar, and when this also fails, revert to
570       Math::BigInt::Calc:
571
572           use Math::BigFloat lib => 'Foo,Math::BigInt::Bar';
573
574       See the respective low-level library documentation for further details.
575
576       Please note that Math::BigFloat does not use the denoted library
577       itself, but it merely passes the lib argument to Math::BigInt. So,
578       instead of the need to do:
579
580           use Math::BigInt lib => 'GMP';
581           use Math::BigFloat;
582
583       you can roll it all into one line:
584
585           use Math::BigFloat lib => 'GMP';
586
587       It is also possible to just require Math::BigFloat:
588
589           require Math::BigFloat;
590
591       This will load the necessary things (like BigInt) when they are needed,
592       and automatically.
593
594       See Math::BigInt for more details than you ever wanted to know about
595       using a different low-level library.
596
597   Using Math::BigInt::Lite
598       For backwards compatibility reasons it is still possible to request a
599       different storage class for use with Math::BigFloat:
600
601           use Math::BigFloat with => 'Math::BigInt::Lite';
602
603       However, this request is ignored, as the current code now uses the low-
604       level math library for directly storing the number parts.
605

EXPORTS

607       "Math::BigFloat" exports nothing by default, but can export the "bpi()"
608       method:
609
610           use Math::BigFloat qw/bpi/;
611
612           print bpi(10), "\n";
613

CAVEATS

615       Do not try to be clever to insert some operations in between switching
616       libraries:
617
618           require Math::BigFloat;
619           my $matter = Math::BigFloat->bone() + 4;    # load BigInt and Calc
620           Math::BigFloat->import( lib => 'Pari' );    # load Pari, too
621           my $anti_matter = Math::BigFloat->bone()+4; # now use Pari
622
623       This will create objects with numbers stored in two different backend
624       libraries, and VERY BAD THINGS will happen when you use these together:
625
626           my $flash_and_bang = $matter + $anti_matter;    # Don't do this!
627
628       stringify, bstr()
629           Both stringify and bstr() now drop the leading '+'. The old code
630           would return '+1.23', the new returns '1.23'. See the documentation
631           in Math::BigInt for reasoning and details.
632
633       brsft()
634           The following will probably not print what you expect:
635
636               my $c = Math::BigFloat->new('3.14159');
637               print $c->brsft(3,10),"\n";     # prints 0.00314153.1415
638
639           It prints both quotient and remainder, since print calls "brsft()"
640           in list context. Also, "$c->brsft()" will modify $c, so be careful.
641           You probably want to use
642
643               print scalar $c->copy()->brsft(3,10),"\n";
644               # or if you really want to modify $c
645               print scalar $c->brsft(3,10),"\n";
646
647           instead.
648
649       Modifying and =
650           Beware of:
651
652               $x = Math::BigFloat->new(5);
653               $y = $x;
654
655           It will not do what you think, e.g. making a copy of $x. Instead it
656           just makes a second reference to the same object and stores it in
657           $y. Thus anything that modifies $x will modify $y (except
658           overloaded math operators), and vice versa. See Math::BigInt for
659           details and how to avoid that.
660
661       precision() vs. accuracy()
662           A common pitfall is to use "precision()" when you want to round a
663           result to a certain number of digits:
664
665               use Math::BigFloat;
666
667               Math::BigFloat->precision(4);           # does not do what you
668                                                       # think it does
669               my $x = Math::BigFloat->new(12345);     # rounds $x to "12000"!
670               print "$x\n";                           # print "12000"
671               my $y = Math::BigFloat->new(3);         # rounds $y to "0"!
672               print "$y\n";                           # print "0"
673               $z = $x / $y;                           # 12000 / 0 => NaN!
674               print "$z\n";
675               print $z->precision(),"\n";             # 4
676
677           Replacing "precision()" with "accuracy()" is probably not what you
678           want, either:
679
680               use Math::BigFloat;
681
682               Math::BigFloat->accuracy(4);          # enables global rounding:
683               my $x = Math::BigFloat->new(123456);  # rounded immediately
684                                                     #   to "12350"
685               print "$x\n";                         # print "123500"
686               my $y = Math::BigFloat->new(3);       # rounded to "3
687               print "$y\n";                         # print "3"
688               print $z = $x->copy()->bdiv($y),"\n"; # 41170
689               print $z->accuracy(),"\n";            # 4
690
691           What you want to use instead is:
692
693               use Math::BigFloat;
694
695               my $x = Math::BigFloat->new(123456);    # no rounding
696               print "$x\n";                           # print "123456"
697               my $y = Math::BigFloat->new(3);         # no rounding
698               print "$y\n";                           # print "3"
699               print $z = $x->copy()->bdiv($y,4),"\n"; # 41150
700               print $z->accuracy(),"\n";              # undef
701
702           In addition to computing what you expected, the last example also
703           does not "taint" the result with an accuracy or precision setting,
704           which would influence any further operation.
705

BUGS

707       Please report any bugs or feature requests to "bug-math-bigint at
708       rt.cpan.org", or through the web interface at
709       <https://rt.cpan.org/Ticket/Create.html?Queue=Math-BigInt> (requires
710       login).  We will be notified, and then you'll automatically be notified
711       of progress on your bug as I make changes.
712

SUPPORT

714       You can find documentation for this module with the perldoc command.
715
716           perldoc Math::BigFloat
717
718       You can also look for information at:
719
720       ·   RT: CPAN's request tracker
721
722           <https://rt.cpan.org/Public/Dist/Display.html?Name=Math-BigInt>
723
724       ·   AnnoCPAN: Annotated CPAN documentation
725
726           <http://annocpan.org/dist/Math-BigInt>
727
728       ·   CPAN Ratings
729
730           <http://cpanratings.perl.org/dist/Math-BigInt>
731
732       ·   Search CPAN
733
734           <http://search.cpan.org/dist/Math-BigInt/>
735
736       ·   CPAN Testers Matrix
737
738           <http://matrix.cpantesters.org/?dist=Math-BigInt>
739
740       ·   The Bignum mailing list
741
742           ·   Post to mailing list
743
744               "bignum at lists.scsys.co.uk"
745
746           ·   View mailing list
747
748               <http://lists.scsys.co.uk/pipermail/bignum/>
749
750           ·   Subscribe/Unsubscribe
751
752               <http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/bignum>
753

LICENSE

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

SEE ALSO

759       Math::BigFloat and Math::BigInt as well as the backends
760       Math::BigInt::FastCalc, Math::BigInt::GMP, and Math::BigInt::Pari.
761
762       The pragmas bignum, bigint and bigrat also might be of interest because
763       they solve the autoupgrading/downgrading issue, at least partly.
764

AUTHORS

766       ·   Mark Biggar, overloaded interface by Ilya Zakharevich, 1996-2001.
767
768       ·   Completely rewritten by Tels <http://bloodgate.com> in 2001-2008.
769
770       ·   Florian Ragwitz <flora@cpan.org>, 2010.
771
772       ·   Peter John Acklam <pjacklam@online.no>, 2011-.
773
774
775
776perl v5.28.1                      2018-04-18                 Math::BigFloat(3)
Impressum