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
160         # Conversion methods (do not modify the invocand)
161
162         $x->bstr();         # decimal notation, possibly zero padded
163         $x->bsstr();        # string in scientific notation with integers
164         $x->bnstr();        # string in normalized notation
165         $x->bestr();        # string in engineering notation
166         $x->bdstr();        # string in decimal notation
167         $x->as_hex();       # as signed hexadecimal string with prefixed 0x
168         $x->as_bin();       # as signed binary string with prefixed 0b
169         $x->as_oct();       # as signed octal string with prefixed 0
170         $x->to_ieee754($format); # to bytes encoded according to IEEE 754-2008
171
172         # Other conversion methods
173
174         $x->numify();           # return as scalar (might overflow or underflow)
175

DESCRIPTION

177       Math::BigFloat provides support for arbitrary precision floating point.
178       Overloading is also provided for Perl operators.
179
180       All operators (including basic math operations) are overloaded if you
181       declare your big floating point numbers as
182
183         $x = Math::BigFloat -> new('12_3.456_789_123_456_789E-2');
184
185       Operations with overloaded operators preserve the arguments, which is
186       exactly what you expect.
187
188   Input
189       Input values to these routines may be any scalar number or string that
190       looks like a number and represents a floating point number.
191
192       •   Leading and trailing whitespace is ignored.
193
194       •   Leading zeros are ignored, except for floating point numbers with a
195           binary exponent, in which case the number is interpreted as an
196           octal floating point number. For example, "01.4p+0" gives 1.5,
197           "00.4p+0" gives 0.5, but "0.4p+0" gives a NaN. And while "0377"
198           gives 255, "0377p0" gives 255.
199
200       •   If the string has a "0x" prefix, it is interpreted as a hexadecimal
201           number.
202
203       •   If the string has a "0o" prefix, it is interpreted as an octal
204           number.
205
206       •   If the string has a "0b" prefix, it is interpreted as a binary
207           number.
208
209       •   One underline is allowed between any two digits.
210
211       •   If the string can not be interpreted, NaN is returned.
212
213       •   For hexadecimal, octal, and binary numbers, the exponent must be
214           separated from the significand (mantissa) by the letter "p" or "P",
215           not "e" or "E" as with decimal numbers.
216
217       Some examples of valid string input
218
219           Input string                Resulting value
220           123                         123
221           1.23e2                      123
222           12300e-2                    123
223           0xcafe                      51966
224           0XCAFE                      51966
225           0o1337                      735
226           0O1337                      735
227           0b1101                      13
228           0B1101                      13
229           67_538_754                  67538754
230           -4_5_6.7_8_9e+0_1_0         -4567890000000
231           0x1.921fb5p+1               3.14159262180328369140625e+0
232           0o1.2677025p1               2.71828174591064453125
233           01.2677025p1                2.71828174591064453125
234           0b1.1001p-4                 9.765625e-2
235
236   Output
237       Output values are usually Math::BigFloat objects.
238
239       Boolean operators "is_zero()", "is_one()", "is_inf()", etc. return true
240       or false.
241
242       Comparison operators "bcmp()" and "bacmp()") return -1, 0, 1, or undef.
243

METHODS

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

Autocreating constants

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

EXPORTS

635       "Math::BigFloat" exports nothing by default, but can export the "bpi()"
636       method:
637
638           use Math::BigFloat qw/bpi/;
639
640           print bpi(10), "\n";
641

CAVEATS

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

BUGS

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

SUPPORT

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

LICENSE

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

SEE ALSO

787       Math::BigInt and Math::BigInt as well as the backends
788       Math::BigInt::FastCalc, Math::BigInt::GMP, and Math::BigInt::Pari.
789
790       The pragmas bignum, bigint and bigrat also might be of interest because
791       they solve the autoupgrading/downgrading issue, at least partly.
792

AUTHORS

794       •   Mark Biggar, overloaded interface by Ilya Zakharevich, 1996-2001.
795
796       •   Completely rewritten by Tels <http://bloodgate.com> in 2001-2008.
797
798       •   Florian Ragwitz <flora@cpan.org>, 2010.
799
800       •   Peter John Acklam <pjacklam@gmail.com>, 2011-.
801
802
803
804perl v5.34.0                      2021-09-22                 Math::BigFloat(3)
Impressum