1Math::BigInt(3) User Contributed Perl Documentation Math::BigInt(3)
2
6 Math::BigInt - arbitrary size integer 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 # to warn if Math::BigInt::GMP cannot be found, use
17 use Math::BigInt lib => 'GMP';
18 # to suppress the warning if Math::BigInt::GMP cannot be found, use
20 # use Math::BigInt try => 'GMP';
21 # to die if Math::BigInt::GMP cannot be found, use
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->from_base_num([1, 0], 2); # from any base
52 $x = Math::BigInt->bzero(); # create a +0
53 $x = Math::BigInt->bone(); # create a +1
54 $x = Math::BigInt->bone('-'); # create a -1
55 $x = Math::BigInt->binf(); # create a +inf
56 $x = Math::BigInt->binf('-'); # create a -inf
57 $x = Math::BigInt->bnan(); # create a Not-A-Number
58 $x = Math::BigInt->bpi(); # returns pi
59 $y = $x->copy(); # make a copy (unlike $y = $x)
61 $y = $x->as_int(); # return as a Math::BigInt
62 # Boolean methods (these don't modify the invocand)
64 $x->is_zero(); # if $x is 0
66 $x->is_one(); # if $x is +1
67 $x->is_one("+"); # ditto
68 $x->is_one("-"); # if $x is -1
69 $x->is_inf(); # if $x is +inf or -inf
70 $x->is_inf("+"); # if $x is +inf
71 $x->is_inf("-"); # if $x is -inf
72 $x->is_nan(); # if $x is NaN
73 $x->is_positive(); # if $x > 0
75 $x->is_pos(); # ditto
76 $x->is_negative(); # if $x < 0
77 $x->is_neg(); # ditto
78 $x->is_odd(); # if $x is odd
80 $x->is_even(); # if $x is even
81 $x->is_int(); # if $x is an integer
82 # Comparison methods
84 $x->bcmp($y); # compare numbers (undef, < 0, == 0, > 0)
86 $x->bacmp($y); # compare absolutely (undef, < 0, == 0, > 0)
87 $x->beq($y); # true if and only if $x == $y
88 $x->bne($y); # true if and only if $x != $y
89 $x->blt($y); # true if and only if $x < $y
90 $x->ble($y); # true if and only if $x <= $y
91 $x->bgt($y); # true if and only if $x > $y
92 $x->bge($y); # true if and only if $x >= $y
93 # Arithmetic methods
95 $x->bneg(); # negation
97 $x->babs(); # absolute value
98 $x->bsgn(); # sign function (-1, 0, 1, or NaN)
99 $x->bnorm(); # normalize (no-op)
100 $x->binc(); # increment $x by 1
101 $x->bdec(); # decrement $x by 1
102 $x->badd($y); # addition (add $y to $x)
103 $x->bsub($y); # subtraction (subtract $y from $x)
104 $x->bmul($y); # multiplication (multiply $x by $y)
105 $x->bmuladd($y,$z); # $x = $x * $y + $z
106 $x->bdiv($y); # division (floored), set $x to quotient
107 # return (quo,rem) or quo if scalar
108 $x->btdiv($y); # division (truncated), set $x to quotient
109 # return (quo,rem) or quo if scalar
110 $x->bmod($y); # modulus (x % y)
111 $x->btmod($y); # modulus (truncated)
112 $x->bmodinv($mod); # modular multiplicative inverse
113 $x->bmodpow($y,$mod); # modular exponentiation (($x ** $y) % $mod)
114 $x->bpow($y); # power of arguments (x ** y)
115 $x->blog(); # logarithm of $x to base e (Euler's number)
116 $x->blog($base); # logarithm of $x to base $base (e.g., base 2)
117 $x->bexp(); # calculate e ** $x where e is Euler's number
118 $x->bnok($y); # x over y (binomial coefficient n over k)
119 $x->buparrow($n, $y); # Knuth's up-arrow notation
120 $x->backermann($y); # the Ackermann function
121 $x->bsin(); # sine
122 $x->bcos(); # cosine
123 $x->batan(); # inverse tangent
124 $x->batan2($y); # two-argument inverse tangent
125 $x->bsqrt(); # calculate square root
126 $x->broot($y); # $y'th root of $x (e.g. $y == 3 => cubic root)
127 $x->bfac(); # factorial of $x (1*2*3*4*..$x)
128 $x->bdfac(); # double factorial of $x ($x*($x-2)*($x-4)*...)
129 $x->btfac(); # triple factorial of $x ($x*($x-3)*($x-6)*...)
130 $x->bmfac($k); # $k'th multi-factorial of $x ($x*($x-$k)*...)
131 $x->blsft($n); # left shift $n places in base 2
133 $x->blsft($n,$b); # left shift $n places in base $b
134 # returns (quo,rem) or quo (scalar context)
135 $x->brsft($n); # right shift $n places in base 2
136 $x->brsft($n,$b); # right shift $n places in base $b
137 # returns (quo,rem) or quo (scalar context)
138 # Bitwise methods
140 $x->band($y); # bitwise and
142 $x->bior($y); # bitwise inclusive or
143 $x->bxor($y); # bitwise exclusive or
144 $x->bnot(); # bitwise not (two's complement)
145 # Rounding methods
147 $x->round($A,$P,$mode); # round to accuracy or precision using
148 # rounding mode $mode
149 $x->bround($n); # accuracy: preserve $n digits
150 $x->bfround($n); # $n > 0: round to $nth digit left of dec. point
151 # $n < 0: round to $nth digit right of dec. point
152 $x->bfloor(); # round towards minus infinity
153 $x->bceil(); # round towards plus infinity
154 $x->bint(); # round towards zero
155 # Other mathematical methods
157 $x->bgcd($y); # greatest common divisor
159 $x->blcm($y); # least common multiple
160 # Object property methods (do not modify the invocand)
162 $x->sign(); # the sign, either +, - or NaN
164 $x->digit($n); # the nth digit, counting from the right
165 $x->digit(-$n); # the nth digit, counting from the left
166 $x->length(); # return number of digits in number
167 ($xl,$f) = $x->length(); # length of number and length of fraction
168 # part, latter is always 0 digits long
169 # for Math::BigInt objects
170 $x->mantissa(); # return (signed) mantissa as a Math::BigInt
171 $x->exponent(); # return exponent as a Math::BigInt
172 $x->parts(); # return (mantissa,exponent) as a Math::BigInt
173 $x->sparts(); # mantissa and exponent (as integers)
174 $x->nparts(); # mantissa and exponent (normalised)
175 $x->eparts(); # mantissa and exponent (engineering notation)
176 $x->dparts(); # integer and fraction part
177 $x->fparts(); # numerator and denominator
178 $x->numerator(); # numerator
179 $x->denominator(); # denominator
180 # Conversion methods (do not modify the invocand)
182 $x->bstr(); # decimal notation, possibly zero padded
184 $x->bsstr(); # string in scientific notation with integers
185 $x->bnstr(); # string in normalized notation
186 $x->bestr(); # string in engineering notation
187 $x->bdstr(); # string in decimal notation
188 $x->to_hex(); # as signed hexadecimal string
190 $x->to_bin(); # as signed binary string
191 $x->to_oct(); # as signed octal string
192 $x->to_bytes(); # as byte string
193 $x->to_base($b); # as string in any base
194 $x->to_base_num($b); # as array of integers in any base
195 $x->as_hex(); # as signed hexadecimal string with prefixed 0x
197 $x->as_bin(); # as signed binary string with prefixed 0b
198 $x->as_oct(); # as signed octal string with prefixed 0
199 # Other conversion methods
201 $x->numify(); # return as scalar (might overflow or underflow)
203
205 Math::BigInt provides support for arbitrary precision integers.
206 Overloading is also provided for Perl operators.
207 Input
209 Input values to these routines may be any scalar number or string that
210 looks like a number and represents an integer. Anything that is
211 accepted by Perl as a literal numeric constant should be accepted by
212 this module, except that finite non-integers return NaN.
213 • Leading and trailing whitespace is ignored.
215 • Leading zeros are ignored, except for floating point numbers with a
217 binary exponent, in which case the number is interpreted as an
218 octal floating point number. For example, "01.4p+0" gives 1.5,
219 "00.4p+0" gives 0.5, but "0.4p+0" gives a NaN. And while "0377"
220 gives 255, "0377p0" gives 255.
221 • If the string has a "0x" or "0X" prefix, it is interpreted as a
223 hexadecimal number.
224 • If the string has a "0o" or "0O" prefix, it is interpreted as an
226 octal number. A floating point literal with a "0" prefix is also
227 interpreted as an octal number.
228 • If the string has a "0b" or "0B" prefix, it is interpreted as a
230 binary number.
231 • Underline characters are allowed in the same way as they are
233 allowed in literal numerical constants.
234 • If the string can not be interpreted, or does not represent a
236 finite integer, NaN is returned.
237 • For hexadecimal, octal, and binary floating point numbers, the
239 exponent must be separated from the significand (mantissa) by the
240 letter "p" or "P", not "e" or "E" as with decimal numbers.
241 Some examples of valid string input
243 Input string Resulting value
245 123 123
247 1.23e2 123
248 12300e-2 123
249 67_538_754 67538754
251 -4_5_6.7_8_9e+0_1_0 -4567890000000
252 0x13a 314
254 0x13ap0 314
255 0x1.3ap+8 314
256 0x0.00013ap+24 314
257 0x13a000p-12 314
258 0o472 314
260 0o1.164p+8 314
261 0o0.0001164p+20 314
262 0o1164000p-10 314
263 0472 472 Note!
265 01.164p+8 314
266 00.0001164p+20 314
267 01164000p-10 314
268 0b100111010 314
270 0b1.0011101p+8 314
271 0b0.00010011101p+12 314
272 0b100111010000p-3 314
273 Input given as scalar numbers might lose precision. Quote your input to
275 ensure that no digits are lost:
276 $x = Math::BigInt->new( 56789012345678901234 ); # bad
278 $x = Math::BigInt->new('56789012345678901234'); # good
279 Currently, "Math::BigInt-"new()> (no input argument) and
281 "Math::BigInt-"new("")> return 0. This might change in the future, so
282 always use the following explicit forms to get a zero:
283 $zero = Math::BigInt->bzero();
285 Output
287 Output values are usually Math::BigInt objects.
288 Boolean operators "is_zero()", "is_one()", "is_inf()", etc. return true
290 or false.
291 Comparison operators "bcmp()" and "bacmp()") return -1, 0, 1, or undef.
293
295 Configuration methods
296 Each of the methods below (except config(), accuracy() and precision())
297 accepts three additional parameters. These arguments $A, $P and $R are
298 "accuracy", "precision" and "round_mode". Please see the section about
299 "ACCURACY and PRECISION" for more information.
300 Setting a class variable effects all object instance that are created
302 afterwards.
303 accuracy()
305 Math::BigInt->accuracy(5); # set class accuracy
306 $x->accuracy(5); # set instance accuracy
307 $A = Math::BigInt->accuracy(); # get class accuracy
309 $A = $x->accuracy(); # get instance accuracy
310 Set or get the accuracy, i.e., the number of significant digits.
312 The accuracy must be an integer. If the accuracy is set to "undef",
313 no rounding is done.
314 Alternatively, one can round the results explicitly using one of
316 "round()", "bround()" or "bfround()" or by passing the desired
317 accuracy to the method as an additional parameter:
318 my $x = Math::BigInt->new(30000);
320 my $y = Math::BigInt->new(7);
321 print scalar $x->copy()->bdiv($y, 2); # prints 4300
322 print scalar $x->copy()->bdiv($y)->bround(2); # prints 4300
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->accuracy(4); # set class accuracy to 4
329 $x = Math::BigInt->new(1234567); # $x is rounded automatically
330 print "$x $y"; # prints "1235000 1234567"
331 print $x->accuracy(); # prints "4"
333 print $y->accuracy(); # also prints "4", since
334 # class accuracy is 4
335 Math::BigInt->accuracy(5); # set class accuracy to 5
337 print $x->accuracy(); # prints "4", since instance
338 # accuracy is 4
339 print $y->accuracy(); # prints "5", since no instance
340 # accuracy, and class accuracy is 5
341 Note: Each class has it's own globals separated from Math::BigInt,
343 but it is possible to subclass Math::BigInt and make the globals of
344 the subclass aliases to the ones from Math::BigInt.
345 precision()
347 Math::BigInt->precision(-2); # set class precision
348 $x->precision(-2); # set instance precision
349 $P = Math::BigInt->precision(); # get class precision
351 $P = $x->precision(); # get instance precision
352 Set or get the precision, i.e., the place to round relative to the
354 decimal point. The precision must be a integer. Setting the
355 precision to $P means that each number is rounded up or down,
356 depending on the rounding mode, to the nearest multiple of 10**$P.
357 If the precision is set to "undef", no rounding is done.
358 You might want to use "accuracy()" instead. With "accuracy()" you
360 set the number of digits each result should have, with
361 "precision()" you set the place where to round.
362 Please see the section about "ACCURACY and PRECISION" for further
364 details.
365 $y = Math::BigInt->new(1234567); # $y is not rounded
367 Math::BigInt->precision(4); # set class precision to 4
368 $x = Math::BigInt->new(1234567); # $x is rounded automatically
369 print $x; # prints "1230000"
370 Note: Each class has its own globals separated from Math::BigInt,
372 but it is possible to subclass Math::BigInt and make the globals of
373 the subclass aliases to the ones from Math::BigInt.
374 div_scale()
376 Set/get the fallback accuracy. This is the accuracy used when
377 neither accuracy nor precision is set explicitly. It is used when a
378 computation might otherwise attempt to return an infinite number of
379 digits.
380 round_mode()
382 Set/get the rounding mode.
383 upgrade()
385 Set/get the class for upgrading. When a computation might result in
386 a non-integer, the operands are upgraded to this class. This is
387 used for instance by bignum. The default is "undef", i.e., no
388 upgrading.
389 # with no upgrading
391 $x = Math::BigInt->new(12);
392 $y = Math::BigInt->new(5);
393 print $x / $y, "\n"; # 2 as a Math::BigInt
394 # with upgrading to Math::BigFloat
396 Math::BigInt -> upgrade("Math::BigFloat");
397 print $x / $y, "\n"; # 2.4 as a Math::BigFloat
398 # with upgrading to Math::BigRat (after loading Math::BigRat)
400 Math::BigInt -> upgrade("Math::BigRat");
401 print $x / $y, "\n"; # 12/5 as a Math::BigRat
402 downgrade()
404 Set/get the class for downgrading. The default is "undef", i.e., no
405 downgrading. Downgrading is not done by Math::BigInt.
406 modify()
408 $x->modify('bpowd');
409 This method returns 0 if the object can be modified with the given
411 operation, or 1 if not.
412 This is used for instance by Math::BigInt::Constant.
414 config()
416 Math::BigInt->config("trap_nan" => 1); # set
417 $accu = Math::BigInt->config("accuracy"); # get
418 Set or get class variables. Read-only parameters are marked as RO.
420 Read-write parameters are marked as RW. The following parameters
421 are supported.
422 Parameter RO/RW Description
424 Example
425 ============================================================
426 lib RO Name of the math backend library
427 Math::BigInt::Calc
428 lib_version RO Version of the math backend library
429 0.30
430 class RO The class of config you just called
431 Math::BigRat
432 version RO version number of the class you used
433 0.10
434 upgrade RW To which class numbers are upgraded
435 undef
436 downgrade RW To which class numbers are downgraded
437 undef
438 precision RW Global precision
439 undef
440 accuracy RW Global accuracy
441 undef
442 round_mode RW Global round mode
443 even
444 div_scale RW Fallback accuracy for division etc.
445 40
446 trap_nan RW Trap NaNs
447 undef
448 trap_inf RW Trap +inf/-inf
449 undef
450 Constructor methods
452 new()
453 $x = Math::BigInt->new($str,$A,$P,$R);
454 Creates a new Math::BigInt object from a scalar or another
456 Math::BigInt object. The input is accepted as decimal, hexadecimal
457 (with leading '0x'), octal (with leading ('0o') or binary (with
458 leading '0b').
459 See "Input" for more info on accepted input formats.
461 from_dec()
463 $x = Math::BigInt->from_dec("314159"); # input is decimal
464 Interpret input as a decimal. It is equivalent to new(), but does
466 not accept anything but strings representing finite, decimal
467 numbers.
468 from_hex()
470 $x = Math::BigInt->from_hex("0xcafe"); # input is hexadecimal
471 Interpret input as a hexadecimal string. A "0x" or "x" prefix is
473 optional. A single underscore character may be placed right after
474 the prefix, if present, or between any two digits. If the input is
475 invalid, a NaN is returned.
476 from_oct()
478 $x = Math::BigInt->from_oct("0775"); # input is octal
479 Interpret the input as an octal string and return the corresponding
481 value. A "0" (zero) prefix is optional. A single underscore
482 character may be placed right after the prefix, if present, or
483 between any two digits. If the input is invalid, a NaN is returned.
484 from_bin()
486 $x = Math::BigInt->from_bin("0b10011"); # input is binary
487 Interpret the input as a binary string. A "0b" or "b" prefix is
489 optional. A single underscore character may be placed right after
490 the prefix, if present, or between any two digits. If the input is
491 invalid, a NaN is returned.
492 from_bytes()
494 $x = Math::BigInt->from_bytes("\xf3\x6b"); # $x = 62315
495 Interpret the input as a byte string, assuming big endian byte
497 order. The output is always a non-negative, finite integer.
498 In some special cases, from_bytes() matches the conversion done by
500 unpack():
501 $b = "\x4e"; # one char byte string
503 $x = Math::BigInt->from_bytes($b); # = 78
504 $y = unpack "C", $b; # ditto, but scalar
505 $b = "\xf3\x6b"; # two char byte string
507 $x = Math::BigInt->from_bytes($b); # = 62315
508 $y = unpack "S>", $b; # ditto, but scalar
509 $b = "\x2d\xe0\x49\xad"; # four char byte string
511 $x = Math::BigInt->from_bytes($b); # = 769673645
512 $y = unpack "L>", $b; # ditto, but scalar
513 $b = "\x2d\xe0\x49\xad\x2d\xe0\x49\xad"; # eight char byte string
515 $x = Math::BigInt->from_bytes($b); # = 3305723134637787565
516 $y = unpack "Q>", $b; # ditto, but scalar
517 from_base()
519 Given a string, a base, and an optional collation sequence,
520 interpret the string as a number in the given base. The collation
521 sequence describes the value of each character in the string.
522 If a collation sequence is not given, a default collation sequence
524 is used. If the base is less than or equal to 36, the collation
525 sequence is the string consisting of the 36 characters "0" to "9"
526 and "A" to "Z". In this case, the letter case in the input is
527 ignored. If the base is greater than 36, and smaller than or equal
528 to 62, the collation sequence is the string consisting of the 62
529 characters "0" to "9", "A" to "Z", and "a" to "z". A base larger
530 than 62 requires the collation sequence to be specified explicitly.
531 These examples show standard binary, octal, and hexadecimal
533 conversion. All cases return 250.
534 $x = Math::BigInt->from_base("11111010", 2);
536 $x = Math::BigInt->from_base("372", 8);
537 $x = Math::BigInt->from_base("fa", 16);
538 When the base is less than or equal to 36, and no collation
540 sequence is given, the letter case is ignored, so both of these
541 also return 250:
542 $x = Math::BigInt->from_base("6Y", 16);
544 $x = Math::BigInt->from_base("6y", 16);
545 When the base greater than 36, and no collation sequence is given,
547 the default collation sequence contains both uppercase and
548 lowercase letters, so the letter case in the input is not ignored:
549 $x = Math::BigInt->from_base("6S", 37); # $x is 250
551 $x = Math::BigInt->from_base("6s", 37); # $x is 276
552 $x = Math::BigInt->from_base("121", 3); # $x is 16
553 $x = Math::BigInt->from_base("XYZ", 36); # $x is 44027
554 $x = Math::BigInt->from_base("Why", 42); # $x is 58314
555 The collation sequence can be any set of unique characters. These
557 two cases are equivalent
558 $x = Math::BigInt->from_base("100", 2, "01"); # $x is 4
560 $x = Math::BigInt->from_base("|--", 2, "-|"); # $x is 4
561 from_base_num()
563 Returns a new Math::BigInt object given an array of values and a
564 base. This method is equivalent to "from_base()", but works on
565 numbers in an array rather than characters in a string. Unlike
566 "from_base()", all input values may be arbitrarily large.
567 $x = Math::BigInt->from_base_num([1, 1, 0, 1], 2) # $x is 13
569 $x = Math::BigInt->from_base_num([3, 125, 39], 128) # $x is 65191
570 bzero()
572 $x = Math::BigInt->bzero();
573 $x->bzero();
574 Returns a new Math::BigInt object representing zero. If used as an
576 instance method, assigns the value to the invocand.
577 bone()
579 $x = Math::BigInt->bone(); # +1
580 $x = Math::BigInt->bone("+"); # +1
581 $x = Math::BigInt->bone("-"); # -1
582 $x->bone(); # +1
583 $x->bone("+"); # +1
584 $x->bone('-'); # -1
585 Creates a new Math::BigInt object representing one. The optional
587 argument is either '-' or '+', indicating whether you want plus one
588 or minus one. If used as an instance method, assigns the value to
589 the invocand.
590 binf()
592 $x = Math::BigInt->binf($sign);
593 Creates a new Math::BigInt object representing infinity. The
595 optional argument is either '-' or '+', indicating whether you want
596 infinity or minus infinity. If used as an instance method, assigns
597 the value to the invocand.
598 $x->binf();
600 $x->binf('-');
601 bnan()
603 $x = Math::BigInt->bnan();
604 Creates a new Math::BigInt object representing NaN (Not A Number).
606 If used as an instance method, assigns the value to the invocand.
607 $x->bnan();
609 bpi()
611 $x = Math::BigInt->bpi(100); # 3
612 $x->bpi(100); # 3
613 Creates a new Math::BigInt object representing PI. If used as an
615 instance method, assigns the value to the invocand. With
616 Math::BigInt this always returns 3.
617 If upgrading is in effect, returns PI, rounded to N digits with the
619 current rounding mode:
620 use Math::BigFloat;
622 use Math::BigInt upgrade => "Math::BigFloat";
623 print Math::BigInt->bpi(3), "\n"; # 3.14
624 print Math::BigInt->bpi(100), "\n"; # 3.1415....
625 copy()
627 $x->copy(); # make a true copy of $x (unlike $y = $x)
628 as_int()
630 as_number()
631 These methods are called when Math::BigInt encounters an object it
632 doesn't know how to handle. For instance, assume $x is a
633 Math::BigInt, or subclass thereof, and $y is defined, but not a
634 Math::BigInt, or subclass thereof. If you do
635 $x -> badd($y);
637 $y needs to be converted into an object that $x can deal with. This
639 is done by first checking if $y is something that $x might be
640 upgraded to. If that is the case, no further attempts are made. The
641 next is to see if $y supports the method "as_int()". If it does,
642 "as_int()" is called, but if it doesn't, the next thing is to see
643 if $y supports the method "as_number()". If it does, "as_number()"
644 is called. The method "as_int()" (and "as_number()") is expected to
645 return either an object that has the same class as $x, a subclass
646 thereof, or a string that "ref($x)->new()" can parse to create an
647 object.
648 "as_number()" is an alias to "as_int()". "as_number" was introduced
650 in v1.22, while "as_int()" was introduced in v1.68.
651 In Math::BigInt, "as_int()" has the same effect as "copy()".
653 Boolean methods
655 None of these methods modify the invocand object.
656 is_zero()
658 $x->is_zero(); # true if $x is 0
659 Returns true if the invocand is zero and false otherwise.
661 is_one( [ SIGN ])
663 $x->is_one(); # true if $x is +1
664 $x->is_one("+"); # ditto
665 $x->is_one("-"); # true if $x is -1
666 Returns true if the invocand is one and false otherwise.
668 is_finite()
670 $x->is_finite(); # true if $x is not +inf, -inf or NaN
671 Returns true if the invocand is a finite number, i.e., it is
673 neither +inf, -inf, nor NaN.
674 is_inf( [ SIGN ] )
676 $x->is_inf(); # true if $x is +inf
677 $x->is_inf("+"); # ditto
678 $x->is_inf("-"); # true if $x is -inf
679 Returns true if the invocand is infinite and false otherwise.
681 is_nan()
683 $x->is_nan(); # true if $x is NaN
684 is_positive()
686 is_pos()
687 $x->is_positive(); # true if > 0
688 $x->is_pos(); # ditto
689 Returns true if the invocand is positive and false otherwise. A
691 "NaN" is neither positive nor negative.
692 is_negative()
694 is_neg()
695 $x->is_negative(); # true if < 0
696 $x->is_neg(); # ditto
697 Returns true if the invocand is negative and false otherwise. A
699 "NaN" is neither positive nor negative.
700 is_non_positive()
702 $x->is_non_positive(); # true if <= 0
703 Returns true if the invocand is negative or zero.
705 is_non_negative()
707 $x->is_non_negative(); # true if >= 0
708 Returns true if the invocand is positive or zero.
710 is_odd()
712 $x->is_odd(); # true if odd, false for even
713 Returns true if the invocand is odd and false otherwise. "NaN",
715 "+inf", and "-inf" are neither odd nor even.
716 is_even()
718 $x->is_even(); # true if $x is even
719 Returns true if the invocand is even and false otherwise. "NaN",
721 "+inf", "-inf" are not integers and are neither odd nor even.
722 is_int()
724 $x->is_int(); # true if $x is an integer
725 Returns true if the invocand is an integer and false otherwise.
727 "NaN", "+inf", "-inf" are not integers.
728 Comparison methods
730 None of these methods modify the invocand object. Note that a "NaN" is
731 neither less than, greater than, or equal to anything else, even a
732 "NaN".
733 bcmp()
735 $x->bcmp($y);
736 Returns -1, 0, 1 depending on whether $x is less than, equal to, or
738 grater than $y. Returns undef if any operand is a NaN.
739 bacmp()
741 $x->bacmp($y);
742 Returns -1, 0, 1 depending on whether the absolute value of $x is
744 less than, equal to, or grater than the absolute value of $y.
745 Returns undef if any operand is a NaN.
746 beq()
748 $x -> beq($y);
749 Returns true if and only if $x is equal to $y, and false otherwise.
751 bne()
753 $x -> bne($y);
754 Returns true if and only if $x is not equal to $y, and false
756 otherwise.
757 blt()
759 $x -> blt($y);
760 Returns true if and only if $x is equal to $y, and false otherwise.
762 ble()
764 $x -> ble($y);
765 Returns true if and only if $x is less than or equal to $y, and
767 false otherwise.
768 bgt()
770 $x -> bgt($y);
771 Returns true if and only if $x is greater than $y, and false
773 otherwise.
774 bge()
776 $x -> bge($y);
777 Returns true if and only if $x is greater than or equal to $y, and
779 false otherwise.
780 Arithmetic methods
782 These methods modify the invocand object and returns it.
783 bneg()
785 $x->bneg();
786 Negate the number, e.g. change the sign between '+' and '-', or
788 between '+inf' and '-inf', respectively. Does nothing for NaN or
789 zero.
790 babs()
792 $x->babs();
793 Set the number to its absolute value, e.g. change the sign from '-'
795 to '+' and from '-inf' to '+inf', respectively. Does nothing for
796 NaN or positive numbers.
797 bsgn()
799 $x->bsgn();
800 Signum function. Set the number to -1, 0, or 1, depending on
802 whether the number is negative, zero, or positive, respectively.
803 Does not modify NaNs.
804 bnorm()
806 $x->bnorm(); # normalize (no-op)
807 Normalize the number. This is a no-op and is provided only for
809 backwards compatibility.
810 binc()
812 $x->binc(); # increment x by 1
813 bdec()
815 $x->bdec(); # decrement x by 1
816 badd()
818 $x->badd($y); # addition (add $y to $x)
819 bsub()
821 $x->bsub($y); # subtraction (subtract $y from $x)
822 bmul()
824 $x->bmul($y); # multiplication (multiply $x by $y)
825 bmuladd()
827 $x->bmuladd($y,$z);
828 Multiply $x by $y, and then add $z to the result,
830 This method was added in v1.87 of Math::BigInt (June 2007).
832 bdiv()
834 $x->bdiv($y); # divide, set $x to quotient
835 Divides $x by $y by doing floored division (F-division), where the
837 quotient is the floored (rounded towards negative infinity)
838 quotient of the two operands. In list context, returns the
839 quotient and the remainder. The remainder is either zero or has the
840 same sign as the second operand. In scalar context, only the
841 quotient is returned.
842 The quotient is always the greatest integer less than or equal to
844 the real-valued quotient of the two operands, and the remainder
845 (when it is non-zero) always has the same sign as the second
846 operand; so, for example,
847 1 / 4 => ( 0, 1)
849 1 / -4 => (-1, -3)
850 -3 / 4 => (-1, 1)
851 -3 / -4 => ( 0, -3)
852 -11 / 2 => (-5, 1)
853 11 / -2 => (-5, -1)
854 The behavior of the overloaded operator % agrees with the behavior
856 of Perl's built-in % operator (as documented in the perlop
857 manpage), and the equation
858 $x == ($x / $y) * $y + ($x % $y)
860 holds true for any finite $x and finite, non-zero $y.
862 Perl's "use integer" might change the behaviour of % and / for
864 scalars. This is because under 'use integer' Perl does what the
865 underlying C library thinks is right, and this varies. However,
866 "use integer" does not change the way things are done with
867 Math::BigInt objects.
868 btdiv()
870 $x->btdiv($y); # divide, set $x to quotient
871 Divides $x by $y by doing truncated division (T-division), where
873 quotient is the truncated (rouneded towards zero) quotient of the
874 two operands. In list context, returns the quotient and the
875 remainder. The remainder is either zero or has the same sign as the
876 first operand. In scalar context, only the quotient is returned.
877 bmod()
879 $x->bmod($y); # modulus (x % y)
880 Returns $x modulo $y, i.e., the remainder after floored division
882 (F-division). This method is like Perl's % operator. See "bdiv()".
883 btmod()
885 $x->btmod($y); # modulus
886 Returns the remainer after truncated division (T-division). See
888 "btdiv()".
889 bmodinv()
891 $x->bmodinv($mod); # modular multiplicative inverse
892 Returns the multiplicative inverse of $x modulo $mod. If
894 $y = $x -> copy() -> bmodinv($mod)
896 then $y is the number closest to zero, and with the same sign as
898 $mod, satisfying
899 ($x * $y) % $mod = 1 % $mod
901 If $x and $y are non-zero, they must be relative primes, i.e.,
903 "bgcd($y, $mod)==1". '"NaN"' is returned when no modular
904 multiplicative inverse exists.
905 bmodpow()
907 $num->bmodpow($exp,$mod); # modular exponentiation
908 # ($num**$exp % $mod)
909 Returns the value of $num taken to the power $exp in the modulus
911 $mod using binary exponentiation. "bmodpow" is far superior to
912 writing
913 $num ** $exp % $mod
915 because it is much faster - it reduces internal variables into the
917 modulus whenever possible, so it operates on smaller numbers.
918 "bmodpow" also supports negative exponents.
920 bmodpow($num, -1, $mod)
922 is exactly equivalent to
924 bmodinv($num, $mod)
926 bpow()
928 $x->bpow($y); # power of arguments (x ** y)
929 "bpow()" (and the rounding functions) now modifies the first
931 argument and returns it, unlike the old code which left it alone
932 and only returned the result. This is to be consistent with
933 "badd()" etc. The first three modifies $x, the last one won't:
934 print bpow($x,$i),"\n"; # modify $x
936 print $x->bpow($i),"\n"; # ditto
937 print $x **= $i,"\n"; # the same
938 print $x ** $i,"\n"; # leave $x alone
939 The form "$x **= $y" is faster than "$x = $x ** $y;", though.
941 blog()
943 $x->blog($base, $accuracy); # logarithm of x to the base $base
944 If $base is not defined, Euler's number (e) is used:
946 print $x->blog(undef, 100); # log(x) to 100 digits
948 bexp()
950 $x->bexp($accuracy); # calculate e ** X
951 Calculates the expression "e ** $x" where "e" is Euler's number.
953 This method was added in v1.82 of Math::BigInt (April 2007).
955 See also "blog()".
957 bnok()
959 $x->bnok($y); # x over y (binomial coefficient n over k)
960 Calculates the binomial coefficient n over k, also called the
962 "choose" function, which is
963 ( n ) n!
965 | | = --------
966 ( k ) k!(n-k)!
967 when n and k are non-negative. This method implements the full
969 Kronenburg extension (Kronenburg, M.J. "The Binomial Coefficient
970 for Negative Arguments." 18 May 2011.
971 http://arxiv.org/abs/1105.3689/) illustrated by the following
972 pseudo-code:
973 if n >= 0 and k >= 0:
975 return binomial(n, k)
976 if k >= 0:
977 return (-1)^k*binomial(-n+k-1, k)
978 if k <= n:
979 return (-1)^(n-k)*binomial(-k-1, n-k)
980 else
981 return 0
982 The behaviour is identical to the behaviour of the Maple and
984 Mathematica function for negative integers n, k.
985 buparrow()
987 uparrow()
988 $a -> buparrow($n, $b); # modifies $a
989 $x = $a -> uparrow($n, $b); # does not modify $a
990 This method implements Knuth's up-arrow notation, where $n is a
992 non-negative integer representing the number of up-arrows. $n = 0
993 gives multiplication, $n = 1 gives exponentiation, $n = 2 gives
994 tetration, $n = 3 gives hexation etc. The following illustrates the
995 relation between the first values of $n.
996 See <https://en.wikipedia.org/wiki/Knuth%27s_up-arrow_notation>.
998 backermann()
1000 ackermann()
1001 $m -> backermann($n); # modifies $a
1002 $x = $m -> ackermann($n); # does not modify $a
1003 This method implements the Ackermann function:
1005 / n + 1 if m = 0
1007 A(m, n) = | A(m-1, 1) if m > 0 and n = 0
1008 \ A(m-1, A(m, n-1)) if m > 0 and n > 0
1009 Its value grows rapidly, even for small inputs. For example, A(4,
1011 2) is an integer of 19729 decimal digits.
1012 See https://en.wikipedia.org/wiki/Ackermann_function
1014 bsin()
1016 my $x = Math::BigInt->new(1);
1017 print $x->bsin(100), "\n";
1018 Calculate the sine of $x, modifying $x in place.
1020 In Math::BigInt, unless upgrading is in effect, the result is
1022 truncated to an integer.
1023 This method was added in v1.87 of Math::BigInt (June 2007).
1025 bcos()
1027 my $x = Math::BigInt->new(1);
1028 print $x->bcos(100), "\n";
1029 Calculate the cosine of $x, modifying $x in place.
1031 In Math::BigInt, unless upgrading is in effect, the result is
1033 truncated to an integer.
1034 This method was added in v1.87 of Math::BigInt (June 2007).
1036 batan()
1038 my $x = Math::BigFloat->new(0.5);
1039 print $x->batan(100), "\n";
1040 Calculate the arcus tangens of $x, modifying $x in place.
1042 In Math::BigInt, unless upgrading is in effect, the result is
1044 truncated to an integer.
1045 This method was added in v1.87 of Math::BigInt (June 2007).
1047 batan2()
1049 my $x = Math::BigInt->new(1);
1050 my $y = Math::BigInt->new(1);
1051 print $y->batan2($x), "\n";
1052 Calculate the arcus tangens of $y divided by $x, modifying $y in
1054 place.
1055 In Math::BigInt, unless upgrading is in effect, the result is
1057 truncated to an integer.
1058 This method was added in v1.87 of Math::BigInt (June 2007).
1060 bsqrt()
1062 $x->bsqrt(); # calculate square root
1063 "bsqrt()" returns the square root truncated to an integer.
1065 If you want a better approximation of the square root, then use:
1067 $x = Math::BigFloat->new(12);
1069 Math::BigFloat->precision(0);
1070 Math::BigFloat->round_mode('even');
1071 print $x->copy->bsqrt(),"\n"; # 4
1072 Math::BigFloat->precision(2);
1074 print $x->bsqrt(),"\n"; # 3.46
1075 print $x->bsqrt(3),"\n"; # 3.464
1076 broot()
1078 $x->broot($N);
1079 Calculates the N'th root of $x.
1081 bfac()
1083 $x->bfac(); # factorial of $x
1084 Returns the factorial of $x, i.e., $x*($x-1)*($x-2)*...*2*1, the
1086 product of all positive integers up to and including $x. $x must be
1087 > -1. The factorial of N is commonly written as N!, or N!1, when
1088 using the multifactorial notation.
1089 bdfac()
1091 $x->bdfac(); # double factorial of $x
1092 Returns the double factorial of $x, i.e., $x*($x-2)*($x-4)*... $x
1094 must be > -2. The double factorial of N is commonly written as N!!,
1095 or N!2, when using the multifactorial notation.
1096 btfac()
1098 $x->btfac(); # triple factorial of $x
1099 Returns the triple factorial of $x, i.e., $x*($x-3)*($x-6)*... $x
1101 must be > -3. The triple factorial of N is commonly written as
1102 N!!!, or N!3, when using the multifactorial notation.
1103 bmfac()
1105 $x->bmfac($k); # $k'th multifactorial of $x
1106 Returns the multi-factorial of $x, i.e., $x*($x-$k)*($x-2*$k)*...
1108 $x must be > -$k. The multi-factorial of N is commonly written as
1109 N!K.
1110 bfib()
1112 $F = $n->bfib(); # a single Fibonacci number
1113 @F = $n->bfib(); # a list of Fibonacci numbers
1114 In scalar context, returns a single Fibonacci number. In list
1116 context, returns a list of Fibonacci numbers. The invocand is the
1117 last element in the output.
1118 The Fibonacci sequence is defined by
1120 F(0) = 0
1122 F(1) = 1
1123 F(n) = F(n-1) + F(n-2)
1124 In list context, F(0) and F(n) is the first and last number in the
1126 output, respectively. For example, if $n is 12, then "@F =
1127 $n->bfib()" returns the following values, F(0) to F(12):
1128 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144
1130 The sequence can also be extended to negative index n using the re-
1132 arranged recurrence relation
1133 F(n-2) = F(n) - F(n-1)
1135 giving the bidirectional sequence
1137 n -7 -6 -5 -4 -3 -2 -1 0 1 2 3 4 5 6 7
1139 F(n) 13 -8 5 -3 2 -1 1 0 1 1 2 3 5 8 13
1140 If $n is -12, the following values, F(0) to F(12), are returned:
1142 0, 1, -1, 2, -3, 5, -8, 13, -21, 34, -55, 89, -144
1144 blucas()
1146 $F = $n->blucas(); # a single Lucas number
1147 @F = $n->blucas(); # a list of Lucas numbers
1148 In scalar context, returns a single Lucas number. In list context,
1150 returns a list of Lucas numbers. The invocand is the last element
1151 in the output.
1152 The Lucas sequence is defined by
1154 L(0) = 2
1156 L(1) = 1
1157 L(n) = L(n-1) + L(n-2)
1158 In list context, L(0) and L(n) is the first and last number in the
1160 output, respectively. For example, if $n is 12, then "@L =
1161 $n->blucas()" returns the following values, L(0) to L(12):
1162 2, 1, 3, 4, 7, 11, 18, 29, 47, 76, 123, 199, 322
1164 The sequence can also be extended to negative index n using the re-
1166 arranged recurrence relation
1167 L(n-2) = L(n) - L(n-1)
1169 giving the bidirectional sequence
1171 n -7 -6 -5 -4 -3 -2 -1 0 1 2 3 4 5 6 7
1173 L(n) 29 -18 11 -7 4 -3 1 2 1 3 4 7 11 18 29
1174 If $n is -12, the following values, L(0) to L(-12), are returned:
1176 2, 1, -3, 4, -7, 11, -18, 29, -47, 76, -123, 199, -322
1178 brsft()
1180 $x->brsft($n); # right shift $n places in base 2
1181 $x->brsft($n, $b); # right shift $n places in base $b
1182 The latter is equivalent to
1184 $x -> bdiv($b -> copy() -> bpow($n))
1186 blsft()
1188 $x->blsft($n); # left shift $n places in base 2
1189 $x->blsft($n, $b); # left shift $n places in base $b
1190 The latter is equivalent to
1192 $x -> bmul($b -> copy() -> bpow($n))
1194 Bitwise methods
1196 band()
1197 $x->band($y); # bitwise and
1198 bior()
1200 $x->bior($y); # bitwise inclusive or
1201 bxor()
1203 $x->bxor($y); # bitwise exclusive or
1204 bnot()
1206 $x->bnot(); # bitwise not (two's complement)
1207 Two's complement (bitwise not). This is equivalent to, but faster
1209 than,
1210 $x->binc()->bneg();
1212 Rounding methods
1214 round()
1215 $x->round($A,$P,$round_mode);
1216 Round $x to accuracy $A or precision $P using the round mode
1218 $round_mode.
1219 bround()
1221 $x->bround($N); # accuracy: preserve $N digits
1222 Rounds $x to an accuracy of $N digits.
1224 bfround()
1226 $x->bfround($N);
1227 Rounds to a multiple of 10**$N. Examples:
1229 Input N Result
1231 123456.123456 3 123500
1233 123456.123456 2 123450
1234 123456.123456 -2 123456.12
1235 123456.123456 -3 123456.123
1236 bfloor()
1238 $x->bfloor();
1239 Round $x towards minus infinity, i.e., set $x to the largest
1241 integer less than or equal to $x.
1242 bceil()
1244 $x->bceil();
1245 Round $x towards plus infinity, i.e., set $x to the smallest
1247 integer greater than or equal to $x).
1248 bint()
1250 $x->bint();
1251 Round $x towards zero.
1253 Other mathematical methods
1255 bgcd()
1256 $x -> bgcd($y); # GCD of $x and $y
1257 $x -> bgcd($y, $z, ...); # GCD of $x, $y, $z, ...
1258 Returns the greatest common divisor (GCD).
1260 blcm()
1262 $x -> blcm($y); # LCM of $x and $y
1263 $x -> blcm($y, $z, ...); # LCM of $x, $y, $z, ...
1264 Returns the least common multiple (LCM).
1266 Object property methods
1268 sign()
1269 $x->sign();
1270 Return the sign, of $x, meaning either "+", "-", "-inf", "+inf" or
1272 NaN.
1273 If you want $x to have a certain sign, use one of the following
1275 methods:
1276 $x->babs(); # '+'
1278 $x->babs()->bneg(); # '-'
1279 $x->bnan(); # 'NaN'
1280 $x->binf(); # '+inf'
1281 $x->binf('-'); # '-inf'
1282 digit()
1284 $x->digit($n); # return the nth digit, counting from right
1285 If $n is negative, returns the digit counting from left.
1287 digitsum()
1289 $x->digitsum();
1290 Computes the sum of the base 10 digits and returns it.
1292 bdigitsum()
1294 $x->bdigitsum();
1295 Computes the sum of the base 10 digits and assigns the result to
1297 the invocand.
1298 length()
1300 $x->length();
1301 ($xl, $fl) = $x->length();
1302 Returns the number of digits in the decimal representation of the
1304 number. In list context, returns the length of the integer and
1305 fraction part. For Math::BigInt objects, the length of the fraction
1306 part is always 0.
1307 The following probably doesn't do what you expect:
1309 $c = Math::BigInt->new(123);
1311 print $c->length(),"\n"; # prints 30
1312 It prints both the number of digits in the number and in the
1314 fraction part since print calls "length()" in list context. Use
1315 something like:
1316 print scalar $c->length(),"\n"; # prints 3
1318 mantissa()
1320 $x->mantissa();
1321 Return the signed mantissa of $x as a Math::BigInt.
1323 exponent()
1325 $x->exponent();
1326 Return the exponent of $x as a Math::BigInt.
1328 parts()
1330 $x->parts();
1331 Returns the significand (mantissa) and the exponent as integers. In
1333 Math::BigFloat, both are returned as Math::BigInt objects.
1334 sparts()
1336 Returns the significand (mantissa) and the exponent as integers. In
1337 scalar context, only the significand is returned. The significand
1338 is the integer with the smallest absolute value. The output of
1339 "sparts()" corresponds to the output from "bsstr()".
1340 In Math::BigInt, this method is identical to "parts()".
1342 nparts()
1344 Returns the significand (mantissa) and exponent corresponding to
1345 normalized notation. In scalar context, only the significand is
1346 returned. For finite non-zero numbers, the significand's absolute
1347 value is greater than or equal to 1 and less than 10. The output of
1348 "nparts()" corresponds to the output from "bnstr()". In
1349 Math::BigInt, if the significand can not be represented as an
1350 integer, upgrading is performed or NaN is returned.
1351 eparts()
1353 Returns the significand (mantissa) and exponent corresponding to
1354 engineering notation. In scalar context, only the significand is
1355 returned. For finite non-zero numbers, the significand's absolute
1356 value is greater than or equal to 1 and less than 1000, and the
1357 exponent is a multiple of 3. The output of "eparts()" corresponds
1358 to the output from "bestr()". In Math::BigInt, if the significand
1359 can not be represented as an integer, upgrading is performed or NaN
1360 is returned.
1361 dparts()
1363 Returns the integer part and the fraction part. If the fraction
1364 part can not be represented as an integer, upgrading is performed
1365 or NaN is returned. The output of "dparts()" corresponds to the
1366 output from "bdstr()".
1367 fparts()
1369 Returns the smallest possible numerator and denominator so that the
1370 numerator divided by the denominator gives back the original value.
1371 For finite numbers, both values are integers. Mnemonic: fraction.
1372 numerator()
1374 Together with "denominator()", returns the smallest integers so
1375 that the numerator divided by the denominator reproduces the
1376 original value. With Math::BigInt, numerator() simply returns a
1377 copy of the invocand.
1378 denominator()
1380 Together with "numerator()", returns the smallest integers so that
1381 the numerator divided by the denominator reproduces the original
1382 value. With Math::BigInt, denominator() always returns either a 1
1383 or a NaN.
1384 String conversion methods
1386 bstr()
1387 Returns a string representing the number using decimal notation. In
1388 Math::BigFloat, the output is zero padded according to the current
1389 accuracy or precision, if any of those are defined.
1390 bsstr()
1392 Returns a string representing the number using scientific notation
1393 where both the significand (mantissa) and the exponent are
1394 integers. The output corresponds to the output from "sparts()".
1395 123 is returned as "123e+0"
1397 1230 is returned as "123e+1"
1398 12300 is returned as "123e+2"
1399 12000 is returned as "12e+3"
1400 10000 is returned as "1e+4"
1401 bnstr()
1403 Returns a string representing the number using normalized notation,
1404 the most common variant of scientific notation. For finite non-zero
1405 numbers, the absolute value of the significand is greater than or
1406 equal to 1 and less than 10. The output corresponds to the output
1407 from "nparts()".
1408 123 is returned as "1.23e+2"
1410 1230 is returned as "1.23e+3"
1411 12300 is returned as "1.23e+4"
1412 12000 is returned as "1.2e+4"
1413 10000 is returned as "1e+4"
1414 bestr()
1416 Returns a string representing the number using engineering
1417 notation. For finite non-zero numbers, the absolute value of the
1418 significand is greater than or equal to 1 and less than 1000, and
1419 the exponent is a multiple of 3. The output corresponds to the
1420 output from "eparts()".
1421 123 is returned as "123e+0"
1423 1230 is returned as "1.23e+3"
1424 12300 is returned as "12.3e+3"
1425 12000 is returned as "12e+3"
1426 10000 is returned as "10e+3"
1427 bdstr()
1429 Returns a string representing the number using decimal notation.
1430 The output corresponds to the output from "dparts()".
1431 123 is returned as "123"
1433 1230 is returned as "1230"
1434 12300 is returned as "12300"
1435 12000 is returned as "12000"
1436 10000 is returned as "10000"
1437 to_hex()
1439 $x->to_hex();
1440 Returns a hexadecimal string representation of the number. See also
1442 from_hex().
1443 to_bin()
1445 $x->to_bin();
1446 Returns a binary string representation of the number. See also
1448 from_bin().
1449 to_oct()
1451 $x->to_oct();
1452 Returns an octal string representation of the number. See also
1454 from_oct().
1455 to_bytes()
1457 $x = Math::BigInt->new("1667327589");
1458 $s = $x->to_bytes(); # $s = "cafe"
1459 Returns a byte string representation of the number using big endian
1461 byte order. The invocand must be a non-negative, finite integer.
1462 See also from_bytes().
1463 to_base()
1465 $x = Math::BigInt->new("250");
1466 $x->to_base(2); # returns "11111010"
1467 $x->to_base(8); # returns "372"
1468 $x->to_base(16); # returns "fa"
1469 Returns a string representation of the number in the given base. If
1471 a collation sequence is given, the collation sequence determines
1472 which characters are used in the output.
1473 Here are some more examples
1475 $x = Math::BigInt->new("16")->to_base(3); # returns "121"
1477 $x = Math::BigInt->new("44027")->to_base(36); # returns "XYZ"
1478 $x = Math::BigInt->new("58314")->to_base(42); # returns "Why"
1479 $x = Math::BigInt->new("4")->to_base(2, "-|"); # returns "|--"
1480 See from_base() for information and examples.
1482 to_base_num()
1484 Converts the given number to the given base. This method is
1485 equivalent to "_to_base()", but returns numbers in an array rather
1486 than characters in a string. In the output, the first element is
1487 the most significant. Unlike "_to_base()", all input values may be
1488 arbitrarily large.
1489 $x = Math::BigInt->new(13);
1491 $x->to_base_num(2); # returns [1, 1, 0, 1]
1492 $x = Math::BigInt->new(65191);
1494 $x->to_base_num(128); # returns [3, 125, 39]
1495 as_hex()
1497 $x->as_hex();
1498 As, "to_hex()", but with a "0x" prefix.
1500 as_bin()
1502 $x->as_bin();
1503 As, "to_bin()", but with a "0b" prefix.
1505 as_oct()
1507 $x->as_oct();
1508 As, "to_oct()", but with a "0" prefix.
1510 as_bytes()
1512 This is just an alias for "to_bytes()".
1513 Other conversion methods
1515 numify()
1516 print $x->numify();
1517 Returns a Perl scalar from $x. It is used automatically whenever a
1519 scalar is needed, for instance in array index operations.
1520 Utility methods
1522 These utility methods are made public
1523 dec_str_to_dec_flt_str()
1525 Takes a string representing any valid number using decimal notation
1526 and converts it to a string representing the same number using
1527 decimal floating point notation. The output consists of five parts
1528 joined together: the sign of the significand, the absolute value of
1529 the significand as the smallest possible integer, the letter "e",
1530 the sign of the exponent, and the absolute value of the exponent.
1531 If the input is invalid, nothing is returned.
1532 $str2 = $class -> dec_str_to_dec_flt_str($str1);
1534 Some examples
1536 Input Output
1538 31400.00e-4 +314e-2
1539 -0.00012300e8 -123e+2
1540 0 +0e+0
1541 hex_str_to_dec_flt_str()
1543 Takes a string representing any valid number using hexadecimal
1544 notation and converts it to a string representing the same number
1545 using decimal floating point notation. The output has the same
1546 format as that of "dec_str_to_dec_flt_str()".
1547 $str2 = $class -> hex_str_to_dec_flt_str($str1);
1549 Some examples
1551 Input Output
1553 0xff +255e+0
1554 Some examples
1556 oct_str_to_dec_flt_str()
1558 Takes a string representing any valid number using octal notation
1559 and converts it to a string representing the same number using
1560 decimal floating point notation. The output has the same format as
1561 that of "dec_str_to_dec_flt_str()".
1562 $str2 = $class -> oct_str_to_dec_flt_str($str1);
1564 bin_str_to_dec_flt_str()
1566 Takes a string representing any valid number using binary notation
1567 and converts it to a string representing the same number using
1568 decimal floating point notation. The output has the same format as
1569 that of "dec_str_to_dec_flt_str()".
1570 $str2 = $class -> bin_str_to_dec_flt_str($str1);
1572 dec_str_to_dec_str()
1574 Takes a string representing any valid number using decimal notation
1575 and converts it to a string representing the same number using
1576 decimal notation. If the number represents an integer, the output
1577 consists of a sign and the absolute value. If the number represents
1578 a non-integer, the output consists of a sign, the integer part of
1579 the number, the decimal point ".", and the fraction part of the
1580 number without any trailing zeros. If the input is invalid, nothing
1581 is returned.
1582 hex_str_to_dec_str()
1584 Takes a string representing any valid number using hexadecimal
1585 notation and converts it to a string representing the same number
1586 using decimal notation. The output has the same format as that of
1587 "dec_str_to_dec_str()".
1588 oct_str_to_dec_str()
1590 Takes a string representing any valid number using octal notation
1591 and converts it to a string representing the same number using
1592 decimal notation. The output has the same format as that of
1593 "dec_str_to_dec_str()".
1594 bin_str_to_dec_str()
1596 Takes a string representing any valid number using binary notation
1597 and converts it to a string representing the same number using
1598 decimal notation. The output has the same format as that of
1599 "dec_str_to_dec_str()".
1600
1602 Math::BigInt and Math::BigFloat have full support for accuracy and
1603 precision based rounding, both automatically after every operation, as
1604 well as manually.
1605 This section describes the accuracy/precision handling in Math::BigInt
1607 and Math::BigFloat as it used to be and as it is now, complete with an
1608 explanation of all terms and abbreviations.
1609 Not yet implemented things (but with correct description) are marked
1611 with '!', things that need to be answered are marked with '?'.
1612 In the next paragraph follows a short description of terms used here
1614 (because these may differ from terms used by others people or
1615 documentation).
1616 During the rest of this document, the shortcuts A (for accuracy), P
1618 (for precision), F (fallback) and R (rounding mode) are be used.
1619 Precision P
1621 Precision is a fixed number of digits before (positive) or after
1622 (negative) the decimal point. For example, 123.45 has a precision of
1623 -2. 0 means an integer like 123 (or 120). A precision of 2 means at
1624 least two digits to the left of the decimal point are zero, so 123 with
1625 P = 1 becomes 120. Note that numbers with zeros before the decimal
1626 point may have different precisions, because 1200 can have P = 0, 1 or
1627 2 (depending on what the initial value was). It could also have p < 0,
1628 when the digits after the decimal point are zero.
1629 The string output (of floating point numbers) is padded with zeros:
1631 Initial value P A Result String
1633 ------------------------------------------------------------
1634 1234.01 -3 1000 1000
1635 1234 -2 1200 1200
1636 1234.5 -1 1230 1230
1637 1234.001 1 1234 1234.0
1638 1234.01 0 1234 1234
1639 1234.01 2 1234.01 1234.01
1640 1234.01 5 1234.01 1234.01000
1641 For Math::BigInt objects, no padding occurs.
1643 Accuracy A
1645 Number of significant digits. Leading zeros are not counted. A number
1646 may have an accuracy greater than the non-zero digits when there are
1647 zeros in it or trailing zeros. For example, 123.456 has A of 6, 10203
1648 has 5, 123.0506 has 7, 123.45000 has 8 and 0.000123 has 3.
1649 The string output (of floating point numbers) is padded with zeros:
1651 Initial value P A Result String
1653 ------------------------------------------------------------
1654 1234.01 3 1230 1230
1655 1234.01 6 1234.01 1234.01
1656 1234.1 8 1234.1 1234.1000
1657 For Math::BigInt objects, no padding occurs.
1659 Fallback F
1661 When both A and P are undefined, this is used as a fallback accuracy
1662 when dividing numbers.
1663 Rounding mode R
1665 When rounding a number, different 'styles' or 'kinds' of rounding are
1666 possible. (Note that random rounding, as in Math::Round, is not
1667 implemented.)
1668 Directed rounding
1670 These round modes always round in the same direction.
1672 'trunc'
1674 Round towards zero. Remove all digits following the rounding place,
1675 i.e., replace them with zeros. Thus, 987.65 rounded to tens (P=1)
1676 becomes 980, and rounded to the fourth significant digit becomes
1677 987.6 (A=4). 123.456 rounded to the second place after the decimal
1678 point (P=-2) becomes 123.46. This corresponds to the IEEE 754
1679 rounding mode 'roundTowardZero'.
1680 Rounding to nearest
1682 These rounding modes round to the nearest digit. They differ in how
1684 they determine which way to round in the ambiguous case when there is a
1685 tie.
1686 'even'
1688 Round towards the nearest even digit, e.g., when rounding to
1689 nearest integer, -5.5 becomes -6, 4.5 becomes 4, but 4.501 becomes
1690 5. This corresponds to the IEEE 754 rounding mode
1691 'roundTiesToEven'.
1692 'odd'
1694 Round towards the nearest odd digit, e.g., when rounding to nearest
1695 integer, 4.5 becomes 5, -5.5 becomes -5, but 5.501 becomes 6. This
1696 corresponds to the IEEE 754 rounding mode 'roundTiesToOdd'.
1697 '+inf'
1699 Round towards plus infinity, i.e., always round up. E.g., when
1700 rounding to the nearest integer, 4.5 becomes 5, -5.5 becomes -5,
1701 and 4.501 also becomes 5. This corresponds to the IEEE 754 rounding
1702 mode 'roundTiesToPositive'.
1703 '-inf'
1705 Round towards minus infinity, i.e., always round down. E.g., when
1706 rounding to the nearest integer, 4.5 becomes 4, -5.5 becomes -6,
1707 but 4.501 becomes 5. This corresponds to the IEEE 754 rounding mode
1708 'roundTiesToNegative'.
1709 'zero'
1711 Round towards zero, i.e., round positive numbers down and negative
1712 numbers up. E.g., when rounding to the nearest integer, 4.5
1713 becomes 4, -5.5 becomes -5, but 4.501 becomes 5. This corresponds
1714 to the IEEE 754 rounding mode 'roundTiesToZero'.
1715 'common'
1717 Round away from zero, i.e., round to the number with the largest
1718 absolute value. E.g., when rounding to the nearest integer, -1.5
1719 becomes -2, 1.5 becomes 2 and 1.49 becomes 1. This corresponds to
1720 the IEEE 754 rounding mode 'roundTiesToAway'.
1721 The handling of A & P in MBI/MBF (the old core code shipped with Perl
1723 versions <= 5.7.2) is like this:
1724 Precision
1726 * bfround($p) is able to round to $p number of digits after the decimal
1727 point
1728 * otherwise P is unused
1729 Accuracy (significant digits)
1731 * bround($a) rounds to $a significant digits
1732 * only bdiv() and bsqrt() take A as (optional) parameter
1733 + other operations simply create the same number (bneg etc), or
1734 more (bmul) of digits
1735 + rounding/truncating is only done when explicitly calling one
1736 of bround or bfround, and never for Math::BigInt (not implemented)
1737 * bsqrt() simply hands its accuracy argument over to bdiv.
1738 * the documentation and the comment in the code indicate two
1739 different ways on how bdiv() determines the maximum number
1740 of digits it should calculate, and the actual code does yet
1741 another thing
1742 POD:
1743 max($Math::BigFloat::div_scale,length(dividend)+length(divisor))
1744 Comment:
1745 result has at most max(scale, length(dividend), length(divisor)) digits
1746 Actual code:
1747 scale = max(scale, length(dividend)-1,length(divisor)-1);
1748 scale += length(divisor) - length(dividend);
1749 So for lx = 3, ly = 9, scale = 10, scale will actually be 16 (10
1750 So for lx = 3, ly = 9, scale = 10, scale will actually be 16
1751 (10+9-3). Actually, the 'difference' added to the scale is cal-
1752 culated from the number of "significant digits" in dividend and
1753 divisor, which is derived by looking at the length of the man-
1754 tissa. Which is wrong, since it includes the + sign (oops) and
1755 actually gets 2 for '+100' and 4 for '+101'. Oops again. Thus
1756 124/3 with div_scale=1 will get you '41.3' based on the strange
1757 assumption that 124 has 3 significant digits, while 120/7 will
1758 get you '17', not '17.1' since 120 is thought to have 2 signif-
1759 icant digits. The rounding after the division then uses the
1760 remainder and $y to determine whether it must round up or down.
1761 ? I have no idea which is the right way. That's why I used a slightly more
1762 ? simple scheme and tweaked the few failing testcases to match it.
1763 This is how it works now:
1765 Setting/Accessing
1767 * You can set the A global via Math::BigInt->accuracy() or
1768 Math::BigFloat->accuracy() or whatever class you are using.
1769 * You can also set P globally by using Math::SomeClass->precision()
1770 likewise.
1771 * Globals are classwide, and not inherited by subclasses.
1772 * to undefine A, use Math::SomeClass->accuracy(undef);
1773 * to undefine P, use Math::SomeClass->precision(undef);
1774 * Setting Math::SomeClass->accuracy() clears automatically
1775 Math::SomeClass->precision(), and vice versa.
1776 * To be valid, A must be > 0, P can have any value.
1777 * If P is negative, this means round to the P'th place to the right of the
1778 decimal point; positive values mean to the left of the decimal point.
1779 P of 0 means round to integer.
1780 * to find out the current global A, use Math::SomeClass->accuracy()
1781 * to find out the current global P, use Math::SomeClass->precision()
1782 * use $x->accuracy() respective $x->precision() for the local
1783 setting of $x.
1784 * Please note that $x->accuracy() respective $x->precision()
1785 return eventually defined global A or P, when $x's A or P is not
1786 set.
1787 Creating numbers
1789 * When you create a number, you can give the desired A or P via:
1790 $x = Math::BigInt->new($number,$A,$P);
1791 * Only one of A or P can be defined, otherwise the result is NaN
1792 * If no A or P is give ($x = Math::BigInt->new($number) form), then the
1793 globals (if set) will be used. Thus changing the global defaults later on
1794 will not change the A or P of previously created numbers (i.e., A and P of
1795 $x will be what was in effect when $x was created)
1796 * If given undef for A and P, NO rounding will occur, and the globals will
1797 NOT be used. This is used by subclasses to create numbers without
1798 suffering rounding in the parent. Thus a subclass is able to have its own
1799 globals enforced upon creation of a number by using
1800 $x = Math::BigInt->new($number,undef,undef):
1801 use Math::BigInt::SomeSubclass;
1803 use Math::BigInt;
1804 Math::BigInt->accuracy(2);
1806 Math::BigInt::SomeSubclass->accuracy(3);
1807 $x = Math::BigInt::SomeSubclass->new(1234);
1808 $x is now 1230, and not 1200. A subclass might choose to implement
1810 this otherwise, e.g. falling back to the parent's A and P.
1811 Usage
1813 * If A or P are enabled/defined, they are used to round the result of each
1814 operation according to the rules below
1815 * Negative P is ignored in Math::BigInt, since Math::BigInt objects never
1816 have digits after the decimal point
1817 * Math::BigFloat uses Math::BigInt internally, but setting A or P inside
1818 Math::BigInt as globals does not tamper with the parts of a Math::BigFloat.
1819 A flag is used to mark all Math::BigFloat numbers as 'never round'.
1820 Precedence
1822 * It only makes sense that a number has only one of A or P at a time.
1823 If you set either A or P on one object, or globally, the other one will
1824 be automatically cleared.
1825 * If two objects are involved in an operation, and one of them has A in
1826 effect, and the other P, this results in an error (NaN).
1827 * A takes precedence over P (Hint: A comes before P).
1828 If neither of them is defined, nothing is used, i.e. the result will have
1829 as many digits as it can (with an exception for bdiv/bsqrt) and will not
1830 be rounded.
1831 * There is another setting for bdiv() (and thus for bsqrt()). If neither of
1832 A or P is defined, bdiv() will use a fallback (F) of $div_scale digits.
1833 If either the dividend's or the divisor's mantissa has more digits than
1834 the value of F, the higher value will be used instead of F.
1835 This is to limit the digits (A) of the result (just consider what would
1836 happen with unlimited A and P in the case of 1/3 :-)
1837 * bdiv will calculate (at least) 4 more digits than required (determined by
1838 A, P or F), and, if F is not used, round the result
1839 (this will still fail in the case of a result like 0.12345000000001 with A
1840 or P of 5, but this can not be helped - or can it?)
1841 * Thus you can have the math done by on Math::Big* class in two modi:
1842 + never round (this is the default):
1843 This is done by setting A and P to undef. No math operation
1844 will round the result, with bdiv() and bsqrt() as exceptions to guard
1845 against overflows. You must explicitly call bround(), bfround() or
1846 round() (the latter with parameters).
1847 Note: Once you have rounded a number, the settings will 'stick' on it
1848 and 'infect' all other numbers engaged in math operations with it, since
1849 local settings have the highest precedence. So, to get SaferRound[tm],
1850 use a copy() before rounding like this:
1851 $x = Math::BigFloat->new(12.34);
1853 $y = Math::BigFloat->new(98.76);
1854 $z = $x * $y; # 1218.6984
1855 print $x->copy()->bround(3); # 12.3 (but A is now 3!)
1856 $z = $x * $y; # still 1218.6984, without
1857 # copy would have been 1210!
1858 + round after each op:
1860 After each single operation (except for testing like is_zero()), the
1861 method round() is called and the result is rounded appropriately. By
1862 setting proper values for A and P, you can have all-the-same-A or
1863 all-the-same-P modes. For example, Math::Currency might set A to undef,
1864 and P to -2, globally.
1865 ?Maybe an extra option that forbids local A & P settings would be in order,
1867 ?so that intermediate rounding does not 'poison' further math?
1868 Overriding globals
1870 * you will be able to give A, P and R as an argument to all the calculation
1871 routines; the second parameter is A, the third one is P, and the fourth is
1872 R (shift right by one for binary operations like badd). P is used only if
1873 the first parameter (A) is undefined. These three parameters override the
1874 globals in the order detailed as follows, i.e. the first defined value
1875 wins:
1876 (local: per object, global: global default, parameter: argument to sub)
1877 + parameter A
1878 + parameter P
1879 + local A (if defined on both of the operands: smaller one is taken)
1880 + local P (if defined on both of the operands: bigger one is taken)
1881 + global A
1882 + global P
1883 + global F
1884 * bsqrt() will hand its arguments to bdiv(), as it used to, only now for two
1885 arguments (A and P) instead of one
1886 Local settings
1888 * You can set A or P locally by using $x->accuracy() or
1889 $x->precision()
1890 and thus force different A and P for different objects/numbers.
1891 * Setting A or P this way immediately rounds $x to the new value.
1892 * $x->accuracy() clears $x->precision(), and vice versa.
1893 Rounding
1895 * the rounding routines will use the respective global or local settings.
1896 bround() is for accuracy rounding, while bfround() is for precision
1897 * the two rounding functions take as the second parameter one of the
1898 following rounding modes (R):
1899 'even', 'odd', '+inf', '-inf', 'zero', 'trunc', 'common'
1900 * you can set/get the global R by using Math::SomeClass->round_mode()
1901 or by setting $Math::SomeClass::round_mode
1902 * after each operation, $result->round() is called, and the result may
1903 eventually be rounded (that is, if A or P were set either locally,
1904 globally or as parameter to the operation)
1905 * to manually round a number, call $x->round($A,$P,$round_mode);
1906 this will round the number by using the appropriate rounding function
1907 and then normalize it.
1908 * rounding modifies the local settings of the number:
1909 $x = Math::BigFloat->new(123.456);
1911 $x->accuracy(5);
1912 $x->bround(4);
1913 Here 4 takes precedence over 5, so 123.5 is the result and $x->accuracy()
1915 will be 4 from now on.
1916 Default values
1918 * R: 'even'
1919 * F: 40
1920 * A: undef
1921 * P: undef
1922 Remarks
1924 * The defaults are set up so that the new code gives the same results as
1925 the old code (except in a few cases on bdiv):
1926 + Both A and P are undefined and thus will not be used for rounding
1927 after each operation.
1928 + round() is thus a no-op, unless given extra parameters A and P
1929
1931 While Math::BigInt has extensive handling of inf and NaN, certain
1932 quirks remain.
1933 oct()/hex()
1935 These perl routines currently (as of Perl v.5.8.6) cannot handle
1936 passed inf.
1937 te@linux:~> perl -wle 'print 2 ** 3333'
1939 Inf
1940 te@linux:~> perl -wle 'print 2 ** 3333 == 2 ** 3333'
1941 1
1942 te@linux:~> perl -wle 'print oct(2 ** 3333)'
1943 0
1944 te@linux:~> perl -wle 'print hex(2 ** 3333)'
1945 Illegal hexadecimal digit 'I' ignored at -e line 1.
1946 0
1947 The same problems occur if you pass them Math::BigInt->binf()
1949 objects. Since overloading these routines is not possible, this
1950 cannot be fixed from Math::BigInt.
1951
1953 You should neither care about nor depend on the internal
1954 representation; it might change without notice. Use ONLY method calls
1955 like "$x->sign();" instead relying on the internal representation.
1956 MATH LIBRARY
1958 The mathematical computations are performed by a backend library. It is
1959 not required to specify which backend library to use, but some backend
1960 libraries are much faster than the default library.
1961 The default library
1963 The default library is Math::BigInt::Calc, which is implemented in pure
1965 Perl and hence does not require a compiler.
1966 Specifying a library
1968 The simple case
1970 use Math::BigInt;
1972 is equivalent to saying
1974 use Math::BigInt try => 'Calc';
1976 You can use a different backend library with, e.g.,
1978 use Math::BigInt try => 'GMP';
1980 which attempts to load the Math::BigInt::GMP library, and falls back to
1982 the default library if the specified library can't be loaded.
1983 Multiple libraries can be specified by separating them by a comma,
1985 e.g.,
1986 use Math::BigInt try => 'GMP,Pari';
1988 If you request a specific set of libraries and do not allow fallback to
1990 the default library, specify them using "only",
1991 use Math::BigInt only => 'GMP,Pari';
1993 If you prefer a specific set of libraries, but want to see a warning if
1995 the fallback library is used, specify them using "lib",
1996 use Math::BigInt lib => 'GMP,Pari';
1998 The following first tries to find Math::BigInt::Foo, then
2000 Math::BigInt::Bar, and if this also fails, reverts to
2001 Math::BigInt::Calc:
2002 use Math::BigInt try => 'Foo,Math::BigInt::Bar';
2004 Which library to use?
2006 Note: General purpose packages should not be explicit about the library
2008 to use; let the script author decide which is best.
2009 Math::BigInt::GMP, Math::BigInt::Pari, and Math::BigInt::GMPz are in
2011 cases involving big numbers much faster than Math::BigInt::Calc.
2012 However these libraries are slower when dealing with very small numbers
2013 (less than about 20 digits) and when converting very large numbers to
2014 decimal (for instance for printing, rounding, calculating their length
2015 in decimal etc.).
2016 So please select carefully what library you want to use.
2018 Different low-level libraries use different formats to store the
2020 numbers, so mixing them won't work. You should not depend on the number
2021 having a specific internal format.
2022 See the respective math library module documentation for further
2024 details.
2025 Loading multiple libraries
2027 The first library that is successfully loaded is the one that will be
2029 used. Any further attempts at loading a different module will be
2030 ignored. This is to avoid the situation where module A requires math
2031 library X, and module B requires math library Y, causing modules A and
2032 B to be incompatible. For example,
2033 use Math::BigInt; # loads default "Calc"
2035 use Math::BigFloat only => "GMP"; # ignores "GMP"
2036 SIGN
2038 The sign is either '+', '-', 'NaN', '+inf' or '-inf'.
2039 A sign of 'NaN' is used to represent the result when input arguments
2041 are not numbers or as a result of 0/0. '+inf' and '-inf' represent plus
2042 respectively minus infinity. You get '+inf' when dividing a positive
2043 number by 0, and '-inf' when dividing any negative number by 0.
2044
2046 use Math::BigInt;
2047 sub bigint { Math::BigInt->new(shift); }
2049 $x = Math::BigInt->bstr("1234") # string "1234"
2051 $x = "$x"; # same as bstr()
2052 $x = Math::BigInt->bneg("1234"); # Math::BigInt "-1234"
2053 $x = Math::BigInt->babs("-12345"); # Math::BigInt "12345"
2054 $x = Math::BigInt->bnorm("-0.00"); # Math::BigInt "0"
2055 $x = bigint(1) + bigint(2); # Math::BigInt "3"
2056 $x = bigint(1) + "2"; # ditto ("2" becomes a Math::BigInt)
2057 $x = bigint(1); # Math::BigInt "1"
2058 $x = $x + 5 / 2; # Math::BigInt "3"
2059 $x = $x ** 3; # Math::BigInt "27"
2060 $x *= 2; # Math::BigInt "54"
2061 $x = Math::BigInt->new(0); # Math::BigInt "0"
2062 $x--; # Math::BigInt "-1"
2063 $x = Math::BigInt->badd(4,5) # Math::BigInt "9"
2064 print $x->bsstr(); # 9e+0
2065 Examples for rounding:
2067 use Math::BigFloat;
2069 use Test::More;
2070 $x = Math::BigFloat->new(123.4567);
2072 $y = Math::BigFloat->new(123.456789);
2073 Math::BigFloat->accuracy(4); # no more A than 4
2074 is ($x->copy()->bround(),123.4); # even rounding
2076 print $x->copy()->bround(),"\n"; # 123.4
2077 Math::BigFloat->round_mode('odd'); # round to odd
2078 print $x->copy()->bround(),"\n"; # 123.5
2079 Math::BigFloat->accuracy(5); # no more A than 5
2080 Math::BigFloat->round_mode('odd'); # round to odd
2081 print $x->copy()->bround(),"\n"; # 123.46
2082 $y = $x->copy()->bround(4),"\n"; # A = 4: 123.4
2083 print "$y, ",$y->accuracy(),"\n"; # 123.4, 4
2084 Math::BigFloat->accuracy(undef); # A not important now
2086 Math::BigFloat->precision(2); # P important
2087 print $x->copy()->bnorm(),"\n"; # 123.46
2088 print $x->copy()->bround(),"\n"; # 123.46
2089 Examples for converting:
2091 my $x = Math::BigInt->new('0b1'.'01' x 123);
2093 print "bin: ",$x->as_bin()," hex:",$x->as_hex()," dec: ",$x,"\n";
2094
2096 After "use Math::BigInt ':constant'" all numeric literals in the given
2097 scope are converted to "Math::BigInt" objects. This conversion happens
2098 at compile time. Every non-integer is convert to a NaN.
2099 For example,
2101 perl -MMath::BigInt=:constant -le 'print 2**150'
2103 prints the exact value of "2**150". Note that without conversion of
2105 constants to objects the expression "2**150" is calculated using Perl
2106 scalars, which leads to an inaccurate result.
2107 Please note that strings are not affected, so that
2109 use Math::BigInt qw/:constant/;
2111 $x = "1234567890123456789012345678901234567890"
2113 + "123456789123456789";
2114 does give you what you expect. You need an explicit Math::BigInt->new()
2116 around at least one of the operands. You should also quote large
2117 constants to prevent loss of precision:
2118 use Math::BigInt;
2120 $x = Math::BigInt->new("1234567889123456789123456789123456789");
2122 Without the quotes Perl first converts the large number to a floating
2124 point constant at compile time, and then converts the result to a
2125 Math::BigInt object at run time, which results in an inaccurate result.
2126 Hexadecimal, octal, and binary floating point literals
2128 Perl (and this module) accepts hexadecimal, octal, and binary floating
2129 point literals, but use them with care with Perl versions before
2130 v5.32.0, because some versions of Perl silently give the wrong result.
2131 Below are some examples of different ways to write the number decimal
2132 314.
2133 Hexadecimal floating point literals:
2135 0x1.3ap+8 0X1.3AP+8
2137 0x1.3ap8 0X1.3AP8
2138 0x13a0p-4 0X13A0P-4
2139 Octal floating point literals (with "0" prefix):
2141 01.164p+8 01.164P+8
2143 01.164p8 01.164P8
2144 011640p-4 011640P-4
2145 Octal floating point literals (with "0o" prefix) (requires v5.34.0):
2147 0o1.164p+8 0O1.164P+8
2149 0o1.164p8 0O1.164P8
2150 0o11640p-4 0O11640P-4
2151 Binary floating point literals:
2153 0b1.0011101p+8 0B1.0011101P+8
2155 0b1.0011101p8 0B1.0011101P8
2156 0b10011101000p-2 0B10011101000P-2
2157
2159 Using the form $x += $y; etc over $x = $x + $y is faster, since a copy
2160 of $x must be made in the second case. For long numbers, the copy can
2161 eat up to 20% of the work (in the case of addition/subtraction, less
2162 for multiplication/division). If $y is very small compared to $x, the
2163 form $x += $y is MUCH faster than $x = $x + $y since making the copy of
2164 $x takes more time then the actual addition.
2165 With a technique called copy-on-write, the cost of copying with
2167 overload could be minimized or even completely avoided. A test
2168 implementation of COW did show performance gains for overloaded math,
2169 but introduced a performance loss due to a constant overhead for all
2170 other operations. So Math::BigInt does currently not COW.
2171 The rewritten version of this module (vs. v0.01) is slower on certain
2173 operations, like "new()", "bstr()" and "numify()". The reason are that
2174 it does now more work and handles much more cases. The time spent in
2175 these operations is usually gained in the other math operations so that
2176 code on the average should get (much) faster. If they don't, please
2177 contact the author.
2178 Some operations may be slower for small numbers, but are significantly
2180 faster for big numbers. Other operations are now constant (O(1), like
2181 "bneg()", "babs()" etc), instead of O(N) and thus nearly always take
2182 much less time. These optimizations were done on purpose.
2183 If you find the Calc module to slow, try to install any of the
2185 replacement modules and see if they help you.
2186 Alternative math libraries
2188 You can use an alternative library to drive Math::BigInt. See the
2189 section "MATH LIBRARY" for more information.
2190 For more benchmark results see
2192 <http://bloodgate.com/perl/benchmarks.html>.
2193
2195 Subclassing Math::BigInt
2196 The basic design of Math::BigInt allows simple subclasses with very
2197 little work, as long as a few simple rules are followed:
2198 • The public API must remain consistent, i.e. if a sub-class is
2200 overloading addition, the sub-class must use the same name, in this
2201 case badd(). The reason for this is that Math::BigInt is optimized
2202 to call the object methods directly.
2203 • The private object hash keys like "$x->{sign}" may not be changed,
2205 but additional keys can be added, like "$x->{_custom}".
2206 • Accessor functions are available for all existing object hash keys
2208 and should be used instead of directly accessing the internal hash
2209 keys. The reason for this is that Math::BigInt itself has a
2210 pluggable interface which permits it to support different storage
2211 methods.
2212 More complex sub-classes may have to replicate more of the logic
2214 internal of Math::BigInt if they need to change more basic behaviors. A
2215 subclass that needs to merely change the output only needs to overload
2216 "bstr()".
2217 All other object methods and overloaded functions can be directly
2219 inherited from the parent class.
2220 At the very minimum, any subclass needs to provide its own "new()" and
2222 can store additional hash keys in the object. There are also some
2223 package globals that must be defined, e.g.:
2224 # Globals
2226 $accuracy = undef;
2227 $precision = -2; # round to 2 decimal places
2228 $round_mode = 'even';
2229 $div_scale = 40;
2230 Additionally, you might want to provide the following two globals to
2232 allow auto-upgrading and auto-downgrading to work correctly:
2233 $upgrade = undef;
2235 $downgrade = undef;
2236 This allows Math::BigInt to correctly retrieve package globals from the
2238 subclass, like $SubClass::precision. See t/Math/BigInt/Subclass.pm or
2239 t/Math/BigFloat/SubClass.pm completely functional subclass examples.
2240 Don't forget to
2242 use overload;
2244 in your subclass to automatically inherit the overloading from the
2246 parent. If you like, you can change part of the overloading, look at
2247 Math::String for an example.
2248
2250 When used like this:
2251 use Math::BigInt upgrade => 'Foo::Bar';
2253 certain operations 'upgrade' their calculation and thus the result to
2255 the class Foo::Bar. Usually this is used in conjunction with
2256 Math::BigFloat:
2257 use Math::BigInt upgrade => 'Math::BigFloat';
2259 As a shortcut, you can use the module bignum:
2261 use bignum;
2263 Also good for one-liners:
2265 perl -Mbignum -le 'print 2 ** 255'
2267 This makes it possible to mix arguments of different classes (as in 2.5
2269 + 2) as well es preserve accuracy (as in sqrt(3)).
2270 Beware: This feature is not fully implemented yet.
2272 Auto-upgrade
2274 The following methods upgrade themselves unconditionally; that is if
2275 upgrade is in effect, they always hands up their work:
2276 div bsqrt blog bexp bpi bsin bcos batan batan2
2278 All other methods upgrade themselves only when one (or all) of their
2280 arguments are of the class mentioned in $upgrade.
2281
2283 "Math::BigInt" exports nothing by default, but can export the following
2284 methods:
2285 bgcd
2287 blcm
2288
2290 Some things might not work as you expect them. Below is documented what
2291 is known to be troublesome:
2292 Comparing numbers as strings
2294 Both "bstr()" and "bsstr()" as well as stringify via overload drop
2295 the leading '+'. This is to be consistent with Perl and to make
2296 "cmp" (especially with overloading) to work as you expect. It also
2297 solves problems with "Test.pm" and Test::More, which stringify
2298 arguments before comparing them.
2299 Mark Biggar said, when asked about to drop the '+' altogether, or
2301 make only "cmp" work:
2302 I agree (with the first alternative), don't add the '+' on positive
2304 numbers. It's not as important anymore with the new internal form
2305 for numbers. It made doing things like abs and neg easier, but
2306 those have to be done differently now anyway.
2307 So, the following examples now works as expected:
2309 use Test::More tests => 1;
2311 use Math::BigInt;
2312 my $x = Math::BigInt -> new(3*3);
2314 my $y = Math::BigInt -> new(3*3);
2315 is($x,3*3, 'multiplication');
2317 print "$x eq 9" if $x eq $y;
2318 print "$x eq 9" if $x eq '9';
2319 print "$x eq 9" if $x eq 3*3;
2320 Additionally, the following still works:
2322 print "$x == 9" if $x == $y;
2324 print "$x == 9" if $x == 9;
2325 print "$x == 9" if $x == 3*3;
2326 There is now a "bsstr()" method to get the string in scientific
2328 notation aka 1e+2 instead of 100. Be advised that overloaded 'eq'
2329 always uses bstr() for comparison, but Perl represents some numbers
2330 as 100 and others as 1e+308. If in doubt, convert both arguments
2331 to Math::BigInt before comparing them as strings:
2332 use Test::More tests => 3;
2334 use Math::BigInt;
2335 $x = Math::BigInt->new('1e56'); $y = 1e56;
2337 is($x,$y); # fails
2338 is($x->bsstr(),$y); # okay
2339 $y = Math::BigInt->new($y);
2340 is($x,$y); # okay
2341 Alternatively, simply use "<=>" for comparisons, this always gets
2343 it right. There is not yet a way to get a number automatically
2344 represented as a string that matches exactly the way Perl
2345 represents it.
2346 See also the section about "Infinity and Not a Number" for problems
2348 in comparing NaNs.
2349 int()
2351 "int()" returns (at least for Perl v5.7.1 and up) another
2352 Math::BigInt, not a Perl scalar:
2353 $x = Math::BigInt->new(123);
2355 $y = int($x); # 123 as a Math::BigInt
2356 $x = Math::BigFloat->new(123.45);
2357 $y = int($x); # 123 as a Math::BigFloat
2358 If you want a real Perl scalar, use "numify()":
2360 $y = $x->numify(); # 123 as a scalar
2362 This is seldom necessary, though, because this is done
2364 automatically, like when you access an array:
2365 $z = $array[$x]; # does work automatically
2367 Modifying and =
2369 Beware of:
2370 $x = Math::BigFloat->new(5);
2372 $y = $x;
2373 This makes a second reference to the same object and stores it in
2375 $y. Thus anything that modifies $x (except overloaded operators)
2376 also modifies $y, and vice versa. Or in other words, "=" is only
2377 safe if you modify your Math::BigInt objects only via overloaded
2378 math. As soon as you use a method call it breaks:
2379 $x->bmul(2);
2381 print "$x, $y\n"; # prints '10, 10'
2382 If you want a true copy of $x, use:
2384 $y = $x->copy();
2386 You can also chain the calls like this, this first makes a copy and
2388 then multiply it by 2:
2389 $y = $x->copy()->bmul(2);
2391 See also the documentation for overload.pm regarding "=".
2393 Overloading -$x
2395 The following:
2396 $x = -$x;
2398 is slower than
2400 $x->bneg();
2402 since overload calls "sub($x,0,1);" instead of "neg($x)". The first
2404 variant needs to preserve $x since it does not know that it later
2405 gets overwritten. This makes a copy of $x and takes O(N), but
2406 $x->bneg() is O(1).
2407 Mixing different object types
2409 With overloaded operators, it is the first (dominating) operand
2410 that determines which method is called. Here are some examples
2411 showing what actually gets called in various cases.
2412 use Math::BigInt;
2414 use Math::BigFloat;
2415 $mbf = Math::BigFloat->new(5);
2417 $mbi2 = Math::BigInt->new(5);
2418 $mbi = Math::BigInt->new(2);
2419 # what actually gets called:
2420 $float = $mbf + $mbi; # $mbf->badd($mbi)
2421 $float = $mbf / $mbi; # $mbf->bdiv($mbi)
2422 $integer = $mbi + $mbf; # $mbi->badd($mbf)
2423 $integer = $mbi2 / $mbi; # $mbi2->bdiv($mbi)
2424 $integer = $mbi2 / $mbf; # $mbi2->bdiv($mbf)
2425 For instance, Math::BigInt->bdiv() always returns a Math::BigInt,
2427 regardless of whether the second operant is a Math::BigFloat. To
2428 get a Math::BigFloat you either need to call the operation
2429 manually, make sure each operand already is a Math::BigFloat, or
2430 cast to that type via Math::BigFloat->new():
2431 $float = Math::BigFloat->new($mbi2) / $mbi; # = 2.5
2433 Beware of casting the entire expression, as this would cast the
2435 result, at which point it is too late:
2436 $float = Math::BigFloat->new($mbi2 / $mbi); # = 2
2438 Beware also of the order of more complicated expressions like:
2440 $integer = ($mbi2 + $mbi) / $mbf; # int / float => int
2442 $integer = $mbi2 / Math::BigFloat->new($mbi); # ditto
2443 If in doubt, break the expression into simpler terms, or cast all
2445 operands to the desired resulting type.
2446 Scalar values are a bit different, since:
2448 $float = 2 + $mbf;
2450 $float = $mbf + 2;
2451 both result in the proper type due to the way the overloaded math
2453 works.
2454 This section also applies to other overloaded math packages, like
2456 Math::String.
2457 One solution to you problem might be autoupgrading|upgrading. See
2459 the pragmas bignum, bigint and bigrat for an easy way to do this.
2460
2462 Please report any bugs or feature requests to "bug-math-bigint at
2463 rt.cpan.org", or through the web interface at
2464 <https://rt.cpan.org/Ticket/Create.html?Queue=Math-BigInt> (requires
2465 login). We will be notified, and then you'll automatically be notified
2466 of progress on your bug as I make changes.
2467
2469 You can find documentation for this module with the perldoc command.
2470 perldoc Math::BigInt
2472 You can also look for information at:
2474 • GitHub
2476 <https://github.com/pjacklam/p5-Math-BigInt>
2478 • RT: CPAN's request tracker
2480 <https://rt.cpan.org/Dist/Display.html?Name=Math-BigInt>
2482 • MetaCPAN
2484 <https://metacpan.org/release/Math-BigInt>
2486 • CPAN Testers Matrix
2488 <http://matrix.cpantesters.org/?dist=Math-BigInt>
2490 • CPAN Ratings
2492 <https://cpanratings.perl.org/dist/Math-BigInt>
2494 • The Bignum mailing list
2496 • Post to mailing list
2498 "bignum at lists.scsys.co.uk"
2500 • View mailing list
2502 <http://lists.scsys.co.uk/pipermail/bignum/>
2504 • Subscribe/Unsubscribe
2506 <http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/bignum>
2508
2510 This program is free software; you may redistribute it and/or modify it
2511 under the same terms as Perl itself.
2512
2514 Math::BigFloat and Math::BigRat as well as the backends
2515 Math::BigInt::FastCalc, Math::BigInt::GMP, and Math::BigInt::Pari.
2516 The pragmas bignum, bigint and bigrat also might be of interest because
2518 they solve the autoupgrading/downgrading issue, at least partly.
2519
2521 • Mark Biggar, overloaded interface by Ilya Zakharevich, 1996-2001.
2522 • Completely rewritten by Tels <http://bloodgate.com>, 2001-2008.
2524 • Florian Ragwitz <flora@cpan.org>, 2010.
2526 • Peter John Acklam <pjacklam@gmail.com>, 2011-.
2528 Many people contributed in one or more ways to the final beast, see the
2530 file CREDITS for an (incomplete) list. If you miss your name, please
2531 drop me a mail. Thank you!
2532perl v5.34.1 2022-04-13 Math::BigInt(3)