1bignum(3) User Contributed Perl Documentation bignum(3)
2
6 bignum - transparent big number support for Perl
7
9 use bignum;
10 $x = 2 + 4.5; # Math::BigFloat 6.5
12 print 2 ** 512 * 0.1; # Math::BigFloat 134...09.6
13 print 2 ** 512; # Math::BigInt 134...096
14 print inf + 42; # Math::BigInt inf
15 print NaN * 7; # Math::BigInt NaN
16 print hex("0x1234567890123490"); # Perl v5.10.0 or later
17 {
19 no bignum;
20 print 2 ** 256; # a normal Perl scalar now
21 }
22 # for older Perls, import into current package:
24 use bignum qw/hex oct/;
25 print hex("0x1234567890123490");
26 print oct("01234567890123490");
27
29 Literal numeric constants
30 By default, every literal integer becomes a Math::BigInt object, and
31 literal non-integer becomes a Math::BigFloat object. Whether a numeric
32 literal is considered an integer or non-integers depends only on the
33 value of the constant, not on how it is represented. For instance, the
34 constants 3.14e2 and 0x1.3ap8 become Math::BigInt objects, because they
35 both represent the integer value decimal 314.
36 The default "use bignum;" is equivalent to
38 use bignum downgrade => "Math::BigInt", upgrade => "Math::BigFloat";
40 The classes used for integers and non-integers can be set at compile
42 time with the "downgrade" and "upgrade" options, for example
43 # use Math::BigInt for integers and Math::BigRat for non-integers
45 use bignum upgrade => "Math::BigRat";
46 Note that disabling downgrading and upgrading does not affect how
48 numeric literals are converted to objects
49 # disable both downgrading and upgrading
51 use bignum downgrade => undef, upgrade => undef;
52 $x = 2.4; # becomes 2.4 as a Math::BigFloat
53 $y = 2; # becomes 2 as a Math::BigInt
54 Upgrading and downgrading
56 By default, when the result of a computation is an integer, an Inf, or
57 a NaN, the result is downgraded even when all the operands are
58 instances of the upgrade class.
59 use bignum;
61 $x = 2.4; # becomes 2.4 as a Math::BigFloat
62 $y = 1.2; # becomes 1.2 as a Math::BigFloat
63 $z = $x / $y; # becomes 2 as a Math::BigInt due to downgrading
64 Equivalently, by default, when the result of a computation is a finite
66 non-integer, the result is upgraded even when all the operands are
67 instances of the downgrade class.
68 use bignum;
70 $x = 7; # becomes 7 as a Math::BigInt
71 $y = 2; # becomes 2 as a Math::BigInt
72 $z = $x / $y; # becomes 3.5 as a Math::BigFloat due to upgrading
73 The classes used for downgrading and upgrading can be set at runtime
75 with the "downgrade()" and "upgrade()" methods, but see "CAVEATS"
76 below.
77 The upgrade and downgrade classes don't have to be Math::BigInt and
79 Math::BigFloat. For example, to use Math::BigRat as the upgrade class,
80 use
81 use bignum upgrade => "Math::BigRat";
83 $x = 2; # becomes 2 as a Math::BigInt
84 $y = 3.6; # becomes 18/5 as a Math::BigRat
85 The upgrade and downgrade classes can be modified at runtime
87 use bignum;
89 $x = 3; # becomes 3 as a Math::BigInt
90 $y = 2; # becomes 2 as a Math::BigInt
91 $z = $x / $y; # becomes 1.5 as a Math::BigFlaot
92 bignum -> upgrade("Math::BigRat");
94 $w = $x / $y; # becomes 3/2 as a Math::BigRat
95 Disabling downgrading doesn't change the fact that literal constant
97 integers are converted to the downgrade class, it only prevents
98 downgrading as a result of a computation. E.g.,
99 use bignum downgrade => undef;
101 $x = 2; # becomes 2 as a Math::BigInt
102 $y = 2.4; # becomes 2.4 as a Math::BigFloat
103 $z = 1.2; # becomes 1.2 as a Math::BigFloat
104 $w = $x / $y; # becomes 2 as a Math::BigFloat due to no downgrading
105 If you want all numeric literals, both integers and non-integers, to
107 become Math::BigFloat objects, use the bigfloat pragma.
108 Equivalently, disabling upgrading doesn't change the fact that literal
110 constant non-integers are converted to the upgrade class, it only
111 prevents upgrading as a result of a computation. E.g.,
112 use bignum upgrade => undef;
114 $x = 2.5; # becomes 2.5 as a Math::BigFloat
115 $y = 7; # becomes 7 as a Math::BigInt
116 $z = 2; # becomes 2 as a Math::BigInt
117 $w = $x / $y; # becomes 3 as a Math::BigInt due to no upgrading
118 If you want all numeric literals, both integers and non-integers, to
120 become Math::BigInt objects, use the bigint pragma.
121 You can even do
123 use bignum upgrade => "Math::BigRat", upgrade => undef;
125 which converts all integer literals to Math::BigInt objects and all
127 non-integer literals to Math::BigRat objects. However, when the result
128 of a computation involving two Math::BigInt objects results in a non-
129 integer (e.g., 7/2), the result will be truncted to a Math::BigInt
130 rather than being upgraded to a Math::BigRat, since upgrading is
131 disabled.
132 Overloading
134 Since all numeric literals become objects, you can call all the usual
135 methods from Math::BigInt and Math::BigFloat on them. This even works
136 to some extent on expressions:
137 perl -Mbignum -le '$x = 1234; print $x->bdec()'
139 perl -Mbignum -le 'print 1234->copy()->binc();'
140 perl -Mbignum -le 'print 1234->copy()->binc()->badd(6);'
141 Options
143 "bignum" recognizes some options that can be passed while loading it
144 via via "use". The following options exist:
145 a or accuracy
147 This sets the accuracy for all math operations. The argument must
148 be greater than or equal to zero. See Math::BigInt's bround()
149 method for details.
150 perl -Mbignum=a,50 -le 'print sqrt(20)'
152 Note that setting precision and accuracy at the same time is not
154 possible.
155 p or precision
157 This sets the precision for all math operations. The argument can
158 be any integer. Negative values mean a fixed number of digits after
159 the dot, while a positive value rounds to this digit left from the
160 dot. 0 means round to integer. See Math::BigInt's bfround() method
161 for details.
162 perl -Mbignum=p,-50 -le 'print sqrt(20)'
164 Note that setting precision and accuracy at the same time is not
166 possible.
167 l, lib, try, or only
169 Load a different math lib, see "Math Library".
170 perl -Mbignum=l,GMP -e 'print 2 ** 512'
172 perl -Mbignum=lib,GMP -e 'print 2 ** 512'
173 perl -Mbignum=try,GMP -e 'print 2 ** 512'
174 perl -Mbignum=only,GMP -e 'print 2 ** 512'
175 hex Override the built-in hex() method with a version that can handle
177 big numbers. This overrides it by exporting it to the current
178 package. Under Perl v5.10.0 and higher, this is not so necessary,
179 as hex() is lexically overridden in the current scope whenever the
180 "bignum" pragma is active.
181 oct Override the built-in oct() method with a version that can handle
183 big numbers. This overrides it by exporting it to the current
184 package. Under Perl v5.10.0 and higher, this is not so necessary,
185 as oct() is lexically overridden in the current scope whenever the
186 "bignum" pragma is active.
187 v or version
189 this prints out the name and version of the modules and then exits.
190 perl -Mbignum=v
192 Math Library
194 Math with the numbers is done (by default) by a backend library module
195 called Math::BigInt::Calc. The default is equivalent to saying:
196 use bignum lib => 'Calc';
198 you can change this by using:
200 use bignum lib => 'GMP';
202 The following would first try to find Math::BigInt::Foo, then
204 Math::BigInt::Bar, and if this also fails, revert to
205 Math::BigInt::Calc:
206 use bignum lib => 'Foo,Math::BigInt::Bar';
208 Using c<lib> warns if none of the specified libraries can be found and
210 Math::BigInt and Math::BigFloat fell back to one of the default
211 libraries. To suppress this warning, use "try" instead:
212 use bignum try => 'GMP';
214 If you want the code to die instead of falling back, use "only"
216 instead:
217 use bignum only => 'GMP';
219 Please see respective module documentation for further details.
221 Method calls
223 Since all numbers are now objects, you can use the methods that are
224 part of the Math::BigInt and Math::BigFloat API.
225 But a warning is in order. When using the following to make a copy of a
227 number, only a shallow copy will be made.
228 $x = 9; $y = $x;
230 $x = $y = 7;
231 Using the copy or the original with overloaded math is okay, e.g., the
233 following work:
234 $x = 9; $y = $x;
236 print $x + 1, " ", $y,"\n"; # prints 10 9
237 but calling any method that modifies the number directly will result in
239 both the original and the copy being destroyed:
240 $x = 9; $y = $x;
242 print $x->badd(1), " ", $y,"\n"; # prints 10 10
243 $x = 9; $y = $x;
245 print $x->binc(1), " ", $y,"\n"; # prints 10 10
246 $x = 9; $y = $x;
248 print $x->bmul(2), " ", $y,"\n"; # prints 18 18
249 Using methods that do not modify, but test that the contents works:
251 $x = 9; $y = $x;
253 $z = 9 if $x->is_zero(); # works fine
254 See the documentation about the copy constructor and "=" in overload,
256 as well as the documentation in Math::BigFloat for further details.
257 Methods
259 inf()
260 A shortcut to return "inf" as an object. Useful because Perl does
261 not always handle bareword "inf" properly.
262 NaN()
264 A shortcut to return "NaN" as an object. Useful because Perl does
265 not always handle bareword "NaN" properly.
266 e
268 # perl -Mbignum=e -wle 'print e'
269 Returns Euler's number "e", aka exp(1) (= 2.7182818284...).
271 PI
273 # perl -Mbignum=PI -wle 'print PI'
274 Returns PI (= 3.1415926532..).
276 bexp()
278 bexp($power, $accuracy);
279 Returns Euler's number "e" raised to the appropriate power, to the
281 wanted accuracy.
282 Example:
284 # perl -Mbignum=bexp -wle 'print bexp(1,80)'
286 bpi()
288 bpi($accuracy);
289 Returns PI to the wanted accuracy.
291 Example:
293 # perl -Mbignum=bpi -wle 'print bpi(80)'
295 accuracy()
297 Set or get the accuracy.
298 precision()
300 Set or get the precision.
301 round_mode()
303 Set or get the rounding mode.
304 div_scale()
306 Set or get the division scale.
307 upgrade()
309 Set or get the class that the downgrade class upgrades to, if any.
310 Set the upgrade class to "undef" to disable upgrading. See
311 "/CAVEATS" below.
312 downgrade()
314 Set or get the class that the upgrade class downgrades to, if any.
315 Set the downgrade class to "undef" to disable upgrading. See
316 "CAVEATS" below.
317 in_effect()
319 use bignum;
320 print "in effect\n" if bignum::in_effect; # true
322 {
323 no bignum;
324 print "in effect\n" if bignum::in_effect; # false
325 }
326 Returns true or false if "bignum" is in effect in the current
328 scope.
329 This method only works on Perl v5.9.4 or later.
331
333 The upgrade() and downgrade() methods
334 Note that setting both the upgrade and downgrade classes at runtime
335 with the "upgrade()" and "downgrade()" methods, might not do what
336 you expect:
337 # Assuming that downgrading and upgrading hasn't been modified so far, so
339 # the downgrade and upgrade classes are Math::BigInt and Math::BigFloat,
340 # respectively, the following sets the upgrade class to Math::BigRat, i.e.,
341 # makes Math::BigInt upgrade to Math::BigRat:
342 bignum -> upgrade("Math::BigRat");
344 # The following sets the downgrade class to Math::BigInt::Lite, i.e., makes
346 # the new upgrade class Math::BigRat downgrade to Math::BigInt::Lite
347 bignum -> downgrade("Math::BigInt::Lite");
349 # Note that at this point, it is still Math::BigInt, not Math::BigInt::Lite,
351 # that upgrades to Math::BigRat, so to get Math::BigInt::Lite to upgrade to
352 # Math::BigRat, we need to do the following (again):
353 bignum -> upgrade("Math::BigRat");
355 A simpler way to do this at runtime is to use import(),
357 bignum -> import(upgrade => "Math::BigRat",
359 downgrade => "Math::BigInt::Lite");
360 Hexadecimal, octal, and binary floating point literals
362 Perl (and this module) accepts hexadecimal, octal, and binary
363 floating point literals, but use them with care with Perl versions
364 before v5.32.0, because some versions of Perl silently give the
365 wrong result.
366 Operator vs literal overloading
368 "bigrat" works by overloading handling of integer and floating
369 point literals, converting them to Math::BigRat objects.
370 This means that arithmetic involving only string values or string
372 literals are performed using Perl's built-in operators.
373 For example:
375 use bigrat;
377 my $x = "900000000000000009";
378 my $y = "900000000000000007";
379 print $x - $y;
380 outputs 0 on default 32-bit builds, since "bignum" never sees the
382 string literals. To ensure the expression is all treated as
383 "Math::BigFloat" objects, use a literal number in the expression:
384 print +(0+$x) - $y;
386 Ranges
388 Perl does not allow overloading of ranges, so you can neither
389 safely use ranges with "bignum" endpoints, nor is the iterator
390 variable a "Math::BigFloat".
391 use 5.010;
393 for my $i (12..13) {
394 for my $j (20..21) {
395 say $i ** $j; # produces a floating-point number,
396 # not an object
397 }
398 }
399 in_effect()
401 This method only works on Perl v5.9.4 or later.
402 hex()/oct()
404 "bignum" overrides these routines with versions that can also
405 handle big integer values. Under Perl prior to version v5.9.4,
406 however, this will not happen unless you specifically ask for it
407 with the two import tags "hex" and "oct" - and then it will be
408 global and cannot be disabled inside a scope with "no bignum":
409 use bignum qw/hex oct/;
411 print hex("0x1234567890123456");
413 {
414 no bignum;
415 print hex("0x1234567890123456");
416 }
417 The second call to hex() will warn about a non-portable constant.
419 Compare this to:
421 use bignum;
423 # will warn only under Perl older than v5.9.4
425 print hex("0x1234567890123456");
426
428 Some cool command line examples to impress the Python crowd ;)
429 perl -Mbignum -le 'print sqrt(33)'
431 perl -Mbignum -le 'print 2**255'
432 perl -Mbignum -le 'print 4.5+2**255'
433 perl -Mbignum -le 'print 3/7 + 5/7 + 8/3'
434 perl -Mbignum -le 'print 123->is_odd()'
435 perl -Mbignum -le 'print log(2)'
436 perl -Mbignum -le 'print exp(1)'
437 perl -Mbignum -le 'print 2 ** 0.5'
438 perl -Mbignum=a,65 -le 'print 2 ** 0.2'
439 perl -Mbignum=l,GMP -le 'print 7 ** 7777'
440
442 Please report any bugs or feature requests to "bug-bignum at
443 rt.cpan.org", or through the web interface at
444 <https://rt.cpan.org/Ticket/Create.html?Queue=bignum> (requires login).
445 We will be notified, and then you'll automatically be notified of
446 progress on your bug as I make changes.
447
449 You can find documentation for this module with the perldoc command.
450 perldoc bignum
452 You can also look for information at:
454 • GitHub
456 <https://github.com/pjacklam/p5-bignum>
458 • RT: CPAN's request tracker
460 <https://rt.cpan.org/Dist/Display.html?Name=bignum>
462 • MetaCPAN
464 <https://metacpan.org/release/bignum>
466 • CPAN Testers Matrix
468 <http://matrix.cpantesters.org/?dist=bignum>
470 • CPAN Ratings
472 <https://cpanratings.perl.org/dist/bignum>
474
476 This program is free software; you may redistribute it and/or modify it
477 under the same terms as Perl itself.
478
480 bigint and bigrat.
481 Math::BigInt, Math::BigFloat, Math::BigRat and Math::Big as well as
483 Math::BigInt::FastCalc, Math::BigInt::Pari and Math::BigInt::GMP.
484
486 • (C) by Tels <http://bloodgate.com/> in early 2002 - 2007.
487 • Maintained by Peter John Acklam <pjacklam@gmail.com>, 2014-.
489perl v5.38.0 2023-07-21 bignum(3)