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 $y = $x->as_float(); # return as a Math::BigFloat
50 $y = $x->as_rat(); # return as a Math::BigRat
51 # Boolean methods (these don't modify the invocand)
53 $x->is_zero(); # if $x is 0
55 $x->is_one(); # if $x is +1
56 $x->is_one("+"); # ditto
57 $x->is_one("-"); # if $x is -1
58 $x->is_inf(); # if $x is +inf or -inf
59 $x->is_inf("+"); # if $x is +inf
60 $x->is_inf("-"); # if $x is -inf
61 $x->is_nan(); # if $x is NaN
62 $x->is_positive(); # if $x > 0
64 $x->is_pos(); # ditto
65 $x->is_negative(); # if $x < 0
66 $x->is_neg(); # ditto
67 $x->is_odd(); # if $x is odd
69 $x->is_even(); # if $x is even
70 $x->is_int(); # if $x is an integer
71 # Comparison methods
73 $x->bcmp($y); # compare numbers (undef, < 0, == 0, > 0)
75 $x->bacmp($y); # compare absolutely (undef, < 0, == 0, > 0)
76 $x->beq($y); # true if and only if $x == $y
77 $x->bne($y); # true if and only if $x != $y
78 $x->blt($y); # true if and only if $x < $y
79 $x->ble($y); # true if and only if $x <= $y
80 $x->bgt($y); # true if and only if $x > $y
81 $x->bge($y); # true if and only if $x >= $y
82 # Arithmetic methods
84 $x->bneg(); # negation
86 $x->babs(); # absolute value
87 $x->bsgn(); # sign function (-1, 0, 1, or NaN)
88 $x->bnorm(); # normalize (no-op)
89 $x->binc(); # increment $x by 1
90 $x->bdec(); # decrement $x by 1
91 $x->badd($y); # addition (add $y to $x)
92 $x->bsub($y); # subtraction (subtract $y from $x)
93 $x->bmul($y); # multiplication (multiply $x by $y)
94 $x->bmuladd($y,$z); # $x = $x * $y + $z
95 $x->bdiv($y); # division (floored), set $x to quotient
96 # return (quo,rem) or quo if scalar
97 $x->btdiv($y); # division (truncated), set $x to quotient
98 # return (quo,rem) or quo if scalar
99 $x->bmod($y); # modulus (x % y)
100 $x->btmod($y); # modulus (truncated)
101 $x->bmodinv($mod); # modular multiplicative inverse
102 $x->bmodpow($y,$mod); # modular exponentiation (($x ** $y) % $mod)
103 $x->bpow($y); # power of arguments (x ** y)
104 $x->blog(); # logarithm of $x to base e (Euler's number)
105 $x->blog($base); # logarithm of $x to base $base (e.g., base 2)
106 $x->bexp(); # calculate e ** $x where e is Euler's number
107 $x->bnok($y); # x over y (binomial coefficient n over k)
108 $x->bsin(); # sine
109 $x->bcos(); # cosine
110 $x->batan(); # inverse tangent
111 $x->batan2($y); # two-argument inverse tangent
112 $x->bsqrt(); # calculate square root
113 $x->broot($y); # $y'th root of $x (e.g. $y == 3 => cubic root)
114 $x->bfac(); # factorial of $x (1*2*3*4*..$x)
115 $x->blsft($n); # left shift $n places in base 2
117 $x->blsft($n,$b); # left shift $n places in base $b
118 # returns (quo,rem) or quo (scalar context)
119 $x->brsft($n); # right shift $n places in base 2
120 $x->brsft($n,$b); # right shift $n places in base $b
121 # returns (quo,rem) or quo (scalar context)
122 # Bitwise methods
124 $x->band($y); # bitwise and
126 $x->bior($y); # bitwise inclusive or
127 $x->bxor($y); # bitwise exclusive or
128 $x->bnot(); # bitwise not (two's complement)
129 # Rounding methods
131 $x->round($A,$P,$mode); # round to accuracy or precision using
132 # rounding mode $mode
133 $x->bround($n); # accuracy: preserve $n digits
134 $x->bfround($n); # $n > 0: round to $nth digit left of dec. point
135 # $n < 0: round to $nth digit right of dec. point
136 $x->bfloor(); # round towards minus infinity
137 $x->bceil(); # round towards plus infinity
138 $x->bint(); # round towards zero
139 # Other mathematical methods
141 $x->bgcd($y); # greatest common divisor
143 $x->blcm($y); # least common multiple
144 # Object property methods (do not modify the invocand)
146 $x->sign(); # the sign, either +, - or NaN
148 $x->digit($n); # the nth digit, counting from the right
149 $x->digit(-$n); # the nth digit, counting from the left
150 $x->length(); # return number of digits in number
151 ($xl,$f) = $x->length(); # length of number and length of fraction
152 # part, latter is always 0 digits long
153 # for Math::BigInt objects
154 $x->mantissa(); # return (signed) mantissa as BigInt
155 $x->exponent(); # return exponent as BigInt
156 $x->parts(); # return (mantissa,exponent) as BigInt
157 $x->sparts(); # mantissa and exponent (as integers)
158 $x->nparts(); # mantissa and exponent (normalised)
159 $x->eparts(); # mantissa and exponent (engineering notation)
160 $x->dparts(); # integer and fraction part
161 $x->fparts(); # numerator and denominator
162 $x->numerator(); # numerator
163 $x->denominator(); # denominator
164 # Conversion methods (do not modify the invocand)
166 $x->bstr(); # decimal notation, possibly zero padded
168 $x->bsstr(); # string in scientific notation with integers
169 $x->bnstr(); # string in normalized notation
170 $x->bestr(); # string in engineering notation
171 $x->bdstr(); # string in decimal notation
172 $x->bfstr(); # string in fractional notation
173 $x->as_hex(); # as signed hexadecimal string with prefixed 0x
175 $x->as_bin(); # as signed binary string with prefixed 0b
176 $x->as_oct(); # as signed octal string with prefixed 0
177 $x->to_ieee754($format); # to bytes encoded according to IEEE 754-2008
178 # Other conversion methods
180 $x->numify(); # return as scalar (might overflow or underflow)
182
184 Math::BigFloat provides support for arbitrary precision floating point.
185 Overloading is also provided for Perl operators.
186 All operators (including basic math operations) are overloaded if you
188 declare your big floating point numbers as
189 $x = Math::BigFloat -> new('12_3.456_789_123_456_789E-2');
191 Operations with overloaded operators preserve the arguments, which is
193 exactly what you expect.
194 Input
196 Input values to these routines may be any scalar number or string that
197 looks like a number. Anything that is accepted by Perl as a literal
198 numeric constant should be accepted by this module.
199 • Leading and trailing whitespace is ignored.
201 • Leading zeros are ignored, except for floating point numbers with a
203 binary exponent, in which case the number is interpreted as an
204 octal floating point number. For example, "01.4p+0" gives 1.5,
205 "00.4p+0" gives 0.5, but "0.4p+0" gives a NaN. And while "0377"
206 gives 255, "0377p0" gives 255.
207 • If the string has a "0x" or "0X" prefix, it is interpreted as a
209 hexadecimal number.
210 • If the string has a "0o" or "0O" prefix, it is interpreted as an
212 octal number. A floating point literal with a "0" prefix is also
213 interpreted as an octal number.
214 • If the string has a "0b" or "0B" prefix, it is interpreted as a
216 binary number.
217 • Underline characters are allowed in the same way as they are
219 allowed in literal numerical constants.
220 • If the string can not be interpreted, NaN is returned.
222 • For hexadecimal, octal, and binary floating point numbers, the
224 exponent must be separated from the significand (mantissa) by the
225 letter "p" or "P", not "e" or "E" as with decimal numbers.
226 Some examples of valid string input
228 Input string Resulting value
230 123 123
232 1.23e2 123
233 12300e-2 123
234 67_538_754 67538754
236 -4_5_6.7_8_9e+0_1_0 -4567890000000
237 0x13a 314
239 0x13ap0 314
240 0x1.3ap+8 314
241 0x0.00013ap+24 314
242 0x13a000p-12 314
243 0o472 314
245 0o1.164p+8 314
246 0o0.0001164p+20 314
247 0o1164000p-10 314
248 0472 472 Note!
250 01.164p+8 314
251 00.0001164p+20 314
252 01164000p-10 314
253 0b100111010 314
255 0b1.0011101p+8 314
256 0b0.00010011101p+12 314
257 0b100111010000p-3 314
258 0x1.921fb5p+1 3.14159262180328369140625e+0
260 0o1.2677025p1 2.71828174591064453125
261 01.2677025p1 2.71828174591064453125
262 0b1.1001p-4 9.765625e-2
263 Output
265 Output values are usually Math::BigFloat objects.
266 Boolean operators is_zero(), is_one(), is_inf(), etc. return true or
268 false.
269 Comparison operators bcmp() and bacmp()) return -1, 0, 1, or undef.
271
273 Math::BigFloat supports all methods that Math::BigInt supports, except
274 it calculates non-integer results when possible. Please see
275 Math::BigInt for a full description of each method. Below are just the
276 most important differences:
277 Configuration methods
279 accuracy()
280 $x->accuracy(5); # local for $x
281 CLASS->accuracy(5); # global for all members of CLASS
282 # Note: This also applies to new()!
283 $A = $x->accuracy(); # read out accuracy that affects $x
285 $A = CLASS->accuracy(); # read out global accuracy
286 Set or get the global or local accuracy, aka how many significant
288 digits the results have. If you set a global accuracy, then this
289 also applies to new()!
290 Warning! The accuracy sticks, e.g. once you created a number under
292 the influence of "CLASS->accuracy($A)", all results from math
293 operations with that number will also be rounded.
294 In most cases, you should probably round the results explicitly
296 using one of "round()" in Math::BigInt, "bround()" in Math::BigInt
297 or "bfround()" in Math::BigInt or by passing the desired accuracy
298 to the math operation as additional parameter:
299 my $x = Math::BigInt->new(30000);
301 my $y = Math::BigInt->new(7);
302 print scalar $x->copy()->bdiv($y, 2); # print 4300
303 print scalar $x->copy()->bdiv($y)->bround(2); # print 4300
304 precision()
306 $x->precision(-2); # local for $x, round at the second
307 # digit right of the dot
308 $x->precision(2); # ditto, round at the second digit
309 # left of the dot
310 CLASS->precision(5); # Global for all members of CLASS
312 # This also applies to new()!
313 CLASS->precision(-5); # ditto
314 $P = CLASS->precision(); # read out global precision
316 $P = $x->precision(); # read out precision that affects $x
317 Note: You probably want to use "accuracy()" instead. With
319 "accuracy()" you set the number of digits each result should have,
320 with "precision()" you set the place where to round!
321 Constructor methods
323 from_hex()
324 $x -> from_hex("0x1.921fb54442d18p+1");
325 $x = Math::BigFloat -> from_hex("0x1.921fb54442d18p+1");
326 Interpret input as a hexadecimal string.A prefix ("0x", "x",
328 ignoring case) is optional. A single underscore character ("_") may
329 be placed between any two digits. If the input is invalid, a NaN is
330 returned. The exponent is in base 2 using decimal digits.
331 If called as an instance method, the value is assigned to the
333 invocand.
334 from_oct()
336 $x -> from_oct("1.3267p-4");
337 $x = Math::BigFloat -> from_oct("1.3267p-4");
338 Interpret input as an octal string. A single underscore character
340 ("_") may be placed between any two digits. If the input is
341 invalid, a NaN is returned. The exponent is in base 2 using decimal
342 digits.
343 If called as an instance method, the value is assigned to the
345 invocand.
346 from_bin()
348 $x -> from_bin("0b1.1001p-4");
349 $x = Math::BigFloat -> from_bin("0b1.1001p-4");
350 Interpret input as a hexadecimal string. A prefix ("0b" or "b",
352 ignoring case) is optional. A single underscore character ("_") may
353 be placed between any two digits. If the input is invalid, a NaN is
354 returned. The exponent is in base 2 using decimal digits.
355 If called as an instance method, the value is assigned to the
357 invocand.
358 from_ieee754()
360 Interpret the input as a value encoded as described in
361 IEEE754-2008. The input can be given as a byte string, hex string
362 or binary string. The input is assumed to be in big-endian byte-
363 order.
364 # both $dbl and $mbf are 3.141592...
366 $bytes = "\x40\x09\x21\xfb\x54\x44\x2d\x18";
367 $dbl = unpack "d>", $bytes;
368 $mbf = Math::BigFloat -> from_ieee754($bytes, "binary64");
369 bpi()
371 print Math::BigFloat->bpi(100), "\n";
372 Calculate PI to N digits (including the 3 before the dot). The
374 result is rounded according to the current rounding mode, which
375 defaults to "even".
376 This method was added in v1.87 of Math::BigInt (June 2007).
378 Arithmetic methods
380 bmuladd()
381 $x->bmuladd($y,$z);
382 Multiply $x by $y, and then add $z to the result.
384 This method was added in v1.87 of Math::BigInt (June 2007).
386 bdiv()
388 $q = $x->bdiv($y);
389 ($q, $r) = $x->bdiv($y);
390 In scalar context, divides $x by $y and returns the result to the
392 given or default accuracy/precision. In list context, does floored
393 division (F-division), returning an integer $q and a remainder $r
394 so that $x = $q * $y + $r. The remainer (modulo) is equal to what
395 is returned by "$x->bmod($y)".
396 bmod()
398 $x->bmod($y);
399 Returns $x modulo $y. When $x is finite, and $y is finite and non-
401 zero, the result is identical to the remainder after floored
402 division (F-division). If, in addition, both $x and $y are
403 integers, the result is identical to the result from Perl's %
404 operator.
405 bexp()
407 $x->bexp($accuracy); # calculate e ** X
408 Calculates the expression "e ** $x" where "e" is Euler's number.
410 This method was added in v1.82 of Math::BigInt (April 2007).
412 bnok()
414 $x->bnok($y); # x over y (binomial coefficient n over k)
415 Calculates the binomial coefficient n over k, also called the
417 "choose" function. The result is equivalent to:
418 ( n ) n!
420 | - | = -------
421 ( k ) k!(n-k)!
422 This method was added in v1.84 of Math::BigInt (April 2007).
424 bsin()
426 my $x = Math::BigFloat->new(1);
427 print $x->bsin(100), "\n";
428 Calculate the sinus of $x, modifying $x in place.
430 This method was added in v1.87 of Math::BigInt (June 2007).
432 bcos()
434 my $x = Math::BigFloat->new(1);
435 print $x->bcos(100), "\n";
436 Calculate the cosinus of $x, modifying $x in place.
438 This method was added in v1.87 of Math::BigInt (June 2007).
440 batan()
442 my $x = Math::BigFloat->new(1);
443 print $x->batan(100), "\n";
444 Calculate the arcus tanges of $x, modifying $x in place. See also
446 "batan2()".
447 This method was added in v1.87 of Math::BigInt (June 2007).
449 batan2()
451 my $y = Math::BigFloat->new(2);
452 my $x = Math::BigFloat->new(3);
453 print $y->batan2($x), "\n";
454 Calculate the arcus tanges of $y divided by $x, modifying $y in
456 place. See also "batan()".
457 This method was added in v1.87 of Math::BigInt (June 2007).
459 as_float()
461 This method is called when Math::BigFloat encounters an object it
462 doesn't know how to handle. For instance, assume $x is a
463 Math::BigFloat, or subclass thereof, and $y is defined, but not a
464 Math::BigFloat, or subclass thereof. If you do
465 $x -> badd($y);
467 $y needs to be converted into an object that $x can deal with. This
469 is done by first checking if $y is something that $x might be
470 upgraded to. If that is the case, no further attempts are made. The
471 next is to see if $y supports the method as_float(). The method
472 as_float() is expected to return either an object that has the same
473 class as $x, a subclass thereof, or a string that "ref($x)->new()"
474 can parse to create an object.
475 In Math::BigFloat, as_float() has the same effect as copy().
477 to_ieee754()
479 Encodes the invocand as a byte string in the given format as
480 specified in IEEE 754-2008. Note that the encoded value is the
481 nearest possible representation of the value. This value might not
482 be exactly the same as the value in the invocand.
483 # $x = 3.1415926535897932385
485 $x = Math::BigFloat -> bpi(30);
486 $b = $x -> to_ieee754("binary64"); # encode as 8 bytes
488 $h = unpack "H*", $b; # "400921fb54442d18"
489 # 3.141592653589793115997963...
491 $y = Math::BigFloat -> from_ieee754($h, "binary64");
492 All binary formats in IEEE 754-2008 are accepted. For convenience,
494 som aliases are recognized: "half" for "binary16", "single" for
495 "binary32", "double" for "binary64", "quadruple" for "binary128",
496 "octuple" for "binary256", and "sexdecuple" for "binary512".
497 See also <https://en.wikipedia.org/wiki/IEEE_754>.
499 ACCURACY AND PRECISION
501 See also: Rounding.
502 Math::BigFloat supports both precision (rounding to a certain place
504 before or after the dot) and accuracy (rounding to a certain number of
505 digits). For a full documentation, examples and tips on these topics
506 please see the large section about rounding in Math::BigInt.
507 Since things like sqrt(2) or "1 / 3" must presented with a limited
509 accuracy lest a operation consumes all resources, each operation
510 produces no more than the requested number of digits.
511 If there is no global precision or accuracy set, and the operation in
513 question was not called with a requested precision or accuracy, and the
514 input $x has no accuracy or precision set, then a fallback parameter
515 will be used. For historical reasons, it is called "div_scale" and can
516 be accessed via:
517 $d = Math::BigFloat->div_scale(); # query
519 Math::BigFloat->div_scale($n); # set to $n digits
520 The default value for "div_scale" is 40.
522 In case the result of one operation has more digits than specified, it
524 is rounded. The rounding mode taken is either the default mode, or the
525 one supplied to the operation after the scale:
526 $x = Math::BigFloat->new(2);
528 Math::BigFloat->accuracy(5); # 5 digits max
529 $y = $x->copy()->bdiv(3); # gives 0.66667
530 $y = $x->copy()->bdiv(3,6); # gives 0.666667
531 $y = $x->copy()->bdiv(3,6,undef,'odd'); # gives 0.666667
532 Math::BigFloat->round_mode('zero');
533 $y = $x->copy()->bdiv(3,6); # will also give 0.666667
534 Note that "Math::BigFloat->accuracy()" and
536 "Math::BigFloat->precision()" set the global variables, and thus any
537 newly created number will be subject to the global rounding
538 immediately. This means that in the examples above, the 3 as argument
539 to bdiv() will also get an accuracy of 5.
540 It is less confusing to either calculate the result fully, and
542 afterwards round it explicitly, or use the additional parameters to the
543 math functions like so:
544 use Math::BigFloat;
546 $x = Math::BigFloat->new(2);
547 $y = $x->copy()->bdiv(3);
548 print $y->bround(5),"\n"; # gives 0.66667
549 or
551 use Math::BigFloat;
553 $x = Math::BigFloat->new(2);
554 $y = $x->copy()->bdiv(3,5); # gives 0.66667
555 print "$y\n";
556 Rounding
558 bfround ( +$scale )
559 Rounds to the $scale'th place left from the '.', counting from the
560 dot. The first digit is numbered 1.
561 bfround ( -$scale )
563 Rounds to the $scale'th place right from the '.', counting from the
564 dot.
565 bfround ( 0 )
567 Rounds to an integer.
568 bround ( +$scale )
570 Preserves accuracy to $scale digits from the left (aka significant
571 digits) and pads the rest with zeros. If the number is between 1
572 and -1, the significant digits count from the first non-zero after
573 the '.'
574 bround ( -$scale ) and bround ( 0 )
576 These are effectively no-ops.
577 All rounding functions take as a second parameter a rounding mode from
579 one of the following: 'even', 'odd', '+inf', '-inf', 'zero', 'trunc' or
580 'common'.
581 The default rounding mode is 'even'. By using
583 "Math::BigFloat->round_mode($round_mode);" you can get and set the
584 default mode for subsequent rounding. The usage of
585 "$Math::BigFloat::$round_mode" is no longer supported. The second
586 parameter to the round functions then overrides the default
587 temporarily.
588 The as_number() function returns a BigInt from a Math::BigFloat. It
590 uses 'trunc' as rounding mode to make it equivalent to:
591 $x = 2.5;
593 $y = int($x) + 2;
594 You can override this by passing the desired rounding mode as parameter
596 to as_number():
597 $x = Math::BigFloat->new(2.5);
599 $y = $x->as_number('odd'); # $y = 3
600
602 After "use Math::BigFloat ':constant'" all numeric literals in the
603 given scope are converted to "Math::BigFloat" objects. This conversion
604 happens at compile time.
605 For example,
607 perl -MMath::BigFloat=:constant -le 'print 2e-150'
609 prints the exact value of 2e-150. Note that without conversion of
611 constants the expression 2e-150 is calculated using Perl scalars, which
612 leads to an inaccuracte result.
613 Note that strings are not affected, so that
615 use Math::BigFloat qw/:constant/;
617 $y = "1234567890123456789012345678901234567890"
619 + "123456789123456789";
620 does not give you what you expect. You need an explicit
622 Math::BigFloat->new() around at least one of the operands. You should
623 also quote large constants to prevent loss of precision:
624 use Math::BigFloat;
626 $x = Math::BigFloat->new("1234567889123456789123456789123456789");
628 Without the quotes Perl converts the large number to a floating point
630 constant at compile time, and then converts the result to a
631 Math::BigFloat object at runtime, which results in an inaccurate
632 result.
633 Hexadecimal, octal, and binary floating point literals
635 Perl (and this module) accepts hexadecimal, octal, and binary floating
636 point literals, but use them with care with Perl versions before
637 v5.32.0, because some versions of Perl silently give the wrong result.
638 Below are some examples of different ways to write the number decimal
639 314.
640 Hexadecimal floating point literals:
642 0x1.3ap+8 0X1.3AP+8
644 0x1.3ap8 0X1.3AP8
645 0x13a0p-4 0X13A0P-4
646 Octal floating point literals (with "0" prefix):
648 01.164p+8 01.164P+8
650 01.164p8 01.164P8
651 011640p-4 011640P-4
652 Octal floating point literals (with "0o" prefix) (requires v5.34.0):
654 0o1.164p+8 0O1.164P+8
656 0o1.164p8 0O1.164P8
657 0o11640p-4 0O11640P-4
658 Binary floating point literals:
660 0b1.0011101p+8 0B1.0011101P+8
662 0b1.0011101p8 0B1.0011101P8
663 0b10011101000p-2 0B10011101000P-2
664 Math library
666 Math with the numbers is done (by default) by a module called
667 Math::BigInt::Calc. This is equivalent to saying:
668 use Math::BigFloat lib => "Calc";
670 You can change this by using:
672 use Math::BigFloat lib => "GMP";
674 Note: General purpose packages should not be explicit about the library
676 to use; let the script author decide which is best.
677 Note: The keyword 'lib' will warn when the requested library could not
679 be loaded. To suppress the warning use 'try' instead:
680 use Math::BigFloat try => "GMP";
682 If your script works with huge numbers and Calc is too slow for them,
684 you can also for the loading of one of these libraries and if none of
685 them can be used, the code will die:
686 use Math::BigFloat only => "GMP,Pari";
688 The following would first try to find Math::BigInt::Foo, then
690 Math::BigInt::Bar, and when this also fails, revert to
691 Math::BigInt::Calc:
692 use Math::BigFloat lib => "Foo,Math::BigInt::Bar";
694 See the respective low-level library documentation for further details.
696 See Math::BigInt for more details about using a different low-level
698 library.
699 Using Math::BigInt::Lite
701 For backwards compatibility reasons it is still possible to request a
702 different storage class for use with Math::BigFloat:
703 use Math::BigFloat with => 'Math::BigInt::Lite';
705 However, this request is ignored, as the current code now uses the low-
707 level math library for directly storing the number parts.
708
710 "Math::BigFloat" exports nothing by default, but can export the bpi()
711 method:
712 use Math::BigFloat qw/bpi/;
714 print bpi(10), "\n";
716
718 Do not try to be clever to insert some operations in between switching
719 libraries:
720 require Math::BigFloat;
722 my $matter = Math::BigFloat->bone() + 4; # load BigInt and Calc
723 Math::BigFloat->import( lib => 'Pari' ); # load Pari, too
724 my $anti_matter = Math::BigFloat->bone()+4; # now use Pari
725 This will create objects with numbers stored in two different backend
727 libraries, and VERY BAD THINGS will happen when you use these together:
728 my $flash_and_bang = $matter + $anti_matter; # Don't do this!
730 stringify, bstr()
732 Both stringify and bstr() now drop the leading '+'. The old code
733 would return '+1.23', the new returns '1.23'. See the documentation
734 in Math::BigInt for reasoning and details.
735 brsft()
737 The following will probably not print what you expect:
738 my $c = Math::BigFloat->new('3.14159');
740 print $c->brsft(3,10),"\n"; # prints 0.00314153.1415
741 It prints both quotient and remainder, since print calls brsft() in
743 list context. Also, "$c->brsft()" will modify $c, so be careful.
744 You probably want to use
745 print scalar $c->copy()->brsft(3,10),"\n";
747 # or if you really want to modify $c
748 print scalar $c->brsft(3,10),"\n";
749 instead.
751 Modifying and =
753 Beware of:
754 $x = Math::BigFloat->new(5);
756 $y = $x;
757 It will not do what you think, e.g. making a copy of $x. Instead it
759 just makes a second reference to the same object and stores it in
760 $y. Thus anything that modifies $x will modify $y (except
761 overloaded math operators), and vice versa. See Math::BigInt for
762 details and how to avoid that.
763 precision() vs. accuracy()
765 A common pitfall is to use "precision()" when you want to round a
766 result to a certain number of digits:
767 use Math::BigFloat;
769 Math::BigFloat->precision(4); # does not do what you
771 # think it does
772 my $x = Math::BigFloat->new(12345); # rounds $x to "12000"!
773 print "$x\n"; # print "12000"
774 my $y = Math::BigFloat->new(3); # rounds $y to "0"!
775 print "$y\n"; # print "0"
776 $z = $x / $y; # 12000 / 0 => NaN!
777 print "$z\n";
778 print $z->precision(),"\n"; # 4
779 Replacing "precision()" with "accuracy()" is probably not what you
781 want, either:
782 use Math::BigFloat;
784 Math::BigFloat->accuracy(4); # enables global rounding:
786 my $x = Math::BigFloat->new(123456); # rounded immediately
787 # to "12350"
788 print "$x\n"; # print "123500"
789 my $y = Math::BigFloat->new(3); # rounded to "3
790 print "$y\n"; # print "3"
791 print $z = $x->copy()->bdiv($y),"\n"; # 41170
792 print $z->accuracy(),"\n"; # 4
793 What you want to use instead is:
795 use Math::BigFloat;
797 my $x = Math::BigFloat->new(123456); # no rounding
799 print "$x\n"; # print "123456"
800 my $y = Math::BigFloat->new(3); # no rounding
801 print "$y\n"; # print "3"
802 print $z = $x->copy()->bdiv($y,4),"\n"; # 41150
803 print $z->accuracy(),"\n"; # undef
804 In addition to computing what you expected, the last example also
806 does not "taint" the result with an accuracy or precision setting,
807 which would influence any further operation.
808
810 Please report any bugs or feature requests to "bug-math-bigint at
811 rt.cpan.org", or through the web interface at
812 <https://rt.cpan.org/Ticket/Create.html?Queue=Math-BigInt> (requires
813 login). We will be notified, and then you'll automatically be notified
814 of progress on your bug as I make changes.
815
817 You can find documentation for this module with the perldoc command.
818 perldoc Math::BigFloat
820 You can also look for information at:
822 • GitHub
824 <https://github.com/pjacklam/p5-Math-BigInt>
826 • RT: CPAN's request tracker
828 <https://rt.cpan.org/Dist/Display.html?Name=Math-BigInt>
830 • MetaCPAN
832 <https://metacpan.org/release/Math-BigInt>
834 • CPAN Testers Matrix
836 <http://matrix.cpantesters.org/?dist=Math-BigInt>
838
840 This program is free software; you may redistribute it and/or modify it
841 under the same terms as Perl itself.
842
844 Math::BigInt and Math::BigInt as well as the backends
845 Math::BigInt::FastCalc, Math::BigInt::GMP, and Math::BigInt::Pari.
846 The pragmas bignum, bigint and bigrat.
848
850 • Mark Biggar, overloaded interface by Ilya Zakharevich, 1996-2001.
851 • Completely rewritten by Tels <http://bloodgate.com> in 2001-2008.
853 • Florian Ragwitz <flora@cpan.org>, 2010.
855 • Peter John Acklam <pjacklam@gmail.com>, 2011-.
857perl v5.36.1 2023-07-17 Math::BigFloat(3)