1bigint(3) User Contributed Perl Documentation bigint(3)
2
6 bigint - Transparent BigInteger support for Perl
7
9 use bigint;
10 $x = 2 + 4.5,"\n"; # BigInt 6
12 print 2 ** 512,"\n"; # really is what you think it is
13 print inf + 42,"\n"; # inf
14 print NaN * 7,"\n"; # NaN
15 print hex("0x1234567890123490"),"\n"; # Perl v5.10.0 or later
16 {
18 no bigint;
19 print 2 ** 256,"\n"; # a normal Perl scalar now
20 }
21 # Import into current package:
23 use bigint qw/hex oct/;
24 print hex("0x1234567890123490"),"\n";
25 print oct("01234567890123490"),"\n";
26
28 All operators (including basic math operations) except the range
29 operator ".." are overloaded. Integer constants are created as proper
30 BigInts.
31 Floating point constants are truncated to integer. All parts and
33 results of expressions are also truncated.
34 Unlike integer, this pragma creates integer constants that are only
36 limited in their size by the available memory and CPU time.
37 use integer vs. use bigint
39 There is one small difference between "use integer" and "use bigint":
40 the former will not affect assignments to variables and the return
41 value of some functions. "bigint" truncates these results to integer
42 too:
43 # perl -Minteger -wle 'print 3.2'
45 3.2
46 # perl -Minteger -wle 'print 3.2 + 0'
47 3
48 # perl -Mbigint -wle 'print 3.2'
49 3
50 # perl -Mbigint -wle 'print 3.2 + 0'
51 3
52 # perl -Mbigint -wle 'print exp(1) + 0'
54 2
55 # perl -Mbigint -wle 'print exp(1)'
56 2
57 # perl -Minteger -wle 'print exp(1)'
58 2.71828182845905
59 # perl -Minteger -wle 'print exp(1) + 0'
60 2
61 In practice this makes seldom a difference as parts and results of
63 expressions will be truncated anyway, but this can, for instance,
64 affect the return value of subroutines:
65 sub three_integer { use integer; return 3.2; }
67 sub three_bigint { use bigint; return 3.2; }
68 print three_integer(), " ", three_bigint(),"\n"; # prints "3.2 3"
70 Options
72 bigint recognizes some options that can be passed while loading it via
73 use. The options can (currently) be either a single letter form, or
74 the long form. The following options exist:
75 a or accuracy
77 This sets the accuracy for all math operations. The argument must be
78 greater than or equal to zero. See Math::BigInt's bround() function
79 for details.
80 perl -Mbigint=a,2 -le 'print 12345+1'
82 Note that setting precision and accuracy at the same time is not
84 possible.
85 p or precision
87 This sets the precision for all math operations. The argument can be
88 any integer. Negative values mean a fixed number of digits after the
89 dot, and are <B>ignored</B> since all operations happen in integer
90 space. A positive value rounds to this digit left from the dot. 0 or
91 1 mean round to integer and are ignore like negative values.
92 See Math::BigInt's bfround() function for details.
94 perl -Mbignum=p,5 -le 'print 123456789+123'
96 Note that setting precision and accuracy at the same time is not
98 possible.
99 t or trace
101 This enables a trace mode and is primarily for debugging bigint or
102 Math::BigInt.
103 hex
105 Override the built-in hex() method with a version that can handle big
106 integers. This overrides it by exporting it to the current package.
107 Under Perl v5.10.0 and higher, this is not so necessary, as hex() is
108 lexically overridden in the current scope whenever the bigint pragma
109 is active.
110 oct
112 Override the built-in oct() method with a version that can handle big
113 integers. This overrides it by exporting it to the current package.
114 Under Perl v5.10.0 and higher, this is not so necessary, as oct() is
115 lexically overridden in the current scope whenever the bigint pragma
116 is active.
117 l, lib, try or only
119 Load a different math lib, see "Math Library".
120 perl -Mbigint=lib,GMP -e 'print 2 ** 512'
122 perl -Mbigint=try,GMP -e 'print 2 ** 512'
123 perl -Mbigint=only,GMP -e 'print 2 ** 512'
124 Currently there is no way to specify more than one library on the
126 command line. This means the following does not work:
127 perl -Mbignum=l,GMP,Pari -e 'print 2 ** 512'
129 This will be hopefully fixed soon ;)
131 v or version
133 This prints out the name and version of all modules used and then
134 exits.
135 perl -Mbigint=v
137 Math Library
139 Math with the numbers is done (by default) by a module called
140 Math::BigInt::Calc. This is equivalent to saying:
141 use bigint lib => 'Calc';
143 You can change this by using:
145 use bignum lib => 'GMP';
147 The following would first try to find Math::BigInt::Foo, then
149 Math::BigInt::Bar, and when this also fails, revert to
150 Math::BigInt::Calc:
151 use bigint lib => 'Foo,Math::BigInt::Bar';
153 Using "lib" warns if none of the specified libraries can be found and
155 Math::BigInt did fall back to one of the default libraries. To
156 suppress this warning, use "try" instead:
157 use bignum try => 'GMP';
159 If you want the code to die instead of falling back, use "only"
161 instead:
162 use bignum only => 'GMP';
164 Please see respective module documentation for further details.
166 Internal Format
168 The numbers are stored as objects, and their internals might change at
169 anytime, especially between math operations. The objects also might
170 belong to different classes, like Math::BigInt, or Math::BigInt::Lite.
171 Mixing them together, even with normal scalars is not extraordinary,
172 but normal and expected.
173 You should not depend on the internal format, all accesses must go
175 through accessor methods. E.g. looking at $x->{sign} is not a good idea
176 since there is no guaranty that the object in question has such a hash
177 key, nor is a hash underneath at all.
178 Sign
180 The sign is either '+', '-', 'NaN', '+inf' or '-inf'. You can access
181 it with the sign() method.
182 A sign of 'NaN' is used to represent the result when input arguments
184 are not numbers or as a result of 0/0. '+inf' and '-inf' represent plus
185 respectively minus infinity. You will get '+inf' when dividing a
186 positive number by 0, and '-inf' when dividing any negative number by
187 0.
188 Method calls
190 Since all numbers are now objects, you can use all functions that are
191 part of the BigInt API. You can only use the bxxx() notation, and not
192 the fxxx() notation, though.
193 But a warning is in order. When using the following to make a copy of a
195 number, only a shallow copy will be made.
196 $x = 9; $y = $x;
198 $x = $y = 7;
199 Using the copy or the original with overloaded math is okay, e.g. the
201 following work:
202 $x = 9; $y = $x;
204 print $x + 1, " ", $y,"\n"; # prints 10 9
205 but calling any method that modifies the number directly will result in
207 both the original and the copy being destroyed:
208 $x = 9; $y = $x;
210 print $x->badd(1), " ", $y,"\n"; # prints 10 10
211 $x = 9; $y = $x;
213 print $x->binc(1), " ", $y,"\n"; # prints 10 10
214 $x = 9; $y = $x;
216 print $x->bmul(2), " ", $y,"\n"; # prints 18 18
217 Using methods that do not modify, but test that the contents works:
219 $x = 9; $y = $x;
221 $z = 9 if $x->is_zero(); # works fine
222 See the documentation about the copy constructor and "=" in overload,
224 as well as the documentation in BigInt for further details.
225 Methods
227 inf()
228 A shortcut to return Math::BigInt->binf(). Useful because Perl does
229 not always handle bareword "inf" properly.
230 NaN()
232 A shortcut to return Math::BigInt->bnan(). Useful because Perl does
233 not always handle bareword "NaN" properly.
234 e
236 # perl -Mbigint=e -wle 'print e'
237 Returns Euler's number "e", aka exp(1). Note that under bigint, this
239 is truncated to an integer, and hence simple '2'.
240 PI
242 # perl -Mbigint=PI -wle 'print PI'
243 Returns PI. Note that under bigint, this is truncated to an integer,
245 and hence simple '3'.
246 bexp()
248 bexp($power,$accuracy);
249 Returns Euler's number "e" raised to the appropriate power, to the
251 wanted accuracy.
252 Note that under bigint, the result is truncated to an integer.
254 Example:
256 # perl -Mbigint=bexp -wle 'print bexp(1,80)'
258 bpi()
260 bpi($accuracy);
261 Returns PI to the wanted accuracy. Note that under bigint, this is
263 truncated to an integer, and hence simple '3'.
264 Example:
266 # perl -Mbigint=bpi -wle 'print bpi(80)'
268 upgrade()
270 Return the class that numbers are upgraded to, is in fact returning
271 $Math::BigInt::upgrade.
272 in_effect()
274 use bigint;
275 print "in effect\n" if bigint::in_effect; # true
277 {
278 no bigint;
279 print "in effect\n" if bigint::in_effect; # false
280 }
281 Returns true or false if "bigint" is in effect in the current scope.
283 This method only works on Perl v5.9.4 or later.
285
287 Operator vs literal overloading
288 "bigint" works by overloading handling of integer and floating point
289 literals, converting them to Math::BigInt objects.
290 This means that arithmetic involving only string values or string
292 literals will be performed using Perl's built-in operators.
293 For example:
295 use bignum;
297 my $x = "900000000000000009";
298 my $y = "900000000000000007";
299 print $x - $y;
300 will output 0 on default 32-bit builds, since "bigint" never sees the
302 string literals. To ensure the expression is all treated as
303 "Math::BigInt" objects, use a literal number in the expression:
304 print +(0+$x) - $y;
306 ranges
308 Perl does not allow overloading of ranges, so you can neither safely
309 use ranges with bigint endpoints, nor is the iterator variable a
310 bigint.
311 use 5.010;
313 for my $i (12..13) {
314 for my $j (20..21) {
315 say $i ** $j; # produces a floating-point number,
316 # not a big integer
317 }
318 }
319 in_effect()
321 This method only works on Perl v5.9.4 or later.
322 hex()/oct()
324 "bigint" overrides these routines with versions that can also handle
325 big integer values. Under Perl prior to version v5.9.4, however, this
326 will not happen unless you specifically ask for it with the two
327 import tags "hex" and "oct" - and then it will be global and cannot
328 be disabled inside a scope with "no bigint":
329 use bigint qw/hex oct/;
331 print hex("0x1234567890123456");
333 {
334 no bigint;
335 print hex("0x1234567890123456");
336 }
337 The second call to hex() will warn about a non-portable constant.
339 Compare this to:
341 use bigint;
343 # will warn only under Perl older than v5.9.4
345 print hex("0x1234567890123456");
346
348 "bigint" is just a thin wrapper around various modules of the
349 Math::BigInt family. Think of it as the head of the family, who runs
350 the shop, and orders the others to do the work.
351 The following modules are currently used by bigint:
353 Math::BigInt::Lite (for speed, and only if it is loadable)
355 Math::BigInt
356
358 Some cool command line examples to impress the Python crowd ;) You
359 might want to compare them to the results under -Mbignum or -Mbigrat:
360 perl -Mbigint -le 'print sqrt(33)'
362 perl -Mbigint -le 'print 2*255'
363 perl -Mbigint -le 'print 4.5+2*255'
364 perl -Mbigint -le 'print 3/7 + 5/7 + 8/3'
365 perl -Mbigint -le 'print 123->is_odd()'
366 perl -Mbigint -le 'print log(2)'
367 perl -Mbigint -le 'print 2 ** 0.5'
368 perl -Mbigint=a,65 -le 'print 2 ** 0.2'
369 perl -Mbignum=a,65,l,GMP -le 'print 7 ** 7777'
370
372 For information about bugs and how to report them, see the BUGS section
373 in the documentation available with the perldoc command.
374 perldoc bignum
376
378 You can find documentation for this module with the perldoc command.
379 perldoc bigint
381 For more information, see the SUPPORT section in the documentation
383 available with the perldoc command.
384 perldoc bignum
386
388 This program is free software; you may redistribute it and/or modify it
389 under the same terms as Perl itself.
390
392 bignum and bigrat.
393 Math::BigInt, Math::BigFloat, Math::BigRat and Math::Big as well as
395 Math::BigInt::FastCalc, Math::BigInt::Pari and Math::BigInt::GMP.
396
398 • (C) by Tels <http://bloodgate.com/> in early 2002 - 2007.
399 • Maintained by Peter John Acklam <pjacklam@gmail.com>, 2014-.
401perl v5.34.0 2021-07-27 bigint(3)