7 @EXPORT = qw( inf NaN );
13 ##############################################################################
15 # These are all alike, and thus faked by AUTOLOAD
17 my @faked = qw/round_mode accuracy precision div_scale/;
18 use vars qw/$VERSION $AUTOLOAD $_lite/; # _lite for testsuite
24 $name =~ s/.*:://; # split package
26 foreach my $n (@faked)
30 *{"bignum::$name"} = sub
36 Math::BigInt->$name($_[0]);
37 return Math::BigFloat->$name($_[0]);
39 return Math::BigInt->$name();
45 # delayed load of Carp and avoid recursion
47 Carp::croak ("Can't call bignum\-\>$name, not a valid method");
52 $Math::BigInt::upgrade;
57 # this takes a binary/hexadecimal/octal constant string and returns it
58 # as string suitable for new. Basically it converts octal to decimal, and
59 # passes every thing else unmodified back.
62 return Math::BigInt->new($string) if $string =~ /^0[bx]/;
64 # so it must be an octal constant
65 Math::BigInt->from_oct($string);
70 $^H{bignum} = undef; # no longer in effect
71 overload::remove_constant('binary','','float','','integer');
76 my $level = shift || 0;
77 my $hinthash = (caller($level))[10];
85 $^H{bignum} = 1; # we are in effect
88 my $lib = ''; my $lib_kind = 'try';
89 my $upgrade = 'Math::BigFloat';
90 my $downgrade = 'Math::BigInt';
92 my @import = ( ':constant' ); # drive it w/ constant
93 my @a = @_; my $l = scalar @_; my $j = 0;
94 my ($ver,$trace); # version? trace?
95 my ($a,$p); # accuracy, precision
96 for ( my $i = 0; $i < $l ; $i++,$j++ )
98 if ($_[$i] eq 'upgrade')
100 # this causes upgrading
101 $upgrade = $_[$i+1]; # or undef to disable
102 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
103 splice @a, $j, $s; $j -= $s; $i++;
105 elsif ($_[$i] eq 'downgrade')
107 # this causes downgrading
108 $downgrade = $_[$i+1]; # or undef to disable
109 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
110 splice @a, $j, $s; $j -= $s; $i++;
112 elsif ($_[$i] =~ /^(l|lib|try|only)$/)
114 # this causes a different low lib to take care...
115 $lib_kind = $1; $lib_kind = 'lib' if $lib_kind eq 'l';
116 $lib = $_[$i+1] || '';
117 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
118 splice @a, $j, $s; $j -= $s; $i++;
120 elsif ($_[$i] =~ /^(a|accuracy)$/)
123 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
124 splice @a, $j, $s; $j -= $s; $i++;
126 elsif ($_[$i] =~ /^(p|precision)$/)
129 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
130 splice @a, $j, $s; $j -= $s; $i++;
132 elsif ($_[$i] =~ /^(v|version)$/)
135 splice @a, $j, 1; $j --;
137 elsif ($_[$i] =~ /^(t|trace)$/)
140 splice @a, $j, 1; $j --;
142 else { die "unknown option $_[$i]"; }
145 $_lite = 0; # using M::BI::L ?
148 require Math::BigInt::Trace; $class = 'Math::BigInt::Trace';
149 $upgrade = 'Math::BigFloat::Trace';
153 # see if we can find Math::BigInt::Lite
154 if (!defined $a && !defined $p) # rounding won't work to well
156 eval 'require Math::BigInt::Lite;';
159 @import = ( ); # :constant in Lite, not MBI
160 Math::BigInt::Lite->import( ':constant' );
161 $_lite= 1; # signal okay
164 require Math::BigInt if $_lite == 0; # not already loaded?
165 $class = 'Math::BigInt'; # regardless of MBIL or not
167 push @import, $lib_kind => $lib if $lib ne '';
168 # Math::BigInt::Trace or plain Math::BigInt
169 $class->import(@import, upgrade => $upgrade);
173 require Math::BigFloat::Trace; $class = 'Math::BigFloat::Trace';
174 $downgrade = 'Math::BigInt::Trace';
178 require Math::BigFloat; $class = 'Math::BigFloat';
180 $class->import(':constant','downgrade',$downgrade);
182 bignum->accuracy($a) if defined $a;
183 bignum->precision($p) if defined $p;
186 print "bignum\t\t\t v$VERSION\n";
187 print "Math::BigInt::Lite\t v$Math::BigInt::Lite::VERSION\n" if $_lite;
188 print "Math::BigInt\t\t v$Math::BigInt::VERSION";
189 my $config = Math::BigInt->config();
190 print " lib => $config->{lib} v$config->{lib_version}\n";
191 print "Math::BigFloat\t\t v$Math::BigFloat::VERSION\n";
195 # Take care of octal/hexadecimal constants
196 overload::constant binary => sub { _binary_constant(shift) };
198 # if another big* was already loaded:
199 my ($package) = caller();
202 if (!defined *{"${package}::inf"})
204 $self->export_to_level(1,$self,@a); # export inf and NaN
208 sub inf () { Math::BigInt->binf(); }
209 sub NaN () { Math::BigInt->bnan(); }
217 bignum - Transparent BigNumber support for Perl
223 $x = 2 + 4.5,"\n"; # BigFloat 6.5
224 print 2 ** 512 * 0.1,"\n"; # really is what you think it is
225 print inf * inf,"\n"; # prints inf
226 print NaN * 3,"\n"; # prints NaN
230 print 2 ** 256,"\n"; # a normal Perl scalar now
235 All operators (including basic math operations) are overloaded. Integer and
236 floating-point constants are created as proper BigInts or BigFloats,
243 at the top of your script, Math::BigFloat and Math::BigInt will be loaded
244 and any constant number will be converted to an object (Math::BigFloat for
245 floats like 3.1415 and Math::BigInt for integers like 1234).
247 So, the following line:
251 creates actually a Math::BigInt and stores a reference to in $x.
252 This happens transparently and behind your back, so to speak.
254 You can see this with the following:
256 perl -Mbignum -le 'print ref(1234)'
258 Don't worry if it says Math::BigInt::Lite, bignum and friends will use Lite
259 if it is installed since it is faster for some operations. It will be
260 automatically upgraded to BigInt whenever necessary:
262 perl -Mbignum -le 'print ref(2**255)'
264 This also means it is a bad idea to check for some specific package, since
265 the actual contents of $x might be something unexpected. Due to the
266 transparent way of bignum C<ref()> should not be necessary, anyway.
268 Since Math::BigInt and BigFloat also overload the normal math operations,
269 the following line will still work:
271 perl -Mbignum -le 'print ref(1234+1234)'
273 Since numbers are actually objects, you can call all the usual methods from
274 BigInt/BigFloat on them. This even works to some extent on expressions:
276 perl -Mbignum -le '$x = 1234; print $x->bdec()'
277 perl -Mbignum -le 'print 1234->binc();'
278 perl -Mbignum -le 'print 1234->binc->badd(6);'
279 perl -Mbignum -le 'print +(1234)->binc()'
281 (Note that print doesn't do what you expect if the expression starts with
284 You can even chain the operations together as usual:
286 perl -Mbignum -le 'print 1234->binc->badd(6);'
289 Under bignum (or bigint or bigrat), Perl will "upgrade" the numbers
290 appropriately. This means that:
292 perl -Mbignum -le 'print 1234+4.5'
295 will work correctly. These mixed cases don't do always work when using
296 Math::BigInt or Math::BigFloat alone, or at least not in the way normal Perl
299 If you do want to work with large integers like under C<use integer;>, try
302 perl -Mbigint -le 'print 1234.5+4.5'
305 There is also C<use bigrat;> which gives you big rationals:
307 perl -Mbigrat -le 'print 1234+4.1'
310 The entire upgrading/downgrading is still experimental and might not work
311 as you expect or may even have bugs.
313 You might get errors like this:
315 Can't use an undefined value as an ARRAY reference at
316 /usr/local/lib/perl5/5.8.0/Math/BigInt/Calc.pm line 864
318 This means somewhere a routine got a BigFloat/Lite but expected a BigInt (or
319 vice versa) and the upgrade/downgrad path was missing. This is a bug, please
320 report it so that we can fix it.
322 You might consider using just Math::BigInt or Math::BigFloat, since they
323 allow you finer control over what get's done in which module/space. For
324 instance, simple loop counters will be Math::BigInts under C<use bignum;> and
325 this is slower than keeping them as Perl scalars:
327 perl -Mbignum -le 'for ($i = 0; $i < 10; $i++) { print ref($i); }'
329 Please note the following does not work as expected (prints nothing), since
330 overloading of '..' is not yet possible in Perl (as of v5.8.0):
332 perl -Mbignum -le 'for (1..2) { print ref($_); }'
336 bignum recognizes some options that can be passed while loading it via use.
337 The options can (currently) be either a single letter form, or the long form.
338 The following options exist:
344 This sets the accuracy for all math operations. The argument must be greater
345 than or equal to zero. See Math::BigInt's bround() function for details.
347 perl -Mbignum=a,50 -le 'print sqrt(20)'
349 Note that setting precision and accurary at the same time is not possible.
353 This sets the precision for all math operations. The argument can be any
354 integer. Negative values mean a fixed number of digits after the dot, while
355 a positive value rounds to this digit left from the dot. 0 or 1 mean round to
356 integer. See Math::BigInt's bfround() function for details.
358 perl -Mbignum=p,-50 -le 'print sqrt(20)'
360 Note that setting precision and accurary at the same time is not possible.
364 This enables a trace mode and is primarily for debugging bignum or
365 Math::BigInt/Math::BigFloat.
369 Load a different math lib, see L<MATH LIBRARY>.
371 perl -Mbignum=l,GMP -e 'print 2 ** 512'
373 Currently there is no way to specify more than one library on the command
374 line. This means the following does not work:
376 perl -Mbignum=l,GMP,Pari -e 'print 2 ** 512'
378 This will be hopefully fixed soon ;)
382 This prints out the name and version of all modules used and then exits.
390 Beside import() and AUTOLOAD() there are only a few other methods.
392 Since all numbers are now objects, you can use all functions that are part of
393 the BigInt or BigFloat API. It is wise to use only the bxxx() notation, and not
394 the fxxx() notation, though. This makes it possible that the underlying object
395 might morph into a different class than BigFloat.
399 But a warning is in order. When using the following to make a copy of a number,
400 only a shallow copy will be made.
405 If you want to make a real copy, use the following:
409 Using the copy or the original with overloaded math is okay, e.g. the
413 print $x + 1, " ", $y,"\n"; # prints 10 9
415 but calling any method that modifies the number directly will result in
416 B<both> the original and the copy being destroyed:
419 print $x->badd(1), " ", $y,"\n"; # prints 10 10
422 print $x->binc(1), " ", $y,"\n"; # prints 10 10
425 print $x->bmul(2), " ", $y,"\n"; # prints 18 18
427 Using methods that do not modify, but testthe contents works:
430 $z = 9 if $x->is_zero(); # works fine
432 See the documentation about the copy constructor and C<=> in overload, as
433 well as the documentation in BigInt for further details.
439 A shortcut to return Math::BigInt->binf(). Useful because Perl does not always
440 handle bareword C<inf> properly.
444 A shortcut to return Math::BigInt->bnan(). Useful because Perl does not always
445 handle bareword C<NaN> properly.
449 Return the class that numbers are upgraded to, is in fact returning
450 C<$Math::BigInt::upgrade>.
456 print "in effect\n" if bignum::in_effect; # true
459 print "in effect\n" if bignum::in_effect; # false
462 Returns true or false if C<bignum> is in effect in the current scope.
464 This method only works on Perl v5.9.4 or later.
470 Math with the numbers is done (by default) by a module called
471 Math::BigInt::Calc. This is equivalent to saying:
473 use bignum lib => 'Calc';
475 You can change this by using:
477 use bignum lib => 'GMP';
479 The following would first try to find Math::BigInt::Foo, then
480 Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:
482 use bignum lib => 'Foo,Math::BigInt::Bar';
484 Please see respective module documentation for further details.
486 Using C<lib> warns if none of the specified libraries can be found and
487 L<Math::BigInt> did fall back to one of the default libraries.
488 To supress this warning, use C<try> instead:
490 use bignum try => 'GMP';
492 If you want the code to die instead of falling back, use C<only> instead:
494 use bignum only => 'GMP';
496 =head2 INTERNAL FORMAT
498 The numbers are stored as objects, and their internals might change at anytime,
499 especially between math operations. The objects also might belong to different
500 classes, like Math::BigInt, or Math::BigFLoat. Mixing them together, even
501 with normal scalars is not extraordinary, but normal and expected.
503 You should not depend on the internal format, all accesses must go through
504 accessor methods. E.g. looking at $x->{sign} is not a bright idea since there
505 is no guaranty that the object in question has such a hashkey, nor is a hash
510 The sign is either '+', '-', 'NaN', '+inf' or '-inf' and stored seperately.
511 You can access it with the sign() method.
513 A sign of 'NaN' is used to represent the result when input arguments are not
514 numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively
515 minus infinity. You will get '+inf' when dividing a positive number by 0, and
516 '-inf' when dividing any negative number by 0.
520 C<bignum> is just a thin wrapper around various modules of the Math::BigInt
521 family. Think of it as the head of the family, who runs the shop, and orders
522 the others to do the work.
524 The following modules are currently used by bignum:
526 Math::BigInt::Lite (for speed, and only if it is loadable)
532 Some cool command line examples to impress the Python crowd ;)
534 perl -Mbignum -le 'print sqrt(33)'
535 perl -Mbignum -le 'print 2*255'
536 perl -Mbignum -le 'print 4.5+2*255'
537 perl -Mbignum -le 'print 3/7 + 5/7 + 8/3'
538 perl -Mbignum -le 'print 123->is_odd()'
539 perl -Mbignum -le 'print log(2)'
540 perl -Mbignum -le 'print exp(1)'
541 perl -Mbignum -le 'print 2 ** 0.5'
542 perl -Mbignum=a,65 -le 'print 2 ** 0.2'
543 perl -Mbignum=a,65,l,GMP -le 'print 7 ** 7777'
547 This program is free software; you may redistribute it and/or modify it under
548 the same terms as Perl itself.
552 Especially L<bigrat> as in C<perl -Mbigrat -le 'print 1/3+1/4'>.
554 L<Math::BigFloat>, L<Math::BigInt>, L<Math::BigRat> and L<Math::Big> as well
555 as L<Math::BigInt::BitVect>, L<Math::BigInt::Pari> and L<Math::BigInt::GMP>.
559 (C) by Tels L<http://bloodgate.com/> in early 2002 - 2007.