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

DESCRIPTION

184       Math::BigFloat provides support for arbitrary precision floating point.
185       Overloading is also provided for Perl operators.
186
187       All operators (including basic math operations) are overloaded if you
188       declare your big floating point numbers as
189
190         $x = Math::BigFloat -> new('12_3.456_789_123_456_789E-2');
191
192       Operations with overloaded operators preserve the arguments, which is
193       exactly what you expect.
194
195   Input
196       Input values to these routines may be any scalar number or string that
197       looks like a number. Anything that is accepted by Perl as a literal
198       numeric constant should be accepted by this module.
199
200       •   Leading and trailing whitespace is ignored.
201
202       •   Leading zeros are ignored, except for floating point numbers with a
203           binary exponent, in which case the number is interpreted as an
204           octal floating point number. For example, "01.4p+0" gives 1.5,
205           "00.4p+0" gives 0.5, but "0.4p+0" gives a NaN. And while "0377"
206           gives 255, "0377p0" gives 255.
207
208       •   If the string has a "0x" or "0X" prefix, it is interpreted as a
209           hexadecimal number.
210
211       •   If the string has a "0o" or "0O" prefix, it is interpreted as an
212           octal number. A floating point literal with a "0" prefix is also
213           interpreted as an octal number.
214
215       •   If the string has a "0b" or "0B" prefix, it is interpreted as a
216           binary number.
217
218       •   Underline characters are allowed in the same way as they are
219           allowed in literal numerical constants.
220
221       •   If the string can not be interpreted, NaN is returned.
222
223       •   For hexadecimal, octal, and binary floating point numbers, the
224           exponent must be separated from the significand (mantissa) by the
225           letter "p" or "P", not "e" or "E" as with decimal numbers.
226
227       Some examples of valid string input
228
229           Input string                Resulting value
230
231           123                         123
232           1.23e2                      123
233           12300e-2                    123
234
235           67_538_754                  67538754
236           -4_5_6.7_8_9e+0_1_0         -4567890000000
237
238           0x13a                       314
239           0x13ap0                     314
240           0x1.3ap+8                   314
241           0x0.00013ap+24              314
242           0x13a000p-12                314
243
244           0o472                       314
245           0o1.164p+8                  314
246           0o0.0001164p+20             314
247           0o1164000p-10               314
248
249           0472                        472     Note!
250           01.164p+8                   314
251           00.0001164p+20              314
252           01164000p-10                314
253
254           0b100111010                 314
255           0b1.0011101p+8              314
256           0b0.00010011101p+12         314
257           0b100111010000p-3           314
258
259           0x1.921fb5p+1               3.14159262180328369140625e+0
260           0o1.2677025p1               2.71828174591064453125
261           01.2677025p1                2.71828174591064453125
262           0b1.1001p-4                 9.765625e-2
263
264   Output
265       Output values are usually Math::BigFloat objects.
266
267       Boolean operators is_zero(), is_one(), is_inf(), etc. return true or
268       false.
269
270       Comparison operators bcmp() and bacmp()) return -1, 0, 1, or undef.
271

METHODS

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

NUMERIC LITERALS

602       After "use Math::BigFloat ':constant'" all numeric literals in the
603       given scope are converted to "Math::BigFloat" objects. This conversion
604       happens at compile time.
605
606       For example,
607
608           perl -MMath::BigFloat=:constant -le 'print 2e-150'
609
610       prints the exact value of 2e-150. Note that without conversion of
611       constants the expression 2e-150 is calculated using Perl scalars, which
612       leads to an inaccuracte result.
613
614       Note that strings are not affected, so that
615
616           use Math::BigFloat qw/:constant/;
617
618           $y = "1234567890123456789012345678901234567890"
619                   + "123456789123456789";
620
621       does not give you what you expect. You need an explicit
622       Math::BigFloat->new() around at least one of the operands. You should
623       also quote large constants to prevent loss of precision:
624
625           use Math::BigFloat;
626
627           $x = Math::BigFloat->new("1234567889123456789123456789123456789");
628
629       Without the quotes Perl converts the large number to a floating point
630       constant at compile time, and then converts the result to a
631       Math::BigFloat object at runtime, which results in an inaccurate
632       result.
633
634   Hexadecimal, octal, and binary floating point literals
635       Perl (and this module) accepts hexadecimal, octal, and binary floating
636       point literals, but use them with care with Perl versions before
637       v5.32.0, because some versions of Perl silently give the wrong result.
638       Below are some examples of different ways to write the number decimal
639       314.
640
641       Hexadecimal floating point literals:
642
643           0x1.3ap+8         0X1.3AP+8
644           0x1.3ap8          0X1.3AP8
645           0x13a0p-4         0X13A0P-4
646
647       Octal floating point literals (with "0" prefix):
648
649           01.164p+8         01.164P+8
650           01.164p8          01.164P8
651           011640p-4         011640P-4
652
653       Octal floating point literals (with "0o" prefix) (requires v5.34.0):
654
655           0o1.164p+8        0O1.164P+8
656           0o1.164p8         0O1.164P8
657           0o11640p-4        0O11640P-4
658
659       Binary floating point literals:
660
661           0b1.0011101p+8    0B1.0011101P+8
662           0b1.0011101p8     0B1.0011101P8
663           0b10011101000p-2  0B10011101000P-2
664
665   Math library
666       Math with the numbers is done (by default) by a module called
667       Math::BigInt::Calc. This is equivalent to saying:
668
669           use Math::BigFloat lib => "Calc";
670
671       You can change this by using:
672
673           use Math::BigFloat lib => "GMP";
674
675       Note: General purpose packages should not be explicit about the library
676       to use; let the script author decide which is best.
677
678       Note: The keyword 'lib' will warn when the requested library could not
679       be loaded. To suppress the warning use 'try' instead:
680
681           use Math::BigFloat try => "GMP";
682
683       If your script works with huge numbers and Calc is too slow for them,
684       you can also for the loading of one of these libraries and if none of
685       them can be used, the code will die:
686
687           use Math::BigFloat only => "GMP,Pari";
688
689       The following would first try to find Math::BigInt::Foo, then
690       Math::BigInt::Bar, and when this also fails, revert to
691       Math::BigInt::Calc:
692
693           use Math::BigFloat lib => "Foo,Math::BigInt::Bar";
694
695       See the respective low-level library documentation for further details.
696
697       See Math::BigInt for more details about using a different low-level
698       library.
699
700   Using Math::BigInt::Lite
701       For backwards compatibility reasons it is still possible to request a
702       different storage class for use with Math::BigFloat:
703
704           use Math::BigFloat with => 'Math::BigInt::Lite';
705
706       However, this request is ignored, as the current code now uses the low-
707       level math library for directly storing the number parts.
708

EXPORTS

710       "Math::BigFloat" exports nothing by default, but can export the bpi()
711       method:
712
713           use Math::BigFloat qw/bpi/;
714
715           print bpi(10), "\n";
716

CAVEATS

718       Do not try to be clever to insert some operations in between switching
719       libraries:
720
721           require Math::BigFloat;
722           my $matter = Math::BigFloat->bone() + 4;    # load BigInt and Calc
723           Math::BigFloat->import( lib => 'Pari' );    # load Pari, too
724           my $anti_matter = Math::BigFloat->bone()+4; # now use Pari
725
726       This will create objects with numbers stored in two different backend
727       libraries, and VERY BAD THINGS will happen when you use these together:
728
729           my $flash_and_bang = $matter + $anti_matter;    # Don't do this!
730
731       stringify, bstr()
732           Both stringify and bstr() now drop the leading '+'. The old code
733           would return '+1.23', the new returns '1.23'. See the documentation
734           in Math::BigInt for reasoning and details.
735
736       brsft()
737           The following will probably not print what you expect:
738
739               my $c = Math::BigFloat->new('3.14159');
740               print $c->brsft(3,10),"\n";     # prints 0.00314153.1415
741
742           It prints both quotient and remainder, since print calls brsft() in
743           list context. Also, "$c->brsft()" will modify $c, so be careful.
744           You probably want to use
745
746               print scalar $c->copy()->brsft(3,10),"\n";
747               # or if you really want to modify $c
748               print scalar $c->brsft(3,10),"\n";
749
750           instead.
751
752       Modifying and =
753           Beware of:
754
755               $x = Math::BigFloat->new(5);
756               $y = $x;
757
758           It will not do what you think, e.g. making a copy of $x. Instead it
759           just makes a second reference to the same object and stores it in
760           $y. Thus anything that modifies $x will modify $y (except
761           overloaded math operators), and vice versa. See Math::BigInt for
762           details and how to avoid that.
763
764       precision() vs. accuracy()
765           A common pitfall is to use "precision()" when you want to round a
766           result to a certain number of digits:
767
768               use Math::BigFloat;
769
770               Math::BigFloat->precision(4);           # does not do what you
771                                                       # think it does
772               my $x = Math::BigFloat->new(12345);     # rounds $x to "12000"!
773               print "$x\n";                           # print "12000"
774               my $y = Math::BigFloat->new(3);         # rounds $y to "0"!
775               print "$y\n";                           # print "0"
776               $z = $x / $y;                           # 12000 / 0 => NaN!
777               print "$z\n";
778               print $z->precision(),"\n";             # 4
779
780           Replacing "precision()" with "accuracy()" is probably not what you
781           want, either:
782
783               use Math::BigFloat;
784
785               Math::BigFloat->accuracy(4);          # enables global rounding:
786               my $x = Math::BigFloat->new(123456);  # rounded immediately
787                                                     #   to "12350"
788               print "$x\n";                         # print "123500"
789               my $y = Math::BigFloat->new(3);       # rounded to "3
790               print "$y\n";                         # print "3"
791               print $z = $x->copy()->bdiv($y),"\n"; # 41170
792               print $z->accuracy(),"\n";            # 4
793
794           What you want to use instead is:
795
796               use Math::BigFloat;
797
798               my $x = Math::BigFloat->new(123456);    # no rounding
799               print "$x\n";                           # print "123456"
800               my $y = Math::BigFloat->new(3);         # no rounding
801               print "$y\n";                           # print "3"
802               print $z = $x->copy()->bdiv($y,4),"\n"; # 41150
803               print $z->accuracy(),"\n";              # undef
804
805           In addition to computing what you expected, the last example also
806           does not "taint" the result with an accuracy or precision setting,
807           which would influence any further operation.
808

BUGS

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

SUPPORT

817       You can find documentation for this module with the perldoc command.
818
819           perldoc Math::BigFloat
820
821       You can also look for information at:
822
823       •   GitHub
824
825           <https://github.com/pjacklam/p5-Math-BigInt>
826
827       •   RT: CPAN's request tracker
828
829           <https://rt.cpan.org/Dist/Display.html?Name=Math-BigInt>
830
831       •   MetaCPAN
832
833           <https://metacpan.org/release/Math-BigInt>
834
835       •   CPAN Testers Matrix
836
837           <http://matrix.cpantesters.org/?dist=Math-BigInt>
838

LICENSE

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

SEE ALSO

844       Math::BigInt and Math::BigInt as well as the backends
845       Math::BigInt::FastCalc, Math::BigInt::GMP, and Math::BigInt::Pari.
846
847       The pragmas bignum, bigint and bigrat.
848

AUTHORS

850       •   Mark Biggar, overloaded interface by Ilya Zakharevich, 1996-2001.
851
852       •   Completely rewritten by Tels <http://bloodgate.com> in 2001-2008.
853
854       •   Florian Ragwitz <flora@cpan.org>, 2010.
855
856       •   Peter John Acklam <pjacklam@gmail.com>, 2011-.
857
858
859
860perl v5.36.1                      2023-07-17                 Math::BigFloat(3)
Impressum