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");
56 # $Math::BigInt::upgrade = $_[0];
57 # $Math::BigFloat::upgrade = $_[0];
59 $Math::BigInt::upgrade;
64 # this takes a binary/hexadecimal/octal constant string and returns it
65 # as string suitable for new. Basically it converts octal to decimal, and
66 # passes every thing else unmodified back.
69 return Math::BigInt->new($string) if $string =~ /^0[bx]/;
71 # so it must be an octal constant
72 Math::BigInt->from_oct($string);
81 my $upgrade = 'Math::BigFloat';
82 my $downgrade = 'Math::BigInt';
84 my @import = ( ':constant' ); # drive it w/ constant
85 my @a = @_; my $l = scalar @_; my $j = 0;
86 my ($ver,$trace); # version? trace?
87 my ($a,$p); # accuracy, precision
88 for ( my $i = 0; $i < $l ; $i++,$j++ )
90 if ($_[$i] eq 'upgrade')
92 # this causes upgrading
93 $upgrade = $_[$i+1]; # or undef to disable
94 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
95 splice @a, $j, $s; $j -= $s; $i++;
97 elsif ($_[$i] eq 'downgrade')
99 # this causes downgrading
100 $downgrade = $_[$i+1]; # or undef to disable
101 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
102 splice @a, $j, $s; $j -= $s; $i++;
104 elsif ($_[$i] =~ /^(l|lib)$/)
106 # this causes a different low lib to take care...
107 $lib = $_[$i+1] || '';
108 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
109 splice @a, $j, $s; $j -= $s; $i++;
111 elsif ($_[$i] =~ /^(a|accuracy)$/)
114 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
115 splice @a, $j, $s; $j -= $s; $i++;
117 elsif ($_[$i] =~ /^(p|precision)$/)
120 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
121 splice @a, $j, $s; $j -= $s; $i++;
123 elsif ($_[$i] =~ /^(v|version)$/)
126 splice @a, $j, 1; $j --;
128 elsif ($_[$i] =~ /^(t|trace)$/)
131 splice @a, $j, 1; $j --;
133 else { die "unknown option $_[$i]"; }
136 $_lite = 0; # using M::BI::L ?
139 require Math::BigInt::Trace; $class = 'Math::BigInt::Trace';
140 $upgrade = 'Math::BigFloat::Trace';
144 # see if we can find Math::BigInt::Lite
145 if (!defined $a && !defined $p) # rounding won't work to well
147 eval 'require Math::BigInt::Lite;';
150 @import = ( ); # :constant in Lite, not MBI
151 Math::BigInt::Lite->import( ':constant' );
152 $_lite= 1; # signal okay
155 require Math::BigInt if $_lite == 0; # not already loaded?
156 $class = 'Math::BigInt'; # regardless of MBIL or not
158 push @import, 'try' => $lib if $lib ne '';
159 # Math::BigInt::Trace or plain Math::BigInt
160 $class->import(@import, upgrade => $upgrade);
164 require Math::BigFloat::Trace; $class = 'Math::BigFloat::Trace';
165 $downgrade = 'Math::BigInt::Trace';
169 require Math::BigFloat; $class = 'Math::BigFloat';
171 $class->import(':constant','downgrade',$downgrade);
173 bignum->accuracy($a) if defined $a;
174 bignum->precision($p) if defined $p;
177 print "bignum\t\t\t v$VERSION\n";
178 print "Math::BigInt::Lite\t v$Math::BigInt::Lite::VERSION\n" if $_lite;
179 print "Math::BigInt\t\t v$Math::BigInt::VERSION";
180 my $config = Math::BigInt->config();
181 print " lib => $config->{lib} v$config->{lib_version}\n";
182 print "Math::BigFloat\t\t v$Math::BigFloat::VERSION\n";
186 # Take care of octal/hexadecimal constants
187 overload::constant 'binary' => sub { _binary_constant(shift) };
189 $self->export_to_level(1,$self,@a); # export inf and NaN
192 sub inf () { Math::BigInt->binf(); }
193 sub NaN () { Math::BigInt->bnan(); }
201 bignum - Transparent BigNumber support for Perl
207 $x = 2 + 4.5,"\n"; # BigFloat 6.5
208 print 2 ** 512 * 0.1,"\n"; # really is what you think it is
209 print inf * inf,"\n"; # prints inf
210 print NaN * 3,"\n"; # prints NaN
214 All operators (including basic math operations) are overloaded. Integer and
215 floating-point constants are created as proper BigInts or BigFloats,
222 at the top of your script, Math::BigFloat and Math::BigInt will be loaded
223 and any constant number will be converted to an object (Math::BigFloat for
224 floats like 3.1415 and Math::BigInt for integers like 1234).
226 So, the following line:
230 creates actually a Math::BigInt and stores a reference to in $x.
231 This happens transparently and behind your back, so to speak.
233 You can see this with the following:
235 perl -Mbignum -le 'print ref(1234)'
237 Don't worry if it says Math::BigInt::Lite, bignum and friends will use Lite
238 if it is installed since it is faster for some operations. It will be
239 automatically upgraded to BigInt whenever necessary:
241 perl -Mbignum -le 'print ref(2**255)'
243 This also means it is a bad idea to check for some specific package, since
244 the actual contents of $x might be something unexpected. Due to the
245 transparent way of bignum C<ref()> should not be necessary, anyway.
247 Since Math::BigInt and BigFloat also overload the normal math operations,
248 the following line will still work:
250 perl -Mbignum -le 'print ref(1234+1234)'
252 Since numbers are actually objects, you can call all the usual methods from
253 BigInt/BigFloat on them. This even works to some extent on expressions:
255 perl -Mbignum -le '$x = 1234; print $x->bdec()'
256 perl -Mbignum -le 'print 1234->binc();'
257 perl -Mbignum -le 'print 1234->binc->badd(6);'
258 perl -Mbignum -le 'print +(1234)->binc()'
260 (Note that print doesn't do what you expect if the expression starts with
263 You can even chain the operations together as usual:
265 perl -Mbignum -le 'print 1234->binc->badd(6);'
268 Under bignum (or bigint or bigrat), Perl will "upgrade" the numbers
269 appropriately. This means that:
271 perl -Mbignum -le 'print 1234+4.5'
274 will work correctly. These mixed cases don't do always work when using
275 Math::BigInt or Math::BigFloat alone, or at least not in the way normal Perl
278 If you do want to work with large integers like under C<use integer;>, try
281 perl -Mbigint -le 'print 1234.5+4.5'
284 There is also C<use bigrat;> which gives you big rationals:
286 perl -Mbigrat -le 'print 1234+4.1'
289 The entire upgrading/downgrading is still experimental and might not work
290 as you expect or may even have bugs.
292 You might get errors like this:
294 Can't use an undefined value as an ARRAY reference at
295 /usr/local/lib/perl5/5.8.0/Math/BigInt/Calc.pm line 864
297 This means somewhere a routine got a BigFloat/Lite but expected a BigInt (or
298 vice versa) and the upgrade/downgrad path was missing. This is a bug, please
299 report it so that we can fix it.
301 You might consider using just Math::BigInt or Math::BigFloat, since they
302 allow you finer control over what get's done in which module/space. For
303 instance, simple loop counters will be Math::BigInts under C<use bignum;> and
304 this is slower than keeping them as Perl scalars:
306 perl -Mbignum -le 'for ($i = 0; $i < 10; $i++) { print ref($i); }'
308 Please note the following does not work as expected (prints nothing), since
309 overloading of '..' is not yet possible in Perl (as of v5.8.0):
311 perl -Mbignum -le 'for (1..2) { print ref($_); }'
315 bignum recognizes some options that can be passed while loading it via use.
316 The options can (currently) be either a single letter form, or the long form.
317 The following options exist:
323 This sets the accuracy for all math operations. The argument must be greater
324 than or equal to zero. See Math::BigInt's bround() function for details.
326 perl -Mbignum=a,50 -le 'print sqrt(20)'
328 Note that setting precision and accurary at the same time is not possible.
332 This sets the precision for all math operations. The argument can be any
333 integer. Negative values mean a fixed number of digits after the dot, while
334 a positive value rounds to this digit left from the dot. 0 or 1 mean round to
335 integer. See Math::BigInt's bfround() function for details.
337 perl -Mbignum=p,-50 -le 'print sqrt(20)'
339 Note that setting precision and accurary at the same time is not possible.
343 This enables a trace mode and is primarily for debugging bignum or
344 Math::BigInt/Math::BigFloat.
348 Load a different math lib, see L<MATH LIBRARY>.
350 perl -Mbignum=l,GMP -e 'print 2 ** 512'
352 Currently there is no way to specify more than one library on the command
353 line. This means the following does not work:
355 perl -Mbignum=l,GMP,Pari -e 'print 2 ** 512'
357 This will be hopefully fixed soon ;)
361 This prints out the name and version of all modules used and then exits.
369 Beside import() and AUTOLOAD() there are only a few other methods.
371 Since all numbers are now objects, you can use all functions that are part of
372 the BigInt or BigFloat API. It is wise to use only the bxxx() notation, and not
373 the fxxx() notation, though. This makes it possible that the underlying object
374 might morph into a different class than BigFloat.
378 But a warning is in order. When using the following to make a copy of a number,
379 only a shallow copy will be made.
384 If you want to make a real copy, use the following:
388 Using the copy or the original with overloaded math is okay, e.g. the
392 print $x + 1, " ", $y,"\n"; # prints 10 9
394 but calling any method that modifies the number directly will result in
395 B<both> the original and the copy being destroyed:
398 print $x->badd(1), " ", $y,"\n"; # prints 10 10
401 print $x->binc(1), " ", $y,"\n"; # prints 10 10
404 print $x->bmul(2), " ", $y,"\n"; # prints 18 18
406 Using methods that do not modify, but testthe contents works:
409 $z = 9 if $x->is_zero(); # works fine
411 See the documentation about the copy constructor and C<=> in overload, as
412 well as the documentation in BigInt for further details.
418 A shortcut to return Math::BigInt->binf(). Useful because Perl does not always
419 handle bareword C<inf> properly.
423 A shortcut to return Math::BigInt->bnan(). Useful because Perl does not always
424 handle bareword C<NaN> properly.
428 Return the class that numbers are upgraded to, is in fact returning
429 C<$Math::BigInt::upgrade>.
435 Math with the numbers is done (by default) by a module called
436 Math::BigInt::Calc. This is equivalent to saying:
438 use bignum lib => 'Calc';
440 You can change this by using:
442 use bignum lib => 'BitVect';
444 The following would first try to find Math::BigInt::Foo, then
445 Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:
447 use bignum lib => 'Foo,Math::BigInt::Bar';
449 Please see respective module documentation for further details.
451 =head2 INTERNAL FORMAT
453 The numbers are stored as objects, and their internals might change at anytime,
454 especially between math operations. The objects also might belong to different
455 classes, like Math::BigInt, or Math::BigFLoat. Mixing them together, even
456 with normal scalars is not extraordinary, but normal and expected.
458 You should not depend on the internal format, all accesses must go through
459 accessor methods. E.g. looking at $x->{sign} is not a bright idea since there
460 is no guaranty that the object in question has such a hashkey, nor is a hash
465 The sign is either '+', '-', 'NaN', '+inf' or '-inf' and stored seperately.
466 You can access it with the sign() method.
468 A sign of 'NaN' is used to represent the result when input arguments are not
469 numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively
470 minus infinity. You will get '+inf' when dividing a positive number by 0, and
471 '-inf' when dividing any negative number by 0.
475 C<bignum> is just a thin wrapper around various modules of the Math::BigInt
476 family. Think of it as the head of the family, who runs the shop, and orders
477 the others to do the work.
479 The following modules are currently used by bignum:
481 Math::BigInt::Lite (for speed, and only if it is loadable)
487 Some cool command line examples to impress the Python crowd ;)
489 perl -Mbignum -le 'print sqrt(33)'
490 perl -Mbignum -le 'print 2*255'
491 perl -Mbignum -le 'print 4.5+2*255'
492 perl -Mbignum -le 'print 3/7 + 5/7 + 8/3'
493 perl -Mbignum -le 'print 123->is_odd()'
494 perl -Mbignum -le 'print log(2)'
495 perl -Mbignum -le 'print 2 ** 0.5'
496 perl -Mbignum=a,65 -le 'print 2 ** 0.2'
497 perl -Mbignum=a,65,l,GMP -le 'print 7 ** 7777'
501 This program is free software; you may redistribute it and/or modify it under
502 the same terms as Perl itself.
506 Especially L<bigrat> as in C<perl -Mbigrat -le 'print 1/3+1/4'>.
508 L<Math::BigFloat>, L<Math::BigInt>, L<Math::BigRat> and L<Math::Big> as well
509 as L<Math::BigInt::BitVect>, L<Math::BigInt::Pari> and L<Math::BigInt::GMP>.
513 (C) by Tels L<http://bloodgate.com/> in early 2002 - 2007.