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 results are also
 251 truncated.
 252
 253 =head2 Options
 254
 255 bigint recognizes some options that can be passed while loading it via use.
 256 The options can (currently) be either a single letter form, or the long form.
 257 The following options exist:
 258
 259 =over 2
 260
 261 =item a or accuracy
 262
 263 This sets the accuracy for all math operations. The argument must be greater
 264 than or equal to zero. See Math::BigInt's bround() function for details.
 265
 266         perl -Mbigint=a,2 -le 'print 12345+1'
 267
 268 Note that setting precision and accurary at the same time is not possible.
 269
 270 =item p or precision
 271
 272 This sets the precision for all math operations. The argument can be any
 273 integer. Negative values mean a fixed number of digits after the dot, and
 274 are <B>ignored</B> since all operations happen in integer space.
 275 A positive value rounds to this digit left from the dot. 0 or 1 mean round to
 276 integer and are ignore like negative values.
 277
 278 See Math::BigInt's bfround() function for details.
 279
 280         perl -Mbignum=p,5 -le 'print 123456789+123'
 281
 282 Note that setting precision and accurary at the same time is not possible.
 283
 284 =item t or trace
 285
 286 This enables a trace mode and is primarily for debugging bigint or
 287 Math::BigInt.
 288
 289 =item l, lib, try or only
 290
 291 Load a different math lib, see L<Math Library>.
 292
 293         perl -Mbigint=lib,GMP -e 'print 2 ** 512'
 294         perl -Mbigint=try,GMP -e 'print 2 ** 512'
 295         perl -Mbigint=only,GMP -e 'print 2 ** 512'
 296
 297 Currently there is no way to specify more than one library on the command
 298 line. This means the following does not work:
 299
 300         perl -Mbignum=l,GMP,Pari -e 'print 2 ** 512'
 301
 302 This will be hopefully fixed soon ;)
 303
 304 =item v or version
 305
 306 This prints out the name and version of all modules used and then exits.
 307
 308         perl -Mbigint=v
 309
 310 =back
 311
 312 =head2 Math Library
 313
 314 Math with the numbers is done (by default) by a module called
 315 Math::BigInt::Calc. This is equivalent to saying:
 316
 317         use bigint lib => 'Calc';
 318
 319 You can change this by using:
 320
 321         use bignum lib => 'GMP';
 322
 323 The following would first try to find Math::BigInt::Foo, then
 324 Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:
 325
 326         use bigint lib => 'Foo,Math::BigInt::Bar';
 327
 328 Using C<lib> warns if none of the specified libraries can be found and
 329 L<Math::BigInt> did fall back to one of the default libraries.
 330 To supress this warning, use C<try> instead:
 331
 332         use bignum try => 'GMP';
 333
 334 If you want the code to die instead of falling back, use C<only> instead:
 335
 336         use bignum only => 'GMP';
 337
 338 Please see respective module documentation for further details.
 339
 340 =head2 Internal Format
 341
 342 The numbers are stored as objects, and their internals might change at anytime,
 343 especially between math operations. The objects also might belong to different
 344 classes, like Math::BigInt, or Math::BigInt::Lite. Mixing them together, even
 345 with normal scalars is not extraordinary, but normal and expected.
 346
 347 You should not depend on the internal format, all accesses must go through
 348 accessor methods. E.g. looking at $x->{sign} is not a good idea since there
 349 is no guaranty that the object in question has such a hash key, nor is a hash
 350 underneath at all.
 351
 352 =head2 Sign
 353
 354 The sign is either '+', '-', 'NaN', '+inf' or '-inf'.
 355 You can access it with the sign() method.
 356
 357 A sign of 'NaN' is used to represent the result when input arguments are not
 358 numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively
 359 minus infinity. You will get '+inf' when dividing a positive number by 0, and
 360 '-inf' when dividing any negative number by 0.
 361
 362 =head2 Methods
 363
 364 Since all numbers are now objects, you can use all functions that are part of
 365 the BigInt API. You can only use the bxxx() notation, and not the fxxx()
 366 notation, though.
 367
 368 =over 2
 369
 370 =item inf()
 371
 372 A shortcut to return Math::BigInt->binf(). Useful because Perl does not always
 373 handle bareword C<inf> properly.
 374
 375 =item NaN()
 376
 377 A shortcut to return Math::BigInt->bnan(). Useful because Perl does not always
 378 handle bareword C<NaN> properly.
 379
 380 =item upgrade()
 381
 382 Return the class that numbers are upgraded to, is in fact returning
 383 C<$Math::BigInt::upgrade>.
 384
 385 =item in_effect()
 386
 387         use bigint;
 388
 389         print "in effect\n" if bigint::in_effect;       # true
 390         {
 391           no bigint;
 392           print "in effect\n" if bigint::in_effect;     # false
 393         }
 394
 395 Returns true or false if C<bigint> is in effect in the current scope.
 396
 397 This method only works on Perl v5.9.4 or later.
 398
 399 =back
 400
 401 =head2 MATH LIBRARY
 402
 403 Math with the numbers is done (by default) by a module called
 404
 405 =head2 Caveat
 406
 407 But a warning is in order. When using the following to make a copy of a number,
 408 only a shallow copy will be made.
 409
 410         $x = 9; $y = $x;
 411         $x = $y = 7;
 412
 413 Using the copy or the original with overloaded math is okay, e.g. the
 414 following work:
 415
 416         $x = 9; $y = $x;
 417         print $x + 1, " ", $y,"\n";     # prints 10 9
 418
 419 but calling any method that modifies the number directly will result in
 420 B<both> the original and the copy being destroyed:
 421
 422         $x = 9; $y = $x;
 423         print $x->badd(1), " ", $y,"\n";        # prints 10 10
 424
 425         $x = 9; $y = $x;
 426         print $x->binc(1), " ", $y,"\n";        # prints 10 10
 427
 428         $x = 9; $y = $x;
 429         print $x->bmul(2), " ", $y,"\n";        # prints 18 18
 430
 431 Using methods that do not modify, but testthe contents works:
 432
 433         $x = 9; $y = $x;
 434         $z = 9 if $x->is_zero();                # works fine
 435
 436 See the documentation about the copy constructor and C<=> in overload, as
 437 well as the documentation in BigInt for further details.
 438
 439 =head1 MODULES USED
 440
 441 C<bigint> is just a thin wrapper around various modules of the Math::BigInt
 442 family. Think of it as the head of the family, who runs the shop, and orders
 443 the others to do the work.
 444
 445 The following modules are currently used by bigint:
 446
 447         Math::BigInt::Lite      (for speed, and only if it is loadable)
 448         Math::BigInt
 449
 450 =head1 EXAMPLES
 451
 452 Some cool command line examples to impress the Python crowd ;) You might want
 453 to compare them to the results under -Mbignum or -Mbigrat:
 454
 455         perl -Mbigint -le 'print sqrt(33)'
 456         perl -Mbigint -le 'print 2*255'
 457         perl -Mbigint -le 'print 4.5+2*255'
 458         perl -Mbigint -le 'print 3/7 + 5/7 + 8/3'
 459         perl -Mbigint -le 'print 123->is_odd()'
 460         perl -Mbigint -le 'print log(2)'
 461         perl -Mbigint -le 'print 2 ** 0.5'
 462         perl -Mbigint=a,65 -le 'print 2 ** 0.2'
 463         perl -Mbignum=a,65,l,GMP -le 'print 7 ** 7777'
 464
 465 =head1 LICENSE
 466
 467 This program is free software; you may redistribute it and/or modify it under
 468 the same terms as Perl itself.
 469
 470 =head1 SEE ALSO
 471
 472 Especially L<bigrat> as in C<perl -Mbigrat -le 'print 1/3+1/4'> and
 473 L<bignum> as in C<perl -Mbignum -le 'print sqrt(2)'>.
 474
 475 L<Math::BigInt>, L<Math::BigRat> and L<Math::Big> as well
 476 as L<Math::BigInt::BitVect>, L<Math::BigInt::Pari> and  L<Math::BigInt::GMP>.
 477
 478 =head1 AUTHORS
 479
 480 (C) by Tels L<http://bloodgate.com/> in early 2002 - 2007.
 481
 482 =cut