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

DESCRIPTION

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

METHODS

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

Autocreating constants

563       After "use Math::BigFloat ':constant'" all the floating point constants
564       in the given scope are converted to "Math::BigFloat". This conversion
565       happens at compile time.
566
567       In particular
568
569           perl -MMath::BigFloat=:constant -e 'print 2E-100,"\n"'
570
571       prints the value of "2E-100". Note that without conversion of constants
572       the expression 2E-100 will be calculated as normal floating point
573       number.
574
575       Please note that ':constant' does not affect integer constants, nor
576       binary nor hexadecimal constants. Use bignum or Math::BigInt to get
577       this to work.
578
579   Math library
580       Math with the numbers is done (by default) by a module called
581       Math::BigInt::Calc. This is equivalent to saying:
582
583           use Math::BigFloat lib => 'Calc';
584
585       You can change this by using:
586
587           use Math::BigFloat lib => 'GMP';
588
589       Note: General purpose packages should not be explicit about the library
590       to use; let the script author decide which is best.
591
592       Note: The keyword 'lib' will warn when the requested library could not
593       be loaded. To suppress the warning use 'try' instead:
594
595           use Math::BigFloat try => 'GMP';
596
597       If your script works with huge numbers and Calc is too slow for them,
598       you can also for the loading of one of these libraries and if none of
599       them can be used, the code will die:
600
601           use Math::BigFloat only => 'GMP,Pari';
602
603       The following would first try to find Math::BigInt::Foo, then
604       Math::BigInt::Bar, and when this also fails, revert to
605       Math::BigInt::Calc:
606
607           use Math::BigFloat lib => 'Foo,Math::BigInt::Bar';
608
609       See the respective low-level library documentation for further details.
610
611       Please note that Math::BigFloat does not use the denoted library
612       itself, but it merely passes the lib argument to Math::BigInt. So,
613       instead of the need to do:
614
615           use Math::BigInt lib => 'GMP';
616           use Math::BigFloat;
617
618       you can roll it all into one line:
619
620           use Math::BigFloat lib => 'GMP';
621
622       It is also possible to just require Math::BigFloat:
623
624           require Math::BigFloat;
625
626       This will load the necessary things (like BigInt) when they are needed,
627       and automatically.
628
629       See Math::BigInt for more details than you ever wanted to know about
630       using a different low-level library.
631
632   Using Math::BigInt::Lite
633       For backwards compatibility reasons it is still possible to request a
634       different storage class for use with Math::BigFloat:
635
636           use Math::BigFloat with => 'Math::BigInt::Lite';
637
638       However, this request is ignored, as the current code now uses the low-
639       level math library for directly storing the number parts.
640

EXPORTS

642       "Math::BigFloat" exports nothing by default, but can export the "bpi()"
643       method:
644
645           use Math::BigFloat qw/bpi/;
646
647           print bpi(10), "\n";
648

CAVEATS

650       Do not try to be clever to insert some operations in between switching
651       libraries:
652
653           require Math::BigFloat;
654           my $matter = Math::BigFloat->bone() + 4;    # load BigInt and Calc
655           Math::BigFloat->import( lib => 'Pari' );    # load Pari, too
656           my $anti_matter = Math::BigFloat->bone()+4; # now use Pari
657
658       This will create objects with numbers stored in two different backend
659       libraries, and VERY BAD THINGS will happen when you use these together:
660
661           my $flash_and_bang = $matter + $anti_matter;    # Don't do this!
662
663       stringify, bstr()
664           Both stringify and bstr() now drop the leading '+'. The old code
665           would return '+1.23', the new returns '1.23'. See the documentation
666           in Math::BigInt for reasoning and details.
667
668       brsft()
669           The following will probably not print what you expect:
670
671               my $c = Math::BigFloat->new('3.14159');
672               print $c->brsft(3,10),"\n";     # prints 0.00314153.1415
673
674           It prints both quotient and remainder, since print calls "brsft()"
675           in list context. Also, "$c->brsft()" will modify $c, so be careful.
676           You probably want to use
677
678               print scalar $c->copy()->brsft(3,10),"\n";
679               # or if you really want to modify $c
680               print scalar $c->brsft(3,10),"\n";
681
682           instead.
683
684       Modifying and =
685           Beware of:
686
687               $x = Math::BigFloat->new(5);
688               $y = $x;
689
690           It will not do what you think, e.g. making a copy of $x. Instead it
691           just makes a second reference to the same object and stores it in
692           $y. Thus anything that modifies $x will modify $y (except
693           overloaded math operators), and vice versa. See Math::BigInt for
694           details and how to avoid that.
695
696       precision() vs. accuracy()
697           A common pitfall is to use "precision()" when you want to round a
698           result to a certain number of digits:
699
700               use Math::BigFloat;
701
702               Math::BigFloat->precision(4);           # does not do what you
703                                                       # think it does
704               my $x = Math::BigFloat->new(12345);     # rounds $x to "12000"!
705               print "$x\n";                           # print "12000"
706               my $y = Math::BigFloat->new(3);         # rounds $y to "0"!
707               print "$y\n";                           # print "0"
708               $z = $x / $y;                           # 12000 / 0 => NaN!
709               print "$z\n";
710               print $z->precision(),"\n";             # 4
711
712           Replacing "precision()" with "accuracy()" is probably not what you
713           want, either:
714
715               use Math::BigFloat;
716
717               Math::BigFloat->accuracy(4);          # enables global rounding:
718               my $x = Math::BigFloat->new(123456);  # rounded immediately
719                                                     #   to "12350"
720               print "$x\n";                         # print "123500"
721               my $y = Math::BigFloat->new(3);       # rounded to "3
722               print "$y\n";                         # print "3"
723               print $z = $x->copy()->bdiv($y),"\n"; # 41170
724               print $z->accuracy(),"\n";            # 4
725
726           What you want to use instead is:
727
728               use Math::BigFloat;
729
730               my $x = Math::BigFloat->new(123456);    # no rounding
731               print "$x\n";                           # print "123456"
732               my $y = Math::BigFloat->new(3);         # no rounding
733               print "$y\n";                           # print "3"
734               print $z = $x->copy()->bdiv($y,4),"\n"; # 41150
735               print $z->accuracy(),"\n";              # undef
736
737           In addition to computing what you expected, the last example also
738           does not "taint" the result with an accuracy or precision setting,
739           which would influence any further operation.
740

BUGS

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

SUPPORT

749       You can find documentation for this module with the perldoc command.
750
751           perldoc Math::BigFloat
752
753       You can also look for information at:
754
755       ·   RT: CPAN's request tracker
756
757           <https://rt.cpan.org/Public/Dist/Display.html?Name=Math-BigInt>
758
759       ·   AnnoCPAN: Annotated CPAN documentation
760
761           <http://annocpan.org/dist/Math-BigInt>
762
763       ·   CPAN Ratings
764
765           <https://cpanratings.perl.org/dist/Math-BigInt>
766
767       ·   MetaCPAN
768
769           <https://metacpan.org/release/Math-BigInt>
770
771       ·   CPAN Testers Matrix
772
773           <http://matrix.cpantesters.org/?dist=Math-BigInt>
774
775       ·   The Bignum mailing list
776
777           ·   Post to mailing list
778
779               "bignum at lists.scsys.co.uk"
780
781           ·   View mailing list
782
783               <http://lists.scsys.co.uk/pipermail/bignum/>
784
785           ·   Subscribe/Unsubscribe
786
787               <http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/bignum>
788

LICENSE

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

SEE ALSO

794       Math::BigFloat and Math::BigInt as well as the backends
795       Math::BigInt::FastCalc, Math::BigInt::GMP, and Math::BigInt::Pari.
796
797       The pragmas bignum, bigint and bigrat also might be of interest because
798       they solve the autoupgrading/downgrading issue, at least partly.
799

AUTHORS

801       ·   Mark Biggar, overloaded interface by Ilya Zakharevich, 1996-2001.
802
803       ·   Completely rewritten by Tels <http://bloodgate.com> in 2001-2008.
804
805       ·   Florian Ragwitz <flora@cpan.org>, 2010.
806
807       ·   Peter John Acklam <pjacklam@online.no>, 2011-.
808
809
810
811perl v5.30.1                      2020-01-30                 Math::BigFloat(3)
Impressum