8 @EXPORT = qw( inf NaN );
12 require bigint; # no "use" to avoid import being called
14 ##############################################################################
22 # These are all alike, and thus faked by AUTOLOAD
24 my @faked = qw/round_mode accuracy precision div_scale/;
25 use vars qw/$VERSION $AUTOLOAD $_lite/; # _lite for testsuite
31 $name =~ s/.*:://; # split package
33 foreach my $n (@faked)
37 *{"bignum::$name"} = sub
43 Math::BigInt->$name($_[0]);
44 return Math::BigFloat->$name($_[0]);
46 return Math::BigInt->$name();
52 # delayed load of Carp and avoid recursion
54 Carp::croak ("Can't call bignum\-\>$name, not a valid method");
59 $^H{bignum} = undef; # no longer in effect
60 overload::remove_constant('binary','','float','','integer');
65 my $level = shift || 0;
66 my $hinthash = (caller($level))[10];
70 #############################################################################
71 # the following two routines are for Perl 5.9.4 or later and are lexical
75 return CORE::hex($_[0]) unless in_effect(1);
77 $i = '0x'.$i unless $i =~ /^0x/;
78 Math::BigInt->new($i);
83 return CORE::oct($_[0]) unless in_effect(1);
85 return Math::BigInt->from_oct($i) if $i =~ /^0[0-7]/;
86 Math::BigInt->new($i);
93 $^H{bignum} = 1; # we are in effect
95 # for newer Perls override hex() and oct() with a lexical version:
98 no warnings 'redefine';
99 *CORE::GLOBAL::oct = \&_oct;
100 *CORE::GLOBAL::hex = \&_hex;
104 my $lib = ''; my $lib_kind = 'try';
105 my $upgrade = 'Math::BigFloat';
106 my $downgrade = 'Math::BigInt';
108 my @import = ( ':constant' ); # drive it w/ constant
109 my @a = @_; my $l = scalar @_; my $j = 0;
110 my ($ver,$trace); # version? trace?
111 my ($a,$p); # accuracy, precision
112 for ( my $i = 0; $i < $l ; $i++,$j++ )
114 if ($_[$i] eq 'upgrade')
116 # this causes upgrading
117 $upgrade = $_[$i+1]; # or undef to disable
118 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
119 splice @a, $j, $s; $j -= $s; $i++;
121 elsif ($_[$i] eq 'downgrade')
123 # this causes downgrading
124 $downgrade = $_[$i+1]; # or undef to disable
125 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
126 splice @a, $j, $s; $j -= $s; $i++;
128 elsif ($_[$i] =~ /^(l|lib|try|only)$/)
130 # this causes a different low lib to take care...
131 $lib_kind = $1; $lib_kind = 'lib' if $lib_kind eq 'l';
132 $lib = $_[$i+1] || '';
133 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
134 splice @a, $j, $s; $j -= $s; $i++;
136 elsif ($_[$i] =~ /^(a|accuracy)$/)
139 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
140 splice @a, $j, $s; $j -= $s; $i++;
142 elsif ($_[$i] =~ /^(p|precision)$/)
145 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
146 splice @a, $j, $s; $j -= $s; $i++;
148 elsif ($_[$i] =~ /^(v|version)$/)
151 splice @a, $j, 1; $j --;
153 elsif ($_[$i] =~ /^(t|trace)$/)
156 splice @a, $j, 1; $j --;
158 elsif ($_[$i] eq 'hex')
160 splice @a, $j, 1; $j --;
161 no warnings 'redefine';
162 # override with a global version
163 *CORE::GLOBAL::hex = \&bigint::_hex_global;
165 elsif ($_[$i] eq 'oct')
167 splice @a, $j, 1; $j --;
168 no warnings 'redefine';
169 # override with a global version
170 *CORE::GLOBAL::oct = \&bigint::_oct_global;
172 else { die "unknown option $_[$i]"; }
175 $_lite = 0; # using M::BI::L ?
178 require Math::BigInt::Trace; $class = 'Math::BigInt::Trace';
179 $upgrade = 'Math::BigFloat::Trace';
183 # see if we can find Math::BigInt::Lite
184 if (!defined $a && !defined $p) # rounding won't work to well
186 eval 'require Math::BigInt::Lite;';
189 @import = ( ); # :constant in Lite, not MBI
190 Math::BigInt::Lite->import( ':constant' );
191 $_lite= 1; # signal okay
194 require Math::BigInt if $_lite == 0; # not already loaded?
195 $class = 'Math::BigInt'; # regardless of MBIL or not
197 push @import, $lib_kind => $lib if $lib ne '';
198 # Math::BigInt::Trace or plain Math::BigInt
199 $class->import(@import, upgrade => $upgrade);
203 require Math::BigFloat::Trace; $class = 'Math::BigFloat::Trace';
204 $downgrade = 'Math::BigInt::Trace';
208 require Math::BigFloat; $class = 'Math::BigFloat';
210 $class->import(':constant','downgrade',$downgrade);
212 bignum->accuracy($a) if defined $a;
213 bignum->precision($p) if defined $p;
216 print "bignum\t\t\t v$VERSION\n";
217 print "Math::BigInt::Lite\t v$Math::BigInt::Lite::VERSION\n" if $_lite;
218 print "Math::BigInt\t\t v$Math::BigInt::VERSION";
219 my $config = Math::BigInt->config();
220 print " lib => $config->{lib} v$config->{lib_version}\n";
221 print "Math::BigFloat\t\t v$Math::BigFloat::VERSION\n";
225 # Take care of octal/hexadecimal constants
226 overload::constant binary => sub { bigint::_binary_constant(shift) };
228 # if another big* was already loaded:
229 my ($package) = caller();
232 if (!defined *{"${package}::inf"})
234 $self->export_to_level(1,$self,@a); # export inf and NaN
244 bignum - Transparent BigNumber support for Perl
250 $x = 2 + 4.5,"\n"; # BigFloat 6.5
251 print 2 ** 512 * 0.1,"\n"; # really is what you think it is
252 print inf * inf,"\n"; # prints inf
253 print NaN * 3,"\n"; # prints NaN
257 print 2 ** 256,"\n"; # a normal Perl scalar now
260 # for older Perls, note that this will be global:
261 use bignum qw/hex oct/;
262 print hex("0x1234567890123490"),"\n";
263 print oct("01234567890123490"),"\n";
267 All operators (including basic math operations) are overloaded. Integer and
268 floating-point constants are created as proper BigInts or BigFloats,
275 at the top of your script, Math::BigFloat and Math::BigInt will be loaded
276 and any constant number will be converted to an object (Math::BigFloat for
277 floats like 3.1415 and Math::BigInt for integers like 1234).
279 So, the following line:
283 creates actually a Math::BigInt and stores a reference to in $x.
284 This happens transparently and behind your back, so to speak.
286 You can see this with the following:
288 perl -Mbignum -le 'print ref(1234)'
290 Don't worry if it says Math::BigInt::Lite, bignum and friends will use Lite
291 if it is installed since it is faster for some operations. It will be
292 automatically upgraded to BigInt whenever necessary:
294 perl -Mbignum -le 'print ref(2**255)'
296 This also means it is a bad idea to check for some specific package, since
297 the actual contents of $x might be something unexpected. Due to the
298 transparent way of bignum C<ref()> should not be necessary, anyway.
300 Since Math::BigInt and BigFloat also overload the normal math operations,
301 the following line will still work:
303 perl -Mbignum -le 'print ref(1234+1234)'
305 Since numbers are actually objects, you can call all the usual methods from
306 BigInt/BigFloat on them. This even works to some extent on expressions:
308 perl -Mbignum -le '$x = 1234; print $x->bdec()'
309 perl -Mbignum -le 'print 1234->copy()->binc();'
310 perl -Mbignum -le 'print 1234->copy()->binc->badd(6);'
311 perl -Mbignum -le 'print +(1234)->copy()->binc()'
313 (Note that print doesn't do what you expect if the expression starts with
316 You can even chain the operations together as usual:
318 perl -Mbignum -le 'print 1234->copy()->binc->badd(6);'
321 Under bignum (or bigint or bigrat), Perl will "upgrade" the numbers
322 appropriately. This means that:
324 perl -Mbignum -le 'print 1234+4.5'
327 will work correctly. These mixed cases don't do always work when using
328 Math::BigInt or Math::BigFloat alone, or at least not in the way normal Perl
331 If you do want to work with large integers like under C<use integer;>, try
334 perl -Mbigint -le 'print 1234.5+4.5'
337 There is also C<use bigrat;> which gives you big rationals:
339 perl -Mbigrat -le 'print 1234+4.1'
342 The entire upgrading/downgrading is still experimental and might not work
343 as you expect or may even have bugs. You might get errors like this:
345 Can't use an undefined value as an ARRAY reference at
346 /usr/local/lib/perl5/5.8.0/Math/BigInt/Calc.pm line 864
348 This means somewhere a routine got a BigFloat/Lite but expected a BigInt (or
349 vice versa) and the upgrade/downgrad path was missing. This is a bug, please
350 report it so that we can fix it.
352 You might consider using just Math::BigInt or Math::BigFloat, since they
353 allow you finer control over what get's done in which module/space. For
354 instance, simple loop counters will be Math::BigInts under C<use bignum;> and
355 this is slower than keeping them as Perl scalars:
357 perl -Mbignum -le 'for ($i = 0; $i < 10; $i++) { print ref($i); }'
359 Please note the following does not work as expected (prints nothing), since
360 overloading of '..' is not yet possible in Perl (as of v5.8.0):
362 perl -Mbignum -le 'for (1..2) { print ref($_); }'
366 bignum recognizes some options that can be passed while loading it via use.
367 The options can (currently) be either a single letter form, or the long form.
368 The following options exist:
374 This sets the accuracy for all math operations. The argument must be greater
375 than or equal to zero. See Math::BigInt's bround() function for details.
377 perl -Mbignum=a,50 -le 'print sqrt(20)'
379 Note that setting precision and accurary at the same time is not possible.
383 This sets the precision for all math operations. The argument can be any
384 integer. Negative values mean a fixed number of digits after the dot, while
385 a positive value rounds to this digit left from the dot. 0 or 1 mean round to
386 integer. See Math::BigInt's bfround() function for details.
388 perl -Mbignum=p,-50 -le 'print sqrt(20)'
390 Note that setting precision and accurary at the same time is not possible.
394 This enables a trace mode and is primarily for debugging bignum or
395 Math::BigInt/Math::BigFloat.
399 Load a different math lib, see L<MATH LIBRARY>.
401 perl -Mbignum=l,GMP -e 'print 2 ** 512'
403 Currently there is no way to specify more than one library on the command
404 line. This means the following does not work:
406 perl -Mbignum=l,GMP,Pari -e 'print 2 ** 512'
408 This will be hopefully fixed soon ;)
412 Override the build-in hex() method with a version that can handle big
413 integers. Note that under Perl older than v5.9.4, this will be global
414 and cannot be disabled with "no bigint;".
418 Override the build-in oct() method with a version that can handle big
419 integers. Note that under Perl older than v5.9.4, this will be global
420 and cannot be disabled with "no bigint;".
424 This prints out the name and version of all modules used and then exits.
432 Beside import() and AUTOLOAD() there are only a few other methods.
434 Since all numbers are now objects, you can use all functions that are part of
435 the BigInt or BigFloat API. It is wise to use only the bxxx() notation, and not
436 the fxxx() notation, though. This makes it possible that the underlying object
437 might morph into a different class than BigFloat.
441 But a warning is in order. When using the following to make a copy of a number,
442 only a shallow copy will be made.
447 If you want to make a real copy, use the following:
451 Using the copy or the original with overloaded math is okay, e.g. the
455 print $x + 1, " ", $y,"\n"; # prints 10 9
457 but calling any method that modifies the number directly will result in
458 B<both> the original and the copy being destroyed:
461 print $x->badd(1), " ", $y,"\n"; # prints 10 10
464 print $x->binc(1), " ", $y,"\n"; # prints 10 10
467 print $x->bmul(2), " ", $y,"\n"; # prints 18 18
469 Using methods that do not modify, but test the contents works:
472 $z = 9 if $x->is_zero(); # works fine
474 See the documentation about the copy constructor and C<=> in overload, as
475 well as the documentation in BigInt for further details.
481 A shortcut to return Math::BigInt->binf(). Useful because Perl does not always
482 handle bareword C<inf> properly.
486 A shortcut to return Math::BigInt->bnan(). Useful because Perl does not always
487 handle bareword C<NaN> properly.
491 Return the class that numbers are upgraded to, is in fact returning
492 C<$Math::BigInt::upgrade>.
498 print "in effect\n" if bignum::in_effect; # true
501 print "in effect\n" if bignum::in_effect; # false
504 Returns true or false if C<bignum> is in effect in the current scope.
506 This method only works on Perl v5.9.4 or later.
512 Math with the numbers is done (by default) by a module called
513 Math::BigInt::Calc. This is equivalent to saying:
515 use bignum lib => 'Calc';
517 You can change this by using:
519 use bignum lib => 'GMP';
521 The following would first try to find Math::BigInt::Foo, then
522 Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:
524 use bignum lib => 'Foo,Math::BigInt::Bar';
526 Please see respective module documentation for further details.
528 Using C<lib> warns if none of the specified libraries can be found and
529 L<Math::BigInt> did fall back to one of the default libraries.
530 To supress this warning, use C<try> instead:
532 use bignum try => 'GMP';
534 If you want the code to die instead of falling back, use C<only> instead:
536 use bignum only => 'GMP';
538 =head2 INTERNAL FORMAT
540 The numbers are stored as objects, and their internals might change at anytime,
541 especially between math operations. The objects also might belong to different
542 classes, like Math::BigInt, or Math::BigFLoat. Mixing them together, even
543 with normal scalars is not extraordinary, but normal and expected.
545 You should not depend on the internal format, all accesses must go through
546 accessor methods. E.g. looking at $x->{sign} is not a bright idea since there
547 is no guaranty that the object in question has such a hashkey, nor is a hash
552 The sign is either '+', '-', 'NaN', '+inf' or '-inf' and stored seperately.
553 You can access it with the sign() method.
555 A sign of 'NaN' is used to represent the result when input arguments are not
556 numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively
557 minus infinity. You will get '+inf' when dividing a positive number by 0, and
558 '-inf' when dividing any negative number by 0.
566 This method only works on Perl v5.9.4 or later.
570 C<bigint> overrides these routines with versions that can also handle
571 big integer values. Under Perl prior to version v5.9.4, however, this
572 will not happen unless you specifically ask for it with the two
573 import tags "hex" and "oct" - and then it will be global and cannot be
574 disabled inside a scope with "no bigint":
576 use bigint qw/hex oct/;
578 print hex("0x1234567890123456");
581 print hex("0x1234567890123456");
584 The second call to hex() will warn about a non-portable constant.
590 # will warn only under older than v5.9.4
591 print hex("0x1234567890123456");
597 C<bignum> is just a thin wrapper around various modules of the Math::BigInt
598 family. Think of it as the head of the family, who runs the shop, and orders
599 the others to do the work.
601 The following modules are currently used by bignum:
603 Math::BigInt::Lite (for speed, and only if it is loadable)
609 Some cool command line examples to impress the Python crowd ;)
611 perl -Mbignum -le 'print sqrt(33)'
612 perl -Mbignum -le 'print 2*255'
613 perl -Mbignum -le 'print 4.5+2*255'
614 perl -Mbignum -le 'print 3/7 + 5/7 + 8/3'
615 perl -Mbignum -le 'print 123->is_odd()'
616 perl -Mbignum -le 'print log(2)'
617 perl -Mbignum -le 'print exp(1)'
618 perl -Mbignum -le 'print 2 ** 0.5'
619 perl -Mbignum=a,65 -le 'print 2 ** 0.2'
620 perl -Mbignum=a,65,l,GMP -le 'print 7 ** 7777'
624 This program is free software; you may redistribute it and/or modify it under
625 the same terms as Perl itself.
629 Especially L<bigrat> as in C<perl -Mbigrat -le 'print 1/3+1/4'>.
631 L<Math::BigFloat>, L<Math::BigInt>, L<Math::BigRat> and L<Math::Big> as well
632 as L<Math::BigInt::BitVect>, L<Math::BigInt::Pari> and L<Math::BigInt::GMP>.
636 (C) by Tels L<http://bloodgate.com/> in early 2002 - 2007.