1Math::BigInt(3) User Contributed Perl Documentation Math::BigInt(3)
2
6 Math::BigInt - Arbitrary size integer/float math package
7
9 use Math::BigInt;
10 # or make it faster with huge numbers: install (optional)
12 # Math::BigInt::GMP and always use (it falls back to
13 # pure Perl if the GMP library is not installed):
14 # (See also the L<MATH LIBRARY> section!)
15 # warns if Math::BigInt::GMP cannot be found
17 use Math::BigInt lib => 'GMP';
18 # to suppress the warning use this:
20 # use Math::BigInt try => 'GMP';
21 # dies if GMP cannot be loaded:
23 # use Math::BigInt only => 'GMP';
24 my $str = '1234567890';
26 my @values = (64, 74, 18);
27 my $n = 1; my $sign = '-';
28 # Configuration methods (may be used as class methods and instance methods)
30 Math::BigInt->accuracy(); # get class accuracy
32 Math::BigInt->accuracy($n); # set class accuracy
33 Math::BigInt->precision(); # get class precision
34 Math::BigInt->precision($n); # set class precision
35 Math::BigInt->round_mode(); # get class rounding mode
36 Math::BigInt->round_mode($m); # set global round mode, must be one of
37 # 'even', 'odd', '+inf', '-inf', 'zero',
38 # 'trunc', or 'common'
39 Math::BigInt->config(); # return hash with configuration
40 # Constructor methods (when the class methods below are used as instance
42 # methods, the value is assigned the invocand)
43 $x = Math::BigInt->new($str); # defaults to 0
45 $x = Math::BigInt->new('0x123'); # from hexadecimal
46 $x = Math::BigInt->new('0b101'); # from binary
47 $x = Math::BigInt->from_hex('cafe'); # from hexadecimal
48 $x = Math::BigInt->from_oct('377'); # from octal
49 $x = Math::BigInt->from_bin('1101'); # from binary
50 $x = Math::BigInt->from_base('why', 36); # from any base
51 $x = Math::BigInt->bzero(); # create a +0
52 $x = Math::BigInt->bone(); # create a +1
53 $x = Math::BigInt->bone('-'); # create a -1
54 $x = Math::BigInt->binf(); # create a +inf
55 $x = Math::BigInt->binf('-'); # create a -inf
56 $x = Math::BigInt->bnan(); # create a Not-A-Number
57 $x = Math::BigInt->bpi(); # returns pi
58 $y = $x->copy(); # make a copy (unlike $y = $x)
60 $y = $x->as_int(); # return as a Math::BigInt
61 # Boolean methods (these don't modify the invocand)
63 $x->is_zero(); # if $x is 0
65 $x->is_one(); # if $x is +1
66 $x->is_one("+"); # ditto
67 $x->is_one("-"); # if $x is -1
68 $x->is_inf(); # if $x is +inf or -inf
69 $x->is_inf("+"); # if $x is +inf
70 $x->is_inf("-"); # if $x is -inf
71 $x->is_nan(); # if $x is NaN
72 $x->is_positive(); # if $x > 0
74 $x->is_pos(); # ditto
75 $x->is_negative(); # if $x < 0
76 $x->is_neg(); # ditto
77 $x->is_odd(); # if $x is odd
79 $x->is_even(); # if $x is even
80 $x->is_int(); # if $x is an integer
81 # Comparison methods
83 $x->bcmp($y); # compare numbers (undef, < 0, == 0, > 0)
85 $x->bacmp($y); # compare absolutely (undef, < 0, == 0, > 0)
86 $x->beq($y); # true if and only if $x == $y
87 $x->bne($y); # true if and only if $x != $y
88 $x->blt($y); # true if and only if $x < $y
89 $x->ble($y); # true if and only if $x <= $y
90 $x->bgt($y); # true if and only if $x > $y
91 $x->bge($y); # true if and only if $x >= $y
92 # Arithmetic methods
94 $x->bneg(); # negation
96 $x->babs(); # absolute value
97 $x->bsgn(); # sign function (-1, 0, 1, or NaN)
98 $x->bnorm(); # normalize (no-op)
99 $x->binc(); # increment $x by 1
100 $x->bdec(); # decrement $x by 1
101 $x->badd($y); # addition (add $y to $x)
102 $x->bsub($y); # subtraction (subtract $y from $x)
103 $x->bmul($y); # multiplication (multiply $x by $y)
104 $x->bmuladd($y,$z); # $x = $x * $y + $z
105 $x->bdiv($y); # division (floored), set $x to quotient
106 # return (quo,rem) or quo if scalar
107 $x->btdiv($y); # division (truncated), set $x to quotient
108 # return (quo,rem) or quo if scalar
109 $x->bmod($y); # modulus (x % y)
110 $x->btmod($y); # modulus (truncated)
111 $x->bmodinv($mod); # modular multiplicative inverse
112 $x->bmodpow($y,$mod); # modular exponentiation (($x ** $y) % $mod)
113 $x->bpow($y); # power of arguments (x ** y)
114 $x->blog(); # logarithm of $x to base e (Euler's number)
115 $x->blog($base); # logarithm of $x to base $base (e.g., base 2)
116 $x->bexp(); # calculate e ** $x where e is Euler's number
117 $x->bnok($y); # x over y (binomial coefficient n over k)
118 $x->buparrow($n, $y); # Knuth's up-arrow notation
119 $x->backermann($y); # the Ackermann function
120 $x->bsin(); # sine
121 $x->bcos(); # cosine
122 $x->batan(); # inverse tangent
123 $x->batan2($y); # two-argument inverse tangent
124 $x->bsqrt(); # calculate square root
125 $x->broot($y); # $y'th root of $x (e.g. $y == 3 => cubic root)
126 $x->bfac(); # factorial of $x (1*2*3*4*..$x)
127 $x->blsft($n); # left shift $n places in base 2
129 $x->blsft($n,$b); # left shift $n places in base $b
130 # returns (quo,rem) or quo (scalar context)
131 $x->brsft($n); # right shift $n places in base 2
132 $x->brsft($n,$b); # right shift $n places in base $b
133 # returns (quo,rem) or quo (scalar context)
134 # Bitwise methods
136 $x->band($y); # bitwise and
138 $x->bior($y); # bitwise inclusive or
139 $x->bxor($y); # bitwise exclusive or
140 $x->bnot(); # bitwise not (two's complement)
141 # Rounding methods
143 $x->round($A,$P,$mode); # round to accuracy or precision using
144 # rounding mode $mode
145 $x->bround($n); # accuracy: preserve $n digits
146 $x->bfround($n); # $n > 0: round to $nth digit left of dec. point
147 # $n < 0: round to $nth digit right of dec. point
148 $x->bfloor(); # round towards minus infinity
149 $x->bceil(); # round towards plus infinity
150 $x->bint(); # round towards zero
151 # Other mathematical methods
153 $x->bgcd($y); # greatest common divisor
155 $x->blcm($y); # least common multiple
156 # Object property methods (do not modify the invocand)
158 $x->sign(); # the sign, either +, - or NaN
160 $x->digit($n); # the nth digit, counting from the right
161 $x->digit(-$n); # the nth digit, counting from the left
162 $x->length(); # return number of digits in number
163 ($xl,$f) = $x->length(); # length of number and length of fraction
164 # part, latter is always 0 digits long
165 # for Math::BigInt objects
166 $x->mantissa(); # return (signed) mantissa as a Math::BigInt
167 $x->exponent(); # return exponent as a Math::BigInt
168 $x->parts(); # return (mantissa,exponent) as a Math::BigInt
169 $x->sparts(); # mantissa and exponent (as integers)
170 $x->nparts(); # mantissa and exponent (normalised)
171 $x->eparts(); # mantissa and exponent (engineering notation)
172 $x->dparts(); # integer and fraction part
173 # Conversion methods (do not modify the invocand)
175 $x->bstr(); # decimal notation, possibly zero padded
177 $x->bsstr(); # string in scientific notation with integers
178 $x->bnstr(); # string in normalized notation
179 $x->bestr(); # string in engineering notation
180 $x->bdstr(); # string in decimal notation
181 $x->to_hex(); # as signed hexadecimal string
183 $x->to_bin(); # as signed binary string
184 $x->to_oct(); # as signed octal string
185 $x->to_bytes(); # as byte string
186 $x->to_base($b); # as string in any base
187 $x->as_hex(); # as signed hexadecimal string with prefixed 0x
189 $x->as_bin(); # as signed binary string with prefixed 0b
190 $x->as_oct(); # as signed octal string with prefixed 0
191 # Other conversion methods
193 $x->numify(); # return as scalar (might overflow or underflow)
195
197 Math::BigInt provides support for arbitrary precision integers.
198 Overloading is also provided for Perl operators.
199 Input
201 Input values to these routines may be any scalar number or string that
202 looks like a number and represents an integer.
203 · Leading and trailing whitespace is ignored.
205 · Leading and trailing zeros are ignored.
207 · If the string has a "0x" prefix, it is interpreted as a hexadecimal
209 number.
210 · If the string has a "0b" prefix, it is interpreted as a binary
212 number.
213 · One underline is allowed between any two digits.
215 · If the string can not be interpreted, NaN is returned.
217 Octal numbers are typically prefixed by "0", but since leading zeros
219 are stripped, these methods can not automatically recognize octal
220 numbers, so use the constructor from_oct() to interpret octal strings.
221 Some examples of valid string input
223 Input string Resulting value
225 123 123
226 1.23e2 123
227 12300e-2 123
228 0xcafe 51966
229 0b1101 13
230 67_538_754 67538754
231 -4_5_6.7_8_9e+0_1_0 -4567890000000
232 Input given as scalar numbers might lose precision. Quote your input to
234 ensure that no digits are lost:
235 $x = Math::BigInt->new( 56789012345678901234 ); # bad
237 $x = Math::BigInt->new('56789012345678901234'); # good
238 Currently, Math::BigInt->new() defaults to 0, while
240 Math::BigInt->new('') results in 'NaN'. This might change in the
241 future, so use always the following explicit forms to get a zero or
242 NaN:
243 $zero = Math::BigInt->bzero();
245 $nan = Math::BigInt->bnan();
246 Output
248 Output values are usually Math::BigInt objects.
249 Boolean operators "is_zero()", "is_one()", "is_inf()", etc. return true
251 or false.
252 Comparison operators "bcmp()" and "bacmp()") return -1, 0, 1, or undef.
254
256 Configuration methods
257 Each of the methods below (except config(), accuracy() and precision())
258 accepts three additional parameters. These arguments $A, $P and $R are
259 "accuracy", "precision" and "round_mode". Please see the section about
260 "ACCURACY and PRECISION" for more information.
261 Setting a class variable effects all object instance that are created
263 afterwards.
264 accuracy()
266 Math::BigInt->accuracy(5); # set class accuracy
267 $x->accuracy(5); # set instance accuracy
268 $A = Math::BigInt->accuracy(); # get class accuracy
270 $A = $x->accuracy(); # get instance accuracy
271 Set or get the accuracy, i.e., the number of significant digits.
273 The accuracy must be an integer. If the accuracy is set to "undef",
274 no rounding is done.
275 Alternatively, one can round the results explicitly using one of
277 "round()", "bround()" or "bfround()" or by passing the desired
278 accuracy to the method as an additional parameter:
279 my $x = Math::BigInt->new(30000);
281 my $y = Math::BigInt->new(7);
282 print scalar $x->copy()->bdiv($y, 2); # prints 4300
283 print scalar $x->copy()->bdiv($y)->bround(2); # prints 4300
284 Please see the section about "ACCURACY and PRECISION" for further
286 details.
287 $y = Math::BigInt->new(1234567); # $y is not rounded
289 Math::BigInt->accuracy(4); # set class accuracy to 4
290 $x = Math::BigInt->new(1234567); # $x is rounded automatically
291 print "$x $y"; # prints "1235000 1234567"
292 print $x->accuracy(); # prints "4"
294 print $y->accuracy(); # also prints "4", since
295 # class accuracy is 4
296 Math::BigInt->accuracy(5); # set class accuracy to 5
298 print $x->accuracy(); # prints "4", since instance
299 # accuracy is 4
300 print $y->accuracy(); # prints "5", since no instance
301 # accuracy, and class accuracy is 5
302 Note: Each class has it's own globals separated from Math::BigInt,
304 but it is possible to subclass Math::BigInt and make the globals of
305 the subclass aliases to the ones from Math::BigInt.
306 precision()
308 Math::BigInt->precision(-2); # set class precision
309 $x->precision(-2); # set instance precision
310 $P = Math::BigInt->precision(); # get class precision
312 $P = $x->precision(); # get instance precision
313 Set or get the precision, i.e., the place to round relative to the
315 decimal point. The precision must be a integer. Setting the
316 precision to $P means that each number is rounded up or down,
317 depending on the rounding mode, to the nearest multiple of 10**$P.
318 If the precision is set to "undef", no rounding is done.
319 You might want to use "accuracy()" instead. With "accuracy()" you
321 set the number of digits each result should have, with
322 "precision()" you set the place where to round.
323 Please see the section about "ACCURACY and PRECISION" for further
325 details.
326 $y = Math::BigInt->new(1234567); # $y is not rounded
328 Math::BigInt->precision(4); # set class precision to 4
329 $x = Math::BigInt->new(1234567); # $x is rounded automatically
330 print $x; # prints "1230000"
331 Note: Each class has its own globals separated from Math::BigInt,
333 but it is possible to subclass Math::BigInt and make the globals of
334 the subclass aliases to the ones from Math::BigInt.
335 div_scale()
337 Set/get the fallback accuracy. This is the accuracy used when
338 neither accuracy nor precision is set explicitly. It is used when a
339 computation might otherwise attempt to return an infinite number of
340 digits.
341 round_mode()
343 Set/get the rounding mode.
344 upgrade()
346 Set/get the class for upgrading. When a computation might result in
347 a non-integer, the operands are upgraded to this class. This is
348 used for instance by bignum. The default is "undef", thus the
349 following operation creates a Math::BigInt, not a Math::BigFloat:
350 my $i = Math::BigInt->new(123);
352 my $f = Math::BigFloat->new('123.1');
353 print $i + $f, "\n"; # prints 246
355 downgrade()
357 Set/get the class for downgrading. The default is "undef".
358 Downgrading is not done by Math::BigInt.
359 modify()
361 $x->modify('bpowd');
362 This method returns 0 if the object can be modified with the given
364 operation, or 1 if not.
365 This is used for instance by Math::BigInt::Constant.
367 config()
369 Math::BigInt->config("trap_nan" => 1); # set
370 $accu = Math::BigInt->config("accuracy"); # get
371 Set or get class variables. Read-only parameters are marked as RO.
373 Read-write parameters are marked as RW. The following parameters
374 are supported.
375 Parameter RO/RW Description
377 Example
378 ============================================================
379 lib RO Name of the math backend library
380 Math::BigInt::Calc
381 lib_version RO Version of the math backend library
382 0.30
383 class RO The class of config you just called
384 Math::BigRat
385 version RO version number of the class you used
386 0.10
387 upgrade RW To which class numbers are upgraded
388 undef
389 downgrade RW To which class numbers are downgraded
390 undef
391 precision RW Global precision
392 undef
393 accuracy RW Global accuracy
394 undef
395 round_mode RW Global round mode
396 even
397 div_scale RW Fallback accuracy for division etc.
398 40
399 trap_nan RW Trap NaNs
400 undef
401 trap_inf RW Trap +inf/-inf
402 undef
403 Constructor methods
405 new()
406 $x = Math::BigInt->new($str,$A,$P,$R);
407 Creates a new Math::BigInt object from a scalar or another
409 Math::BigInt object. The input is accepted as decimal, hexadecimal
410 (with leading '0x') or binary (with leading '0b').
411 See "Input" for more info on accepted input formats.
413 from_hex()
415 $x = Math::BigInt->from_hex("0xcafe"); # input is hexadecimal
416 Interpret input as a hexadecimal string. A "0x" or "x" prefix is
418 optional. A single underscore character may be placed right after
419 the prefix, if present, or between any two digits. If the input is
420 invalid, a NaN is returned.
421 from_oct()
423 $x = Math::BigInt->from_oct("0775"); # input is octal
424 Interpret the input as an octal string and return the corresponding
426 value. A "0" (zero) prefix is optional. A single underscore
427 character may be placed right after the prefix, if present, or
428 between any two digits. If the input is invalid, a NaN is returned.
429 from_bin()
431 $x = Math::BigInt->from_bin("0b10011"); # input is binary
432 Interpret the input as a binary string. A "0b" or "b" prefix is
434 optional. A single underscore character may be placed right after
435 the prefix, if present, or between any two digits. If the input is
436 invalid, a NaN is returned.
437 from_bytes()
439 $x = Math::BigInt->from_bytes("\xf3\x6b"); # $x = 62315
440 Interpret the input as a byte string, assuming big endian byte
442 order. The output is always a non-negative, finite integer.
443 In some special cases, from_bytes() matches the conversion done by
445 unpack():
446 $b = "\x4e"; # one char byte string
448 $x = Math::BigInt->from_bytes($b); # = 78
449 $y = unpack "C", $b; # ditto, but scalar
450 $b = "\xf3\x6b"; # two char byte string
452 $x = Math::BigInt->from_bytes($b); # = 62315
453 $y = unpack "S>", $b; # ditto, but scalar
454 $b = "\x2d\xe0\x49\xad"; # four char byte string
456 $x = Math::BigInt->from_bytes($b); # = 769673645
457 $y = unpack "L>", $b; # ditto, but scalar
458 $b = "\x2d\xe0\x49\xad\x2d\xe0\x49\xad"; # eight char byte string
460 $x = Math::BigInt->from_bytes($b); # = 3305723134637787565
461 $y = unpack "Q>", $b; # ditto, but scalar
462 from_base()
464 Given a string, a base, and an optional collation sequence,
465 interpret the string as a number in the given base. The collation
466 sequence describes the value of each character in the string.
467 If a collation sequence is not given, a default collation sequence
469 is used. If the base is less than or equal to 36, the collation
470 sequence is the string consisting of the 36 characters "0" to "9"
471 and "A" to "Z". In this case, the letter case in the input is
472 ignored. If the base is greater than 36, and smaller than or equal
473 to 62, the collation sequence is the string consisting of the 62
474 characters "0" to "9", "A" to "Z", and "a" to "z". A base larger
475 than 62 requires the collation sequence to be specified explicitly.
476 These examples show standard binary, octal, and hexadecimal
478 conversion. All cases return 250.
479 $x = Math::BigInt->from_base("11111010", 2);
481 $x = Math::BigInt->from_base("372", 8);
482 $x = Math::BigInt->from_base("fa", 16);
483 When the base is less than or equal to 36, and no collation
485 sequence is given, the letter case is ignored, so both of these
486 also return 250:
487 $x = Math::BigInt->from_base("6Y", 16);
489 $x = Math::BigInt->from_base("6y", 16);
490 When the base greater than 36, and no collation sequence is given,
492 the default collation sequence contains both uppercase and
493 lowercase letters, so the letter case in the input is not ignored:
494 $x = Math::BigInt->from_base("6S", 37); # $x is 250
496 $x = Math::BigInt->from_base("6s", 37); # $x is 276
497 $x = Math::BigInt->from_base("121", 3); # $x is 16
498 $x = Math::BigInt->from_base("XYZ", 36); # $x is 44027
499 $x = Math::BigInt->from_base("Why", 42); # $x is 58314
500 The collation sequence can be any set of unique characters. These
502 two cases are equivalent
503 $x = Math::BigInt->from_base("100", 2, "01"); # $x is 4
505 $x = Math::BigInt->from_base("|--", 2, "-|"); # $x is 4
506 bzero()
508 $x = Math::BigInt->bzero();
509 $x->bzero();
510 Returns a new Math::BigInt object representing zero. If used as an
512 instance method, assigns the value to the invocand.
513 bone()
515 $x = Math::BigInt->bone(); # +1
516 $x = Math::BigInt->bone("+"); # +1
517 $x = Math::BigInt->bone("-"); # -1
518 $x->bone(); # +1
519 $x->bone("+"); # +1
520 $x->bone('-'); # -1
521 Creates a new Math::BigInt object representing one. The optional
523 argument is either '-' or '+', indicating whether you want plus one
524 or minus one. If used as an instance method, assigns the value to
525 the invocand.
526 binf()
528 $x = Math::BigInt->binf($sign);
529 Creates a new Math::BigInt object representing infinity. The
531 optional argument is either '-' or '+', indicating whether you want
532 infinity or minus infinity. If used as an instance method, assigns
533 the value to the invocand.
534 $x->binf();
536 $x->binf('-');
537 bnan()
539 $x = Math::BigInt->bnan();
540 Creates a new Math::BigInt object representing NaN (Not A Number).
542 If used as an instance method, assigns the value to the invocand.
543 $x->bnan();
545 bpi()
547 $x = Math::BigInt->bpi(100); # 3
548 $x->bpi(100); # 3
549 Creates a new Math::BigInt object representing PI. If used as an
551 instance method, assigns the value to the invocand. With
552 Math::BigInt this always returns 3.
553 If upgrading is in effect, returns PI, rounded to N digits with the
555 current rounding mode:
556 use Math::BigFloat;
558 use Math::BigInt upgrade => "Math::BigFloat";
559 print Math::BigInt->bpi(3), "\n"; # 3.14
560 print Math::BigInt->bpi(100), "\n"; # 3.1415....
561 copy()
563 $x->copy(); # make a true copy of $x (unlike $y = $x)
564 as_int()
566 as_number()
567 These methods are called when Math::BigInt encounters an object it
568 doesn't know how to handle. For instance, assume $x is a
569 Math::BigInt, or subclass thereof, and $y is defined, but not a
570 Math::BigInt, or subclass thereof. If you do
571 $x -> badd($y);
573 $y needs to be converted into an object that $x can deal with. This
575 is done by first checking if $y is something that $x might be
576 upgraded to. If that is the case, no further attempts are made. The
577 next is to see if $y supports the method "as_int()". If it does,
578 "as_int()" is called, but if it doesn't, the next thing is to see
579 if $y supports the method "as_number()". If it does, "as_number()"
580 is called. The method "as_int()" (and "as_number()") is expected to
581 return either an object that has the same class as $x, a subclass
582 thereof, or a string that "ref($x)->new()" can parse to create an
583 object.
584 "as_number()" is an alias to "as_int()". "as_number" was introduced
586 in v1.22, while "as_int()" was introduced in v1.68.
587 In Math::BigInt, "as_int()" has the same effect as "copy()".
589 Boolean methods
591 None of these methods modify the invocand object.
592 is_zero()
594 $x->is_zero(); # true if $x is 0
595 Returns true if the invocand is zero and false otherwise.
597 is_one( [ SIGN ])
599 $x->is_one(); # true if $x is +1
600 $x->is_one("+"); # ditto
601 $x->is_one("-"); # true if $x is -1
602 Returns true if the invocand is one and false otherwise.
604 is_finite()
606 $x->is_finite(); # true if $x is not +inf, -inf or NaN
607 Returns true if the invocand is a finite number, i.e., it is
609 neither +inf, -inf, nor NaN.
610 is_inf( [ SIGN ] )
612 $x->is_inf(); # true if $x is +inf
613 $x->is_inf("+"); # ditto
614 $x->is_inf("-"); # true if $x is -inf
615 Returns true if the invocand is infinite and false otherwise.
617 is_nan()
619 $x->is_nan(); # true if $x is NaN
620 is_positive()
622 is_pos()
623 $x->is_positive(); # true if > 0
624 $x->is_pos(); # ditto
625 Returns true if the invocand is positive and false otherwise. A
627 "NaN" is neither positive nor negative.
628 is_negative()
630 is_neg()
631 $x->is_negative(); # true if < 0
632 $x->is_neg(); # ditto
633 Returns true if the invocand is negative and false otherwise. A
635 "NaN" is neither positive nor negative.
636 is_non_positive()
638 $x->is_non_positive(); # true if <= 0
639 Returns true if the invocand is negative or zero.
641 is_non_negative()
643 $x->is_non_negative(); # true if >= 0
644 Returns true if the invocand is positive or zero.
646 is_odd()
648 $x->is_odd(); # true if odd, false for even
649 Returns true if the invocand is odd and false otherwise. "NaN",
651 "+inf", and "-inf" are neither odd nor even.
652 is_even()
654 $x->is_even(); # true if $x is even
655 Returns true if the invocand is even and false otherwise. "NaN",
657 "+inf", "-inf" are not integers and are neither odd nor even.
658 is_int()
660 $x->is_int(); # true if $x is an integer
661 Returns true if the invocand is an integer and false otherwise.
663 "NaN", "+inf", "-inf" are not integers.
664 Comparison methods
666 None of these methods modify the invocand object. Note that a "NaN" is
667 neither less than, greater than, or equal to anything else, even a
668 "NaN".
669 bcmp()
671 $x->bcmp($y);
672 Returns -1, 0, 1 depending on whether $x is less than, equal to, or
674 grater than $y. Returns undef if any operand is a NaN.
675 bacmp()
677 $x->bacmp($y);
678 Returns -1, 0, 1 depending on whether the absolute value of $x is
680 less than, equal to, or grater than the absolute value of $y.
681 Returns undef if any operand is a NaN.
682 beq()
684 $x -> beq($y);
685 Returns true if and only if $x is equal to $y, and false otherwise.
687 bne()
689 $x -> bne($y);
690 Returns true if and only if $x is not equal to $y, and false
692 otherwise.
693 blt()
695 $x -> blt($y);
696 Returns true if and only if $x is equal to $y, and false otherwise.
698 ble()
700 $x -> ble($y);
701 Returns true if and only if $x is less than or equal to $y, and
703 false otherwise.
704 bgt()
706 $x -> bgt($y);
707 Returns true if and only if $x is greater than $y, and false
709 otherwise.
710 bge()
712 $x -> bge($y);
713 Returns true if and only if $x is greater than or equal to $y, and
715 false otherwise.
716 Arithmetic methods
718 These methods modify the invocand object and returns it.
719 bneg()
721 $x->bneg();
722 Negate the number, e.g. change the sign between '+' and '-', or
724 between '+inf' and '-inf', respectively. Does nothing for NaN or
725 zero.
726 babs()
728 $x->babs();
729 Set the number to its absolute value, e.g. change the sign from '-'
731 to '+' and from '-inf' to '+inf', respectively. Does nothing for
732 NaN or positive numbers.
733 bsgn()
735 $x->bsgn();
736 Signum function. Set the number to -1, 0, or 1, depending on
738 whether the number is negative, zero, or positive, respectively.
739 Does not modify NaNs.
740 bnorm()
742 $x->bnorm(); # normalize (no-op)
743 Normalize the number. This is a no-op and is provided only for
745 backwards compatibility.
746 binc()
748 $x->binc(); # increment x by 1
749 bdec()
751 $x->bdec(); # decrement x by 1
752 badd()
754 $x->badd($y); # addition (add $y to $x)
755 bsub()
757 $x->bsub($y); # subtraction (subtract $y from $x)
758 bmul()
760 $x->bmul($y); # multiplication (multiply $x by $y)
761 bmuladd()
763 $x->bmuladd($y,$z);
764 Multiply $x by $y, and then add $z to the result,
766 This method was added in v1.87 of Math::BigInt (June 2007).
768 bdiv()
770 $x->bdiv($y); # divide, set $x to quotient
771 Divides $x by $y by doing floored division (F-division), where the
773 quotient is the floored (rounded towards negative infinity)
774 quotient of the two operands. In list context, returns the
775 quotient and the remainder. The remainder is either zero or has the
776 same sign as the second operand. In scalar context, only the
777 quotient is returned.
778 The quotient is always the greatest integer less than or equal to
780 the real-valued quotient of the two operands, and the remainder
781 (when it is non-zero) always has the same sign as the second
782 operand; so, for example,
783 1 / 4 => ( 0, 1)
785 1 / -4 => (-1, -3)
786 -3 / 4 => (-1, 1)
787 -3 / -4 => ( 0, -3)
788 -11 / 2 => (-5, 1)
789 11 / -2 => (-5, -1)
790 The behavior of the overloaded operator % agrees with the behavior
792 of Perl's built-in % operator (as documented in the perlop
793 manpage), and the equation
794 $x == ($x / $y) * $y + ($x % $y)
796 holds true for any finite $x and finite, non-zero $y.
798 Perl's "use integer" might change the behaviour of % and / for
800 scalars. This is because under 'use integer' Perl does what the
801 underlying C library thinks is right, and this varies. However,
802 "use integer" does not change the way things are done with
803 Math::BigInt objects.
804 btdiv()
806 $x->btdiv($y); # divide, set $x to quotient
807 Divides $x by $y by doing truncated division (T-division), where
809 quotient is the truncated (rouneded towards zero) quotient of the
810 two operands. In list context, returns the quotient and the
811 remainder. The remainder is either zero or has the same sign as the
812 first operand. In scalar context, only the quotient is returned.
813 bmod()
815 $x->bmod($y); # modulus (x % y)
816 Returns $x modulo $y, i.e., the remainder after floored division
818 (F-division). This method is like Perl's % operator. See "bdiv()".
819 btmod()
821 $x->btmod($y); # modulus
822 Returns the remainer after truncated division (T-division). See
824 "btdiv()".
825 bmodinv()
827 $x->bmodinv($mod); # modular multiplicative inverse
828 Returns the multiplicative inverse of $x modulo $mod. If
830 $y = $x -> copy() -> bmodinv($mod)
832 then $y is the number closest to zero, and with the same sign as
834 $mod, satisfying
835 ($x * $y) % $mod = 1 % $mod
837 If $x and $y are non-zero, they must be relative primes, i.e.,
839 "bgcd($y, $mod)==1". '"NaN"' is returned when no modular
840 multiplicative inverse exists.
841 bmodpow()
843 $num->bmodpow($exp,$mod); # modular exponentiation
844 # ($num**$exp % $mod)
845 Returns the value of $num taken to the power $exp in the modulus
847 $mod using binary exponentiation. "bmodpow" is far superior to
848 writing
849 $num ** $exp % $mod
851 because it is much faster - it reduces internal variables into the
853 modulus whenever possible, so it operates on smaller numbers.
854 "bmodpow" also supports negative exponents.
856 bmodpow($num, -1, $mod)
858 is exactly equivalent to
860 bmodinv($num, $mod)
862 bpow()
864 $x->bpow($y); # power of arguments (x ** y)
865 "bpow()" (and the rounding functions) now modifies the first
867 argument and returns it, unlike the old code which left it alone
868 and only returned the result. This is to be consistent with
869 "badd()" etc. The first three modifies $x, the last one won't:
870 print bpow($x,$i),"\n"; # modify $x
872 print $x->bpow($i),"\n"; # ditto
873 print $x **= $i,"\n"; # the same
874 print $x ** $i,"\n"; # leave $x alone
875 The form "$x **= $y" is faster than "$x = $x ** $y;", though.
877 blog()
879 $x->blog($base, $accuracy); # logarithm of x to the base $base
880 If $base is not defined, Euler's number (e) is used:
882 print $x->blog(undef, 100); # log(x) to 100 digits
884 bexp()
886 $x->bexp($accuracy); # calculate e ** X
887 Calculates the expression "e ** $x" where "e" is Euler's number.
889 This method was added in v1.82 of Math::BigInt (April 2007).
891 See also "blog()".
893 bnok()
895 $x->bnok($y); # x over y (binomial coefficient n over k)
896 Calculates the binomial coefficient n over k, also called the
898 "choose" function, which is
899 ( n ) n!
901 | | = --------
902 ( k ) k!(n-k)!
903 when n and k are non-negative. This method implements the full
905 Kronenburg extension (Kronenburg, M.J. "The Binomial Coefficient
906 for Negative Arguments." 18 May 2011.
907 http://arxiv.org/abs/1105.3689/) illustrated by the following
908 pseudo-code:
909 if n >= 0 and k >= 0:
911 return binomial(n, k)
912 if k >= 0:
913 return (-1)^k*binomial(-n+k-1, k)
914 if k <= n:
915 return (-1)^(n-k)*binomial(-k-1, n-k)
916 else
917 return 0
918 The behaviour is identical to the behaviour of the Maple and
920 Mathematica function for negative integers n, k.
921 buparrow()
923 uparrow()
924 $a -> buparrow($n, $b); # modifies $a
925 $x = $a -> uparrow($n, $b); # does not modify $a
926 This method implements Knuth's up-arrow notation, where $n is a
928 non-negative integer representing the number of up-arrows. $n = 0
929 gives multiplication, $n = 1 gives exponentiation, $n = 2 gives
930 tetration, $n = 3 gives hexation etc. The following illustrates the
931 relation between the first values of $n.
932 See <https://en.wikipedia.org/wiki/Knuth%27s_up-arrow_notation>.
934 backermann()
936 ackermann()
937 $m -> backermann($n); # modifies $a
938 $x = $m -> ackermann($n); # does not modify $a
939 This method implements the Ackermann function:
941 / n + 1 if m = 0
943 A(m, n) = | A(m-1, 1) if m > 0 and n = 0
944 \ A(m-1, A(m, n-1)) if m > 0 and n > 0
945 Its value grows rapidly, even for small inputs. For example, A(4,
947 2) is an integer of 19729 decimal digits.
948 See https://en.wikipedia.org/wiki/Ackermann_function
950 bsin()
952 my $x = Math::BigInt->new(1);
953 print $x->bsin(100), "\n";
954 Calculate the sine of $x, modifying $x in place.
956 In Math::BigInt, unless upgrading is in effect, the result is
958 truncated to an integer.
959 This method was added in v1.87 of Math::BigInt (June 2007).
961 bcos()
963 my $x = Math::BigInt->new(1);
964 print $x->bcos(100), "\n";
965 Calculate the cosine of $x, modifying $x in place.
967 In Math::BigInt, unless upgrading is in effect, the result is
969 truncated to an integer.
970 This method was added in v1.87 of Math::BigInt (June 2007).
972 batan()
974 my $x = Math::BigFloat->new(0.5);
975 print $x->batan(100), "\n";
976 Calculate the arcus tangens of $x, modifying $x in place.
978 In Math::BigInt, unless upgrading is in effect, the result is
980 truncated to an integer.
981 This method was added in v1.87 of Math::BigInt (June 2007).
983 batan2()
985 my $x = Math::BigInt->new(1);
986 my $y = Math::BigInt->new(1);
987 print $y->batan2($x), "\n";
988 Calculate the arcus tangens of $y divided by $x, modifying $y in
990 place.
991 In Math::BigInt, unless upgrading is in effect, the result is
993 truncated to an integer.
994 This method was added in v1.87 of Math::BigInt (June 2007).
996 bsqrt()
998 $x->bsqrt(); # calculate square root
999 "bsqrt()" returns the square root truncated to an integer.
1001 If you want a better approximation of the square root, then use:
1003 $x = Math::BigFloat->new(12);
1005 Math::BigFloat->precision(0);
1006 Math::BigFloat->round_mode('even');
1007 print $x->copy->bsqrt(),"\n"; # 4
1008 Math::BigFloat->precision(2);
1010 print $x->bsqrt(),"\n"; # 3.46
1011 print $x->bsqrt(3),"\n"; # 3.464
1012 broot()
1014 $x->broot($N);
1015 Calculates the N'th root of $x.
1017 bfac()
1019 $x->bfac(); # factorial of $x (1*2*3*4*..*$x)
1020 Returns the factorial of $x, i.e., the product of all positive
1022 integers up to and including $x.
1023 bdfac()
1025 $x->bdfac(); # double factorial of $x (1*2*3*4*..*$x)
1026 Returns the double factorial of $x. If $x is an even integer,
1028 returns the product of all positive, even integers up to and
1029 including $x, i.e., 2*4*6*...*$x. If $x is an odd integer, returns
1030 the product of all positive, odd integers, i.e., 1*3*5*...*$x.
1031 bfib()
1033 $F = $n->bfib(); # a single Fibonacci number
1034 @F = $n->bfib(); # a list of Fibonacci numbers
1035 In scalar context, returns a single Fibonacci number. In list
1037 context, returns a list of Fibonacci numbers. The invocand is the
1038 last element in the output.
1039 The Fibonacci sequence is defined by
1041 F(0) = 0
1043 F(1) = 1
1044 F(n) = F(n-1) + F(n-2)
1045 In list context, F(0) and F(n) is the first and last number in the
1047 output, respectively. For example, if $n is 12, then "@F =
1048 $n->bfib()" returns the following values, F(0) to F(12):
1049 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144
1051 The sequence can also be extended to negative index n using the re-
1053 arranged recurrence relation
1054 F(n-2) = F(n) - F(n-1)
1056 giving the bidirectional sequence
1058 n -7 -6 -5 -4 -3 -2 -1 0 1 2 3 4 5 6 7
1060 F(n) 13 -8 5 -3 2 -1 1 0 1 1 2 3 5 8 13
1061 If $n is -12, the following values, F(0) to F(12), are returned:
1063 0, 1, -1, 2, -3, 5, -8, 13, -21, 34, -55, 89, -144
1065 blucas()
1067 $F = $n->blucas(); # a single Lucas number
1068 @F = $n->blucas(); # a list of Lucas numbers
1069 In scalar context, returns a single Lucas number. In list context,
1071 returns a list of Lucas numbers. The invocand is the last element
1072 in the output.
1073 The Lucas sequence is defined by
1075 L(0) = 2
1077 L(1) = 1
1078 L(n) = L(n-1) + L(n-2)
1079 In list context, L(0) and L(n) is the first and last number in the
1081 output, respectively. For example, if $n is 12, then "@L =
1082 $n->blucas()" returns the following values, L(0) to L(12):
1083 2, 1, 3, 4, 7, 11, 18, 29, 47, 76, 123, 199, 322
1085 The sequence can also be extended to negative index n using the re-
1087 arranged recurrence relation
1088 L(n-2) = L(n) - L(n-1)
1090 giving the bidirectional sequence
1092 n -7 -6 -5 -4 -3 -2 -1 0 1 2 3 4 5 6 7
1094 L(n) 29 -18 11 -7 4 -3 1 2 1 3 4 7 11 18 29
1095 If $n is -12, the following values, L(0) to L(-12), are returned:
1097 2, 1, -3, 4, -7, 11, -18, 29, -47, 76, -123, 199, -322
1099 brsft()
1101 $x->brsft($n); # right shift $n places in base 2
1102 $x->brsft($n, $b); # right shift $n places in base $b
1103 The latter is equivalent to
1105 $x -> bdiv($b -> copy() -> bpow($n))
1107 blsft()
1109 $x->blsft($n); # left shift $n places in base 2
1110 $x->blsft($n, $b); # left shift $n places in base $b
1111 The latter is equivalent to
1113 $x -> bmul($b -> copy() -> bpow($n))
1115 Bitwise methods
1117 band()
1118 $x->band($y); # bitwise and
1119 bior()
1121 $x->bior($y); # bitwise inclusive or
1122 bxor()
1124 $x->bxor($y); # bitwise exclusive or
1125 bnot()
1127 $x->bnot(); # bitwise not (two's complement)
1128 Two's complement (bitwise not). This is equivalent to, but faster
1130 than,
1131 $x->binc()->bneg();
1133 Rounding methods
1135 round()
1136 $x->round($A,$P,$round_mode);
1137 Round $x to accuracy $A or precision $P using the round mode
1139 $round_mode.
1140 bround()
1142 $x->bround($N); # accuracy: preserve $N digits
1143 Rounds $x to an accuracy of $N digits.
1145 bfround()
1147 $x->bfround($N);
1148 Rounds to a multiple of 10**$N. Examples:
1150 Input N Result
1152 123456.123456 3 123500
1154 123456.123456 2 123450
1155 123456.123456 -2 123456.12
1156 123456.123456 -3 123456.123
1157 bfloor()
1159 $x->bfloor();
1160 Round $x towards minus infinity, i.e., set $x to the largest
1162 integer less than or equal to $x.
1163 bceil()
1165 $x->bceil();
1166 Round $x towards plus infinity, i.e., set $x to the smallest
1168 integer greater than or equal to $x).
1169 bint()
1171 $x->bint();
1172 Round $x towards zero.
1174 Other mathematical methods
1176 bgcd()
1177 $x -> bgcd($y); # GCD of $x and $y
1178 $x -> bgcd($y, $z, ...); # GCD of $x, $y, $z, ...
1179 Returns the greatest common divisor (GCD).
1181 blcm()
1183 $x -> blcm($y); # LCM of $x and $y
1184 $x -> blcm($y, $z, ...); # LCM of $x, $y, $z, ...
1185 Returns the least common multiple (LCM).
1187 Object property methods
1189 sign()
1190 $x->sign();
1191 Return the sign, of $x, meaning either "+", "-", "-inf", "+inf" or
1193 NaN.
1194 If you want $x to have a certain sign, use one of the following
1196 methods:
1197 $x->babs(); # '+'
1199 $x->babs()->bneg(); # '-'
1200 $x->bnan(); # 'NaN'
1201 $x->binf(); # '+inf'
1202 $x->binf('-'); # '-inf'
1203 digit()
1205 $x->digit($n); # return the nth digit, counting from right
1206 If $n is negative, returns the digit counting from left.
1208 digitsum()
1210 $x->digitsum();
1211 Computes the sum of the base 10 digits and returns it.
1213 bdigitsum()
1215 $x->bdigitsum();
1216 Computes the sum of the base 10 digits and assigns the result to
1218 the invocand.
1219 length()
1221 $x->length();
1222 ($xl, $fl) = $x->length();
1223 Returns the number of digits in the decimal representation of the
1225 number. In list context, returns the length of the integer and
1226 fraction part. For Math::BigInt objects, the length of the fraction
1227 part is always 0.
1228 The following probably doesn't do what you expect:
1230 $c = Math::BigInt->new(123);
1232 print $c->length(),"\n"; # prints 30
1233 It prints both the number of digits in the number and in the
1235 fraction part since print calls "length()" in list context. Use
1236 something like:
1237 print scalar $c->length(),"\n"; # prints 3
1239 mantissa()
1241 $x->mantissa();
1242 Return the signed mantissa of $x as a Math::BigInt.
1244 exponent()
1246 $x->exponent();
1247 Return the exponent of $x as a Math::BigInt.
1249 parts()
1251 $x->parts();
1252 Returns the significand (mantissa) and the exponent as integers. In
1254 Math::BigFloat, both are returned as Math::BigInt objects.
1255 sparts()
1257 Returns the significand (mantissa) and the exponent as integers. In
1258 scalar context, only the significand is returned. The significand
1259 is the integer with the smallest absolute value. The output of
1260 "sparts()" corresponds to the output from "bsstr()".
1261 In Math::BigInt, this method is identical to "parts()".
1263 nparts()
1265 Returns the significand (mantissa) and exponent corresponding to
1266 normalized notation. In scalar context, only the significand is
1267 returned. For finite non-zero numbers, the significand's absolute
1268 value is greater than or equal to 1 and less than 10. The output of
1269 "nparts()" corresponds to the output from "bnstr()". In
1270 Math::BigInt, if the significand can not be represented as an
1271 integer, upgrading is performed or NaN is returned.
1272 eparts()
1274 Returns the significand (mantissa) and exponent corresponding to
1275 engineering notation. In scalar context, only the significand is
1276 returned. For finite non-zero numbers, the significand's absolute
1277 value is greater than or equal to 1 and less than 1000, and the
1278 exponent is a multiple of 3. The output of "eparts()" corresponds
1279 to the output from "bestr()". In Math::BigInt, if the significand
1280 can not be represented as an integer, upgrading is performed or NaN
1281 is returned.
1282 dparts()
1284 Returns the integer part and the fraction part. If the fraction
1285 part can not be represented as an integer, upgrading is performed
1286 or NaN is returned. The output of "dparts()" corresponds to the
1287 output from "bdstr()".
1288 String conversion methods
1290 bstr()
1291 Returns a string representing the number using decimal notation. In
1292 Math::BigFloat, the output is zero padded according to the current
1293 accuracy or precision, if any of those are defined.
1294 bsstr()
1296 Returns a string representing the number using scientific notation
1297 where both the significand (mantissa) and the exponent are
1298 integers. The output corresponds to the output from "sparts()".
1299 123 is returned as "123e+0"
1301 1230 is returned as "123e+1"
1302 12300 is returned as "123e+2"
1303 12000 is returned as "12e+3"
1304 10000 is returned as "1e+4"
1305 bnstr()
1307 Returns a string representing the number using normalized notation,
1308 the most common variant of scientific notation. For finite non-zero
1309 numbers, the absolute value of the significand is greater than or
1310 equal to 1 and less than 10. The output corresponds to the output
1311 from "nparts()".
1312 123 is returned as "1.23e+2"
1314 1230 is returned as "1.23e+3"
1315 12300 is returned as "1.23e+4"
1316 12000 is returned as "1.2e+4"
1317 10000 is returned as "1e+4"
1318 bestr()
1320 Returns a string representing the number using engineering
1321 notation. For finite non-zero numbers, the absolute value of the
1322 significand is greater than or equal to 1 and less than 1000, and
1323 the exponent is a multiple of 3. The output corresponds to the
1324 output from "eparts()".
1325 123 is returned as "123e+0"
1327 1230 is returned as "1.23e+3"
1328 12300 is returned as "12.3e+3"
1329 12000 is returned as "12e+3"
1330 10000 is returned as "10e+3"
1331 bdstr()
1333 Returns a string representing the number using decimal notation.
1334 The output corresponds to the output from "dparts()".
1335 123 is returned as "123"
1337 1230 is returned as "1230"
1338 12300 is returned as "12300"
1339 12000 is returned as "12000"
1340 10000 is returned as "10000"
1341 to_hex()
1343 $x->to_hex();
1344 Returns a hexadecimal string representation of the number. See also
1346 from_hex().
1347 to_bin()
1349 $x->to_bin();
1350 Returns a binary string representation of the number. See also
1352 from_bin().
1353 to_oct()
1355 $x->to_oct();
1356 Returns an octal string representation of the number. See also
1358 from_oct().
1359 to_bytes()
1361 $x = Math::BigInt->new("1667327589");
1362 $s = $x->to_bytes(); # $s = "cafe"
1363 Returns a byte string representation of the number using big endian
1365 byte order. The invocand must be a non-negative, finite integer.
1366 See also from_bytes().
1367 to_base()
1369 $x = Math::BigInt->new("250");
1370 $x->to_base(2); # returns "11111010"
1371 $x->to_base(8); # returns "372"
1372 $x->to_base(16); # returns "fa"
1373 Returns a string representation of the number in the given base. If
1375 a collation sequence is given, the collation sequence determines
1376 which characters are used in the output.
1377 Here are some more examples
1379 $x = Math::BigInt->new("16")->to_base(3); # returns "121"
1381 $x = Math::BigInt->new("44027")->to_base(36); # returns "XYZ"
1382 $x = Math::BigInt->new("58314")->to_base(42); # returns "Why"
1383 $x = Math::BigInt->new("4")->to_base(2, "-|"); # returns "|--"
1384 See from_base() for information and examples.
1386 as_hex()
1388 $x->as_hex();
1389 As, "to_hex()", but with a "0x" prefix.
1391 as_bin()
1393 $x->as_bin();
1394 As, "to_bin()", but with a "0b" prefix.
1396 as_oct()
1398 $x->as_oct();
1399 As, "to_oct()", but with a "0" prefix.
1401 as_bytes()
1403 This is just an alias for "to_bytes()".
1404 Other conversion methods
1406 numify()
1407 print $x->numify();
1408 Returns a Perl scalar from $x. It is used automatically whenever a
1410 scalar is needed, for instance in array index operations.
1411
1413 Math::BigInt and Math::BigFloat have full support for accuracy and
1414 precision based rounding, both automatically after every operation, as
1415 well as manually.
1416 This section describes the accuracy/precision handling in Math::BigInt
1418 and Math::BigFloat as it used to be and as it is now, complete with an
1419 explanation of all terms and abbreviations.
1420 Not yet implemented things (but with correct description) are marked
1422 with '!', things that need to be answered are marked with '?'.
1423 In the next paragraph follows a short description of terms used here
1425 (because these may differ from terms used by others people or
1426 documentation).
1427 During the rest of this document, the shortcuts A (for accuracy), P
1429 (for precision), F (fallback) and R (rounding mode) are be used.
1430 Precision P
1432 Precision is a fixed number of digits before (positive) or after
1433 (negative) the decimal point. For example, 123.45 has a precision of
1434 -2. 0 means an integer like 123 (or 120). A precision of 2 means at
1435 least two digits to the left of the decimal point are zero, so 123 with
1436 P = 1 becomes 120. Note that numbers with zeros before the decimal
1437 point may have different precisions, because 1200 can have P = 0, 1 or
1438 2 (depending on what the initial value was). It could also have p < 0,
1439 when the digits after the decimal point are zero.
1440 The string output (of floating point numbers) is padded with zeros:
1442 Initial value P A Result String
1444 ------------------------------------------------------------
1445 1234.01 -3 1000 1000
1446 1234 -2 1200 1200
1447 1234.5 -1 1230 1230
1448 1234.001 1 1234 1234.0
1449 1234.01 0 1234 1234
1450 1234.01 2 1234.01 1234.01
1451 1234.01 5 1234.01 1234.01000
1452 For Math::BigInt objects, no padding occurs.
1454 Accuracy A
1456 Number of significant digits. Leading zeros are not counted. A number
1457 may have an accuracy greater than the non-zero digits when there are
1458 zeros in it or trailing zeros. For example, 123.456 has A of 6, 10203
1459 has 5, 123.0506 has 7, 123.45000 has 8 and 0.000123 has 3.
1460 The string output (of floating point numbers) is padded with zeros:
1462 Initial value P A Result String
1464 ------------------------------------------------------------
1465 1234.01 3 1230 1230
1466 1234.01 6 1234.01 1234.01
1467 1234.1 8 1234.1 1234.1000
1468 For Math::BigInt objects, no padding occurs.
1470 Fallback F
1472 When both A and P are undefined, this is used as a fallback accuracy
1473 when dividing numbers.
1474 Rounding mode R
1476 When rounding a number, different 'styles' or 'kinds' of rounding are
1477 possible. (Note that random rounding, as in Math::Round, is not
1478 implemented.)
1479 Directed rounding
1481 These round modes always round in the same direction.
1483 'trunc'
1485 Round towards zero. Remove all digits following the rounding place,
1486 i.e., replace them with zeros. Thus, 987.65 rounded to tens (P=1)
1487 becomes 980, and rounded to the fourth significant digit becomes
1488 987.6 (A=4). 123.456 rounded to the second place after the decimal
1489 point (P=-2) becomes 123.46. This corresponds to the IEEE 754
1490 rounding mode 'roundTowardZero'.
1491 Rounding to nearest
1493 These rounding modes round to the nearest digit. They differ in how
1495 they determine which way to round in the ambiguous case when there is a
1496 tie.
1497 'even'
1499 Round towards the nearest even digit, e.g., when rounding to
1500 nearest integer, -5.5 becomes -6, 4.5 becomes 4, but 4.501 becomes
1501 5. This corresponds to the IEEE 754 rounding mode
1502 'roundTiesToEven'.
1503 'odd'
1505 Round towards the nearest odd digit, e.g., when rounding to nearest
1506 integer, 4.5 becomes 5, -5.5 becomes -5, but 5.501 becomes 6. This
1507 corresponds to the IEEE 754 rounding mode 'roundTiesToOdd'.
1508 '+inf'
1510 Round towards plus infinity, i.e., always round up. E.g., when
1511 rounding to the nearest integer, 4.5 becomes 5, -5.5 becomes -5,
1512 and 4.501 also becomes 5. This corresponds to the IEEE 754 rounding
1513 mode 'roundTiesToPositive'.
1514 '-inf'
1516 Round towards minus infinity, i.e., always round down. E.g., when
1517 rounding to the nearest integer, 4.5 becomes 4, -5.5 becomes -6,
1518 but 4.501 becomes 5. This corresponds to the IEEE 754 rounding mode
1519 'roundTiesToNegative'.
1520 'zero'
1522 Round towards zero, i.e., round positive numbers down and negative
1523 numbers up. E.g., when rounding to the nearest integer, 4.5
1524 becomes 4, -5.5 becomes -5, but 4.501 becomes 5. This corresponds
1525 to the IEEE 754 rounding mode 'roundTiesToZero'.
1526 'common'
1528 Round away from zero, i.e., round to the number with the largest
1529 absolute value. E.g., when rounding to the nearest integer, -1.5
1530 becomes -2, 1.5 becomes 2 and 1.49 becomes 1. This corresponds to
1531 the IEEE 754 rounding mode 'roundTiesToAway'.
1532 The handling of A & P in MBI/MBF (the old core code shipped with Perl
1534 versions <= 5.7.2) is like this:
1535 Precision
1537 * bfround($p) is able to round to $p number of digits after the decimal
1538 point
1539 * otherwise P is unused
1540 Accuracy (significant digits)
1542 * bround($a) rounds to $a significant digits
1543 * only bdiv() and bsqrt() take A as (optional) parameter
1544 + other operations simply create the same number (bneg etc), or
1545 more (bmul) of digits
1546 + rounding/truncating is only done when explicitly calling one
1547 of bround or bfround, and never for Math::BigInt (not implemented)
1548 * bsqrt() simply hands its accuracy argument over to bdiv.
1549 * the documentation and the comment in the code indicate two
1550 different ways on how bdiv() determines the maximum number
1551 of digits it should calculate, and the actual code does yet
1552 another thing
1553 POD:
1554 max($Math::BigFloat::div_scale,length(dividend)+length(divisor))
1555 Comment:
1556 result has at most max(scale, length(dividend), length(divisor)) digits
1557 Actual code:
1558 scale = max(scale, length(dividend)-1,length(divisor)-1);
1559 scale += length(divisor) - length(dividend);
1560 So for lx = 3, ly = 9, scale = 10, scale will actually be 16 (10
1561 So for lx = 3, ly = 9, scale = 10, scale will actually be 16
1562 (10+9-3). Actually, the 'difference' added to the scale is cal-
1563 culated from the number of "significant digits" in dividend and
1564 divisor, which is derived by looking at the length of the man-
1565 tissa. Which is wrong, since it includes the + sign (oops) and
1566 actually gets 2 for '+100' and 4 for '+101'. Oops again. Thus
1567 124/3 with div_scale=1 will get you '41.3' based on the strange
1568 assumption that 124 has 3 significant digits, while 120/7 will
1569 get you '17', not '17.1' since 120 is thought to have 2 signif-
1570 icant digits. The rounding after the division then uses the
1571 remainder and $y to determine whether it must round up or down.
1572 ? I have no idea which is the right way. That's why I used a slightly more
1573 ? simple scheme and tweaked the few failing testcases to match it.
1574 This is how it works now:
1576 Setting/Accessing
1578 * You can set the A global via Math::BigInt->accuracy() or
1579 Math::BigFloat->accuracy() or whatever class you are using.
1580 * You can also set P globally by using Math::SomeClass->precision()
1581 likewise.
1582 * Globals are classwide, and not inherited by subclasses.
1583 * to undefine A, use Math::SomeCLass->accuracy(undef);
1584 * to undefine P, use Math::SomeClass->precision(undef);
1585 * Setting Math::SomeClass->accuracy() clears automatically
1586 Math::SomeClass->precision(), and vice versa.
1587 * To be valid, A must be > 0, P can have any value.
1588 * If P is negative, this means round to the P'th place to the right of the
1589 decimal point; positive values mean to the left of the decimal point.
1590 P of 0 means round to integer.
1591 * to find out the current global A, use Math::SomeClass->accuracy()
1592 * to find out the current global P, use Math::SomeClass->precision()
1593 * use $x->accuracy() respective $x->precision() for the local
1594 setting of $x.
1595 * Please note that $x->accuracy() respective $x->precision()
1596 return eventually defined global A or P, when $x's A or P is not
1597 set.
1598 Creating numbers
1600 * When you create a number, you can give the desired A or P via:
1601 $x = Math::BigInt->new($number,$A,$P);
1602 * Only one of A or P can be defined, otherwise the result is NaN
1603 * If no A or P is give ($x = Math::BigInt->new($number) form), then the
1604 globals (if set) will be used. Thus changing the global defaults later on
1605 will not change the A or P of previously created numbers (i.e., A and P of
1606 $x will be what was in effect when $x was created)
1607 * If given undef for A and P, NO rounding will occur, and the globals will
1608 NOT be used. This is used by subclasses to create numbers without
1609 suffering rounding in the parent. Thus a subclass is able to have its own
1610 globals enforced upon creation of a number by using
1611 $x = Math::BigInt->new($number,undef,undef):
1612 use Math::BigInt::SomeSubclass;
1614 use Math::BigInt;
1615 Math::BigInt->accuracy(2);
1617 Math::BigInt::SomeSubClass->accuracy(3);
1618 $x = Math::BigInt::SomeSubClass->new(1234);
1619 $x is now 1230, and not 1200. A subclass might choose to implement
1621 this otherwise, e.g. falling back to the parent's A and P.
1622 Usage
1624 * If A or P are enabled/defined, they are used to round the result of each
1625 operation according to the rules below
1626 * Negative P is ignored in Math::BigInt, since Math::BigInt objects never
1627 have digits after the decimal point
1628 * Math::BigFloat uses Math::BigInt internally, but setting A or P inside
1629 Math::BigInt as globals does not tamper with the parts of a Math::BigFloat.
1630 A flag is used to mark all Math::BigFloat numbers as 'never round'.
1631 Precedence
1633 * It only makes sense that a number has only one of A or P at a time.
1634 If you set either A or P on one object, or globally, the other one will
1635 be automatically cleared.
1636 * If two objects are involved in an operation, and one of them has A in
1637 effect, and the other P, this results in an error (NaN).
1638 * A takes precedence over P (Hint: A comes before P).
1639 If neither of them is defined, nothing is used, i.e. the result will have
1640 as many digits as it can (with an exception for bdiv/bsqrt) and will not
1641 be rounded.
1642 * There is another setting for bdiv() (and thus for bsqrt()). If neither of
1643 A or P is defined, bdiv() will use a fallback (F) of $div_scale digits.
1644 If either the dividend's or the divisor's mantissa has more digits than
1645 the value of F, the higher value will be used instead of F.
1646 This is to limit the digits (A) of the result (just consider what would
1647 happen with unlimited A and P in the case of 1/3 :-)
1648 * bdiv will calculate (at least) 4 more digits than required (determined by
1649 A, P or F), and, if F is not used, round the result
1650 (this will still fail in the case of a result like 0.12345000000001 with A
1651 or P of 5, but this can not be helped - or can it?)
1652 * Thus you can have the math done by on Math::Big* class in two modi:
1653 + never round (this is the default):
1654 This is done by setting A and P to undef. No math operation
1655 will round the result, with bdiv() and bsqrt() as exceptions to guard
1656 against overflows. You must explicitly call bround(), bfround() or
1657 round() (the latter with parameters).
1658 Note: Once you have rounded a number, the settings will 'stick' on it
1659 and 'infect' all other numbers engaged in math operations with it, since
1660 local settings have the highest precedence. So, to get SaferRound[tm],
1661 use a copy() before rounding like this:
1662 $x = Math::BigFloat->new(12.34);
1664 $y = Math::BigFloat->new(98.76);
1665 $z = $x * $y; # 1218.6984
1666 print $x->copy()->bround(3); # 12.3 (but A is now 3!)
1667 $z = $x * $y; # still 1218.6984, without
1668 # copy would have been 1210!
1669 + round after each op:
1671 After each single operation (except for testing like is_zero()), the
1672 method round() is called and the result is rounded appropriately. By
1673 setting proper values for A and P, you can have all-the-same-A or
1674 all-the-same-P modes. For example, Math::Currency might set A to undef,
1675 and P to -2, globally.
1676 ?Maybe an extra option that forbids local A & P settings would be in order,
1678 ?so that intermediate rounding does not 'poison' further math?
1679 Overriding globals
1681 * you will be able to give A, P and R as an argument to all the calculation
1682 routines; the second parameter is A, the third one is P, and the fourth is
1683 R (shift right by one for binary operations like badd). P is used only if
1684 the first parameter (A) is undefined. These three parameters override the
1685 globals in the order detailed as follows, i.e. the first defined value
1686 wins:
1687 (local: per object, global: global default, parameter: argument to sub)
1688 + parameter A
1689 + parameter P
1690 + local A (if defined on both of the operands: smaller one is taken)
1691 + local P (if defined on both of the operands: bigger one is taken)
1692 + global A
1693 + global P
1694 + global F
1695 * bsqrt() will hand its arguments to bdiv(), as it used to, only now for two
1696 arguments (A and P) instead of one
1697 Local settings
1699 * You can set A or P locally by using $x->accuracy() or
1700 $x->precision()
1701 and thus force different A and P for different objects/numbers.
1702 * Setting A or P this way immediately rounds $x to the new value.
1703 * $x->accuracy() clears $x->precision(), and vice versa.
1704 Rounding
1706 * the rounding routines will use the respective global or local settings.
1707 bround() is for accuracy rounding, while bfround() is for precision
1708 * the two rounding functions take as the second parameter one of the
1709 following rounding modes (R):
1710 'even', 'odd', '+inf', '-inf', 'zero', 'trunc', 'common'
1711 * you can set/get the global R by using Math::SomeClass->round_mode()
1712 or by setting $Math::SomeClass::round_mode
1713 * after each operation, $result->round() is called, and the result may
1714 eventually be rounded (that is, if A or P were set either locally,
1715 globally or as parameter to the operation)
1716 * to manually round a number, call $x->round($A,$P,$round_mode);
1717 this will round the number by using the appropriate rounding function
1718 and then normalize it.
1719 * rounding modifies the local settings of the number:
1720 $x = Math::BigFloat->new(123.456);
1722 $x->accuracy(5);
1723 $x->bround(4);
1724 Here 4 takes precedence over 5, so 123.5 is the result and $x->accuracy()
1726 will be 4 from now on.
1727 Default values
1729 * R: 'even'
1730 * F: 40
1731 * A: undef
1732 * P: undef
1733 Remarks
1735 * The defaults are set up so that the new code gives the same results as
1736 the old code (except in a few cases on bdiv):
1737 + Both A and P are undefined and thus will not be used for rounding
1738 after each operation.
1739 + round() is thus a no-op, unless given extra parameters A and P
1740
1742 While Math::BigInt has extensive handling of inf and NaN, certain
1743 quirks remain.
1744 oct()/hex()
1746 These perl routines currently (as of Perl v.5.8.6) cannot handle
1747 passed inf.
1748 te@linux:~> perl -wle 'print 2 ** 3333'
1750 Inf
1751 te@linux:~> perl -wle 'print 2 ** 3333 == 2 ** 3333'
1752 1
1753 te@linux:~> perl -wle 'print oct(2 ** 3333)'
1754 0
1755 te@linux:~> perl -wle 'print hex(2 ** 3333)'
1756 Illegal hexadecimal digit 'I' ignored at -e line 1.
1757 0
1758 The same problems occur if you pass them Math::BigInt->binf()
1760 objects. Since overloading these routines is not possible, this
1761 cannot be fixed from Math::BigInt.
1762
1764 You should neither care about nor depend on the internal
1765 representation; it might change without notice. Use ONLY method calls
1766 like "$x->sign();" instead relying on the internal representation.
1767 MATH LIBRARY
1769 Math with the numbers is done (by default) by a module called
1770 "Math::BigInt::Calc". This is equivalent to saying:
1771 use Math::BigInt try => 'Calc';
1773 You can change this backend library by using:
1775 use Math::BigInt try => 'GMP';
1777 Note: General purpose packages should not be explicit about the library
1779 to use; let the script author decide which is best.
1780 If your script works with huge numbers and Calc is too slow for them,
1782 you can also for the loading of one of these libraries and if none of
1783 them can be used, the code dies:
1784 use Math::BigInt only => 'GMP,Pari';
1786 The following would first try to find Math::BigInt::Foo, then
1788 Math::BigInt::Bar, and when this also fails, revert to
1789 Math::BigInt::Calc:
1790 use Math::BigInt try => 'Foo,Math::BigInt::Bar';
1792 The library that is loaded last is used. Note that this can be
1794 overwritten at any time by loading a different library, and numbers
1795 constructed with different libraries cannot be used in math operations
1796 together.
1797 What library to use?
1799 Note: General purpose packages should not be explicit about the library
1801 to use; let the script author decide which is best.
1802 Math::BigInt::GMP and Math::BigInt::Pari are in cases involving big
1804 numbers much faster than Calc, however it is slower when dealing with
1805 very small numbers (less than about 20 digits) and when converting very
1806 large numbers to decimal (for instance for printing, rounding,
1807 calculating their length in decimal etc).
1808 So please select carefully what library you want to use.
1810 Different low-level libraries use different formats to store the
1812 numbers. However, you should NOT depend on the number having a
1813 specific format internally.
1814 See the respective math library module documentation for further
1816 details.
1817 SIGN
1819 The sign is either '+', '-', 'NaN', '+inf' or '-inf'.
1820 A sign of 'NaN' is used to represent the result when input arguments
1822 are not numbers or as a result of 0/0. '+inf' and '-inf' represent plus
1823 respectively minus infinity. You get '+inf' when dividing a positive
1824 number by 0, and '-inf' when dividing any negative number by 0.
1825
1827 use Math::BigInt;
1828 sub bigint { Math::BigInt->new(shift); }
1830 $x = Math::BigInt->bstr("1234") # string "1234"
1832 $x = "$x"; # same as bstr()
1833 $x = Math::BigInt->bneg("1234"); # Math::BigInt "-1234"
1834 $x = Math::BigInt->babs("-12345"); # Math::BigInt "12345"
1835 $x = Math::BigInt->bnorm("-0.00"); # Math::BigInt "0"
1836 $x = bigint(1) + bigint(2); # Math::BigInt "3"
1837 $x = bigint(1) + "2"; # ditto (auto-Math::BigIntify of "2")
1838 $x = bigint(1); # Math::BigInt "1"
1839 $x = $x + 5 / 2; # Math::BigInt "3"
1840 $x = $x ** 3; # Math::BigInt "27"
1841 $x *= 2; # Math::BigInt "54"
1842 $x = Math::BigInt->new(0); # Math::BigInt "0"
1843 $x--; # Math::BigInt "-1"
1844 $x = Math::BigInt->badd(4,5) # Math::BigInt "9"
1845 print $x->bsstr(); # 9e+0
1846 Examples for rounding:
1848 use Math::BigFloat;
1850 use Test::More;
1851 $x = Math::BigFloat->new(123.4567);
1853 $y = Math::BigFloat->new(123.456789);
1854 Math::BigFloat->accuracy(4); # no more A than 4
1855 is ($x->copy()->bround(),123.4); # even rounding
1857 print $x->copy()->bround(),"\n"; # 123.4
1858 Math::BigFloat->round_mode('odd'); # round to odd
1859 print $x->copy()->bround(),"\n"; # 123.5
1860 Math::BigFloat->accuracy(5); # no more A than 5
1861 Math::BigFloat->round_mode('odd'); # round to odd
1862 print $x->copy()->bround(),"\n"; # 123.46
1863 $y = $x->copy()->bround(4),"\n"; # A = 4: 123.4
1864 print "$y, ",$y->accuracy(),"\n"; # 123.4, 4
1865 Math::BigFloat->accuracy(undef); # A not important now
1867 Math::BigFloat->precision(2); # P important
1868 print $x->copy()->bnorm(),"\n"; # 123.46
1869 print $x->copy()->bround(),"\n"; # 123.46
1870 Examples for converting:
1872 my $x = Math::BigInt->new('0b1'.'01' x 123);
1874 print "bin: ",$x->as_bin()," hex:",$x->as_hex()," dec: ",$x,"\n";
1875
1877 After "use Math::BigInt ':constant'" all the integer decimal,
1878 hexadecimal and binary constants in the given scope are converted to
1879 "Math::BigInt". This conversion happens at compile time.
1880 In particular,
1882 perl -MMath::BigInt=:constant -e 'print 2**100,"\n"'
1884 prints the integer value of "2**100". Note that without conversion of
1886 constants the expression 2**100 is calculated using Perl scalars.
1887 Please note that strings and floating point constants are not affected,
1889 so that
1890 use Math::BigInt qw/:constant/;
1892 $x = 1234567890123456789012345678901234567890
1894 + 123456789123456789;
1895 $y = '1234567890123456789012345678901234567890'
1896 + '123456789123456789';
1897 does not give you what you expect. You need an explicit
1899 Math::BigInt->new() around one of the operands. You should also quote
1900 large constants to protect loss of precision:
1901 use Math::BigInt;
1903 $x = Math::BigInt->new('1234567889123456789123456789123456789');
1905 Without the quotes Perl would convert the large number to a floating
1907 point constant at compile time and then hand the result to
1908 Math::BigInt, which results in an truncated result or a NaN.
1909 This also applies to integers that look like floating point constants:
1911 use Math::BigInt ':constant';
1913 print ref(123e2),"\n";
1915 print ref(123.2e2),"\n";
1916 prints nothing but newlines. Use either bignum or Math::BigFloat to get
1918 this to work.
1919
1921 Using the form $x += $y; etc over $x = $x + $y is faster, since a copy
1922 of $x must be made in the second case. For long numbers, the copy can
1923 eat up to 20% of the work (in the case of addition/subtraction, less
1924 for multiplication/division). If $y is very small compared to $x, the
1925 form $x += $y is MUCH faster than $x = $x + $y since making the copy of
1926 $x takes more time then the actual addition.
1927 With a technique called copy-on-write, the cost of copying with
1929 overload could be minimized or even completely avoided. A test
1930 implementation of COW did show performance gains for overloaded math,
1931 but introduced a performance loss due to a constant overhead for all
1932 other operations. So Math::BigInt does currently not COW.
1933 The rewritten version of this module (vs. v0.01) is slower on certain
1935 operations, like "new()", "bstr()" and "numify()". The reason are that
1936 it does now more work and handles much more cases. The time spent in
1937 these operations is usually gained in the other math operations so that
1938 code on the average should get (much) faster. If they don't, please
1939 contact the author.
1940 Some operations may be slower for small numbers, but are significantly
1942 faster for big numbers. Other operations are now constant (O(1), like
1943 "bneg()", "babs()" etc), instead of O(N) and thus nearly always take
1944 much less time. These optimizations were done on purpose.
1945 If you find the Calc module to slow, try to install any of the
1947 replacement modules and see if they help you.
1948 Alternative math libraries
1950 You can use an alternative library to drive Math::BigInt. See the
1951 section "MATH LIBRARY" for more information.
1952 For more benchmark results see
1954 <http://bloodgate.com/perl/benchmarks.html>.
1955
1957 Subclassing Math::BigInt
1958 The basic design of Math::BigInt allows simple subclasses with very
1959 little work, as long as a few simple rules are followed:
1960 · The public API must remain consistent, i.e. if a sub-class is
1962 overloading addition, the sub-class must use the same name, in this
1963 case badd(). The reason for this is that Math::BigInt is optimized
1964 to call the object methods directly.
1965 · The private object hash keys like "$x->{sign}" may not be changed,
1967 but additional keys can be added, like "$x->{_custom}".
1968 · Accessor functions are available for all existing object hash keys
1970 and should be used instead of directly accessing the internal hash
1971 keys. The reason for this is that Math::BigInt itself has a
1972 pluggable interface which permits it to support different storage
1973 methods.
1974 More complex sub-classes may have to replicate more of the logic
1976 internal of Math::BigInt if they need to change more basic behaviors. A
1977 subclass that needs to merely change the output only needs to overload
1978 "bstr()".
1979 All other object methods and overloaded functions can be directly
1981 inherited from the parent class.
1982 At the very minimum, any subclass needs to provide its own "new()" and
1984 can store additional hash keys in the object. There are also some
1985 package globals that must be defined, e.g.:
1986 # Globals
1988 $accuracy = undef;
1989 $precision = -2; # round to 2 decimal places
1990 $round_mode = 'even';
1991 $div_scale = 40;
1992 Additionally, you might want to provide the following two globals to
1994 allow auto-upgrading and auto-downgrading to work correctly:
1995 $upgrade = undef;
1997 $downgrade = undef;
1998 This allows Math::BigInt to correctly retrieve package globals from the
2000 subclass, like $SubClass::precision. See t/Math/BigInt/Subclass.pm or
2001 t/Math/BigFloat/SubClass.pm completely functional subclass examples.
2002 Don't forget to
2004 use overload;
2006 in your subclass to automatically inherit the overloading from the
2008 parent. If you like, you can change part of the overloading, look at
2009 Math::String for an example.
2010
2012 When used like this:
2013 use Math::BigInt upgrade => 'Foo::Bar';
2015 certain operations 'upgrade' their calculation and thus the result to
2017 the class Foo::Bar. Usually this is used in conjunction with
2018 Math::BigFloat:
2019 use Math::BigInt upgrade => 'Math::BigFloat';
2021 As a shortcut, you can use the module bignum:
2023 use bignum;
2025 Also good for one-liners:
2027 perl -Mbignum -le 'print 2 ** 255'
2029 This makes it possible to mix arguments of different classes (as in 2.5
2031 + 2) as well es preserve accuracy (as in sqrt(3)).
2032 Beware: This feature is not fully implemented yet.
2034 Auto-upgrade
2036 The following methods upgrade themselves unconditionally; that is if
2037 upgrade is in effect, they always hands up their work:
2038 div bsqrt blog bexp bpi bsin bcos batan batan2
2040 All other methods upgrade themselves only when one (or all) of their
2042 arguments are of the class mentioned in $upgrade.
2043
2045 "Math::BigInt" exports nothing by default, but can export the following
2046 methods:
2047 bgcd
2049 blcm
2050
2052 Some things might not work as you expect them. Below is documented what
2053 is known to be troublesome:
2054 Comparing numbers as strings
2056 Both "bstr()" and "bsstr()" as well as stringify via overload drop
2057 the leading '+'. This is to be consistent with Perl and to make
2058 "cmp" (especially with overloading) to work as you expect. It also
2059 solves problems with "Test.pm" and Test::More, which stringify
2060 arguments before comparing them.
2061 Mark Biggar said, when asked about to drop the '+' altogether, or
2063 make only "cmp" work:
2064 I agree (with the first alternative), don't add the '+' on positive
2066 numbers. It's not as important anymore with the new internal form
2067 for numbers. It made doing things like abs and neg easier, but
2068 those have to be done differently now anyway.
2069 So, the following examples now works as expected:
2071 use Test::More tests => 1;
2073 use Math::BigInt;
2074 my $x = Math::BigInt -> new(3*3);
2076 my $y = Math::BigInt -> new(3*3);
2077 is($x,3*3, 'multiplication');
2079 print "$x eq 9" if $x eq $y;
2080 print "$x eq 9" if $x eq '9';
2081 print "$x eq 9" if $x eq 3*3;
2082 Additionally, the following still works:
2084 print "$x == 9" if $x == $y;
2086 print "$x == 9" if $x == 9;
2087 print "$x == 9" if $x == 3*3;
2088 There is now a "bsstr()" method to get the string in scientific
2090 notation aka 1e+2 instead of 100. Be advised that overloaded 'eq'
2091 always uses bstr() for comparison, but Perl represents some numbers
2092 as 100 and others as 1e+308. If in doubt, convert both arguments
2093 to Math::BigInt before comparing them as strings:
2094 use Test::More tests => 3;
2096 use Math::BigInt;
2097 $x = Math::BigInt->new('1e56'); $y = 1e56;
2099 is($x,$y); # fails
2100 is($x->bsstr(),$y); # okay
2101 $y = Math::BigInt->new($y);
2102 is($x,$y); # okay
2103 Alternatively, simply use "<=>" for comparisons, this always gets
2105 it right. There is not yet a way to get a number automatically
2106 represented as a string that matches exactly the way Perl
2107 represents it.
2108 See also the section about "Infinity and Not a Number" for problems
2110 in comparing NaNs.
2111 int()
2113 "int()" returns (at least for Perl v5.7.1 and up) another
2114 Math::BigInt, not a Perl scalar:
2115 $x = Math::BigInt->new(123);
2117 $y = int($x); # 123 as a Math::BigInt
2118 $x = Math::BigFloat->new(123.45);
2119 $y = int($x); # 123 as a Math::BigFloat
2120 If you want a real Perl scalar, use "numify()":
2122 $y = $x->numify(); # 123 as a scalar
2124 This is seldom necessary, though, because this is done
2126 automatically, like when you access an array:
2127 $z = $array[$x]; # does work automatically
2129 Modifying and =
2131 Beware of:
2132 $x = Math::BigFloat->new(5);
2134 $y = $x;
2135 This makes a second reference to the same object and stores it in
2137 $y. Thus anything that modifies $x (except overloaded operators)
2138 also modifies $y, and vice versa. Or in other words, "=" is only
2139 safe if you modify your Math::BigInt objects only via overloaded
2140 math. As soon as you use a method call it breaks:
2141 $x->bmul(2);
2143 print "$x, $y\n"; # prints '10, 10'
2144 If you want a true copy of $x, use:
2146 $y = $x->copy();
2148 You can also chain the calls like this, this first makes a copy and
2150 then multiply it by 2:
2151 $y = $x->copy()->bmul(2);
2153 See also the documentation for overload.pm regarding "=".
2155 Overloading -$x
2157 The following:
2158 $x = -$x;
2160 is slower than
2162 $x->bneg();
2164 since overload calls "sub($x,0,1);" instead of "neg($x)". The first
2166 variant needs to preserve $x since it does not know that it later
2167 gets overwritten. This makes a copy of $x and takes O(N), but
2168 $x->bneg() is O(1).
2169 Mixing different object types
2171 With overloaded operators, it is the first (dominating) operand
2172 that determines which method is called. Here are some examples
2173 showing what actually gets called in various cases.
2174 use Math::BigInt;
2176 use Math::BigFloat;
2177 $mbf = Math::BigFloat->new(5);
2179 $mbi2 = Math::BigInt->new(5);
2180 $mbi = Math::BigInt->new(2);
2181 # what actually gets called:
2182 $float = $mbf + $mbi; # $mbf->badd($mbi)
2183 $float = $mbf / $mbi; # $mbf->bdiv($mbi)
2184 $integer = $mbi + $mbf; # $mbi->badd($mbf)
2185 $integer = $mbi2 / $mbi; # $mbi2->bdiv($mbi)
2186 $integer = $mbi2 / $mbf; # $mbi2->bdiv($mbf)
2187 For instance, Math::BigInt->bdiv() always returns a Math::BigInt,
2189 regardless of whether the second operant is a Math::BigFloat. To
2190 get a Math::BigFloat you either need to call the operation
2191 manually, make sure each operand already is a Math::BigFloat, or
2192 cast to that type via Math::BigFloat->new():
2193 $float = Math::BigFloat->new($mbi2) / $mbi; # = 2.5
2195 Beware of casting the entire expression, as this would cast the
2197 result, at which point it is too late:
2198 $float = Math::BigFloat->new($mbi2 / $mbi); # = 2
2200 Beware also of the order of more complicated expressions like:
2202 $integer = ($mbi2 + $mbi) / $mbf; # int / float => int
2204 $integer = $mbi2 / Math::BigFloat->new($mbi); # ditto
2205 If in doubt, break the expression into simpler terms, or cast all
2207 operands to the desired resulting type.
2208 Scalar values are a bit different, since:
2210 $float = 2 + $mbf;
2212 $float = $mbf + 2;
2213 both result in the proper type due to the way the overloaded math
2215 works.
2216 This section also applies to other overloaded math packages, like
2218 Math::String.
2219 One solution to you problem might be autoupgrading|upgrading. See
2221 the pragmas bignum, bigint and bigrat for an easy way to do this.
2222
2224 Please report any bugs or feature requests to "bug-math-bigint at
2225 rt.cpan.org", or through the web interface at
2226 <https://rt.cpan.org/Ticket/Create.html?Queue=Math-BigInt> (requires
2227 login). We will be notified, and then you'll automatically be notified
2228 of progress on your bug as I make changes.
2229
2231 You can find documentation for this module with the perldoc command.
2232 perldoc Math::BigInt
2234 You can also look for information at:
2236 · RT: CPAN's request tracker
2238 <https://rt.cpan.org/Public/Dist/Display.html?Name=Math-BigInt>
2240 · AnnoCPAN: Annotated CPAN documentation
2242 <http://annocpan.org/dist/Math-BigInt>
2244 · CPAN Ratings
2246 <https://cpanratings.perl.org/dist/Math-BigInt>
2248 · MetaCPAN
2250 <https://metacpan.org/release/Math-BigInt>
2252 · CPAN Testers Matrix
2254 <http://matrix.cpantesters.org/?dist=Math-BigInt>
2256 · The Bignum mailing list
2258 · Post to mailing list
2260 "bignum at lists.scsys.co.uk"
2262 · View mailing list
2264 <http://lists.scsys.co.uk/pipermail/bignum/>
2266 · Subscribe/Unsubscribe
2268 <http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/bignum>
2270
2272 This program is free software; you may redistribute it and/or modify it
2273 under the same terms as Perl itself.
2274
2276 Math::BigFloat and Math::BigRat as well as the backends
2277 Math::BigInt::FastCalc, Math::BigInt::GMP, and Math::BigInt::Pari.
2278 The pragmas bignum, bigint and bigrat also might be of interest because
2280 they solve the autoupgrading/downgrading issue, at least partly.
2281
2283 · Mark Biggar, overloaded interface by Ilya Zakharevich, 1996-2001.
2284 · Completely rewritten by Tels <http://bloodgate.com>, 2001-2008.
2286 · Florian Ragwitz <flora@cpan.org>, 2010.
2288 · Peter John Acklam <pjacklam@online.no>, 2011-.
2290 Many people contributed in one or more ways to the final beast, see the
2292 file CREDITS for an (incomplete) list. If you miss your name, please
2293 drop me a mail. Thank you!
2294perl v5.30.1 2020-01-30 Math::BigInt(3)