1package bignum; 2 3use strict; 4use warnings; 5 6use Carp qw< carp croak >; 7 8our $VERSION = '0.65'; 9 10use Exporter; 11our @ISA = qw( Exporter ); 12our @EXPORT_OK = qw( PI e bpi bexp hex oct ); 13our @EXPORT = qw( inf NaN ); 14 15use overload; 16 17# Defaults: When a constant is an integer, Inf or NaN, it is converted to an 18# object of class $int_class. When a constant is a finite non-integer, it is 19# converted to an object of class $float_class. 20 21my $int_class = 'Math::BigInt'; 22my $float_class = 'Math::BigFloat'; 23 24############################################################################## 25 26sub accuracy { 27 shift; 28 $int_class -> accuracy(@_); 29 $float_class -> accuracy(@_); 30} 31 32sub precision { 33 shift; 34 $int_class -> precision(@_); 35 $float_class -> precision(@_); 36} 37 38sub round_mode { 39 shift; 40 $int_class -> round_mode(@_); 41 $float_class -> round_mode(@_); 42} 43 44sub div_scale { 45 shift; 46 $int_class -> div_scale(@_); 47 $float_class -> div_scale(@_); 48} 49 50sub upgrade { 51 shift; 52 $int_class -> upgrade(@_); 53} 54 55sub downgrade { 56 shift; 57 $float_class -> downgrade(@_); 58} 59 60sub in_effect { 61 my $level = shift || 0; 62 my $hinthash = (caller($level))[10]; 63 $hinthash->{bignum}; 64} 65 66sub _float_constant { 67 my $str = shift; 68 69 # See if we can convert the input string to a string using a normalized form 70 # consisting of the significand as a signed integer, the character "e", and 71 # the exponent as a signed integer, e.g., "+0e+0", "+314e-2", and "-1e+3". 72 73 my $nstr; 74 75 if ( 76 # See if it is an octal number. An octal number like '0377' is also 77 # accepted by the functions parsing decimal and hexadecimal numbers, so 78 # handle octal numbers before decimal and hexadecimal numbers. 79 80 $str =~ /^0(?:[Oo]|_*[0-7])/ and 81 $nstr = Math::BigInt -> oct_str_to_dec_flt_str($str) 82 83 or 84 85 # See if it is decimal number. 86 87 $nstr = Math::BigInt -> dec_str_to_dec_flt_str($str) 88 89 or 90 91 # See if it is a hexadecimal number. Every hexadecimal number has a 92 # prefix, but the functions parsing numbers don't require it, so check 93 # to see if it actually is a hexadecimal number. 94 95 $str =~ /^0[Xx]/ and 96 $nstr = Math::BigInt -> hex_str_to_dec_flt_str($str) 97 98 or 99 100 # See if it is a binary numbers. Every binary number has a prefix, but 101 # the functions parsing numbers don't require it, so check to see if it 102 # actually is a binary number. 103 104 $str =~ /^0[Bb]/ and 105 $nstr = Math::BigInt -> bin_str_to_dec_flt_str($str)) 106 { 107 my $pos = index($nstr, 'e'); 108 my $expo_sgn = substr($nstr, $pos + 1, 1); 109 my $sign = substr($nstr, 0, 1); 110 my $mant = substr($nstr, 1, $pos - 1); 111 my $mant_len = CORE::length($mant); 112 my $expo = substr($nstr, $pos + 2); 113 114 # The number is a non-integer if and only if the exponent is negative. 115 116 if ($expo_sgn eq '-') { 117 return $float_class -> new($str); 118 119 my $upgrade = $int_class -> upgrade(); 120 return $upgrade -> new($nstr) if defined $upgrade; 121 122 if ($mant_len <= $expo) { 123 return $int_class -> bzero(); # underflow 124 } else { 125 $mant = substr $mant, 0, $mant_len - $expo; # truncate 126 return $int_class -> new($sign . $mant); 127 } 128 } else { 129 $mant .= "0" x $expo; # pad with zeros 130 return $int_class -> new($sign . $mant); 131 } 132 } 133 134 # If we get here, there is a bug in the code above this point. 135 136 warn "Internal error: unable to handle literal constant '$str'.", 137 " This is a bug, so please report this to the module author."; 138 return $int_class -> bnan(); 139} 140 141############################################################################# 142# the following two routines are for "use bignum qw/hex oct/;": 143 144use constant LEXICAL => $] > 5.009004; 145 146# Internal function with the same semantics as CORE::hex(). This function is 147# not used directly, but rather by other front-end functions. 148 149sub _hex_core { 150 my $str = shift; 151 152 # Strip off, clean, and parse as much as we can from the beginning. 153 154 my $x; 155 if ($str =~ s/ ^ ( 0? [xX] )? ( [0-9a-fA-F]* ( _ [0-9a-fA-F]+ )* ) //x) { 156 my $chrs = $2; 157 $chrs =~ tr/_//d; 158 $chrs = '0' unless CORE::length $chrs; 159 $x = $int_class -> from_hex($chrs); 160 } else { 161 $x = $int_class -> bzero(); 162 } 163 164 # Warn about trailing garbage. 165 166 if (CORE::length($str)) { 167 require Carp; 168 Carp::carp(sprintf("Illegal hexadecimal digit '%s' ignored", 169 substr($str, 0, 1))); 170 } 171 172 return $x; 173} 174 175# Internal function with the same semantics as CORE::oct(). This function is 176# not used directly, but rather by other front-end functions. 177 178sub _oct_core { 179 my $str = shift; 180 181 $str =~ s/^\s*//; 182 183 # Hexadecimal input. 184 185 return _hex_core($str) if $str =~ /^0?[xX]/; 186 187 my $x; 188 189 # Binary input. 190 191 if ($str =~ /^0?[bB]/) { 192 193 # Strip off, clean, and parse as much as we can from the beginning. 194 195 if ($str =~ s/ ^ ( 0? [bB] )? ( [01]* ( _ [01]+ )* ) //x) { 196 my $chrs = $2; 197 $chrs =~ tr/_//d; 198 $chrs = '0' unless CORE::length $chrs; 199 $x = $int_class -> from_bin($chrs); 200 } 201 202 # Warn about trailing garbage. 203 204 if (CORE::length($str)) { 205 require Carp; 206 Carp::carp(sprintf("Illegal binary digit '%s' ignored", 207 substr($str, 0, 1))); 208 } 209 210 return $x; 211 } 212 213 # Octal input. Strip off, clean, and parse as much as we can from the 214 # beginning. 215 216 if ($str =~ s/ ^ ( 0? [oO] )? ( [0-7]* ( _ [0-7]+ )* ) //x) { 217 my $chrs = $2; 218 $chrs =~ tr/_//d; 219 $chrs = '0' unless CORE::length $chrs; 220 $x = $int_class -> from_oct($chrs); 221 } 222 223 # Warn about trailing garbage. CORE::oct() only warns about 8 and 9, but it 224 # is more helpful to warn about all invalid digits. 225 226 if (CORE::length($str)) { 227 require Carp; 228 Carp::carp(sprintf("Illegal octal digit '%s' ignored", 229 substr($str, 0, 1))); 230 } 231 232 return $x; 233} 234 235{ 236 my $proto = LEXICAL ? '_' : ';$'; 237 eval ' 238sub hex(' . $proto . ') {' . <<'.'; 239 my $str = @_ ? $_[0] : $_; 240 _hex_core($str); 241} 242. 243 244 eval ' 245sub oct(' . $proto . ') {' . <<'.'; 246 my $str = @_ ? $_[0] : $_; 247 _oct_core($str); 248} 249. 250} 251 252############################################################################# 253# the following two routines are for Perl 5.9.4 or later and are lexical 254 255my ($prev_oct, $prev_hex, $overridden); 256 257if (LEXICAL) { eval <<'.' } 258sub _hex(_) { 259 my $hh = (caller 0)[10]; 260 return $$hh{bignum} ? bignum::_hex_core($_[0]) 261 : $$hh{bigrat} ? bigrat::_hex_core($_[0]) 262 : $$hh{bigint} ? bigint::_hex_core($_[0]) 263 : $prev_hex ? &$prev_hex($_[0]) 264 : CORE::hex($_[0]); 265} 266 267sub _oct(_) { 268 my $hh = (caller 0)[10]; 269 return $$hh{bignum} ? bignum::_oct_core($_[0]) 270 : $$hh{bigrat} ? bigrat::_oct_core($_[0]) 271 : $$hh{bigint} ? bigint::_oct_core($_[0]) 272 : $prev_oct ? &$prev_oct($_[0]) 273 : CORE::oct($_[0]); 274} 275. 276 277sub _override { 278 return if $overridden; 279 $prev_oct = *CORE::GLOBAL::oct{CODE}; 280 $prev_hex = *CORE::GLOBAL::hex{CODE}; 281 no warnings 'redefine'; 282 *CORE::GLOBAL::oct = \&_oct; 283 *CORE::GLOBAL::hex = \&_hex; 284 $overridden = 1; 285} 286 287sub unimport { 288 $^H{bignum} = undef; # no longer in effect 289 overload::remove_constant('binary', '', 'float', '', 'integer'); 290} 291 292sub import { 293 my $class = shift; 294 295 $^H{bignum} = 1; # we are in effect 296 $^H{bigint} = undef; 297 $^H{bigrat} = undef; 298 299 # for newer Perls always override hex() and oct() with a lexical version: 300 if (LEXICAL) { 301 _override(); 302 } 303 304 my @import = (); # common options 305 my @int_import = (upgrade => $float_class); # int class only options 306 my @flt_import = (downgrade => $int_class); # float class only options 307 my @a = (); # unrecognized arguments 308 my $ver; # display version info? 309 310 while (@_) { 311 my $param = shift; 312 313 # Upgrading. 314 315 if ($param eq 'upgrade') { 316 my $arg = shift; 317 $float_class = $arg if defined $arg; 318 push @int_import, 'upgrade', $arg; 319 next; 320 } 321 322 # Downgrading. 323 324 if ($param eq 'downgrade') { 325 my $arg = shift; 326 $int_class = $arg if defined $arg; 327 push @flt_import, 'downgrade', $arg; 328 next; 329 } 330 331 # Accuracy. 332 333 if ($param =~ /^a(ccuracy)?$/) { 334 push @import, 'accuracy', shift(); 335 next; 336 } 337 338 # Precision. 339 340 if ($param =~ /^p(recision)?$/) { 341 push @import, 'precision', shift(); 342 next; 343 } 344 345 # Rounding mode. 346 347 if ($param eq 'round_mode') { 348 push @import, 'round_mode', shift(); 349 next; 350 } 351 352 # Backend library. 353 354 if ($param =~ /^(l|lib|try|only)$/) { 355 push @import, $param eq 'l' ? 'lib' : $param; 356 push @import, shift() if @_; 357 next; 358 } 359 360 if ($param =~ /^(v|version)$/) { 361 $ver = 1; 362 next; 363 } 364 365 if ($param =~ /^(PI|e|bexp|bpi|hex|oct)\z/) { 366 push @a, $param; 367 next; 368 } 369 370 croak("Unknown option '$param'"); 371 } 372 373 eval "require $int_class"; 374 die $@ if $@; 375 $int_class -> import(@int_import, @import); 376 377 eval "require $float_class"; 378 die $@ if $@; 379 $float_class -> import(@flt_import, @import); 380 381 if ($ver) { 382 printf "%-31s v%s\n", $class, $class -> VERSION(); 383 printf " lib => %-23s v%s\n", 384 $int_class -> config("lib"), $int_class -> config("lib_version"); 385 printf "%-31s v%s\n", $int_class, $int_class -> VERSION(); 386 exit; 387 } 388 389 $class -> export_to_level(1, $class, @a); # export inf, NaN, etc. 390 391 overload::constant 392 393 # This takes care each number written as decimal integer and within the 394 # range of what perl can represent as an integer, e.g., "314", but not 395 # "3141592653589793238462643383279502884197169399375105820974944592307". 396 397 integer => sub { 398 #printf "Value '%s' handled by the 'integer' sub.\n", $_[0]; 399 my $str = shift; 400 return $int_class -> new($str); 401 }, 402 403 # This takes care of each number written with a decimal point and/or 404 # using floating point notation, e.g., "3.", "3.0", "3.14e+2" (decimal), 405 # "0b1.101p+2" (binary), "03.14p+2" and "0o3.14p+2" (octal), and 406 # "0x3.14p+2" (hexadecimal). 407 408 float => sub { 409 #printf "# Value '%s' handled by the 'float' sub.\n", $_[0]; 410 _float_constant(shift); 411 }, 412 413 # Take care of each number written as an integer (no decimal point or 414 # exponent) using binary, octal, or hexadecimal notation, e.g., "0b101" 415 # (binary), "0314" and "0o314" (octal), and "0x314" (hexadecimal). 416 417 binary => sub { 418 #printf "# Value '%s' handled by the 'binary' sub.\n", $_[0]; 419 my $str = shift; 420 return $int_class -> new($str) if $str =~ /^0[XxBb]/; 421 $int_class -> from_oct($str); 422 }; 423} 424 425sub inf () { $int_class -> binf(); } 426sub NaN () { $int_class -> bnan(); } 427 428# This should depend on the current accuracy/precision. Fixme! 429sub PI () { $float_class -> new('3.141592653589793238462643383279502884197'); } 430sub e () { $float_class -> new('2.718281828459045235360287471352662497757'); } 431 432sub bpi ($) { 433 my $up = Math::BigFloat -> upgrade(); # get current upgrading, if any ... 434 Math::BigFloat -> upgrade(undef); # ... and disable 435 my $x = Math::BigFloat -> bpi(@_); 436 Math::BigFloat -> upgrade($up); # reset the upgrading 437 return $x; 438} 439 440sub bexp ($$) { 441 my $up = Math::BigFloat -> upgrade(); # get current upgrading, if any ... 442 Math::BigFloat -> upgrade(undef); # ... and disable 443 my $x = Math::BigFloat -> new(shift) -> bexp(@_); 444 Math::BigFloat -> upgrade($up); # reset the upgrading 445 return $x; 446} 447 4481; 449 450__END__ 451 452=pod 453 454=head1 NAME 455 456bignum - transparent big number support for Perl 457 458=head1 SYNOPSIS 459 460 use bignum; 461 462 $x = 2 + 4.5; # Math::BigFloat 6.5 463 print 2 ** 512 * 0.1; # Math::BigFloat 134...09.6 464 print 2 ** 512; # Math::BigInt 134...096 465 print inf + 42; # Math::BigInt inf 466 print NaN * 7; # Math::BigInt NaN 467 print hex("0x1234567890123490"); # Perl v5.10.0 or later 468 469 { 470 no bignum; 471 print 2 ** 256; # a normal Perl scalar now 472 } 473 474 # for older Perls, import into current package: 475 use bignum qw/hex oct/; 476 print hex("0x1234567890123490"); 477 print oct("01234567890123490"); 478 479=head1 DESCRIPTION 480 481=head2 Literal numeric constants 482 483By default, every literal integer becomes a Math::BigInt object, and literal 484non-integer becomes a Math::BigFloat object. Whether a numeric literal is 485considered an integer or non-integers depends only on the value of the constant, 486not on how it is represented. For instance, the constants 3.14e2 and 0x1.3ap8 487become Math::BigInt objects, because they both represent the integer value 488decimal 314. 489 490The default C<use bignum;> is equivalent to 491 492 use bignum downgrade => "Math::BigInt", upgrade => "Math::BigFloat"; 493 494The classes used for integers and non-integers can be set at compile time with 495the C<downgrade> and C<upgrade> options, for example 496 497 # use Math::BigInt for integers and Math::BigRat for non-integers 498 use bignum upgrade => "Math::BigRat"; 499 500Note that disabling downgrading and upgrading does not affect how numeric 501literals are converted to objects 502 503 # disable both downgrading and upgrading 504 use bignum downgrade => undef, upgrade => undef; 505 $x = 2.4; # becomes 2.4 as a Math::BigFloat 506 $y = 2; # becomes 2 as a Math::BigInt 507 508=head2 Upgrading and downgrading 509 510By default, when the result of a computation is an integer, an Inf, or a NaN, 511the result is downgraded even when all the operands are instances of the upgrade 512class. 513 514 use bignum; 515 $x = 2.4; # becomes 2.4 as a Math::BigFloat 516 $y = 1.2; # becomes 1.2 as a Math::BigFloat 517 $z = $x / $y; # becomes 2 as a Math::BigInt due to downgrading 518 519Equivalently, by default, when the result of a computation is a finite 520non-integer, the result is upgraded even when all the operands are instances of 521the downgrade class. 522 523 use bignum; 524 $x = 7; # becomes 7 as a Math::BigInt 525 $y = 2; # becomes 2 as a Math::BigInt 526 $z = $x / $y; # becomes 3.5 as a Math::BigFloat due to upgrading 527 528The classes used for downgrading and upgrading can be set at runtime with the 529L</downgrade()> and L</upgrade()> methods, but see L</CAVEATS> below. 530 531The upgrade and downgrade classes don't have to be Math::BigInt and 532Math::BigFloat. For example, to use Math::BigRat as the upgrade class, use 533 534 use bignum upgrade => "Math::BigRat"; 535 $x = 2; # becomes 2 as a Math::BigInt 536 $y = 3.6; # becomes 18/5 as a Math::BigRat 537 538The upgrade and downgrade classes can be modified at runtime 539 540 use bignum; 541 $x = 3; # becomes 3 as a Math::BigInt 542 $y = 2; # becomes 2 as a Math::BigInt 543 $z = $x / $y; # becomes 1.5 as a Math::BigFlaot 544 545 bignum -> upgrade("Math::BigRat"); 546 $w = $x / $y; # becomes 3/2 as a Math::BigRat 547 548Disabling downgrading doesn't change the fact that literal constant integers are 549converted to the downgrade class, it only prevents downgrading as a result of a 550computation. E.g., 551 552 use bignum downgrade => undef; 553 $x = 2; # becomes 2 as a Math::BigInt 554 $y = 2.4; # becomes 2.4 as a Math::BigFloat 555 $z = 1.2; # becomes 1.2 as a Math::BigFloat 556 $w = $x / $y; # becomes 2 as a Math::BigFloat due to no downgrading 557 558If you want all numeric literals, both integers and non-integers, to become 559Math::BigFloat objects, use the L<bigfloat> pragma. 560 561Equivalently, disabling upgrading doesn't change the fact that literal constant 562non-integers are converted to the upgrade class, it only prevents upgrading as a 563result of a computation. E.g., 564 565 use bignum upgrade => undef; 566 $x = 2.5; # becomes 2.5 as a Math::BigFloat 567 $y = 7; # becomes 7 as a Math::BigInt 568 $z = 2; # becomes 2 as a Math::BigInt 569 $w = $x / $y; # becomes 3 as a Math::BigInt due to no upgrading 570 571If you want all numeric literals, both integers and non-integers, to become 572Math::BigInt objects, use the L<bigint> pragma. 573 574You can even do 575 576 use bignum upgrade => "Math::BigRat", upgrade => undef; 577 578which converts all integer literals to Math::BigInt objects and all non-integer 579literals to Math::BigRat objects. However, when the result of a computation 580involving two Math::BigInt objects results in a non-integer (e.g., 7/2), the 581result will be truncted to a Math::BigInt rather than being upgraded to a 582Math::BigRat, since upgrading is disabled. 583 584=head2 Overloading 585 586Since all numeric literals become objects, you can call all the usual methods 587from Math::BigInt and Math::BigFloat on them. This even works to some extent on 588expressions: 589 590 perl -Mbignum -le '$x = 1234; print $x->bdec()' 591 perl -Mbignum -le 'print 1234->copy()->binc();' 592 perl -Mbignum -le 'print 1234->copy()->binc()->badd(6);' 593 594=head2 Options 595 596C<bignum> recognizes some options that can be passed while loading it via via 597C<use>. The following options exist: 598 599=over 4 600 601=item a or accuracy 602 603This sets the accuracy for all math operations. The argument must be greater 604than or equal to zero. See Math::BigInt's bround() method for details. 605 606 perl -Mbignum=a,50 -le 'print sqrt(20)' 607 608Note that setting precision and accuracy at the same time is not possible. 609 610=item p or precision 611 612This sets the precision for all math operations. The argument can be any 613integer. Negative values mean a fixed number of digits after the dot, while a 614positive value rounds to this digit left from the dot. 0 means round to integer. 615See Math::BigInt's bfround() method for details. 616 617 perl -Mbignum=p,-50 -le 'print sqrt(20)' 618 619Note that setting precision and accuracy at the same time is not possible. 620 621=item l, lib, try, or only 622 623Load a different math lib, see L<Math Library>. 624 625 perl -Mbignum=l,GMP -e 'print 2 ** 512' 626 perl -Mbignum=lib,GMP -e 'print 2 ** 512' 627 perl -Mbignum=try,GMP -e 'print 2 ** 512' 628 perl -Mbignum=only,GMP -e 'print 2 ** 512' 629 630=item hex 631 632Override the built-in hex() method with a version that can handle big numbers. 633This overrides it by exporting it to the current package. Under Perl v5.10.0 and 634higher, this is not so necessary, as hex() is lexically overridden in the 635current scope whenever the C<bignum> pragma is active. 636 637=item oct 638 639Override the built-in oct() method with a version that can handle big numbers. 640This overrides it by exporting it to the current package. Under Perl v5.10.0 and 641higher, this is not so necessary, as oct() is lexically overridden in the 642current scope whenever the C<bignum> pragma is active. 643 644=item v or version 645 646this prints out the name and version of the modules and then exits. 647 648 perl -Mbignum=v 649 650=back 651 652=head2 Math Library 653 654Math with the numbers is done (by default) by a backend library module called 655Math::BigInt::Calc. The default is equivalent to saying: 656 657 use bignum lib => 'Calc'; 658 659you can change this by using: 660 661 use bignum lib => 'GMP'; 662 663The following would first try to find Math::BigInt::Foo, then Math::BigInt::Bar, 664and if this also fails, revert to Math::BigInt::Calc: 665 666 use bignum lib => 'Foo,Math::BigInt::Bar'; 667 668Using c<lib> warns if none of the specified libraries can be found and 669L<Math::BigInt> and L<Math::BigFloat> fell back to one of the default 670libraries. To suppress this warning, use C<try> instead: 671 672 use bignum try => 'GMP'; 673 674If you want the code to die instead of falling back, use C<only> instead: 675 676 use bignum only => 'GMP'; 677 678Please see respective module documentation for further details. 679 680=head2 Method calls 681 682Since all numbers are now objects, you can use the methods that are part of the 683Math::BigInt and Math::BigFloat API. 684 685But a warning is in order. When using the following to make a copy of a number, 686only a shallow copy will be made. 687 688 $x = 9; $y = $x; 689 $x = $y = 7; 690 691Using the copy or the original with overloaded math is okay, e.g., the following 692work: 693 694 $x = 9; $y = $x; 695 print $x + 1, " ", $y,"\n"; # prints 10 9 696 697but calling any method that modifies the number directly will result in B<both> 698the original and the copy being destroyed: 699 700 $x = 9; $y = $x; 701 print $x->badd(1), " ", $y,"\n"; # prints 10 10 702 703 $x = 9; $y = $x; 704 print $x->binc(1), " ", $y,"\n"; # prints 10 10 705 706 $x = 9; $y = $x; 707 print $x->bmul(2), " ", $y,"\n"; # prints 18 18 708 709Using methods that do not modify, but test that the contents works: 710 711 $x = 9; $y = $x; 712 $z = 9 if $x->is_zero(); # works fine 713 714See the documentation about the copy constructor and C<=> in overload, as well 715as the documentation in Math::BigFloat for further details. 716 717=head2 Methods 718 719=over 4 720 721=item inf() 722 723A shortcut to return C<inf> as an object. Useful because Perl does not always 724handle bareword C<inf> properly. 725 726=item NaN() 727 728A shortcut to return C<NaN> as an object. Useful because Perl does not always 729handle bareword C<NaN> properly. 730 731=item e 732 733 # perl -Mbignum=e -wle 'print e' 734 735Returns Euler's number C<e>, aka exp(1) (= 2.7182818284...). 736 737=item PI 738 739 # perl -Mbignum=PI -wle 'print PI' 740 741Returns PI (= 3.1415926532..). 742 743=item bexp() 744 745 bexp($power, $accuracy); 746 747Returns Euler's number C<e> raised to the appropriate power, to the wanted 748accuracy. 749 750Example: 751 752 # perl -Mbignum=bexp -wle 'print bexp(1,80)' 753 754=item bpi() 755 756 bpi($accuracy); 757 758Returns PI to the wanted accuracy. 759 760Example: 761 762 # perl -Mbignum=bpi -wle 'print bpi(80)' 763 764=item accuracy() 765 766Set or get the accuracy. 767 768=item precision() 769 770Set or get the precision. 771 772=item round_mode() 773 774Set or get the rounding mode. 775 776=item div_scale() 777 778Set or get the division scale. 779 780=item upgrade() 781 782Set or get the class that the downgrade class upgrades to, if any. Set the 783upgrade class to C<undef> to disable upgrading. See C</CAVEATS> below. 784 785=item downgrade() 786 787Set or get the class that the upgrade class downgrades to, if any. Set the 788downgrade class to C<undef> to disable upgrading. See L</CAVEATS> below. 789 790=item in_effect() 791 792 use bignum; 793 794 print "in effect\n" if bignum::in_effect; # true 795 { 796 no bignum; 797 print "in effect\n" if bignum::in_effect; # false 798 } 799 800Returns true or false if C<bignum> is in effect in the current scope. 801 802This method only works on Perl v5.9.4 or later. 803 804=back 805 806=head1 CAVEATS 807 808=over 4 809 810=item The upgrade() and downgrade() methods 811 812Note that setting both the upgrade and downgrade classes at runtime with the 813L</upgrade()> and L</downgrade()> methods, might not do what you expect: 814 815 # Assuming that downgrading and upgrading hasn't been modified so far, so 816 # the downgrade and upgrade classes are Math::BigInt and Math::BigFloat, 817 # respectively, the following sets the upgrade class to Math::BigRat, i.e., 818 # makes Math::BigInt upgrade to Math::BigRat: 819 820 bignum -> upgrade("Math::BigRat"); 821 822 # The following sets the downgrade class to Math::BigInt::Lite, i.e., makes 823 # the new upgrade class Math::BigRat downgrade to Math::BigInt::Lite 824 825 bignum -> downgrade("Math::BigInt::Lite"); 826 827 # Note that at this point, it is still Math::BigInt, not Math::BigInt::Lite, 828 # that upgrades to Math::BigRat, so to get Math::BigInt::Lite to upgrade to 829 # Math::BigRat, we need to do the following (again): 830 831 bignum -> upgrade("Math::BigRat"); 832 833A simpler way to do this at runtime is to use import(), 834 835 bignum -> import(upgrade => "Math::BigRat", 836 downgrade => "Math::BigInt::Lite"); 837 838=item Hexadecimal, octal, and binary floating point literals 839 840Perl (and this module) accepts hexadecimal, octal, and binary floating point 841literals, but use them with care with Perl versions before v5.32.0, because some 842versions of Perl silently give the wrong result. 843 844=item Operator vs literal overloading 845 846C<bigrat> works by overloading handling of integer and floating point literals, 847converting them to L<Math::BigRat> objects. 848 849This means that arithmetic involving only string values or string literals are 850performed using Perl's built-in operators. 851 852For example: 853 854 use bigrat; 855 my $x = "900000000000000009"; 856 my $y = "900000000000000007"; 857 print $x - $y; 858 859outputs C<0> on default 32-bit builds, since C<bignum> never sees the string 860literals. To ensure the expression is all treated as C<Math::BigFloat> objects, 861use a literal number in the expression: 862 863 print +(0+$x) - $y; 864 865=item Ranges 866 867Perl does not allow overloading of ranges, so you can neither safely use ranges 868with C<bignum> endpoints, nor is the iterator variable a C<Math::BigFloat>. 869 870 use 5.010; 871 for my $i (12..13) { 872 for my $j (20..21) { 873 say $i ** $j; # produces a floating-point number, 874 # not an object 875 } 876 } 877 878=item in_effect() 879 880This method only works on Perl v5.9.4 or later. 881 882=item hex()/oct() 883 884C<bignum> overrides these routines with versions that can also handle big 885integer values. Under Perl prior to version v5.9.4, however, this will not 886happen unless you specifically ask for it with the two import tags "hex" and 887"oct" - and then it will be global and cannot be disabled inside a scope with 888C<no bignum>: 889 890 use bignum qw/hex oct/; 891 892 print hex("0x1234567890123456"); 893 { 894 no bignum; 895 print hex("0x1234567890123456"); 896 } 897 898The second call to hex() will warn about a non-portable constant. 899 900Compare this to: 901 902 use bignum; 903 904 # will warn only under Perl older than v5.9.4 905 print hex("0x1234567890123456"); 906 907=back 908 909=head1 EXAMPLES 910 911Some cool command line examples to impress the Python crowd ;) 912 913 perl -Mbignum -le 'print sqrt(33)' 914 perl -Mbignum -le 'print 2**255' 915 perl -Mbignum -le 'print 4.5+2**255' 916 perl -Mbignum -le 'print 3/7 + 5/7 + 8/3' 917 perl -Mbignum -le 'print 123->is_odd()' 918 perl -Mbignum -le 'print log(2)' 919 perl -Mbignum -le 'print exp(1)' 920 perl -Mbignum -le 'print 2 ** 0.5' 921 perl -Mbignum=a,65 -le 'print 2 ** 0.2' 922 perl -Mbignum=l,GMP -le 'print 7 ** 7777' 923 924=head1 BUGS 925 926Please report any bugs or feature requests to 927C<bug-bignum at rt.cpan.org>, or through the web interface at 928L<https://rt.cpan.org/Ticket/Create.html?Queue=bignum> (requires login). 929We will be notified, and then you'll automatically be notified of 930progress on your bug as I make changes. 931 932=head1 SUPPORT 933 934You can find documentation for this module with the perldoc command. 935 936 perldoc bignum 937 938You can also look for information at: 939 940=over 4 941 942=item * GitHub 943 944L<https://github.com/pjacklam/p5-bignum> 945 946=item * RT: CPAN's request tracker 947 948L<https://rt.cpan.org/Dist/Display.html?Name=bignum> 949 950=item * MetaCPAN 951 952L<https://metacpan.org/release/bignum> 953 954=item * CPAN Testers Matrix 955 956L<http://matrix.cpantesters.org/?dist=bignum> 957 958=item * CPAN Ratings 959 960L<https://cpanratings.perl.org/dist/bignum> 961 962=back 963 964=head1 LICENSE 965 966This program is free software; you may redistribute it and/or modify it under 967the same terms as Perl itself. 968 969=head1 SEE ALSO 970 971L<bigint> and L<bigrat>. 972 973L<Math::BigInt>, L<Math::BigFloat>, L<Math::BigRat> and L<Math::Big> as well as 974L<Math::BigInt::FastCalc>, L<Math::BigInt::Pari> and L<Math::BigInt::GMP>. 975 976=head1 AUTHORS 977 978=over 4 979 980=item * 981 982(C) by Tels L<http://bloodgate.com/> in early 2002 - 2007. 983 984=item * 985 986Maintained by Peter John Acklam E<lt>pjacklam@gmail.comE<gt>, 2014-. 987 988=back 989 990=cut 991