lib/bigint.pm

   1 package bigint;
   2 use 5.006002;
   3
   4 $VERSION = '0.22';
   5 use Exporter;
   6 @ISA            = qw( Exporter );
   7 @EXPORT_OK      = qw( PI e bpi bexp );
   8 @EXPORT         = qw( inf NaN );
   9
  10 use strict;
  11 use overload;
  12
  13 ##############################################################################
  14
  15 # These are all alike, and thus faked by AUTOLOAD
  16
  17 my @faked = qw/round_mode accuracy precision div_scale/;
  18 use vars qw/$VERSION $AUTOLOAD $_lite/;         # _lite for testsuite
  19
  20 sub 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
  49 sub upgrade
  50   {
  51   $Math::BigInt::upgrade;
  52   }
  53
  54 sub _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
  67 sub _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
 107 sub unimport
 108   {
 109   $^H{bigint} = undef;                                  # no longer in effect
 110   overload::remove_constant('binary','','float','','integer');
 111   }
 112
 113 sub 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
 123 sub _hex_global
 124   {
 125   my $i = $_[0];
 126   $i = '0x'.$i unless $i =~ /^0x/;
 127   Math::BigInt->new($i);
 128   }
 129
 130 sub _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
 140 sub _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
 148 sub _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
 156 sub 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
 281 sub inf () { Math::BigInt::binf(); }
 282 sub NaN () { Math::BigInt::bnan(); }
 283
 284 sub PI () { Math::BigInt->new(3); }
 285 sub e () { Math::BigInt->new(2); }
 286 sub bpi ($) { Math::BigInt->new(3); }
 287 sub bexp ($$) { my $x = Math::BigInt->new($_[0]); $x->bexp($_[1]); }
 288
 289 1;
 290
 291 __END__
 292
 293 =head1 NAME
 294
 295 bigint - 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
 319 All operators (including basic math operations) are overloaded. Integer
 320 constants are created as proper BigInts.
 321
 322 Floating point constants are truncated to integer. All parts and results of
 323 expressions are also truncated.
 324
 325 Unlike L<integer>, this pragma creates integer constants that are only
 326 limited in their size by the available memory and CPU time.
 327
 328 =head2 use integer vs. use bigint
 329
 330 There is one small difference between C<use integer> and C<use bigint>: the
 331 former will not affect assignments to variables and the return value of
 332 some 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
 352 In practice this makes seldom a difference as B<parts and results> of
 353 expressions will be truncated anyway, but this can, for instance, affect the
 354 return 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
 363 bigint recognizes some options that can be passed while loading it via use.
 364 The options can (currently) be either a single letter form, or the long form.
 365 The following options exist:
 366
 367 =over 2
 368
 369 =item a or accuracy
 370
 371 This sets the accuracy for all math operations. The argument must be greater
 372 than or equal to zero. See Math::BigInt's bround() function for details.
 373
 374         perl -Mbigint=a,2 -le 'print 12345+1'
 375
 376 Note that setting precision and accurary at the same time is not possible.
 377
 378 =item p or precision
 379
 380 This sets the precision for all math operations. The argument can be any
 381 integer. Negative values mean a fixed number of digits after the dot, and
 382 are <B>ignored</B> since all operations happen in integer space.
 383 A positive value rounds to this digit left from the dot. 0 or 1 mean round to
 384 integer and are ignore like negative values.
 385
 386 See Math::BigInt's bfround() function for details.
 387
 388         perl -Mbignum=p,5 -le 'print 123456789+123'
 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 bigint or
 395 Math::BigInt.
 396
 397 =item hex
 398
 399 Override the built-in hex() method with a version that can handle big
 400 integers. Note that under Perl v5.9.4 or ealier, this will be global
 401 and cannot be disabled with "no bigint;".
 402
 403 =item oct
 404
 405 Override the built-in oct() method with a version that can handle big
 406 integers. Note that under Perl v5.9.4 or ealier, this will be global
 407 and cannot be disabled with "no bigint;".
 408
 409 =item l, lib, try or only
 410
 411 Load 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
 417 Currently there is no way to specify more than one library on the command
 418 line. This means the following does not work:
 419
 420         perl -Mbignum=l,GMP,Pari -e 'print 2 ** 512'
 421
 422 This will be hopefully fixed soon ;)
 423
 424 =item v or version
 425
 426 This 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
 434 Math with the numbers is done (by default) by a module called
 435 Math::BigInt::Calc. This is equivalent to saying:
 436
 437         use bigint lib => 'Calc';
 438
 439 You can change this by using:
 440
 441         use bignum lib => 'GMP';
 442
 443 The following would first try to find Math::BigInt::Foo, then
 444 Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:
 445
 446         use bigint lib => 'Foo,Math::BigInt::Bar';
 447
 448 Using C<lib> warns if none of the specified libraries can be found and
 449 L<Math::BigInt> did fall back to one of the default libraries.
 450 To supress this warning, use C<try> instead:
 451
 452         use bignum try => 'GMP';
 453
 454 If you want the code to die instead of falling back, use C<only> instead:
 455
 456         use bignum only => 'GMP';
 457
 458 Please see respective module documentation for further details.
 459
 460 =head2 Internal Format
 461
 462 The numbers are stored as objects, and their internals might change at anytime,
 463 especially between math operations. The objects also might belong to different
 464 classes, like Math::BigInt, or Math::BigInt::Lite. Mixing them together, even
 465 with normal scalars is not extraordinary, but normal and expected.
 466
 467 You should not depend on the internal format, all accesses must go through
 468 accessor methods. E.g. looking at $x->{sign} is not a good idea since there
 469 is no guaranty that the object in question has such a hash key, nor is a hash
 470 underneath at all.
 471
 472 =head2 Sign
 473
 474 The sign is either '+', '-', 'NaN', '+inf' or '-inf'.
 475 You can access it with the sign() method.
 476
 477 A sign of 'NaN' is used to represent the result when input arguments are not
 478 numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively
 479 minus 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
 484 Since all numbers are now objects, you can use all functions that are part of
 485 the BigInt API. You can only use the bxxx() notation, and not the fxxx()
 486 notation, though.
 487
 488 =over 2
 489
 490 =item inf()
 491
 492 A shortcut to return Math::BigInt->binf(). Useful because Perl does not always
 493 handle bareword C<inf> properly.
 494
 495 =item NaN()
 496
 497 A shortcut to return Math::BigInt->bnan(). Useful because Perl does not always
 498 handle bareword C<NaN> properly.
 499
 500 =item e
 501
 502         # perl -Mbigint=e -wle 'print e'
 503
 504 Returns Euler's number C<e>, aka exp(1). Note that under bigint, this is
 505 truncated to an integer, and hence simple '2'.
 506
 507 =item PI
 508
 509         # perl -Mbigint=PI -wle 'print PI'
 510
 511 Returns PI. Note that under bigint, this is truncated to an integer, and hence
 512 simple '3'.
 513
 514 =item bexp()
 515
 516         bexp($power,$accuracy);
 517
 518 Returns Euler's number C<e> raised to the appropriate power, to
 519 the wanted accuracy.
 520
 521 Note that under bigint, the result is truncated to an integer.
 522
 523 Example:
 524
 525         # perl -Mbigint=bexp -wle 'print bexp(1,80)'
 526
 527 =item bpi()
 528
 529         bpi($accuracy);
 530
 531 Returns PI to the wanted accuracy. Note that under bigint, this is truncated
 532 to an integer, and hence simple '3'.
 533
 534 Example:
 535
 536         # perl -Mbigint=bpi -wle 'print bpi(80)'
 537
 538 =item upgrade()
 539
 540 Return the class that numbers are upgraded to, is in fact returning
 541 C<$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
 553 Returns true or false if C<bigint> is in effect in the current scope.
 554
 555 This method only works on Perl v5.9.4 or later.
 556
 557 =back
 558
 559 =head2 MATH LIBRARY
 560
 561 Math with the numbers is done (by default) by a module called
 562
 563 =head2 Caveat
 564
 565 But a warning is in order. When using the following to make a copy of a number,
 566 only a shallow copy will be made.
 567
 568         $x = 9; $y = $x;
 569         $x = $y = 7;
 570
 571 Using the copy or the original with overloaded math is okay, e.g. the
 572 following work:
 573
 574         $x = 9; $y = $x;
 575         print $x + 1, " ", $y,"\n";     # prints 10 9
 576
 577 but calling any method that modifies the number directly will result in
 578 B<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
 589 Using 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
 594 See the documentation about the copy constructor and C<=> in overload, as
 595 well as the documentation in BigInt for further details.
 596
 597 =head1 CAVAETS
 598
 599 =over 2
 600
 601 =item in_effect()
 602
 603 This method only works on Perl v5.9.4 or later.
 604
 605 =item hex()/oct()
 606
 607 C<bigint> overrides these routines with versions that can also handle
 608 big integer values. Under Perl prior to version v5.9.4, however, this
 609 will not happen unless you specifically ask for it with the two
 610 import tags "hex" and "oct" - and then it will be global and cannot be
 611 disabled 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
 621 The second call to hex() will warn about a non-portable constant.
 622
 623 Compare 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
 634 C<bigint> is just a thin wrapper around various modules of the Math::BigInt
 635 family. Think of it as the head of the family, who runs the shop, and orders
 636 the others to do the work.
 637
 638 The 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
 645 Some cool command line examples to impress the Python crowd ;) You might want
 646 to 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
 660 This program is free software; you may redistribute it and/or modify it under
 661 the same terms as Perl itself.
 662
 663 =head1 SEE ALSO
 664
 665 Especially L<bigrat> as in C<perl -Mbigrat -le 'print 1/3+1/4'> and
 666 L<bignum> as in C<perl -Mbignum -le 'print sqrt(2)'>.
 667
 668 L<Math::BigInt>, L<Math::BigRat> and L<Math::Big> as well
 669 as 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