1bignum(3) User Contributed Perl Documentation bignum(3)
2
6 bignum - Transparent BigNumber support for Perl
7
9 use bignum;
10 $x = 2 + 4.5,"\n"; # BigFloat 6.5
12 print 2 ** 512 * 0.1,"\n"; # really is what you think it is
13 print inf * inf,"\n"; # prints inf
14 print NaN * 3,"\n"; # prints NaN
15 {
17 no bignum;
18 print 2 ** 256,"\n"; # a normal Perl scalar now
19 }
20 # for older Perls, import into current package:
22 use bignum qw/hex oct/;
23 print hex("0x1234567890123490"),"\n";
24 print oct("01234567890123490"),"\n";
25
27 All operators (including basic math operations) are overloaded. Integer
28 and floating-point constants are created as proper BigInts or
29 BigFloats, respectively.
30 If you do
32 use bignum;
34 at the top of your script, Math::BigFloat and Math::BigInt will be
36 loaded and any constant number will be converted to an object
37 (Math::BigFloat for floats like 3.1415 and Math::BigInt for integers
38 like 1234).
39 So, the following line:
41 $x = 1234;
43 creates actually a Math::BigInt and stores a reference to in $x. This
45 happens transparently and behind your back, so to speak.
46 You can see this with the following:
48 perl -Mbignum -le 'print ref(1234)'
50 Don't worry if it says Math::BigInt::Lite, bignum and friends will use
52 Lite if it is installed since it is faster for some operations. It will
53 be automatically upgraded to BigInt whenever necessary:
54 perl -Mbignum -le 'print ref(2**255)'
56 This also means it is a bad idea to check for some specific package,
58 since the actual contents of $x might be something unexpected. Due to
59 the transparent way of bignum "ref()" should not be necessary, anyway.
60 Since Math::BigInt and BigFloat also overload the normal math
62 operations, the following line will still work:
63 perl -Mbignum -le 'print ref(1234+1234)'
65 Since numbers are actually objects, you can call all the usual methods
67 from BigInt/BigFloat on them. This even works to some extent on
68 expressions:
69 perl -Mbignum -le '$x = 1234; print $x->bdec()'
71 perl -Mbignum -le 'print 1234->copy()->binc();'
72 perl -Mbignum -le 'print 1234->copy()->binc->badd(6);'
73 perl -Mbignum -le 'print +(1234)->copy()->binc()'
74 (Note that print doesn't do what you expect if the expression starts
76 with '(' hence the "+")
77 You can even chain the operations together as usual:
79 perl -Mbignum -le 'print 1234->copy()->binc->badd(6);'
81 1241
82 Under bignum (or bigint or bigrat), Perl will "upgrade" the numbers
84 appropriately. This means that:
85 perl -Mbignum -le 'print 1234+4.5'
87 1238.5
88 will work correctly. These mixed cases don't do always work when using
90 Math::BigInt or Math::BigFloat alone, or at least not in the way normal
91 Perl scalars work.
92 If you do want to work with large integers like under "use integer;",
94 try "use bigint;":
95 perl -Mbigint -le 'print 1234.5+4.5'
97 1238
98 There is also "use bigrat;" which gives you big rationals:
100 perl -Mbigrat -le 'print 1234+4.1'
102 12381/10
103 The entire upgrading/downgrading is still experimental and might not
105 work as you expect or may even have bugs. You might get errors like
106 this:
107 Can't use an undefined value as an ARRAY reference at
109 /usr/local/lib/perl5/5.8.0/Math/BigInt/Calc.pm line 864
110 This means somewhere a routine got a BigFloat/Lite but expected a
112 BigInt (or vice versa) and the upgrade/downgrad path was missing. This
113 is a bug, please report it so that we can fix it.
114 You might consider using just Math::BigInt or Math::BigFloat, since
116 they allow you finer control over what get's done in which
117 module/space. For instance, simple loop counters will be Math::BigInts
118 under "use bignum;" and this is slower than keeping them as Perl
119 scalars:
120 perl -Mbignum -le 'for ($i = 0; $i < 10; $i++) { print ref($i); }'
122 Please note the following does not work as expected (prints nothing),
124 since overloading of '..' is not yet possible in Perl (as of v5.8.0):
125 perl -Mbignum -le 'for (1..2) { print ref($_); }'
127 Options
129 bignum recognizes some options that can be passed while loading it via
130 use. The options can (currently) be either a single letter form, or
131 the long form. The following options exist:
132 a or accuracy
134 This sets the accuracy for all math operations. The argument must be
135 greater than or equal to zero. See Math::BigInt's bround() function
136 for details.
137 perl -Mbignum=a,50 -le 'print sqrt(20)'
139 Note that setting precision and accuracy at the same time is not
141 possible.
142 p or precision
144 This sets the precision for all math operations. The argument can be
145 any integer. Negative values mean a fixed number of digits after the
146 dot, while a positive value rounds to this digit left from the dot. 0
147 or 1 mean round to integer. See Math::BigInt's bfround() function for
148 details.
149 perl -Mbignum=p,-50 -le 'print sqrt(20)'
151 Note that setting precision and accuracy at the same time is not
153 possible.
154 t or trace
156 This enables a trace mode and is primarily for debugging bignum or
157 Math::BigInt/Math::BigFloat.
158 l or lib
160 Load a different math lib, see "Math Library".
161 perl -Mbignum=l,GMP -e 'print 2 ** 512'
163 Currently there is no way to specify more than one library on the
165 command line. This means the following does not work:
166 perl -Mbignum=l,GMP,Pari -e 'print 2 ** 512'
168 This will be hopefully fixed soon ;)
170 hex
172 Override the built-in hex() method with a version that can handle big
173 numbers. This overrides it by exporting it to the current package.
174 Under Perl v5.10.0 and higher, this is not so necessary, as hex() is
175 lexically overridden in the current scope whenever the bignum pragma
176 is active.
177 oct
179 Override the built-in oct() method with a version that can handle big
180 numbers. This overrides it by exporting it to the current package.
181 Under Perl v5.10.0 and higher, this is not so necessary, as oct() is
182 lexically overridden in the current scope whenever the bigint pragma
183 is active.
184 v or version
186 This prints out the name and version of all modules used and then
187 exits.
188 perl -Mbignum=v
190 Methods
192 Beside import() and AUTOLOAD() there are only a few other methods.
193 Since all numbers are now objects, you can use all functions that are
195 part of the BigInt or BigFloat API. It is wise to use only the bxxx()
196 notation, and not the fxxx() notation, though. This makes it possible
197 that the underlying object might morph into a different class than
198 BigFloat.
199 Caveats
201 But a warning is in order. When using the following to make a copy of a
202 number, only a shallow copy will be made.
203 $x = 9; $y = $x;
205 $x = $y = 7;
206 If you want to make a real copy, use the following:
208 $y = $x->copy();
210 Using the copy or the original with overloaded math is okay, e.g. the
212 following work:
213 $x = 9; $y = $x;
215 print $x + 1, " ", $y,"\n"; # prints 10 9
216 but calling any method that modifies the number directly will result in
218 both the original and the copy being destroyed:
219 $x = 9; $y = $x;
221 print $x->badd(1), " ", $y,"\n"; # prints 10 10
222 $x = 9; $y = $x;
224 print $x->binc(1), " ", $y,"\n"; # prints 10 10
225 $x = 9; $y = $x;
227 print $x->bmul(2), " ", $y,"\n"; # prints 18 18
228 Using methods that do not modify, but test the contents works:
230 $x = 9; $y = $x;
232 $z = 9 if $x->is_zero(); # works fine
233 See the documentation about the copy constructor and "=" in overload,
235 as well as the documentation in BigInt for further details.
236 inf()
238 A shortcut to return Math::BigInt->binf(). Useful because Perl does
239 not always handle bareword "inf" properly.
240 NaN()
242 A shortcut to return Math::BigInt->bnan(). Useful because Perl does
243 not always handle bareword "NaN" properly.
244 e
246 # perl -Mbignum=e -wle 'print e'
247 Returns Euler's number "e", aka exp(1).
249 PI()
251 # perl -Mbignum=PI -wle 'print PI'
252 Returns PI.
254 bexp()
256 bexp($power,$accuracy);
257 Returns Euler's number "e" raised to the appropriate power, to the
259 wanted accuracy.
260 Example:
262 # perl -Mbignum=bexp -wle 'print bexp(1,80)'
264 bpi()
266 bpi($accuracy);
267 Returns PI to the wanted accuracy.
269 Example:
271 # perl -Mbignum=bpi -wle 'print bpi(80)'
273 upgrade()
275 Return the class that numbers are upgraded to, is in fact returning
276 $Math::BigInt::upgrade.
277 in_effect()
279 use bignum;
280 print "in effect\n" if bignum::in_effect; # true
282 {
283 no bignum;
284 print "in effect\n" if bignum::in_effect; # false
285 }
286 Returns true or false if "bignum" is in effect in the current scope.
288 This method only works on Perl v5.9.4 or later.
290 Math Library
292 Math with the numbers is done (by default) by a module called
293 Math::BigInt::Calc. This is equivalent to saying:
294 use bignum lib => 'Calc';
296 You can change this by using:
298 use bignum lib => 'GMP';
300 The following would first try to find Math::BigInt::Foo, then
302 Math::BigInt::Bar, and when this also fails, revert to
303 Math::BigInt::Calc:
304 use bignum lib => 'Foo,Math::BigInt::Bar';
306 Please see respective module documentation for further details.
308 Using "lib" warns if none of the specified libraries can be found and
310 Math::BigInt did fall back to one of the default libraries. To
311 suppress this warning, use "try" instead:
312 use bignum try => 'GMP';
314 If you want the code to die instead of falling back, use "only"
316 instead:
317 use bignum only => 'GMP';
319 INTERNAL FORMAT
321 The numbers are stored as objects, and their internals might change at
322 anytime, especially between math operations. The objects also might
323 belong to different classes, like Math::BigInt, or Math::BigFloat.
324 Mixing them together, even with normal scalars is not extraordinary,
325 but normal and expected.
326 You should not depend on the internal format, all accesses must go
328 through accessor methods. E.g. looking at $x->{sign} is not a bright
329 idea since there is no guaranty that the object in question has such a
330 hashkey, nor is a hash underneath at all.
331 SIGN
333 The sign is either '+', '-', 'NaN', '+inf' or '-inf' and stored
334 separately. You can access it with the sign() method.
335 A sign of 'NaN' is used to represent the result when input arguments
337 are not numbers or as a result of 0/0. '+inf' and '-inf' represent plus
338 respectively minus infinity. You will get '+inf' when dividing a
339 positive number by 0, and '-inf' when dividing any negative number by
340 0.
341
343 Operator vs literal overloading
344 "bignum" works by overloading handling of integer and floating point
345 literals, converting them to Math::BigInt or Math::BigFloat objects.
346 This means that arithmetic involving only string values or string
348 literals will be performed using Perl's built-in operators.
349 For example:
351 use bignum;
353 my $x = "900000000000000009";
354 my $y = "900000000000000007";
355 print $x - $y;
356 will output 0 on default 32-bit builds, since "bigrat" never sees the
358 string literals. To ensure the expression is all treated as
359 "Math::BigInt" or "BigFloat" objects, use a literal number in the
360 expression:
361 print +(0+$x) - $y;
363 in_effect()
365 This method only works on Perl v5.9.4 or later.
366 hex()/oct()
368 "bigint" overrides these routines with versions that can also handle
369 big integer values. Under Perl prior to version v5.9.4, however, this
370 will not happen unless you specifically ask for it with the two
371 import tags "hex" and "oct" - and then it will be global and cannot
372 be disabled inside a scope with "no bigint":
373 use bigint qw/hex oct/;
375 print hex("0x1234567890123456");
377 {
378 no bigint;
379 print hex("0x1234567890123456");
380 }
381 The second call to hex() will warn about a non-portable constant.
383 Compare this to:
385 use bigint;
387 # will warn only under older than v5.9.4
389 print hex("0x1234567890123456");
390
392 "bignum" is just a thin wrapper around various modules of the
393 Math::BigInt family. Think of it as the head of the family, who runs
394 the shop, and orders the others to do the work.
395 The following modules are currently used by bignum:
397 Math::BigInt::Lite (for speed, and only if it is loadable)
399 Math::BigInt
400 Math::BigFloat
401
403 Some cool command line examples to impress the Python crowd ;)
404 perl -Mbignum -le 'print sqrt(33)'
406 perl -Mbignum -le 'print 2*255'
407 perl -Mbignum -le 'print 4.5+2*255'
408 perl -Mbignum -le 'print 3/7 + 5/7 + 8/3'
409 perl -Mbignum -le 'print 123->is_odd()'
410 perl -Mbignum -le 'print log(2)'
411 perl -Mbignum -le 'print exp(1)'
412 perl -Mbignum -le 'print 2 ** 0.5'
413 perl -Mbignum=a,65 -le 'print 2 ** 0.2'
414 perl -Mbignum=a,65,l,GMP -le 'print 7 ** 7777'
415
417 Please report any bugs or feature requests to "bug-math-bigint at
418 rt.cpan.org", or through the web interface at
419 <https://rt.cpan.org/Ticket/Create.html?Queue=bignum> (requires login).
420 We will be notified, and then you'll automatically be notified of
421 progress on your bug as I make changes.
422
424 You can find documentation for this module with the perldoc command.
425 perldoc bignum
427 You can also look for information at:
429 · RT: CPAN's request tracker
431 <https://rt.cpan.org/Public/Dist/Display.html?Name=bignum>
433 · AnnoCPAN: Annotated CPAN documentation
435 <http://annocpan.org/dist/bignum>
437 · CPAN Ratings
439 <http://cpanratings.perl.org/dist/bignum>
441 · Search CPAN
443 <http://search.cpan.org/dist/bignum/>
445 · CPAN Testers Matrix
447 <http://matrix.cpantesters.org/?dist=bignum>
449
451 This program is free software; you may redistribute it and/or modify it
452 under the same terms as Perl itself.
453
455 bigint and bigrat.
456 Math::BigInt, Math::BigFloat, Math::BigRat and Math::Big as well as
458 Math::BigInt::FastCalc, Math::BigInt::Pari and Math::BigInt::GMP.
459
461 · (C) by Tels <http://bloodgate.com/> in early 2002 - 2007.
462 · Maintained by Peter John Acklam <pjacklam@gmail.com<gt>, 2014-.
464perl v5.32.0 2020-07-28 bignum(3)