1Math::BigFloat(3) User Contributed Perl Documentation Math::BigFloat(3)
2
6 Math::BigFloat - arbitrary size floating point math package
7
9 use Math::BigFloat;
10 # Configuration methods (may be used as class methods and instance methods)
12 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 # Constructor methods (when the class methods below are used as instance
24 # methods, the value is assigned the invocand)
25 $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 $y = $x->copy(); # make a copy (unlike $y = $x)
48 $y = $x->as_int(); # return as BigInt
49 # Boolean methods (these don't modify the invocand)
51 $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 $x->is_positive(); # if $x > 0
62 $x->is_pos(); # ditto
63 $x->is_negative(); # if $x < 0
64 $x->is_neg(); # ditto
65 $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 # Comparison methods
71 $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 # Arithmetic methods
82 $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 $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 # Bitwise methods
122 $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 # 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 # Other mathematical methods
139 $x->bgcd($y); # greatest common divisor
141 $x->blcm($y); # least common multiple
142 # Object property methods (do not modify the invocand)
144 $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 # Conversion methods (do not modify the invocand)
164 $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 # Other conversion methods
176 $x->numify(); # return as scalar (might overflow or underflow)
178
180 Math::BigFloat provides support for arbitrary precision floating point.
181 Overloading is also provided for Perl operators.
182 All operators (including basic math operations) are overloaded if you
184 declare your big floating point numbers as
185 $x = Math::BigFloat -> new('12_3.456_789_123_456_789E-2');
187 Operations with overloaded operators preserve the arguments, which is
189 exactly what you expect.
190 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 • Leading and trailing whitespace is ignored.
197 • 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 • If the string has a "0x" or "0X" prefix, it is interpreted as a
205 hexadecimal number.
206 • 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 • If the string has a "0b" or "0B" prefix, it is interpreted as a
212 binary number.
213 • Underline characters are allowed in the same way as they are
215 allowed in literal numerical constants.
216 • If the string can not be interpreted, NaN is returned.
218 • 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 Some examples of valid string input
224 Input string Resulting value
226 123 123
228 1.23e2 123
229 12300e-2 123
230 67_538_754 67538754
232 -4_5_6.7_8_9e+0_1_0 -4567890000000
233 0x13a 314
235 0x13ap0 314
236 0x1.3ap+8 314
237 0x0.00013ap+24 314
238 0x13a000p-12 314
239 0o472 314
241 0o1.164p+8 314
242 0o0.0001164p+20 314
243 0o1164000p-10 314
244 0472 472 Note!
246 01.164p+8 314
247 00.0001164p+20 314
248 01164000p-10 314
249 0b100111010 314
251 0b1.0011101p+8 314
252 0b0.00010011101p+12 314
253 0b100111010000p-3 314
254 0x1.921fb5p+1 3.14159262180328369140625e+0
256 0o1.2677025p1 2.71828174591064453125
257 01.2677025p1 2.71828174591064453125
258 0b1.1001p-4 9.765625e-2
259 Output
261 Output values are usually Math::BigFloat objects.
262 Boolean operators "is_zero()", "is_one()", "is_inf()", etc. return true
264 or false.
265 Comparison operators "bcmp()" and "bacmp()") return -1, 0, 1, or undef.
267
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 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 $A = $x->accuracy(); # read out accuracy that affects $x
281 $A = CLASS->accuracy(); # read out global accuracy
282 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 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 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 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 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 CLASS->precision(5); # Global for all members of CLASS
308 # This also applies to new()!
309 CLASS->precision(-5); # ditto
310 $P = CLASS->precision(); # read out global precision
312 $P = $x->precision(); # read out precision that affects $x
313 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 Constructor methods
319 from_hex()
320 $x -> from_hex("0x1.921fb54442d18p+1");
321 $x = Math::BigFloat -> from_hex("0x1.921fb54442d18p+1");
322 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 If called as an instance method, the value is assigned to the
329 invocand.
330 from_oct()
332 $x -> from_oct("1.3267p-4");
333 $x = Math::BigFloat -> from_oct("1.3267p-4");
334 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 If called as an instance method, the value is assigned to the
341 invocand.
342 from_bin()
344 $x -> from_bin("0b1.1001p-4");
345 $x = Math::BigFloat -> from_bin("0b1.1001p-4");
346 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 If called as an instance method, the value is assigned to the
353 invocand.
354 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 # 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 bpi()
367 print Math::BigFloat->bpi(100), "\n";
368 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 This method was added in v1.87 of Math::BigInt (June 2007).
374 Arithmetic methods
376 bmuladd()
377 $x->bmuladd($y,$z);
378 Multiply $x by $y, and then add $z to the result.
380 This method was added in v1.87 of Math::BigInt (June 2007).
382 bdiv()
384 $q = $x->bdiv($y);
385 ($q, $r) = $x->bdiv($y);
386 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 bmod()
394 $x->bmod($y);
395 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 bexp()
403 $x->bexp($accuracy); # calculate e ** X
404 Calculates the expression "e ** $x" where "e" is Euler's number.
406 This method was added in v1.82 of Math::BigInt (April 2007).
408 bnok()
410 $x->bnok($y); # x over y (binomial coefficient n over k)
411 Calculates the binomial coefficient n over k, also called the
413 "choose" function. The result is equivalent to:
414 ( n ) n!
416 | - | = -------
417 ( k ) k!(n-k)!
418 This method was added in v1.84 of Math::BigInt (April 2007).
420 bsin()
422 my $x = Math::BigFloat->new(1);
423 print $x->bsin(100), "\n";
424 Calculate the sinus of $x, modifying $x in place.
426 This method was added in v1.87 of Math::BigInt (June 2007).
428 bcos()
430 my $x = Math::BigFloat->new(1);
431 print $x->bcos(100), "\n";
432 Calculate the cosinus of $x, modifying $x in place.
434 This method was added in v1.87 of Math::BigInt (June 2007).
436 batan()
438 my $x = Math::BigFloat->new(1);
439 print $x->batan(100), "\n";
440 Calculate the arcus tanges of $x, modifying $x in place. See also
442 "batan2()".
443 This method was added in v1.87 of Math::BigInt (June 2007).
445 batan2()
447 my $y = Math::BigFloat->new(2);
448 my $x = Math::BigFloat->new(3);
449 print $y->batan2($x), "\n";
450 Calculate the arcus tanges of $y divided by $x, modifying $y in
452 place. See also "batan()".
453 This method was added in v1.87 of Math::BigInt (June 2007).
455 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 $x -> badd($y);
463 $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 In Math::BigFloat, "as_float()" has the same effect as "copy()".
473 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 # $x = 3.1415926535897932385
481 $x = Math::BigFloat -> bpi(30);
482 $b = $x -> to_ieee754("binary64"); # encode as 8 bytes
484 $h = unpack "H*", $b; # "400921fb54442d18"
485 # 3.141592653589793115997963...
487 $y = Math::BigFloat -> from_ieee754($h, "binary64");
488 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 See also <https://en.wikipedia.org/wiki/IEEE_754>.
495 ACCURACY AND PRECISION
497 See also: Rounding.
498 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 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 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 $d = Math::BigFloat->div_scale(); # query
515 Math::BigFloat->div_scale($n); # set to $n digits
516 The default value for "div_scale" is 40.
518 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 $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 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 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 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 or
547 use Math::BigFloat;
549 $x = Math::BigFloat->new(2);
550 $y = $x->copy()->bdiv(3,5); # gives 0.66667
551 print "$y\n";
552 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 bfround ( -$scale )
559 Rounds to the $scale'th place right from the '.', counting from the
560 dot.
561 bfround ( 0 )
563 Rounds to an integer.
564 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 bround ( -$scale ) and bround ( 0 )
572 These are effectively no-ops.
573 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 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 The "as_number()" function returns a BigInt from a Math::BigFloat. It
586 uses 'trunc' as rounding mode to make it equivalent to:
587 $x = 2.5;
589 $y = int($x) + 2;
590 You can override this by passing the desired rounding mode as parameter
592 to "as_number()":
593 $x = Math::BigFloat->new(2.5);
595 $y = $x->as_number('odd'); # $y = 3
596
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 For example,
603 perl -MMath::BigFloat=:constant -le 'print 2e-150'
605 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 Note that strings are not affected, so that
611 use Math::BigFloat qw/:constant/;
613 $y = "1234567890123456789012345678901234567890"
615 + "123456789123456789";
616 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 use Math::BigFloat;
622 $x = Math::BigFloat->new("1234567889123456789123456789123456789");
624 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 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 Hexadecimal floating point literals:
638 0x1.3ap+8 0X1.3AP+8
640 0x1.3ap8 0X1.3AP8
641 0x13a0p-4 0X13A0P-4
642 Octal floating point literals (with "0" prefix):
644 01.164p+8 01.164P+8
646 01.164p8 01.164P8
647 011640p-4 011640P-4
648 Octal floating point literals (with "0o" prefix) (requires v5.34.0):
650 0o1.164p+8 0O1.164P+8
652 0o1.164p8 0O1.164P8
653 0o11640p-4 0O11640P-4
654 Binary floating point literals:
656 0b1.0011101p+8 0B1.0011101P+8
658 0b1.0011101p8 0B1.0011101P8
659 0b10011101000p-2 0B10011101000P-2
660 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 use Math::BigFloat lib => "Calc";
666 You can change this by using:
668 use Math::BigFloat lib => "GMP";
670 Note: General purpose packages should not be explicit about the library
672 to use; let the script author decide which is best.
673 Note: The keyword 'lib' will warn when the requested library could not
675 be loaded. To suppress the warning use 'try' instead:
676 use Math::BigFloat try => "GMP";
678 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 use Math::BigFloat only => "GMP,Pari";
684 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 use Math::BigFloat lib => "Foo,Math::BigInt::Bar";
690 See the respective low-level library documentation for further details.
692 See Math::BigInt for more details about using a different low-level
694 library.
695 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 use Math::BigFloat with => 'Math::BigInt::Lite';
701 However, this request is ignored, as the current code now uses the low-
703 level math library for directly storing the number parts.
704
706 "Math::BigFloat" exports nothing by default, but can export the "bpi()"
707 method:
708 use Math::BigFloat qw/bpi/;
710 print bpi(10), "\n";
712
714 Do not try to be clever to insert some operations in between switching
715 libraries:
716 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 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 my $flash_and_bang = $matter + $anti_matter; # Don't do this!
726 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 brsft()
733 The following will probably not print what you expect:
734 my $c = Math::BigFloat->new('3.14159');
736 print $c->brsft(3,10),"\n"; # prints 0.00314153.1415
737 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 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 instead.
747 Modifying and =
749 Beware of:
750 $x = Math::BigFloat->new(5);
752 $y = $x;
753 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 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 use Math::BigFloat;
765 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 Replacing "precision()" with "accuracy()" is probably not what you
777 want, either:
778 use Math::BigFloat;
780 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 What you want to use instead is:
791 use Math::BigFloat;
793 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 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
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
813 You can find documentation for this module with the perldoc command.
814 perldoc Math::BigFloat
816 You can also look for information at:
818 • GitHub
820 <https://github.com/pjacklam/p5-Math-BigInt>
822 • RT: CPAN's request tracker
824 <https://rt.cpan.org/Dist/Display.html?Name=Math-BigInt>
826 • MetaCPAN
828 <https://metacpan.org/release/Math-BigInt>
830 • CPAN Testers Matrix
832 <http://matrix.cpantesters.org/?dist=Math-BigInt>
834 • CPAN Ratings
836 <https://cpanratings.perl.org/dist/Math-BigInt>
838 • The Bignum mailing list
840 • Post to mailing list
842 "bignum at lists.scsys.co.uk"
844 • View mailing list
846 <http://lists.scsys.co.uk/pipermail/bignum/>
848 • Subscribe/Unsubscribe
850 <http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/bignum>
852
854 This program is free software; you may redistribute it and/or modify it
855 under the same terms as Perl itself.
856
858 Math::BigInt and Math::BigInt as well as the backends
859 Math::BigInt::FastCalc, Math::BigInt::GMP, and Math::BigInt::Pari.
860 The pragmas bignum, bigint and bigrat.
862
864 • Mark Biggar, overloaded interface by Ilya Zakharevich, 1996-2001.
865 • Completely rewritten by Tels <http://bloodgate.com> in 2001-2008.
867 • Florian Ragwitz <flora@cpan.org>, 2010.
869 • Peter John Acklam <pjacklam@gmail.com>, 2011-.
871perl v5.34.1 2022-04-13 Math::BigFloat(3)