1package bigint; 2use 5.006; 3 4$VERSION = '0.23'; 5use Exporter; 6@ISA = qw( Exporter ); 7@EXPORT_OK = qw( PI e bpi bexp ); 8@EXPORT = qw( inf NaN ); 9 10use strict; 11use overload; 12 13############################################################################## 14 15# These are all alike, and thus faked by AUTOLOAD 16 17my @faked = qw/round_mode accuracy precision div_scale/; 18use vars qw/$VERSION $AUTOLOAD $_lite/; # _lite for testsuite 19 20sub AUTOLOAD 21 { 22 my $name = $AUTOLOAD; 23 24 $name =~ s/.*:://; # split package 25 no strict 'refs'; 26 foreach my $n (@faked) 27 { 28 if ($n eq $name) 29 { 30 *{"bigint::$name"} = sub 31 { 32 my $self = shift; 33 no strict 'refs'; 34 if (defined $_[0]) 35 { 36 return Math::BigInt->$name($_[0]); 37 } 38 return Math::BigInt->$name(); 39 }; 40 return &$name; 41 } 42 } 43 44 # delayed load of Carp and avoid recursion 45 require Carp; 46 Carp::croak ("Can't call bigint\-\>$name, not a valid method"); 47 } 48 49sub upgrade 50 { 51 $Math::BigInt::upgrade; 52 } 53 54sub _binary_constant 55 { 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. 59 my $string = shift; 60 61 return Math::BigInt->new($string) if $string =~ /^0[bx]/; 62 63 # so it must be an octal constant 64 Math::BigInt->from_oct($string); 65 } 66 67sub _float_constant 68 { 69 # this takes a floating point constant string and returns it truncated to 70 # integer. For instance, '4.5' => '4', '1.234e2' => '123' etc 71 my $float = shift; 72 73 # some simple cases first 74 return $float if ($float =~ /^[+-]?[0-9]+$/); # '+123','-1','0' etc 75 return $float 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 79 { 80 $float =~ s/\..*//; 81 return $float; 82 } 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 85 my $ec = int($$ev); 86 my $sign = $$mis; $sign = '' if $sign eq '+'; 87 if ($$es eq '-') 88 { 89 # ignore fraction part entirely 90 if ($ec >= length($$miv)) # 123.23E-4 91 { 92 return '0'; 93 } 94 return $sign . substr ($$miv,0,length($$miv)-$ec); # 1234.45E-2 = 12 95 } 96 # xE+y 97 if ($ec >= length($$mfv)) 98 { 99 $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 102 } 103 $mfv = substr($$mfv,0,$ec); 104 $sign.$$miv.$mfv; # 123.45e+1 => 1234 105 } 106 107sub unimport 108 { 109 $^H{bigint} = undef; # no longer in effect 110 overload::remove_constant('binary','','float','','integer'); 111 } 112 113sub in_effect 114 { 115 my $level = shift || 0; 116 my $hinthash = (caller($level))[10]; 117 $hinthash->{bigint}; 118 } 119 120############################################################################# 121# the following two routines are for "use bigint qw/hex oct/;": 122 123sub _hex_global 124 { 125 my $i = $_[0]; 126 $i = '0x'.$i unless $i =~ /^0x/; 127 Math::BigInt->new($i); 128 } 129 130sub _oct_global 131 { 132 my $i = $_[0]; 133 return Math::BigInt->from_oct($i) if $i =~ /^0[0-7]/; 134 Math::BigInt->new($i); 135 } 136 137############################################################################# 138# the following two routines are for Perl 5.9.4 or later and are lexical 139 140sub _hex 141 { 142 return CORE::hex($_[0]) unless in_effect(1); 143 my $i = $_[0]; 144 $i = '0x'.$i unless $i =~ /^0x/; 145 Math::BigInt->new($i); 146 } 147 148sub _oct 149 { 150 return CORE::oct($_[0]) unless in_effect(1); 151 my $i = $_[0]; 152 return Math::BigInt->from_oct($i) if $i =~ /^0[0-7]/; 153 Math::BigInt->new($i); 154 } 155 156sub import 157 { 158 my $self = shift; 159 160 $^H{bigint} = 1; # we are in effect 161 162 my ($hex,$oct); 163 # for newer Perls always override hex() and oct() with a lexical version: 164 if ($] > 5.009004) 165 { 166 $oct = \&_oct; 167 $hex = \&_hex; 168 } 169 # some defaults 170 my $lib = ''; my $lib_kind = 'try'; 171 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++ ) 177 { 178 if ($_[$i] =~ /^(l|lib|try|only)$/) 179 { 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++; 185 } 186 elsif ($_[$i] =~ /^(a|accuracy)$/) 187 { 188 $a = $_[$i+1]; 189 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..." 190 splice @a, $j, $s; $j -= $s; $i++; 191 } 192 elsif ($_[$i] =~ /^(p|precision)$/) 193 { 194 $p = $_[$i+1]; 195 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..." 196 splice @a, $j, $s; $j -= $s; $i++; 197 } 198 elsif ($_[$i] =~ /^(v|version)$/) 199 { 200 $ver = 1; 201 splice @a, $j, 1; $j --; 202 } 203 elsif ($_[$i] =~ /^(t|trace)$/) 204 { 205 $trace = 1; 206 splice @a, $j, 1; $j --; 207 } 208 elsif ($_[$i] eq 'hex') 209 { 210 splice @a, $j, 1; $j --; 211 $hex = \&_hex_global; 212 } 213 elsif ($_[$i] eq 'oct') 214 { 215 splice @a, $j, 1; $j --; 216 $oct = \&_oct_global; 217 } 218 elsif ($_[$i] !~ /^(PI|e|bpi|bexp)\z/) 219 { 220 die ("unknown option $_[$i]"); 221 } 222 } 223 my $class; 224 $_lite = 0; # using M::BI::L ? 225 if ($trace) 226 { 227 require Math::BigInt::Trace; $class = 'Math::BigInt::Trace'; 228 } 229 else 230 { 231 # see if we can find Math::BigInt::Lite 232 if (!defined $a && !defined $p) # rounding won't work to well 233 { 234 eval 'require Math::BigInt::Lite;'; 235 if ($@ eq '') 236 { 237 @import = ( ); # :constant in Lite, not MBI 238 Math::BigInt::Lite->import( ':constant' ); 239 $_lite= 1; # signal okay 240 } 241 } 242 require Math::BigInt if $_lite == 0; # not already loaded? 243 $class = 'Math::BigInt'; # regardless of MBIL or not 244 } 245 push @import, $lib_kind => $lib if $lib ne ''; 246 # Math::BigInt::Trace or plain Math::BigInt 247 $class->import(@import); 248 249 bigint->accuracy($a) if defined $a; 250 bigint->precision($p) if defined $p; 251 if ($ver) 252 { 253 print "bigint\t\t\t v$VERSION\n"; 254 print "Math::BigInt::Lite\t v$Math::BigInt::Lite::VERSION\n" if $_lite; 255 print "Math::BigInt\t\t v$Math::BigInt::VERSION"; 256 my $config = Math::BigInt->config(); 257 print " lib => $config->{lib} v$config->{lib_version}\n"; 258 exit; 259 } 260 # we take care of floating point constants, since BigFloat isn't available 261 # and BigInt doesn't like them: 262 overload::constant float => sub { Math::BigInt->new( _float_constant(shift) ); }; 263 # Take care of octal/hexadecimal constants 264 overload::constant binary => sub { _binary_constant(shift) }; 265 266 # if another big* was already loaded: 267 my ($package) = caller(); 268 269 no strict 'refs'; 270 if (!defined *{"${package}::inf"}) 271 { 272 $self->export_to_level(1,$self,@a); # export inf and NaN, e and PI 273 } 274 { 275 no warnings 'redefine'; 276 *CORE::GLOBAL::oct = $oct if $oct; 277 *CORE::GLOBAL::hex = $hex if $hex; 278 } 279 } 280 281sub inf () { Math::BigInt::binf(); } 282sub NaN () { Math::BigInt::bnan(); } 283 284sub PI () { Math::BigInt->new(3); } 285sub e () { Math::BigInt->new(2); } 286sub bpi ($) { Math::BigInt->new(3); } 287sub bexp ($$) { my $x = Math::BigInt->new($_[0]); $x->bexp($_[1]); } 288 2891; 290 291__END__ 292 293=head1 NAME 294 295bigint - Transparent BigInteger support for Perl 296 297=head1 SYNOPSIS 298 299 use bigint; 300 301 $x = 2 + 4.5,"\n"; # BigInt 6 302 print 2 ** 512,"\n"; # really is what you think it is 303 print inf + 42,"\n"; # inf 304 print NaN * 7,"\n"; # NaN 305 print hex("0x1234567890123490"),"\n"; # Perl v5.9.4 or later 306 307 { 308 no bigint; 309 print 2 ** 256,"\n"; # a normal Perl scalar now 310 } 311 312 # Note that this will be global: 313 use bigint qw/hex oct/; 314 print hex("0x1234567890123490"),"\n"; 315 print oct("01234567890123490"),"\n"; 316 317=head1 DESCRIPTION 318 319All operators (including basic math operations) are overloaded. Integer 320constants are created as proper BigInts. 321 322Floating point constants are truncated to integer. All parts and results of 323expressions are also truncated. 324 325Unlike L<integer>, this pragma creates integer constants that are only 326limited in their size by the available memory and CPU time. 327 328=head2 use integer vs. use bigint 329 330There is one small difference between C<use integer> and C<use bigint>: the 331former will not affect assignments to variables and the return value of 332some functions. C<bigint> truncates these results to integer too: 333 334 # perl -Minteger -wle 'print 3.2' 335 3.2 336 # perl -Minteger -wle 'print 3.2 + 0' 337 3 338 # perl -Mbigint -wle 'print 3.2' 339 3 340 # perl -Mbigint -wle 'print 3.2 + 0' 341 3 342 343 # perl -Mbigint -wle 'print exp(1) + 0' 344 2 345 # perl -Mbigint -wle 'print exp(1)' 346 2 347 # perl -Minteger -wle 'print exp(1)' 348 2.71828182845905 349 # perl -Minteger -wle 'print exp(1) + 0' 350 2 351 352In practice this makes seldom a difference as B<parts and results> of 353expressions will be truncated anyway, but this can, for instance, affect the 354return value of subroutines: 355 356 sub three_integer { use integer; return 3.2; } 357 sub three_bigint { use bigint; return 3.2; } 358 359 print three_integer(), " ", three_bigint(),"\n"; # prints "3.2 3" 360 361=head2 Options 362 363bigint recognizes some options that can be passed while loading it via use. 364The options can (currently) be either a single letter form, or the long form. 365The following options exist: 366 367=over 2 368 369=item a or accuracy 370 371This sets the accuracy for all math operations. The argument must be greater 372than or equal to zero. See Math::BigInt's bround() function for details. 373 374 perl -Mbigint=a,2 -le 'print 12345+1' 375 376Note that setting precision and accurary at the same time is not possible. 377 378=item p or precision 379 380This sets the precision for all math operations. The argument can be any 381integer. Negative values mean a fixed number of digits after the dot, and 382are <B>ignored</B> since all operations happen in integer space. 383A positive value rounds to this digit left from the dot. 0 or 1 mean round to 384integer and are ignore like negative values. 385 386See Math::BigInt's bfround() function for details. 387 388 perl -Mbignum=p,5 -le 'print 123456789+123' 389 390Note that setting precision and accurary at the same time is not possible. 391 392=item t or trace 393 394This enables a trace mode and is primarily for debugging bigint or 395Math::BigInt. 396 397=item hex 398 399Override the built-in hex() method with a version that can handle big 400integers. Note that under Perl v5.9.4 or ealier, this will be global 401and cannot be disabled with "no bigint;". 402 403=item oct 404 405Override the built-in oct() method with a version that can handle big 406integers. Note that under Perl v5.9.4 or ealier, this will be global 407and cannot be disabled with "no bigint;". 408 409=item l, lib, try or only 410 411Load a different math lib, see L<Math Library>. 412 413 perl -Mbigint=lib,GMP -e 'print 2 ** 512' 414 perl -Mbigint=try,GMP -e 'print 2 ** 512' 415 perl -Mbigint=only,GMP -e 'print 2 ** 512' 416 417Currently there is no way to specify more than one library on the command 418line. This means the following does not work: 419 420 perl -Mbignum=l,GMP,Pari -e 'print 2 ** 512' 421 422This will be hopefully fixed soon ;) 423 424=item v or version 425 426This prints out the name and version of all modules used and then exits. 427 428 perl -Mbigint=v 429 430=back 431 432=head2 Math Library 433 434Math with the numbers is done (by default) by a module called 435Math::BigInt::Calc. This is equivalent to saying: 436 437 use bigint lib => 'Calc'; 438 439You can change this by using: 440 441 use bignum lib => 'GMP'; 442 443The following would first try to find Math::BigInt::Foo, then 444Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc: 445 446 use bigint lib => 'Foo,Math::BigInt::Bar'; 447 448Using C<lib> warns if none of the specified libraries can be found and 449L<Math::BigInt> did fall back to one of the default libraries. 450To supress this warning, use C<try> instead: 451 452 use bignum try => 'GMP'; 453 454If you want the code to die instead of falling back, use C<only> instead: 455 456 use bignum only => 'GMP'; 457 458Please see respective module documentation for further details. 459 460=head2 Internal Format 461 462The numbers are stored as objects, and their internals might change at anytime, 463especially between math operations. The objects also might belong to different 464classes, like Math::BigInt, or Math::BigInt::Lite. Mixing them together, even 465with normal scalars is not extraordinary, but normal and expected. 466 467You should not depend on the internal format, all accesses must go through 468accessor methods. E.g. looking at $x->{sign} is not a good idea since there 469is no guaranty that the object in question has such a hash key, nor is a hash 470underneath at all. 471 472=head2 Sign 473 474The sign is either '+', '-', 'NaN', '+inf' or '-inf'. 475You can access it with the sign() method. 476 477A sign of 'NaN' is used to represent the result when input arguments are not 478numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively 479minus infinity. You will get '+inf' when dividing a positive number by 0, and 480'-inf' when dividing any negative number by 0. 481 482=head2 Methods 483 484Since all numbers are now objects, you can use all functions that are part of 485the BigInt API. You can only use the bxxx() notation, and not the fxxx() 486notation, though. 487 488=over 2 489 490=item inf() 491 492A shortcut to return Math::BigInt->binf(). Useful because Perl does not always 493handle bareword C<inf> properly. 494 495=item NaN() 496 497A shortcut to return Math::BigInt->bnan(). Useful because Perl does not always 498handle bareword C<NaN> properly. 499 500=item e 501 502 # perl -Mbigint=e -wle 'print e' 503 504Returns Euler's number C<e>, aka exp(1). Note that under bigint, this is 505truncated to an integer, and hence simple '2'. 506 507=item PI 508 509 # perl -Mbigint=PI -wle 'print PI' 510 511Returns PI. Note that under bigint, this is truncated to an integer, and hence 512simple '3'. 513 514=item bexp() 515 516 bexp($power,$accuracy); 517 518Returns Euler's number C<e> raised to the appropriate power, to 519the wanted accuracy. 520 521Note that under bigint, the result is truncated to an integer. 522 523Example: 524 525 # perl -Mbigint=bexp -wle 'print bexp(1,80)' 526 527=item bpi() 528 529 bpi($accuracy); 530 531Returns PI to the wanted accuracy. Note that under bigint, this is truncated 532to an integer, and hence simple '3'. 533 534Example: 535 536 # perl -Mbigint=bpi -wle 'print bpi(80)' 537 538=item upgrade() 539 540Return the class that numbers are upgraded to, is in fact returning 541C<$Math::BigInt::upgrade>. 542 543=item in_effect() 544 545 use bigint; 546 547 print "in effect\n" if bigint::in_effect; # true 548 { 549 no bigint; 550 print "in effect\n" if bigint::in_effect; # false 551 } 552 553Returns true or false if C<bigint> is in effect in the current scope. 554 555This method only works on Perl v5.9.4 or later. 556 557=back 558 559=head2 MATH LIBRARY 560 561Math with the numbers is done (by default) by a module called 562 563=head2 Caveat 564 565But a warning is in order. When using the following to make a copy of a number, 566only a shallow copy will be made. 567 568 $x = 9; $y = $x; 569 $x = $y = 7; 570 571Using the copy or the original with overloaded math is okay, e.g. the 572following work: 573 574 $x = 9; $y = $x; 575 print $x + 1, " ", $y,"\n"; # prints 10 9 576 577but calling any method that modifies the number directly will result in 578B<both> the original and the copy being destroyed: 579 580 $x = 9; $y = $x; 581 print $x->badd(1), " ", $y,"\n"; # prints 10 10 582 583 $x = 9; $y = $x; 584 print $x->binc(1), " ", $y,"\n"; # prints 10 10 585 586 $x = 9; $y = $x; 587 print $x->bmul(2), " ", $y,"\n"; # prints 18 18 588 589Using methods that do not modify, but testthe contents works: 590 591 $x = 9; $y = $x; 592 $z = 9 if $x->is_zero(); # works fine 593 594See the documentation about the copy constructor and C<=> in overload, as 595well as the documentation in BigInt for further details. 596 597=head1 CAVAETS 598 599=over 2 600 601=item in_effect() 602 603This method only works on Perl v5.9.4 or later. 604 605=item hex()/oct() 606 607C<bigint> overrides these routines with versions that can also handle 608big integer values. Under Perl prior to version v5.9.4, however, this 609will not happen unless you specifically ask for it with the two 610import tags "hex" and "oct" - and then it will be global and cannot be 611disabled inside a scope with "no bigint": 612 613 use bigint qw/hex oct/; 614 615 print hex("0x1234567890123456"); 616 { 617 no bigint; 618 print hex("0x1234567890123456"); 619 } 620 621The second call to hex() will warn about a non-portable constant. 622 623Compare this to: 624 625 use bigint; 626 627 # will warn only under Perl older than v5.9.4 628 print hex("0x1234567890123456"); 629 630=back 631 632=head1 MODULES USED 633 634C<bigint> is just a thin wrapper around various modules of the Math::BigInt 635family. Think of it as the head of the family, who runs the shop, and orders 636the others to do the work. 637 638The following modules are currently used by bigint: 639 640 Math::BigInt::Lite (for speed, and only if it is loadable) 641 Math::BigInt 642 643=head1 EXAMPLES 644 645Some cool command line examples to impress the Python crowd ;) You might want 646to compare them to the results under -Mbignum or -Mbigrat: 647 648 perl -Mbigint -le 'print sqrt(33)' 649 perl -Mbigint -le 'print 2*255' 650 perl -Mbigint -le 'print 4.5+2*255' 651 perl -Mbigint -le 'print 3/7 + 5/7 + 8/3' 652 perl -Mbigint -le 'print 123->is_odd()' 653 perl -Mbigint -le 'print log(2)' 654 perl -Mbigint -le 'print 2 ** 0.5' 655 perl -Mbigint=a,65 -le 'print 2 ** 0.2' 656 perl -Mbignum=a,65,l,GMP -le 'print 7 ** 7777' 657 658=head1 LICENSE 659 660This program is free software; you may redistribute it and/or modify it under 661the same terms as Perl itself. 662 663=head1 SEE ALSO 664 665Especially L<bigrat> as in C<perl -Mbigrat -le 'print 1/3+1/4'> and 666L<bignum> as in C<perl -Mbignum -le 'print sqrt(2)'>. 667 668L<Math::BigInt>, L<Math::BigRat> and L<Math::Big> as well 669as L<Math::BigInt::BitVect>, L<Math::BigInt::Pari> and L<Math::BigInt::GMP>. 670 671=head1 AUTHORS 672 673(C) by Tels L<http://bloodgate.com/> in early 2002 - 2007. 674 675=cut 676