[Summary view] [Print] [Text view]

   1  package bignum;
   2  use 5.006002;
   3  
   4  $VERSION = '0.22';
   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