lib/bignum.pm

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