1bigint(3) User Contributed Perl Documentation bigint(3)
2
6 bigint - transparent big integer support for Perl
7
9 use bigint;
10 $x = 2 + 4.5; # Math::BigInt 6
12 print 2 ** 512; # Math::BigInt 134...096
13 print inf + 42; # Math::BigInt inf
14 print NaN * 7; # Math::BigInt NaN
15 print hex("0x1234567890123490"); # Perl v5.10.0 or later
16 {
18 no bigint;
19 print 2 ** 256; # a normal Perl scalar now
20 }
21 # for older Perls, import into current package:
23 use bigint qw/hex oct/;
24 print hex("0x1234567890123490");
25 print oct("01234567890123490");
26
28 All numeric literal in the given scope are converted to Math::BigInt
29 objects. Numeric literal that represent non-integers are truncated to
30 an integer. All results of expressions are also truncated to integer.
31 All operators (including basic math operations) except the range
33 operator ".." are overloaded.
34 Unlike the integer pragma, the "bigint" pragma creates integers that
36 are only limited in their size by the available memory.
37 So, the following:
39 use bigint;
41 $x = 1234;
42 creates a Math::BigInt and stores a reference to in $x. This happens
44 transparently and behind your back, so to speak.
45 You can see this with the following:
47 perl -Mbigint -le 'print ref(1234)'
49 Since numbers are actually objects, you can call all the usual methods
51 from Math::BigFloat on them. This even works to some extent on
52 expressions:
53 perl -Mbigint -le '$x = 1234; print $x->bdec()'
55 perl -Mbigint -le 'print 1234->copy()->binc();'
56 perl -Mbigint -le 'print 1234->copy()->binc->badd(6);'
57 perl -Mbigint -le 'print +(1234)->copy()->binc()'
58 (Note that print doesn't do what you expect if the expression starts
60 with '(' hence the "+")
61 You can even chain the operations together as usual:
63 perl -Mbigint -le 'print 1234->copy()->binc->badd(6);'
65 1241
66 Please note the following does not work as expected (prints nothing),
68 since overloading of '..' is not yet possible in Perl (as of v5.8.0):
69 perl -Mbigint -le 'for (1..2) { print ref($_); }'
71 use integer vs. use bigint
73 There are some difference between "use integer" and "use bigint".
74 Whereas "use integer" is limited to what can be handled as a Perl
76 scalar, "use bigint" can handle arbitrarily large integers.
77 Also, "use integer" does affect assignments to variables and the return
79 value of some functions. "use bigint" truncates these results to
80 integer:
81 # perl -Minteger -wle 'print 3.2'
83 3.2
84 # perl -Minteger -wle 'print 3.2 + 0'
85 3
86 # perl -Mbigint -wle 'print 3.2'
87 3
88 # perl -Mbigint -wle 'print 3.2 + 0'
89 3
90 # perl -Mbigint -wle 'print exp(1) + 0'
92 2
93 # perl -Mbigint -wle 'print exp(1)'
94 2
95 # perl -Minteger -wle 'print exp(1)'
96 2.71828182845905
97 # perl -Minteger -wle 'print exp(1) + 0'
98 2
99 In practice this seldom makes a difference for small integers as parts
101 and results of expressions are truncated anyway, but this can, for
102 instance, affect the return value of subroutines:
103 sub three_integer { use integer; return 3.2; }
105 sub three_bigint { use bigint; return 3.2; }
106 print three_integer(), " ", three_bigint(),"\n"; # prints "3.2 3"
108 Options
110 "bigint" recognizes some options that can be passed while loading it
111 via "use". The following options exist:
112 a or accuracy
114 This sets the accuracy for all math operations. The argument must
115 be greater than or equal to zero. See Math::BigInt's bround()
116 method for details.
117 perl -Mbigint=a,2 -le 'print 12345+1'
119 Note that setting precision and accuracy at the same time is not
121 possible.
122 p or precision
124 This sets the precision for all math operations. The argument can
125 be any integer. Negative values mean a fixed number of digits after
126 the dot, and are ignored since all operations happen in integer
127 space. A positive value rounds to this digit left from the dot. 0
128 means round to integer. See Math::BigInt's bfround() method for
129 details.
130 perl -mbigint=p,5 -le 'print 123456789+123'
132 Note that setting precision and accuracy at the same time is not
134 possible.
135 t or trace
137 This enables a trace mode and is primarily for debugging.
138 l, lib, try, or only
140 Load a different math lib, see "Math Library".
141 perl -Mbigint=l,GMP -e 'print 2 ** 512'
143 perl -Mbigint=lib,GMP -e 'print 2 ** 512'
144 perl -Mbigint=try,GMP -e 'print 2 ** 512'
145 perl -Mbigint=only,GMP -e 'print 2 ** 512'
146 hex Override the built-in hex() method with a version that can handle
148 big numbers. This overrides it by exporting it to the current
149 package. Under Perl v5.10.0 and higher, this is not so necessary,
150 as hex() is lexically overridden in the current scope whenever the
151 "bigint" pragma is active.
152 oct Override the built-in oct() method with a version that can handle
154 big numbers. This overrides it by exporting it to the current
155 package. Under Perl v5.10.0 and higher, this is not so necessary,
156 as oct() is lexically overridden in the current scope whenever the
157 "bigint" pragma is active.
158 v or version
160 this prints out the name and version of the modules and then exits.
161 perl -Mbigint=v
163 Math Library
165 Math with the numbers is done (by default) by a backend library module
166 called Math::BigInt::Calc. The default is equivalent to saying:
167 use bigint lib => 'Calc';
169 you can change this by using:
171 use bigint lib => 'GMP';
173 The following would first try to find Math::BigInt::Foo, then
175 Math::BigInt::Bar, and if this also fails, revert to
176 Math::BigInt::Calc:
177 use bigint lib => 'Foo,Math::BigInt::Bar';
179 Using c<lib> warns if none of the specified libraries can be found and
181 Math::BigInt fell back to one of the default libraries. To suppress
182 this warning, use c<try> instead:
183 use bigint try => 'GMP';
185 If you want the code to die instead of falling back, use "only"
187 instead:
188 use bigint only => 'GMP';
190 Please see the respective module documentation for further details.
192 Method calls
194 Since all numbers are now objects, you can use all methods that are
195 part of the Math::BigInt API.
196 But a warning is in order. When using the following to make a copy of a
198 number, only a shallow copy will be made.
199 $x = 9; $y = $x;
201 $x = $y = 7;
202 Using the copy or the original with overloaded math is okay, e.g., the
204 following work:
205 $x = 9; $y = $x;
207 print $x + 1, " ", $y,"\n"; # prints 10 9
208 but calling any method that modifies the number directly will result in
210 both the original and the copy being destroyed:
211 $x = 9; $y = $x;
213 print $x->badd(1), " ", $y,"\n"; # prints 10 10
214 $x = 9; $y = $x;
216 print $x->binc(1), " ", $y,"\n"; # prints 10 10
217 $x = 9; $y = $x;
219 print $x->bmul(2), " ", $y,"\n"; # prints 18 18
220 Using methods that do not modify, but test that the contents works:
222 $x = 9; $y = $x;
224 $z = 9 if $x->is_zero(); # works fine
225 See the documentation about the copy constructor and "=" in overload,
227 as well as the documentation in Math::BigInt for further details.
228 Methods
230 inf()
231 A shortcut to return Math::BigInt->binf(). Useful because Perl does
232 not always handle bareword "inf" properly.
233 NaN()
235 A shortcut to return Math::BigInt->bnan(). Useful because Perl does
236 not always handle bareword "NaN" properly.
237 e
239 # perl -Mbigint=e -wle 'print e'
240 Returns Euler's number "e", aka exp(1). Note that under "bigint",
242 this is truncated to an integer, i.e., 2.
243 PI
245 # perl -Mbigint=PI -wle 'print PI'
246 Returns PI. Note that under "bigint", this is truncated to an
248 integer, i.e., 3.
249 bexp()
251 bexp($power, $accuracy);
252 Returns Euler's number "e" raised to the appropriate power, to the
254 wanted accuracy.
255 Note that under "bigint", the result is truncated to an integer.
257 Example:
259 # perl -Mbigint=bexp -wle 'print bexp(1,80)'
261 bpi()
263 bpi($accuracy);
264 Returns PI to the wanted accuracy. Note that under "bigint", this
266 is truncated to an integer, i.e., 3.
267 Example:
269 # perl -Mbigint=bpi -wle 'print bpi(80)'
271 accuracy()
273 Set or get the accuracy.
274 precision()
276 Set or get the precision.
277 round_mode()
279 Set or get the rounding mode.
280 div_scale()
282 Set or get the division scale.
283 in_effect()
285 use bigint;
286 print "in effect\n" if bigint::in_effect; # true
288 {
289 no bigint;
290 print "in effect\n" if bigint::in_effect; # false
291 }
292 Returns true or false if "bigint" is in effect in the current
294 scope.
295 This method only works on Perl v5.9.4 or later.
297
299 Hexadecimal, octal, and binary floating point literals
300 Perl (and this module) accepts hexadecimal, octal, and binary
301 floating point literals, but use them with care with Perl versions
302 before v5.32.0, because some versions of Perl silently give the
303 wrong result.
304 Operator vs literal overloading
306 "bigint" works by overloading handling of integer and floating
307 point literals, converting them to Math::BigInt objects.
308 This means that arithmetic involving only string values or string
310 literals are performed using Perl's built-in operators.
311 For example:
313 use bigint;
315 my $x = "900000000000000009";
316 my $y = "900000000000000007";
317 print $x - $y;
318 outputs 0 on default 32-bit builds, since "bigint" never sees the
320 string literals. To ensure the expression is all treated as
321 "Math::BigInt" objects, use a literal number in the expression:
322 print +(0+$x) - $y;
324 Ranges
326 Perl does not allow overloading of ranges, so you can neither
327 safely use ranges with "bigint" endpoints, nor is the iterator
328 variable a "Math::BigInt".
329 use 5.010;
331 for my $i (12..13) {
332 for my $j (20..21) {
333 say $i ** $j; # produces a floating-point number,
334 # not an object
335 }
336 }
337 in_effect()
339 This method only works on Perl v5.9.4 or later.
340 hex()/oct()
342 "bigint" overrides these routines with versions that can also
343 handle big integer values. Under Perl prior to version v5.9.4,
344 however, this will not happen unless you specifically ask for it
345 with the two import tags "hex" and "oct" - and then it will be
346 global and cannot be disabled inside a scope with "no bigint":
347 use bigint qw/hex oct/;
349 print hex("0x1234567890123456");
351 {
352 no bigint;
353 print hex("0x1234567890123456");
354 }
355 The second call to hex() will warn about a non-portable constant.
357 Compare this to:
359 use bigint;
361 # will warn only under Perl older than v5.9.4
363 print hex("0x1234567890123456");
364
366 Some cool command line examples to impress the Python crowd ;) You
367 might want to compare them to the results under -Mbigfloat or -Mbigrat:
368 perl -Mbigint -le 'print sqrt(33)'
370 perl -Mbigint -le 'print 2*255'
371 perl -Mbigint -le 'print 4.5+2*255'
372 perl -Mbigint -le 'print 123->is_odd()'
373 perl -Mbigint=l,GMP -le 'print 7 ** 7777'
374
376 Please report any bugs or feature requests to "bug-bignum at
377 rt.cpan.org", or through the web interface at
378 <https://rt.cpan.org/Ticket/Create.html?Queue=bignum> (requires login).
379 We will be notified, and then you'll automatically be notified of
380 progress on your bug as I make changes.
381
383 You can find documentation for this module with the perldoc command.
384 perldoc bigint
386 You can also look for information at:
388 • GitHub
390 <https://github.com/pjacklam/p5-bignum>
392 • RT: CPAN's request tracker
394 <https://rt.cpan.org/Dist/Display.html?Name=bignum>
396 • MetaCPAN
398 <https://metacpan.org/release/bignum>
400 • CPAN Testers Matrix
402 <http://matrix.cpantesters.org/?dist=bignum>
404 • CPAN Ratings
406 <https://cpanratings.perl.org/dist/bignum>
408
410 This program is free software; you may redistribute it and/or modify it
411 under the same terms as Perl itself.
412
414 bignum and bigrat.
415 Math::BigInt, Math::BigFloat, Math::BigRat and Math::Big as well as
417 Math::BigInt::FastCalc, Math::BigInt::Pari and Math::BigInt::GMP.
418
420 • (C) by Tels <http://bloodgate.com/> in early 2002 - 2007.
421 • Maintained by Peter John Acklam <pjacklam@gmail.com>, 2014-.
423perl v5.34.1 2022-04-13 bigint(3)