ext/bignum/lib/bigrat.pm

   1 package bigrat;
   2 use 5.006;
   3
   4 $VERSION = '0.23';
   5 require Exporter;
   6 @ISA            = qw( bigint );
   7 @EXPORT_OK      = qw( PI e bpi bexp );
   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     elsif ($_[$i] !~ /^(PI|e|bpi|bexp)\z/)
 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 sub PI () { Math::BigFloat->new('3.141592653589793238462643383279502884197'); }
 230 sub e () { Math::BigFloat->new('2.718281828459045235360287471352662497757'); }
 231
 232 sub bpi ($) { local $Math::BigFloat::upgrade; Math::BigFloat::bpi(@_); }
 233
 234 sub bexp ($$)
 235   {
 236   local $Math::BigFloat::upgrade;
 237   my $x = Math::BigFloat->new($_[0]); $x->bexp($_[1]);
 238   }
 239
 240 1;
 241
 242 __END__
 243
 244 =head1 NAME
 245
 246 bigrat - Transparent BigNumber/BigRational support for Perl
 247
 248 =head1 SYNOPSIS
 249
 250   use bigrat;
 251
 252   print 2 + 4.5,"\n";                   # BigFloat 6.5
 253   print 1/3 + 1/4,"\n";                 # produces 7/12
 254
 255   {
 256     no bigrat;
 257     print 1/3,"\n";                     # 0.33333...
 258   }
 259
 260   # Note that this will make hex() and oct() be globally overriden:
 261   use bigrat qw/hex oct/;
 262   print hex("0x1234567890123490"),"\n";
 263   print oct("01234567890123490"),"\n";
 264
 265 =head1 DESCRIPTION
 266
 267 All operators (including basic math operations) are overloaded. Integer and
 268 floating-point constants are created as proper BigInts or BigFloats,
 269 respectively.
 270
 271 Other than L<bignum>, this module upgrades to Math::BigRat, meaning that
 272 instead of 2.5 you will get 2+1/2 as output.
 273
 274 =head2 Modules Used
 275
 276 C<bigrat> is just a thin wrapper around various modules of the Math::BigInt
 277 family. Think of it as the head of the family, who runs the shop, and orders
 278 the others to do the work.
 279
 280 The following modules are currently used by bignum:
 281
 282         Math::BigInt::Lite      (for speed, and only if it is loadable)
 283         Math::BigInt
 284         Math::BigFloat
 285         Math::BigRat
 286
 287 =head2 Math Library
 288
 289 Math with the numbers is done (by default) by a module called
 290 Math::BigInt::Calc. This is equivalent to saying:
 291
 292         use bigrat lib => 'Calc';
 293
 294 You can change this by using:
 295
 296         use bignum lib => 'GMP';
 297
 298 The following would first try to find Math::BigInt::Foo, then
 299 Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:
 300
 301         use bigrat lib => 'Foo,Math::BigInt::Bar';
 302
 303 Using C<lib> warns if none of the specified libraries can be found and
 304 L<Math::BigInt> did fall back to one of the default libraries.
 305 To supress this warning, use C<try> instead:
 306
 307         use bignum try => 'GMP';
 308
 309 If you want the code to die instead of falling back, use C<only> instead:
 310
 311         use bignum only => 'GMP';
 312
 313 Please see respective module documentation for further details.
 314
 315 =head2 Sign
 316
 317 The sign is either '+', '-', 'NaN', '+inf' or '-inf'.
 318
 319 A sign of 'NaN' is used to represent the result when input arguments are not
 320 numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively
 321 minus infinity. You will get '+inf' when dividing a positive number by 0, and
 322 '-inf' when dividing any negative number by 0.
 323
 324 =head2 Methods
 325
 326 Since all numbers are not objects, you can use all functions that are part of
 327 the BigInt or BigFloat API. It is wise to use only the bxxx() notation, and not
 328 the fxxx() notation, though. This makes you independed on the fact that the
 329 underlying object might morph into a different class than BigFloat.
 330
 331 =over 2
 332
 333 =item inf()
 334
 335 A shortcut to return Math::BigInt->binf(). Useful because Perl does not always
 336 handle bareword C<inf> properly.
 337
 338 =item NaN()
 339
 340 A shortcut to return Math::BigInt->bnan(). Useful because Perl does not always
 341 handle bareword C<NaN> properly.
 342
 343 =item e
 344
 345         # perl -Mbigrat=e -wle 'print e'
 346
 347 Returns Euler's number C<e>, aka exp(1).
 348
 349 =item PI
 350
 351         # perl -Mbigrat=PI -wle 'print PI'
 352
 353 Returns PI.
 354
 355 =item bexp()
 356
 357         bexp($power,$accuracy);
 358
 359
 360 Returns Euler's number C<e> raised to the appropriate power, to
 361 the wanted accuracy.
 362
 363 Example:
 364
 365         # perl -Mbigrat=bexp -wle 'print bexp(1,80)'
 366
 367 =item bpi()
 368
 369         bpi($accuracy);
 370
 371 Returns PI to the wanted accuracy.
 372
 373 Example:
 374
 375         # perl -Mbigrat=bpi -wle 'print bpi(80)'
 376
 377 =item upgrade()
 378
 379 Return the class that numbers are upgraded to, is in fact returning
 380 C<$Math::BigInt::upgrade>.
 381
 382 =item in_effect()
 383
 384         use bigrat;
 385
 386         print "in effect\n" if bigrat::in_effect;       # true
 387         {
 388           no bigrat;
 389           print "in effect\n" if bigrat::in_effect;     # false
 390         }
 391
 392 Returns true or false if C<bigrat> is in effect in the current scope.
 393
 394 This method only works on Perl v5.9.4 or later.
 395
 396 =back
 397
 398 =head2 MATH LIBRARY
 399
 400 Math with the numbers is done (by default) by a module called
 401
 402 =head2 Cavaet
 403
 404 But a warning is in order. When using the following to make a copy of a number,
 405 only a shallow copy will be made.
 406
 407         $x = 9; $y = $x;
 408         $x = $y = 7;
 409
 410 If you want to make a real copy, use the following:
 411
 412         $y = $x->copy();
 413
 414 Using the copy or the original with overloaded math is okay, e.g. the
 415 following work:
 416
 417         $x = 9; $y = $x;
 418         print $x + 1, " ", $y,"\n";     # prints 10 9
 419
 420 but calling any method that modifies the number directly will result in
 421 B<both> the original and the copy being destroyed:
 422
 423         $x = 9; $y = $x;
 424         print $x->badd(1), " ", $y,"\n";        # prints 10 10
 425
 426         $x = 9; $y = $x;
 427         print $x->binc(1), " ", $y,"\n";        # prints 10 10
 428
 429         $x = 9; $y = $x;
 430         print $x->bmul(2), " ", $y,"\n";        # prints 18 18
 431
 432 Using methods that do not modify, but testthe contents works:
 433
 434         $x = 9; $y = $x;
 435         $z = 9 if $x->is_zero();                # works fine
 436
 437 See the documentation about the copy constructor and C<=> in overload, as
 438 well as the documentation in BigInt for further details.
 439
 440 =head2 Options
 441
 442 bignum recognizes some options that can be passed while loading it via use.
 443 The options can (currently) be either a single letter form, or the long form.
 444 The following options exist:
 445
 446 =over 2
 447
 448 =item a or accuracy
 449
 450 This sets the accuracy for all math operations. The argument must be greater
 451 than or equal to zero. See Math::BigInt's bround() function for details.
 452
 453         perl -Mbigrat=a,50 -le 'print sqrt(20)'
 454
 455 Note that setting precision and accurary at the same time is not possible.
 456
 457 =item p or precision
 458
 459 This sets the precision for all math operations. The argument can be any
 460 integer. Negative values mean a fixed number of digits after the dot, while
 461 a positive value rounds to this digit left from the dot. 0 or 1 mean round to
 462 integer. See Math::BigInt's bfround() function for details.
 463
 464         perl -Mbigrat=p,-50 -le 'print sqrt(20)'
 465
 466 Note that setting precision and accurary at the same time is not possible.
 467
 468 =item t or trace
 469
 470 This enables a trace mode and is primarily for debugging bignum or
 471 Math::BigInt/Math::BigFloat.
 472
 473 =item l or lib
 474
 475 Load a different math lib, see L<MATH LIBRARY>.
 476
 477         perl -Mbigrat=l,GMP -e 'print 2 ** 512'
 478
 479 Currently there is no way to specify more than one library on the command
 480 line. This means the following does not work:
 481
 482         perl -Mbignum=l,GMP,Pari -e 'print 2 ** 512'
 483
 484 This will be hopefully fixed soon ;)
 485
 486 =item hex
 487
 488 Override the built-in hex() method with a version that can handle big
 489 integers. Note that under Perl v5.9.4 or ealier, this will be global
 490 and cannot be disabled with "no bigint;".
 491
 492 =item oct
 493
 494 Override the built-in oct() method with a version that can handle big
 495 integers. Note that under Perl v5.9.4 or ealier, this will be global
 496 and cannot be disabled with "no bigint;".
 497
 498 =item v or version
 499
 500 This prints out the name and version of all modules used and then exits.
 501
 502         perl -Mbigrat=v
 503
 504 =back
 505
 506 =head1 CAVAETS
 507
 508 =over 2
 509
 510 =item in_effect()
 511
 512 This method only works on Perl v5.9.4 or later.
 513
 514 =item hex()/oct()
 515
 516 C<bigint> overrides these routines with versions that can also handle
 517 big integer values. Under Perl prior to version v5.9.4, however, this
 518 will not happen unless you specifically ask for it with the two
 519 import tags "hex" and "oct" - and then it will be global and cannot be
 520 disabled inside a scope with "no bigint":
 521
 522         use bigint qw/hex oct/;
 523
 524         print hex("0x1234567890123456");
 525         {
 526                 no bigint;
 527                 print hex("0x1234567890123456");
 528         }
 529
 530 The second call to hex() will warn about a non-portable constant.
 531
 532 Compare this to:
 533
 534         use bigint;
 535
 536         # will warn only under Perl older than v5.9.4
 537         print hex("0x1234567890123456");
 538
 539 =back
 540
 541 =head1 EXAMPLES
 542
 543         perl -Mbigrat -le 'print sqrt(33)'
 544         perl -Mbigrat -le 'print 2*255'
 545         perl -Mbigrat -le 'print 4.5+2*255'
 546         perl -Mbigrat -le 'print 3/7 + 5/7 + 8/3'
 547         perl -Mbigrat -le 'print 12->is_odd()';
 548         perl -Mbignum=l,GMP -le 'print 7 ** 7777'
 549
 550 =head1 LICENSE
 551
 552 This program is free software; you may redistribute it and/or modify it under
 553 the same terms as Perl itself.
 554
 555 =head1 SEE ALSO
 556
 557 Especially L<bignum>.
 558
 559 L<Math::BigFloat>, L<Math::BigInt>, L<Math::BigRat> and L<Math::Big> as well
 560 as L<Math::BigInt::BitVect>, L<Math::BigInt::Pari> and  L<Math::BigInt::GMP>.
 561
 562 =head1 AUTHORS
 563
 564 (C) by Tels L<http://bloodgate.com/> in early 2002 - 2007.
 565
 566 =cut