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 # Conversion methods (do not modify the invocand)
161 $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 # Other conversion methods
173 $x->numify(); # return as scalar (might overflow or underflow)
175
177 Math::BigFloat provides support for arbitrary precision floating point.
178 Overloading is also provided for Perl operators.
179 All operators (including basic math operations) are overloaded if you
181 declare your big floating point numbers as
182 $x = Math::BigFloat -> new('12_3.456_789_123_456_789E-2');
184 Operations with overloaded operators preserve the arguments, which is
186 exactly what you expect.
187 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 • Leading and trailing whitespace is ignored.
193 • 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 • If the string has a "0x" prefix, it is interpreted as a hexadecimal
201 number.
202 • If the string has a "0o" prefix, it is interpreted as an octal
204 number.
205 • If the string has a "0b" prefix, it is interpreted as a binary
207 number.
208 • One underline is allowed between any two digits.
210 • If the string can not be interpreted, NaN is returned.
212 • 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 Some examples of valid string input
218 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 Output
237 Output values are usually Math::BigFloat objects.
238 Boolean operators "is_zero()", "is_one()", "is_inf()", etc. return true
240 or false.
241 Comparison operators "bcmp()" and "bacmp()") return -1, 0, 1, or undef.
243
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 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 $A = $x->accuracy(); # read out accuracy that affects $x
257 $A = CLASS->accuracy(); # read out global accuracy
258 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 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 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 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 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 CLASS->precision(5); # Global for all members of CLASS
284 # This also applies to new()!
285 CLASS->precision(-5); # ditto
286 $P = CLASS->precision(); # read out global precision
288 $P = $x->precision(); # read out precision that affects $x
289 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 Constructor methods
295 from_hex()
296 $x -> from_hex("0x1.921fb54442d18p+1");
297 $x = Math::BigFloat -> from_hex("0x1.921fb54442d18p+1");
298 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 If called as an instance method, the value is assigned to the
305 invocand.
306 from_oct()
308 $x -> from_oct("1.3267p-4");
309 $x = Math::BigFloat -> from_oct("1.3267p-4");
310 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 If called as an instance method, the value is assigned to the
317 invocand.
318 from_bin()
320 $x -> from_bin("0b1.1001p-4");
321 $x = Math::BigFloat -> from_bin("0b1.1001p-4");
322 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 If called as an instance method, the value is assigned to the
329 invocand.
330 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 # 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 bpi()
343 print Math::BigFloat->bpi(100), "\n";
344 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 This method was added in v1.87 of Math::BigInt (June 2007).
350 Arithmetic methods
352 bmuladd()
353 $x->bmuladd($y,$z);
354 Multiply $x by $y, and then add $z to the result.
356 This method was added in v1.87 of Math::BigInt (June 2007).
358 bdiv()
360 $q = $x->bdiv($y);
361 ($q, $r) = $x->bdiv($y);
362 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 bmod()
370 $x->bmod($y);
371 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 bexp()
379 $x->bexp($accuracy); # calculate e ** X
380 Calculates the expression "e ** $x" where "e" is Euler's number.
382 This method was added in v1.82 of Math::BigInt (April 2007).
384 bnok()
386 $x->bnok($y); # x over y (binomial coefficient n over k)
387 Calculates the binomial coefficient n over k, also called the
389 "choose" function. The result is equivalent to:
390 ( n ) n!
392 | - | = -------
393 ( k ) k!(n-k)!
394 This method was added in v1.84 of Math::BigInt (April 2007).
396 bsin()
398 my $x = Math::BigFloat->new(1);
399 print $x->bsin(100), "\n";
400 Calculate the sinus of $x, modifying $x in place.
402 This method was added in v1.87 of Math::BigInt (June 2007).
404 bcos()
406 my $x = Math::BigFloat->new(1);
407 print $x->bcos(100), "\n";
408 Calculate the cosinus of $x, modifying $x in place.
410 This method was added in v1.87 of Math::BigInt (June 2007).
412 batan()
414 my $x = Math::BigFloat->new(1);
415 print $x->batan(100), "\n";
416 Calculate the arcus tanges of $x, modifying $x in place. See also
418 "batan2()".
419 This method was added in v1.87 of Math::BigInt (June 2007).
421 batan2()
423 my $y = Math::BigFloat->new(2);
424 my $x = Math::BigFloat->new(3);
425 print $y->batan2($x), "\n";
426 Calculate the arcus tanges of $y divided by $x, modifying $y in
428 place. See also "batan()".
429 This method was added in v1.87 of Math::BigInt (June 2007).
431 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 $x -> badd($y);
439 $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 In Math::BigFloat, "as_float()" has the same effect as "copy()".
449 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 # $x = 3.1415926535897932385
457 $x = Math::BigFloat -> bpi(30);
458 $b = $x -> to_ieee754("binary64"); # encode as 8 bytes
460 $h = unpack "H*", $b; # "400921fb54442d18"
461 # 3.141592653589793115997963...
463 $y = Math::BigFloat -> from_ieee754($h, "binary64");
464 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 See also <https://en.wikipedia.org/wiki/IEEE_754>.
471 ACCURACY AND PRECISION
473 See also: Rounding.
474 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 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 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 $d = Math::BigFloat->div_scale(); # query
491 Math::BigFloat->div_scale($n); # set to $n digits
492 The default value for "div_scale" is 40.
494 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 $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 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 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 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 or
523 use Math::BigFloat;
525 $x = Math::BigFloat->new(2);
526 $y = $x->copy()->bdiv(3,5); # gives 0.66667
527 print "$y\n";
528 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 bfround ( -$scale )
535 Rounds to the $scale'th place right from the '.', counting from the
536 dot.
537 bfround ( 0 )
539 Rounds to an integer.
540 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 bround ( -$scale ) and bround ( 0 )
548 These are effectively no-ops.
549 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 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 The "as_number()" function returns a BigInt from a Math::BigFloat. It
562 uses 'trunc' as rounding mode to make it equivalent to:
563 $x = 2.5;
565 $y = int($x) + 2;
566 You can override this by passing the desired rounding mode as parameter
568 to "as_number()":
569 $x = Math::BigFloat->new(2.5);
571 $y = $x->as_number('odd'); # $y = 3
572
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 In particular
579 perl -MMath::BigFloat=:constant -e 'print 2E-100,"\n"'
581 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 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 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 use Math::BigFloat lib => "Calc";
595 You can change this by using:
597 use Math::BigFloat lib => "GMP";
599 Note: General purpose packages should not be explicit about the library
601 to use; let the script author decide which is best.
602 Note: The keyword 'lib' will warn when the requested library could not
604 be loaded. To suppress the warning use 'try' instead:
605 use Math::BigFloat try => "GMP";
607 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 use Math::BigFloat only => "GMP,Pari";
613 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 use Math::BigFloat lib => "Foo,Math::BigInt::Bar";
619 See the respective low-level library documentation for further details.
621 See Math::BigInt for more details about using a different low-level
623 library.
624 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 use Math::BigFloat with => 'Math::BigInt::Lite';
630 However, this request is ignored, as the current code now uses the low-
632 level math library for directly storing the number parts.
633
635 "Math::BigFloat" exports nothing by default, but can export the "bpi()"
636 method:
637 use Math::BigFloat qw/bpi/;
639 print bpi(10), "\n";
641
643 Do not try to be clever to insert some operations in between switching
644 libraries:
645 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 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 my $flash_and_bang = $matter + $anti_matter; # Don't do this!
655 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 brsft()
662 The following will probably not print what you expect:
663 my $c = Math::BigFloat->new('3.14159');
665 print $c->brsft(3,10),"\n"; # prints 0.00314153.1415
666 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 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 instead.
676 Modifying and =
678 Beware of:
679 $x = Math::BigFloat->new(5);
681 $y = $x;
682 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 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 use Math::BigFloat;
694 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 Replacing "precision()" with "accuracy()" is probably not what you
706 want, either:
707 use Math::BigFloat;
709 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 What you want to use instead is:
720 use Math::BigFloat;
722 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 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
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
742 You can find documentation for this module with the perldoc command.
743 perldoc Math::BigFloat
745 You can also look for information at:
747 • GitHub
749 <https://github.com/pjacklam/p5-Math-BigInt>
751 • RT: CPAN's request tracker
753 <https://rt.cpan.org/Dist/Display.html?Name=Math-BigInt>
755 • MetaCPAN
757 <https://metacpan.org/release/Math-BigInt>
759 • CPAN Testers Matrix
761 <http://matrix.cpantesters.org/?dist=Math-BigInt>
763 • CPAN Ratings
765 <https://cpanratings.perl.org/dist/Math-BigInt>
767 • The Bignum mailing list
769 • Post to mailing list
771 "bignum at lists.scsys.co.uk"
773 • View mailing list
775 <http://lists.scsys.co.uk/pipermail/bignum/>
777 • Subscribe/Unsubscribe
779 <http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/bignum>
781
783 This program is free software; you may redistribute it and/or modify it
784 under the same terms as Perl itself.
785
787 Math::BigInt and Math::BigInt as well as the backends
788 Math::BigInt::FastCalc, Math::BigInt::GMP, and Math::BigInt::Pari.
789 The pragmas bignum, bigint and bigrat also might be of interest because
791 they solve the autoupgrading/downgrading issue, at least partly.
792
794 • Mark Biggar, overloaded interface by Ilya Zakharevich, 1996-2001.
795 • Completely rewritten by Tels <http://bloodgate.com> in 2001-2008.
797 • Florian Ragwitz <flora@cpan.org>, 2010.
799 • Peter John Acklam <pjacklam@gmail.com>, 2011-.
801perl v5.34.0 2021-09-22 Math::BigFloat(3)