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( );
   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     else { die "unknown option $_[$i]"; }
 219     }
 220   my $class;
 221   $_lite = 0;                                   # using M::BI::L ?
 222   if ($trace)
 223     {
 224     require Math::BigInt::Trace; $class = 'Math::BigInt::Trace';
 225     }
 226   else
 227     {
 228     # see if we can find Math::BigInt::Lite
 229     if (!defined $a && !defined $p)             # rounding won't work to well
 230       {
 231       eval 'require Math::BigInt::Lite;';
 232       if ($@ eq '')
 233         {
 234         @import = ( );                          # :constant in Lite, not MBI
 235         Math::BigInt::Lite->import( ':constant' );
 236         $_lite= 1;                              # signal okay
 237         }
 238       }
 239     require Math::BigInt if $_lite == 0;        # not already loaded?
 240     $class = 'Math::BigInt';                    # regardless of MBIL or not
 241     }
 242   push @import, $lib_kind => $lib if $lib ne '';
 243   # Math::BigInt::Trace or plain Math::BigInt
 244   $class->import(@import);
 245
 246   bigint->accuracy($a) if defined $a;
 247   bigint->precision($p) if defined $p;
 248   if ($ver)
 249     {
 250     print "bigint\t\t\t v$VERSION\n";
 251     print "Math::BigInt::Lite\t v$Math::BigInt::Lite::VERSION\n" if $_lite;
 252     print "Math::BigInt\t\t v$Math::BigInt::VERSION";
 253     my $config = Math::BigInt->config();
 254     print " lib => $config->{lib} v$config->{lib_version}\n";
 255     exit;
 256     }
 257   # we take care of floating point constants, since BigFloat isn't available
 258   # and BigInt doesn't like them:
 259   overload::constant float => sub { Math::BigInt->new( _float_constant(shift) ); };
 260   # Take care of octal/hexadecimal constants
 261   overload::constant binary => sub { _binary_constant(shift) };
 262
 263   # if another big* was already loaded:
 264   my ($package) = caller();
 265
 266   no strict 'refs';
 267   if (!defined *{"${package}::inf"})
 268     {
 269     $self->export_to_level(1,$self,@a);           # export inf and NaN
 270     }
 271   {
 272     no warnings 'redefine';
 273     *CORE::GLOBAL::oct = $oct if $oct;
 274     *CORE::GLOBAL::hex = $hex if $hex;
 275   }
 276   }
 277
 278 sub inf () { Math::BigInt->binf(); }
 279 sub NaN () { Math::BigInt->bnan(); }
 280
 281 1;
 282
 283 __END__
 284
 285 =head1 NAME
 286
 287 bigint - Transparent BigInteger support for Perl
 288
 289 =head1 SYNOPSIS
 290
 291   use bigint;
 292
 293   $x = 2 + 4.5,"\n";                    # BigInt 6
 294   print 2 ** 512,"\n";                  # really is what you think it is
 295   print inf + 42,"\n";                  # inf
 296   print NaN * 7,"\n";                   # NaN
 297   print hex("0x1234567890123490"),"\n"; # Perl v5.9.4 or later
 298
 299   {
 300     no bigint;
 301     print 2 ** 256,"\n";                # a normal Perl scalar now
 302   }
 303
 304   # Note that this will be global:
 305   use bigint qw/hex oct/;
 306   print hex("0x1234567890123490"),"\n";
 307   print oct("01234567890123490"),"\n";
 308
 309 =head1 DESCRIPTION
 310
 311 All operators (including basic math operations) are overloaded. Integer
 312 constants are created as proper BigInts.
 313
 314 Floating point constants are truncated to integer. All parts and results of
 315 expressions are also truncated.
 316
 317 Unlike L<integer>, this pragma creates integer constants that are only
 318 limited in their size by the available memory and CPU time.
 319
 320 =head2 use integer vs. use bigint
 321
 322 There is one small difference between C<use integer> and C<use bigint>: the
 323 former will not affect assignments to variables and the return value of
 324 some functions. C<bigint> truncates these results to integer too:
 325
 326         # perl -Minteger -wle 'print 3.2'
 327         3.2
 328         # perl -Minteger -wle 'print 3.2 + 0'
 329         3
 330         # perl -Mbigint -wle 'print 3.2'
 331         3
 332         # perl -Mbigint -wle 'print 3.2 + 0'
 333         3
 334
 335         # perl -Mbigint -wle 'print exp(1) + 0'
 336         2
 337         # perl -Mbigint -wle 'print exp(1)'
 338         2
 339         # perl -Minteger -wle 'print exp(1)'
 340         2.71828182845905
 341         # perl -Minteger -wle 'print exp(1) + 0'
 342         2
 343
 344 In practice this makes seldom a difference as B<parts and results> of
 345 expressions will be truncated anyway, but this can, for instance, affect the
 346 return value of subroutines:
 347
 348         sub three_integer { use integer; return 3.2; }
 349         sub three_bigint { use bigint; return 3.2; }
 350
 351         print three_integer(), " ", three_bigint(),"\n";        # prints "3.2 3"
 352
 353 =head2 Options
 354
 355 bigint recognizes some options that can be passed while loading it via use.
 356 The options can (currently) be either a single letter form, or the long form.
 357 The following options exist:
 358
 359 =over 2
 360
 361 =item a or accuracy
 362
 363 This sets the accuracy for all math operations. The argument must be greater
 364 than or equal to zero. See Math::BigInt's bround() function for details.
 365
 366         perl -Mbigint=a,2 -le 'print 12345+1'
 367
 368 Note that setting precision and accurary at the same time is not possible.
 369
 370 =item p or precision
 371
 372 This sets the precision for all math operations. The argument can be any
 373 integer. Negative values mean a fixed number of digits after the dot, and
 374 are <B>ignored</B> since all operations happen in integer space.
 375 A positive value rounds to this digit left from the dot. 0 or 1 mean round to
 376 integer and are ignore like negative values.
 377
 378 See Math::BigInt's bfround() function for details.
 379
 380         perl -Mbignum=p,5 -le 'print 123456789+123'
 381
 382 Note that setting precision and accurary at the same time is not possible.
 383
 384 =item t or trace
 385
 386 This enables a trace mode and is primarily for debugging bigint or
 387 Math::BigInt.
 388
 389 =item hex
 390
 391 Override the build-in hex() method with a version that can handle big
 392 integers. Note that under Perl v5.9.4 or ealier, this will be global
 393 and cannot be disabled with "no bigint;".
 394
 395 =item oct
 396
 397 Override the build-in oct() method with a version that can handle big
 398 integers. Note that under Perl v5.9.4 or ealier, this will be global
 399 and cannot be disabled with "no bigint;".
 400
 401 =item l, lib, try or only
 402
 403 Load a different math lib, see L<Math Library>.
 404
 405         perl -Mbigint=lib,GMP -e 'print 2 ** 512'
 406         perl -Mbigint=try,GMP -e 'print 2 ** 512'
 407         perl -Mbigint=only,GMP -e 'print 2 ** 512'
 408
 409 Currently there is no way to specify more than one library on the command
 410 line. This means the following does not work:
 411
 412         perl -Mbignum=l,GMP,Pari -e 'print 2 ** 512'
 413
 414 This will be hopefully fixed soon ;)
 415
 416 =item v or version
 417
 418 This prints out the name and version of all modules used and then exits.
 419
 420         perl -Mbigint=v
 421
 422 =back
 423
 424 =head2 Math Library
 425
 426 Math with the numbers is done (by default) by a module called
 427 Math::BigInt::Calc. This is equivalent to saying:
 428
 429         use bigint lib => 'Calc';
 430
 431 You can change this by using:
 432
 433         use bignum lib => 'GMP';
 434
 435 The following would first try to find Math::BigInt::Foo, then
 436 Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:
 437
 438         use bigint lib => 'Foo,Math::BigInt::Bar';
 439
 440 Using C<lib> warns if none of the specified libraries can be found and
 441 L<Math::BigInt> did fall back to one of the default libraries.
 442 To supress this warning, use C<try> instead:
 443
 444         use bignum try => 'GMP';
 445
 446 If you want the code to die instead of falling back, use C<only> instead:
 447
 448         use bignum only => 'GMP';
 449
 450 Please see respective module documentation for further details.
 451
 452 =head2 Internal Format
 453
 454 The numbers are stored as objects, and their internals might change at anytime,
 455 especially between math operations. The objects also might belong to different
 456 classes, like Math::BigInt, or Math::BigInt::Lite. Mixing them together, even
 457 with normal scalars is not extraordinary, but normal and expected.
 458
 459 You should not depend on the internal format, all accesses must go through
 460 accessor methods. E.g. looking at $x->{sign} is not a good idea since there
 461 is no guaranty that the object in question has such a hash key, nor is a hash
 462 underneath at all.
 463
 464 =head2 Sign
 465
 466 The sign is either '+', '-', 'NaN', '+inf' or '-inf'.
 467 You can access it with the sign() method.
 468
 469 A sign of 'NaN' is used to represent the result when input arguments are not
 470 numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively
 471 minus infinity. You will get '+inf' when dividing a positive number by 0, and
 472 '-inf' when dividing any negative number by 0.
 473
 474 =head2 Methods
 475
 476 Since all numbers are now objects, you can use all functions that are part of
 477 the BigInt API. You can only use the bxxx() notation, and not the fxxx()
 478 notation, though.
 479
 480 =over 2
 481
 482 =item inf()
 483
 484 A shortcut to return Math::BigInt->binf(). Useful because Perl does not always
 485 handle bareword C<inf> properly.
 486
 487 =item NaN()
 488
 489 A shortcut to return Math::BigInt->bnan(). Useful because Perl does not always
 490 handle bareword C<NaN> properly.
 491
 492 =item upgrade()
 493
 494 Return the class that numbers are upgraded to, is in fact returning
 495 C<$Math::BigInt::upgrade>.
 496
 497 =item in_effect()
 498
 499         use bigint;
 500
 501         print "in effect\n" if bigint::in_effect;       # true
 502         {
 503           no bigint;
 504           print "in effect\n" if bigint::in_effect;     # false
 505         }
 506
 507 Returns true or false if C<bigint> is in effect in the current scope.
 508
 509 This method only works on Perl v5.9.4 or later.
 510
 511 =back
 512
 513 =head2 MATH LIBRARY
 514
 515 Math with the numbers is done (by default) by a module called
 516
 517 =head2 Caveat
 518
 519 But a warning is in order. When using the following to make a copy of a number,
 520 only a shallow copy will be made.
 521
 522         $x = 9; $y = $x;
 523         $x = $y = 7;
 524
 525 Using the copy or the original with overloaded math is okay, e.g. the
 526 following work:
 527
 528         $x = 9; $y = $x;
 529         print $x + 1, " ", $y,"\n";     # prints 10 9
 530
 531 but calling any method that modifies the number directly will result in
 532 B<both> the original and the copy being destroyed:
 533
 534         $x = 9; $y = $x;
 535         print $x->badd(1), " ", $y,"\n";        # prints 10 10
 536
 537         $x = 9; $y = $x;
 538         print $x->binc(1), " ", $y,"\n";        # prints 10 10
 539
 540         $x = 9; $y = $x;
 541         print $x->bmul(2), " ", $y,"\n";        # prints 18 18
 542
 543 Using methods that do not modify, but testthe contents works:
 544
 545         $x = 9; $y = $x;
 546         $z = 9 if $x->is_zero();                # works fine
 547
 548 See the documentation about the copy constructor and C<=> in overload, as
 549 well as the documentation in BigInt for further details.
 550
 551 =head1 CAVAETS
 552
 553 =over 2
 554
 555 =item in_effect()
 556
 557 This method only works on Perl v5.9.4 or later.
 558
 559 =item hex()/oct()
 560
 561 C<bigint> overrides these routines with versions that can also handle
 562 big integer values. Under Perl prior to version v5.9.4, however, this
 563 will not happen unless you specifically ask for it with the two
 564 import tags "hex" and "oct" - and then it will be global and cannot be
 565 disabled inside a scope with "no bigint":
 566
 567         use bigint qw/hex oct/;
 568
 569         print hex("0x1234567890123456");
 570         {
 571                 no bigint;
 572                 print hex("0x1234567890123456");
 573         }
 574
 575 The second call to hex() will warn about a non-portable constant.
 576
 577 Compare this to:
 578
 579         use bigint;
 580
 581         # will warn only under Perl older than v5.9.4
 582         print hex("0x1234567890123456");
 583
 584 =back
 585
 586 =head1 MODULES USED
 587
 588 C<bigint> is just a thin wrapper around various modules of the Math::BigInt
 589 family. Think of it as the head of the family, who runs the shop, and orders
 590 the others to do the work.
 591
 592 The following modules are currently used by bigint:
 593
 594         Math::BigInt::Lite      (for speed, and only if it is loadable)
 595         Math::BigInt
 596
 597 =head1 EXAMPLES
 598
 599 Some cool command line examples to impress the Python crowd ;) You might want
 600 to compare them to the results under -Mbignum or -Mbigrat:
 601
 602         perl -Mbigint -le 'print sqrt(33)'
 603         perl -Mbigint -le 'print 2*255'
 604         perl -Mbigint -le 'print 4.5+2*255'
 605         perl -Mbigint -le 'print 3/7 + 5/7 + 8/3'
 606         perl -Mbigint -le 'print 123->is_odd()'
 607         perl -Mbigint -le 'print log(2)'
 608         perl -Mbigint -le 'print 2 ** 0.5'
 609         perl -Mbigint=a,65 -le 'print 2 ** 0.2'
 610         perl -Mbignum=a,65,l,GMP -le 'print 7 ** 7777'
 611
 612 =head1 LICENSE
 613
 614 This program is free software; you may redistribute it and/or modify it under
 615 the same terms as Perl itself.
 616
 617 =head1 SEE ALSO
 618
 619 Especially L<bigrat> as in C<perl -Mbigrat -le 'print 1/3+1/4'> and
 620 L<bignum> as in C<perl -Mbignum -le 'print sqrt(2)'>.
 621
 622 L<Math::BigInt>, L<Math::BigRat> and L<Math::Big> as well
 623 as L<Math::BigInt::BitVect>, L<Math::BigInt::Pari> and  L<Math::BigInt::GMP>.
 624
 625 =head1 AUTHORS
 626
 627 (C) by Tels L<http://bloodgate.com/> in early 2002 - 2007.
 628
 629 =cut