lib/bigrat.pm

   1 package bigrat;
   2 use 5.006002;
   3
   4 $VERSION = '0.22';
   5 require Exporter;
   6 @ISA            = qw( bigint );
   7 @EXPORT_OK      = qw( );
   8 @EXPORT         = qw( inf NaN );
   9
  10 use strict;
  11 use overload;
  12 require bigint;         # no "use" to avoid callind import
  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       *{"bigrat::$name"} = sub
  38         {
  39         my $self = shift;
  40         no strict 'refs';
  41         if (defined $_[0])
  42           {
  43           Math::BigInt->$name($_[0]);
  44           Math::BigFloat->$name($_[0]);
  45           return Math::BigRat->$name($_[0]);
  46           }
  47         return Math::BigInt->$name();
  48         };
  49       return &$name;
  50       }
  51     }
  52
  53   # delayed load of Carp and avoid recursion
  54   require Carp;
  55   Carp::croak ("Can't call bigrat\-\>$name, not a valid method");
  56   }
  57
  58 sub unimport
  59   {
  60   $^H{bigrat} = undef;                                  # no longer in effect
  61   overload::remove_constant('binary','','float','','integer');
  62   }
  63
  64 sub in_effect
  65   {
  66   my $level = shift || 0;
  67   my $hinthash = (caller($level))[10];
  68   $hinthash->{bigrat};
  69   }
  70
  71 #############################################################################
  72 # the following two routines are for Perl 5.9.4 or later and are lexical
  73
  74 sub _hex
  75   {
  76   return CORE::hex($_[0]) unless in_effect(1);
  77   my $i = $_[0];
  78   $i = '0x'.$i unless $i =~ /^0x/;
  79   Math::BigInt->new($i);
  80   }
  81
  82 sub _oct
  83   {
  84   return CORE::oct($_[0]) unless in_effect(1);
  85   my $i = $_[0];
  86   return Math::BigInt->from_oct($i) if $i =~ /^0[0-7]/;
  87   Math::BigInt->new($i);
  88   }
  89
  90 sub import
  91   {
  92   my $self = shift;
  93
  94   # see also bignum->import() for additional comments
  95
  96   $^H{bigrat} = 1;                                      # we are in effect
  97
  98   my ($hex,$oct);
  99   # for newer Perls always override hex() and oct() with a lexical version:
 100   if ($] > 5.009004)
 101     {
 102     $oct = \&_oct;
 103     $hex = \&_hex;
 104     }
 105   # some defaults
 106   my $lib = ''; my $lib_kind = 'try'; my $upgrade = 'Math::BigFloat';
 107
 108   my @import = ( ':constant' );                         # drive it w/ constant
 109   my @a = @_; my $l = scalar @_; my $j = 0;
 110   my ($a,$p);
 111   my ($ver,$trace);                                     # version? trace?
 112   for ( my $i = 0; $i < $l ; $i++,$j++ )
 113     {
 114     if ($_[$i] eq 'upgrade')
 115       {
 116       # this causes upgrading
 117       $upgrade = $_[$i+1];              # or undef to disable
 118       my $s = 2; $s = 1 if @a-$j < 2;   # avoid "can not modify non-existant..."
 119       splice @a, $j, $s; $j -= $s;
 120       }
 121     elsif ($_[$i] =~ /^(l|lib|try|only)$/)
 122       {
 123       # this causes a different low lib to take care...
 124       $lib_kind = $1; $lib_kind = 'lib' if $lib_kind eq 'l';
 125       $lib = $_[$i+1] || '';
 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] =~ /^(a|accuracy)$/)
 130       {
 131       $a = $_[$i+1];
 132       my $s = 2; $s = 1 if @a-$j < 2;   # avoid "can not modify non-existant..."
 133       splice @a, $j, $s; $j -= $s; $i++;
 134       }
 135     elsif ($_[$i] =~ /^(p|precision)$/)
 136       {
 137       $p = $_[$i+1];
 138       my $s = 2; $s = 1 if @a-$j < 2;   # avoid "can not modify non-existant..."
 139       splice @a, $j, $s; $j -= $s; $i++;
 140       }
 141     elsif ($_[$i] =~ /^(v|version)$/)
 142       {
 143       $ver = 1;
 144       splice @a, $j, 1; $j --;
 145       }
 146     elsif ($_[$i] =~ /^(t|trace)$/)
 147       {
 148       $trace = 1;
 149       splice @a, $j, 1; $j --;
 150       }
 151     elsif ($_[$i] eq 'hex')
 152       {
 153       splice @a, $j, 1; $j --;
 154       $hex = \&bigint::_hex_global;
 155       }
 156     elsif ($_[$i] eq 'oct')
 157       {
 158       splice @a, $j, 1; $j --;
 159       $oct = \&bigint::_oct_global;
 160       }
 161     else
 162       {
 163       die ("unknown option $_[$i]");
 164       }
 165     }
 166   my $class;
 167   $_lite = 0;                                   # using M::BI::L ?
 168   if ($trace)
 169     {
 170     require Math::BigInt::Trace; $class = 'Math::BigInt::Trace';
 171     $upgrade = 'Math::BigFloat::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, upgrade => $upgrade);
 192
 193   require Math::BigFloat;
 194   Math::BigFloat->import( upgrade => 'Math::BigRat', ':constant' );
 195   require Math::BigRat;
 196
 197   bigrat->accuracy($a) if defined $a;
 198   bigrat->precision($p) if defined $p;
 199   if ($ver)
 200     {
 201     print "bigrat\t\t\t v$VERSION\n";
 202     print "Math::BigInt::Lite\t v$Math::BigInt::Lite::VERSION\n" if $_lite;
 203     print "Math::BigInt\t\t v$Math::BigInt::VERSION";
 204     my $config = Math::BigInt->config();
 205     print " lib => $config->{lib} v$config->{lib_version}\n";
 206     print "Math::BigFloat\t\t v$Math::BigFloat::VERSION\n";
 207     print "Math::BigRat\t\t v$Math::BigRat::VERSION\n";
 208     exit;
 209     }
 210
 211   # Take care of octal/hexadecimal constants
 212   overload::constant binary => sub { bigint::_binary_constant(shift) };
 213
 214   # if another big* was already loaded:
 215   my ($package) = caller();
 216
 217   no strict 'refs';
 218   if (!defined *{"${package}::inf"})
 219     {
 220     $self->export_to_level(1,$self,@a);           # export inf and NaN
 221     }
 222   {
 223     no warnings 'redefine';
 224     *CORE::GLOBAL::oct = $oct if $oct;
 225     *CORE::GLOBAL::hex = $hex if $hex;
 226   }
 227   }
 228
 229 1;
 230
 231 __END__
 232
 233 =head1 NAME
 234
 235 bigrat - Transparent BigNumber/BigRational support for Perl
 236
 237 =head1 SYNOPSIS
 238
 239   use bigrat;
 240
 241   print 2 + 4.5,"\n";                   # BigFloat 6.5
 242   print 1/3 + 1/4,"\n";                 # produces 7/12
 243
 244   {
 245     no bigrat;
 246     print 1/3,"\n";                     # 0.33333...
 247   }
 248
 249   # Note that this will make hex() and oct() be globally overriden:
 250   use bigrat qw/hex oct/;
 251   print hex("0x1234567890123490"),"\n";
 252   print oct("01234567890123490"),"\n";
 253
 254 =head1 DESCRIPTION
 255
 256 All operators (including basic math operations) are overloaded. Integer and
 257 floating-point constants are created as proper BigInts or BigFloats,
 258 respectively.
 259
 260 Other than L<bignum>, this module upgrades to Math::BigRat, meaning that
 261 instead of 2.5 you will get 2+1/2 as output.
 262
 263 =head2 Modules Used
 264
 265 C<bigrat> is just a thin wrapper around various modules of the Math::BigInt
 266 family. Think of it as the head of the family, who runs the shop, and orders
 267 the others to do the work.
 268
 269 The following modules are currently used by bignum:
 270
 271         Math::BigInt::Lite      (for speed, and only if it is loadable)
 272         Math::BigInt
 273         Math::BigFloat
 274         Math::BigRat
 275
 276 =head2 Math Library
 277
 278 Math with the numbers is done (by default) by a module called
 279 Math::BigInt::Calc. This is equivalent to saying:
 280
 281         use bigrat lib => 'Calc';
 282
 283 You can change this by using:
 284
 285         use bignum lib => 'GMP';
 286
 287 The following would first try to find Math::BigInt::Foo, then
 288 Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:
 289
 290         use bigrat lib => 'Foo,Math::BigInt::Bar';
 291
 292 Using C<lib> warns if none of the specified libraries can be found and
 293 L<Math::BigInt> did fall back to one of the default libraries.
 294 To supress this warning, use C<try> instead:
 295
 296         use bignum try => 'GMP';
 297
 298 If you want the code to die instead of falling back, use C<only> instead:
 299
 300         use bignum only => 'GMP';
 301
 302 Please see respective module documentation for further details.
 303
 304 =head2 Sign
 305
 306 The sign is either '+', '-', 'NaN', '+inf' or '-inf'.
 307
 308 A sign of 'NaN' is used to represent the result when input arguments are not
 309 numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively
 310 minus infinity. You will get '+inf' when dividing a positive number by 0, and
 311 '-inf' when dividing any negative number by 0.
 312
 313 =head2 Methods
 314
 315 Since all numbers are not objects, you can use all functions that are part of
 316 the BigInt or BigFloat API. It is wise to use only the bxxx() notation, and not
 317 the fxxx() notation, though. This makes you independed on the fact that the
 318 underlying object might morph into a different class than BigFloat.
 319
 320 =over 2
 321
 322 =item inf()
 323
 324 A shortcut to return Math::BigInt->binf(). Useful because Perl does not always
 325 handle bareword C<inf> properly.
 326
 327 =item NaN()
 328
 329 A shortcut to return Math::BigInt->bnan(). Useful because Perl does not always
 330 handle bareword C<NaN> properly.
 331
 332 =item upgrade()
 333
 334 Return the class that numbers are upgraded to, is in fact returning
 335 C<$Math::BigInt::upgrade>.
 336
 337 =item in_effect()
 338
 339         use bigrat;
 340
 341         print "in effect\n" if bigrat::in_effect;       # true
 342         {
 343           no bigrat;
 344           print "in effect\n" if bigrat::in_effect;     # false
 345         }
 346
 347 Returns true or false if C<bigrat> is in effect in the current scope.
 348
 349 This method only works on Perl v5.9.4 or later.
 350
 351 =back
 352
 353 =head2 MATH LIBRARY
 354
 355 Math with the numbers is done (by default) by a module called
 356
 357 =head2 Cavaet
 358
 359 But a warning is in order. When using the following to make a copy of a number,
 360 only a shallow copy will be made.
 361
 362         $x = 9; $y = $x;
 363         $x = $y = 7;
 364
 365 If you want to make a real copy, use the following:
 366
 367         $y = $x->copy();
 368
 369 Using the copy or the original with overloaded math is okay, e.g. the
 370 following work:
 371
 372         $x = 9; $y = $x;
 373         print $x + 1, " ", $y,"\n";     # prints 10 9
 374
 375 but calling any method that modifies the number directly will result in
 376 B<both> the original and the copy being destroyed:
 377
 378         $x = 9; $y = $x;
 379         print $x->badd(1), " ", $y,"\n";        # prints 10 10
 380
 381         $x = 9; $y = $x;
 382         print $x->binc(1), " ", $y,"\n";        # prints 10 10
 383
 384         $x = 9; $y = $x;
 385         print $x->bmul(2), " ", $y,"\n";        # prints 18 18
 386
 387 Using methods that do not modify, but testthe contents works:
 388
 389         $x = 9; $y = $x;
 390         $z = 9 if $x->is_zero();                # works fine
 391
 392 See the documentation about the copy constructor and C<=> in overload, as
 393 well as the documentation in BigInt for further details.
 394
 395 =head2 Options
 396
 397 bignum recognizes some options that can be passed while loading it via use.
 398 The options can (currently) be either a single letter form, or the long form.
 399 The following options exist:
 400
 401 =over 2
 402
 403 =item a or accuracy
 404
 405 This sets the accuracy for all math operations. The argument must be greater
 406 than or equal to zero. See Math::BigInt's bround() function for details.
 407
 408         perl -Mbigrat=a,50 -le 'print sqrt(20)'
 409
 410 Note that setting precision and accurary at the same time is not possible.
 411
 412 =item p or precision
 413
 414 This sets the precision for all math operations. The argument can be any
 415 integer. Negative values mean a fixed number of digits after the dot, while
 416 a positive value rounds to this digit left from the dot. 0 or 1 mean round to
 417 integer. See Math::BigInt's bfround() function for details.
 418
 419         perl -Mbigrat=p,-50 -le 'print sqrt(20)'
 420
 421 Note that setting precision and accurary at the same time is not possible.
 422
 423 =item t or trace
 424
 425 This enables a trace mode and is primarily for debugging bignum or
 426 Math::BigInt/Math::BigFloat.
 427
 428 =item l or lib
 429
 430 Load a different math lib, see L<MATH LIBRARY>.
 431
 432         perl -Mbigrat=l,GMP -e 'print 2 ** 512'
 433
 434 Currently there is no way to specify more than one library on the command
 435 line. This means the following does not work:
 436
 437         perl -Mbignum=l,GMP,Pari -e 'print 2 ** 512'
 438
 439 This will be hopefully fixed soon ;)
 440
 441 =item hex
 442
 443 Override the build-in hex() method with a version that can handle big
 444 integers. Note that under Perl v5.9.4 or ealier, this will be global
 445 and cannot be disabled with "no bigint;".
 446
 447 =item oct
 448
 449 Override the build-in oct() method with a version that can handle big
 450 integers. Note that under Perl v5.9.4 or ealier, this will be global
 451 and cannot be disabled with "no bigint;".
 452
 453 =item v or version
 454
 455 This prints out the name and version of all modules used and then exits.
 456
 457         perl -Mbigrat=v
 458
 459 =back
 460
 461 =head1 CAVAETS
 462
 463 =over 2
 464
 465 =item in_effect()
 466
 467 This method only works on Perl v5.9.4 or later.
 468
 469 =item hex()/oct()
 470
 471 C<bigint> overrides these routines with versions that can also handle
 472 big integer values. Under Perl prior to version v5.9.4, however, this
 473 will not happen unless you specifically ask for it with the two
 474 import tags "hex" and "oct" - and then it will be global and cannot be
 475 disabled inside a scope with "no bigint":
 476
 477         use bigint qw/hex oct/;
 478
 479         print hex("0x1234567890123456");
 480         {
 481                 no bigint;
 482                 print hex("0x1234567890123456");
 483         }
 484
 485 The second call to hex() will warn about a non-portable constant.
 486
 487 Compare this to:
 488
 489         use bigint;
 490
 491         # will warn only under Perl older than v5.9.4
 492         print hex("0x1234567890123456");
 493
 494 =back
 495
 496 =head1 EXAMPLES
 497
 498         perl -Mbigrat -le 'print sqrt(33)'
 499         perl -Mbigrat -le 'print 2*255'
 500         perl -Mbigrat -le 'print 4.5+2*255'
 501         perl -Mbigrat -le 'print 3/7 + 5/7 + 8/3'
 502         perl -Mbigrat -le 'print 12->is_odd()';
 503         perl -Mbignum=l,GMP -le 'print 7 ** 7777'
 504
 505 =head1 LICENSE
 506
 507 This program is free software; you may redistribute it and/or modify it under
 508 the same terms as Perl itself.
 509
 510 =head1 SEE ALSO
 511
 512 Especially L<bignum>.
 513
 514 L<Math::BigFloat>, L<Math::BigInt>, L<Math::BigRat> and L<Math::Big> as well
 515 as L<Math::BigInt::BitVect>, L<Math::BigInt::Pari> and  L<Math::BigInt::GMP>.
 516
 517 =head1 AUTHORS
 518
 519 (C) by Tels L<http://bloodgate.com/> in early 2002 - 2007.
 520
 521 =cut