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

DESCRIPTION

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

METHODS

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

NUMERIC LITERALS

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

EXPORTS

706       "Math::BigFloat" exports nothing by default, but can export the "bpi()"
707       method:
708
709           use Math::BigFloat qw/bpi/;
710
711           print bpi(10), "\n";
712

CAVEATS

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

BUGS

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

SUPPORT

813       You can find documentation for this module with the perldoc command.
814
815           perldoc Math::BigFloat
816
817       You can also look for information at:
818
819       •   GitHub
820
821           <https://github.com/pjacklam/p5-Math-BigInt>
822
823       •   RT: CPAN's request tracker
824
825           <https://rt.cpan.org/Dist/Display.html?Name=Math-BigInt>
826
827       •   MetaCPAN
828
829           <https://metacpan.org/release/Math-BigInt>
830
831       •   CPAN Testers Matrix
832
833           <http://matrix.cpantesters.org/?dist=Math-BigInt>
834
835       •   CPAN Ratings
836
837           <https://cpanratings.perl.org/dist/Math-BigInt>
838
839       •   The Bignum mailing list
840
841           •   Post to mailing list
842
843               "bignum at lists.scsys.co.uk"
844
845           •   View mailing list
846
847               <http://lists.scsys.co.uk/pipermail/bignum/>
848
849           •   Subscribe/Unsubscribe
850
851               <http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/bignum>
852

LICENSE

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

SEE ALSO

858       Math::BigInt and Math::BigInt as well as the backends
859       Math::BigInt::FastCalc, Math::BigInt::GMP, and Math::BigInt::Pari.
860
861       The pragmas bignum, bigint and bigrat.
862

AUTHORS

864       •   Mark Biggar, overloaded interface by Ilya Zakharevich, 1996-2001.
865
866       •   Completely rewritten by Tels <http://bloodgate.com> in 2001-2008.
867
868       •   Florian Ragwitz <flora@cpan.org>, 2010.
869
870       •   Peter John Acklam <pjacklam@gmail.com>, 2011-.
871
872
873
874perl v5.34.1                      2022-04-13                 Math::BigFloat(3)
Impressum