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);
80 my $lib = ''; my $lib_kind = 'try';
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|try|only)$/)
106 # this causes a different low lib to take care...
107 $lib_kind = $1; $lib_kind = 'lib' if $lib_kind eq 'l';
108 $lib = $_[$i+1] || '';
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] =~ /^(a|accuracy)$/)
115 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
116 splice @a, $j, $s; $j -= $s; $i++;
118 elsif ($_[$i] =~ /^(p|precision)$/)
121 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
122 splice @a, $j, $s; $j -= $s; $i++;
124 elsif ($_[$i] =~ /^(v|version)$/)
127 splice @a, $j, 1; $j --;
129 elsif ($_[$i] =~ /^(t|trace)$/)
132 splice @a, $j, 1; $j --;
134 else { die "unknown option $_[$i]"; }
137 $_lite = 0; # using M::BI::L ?
140 require Math::BigInt::Trace; $class = 'Math::BigInt::Trace';
141 $upgrade = 'Math::BigFloat::Trace';
145 # see if we can find Math::BigInt::Lite
146 if (!defined $a && !defined $p) # rounding won't work to well
148 eval 'require Math::BigInt::Lite;';
151 @import = ( ); # :constant in Lite, not MBI
152 Math::BigInt::Lite->import( ':constant' );
153 $_lite= 1; # signal okay
156 require Math::BigInt if $_lite == 0; # not already loaded?
157 $class = 'Math::BigInt'; # regardless of MBIL or not
159 push @import, $lib_kind => $lib if $lib ne '';
160 # Math::BigInt::Trace or plain Math::BigInt
161 $class->import(@import, upgrade => $upgrade);
165 require Math::BigFloat::Trace; $class = 'Math::BigFloat::Trace';
166 $downgrade = 'Math::BigInt::Trace';
170 require Math::BigFloat; $class = 'Math::BigFloat';
172 $class->import(':constant','downgrade',$downgrade);
174 bignum->accuracy($a) if defined $a;
175 bignum->precision($p) if defined $p;
178 print "bignum\t\t\t v$VERSION\n";
179 print "Math::BigInt::Lite\t v$Math::BigInt::Lite::VERSION\n" if $_lite;
180 print "Math::BigInt\t\t v$Math::BigInt::VERSION";
181 my $config = Math::BigInt->config();
182 print " lib => $config->{lib} v$config->{lib_version}\n";
183 print "Math::BigFloat\t\t v$Math::BigFloat::VERSION\n";
187 # Take care of octal/hexadecimal constants
188 overload::constant 'binary' => sub { _binary_constant(shift) };
190 $self->export_to_level(1,$self,@a); # export inf and NaN
193 sub inf () { Math::BigInt->binf(); }
194 sub NaN () { Math::BigInt->bnan(); }
202 bignum - Transparent BigNumber support for Perl
208 $x = 2 + 4.5,"\n"; # BigFloat 6.5
209 print 2 ** 512 * 0.1,"\n"; # really is what you think it is
210 print inf * inf,"\n"; # prints inf
211 print NaN * 3,"\n"; # prints NaN
215 All operators (including basic math operations) are overloaded. Integer and
216 floating-point constants are created as proper BigInts or BigFloats,
223 at the top of your script, Math::BigFloat and Math::BigInt will be loaded
224 and any constant number will be converted to an object (Math::BigFloat for
225 floats like 3.1415 and Math::BigInt for integers like 1234).
227 So, the following line:
231 creates actually a Math::BigInt and stores a reference to in $x.
232 This happens transparently and behind your back, so to speak.
234 You can see this with the following:
236 perl -Mbignum -le 'print ref(1234)'
238 Don't worry if it says Math::BigInt::Lite, bignum and friends will use Lite
239 if it is installed since it is faster for some operations. It will be
240 automatically upgraded to BigInt whenever necessary:
242 perl -Mbignum -le 'print ref(2**255)'
244 This also means it is a bad idea to check for some specific package, since
245 the actual contents of $x might be something unexpected. Due to the
246 transparent way of bignum C<ref()> should not be necessary, anyway.
248 Since Math::BigInt and BigFloat also overload the normal math operations,
249 the following line will still work:
251 perl -Mbignum -le 'print ref(1234+1234)'
253 Since numbers are actually objects, you can call all the usual methods from
254 BigInt/BigFloat on them. This even works to some extent on expressions:
256 perl -Mbignum -le '$x = 1234; print $x->bdec()'
257 perl -Mbignum -le 'print 1234->binc();'
258 perl -Mbignum -le 'print 1234->binc->badd(6);'
259 perl -Mbignum -le 'print +(1234)->binc()'
261 (Note that print doesn't do what you expect if the expression starts with
264 You can even chain the operations together as usual:
266 perl -Mbignum -le 'print 1234->binc->badd(6);'
269 Under bignum (or bigint or bigrat), Perl will "upgrade" the numbers
270 appropriately. This means that:
272 perl -Mbignum -le 'print 1234+4.5'
275 will work correctly. These mixed cases don't do always work when using
276 Math::BigInt or Math::BigFloat alone, or at least not in the way normal Perl
279 If you do want to work with large integers like under C<use integer;>, try
282 perl -Mbigint -le 'print 1234.5+4.5'
285 There is also C<use bigrat;> which gives you big rationals:
287 perl -Mbigrat -le 'print 1234+4.1'
290 The entire upgrading/downgrading is still experimental and might not work
291 as you expect or may even have bugs.
293 You might get errors like this:
295 Can't use an undefined value as an ARRAY reference at
296 /usr/local/lib/perl5/5.8.0/Math/BigInt/Calc.pm line 864
298 This means somewhere a routine got a BigFloat/Lite but expected a BigInt (or
299 vice versa) and the upgrade/downgrad path was missing. This is a bug, please
300 report it so that we can fix it.
302 You might consider using just Math::BigInt or Math::BigFloat, since they
303 allow you finer control over what get's done in which module/space. For
304 instance, simple loop counters will be Math::BigInts under C<use bignum;> and
305 this is slower than keeping them as Perl scalars:
307 perl -Mbignum -le 'for ($i = 0; $i < 10; $i++) { print ref($i); }'
309 Please note the following does not work as expected (prints nothing), since
310 overloading of '..' is not yet possible in Perl (as of v5.8.0):
312 perl -Mbignum -le 'for (1..2) { print ref($_); }'
316 bignum recognizes some options that can be passed while loading it via use.
317 The options can (currently) be either a single letter form, or the long form.
318 The following options exist:
324 This sets the accuracy for all math operations. The argument must be greater
325 than or equal to zero. See Math::BigInt's bround() function for details.
327 perl -Mbignum=a,50 -le 'print sqrt(20)'
329 Note that setting precision and accurary at the same time is not possible.
333 This sets the precision for all math operations. The argument can be any
334 integer. Negative values mean a fixed number of digits after the dot, while
335 a positive value rounds to this digit left from the dot. 0 or 1 mean round to
336 integer. See Math::BigInt's bfround() function for details.
338 perl -Mbignum=p,-50 -le 'print sqrt(20)'
340 Note that setting precision and accurary at the same time is not possible.
344 This enables a trace mode and is primarily for debugging bignum or
345 Math::BigInt/Math::BigFloat.
349 Load a different math lib, see L<MATH LIBRARY>.
351 perl -Mbignum=l,GMP -e 'print 2 ** 512'
353 Currently there is no way to specify more than one library on the command
354 line. This means the following does not work:
356 perl -Mbignum=l,GMP,Pari -e 'print 2 ** 512'
358 This will be hopefully fixed soon ;)
362 This prints out the name and version of all modules used and then exits.
370 Beside import() and AUTOLOAD() there are only a few other methods.
372 Since all numbers are now objects, you can use all functions that are part of
373 the BigInt or BigFloat API. It is wise to use only the bxxx() notation, and not
374 the fxxx() notation, though. This makes it possible that the underlying object
375 might morph into a different class than BigFloat.
379 But a warning is in order. When using the following to make a copy of a number,
380 only a shallow copy will be made.
385 If you want to make a real copy, use the following:
389 Using the copy or the original with overloaded math is okay, e.g. the
393 print $x + 1, " ", $y,"\n"; # prints 10 9
395 but calling any method that modifies the number directly will result in
396 B<both> the original and the copy being destroyed:
399 print $x->badd(1), " ", $y,"\n"; # prints 10 10
402 print $x->binc(1), " ", $y,"\n"; # prints 10 10
405 print $x->bmul(2), " ", $y,"\n"; # prints 18 18
407 Using methods that do not modify, but testthe contents works:
410 $z = 9 if $x->is_zero(); # works fine
412 See the documentation about the copy constructor and C<=> in overload, as
413 well as the documentation in BigInt for further details.
419 A shortcut to return Math::BigInt->binf(). Useful because Perl does not always
420 handle bareword C<inf> properly.
424 A shortcut to return Math::BigInt->bnan(). Useful because Perl does not always
425 handle bareword C<NaN> properly.
429 Return the class that numbers are upgraded to, is in fact returning
430 C<$Math::BigInt::upgrade>.
436 Math with the numbers is done (by default) by a module called
437 Math::BigInt::Calc. This is equivalent to saying:
439 use bignum lib => 'Calc';
441 You can change this by using:
443 use bignum lib => 'GMP';
445 The following would first try to find Math::BigInt::Foo, then
446 Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:
448 use bignum lib => 'Foo,Math::BigInt::Bar';
450 Please see respective module documentation for further details.
452 Using C<lib> warns if none of the specified libraries can be found and
453 L<Math::BigInt> did fall back to one of the default libraries.
454 To supress this warning, use C<try> instead:
456 use bignum try => 'GMP';
458 If you want the code to die instead of falling back, use C<only> instead:
460 use bignum only => 'GMP';
462 =head2 INTERNAL FORMAT
464 The numbers are stored as objects, and their internals might change at anytime,
465 especially between math operations. The objects also might belong to different
466 classes, like Math::BigInt, or Math::BigFLoat. Mixing them together, even
467 with normal scalars is not extraordinary, but normal and expected.
469 You should not depend on the internal format, all accesses must go through
470 accessor methods. E.g. looking at $x->{sign} is not a bright idea since there
471 is no guaranty that the object in question has such a hashkey, nor is a hash
476 The sign is either '+', '-', 'NaN', '+inf' or '-inf' and stored seperately.
477 You can access it with the sign() method.
479 A sign of 'NaN' is used to represent the result when input arguments are not
480 numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively
481 minus infinity. You will get '+inf' when dividing a positive number by 0, and
482 '-inf' when dividing any negative number by 0.
486 C<bignum> is just a thin wrapper around various modules of the Math::BigInt
487 family. Think of it as the head of the family, who runs the shop, and orders
488 the others to do the work.
490 The following modules are currently used by bignum:
492 Math::BigInt::Lite (for speed, and only if it is loadable)
498 Some cool command line examples to impress the Python crowd ;)
500 perl -Mbignum -le 'print sqrt(33)'
501 perl -Mbignum -le 'print 2*255'
502 perl -Mbignum -le 'print 4.5+2*255'
503 perl -Mbignum -le 'print 3/7 + 5/7 + 8/3'
504 perl -Mbignum -le 'print 123->is_odd()'
505 perl -Mbignum -le 'print log(2)'
506 perl -Mbignum -le 'print exp(1)'
507 perl -Mbignum -le 'print 2 ** 0.5'
508 perl -Mbignum=a,65 -le 'print 2 ** 0.2'
509 perl -Mbignum=a,65,l,GMP -le 'print 7 ** 7777'
513 This program is free software; you may redistribute it and/or modify it under
514 the same terms as Perl itself.
518 Especially L<bigrat> as in C<perl -Mbigrat -le 'print 1/3+1/4'>.
520 L<Math::BigFloat>, L<Math::BigInt>, L<Math::BigRat> and L<Math::Big> as well
521 as L<Math::BigInt::BitVect>, L<Math::BigInt::Pari> and L<Math::BigInt::GMP>.
525 (C) by Tels L<http://bloodgate.com/> in early 2002 - 2007.