7 @EXPORT_OK = qw( PI e );
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
97 # for newer Perls override hex() and oct() with a lexical version:
105 my $lib = ''; my $lib_kind = 'try';
106 my $upgrade = 'Math::BigFloat';
107 my $downgrade = 'Math::BigInt';
109 my @import = ( ':constant' ); # drive it w/ constant
110 my @a = @_; my $l = scalar @_; my $j = 0;
111 my ($ver,$trace); # version? trace?
112 my ($a,$p); # accuracy, precision
113 for ( my $i = 0; $i < $l ; $i++,$j++ )
115 if ($_[$i] eq 'upgrade')
117 # this causes upgrading
118 $upgrade = $_[$i+1]; # or undef to disable
119 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
120 splice @a, $j, $s; $j -= $s; $i++;
122 elsif ($_[$i] eq 'downgrade')
124 # this causes downgrading
125 $downgrade = $_[$i+1]; # or undef to disable
126 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
127 splice @a, $j, $s; $j -= $s; $i++;
129 elsif ($_[$i] =~ /^(l|lib|try|only)$/)
131 # this causes a different low lib to take care...
132 $lib_kind = $1; $lib_kind = 'lib' if $lib_kind eq 'l';
133 $lib = $_[$i+1] || '';
134 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
135 splice @a, $j, $s; $j -= $s; $i++;
137 elsif ($_[$i] =~ /^(a|accuracy)$/)
140 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
141 splice @a, $j, $s; $j -= $s; $i++;
143 elsif ($_[$i] =~ /^(p|precision)$/)
146 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
147 splice @a, $j, $s; $j -= $s; $i++;
149 elsif ($_[$i] =~ /^(v|version)$/)
152 splice @a, $j, 1; $j --;
154 elsif ($_[$i] =~ /^(t|trace)$/)
157 splice @a, $j, 1; $j --;
159 elsif ($_[$i] eq 'hex')
161 splice @a, $j, 1; $j --;
162 $hex = \&bigint::_hex_global;
164 elsif ($_[$i] eq 'oct')
166 splice @a, $j, 1; $j --;
167 $oct = \&bigint::_oct_global;
169 elsif ($_[$i] !~ /^(PI|e)\z/)
171 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
237 no warnings 'redefine';
238 *CORE::GLOBAL::oct = $oct if $oct;
239 *CORE::GLOBAL::hex = $hex if $hex;
243 sub PI () { Math::BigFloat::bpi(@_); }
244 sub e () { Math::BigFloat->bone->bexp(@_); }
252 bignum - Transparent BigNumber support for Perl
258 $x = 2 + 4.5,"\n"; # BigFloat 6.5
259 print 2 ** 512 * 0.1,"\n"; # really is what you think it is
260 print inf * inf,"\n"; # prints inf
261 print NaN * 3,"\n"; # prints NaN
265 print 2 ** 256,"\n"; # a normal Perl scalar now
268 # for older Perls, note that this will be global:
269 use bignum qw/hex oct/;
270 print hex("0x1234567890123490"),"\n";
271 print oct("01234567890123490"),"\n";
275 All operators (including basic math operations) are overloaded. Integer and
276 floating-point constants are created as proper BigInts or BigFloats,
283 at the top of your script, Math::BigFloat and Math::BigInt will be loaded
284 and any constant number will be converted to an object (Math::BigFloat for
285 floats like 3.1415 and Math::BigInt for integers like 1234).
287 So, the following line:
291 creates actually a Math::BigInt and stores a reference to in $x.
292 This happens transparently and behind your back, so to speak.
294 You can see this with the following:
296 perl -Mbignum -le 'print ref(1234)'
298 Don't worry if it says Math::BigInt::Lite, bignum and friends will use Lite
299 if it is installed since it is faster for some operations. It will be
300 automatically upgraded to BigInt whenever necessary:
302 perl -Mbignum -le 'print ref(2**255)'
304 This also means it is a bad idea to check for some specific package, since
305 the actual contents of $x might be something unexpected. Due to the
306 transparent way of bignum C<ref()> should not be necessary, anyway.
308 Since Math::BigInt and BigFloat also overload the normal math operations,
309 the following line will still work:
311 perl -Mbignum -le 'print ref(1234+1234)'
313 Since numbers are actually objects, you can call all the usual methods from
314 BigInt/BigFloat on them. This even works to some extent on expressions:
316 perl -Mbignum -le '$x = 1234; print $x->bdec()'
317 perl -Mbignum -le 'print 1234->copy()->binc();'
318 perl -Mbignum -le 'print 1234->copy()->binc->badd(6);'
319 perl -Mbignum -le 'print +(1234)->copy()->binc()'
321 (Note that print doesn't do what you expect if the expression starts with
324 You can even chain the operations together as usual:
326 perl -Mbignum -le 'print 1234->copy()->binc->badd(6);'
329 Under bignum (or bigint or bigrat), Perl will "upgrade" the numbers
330 appropriately. This means that:
332 perl -Mbignum -le 'print 1234+4.5'
335 will work correctly. These mixed cases don't do always work when using
336 Math::BigInt or Math::BigFloat alone, or at least not in the way normal Perl
339 If you do want to work with large integers like under C<use integer;>, try
342 perl -Mbigint -le 'print 1234.5+4.5'
345 There is also C<use bigrat;> which gives you big rationals:
347 perl -Mbigrat -le 'print 1234+4.1'
350 The entire upgrading/downgrading is still experimental and might not work
351 as you expect or may even have bugs. You might get errors like this:
353 Can't use an undefined value as an ARRAY reference at
354 /usr/local/lib/perl5/5.8.0/Math/BigInt/Calc.pm line 864
356 This means somewhere a routine got a BigFloat/Lite but expected a BigInt (or
357 vice versa) and the upgrade/downgrad path was missing. This is a bug, please
358 report it so that we can fix it.
360 You might consider using just Math::BigInt or Math::BigFloat, since they
361 allow you finer control over what get's done in which module/space. For
362 instance, simple loop counters will be Math::BigInts under C<use bignum;> and
363 this is slower than keeping them as Perl scalars:
365 perl -Mbignum -le 'for ($i = 0; $i < 10; $i++) { print ref($i); }'
367 Please note the following does not work as expected (prints nothing), since
368 overloading of '..' is not yet possible in Perl (as of v5.8.0):
370 perl -Mbignum -le 'for (1..2) { print ref($_); }'
374 bignum recognizes some options that can be passed while loading it via use.
375 The options can (currently) be either a single letter form, or the long form.
376 The following options exist:
382 This sets the accuracy for all math operations. The argument must be greater
383 than or equal to zero. See Math::BigInt's bround() function for details.
385 perl -Mbignum=a,50 -le 'print sqrt(20)'
387 Note that setting precision and accurary at the same time is not possible.
391 This sets the precision for all math operations. The argument can be any
392 integer. Negative values mean a fixed number of digits after the dot, while
393 a positive value rounds to this digit left from the dot. 0 or 1 mean round to
394 integer. See Math::BigInt's bfround() function for details.
396 perl -Mbignum=p,-50 -le 'print sqrt(20)'
398 Note that setting precision and accurary at the same time is not possible.
402 This enables a trace mode and is primarily for debugging bignum or
403 Math::BigInt/Math::BigFloat.
407 Load a different math lib, see L<MATH LIBRARY>.
409 perl -Mbignum=l,GMP -e 'print 2 ** 512'
411 Currently there is no way to specify more than one library on the command
412 line. This means the following does not work:
414 perl -Mbignum=l,GMP,Pari -e 'print 2 ** 512'
416 This will be hopefully fixed soon ;)
420 Override the build-in hex() method with a version that can handle big
421 integers. Note that under Perl older than v5.9.4, this will be global
422 and cannot be disabled with "no bigint;".
426 Override the build-in oct() method with a version that can handle big
427 integers. Note that under Perl older than v5.9.4, this will be global
428 and cannot be disabled with "no bigint;".
432 This prints out the name and version of all modules used and then exits.
440 Beside import() and AUTOLOAD() there are only a few other methods.
442 Since all numbers are now objects, you can use all functions that are part of
443 the BigInt or BigFloat API. It is wise to use only the bxxx() notation, and not
444 the fxxx() notation, though. This makes it possible that the underlying object
445 might morph into a different class than BigFloat.
449 But a warning is in order. When using the following to make a copy of a number,
450 only a shallow copy will be made.
455 If you want to make a real copy, use the following:
459 Using the copy or the original with overloaded math is okay, e.g. the
463 print $x + 1, " ", $y,"\n"; # prints 10 9
465 but calling any method that modifies the number directly will result in
466 B<both> the original and the copy being destroyed:
469 print $x->badd(1), " ", $y,"\n"; # prints 10 10
472 print $x->binc(1), " ", $y,"\n"; # prints 10 10
475 print $x->bmul(2), " ", $y,"\n"; # prints 18 18
477 Using methods that do not modify, but test the contents works:
480 $z = 9 if $x->is_zero(); # works fine
482 See the documentation about the copy constructor and C<=> in overload, as
483 well as the documentation in BigInt for further details.
489 A shortcut to return Math::BigInt->binf(). Useful because Perl does not always
490 handle bareword C<inf> properly.
494 A shortcut to return Math::BigInt->bnan(). Useful because Perl does not always
495 handle bareword C<NaN> properly.
499 Returns Euler's number C<e>, aka exp(1), to the given number of digits.
503 Returns PI to the given number of digits.
507 Return the class that numbers are upgraded to, is in fact returning
508 C<$Math::BigInt::upgrade>.
514 print "in effect\n" if bignum::in_effect; # true
517 print "in effect\n" if bignum::in_effect; # false
520 Returns true or false if C<bignum> is in effect in the current scope.
522 This method only works on Perl v5.9.4 or later.
528 Math with the numbers is done (by default) by a module called
529 Math::BigInt::Calc. This is equivalent to saying:
531 use bignum lib => 'Calc';
533 You can change this by using:
535 use bignum lib => 'GMP';
537 The following would first try to find Math::BigInt::Foo, then
538 Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:
540 use bignum lib => 'Foo,Math::BigInt::Bar';
542 Please see respective module documentation for further details.
544 Using C<lib> warns if none of the specified libraries can be found and
545 L<Math::BigInt> did fall back to one of the default libraries.
546 To supress this warning, use C<try> instead:
548 use bignum try => 'GMP';
550 If you want the code to die instead of falling back, use C<only> instead:
552 use bignum only => 'GMP';
554 =head2 INTERNAL FORMAT
556 The numbers are stored as objects, and their internals might change at anytime,
557 especially between math operations. The objects also might belong to different
558 classes, like Math::BigInt, or Math::BigFLoat. Mixing them together, even
559 with normal scalars is not extraordinary, but normal and expected.
561 You should not depend on the internal format, all accesses must go through
562 accessor methods. E.g. looking at $x->{sign} is not a bright idea since there
563 is no guaranty that the object in question has such a hashkey, nor is a hash
568 The sign is either '+', '-', 'NaN', '+inf' or '-inf' and stored seperately.
569 You can access it with the sign() method.
571 A sign of 'NaN' is used to represent the result when input arguments are not
572 numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively
573 minus infinity. You will get '+inf' when dividing a positive number by 0, and
574 '-inf' when dividing any negative number by 0.
582 This method only works on Perl v5.9.4 or later.
586 C<bigint> overrides these routines with versions that can also handle
587 big integer values. Under Perl prior to version v5.9.4, however, this
588 will not happen unless you specifically ask for it with the two
589 import tags "hex" and "oct" - and then it will be global and cannot be
590 disabled inside a scope with "no bigint":
592 use bigint qw/hex oct/;
594 print hex("0x1234567890123456");
597 print hex("0x1234567890123456");
600 The second call to hex() will warn about a non-portable constant.
606 # will warn only under older than v5.9.4
607 print hex("0x1234567890123456");
613 C<bignum> is just a thin wrapper around various modules of the Math::BigInt
614 family. Think of it as the head of the family, who runs the shop, and orders
615 the others to do the work.
617 The following modules are currently used by bignum:
619 Math::BigInt::Lite (for speed, and only if it is loadable)
625 Some cool command line examples to impress the Python crowd ;)
627 perl -Mbignum -le 'print sqrt(33)'
628 perl -Mbignum -le 'print 2*255'
629 perl -Mbignum -le 'print 4.5+2*255'
630 perl -Mbignum -le 'print 3/7 + 5/7 + 8/3'
631 perl -Mbignum -le 'print 123->is_odd()'
632 perl -Mbignum -le 'print log(2)'
633 perl -Mbignum -le 'print exp(1)'
634 perl -Mbignum -le 'print 2 ** 0.5'
635 perl -Mbignum=a,65 -le 'print 2 ** 0.2'
636 perl -Mbignum=a,65,l,GMP -le 'print 7 ** 7777'
640 This program is free software; you may redistribute it and/or modify it under
641 the same terms as Perl itself.
645 Especially L<bigrat> as in C<perl -Mbigrat -le 'print 1/3+1/4'>.
647 L<Math::BigFloat>, L<Math::BigInt>, L<Math::BigRat> and L<Math::Big> as well
648 as L<Math::BigInt::BitVect>, L<Math::BigInt::Pari> and L<Math::BigInt::GMP>.
652 (C) by Tels L<http://bloodgate.com/> in early 2002 - 2007.