lib/bignum.pm

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