8 @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 *{"bigint::$name"} = sub
36 return Math::BigInt->$name($_[0]);
38 return Math::BigInt->$name();
44 # delayed load of Carp and avoid recursion
46 Carp::croak ("Can't call bigint\-\>$name, not a valid method");
51 $Math::BigInt::upgrade;
56 # this takes a binary/hexadecimal/octal constant string and returns it
57 # as string suitable for new. Basically it converts octal to decimal, and
58 # passes every thing else unmodified back.
61 return Math::BigInt->new($string) if $string =~ /^0[bx]/;
63 # so it must be an octal constant
64 Math::BigInt->from_oct($string);
69 # this takes a floating point constant string and returns it truncated to
70 # integer. For instance, '4.5' => '4', '1.234e2' => '123' etc
73 # some simple cases first
74 return $float if ($float =~ /^[+-]?[0-9]+$/); # '+123','-1','0' etc
76 if ($float =~ /^[+-]?[0-9]+\.?[eE]\+?[0-9]+$/); # 123e2, 123.e+2
77 return '0' if ($float =~ /^[+-]?[0]*\.[0-9]+$/); # .2, 0.2, -.1
78 if ($float =~ /^[+-]?[0-9]+\.[0-9]*$/) # 1., 1.23, -1.2 etc
83 my ($mis,$miv,$mfv,$es,$ev) = Math::BigInt::_split($float);
84 return $float if !defined $mis; # doesn't look like a number to me
86 my $sign = $$mis; $sign = '' if $sign eq '+';
89 # ignore fraction part entirely
90 if ($ec >= length($$miv)) # 123.23E-4
94 return $sign . substr ($$miv,0,length($$miv)-$ec); # 1234.45E-2 = 12
97 if ($ec >= length($$mfv))
100 return $sign.$$miv.$$mfv if $ec == 0; # 123.45E+2 => 12345
101 return $sign.$$miv.$$mfv.'E'.$ec; # 123.45e+3 => 12345e1
103 $mfv = substr($$mfv,0,$ec);
104 $sign.$$miv.$mfv; # 123.45e+1 => 1234
109 $^H{bigint} = undef; # no longer in effect
110 overload::remove_constant('binary','','float','','integer');
115 my $level = shift || 0;
116 my $hinthash = (caller($level))[10];
120 #############################################################################
121 # the following two routines are for "use bigint qw/hex oct/;":
126 $i = '0x'.$i unless $i =~ /^0x/;
127 Math::BigInt->new($i);
133 return Math::BigInt->from_oct($i) if $i =~ /^0[0-7]/;
134 Math::BigInt->new($i);
137 #############################################################################
138 # the following two routines are for Perl 5.9.4 or later and are lexical
142 return CORE::hex($_[0]) unless in_effect(1);
144 $i = '0x'.$i unless $i =~ /^0x/;
145 Math::BigInt->new($i);
150 return CORE::oct($_[0]) unless in_effect(1);
152 return Math::BigInt->from_oct($i) if $i =~ /^0[0-7]/;
153 Math::BigInt->new($i);
160 $^H{bigint} = 1; # we are in effect
163 # for newer Perls always override hex() and oct() with a lexical version:
170 my $lib = ''; my $lib_kind = 'try';
172 my @import = ( ':constant' ); # drive it w/ constant
173 my @a = @_; my $l = scalar @_; my $j = 0;
174 my ($ver,$trace); # version? trace?
175 my ($a,$p); # accuracy, precision
176 for ( my $i = 0; $i < $l ; $i++,$j++ )
178 if ($_[$i] =~ /^(l|lib|try|only)$/)
180 # this causes a different low lib to take care...
181 $lib_kind = $1; $lib_kind = 'lib' if $lib_kind eq 'l';
182 $lib = $_[$i+1] || '';
183 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
184 splice @a, $j, $s; $j -= $s; $i++;
186 elsif ($_[$i] =~ /^(a|accuracy)$/)
189 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
190 splice @a, $j, $s; $j -= $s; $i++;
192 elsif ($_[$i] =~ /^(p|precision)$/)
195 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
196 splice @a, $j, $s; $j -= $s; $i++;
198 elsif ($_[$i] =~ /^(v|version)$/)
201 splice @a, $j, 1; $j --;
203 elsif ($_[$i] =~ /^(t|trace)$/)
206 splice @a, $j, 1; $j --;
208 elsif ($_[$i] eq 'hex')
210 splice @a, $j, 1; $j --;
211 $hex = \&_hex_global;
213 elsif ($_[$i] eq 'oct')
215 splice @a, $j, 1; $j --;
216 $oct = \&_oct_global;
218 else { die "unknown option $_[$i]"; }
221 $_lite = 0; # using M::BI::L ?
224 require Math::BigInt::Trace; $class = 'Math::BigInt::Trace';
228 # see if we can find Math::BigInt::Lite
229 if (!defined $a && !defined $p) # rounding won't work to well
231 eval 'require Math::BigInt::Lite;';
234 @import = ( ); # :constant in Lite, not MBI
235 Math::BigInt::Lite->import( ':constant' );
236 $_lite= 1; # signal okay
239 require Math::BigInt if $_lite == 0; # not already loaded?
240 $class = 'Math::BigInt'; # regardless of MBIL or not
242 push @import, $lib_kind => $lib if $lib ne '';
243 # Math::BigInt::Trace or plain Math::BigInt
244 $class->import(@import);
246 bigint->accuracy($a) if defined $a;
247 bigint->precision($p) if defined $p;
250 print "bigint\t\t\t v$VERSION\n";
251 print "Math::BigInt::Lite\t v$Math::BigInt::Lite::VERSION\n" if $_lite;
252 print "Math::BigInt\t\t v$Math::BigInt::VERSION";
253 my $config = Math::BigInt->config();
254 print " lib => $config->{lib} v$config->{lib_version}\n";
257 # we take care of floating point constants, since BigFloat isn't available
258 # and BigInt doesn't like them:
259 overload::constant float => sub { Math::BigInt->new( _float_constant(shift) ); };
260 # Take care of octal/hexadecimal constants
261 overload::constant binary => sub { _binary_constant(shift) };
263 # if another big* was already loaded:
264 my ($package) = caller();
267 if (!defined *{"${package}::inf"})
269 $self->export_to_level(1,$self,@a); # export inf and NaN
272 no warnings 'redefine';
273 *CORE::GLOBAL::oct = $oct if $oct;
274 *CORE::GLOBAL::hex = $hex if $hex;
278 sub inf () { Math::BigInt->binf(); }
279 sub NaN () { Math::BigInt->bnan(); }
287 bigint - Transparent BigInteger support for Perl
293 $x = 2 + 4.5,"\n"; # BigInt 6
294 print 2 ** 512,"\n"; # really is what you think it is
295 print inf + 42,"\n"; # inf
296 print NaN * 7,"\n"; # NaN
297 print hex("0x1234567890123490"),"\n"; # Perl v5.9.4 or later
301 print 2 ** 256,"\n"; # a normal Perl scalar now
304 # Note that this will be global:
305 use bigint qw/hex oct/;
306 print hex("0x1234567890123490"),"\n";
307 print oct("01234567890123490"),"\n";
311 All operators (including basic math operations) are overloaded. Integer
312 constants are created as proper BigInts.
314 Floating point constants are truncated to integer. All parts and results of
315 expressions are also truncated.
317 Unlike L<integer>, this pragma creates integer constants that are only
318 limited in their size by the available memory and CPU time.
320 =head2 use integer vs. use bigint
322 There is one small difference between C<use integer> and C<use bigint>: the
323 former will not affect assignments to variables and the return value of
324 some functions. C<bigint> truncates these results to integer too:
326 # perl -Minteger -wle 'print 3.2'
328 # perl -Minteger -wle 'print 3.2 + 0'
330 # perl -Mbigint -wle 'print 3.2'
332 # perl -Mbigint -wle 'print 3.2 + 0'
335 # perl -Mbigint -wle 'print exp(1) + 0'
337 # perl -Mbigint -wle 'print exp(1)'
339 # perl -Minteger -wle 'print exp(1)'
341 # perl -Minteger -wle 'print exp(1) + 0'
344 In practice this makes seldom a difference as B<parts and results> of
345 expressions will be truncated anyway, but this can, for instance, affect the
346 return value of subroutines:
348 sub three_integer { use integer; return 3.2; }
349 sub three_bigint { use bigint; return 3.2; }
351 print three_integer(), " ", three_bigint(),"\n"; # prints "3.2 3"
355 bigint recognizes some options that can be passed while loading it via use.
356 The options can (currently) be either a single letter form, or the long form.
357 The following options exist:
363 This sets the accuracy for all math operations. The argument must be greater
364 than or equal to zero. See Math::BigInt's bround() function for details.
366 perl -Mbigint=a,2 -le 'print 12345+1'
368 Note that setting precision and accurary at the same time is not possible.
372 This sets the precision for all math operations. The argument can be any
373 integer. Negative values mean a fixed number of digits after the dot, and
374 are <B>ignored</B> since all operations happen in integer space.
375 A positive value rounds to this digit left from the dot. 0 or 1 mean round to
376 integer and are ignore like negative values.
378 See Math::BigInt's bfround() function for details.
380 perl -Mbignum=p,5 -le 'print 123456789+123'
382 Note that setting precision and accurary at the same time is not possible.
386 This enables a trace mode and is primarily for debugging bigint or
391 Override the build-in hex() method with a version that can handle big
392 integers. Note that under Perl v5.9.4 or ealier, this will be global
393 and cannot be disabled with "no bigint;".
397 Override the build-in oct() method with a version that can handle big
398 integers. Note that under Perl v5.9.4 or ealier, this will be global
399 and cannot be disabled with "no bigint;".
401 =item l, lib, try or only
403 Load a different math lib, see L<Math Library>.
405 perl -Mbigint=lib,GMP -e 'print 2 ** 512'
406 perl -Mbigint=try,GMP -e 'print 2 ** 512'
407 perl -Mbigint=only,GMP -e 'print 2 ** 512'
409 Currently there is no way to specify more than one library on the command
410 line. This means the following does not work:
412 perl -Mbignum=l,GMP,Pari -e 'print 2 ** 512'
414 This will be hopefully fixed soon ;)
418 This prints out the name and version of all modules used and then exits.
426 Math with the numbers is done (by default) by a module called
427 Math::BigInt::Calc. This is equivalent to saying:
429 use bigint lib => 'Calc';
431 You can change this by using:
433 use bignum lib => 'GMP';
435 The following would first try to find Math::BigInt::Foo, then
436 Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:
438 use bigint lib => 'Foo,Math::BigInt::Bar';
440 Using C<lib> warns if none of the specified libraries can be found and
441 L<Math::BigInt> did fall back to one of the default libraries.
442 To supress this warning, use C<try> instead:
444 use bignum try => 'GMP';
446 If you want the code to die instead of falling back, use C<only> instead:
448 use bignum only => 'GMP';
450 Please see respective module documentation for further details.
452 =head2 Internal Format
454 The numbers are stored as objects, and their internals might change at anytime,
455 especially between math operations. The objects also might belong to different
456 classes, like Math::BigInt, or Math::BigInt::Lite. Mixing them together, even
457 with normal scalars is not extraordinary, but normal and expected.
459 You should not depend on the internal format, all accesses must go through
460 accessor methods. E.g. looking at $x->{sign} is not a good idea since there
461 is no guaranty that the object in question has such a hash key, nor is a hash
466 The sign is either '+', '-', 'NaN', '+inf' or '-inf'.
467 You can access it with the sign() method.
469 A sign of 'NaN' is used to represent the result when input arguments are not
470 numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively
471 minus infinity. You will get '+inf' when dividing a positive number by 0, and
472 '-inf' when dividing any negative number by 0.
476 Since all numbers are now objects, you can use all functions that are part of
477 the BigInt API. You can only use the bxxx() notation, and not the fxxx()
484 A shortcut to return Math::BigInt->binf(). Useful because Perl does not always
485 handle bareword C<inf> properly.
489 A shortcut to return Math::BigInt->bnan(). Useful because Perl does not always
490 handle bareword C<NaN> properly.
494 Return the class that numbers are upgraded to, is in fact returning
495 C<$Math::BigInt::upgrade>.
501 print "in effect\n" if bigint::in_effect; # true
504 print "in effect\n" if bigint::in_effect; # false
507 Returns true or false if C<bigint> is in effect in the current scope.
509 This method only works on Perl v5.9.4 or later.
515 Math with the numbers is done (by default) by a module called
519 But a warning is in order. When using the following to make a copy of a number,
520 only a shallow copy will be made.
525 Using the copy or the original with overloaded math is okay, e.g. the
529 print $x + 1, " ", $y,"\n"; # prints 10 9
531 but calling any method that modifies the number directly will result in
532 B<both> the original and the copy being destroyed:
535 print $x->badd(1), " ", $y,"\n"; # prints 10 10
538 print $x->binc(1), " ", $y,"\n"; # prints 10 10
541 print $x->bmul(2), " ", $y,"\n"; # prints 18 18
543 Using methods that do not modify, but testthe contents works:
546 $z = 9 if $x->is_zero(); # works fine
548 See the documentation about the copy constructor and C<=> in overload, as
549 well as the documentation in BigInt for further details.
557 This method only works on Perl v5.9.4 or later.
561 C<bigint> overrides these routines with versions that can also handle
562 big integer values. Under Perl prior to version v5.9.4, however, this
563 will not happen unless you specifically ask for it with the two
564 import tags "hex" and "oct" - and then it will be global and cannot be
565 disabled inside a scope with "no bigint":
567 use bigint qw/hex oct/;
569 print hex("0x1234567890123456");
572 print hex("0x1234567890123456");
575 The second call to hex() will warn about a non-portable constant.
581 # will warn only under Perl older than v5.9.4
582 print hex("0x1234567890123456");
588 C<bigint> is just a thin wrapper around various modules of the Math::BigInt
589 family. Think of it as the head of the family, who runs the shop, and orders
590 the others to do the work.
592 The following modules are currently used by bigint:
594 Math::BigInt::Lite (for speed, and only if it is loadable)
599 Some cool command line examples to impress the Python crowd ;) You might want
600 to compare them to the results under -Mbignum or -Mbigrat:
602 perl -Mbigint -le 'print sqrt(33)'
603 perl -Mbigint -le 'print 2*255'
604 perl -Mbigint -le 'print 4.5+2*255'
605 perl -Mbigint -le 'print 3/7 + 5/7 + 8/3'
606 perl -Mbigint -le 'print 123->is_odd()'
607 perl -Mbigint -le 'print log(2)'
608 perl -Mbigint -le 'print 2 ** 0.5'
609 perl -Mbigint=a,65 -le 'print 2 ** 0.2'
610 perl -Mbignum=a,65,l,GMP -le 'print 7 ** 7777'
614 This program is free software; you may redistribute it and/or modify it under
615 the same terms as Perl itself.
619 Especially L<bigrat> as in C<perl -Mbigrat -le 'print 1/3+1/4'> and
620 L<bignum> as in C<perl -Mbignum -le 'print sqrt(2)'>.
622 L<Math::BigInt>, L<Math::BigRat> and L<Math::Big> as well
623 as L<Math::BigInt::BitVect>, L<Math::BigInt::Pari> and L<Math::BigInt::GMP>.
627 (C) by Tels L<http://bloodgate.com/> in early 2002 - 2007.