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 sub import
 121   {
 122   my $self = shift;
 123
 124   $^H{bigint} = 1;                                      # we are in effect
 125
 126   # some defaults
 127   my $lib = ''; my $lib_kind = 'try';
 128
 129   my @import = ( ':constant' );                         # drive it w/ constant
 130   my @a = @_; my $l = scalar @_; my $j = 0;
 131   my ($ver,$trace);                                     # version? trace?
 132   my ($a,$p);                                           # accuracy, precision
 133   for ( my $i = 0; $i < $l ; $i++,$j++ )
 134     {
 135     if ($_[$i] =~ /^(l|lib|try|only)$/)
 136       {
 137       # this causes a different low lib to take care...
 138       $lib_kind = $1; $lib_kind = 'lib' if $lib_kind eq 'l';
 139       $lib = $_[$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] =~ /^(a|accuracy)$/)
 144       {
 145       $a = $_[$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] =~ /^(p|precision)$/)
 150       {
 151       $p = $_[$i+1];
 152       my $s = 2; $s = 1 if @a-$j < 2;   # avoid "can not modify non-existant..."
 153       splice @a, $j, $s; $j -= $s; $i++;
 154       }
 155     elsif ($_[$i] =~ /^(v|version)$/)
 156       {
 157       $ver = 1;
 158       splice @a, $j, 1; $j --;
 159       }
 160     elsif ($_[$i] =~ /^(t|trace)$/)
 161       {
 162       $trace = 1;
 163       splice @a, $j, 1; $j --;
 164       }
 165     else { die "unknown option $_[$i]"; }
 166     }
 167   my $class;
 168   $_lite = 0;                                   # using M::BI::L ?
 169   if ($trace)
 170     {
 171     require Math::BigInt::Trace; $class = 'Math::BigInt::Trace';
 172     }
 173   else
 174     {
 175     # see if we can find Math::BigInt::Lite
 176     if (!defined $a && !defined $p)             # rounding won't work to well
 177       {
 178       eval 'require Math::BigInt::Lite;';
 179       if ($@ eq '')
 180         {
 181         @import = ( );                          # :constant in Lite, not MBI
 182         Math::BigInt::Lite->import( ':constant' );
 183         $_lite= 1;                              # signal okay
 184         }
 185       }
 186     require Math::BigInt if $_lite == 0;        # not already loaded?
 187     $class = 'Math::BigInt';                    # regardless of MBIL or not
 188     }
 189   push @import, $lib_kind => $lib if $lib ne '';
 190   # Math::BigInt::Trace or plain Math::BigInt
 191   $class->import(@import);
 192
 193   bigint->accuracy($a) if defined $a;
 194   bigint->precision($p) if defined $p;
 195   if ($ver)
 196     {
 197     print "bigint\t\t\t v$VERSION\n";
 198     print "Math::BigInt::Lite\t v$Math::BigInt::Lite::VERSION\n" if $_lite;
 199     print "Math::BigInt\t\t v$Math::BigInt::VERSION";
 200     my $config = Math::BigInt->config();
 201     print " lib => $config->{lib} v$config->{lib_version}\n";
 202     exit;
 203     }
 204   # we take care of floating point constants, since BigFloat isn't available
 205   # and BigInt doesn't like them:
 206   overload::constant float => sub { Math::BigInt->new( _float_constant(shift) ); };
 207   # Take care of octal/hexadecimal constants
 208   overload::constant binary => sub { _binary_constant(shift) };
 209
 210   # if another big* was already loaded:
 211   my ($package) = caller();
 212
 213   no strict 'refs';
 214   if (!defined *{"${package}::inf"})
 215     {
 216     $self->export_to_level(1,$self,@a);           # export inf and NaN
 217     }
 218   }
 219
 220 sub inf () { Math::BigInt->binf(); }
 221 sub NaN () { Math::BigInt->bnan(); }
 222
 223 1;
 224
 225 __END__
 226
 227 =head1 NAME
 228
 229 bigint - Transparent BigInteger support for Perl
 230
 231 =head1 SYNOPSIS
 232
 233   use bigint;
 234
 235   $x = 2 + 4.5,"\n";                    # BigInt 6
 236   print 2 ** 512,"\n";                  # really is what you think it is
 237   print inf + 42,"\n";                  # inf
 238   print NaN * 7,"\n";                   # NaN
 239
 240   {
 241     no bigint;
 242     print 2 ** 256,"\n";                # a normal Perl scalar now
 243   }
 244
 245 =head1 DESCRIPTION
 246
 247 All operators (including basic math operations) are overloaded. Integer
 248 constants are created as proper BigInts.
 249
 250 Floating point constants are truncated to integer. All parts and results of
 251 expressions are also truncated.
 252
 253 Unlike L<integer>, this pragma creates integer constants that are only
 254 limited in their size by the available memory and CPU time.
 255
 256 =head2 use integer vs. use bigint
 257
 258 There is one small difference between C<use integer> and C<use bigint>: the
 259 former will not affect assignments to variables and the return value of
 260 some functions. C<bigint> truncates these results to integer too:
 261
 262         # perl -Minteger -wle 'print 3.2'
 263         3.2
 264         # perl -Minteger -wle 'print 3.2 + 0'
 265         3
 266         # perl -Mbigint -wle 'print 3.2'
 267         3
 268         # perl -Mbigint -wle 'print 3.2 + 0'
 269         3
 270
 271         # perl -Mbigint -wle 'print exp(1) + 0'
 272         2
 273         # perl -Mbigint -wle 'print exp(1)'
 274         2
 275         # perl -Mbigint -wle 'print exp(1)'
 276         2.71828182845905
 277         # perl -Mbigint -wle 'print exp(1) + 0'
 278         2
 279
 280 In practice this makes seldom a difference as B<parts and results> of
 281 expressions will be truncated anyway, but this can, for instance, affect the
 282 return value of subroutines:
 283
 284         sub three_integer { use integer; return 3.2; }
 285         sub three_bigint { use bigint; return 3.2; }
 286
 287         print three_integer(), " ", three_bigint(),"\n";        # prints "3.2 3"
 288
 289 =head2 Options
 290
 291 bigint recognizes some options that can be passed while loading it via use.
 292 The options can (currently) be either a single letter form, or the long form.
 293 The following options exist:
 294
 295 =over 2
 296
 297 =item a or accuracy
 298
 299 This sets the accuracy for all math operations. The argument must be greater
 300 than or equal to zero. See Math::BigInt's bround() function for details.
 301
 302         perl -Mbigint=a,2 -le 'print 12345+1'
 303
 304 Note that setting precision and accurary at the same time is not possible.
 305
 306 =item p or precision
 307
 308 This sets the precision for all math operations. The argument can be any
 309 integer. Negative values mean a fixed number of digits after the dot, and
 310 are <B>ignored</B> since all operations happen in integer space.
 311 A positive value rounds to this digit left from the dot. 0 or 1 mean round to
 312 integer and are ignore like negative values.
 313
 314 See Math::BigInt's bfround() function for details.
 315
 316         perl -Mbignum=p,5 -le 'print 123456789+123'
 317
 318 Note that setting precision and accurary at the same time is not possible.
 319
 320 =item t or trace
 321
 322 This enables a trace mode and is primarily for debugging bigint or
 323 Math::BigInt.
 324
 325 =item l, lib, try or only
 326
 327 Load a different math lib, see L<Math Library>.
 328
 329         perl -Mbigint=lib,GMP -e 'print 2 ** 512'
 330         perl -Mbigint=try,GMP -e 'print 2 ** 512'
 331         perl -Mbigint=only,GMP -e 'print 2 ** 512'
 332
 333 Currently there is no way to specify more than one library on the command
 334 line. This means the following does not work:
 335
 336         perl -Mbignum=l,GMP,Pari -e 'print 2 ** 512'
 337
 338 This will be hopefully fixed soon ;)
 339
 340 =item v or version
 341
 342 This prints out the name and version of all modules used and then exits.
 343
 344         perl -Mbigint=v
 345
 346 =back
 347
 348 =head2 Math Library
 349
 350 Math with the numbers is done (by default) by a module called
 351 Math::BigInt::Calc. This is equivalent to saying:
 352
 353         use bigint lib => 'Calc';
 354
 355 You can change this by using:
 356
 357         use bignum lib => 'GMP';
 358
 359 The following would first try to find Math::BigInt::Foo, then
 360 Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:
 361
 362         use bigint lib => 'Foo,Math::BigInt::Bar';
 363
 364 Using C<lib> warns if none of the specified libraries can be found and
 365 L<Math::BigInt> did fall back to one of the default libraries.
 366 To supress this warning, use C<try> instead:
 367
 368         use bignum try => 'GMP';
 369
 370 If you want the code to die instead of falling back, use C<only> instead:
 371
 372         use bignum only => 'GMP';
 373
 374 Please see respective module documentation for further details.
 375
 376 =head2 Internal Format
 377
 378 The numbers are stored as objects, and their internals might change at anytime,
 379 especially between math operations. The objects also might belong to different
 380 classes, like Math::BigInt, or Math::BigInt::Lite. Mixing them together, even
 381 with normal scalars is not extraordinary, but normal and expected.
 382
 383 You should not depend on the internal format, all accesses must go through
 384 accessor methods. E.g. looking at $x->{sign} is not a good idea since there
 385 is no guaranty that the object in question has such a hash key, nor is a hash
 386 underneath at all.
 387
 388 =head2 Sign
 389
 390 The sign is either '+', '-', 'NaN', '+inf' or '-inf'.
 391 You can access it with the sign() method.
 392
 393 A sign of 'NaN' is used to represent the result when input arguments are not
 394 numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively
 395 minus infinity. You will get '+inf' when dividing a positive number by 0, and
 396 '-inf' when dividing any negative number by 0.
 397
 398 =head2 Methods
 399
 400 Since all numbers are now objects, you can use all functions that are part of
 401 the BigInt API. You can only use the bxxx() notation, and not the fxxx()
 402 notation, though.
 403
 404 =over 2
 405
 406 =item inf()
 407
 408 A shortcut to return Math::BigInt->binf(). Useful because Perl does not always
 409 handle bareword C<inf> properly.
 410
 411 =item NaN()
 412
 413 A shortcut to return Math::BigInt->bnan(). Useful because Perl does not always
 414 handle bareword C<NaN> properly.
 415
 416 =item upgrade()
 417
 418 Return the class that numbers are upgraded to, is in fact returning
 419 C<$Math::BigInt::upgrade>.
 420
 421 =item in_effect()
 422
 423         use bigint;
 424
 425         print "in effect\n" if bigint::in_effect;       # true
 426         {
 427           no bigint;
 428           print "in effect\n" if bigint::in_effect;     # false
 429         }
 430
 431 Returns true or false if C<bigint> is in effect in the current scope.
 432
 433 This method only works on Perl v5.9.4 or later.
 434
 435 =back
 436
 437 =head2 MATH LIBRARY
 438
 439 Math with the numbers is done (by default) by a module called
 440
 441 =head2 Caveat
 442
 443 But a warning is in order. When using the following to make a copy of a number,
 444 only a shallow copy will be made.
 445
 446         $x = 9; $y = $x;
 447         $x = $y = 7;
 448
 449 Using the copy or the original with overloaded math is okay, e.g. the
 450 following work:
 451
 452         $x = 9; $y = $x;
 453         print $x + 1, " ", $y,"\n";     # prints 10 9
 454
 455 but calling any method that modifies the number directly will result in
 456 B<both> the original and the copy being destroyed:
 457
 458         $x = 9; $y = $x;
 459         print $x->badd(1), " ", $y,"\n";        # prints 10 10
 460
 461         $x = 9; $y = $x;
 462         print $x->binc(1), " ", $y,"\n";        # prints 10 10
 463
 464         $x = 9; $y = $x;
 465         print $x->bmul(2), " ", $y,"\n";        # prints 18 18
 466
 467 Using methods that do not modify, but testthe contents works:
 468
 469         $x = 9; $y = $x;
 470         $z = 9 if $x->is_zero();                # works fine
 471
 472 See the documentation about the copy constructor and C<=> in overload, as
 473 well as the documentation in BigInt for further details.
 474
 475 =head1 MODULES USED
 476
 477 C<bigint> is just a thin wrapper around various modules of the Math::BigInt
 478 family. Think of it as the head of the family, who runs the shop, and orders
 479 the others to do the work.
 480
 481 The following modules are currently used by bigint:
 482
 483         Math::BigInt::Lite      (for speed, and only if it is loadable)
 484         Math::BigInt
 485
 486 =head1 EXAMPLES
 487
 488 Some cool command line examples to impress the Python crowd ;) You might want
 489 to compare them to the results under -Mbignum or -Mbigrat:
 490
 491         perl -Mbigint -le 'print sqrt(33)'
 492         perl -Mbigint -le 'print 2*255'
 493         perl -Mbigint -le 'print 4.5+2*255'
 494         perl -Mbigint -le 'print 3/7 + 5/7 + 8/3'
 495         perl -Mbigint -le 'print 123->is_odd()'
 496         perl -Mbigint -le 'print log(2)'
 497         perl -Mbigint -le 'print 2 ** 0.5'
 498         perl -Mbigint=a,65 -le 'print 2 ** 0.2'
 499         perl -Mbignum=a,65,l,GMP -le 'print 7 ** 7777'
 500
 501 =head1 LICENSE
 502
 503 This program is free software; you may redistribute it and/or modify it under
 504 the same terms as Perl itself.
 505
 506 =head1 SEE ALSO
 507
 508 Especially L<bigrat> as in C<perl -Mbigrat -le 'print 1/3+1/4'> and
 509 L<bignum> as in C<perl -Mbignum -le 'print sqrt(2)'>.
 510
 511 L<Math::BigInt>, L<Math::BigRat> and L<Math::Big> as well
 512 as L<Math::BigInt::BitVect>, L<Math::BigInt::Pari> and  L<Math::BigInt::GMP>.
 513
 514 =head1 AUTHORS
 515
 516 (C) by Tels L<http://bloodgate.com/> in early 2002 - 2007.
 517
 518 =cut