| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "bignum 3perl" |
| 58 |
.TH bignum 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
bignum \- transparent big number support for Perl |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
.Vb 1 |
| 68 |
\& use bignum; |
| 69 |
\& |
| 70 |
\& $x = 2 + 4.5; # Math::BigFloat 6.5 |
| 71 |
\& print 2 ** 512 * 0.1; # Math::BigFloat 134...09.6 |
| 72 |
\& print 2 ** 512; # Math::BigInt 134...096 |
| 73 |
\& print inf + 42; # Math::BigInt inf |
| 74 |
\& print NaN * 7; # Math::BigInt NaN |
| 75 |
\& print hex("0x1234567890123490"); # Perl v5.10.0 or later |
| 76 |
\& |
| 77 |
\& { |
| 78 |
\& no bignum; |
| 79 |
\& print 2 ** 256; # a normal Perl scalar now |
| 80 |
\& } |
| 81 |
\& |
| 82 |
\& # for older Perls, import into current package: |
| 83 |
\& use bignum qw/hex oct/; |
| 84 |
\& print hex("0x1234567890123490"); |
| 85 |
\& print oct("01234567890123490"); |
| 86 |
.Ve |
| 87 |
.SH DESCRIPTION |
| 88 |
.IX Header "DESCRIPTION" |
| 89 |
.SS "Literal numeric constants" |
| 90 |
.IX Subsection "Literal numeric constants" |
| 91 |
By default, every literal integer becomes a Math::BigInt object, and literal |
| 92 |
non-integer becomes a Math::BigFloat object. Whether a numeric literal is |
| 93 |
considered an integer or non-integers depends only on the value of the constant, |
| 94 |
not on how it is represented. For instance, the constants 3.14e2 and 0x1.3ap8 |
| 95 |
become Math::BigInt objects, because they both represent the integer value |
| 96 |
decimal 314. |
| 97 |
.PP |
| 98 |
The default \f(CW\*(C`use bignum;\*(C'\fR is equivalent to |
| 99 |
.PP |
| 100 |
.Vb 1 |
| 101 |
\& use bignum downgrade => "Math::BigInt", upgrade => "Math::BigFloat"; |
| 102 |
.Ve |
| 103 |
.PP |
| 104 |
The classes used for integers and non-integers can be set at compile time with |
| 105 |
the \f(CW\*(C`downgrade\*(C'\fR and \f(CW\*(C`upgrade\*(C'\fR options, for example |
| 106 |
.PP |
| 107 |
.Vb 2 |
| 108 |
\& # use Math::BigInt for integers and Math::BigRat for non\-integers |
| 109 |
\& use bignum upgrade => "Math::BigRat"; |
| 110 |
.Ve |
| 111 |
.PP |
| 112 |
Note that disabling downgrading and upgrading does not affect how numeric |
| 113 |
literals are converted to objects |
| 114 |
.PP |
| 115 |
.Vb 4 |
| 116 |
\& # disable both downgrading and upgrading |
| 117 |
\& use bignum downgrade => undef, upgrade => undef; |
| 118 |
\& $x = 2.4; # becomes 2.4 as a Math::BigFloat |
| 119 |
\& $y = 2; # becomes 2 as a Math::BigInt |
| 120 |
.Ve |
| 121 |
.SS "Upgrading and downgrading" |
| 122 |
.IX Subsection "Upgrading and downgrading" |
| 123 |
By default, when the result of a computation is an integer, an Inf, or a NaN, |
| 124 |
the result is downgraded even when all the operands are instances of the upgrade |
| 125 |
class. |
| 126 |
.PP |
| 127 |
.Vb 4 |
| 128 |
\& use bignum; |
| 129 |
\& $x = 2.4; # becomes 2.4 as a Math::BigFloat |
| 130 |
\& $y = 1.2; # becomes 1.2 as a Math::BigFloat |
| 131 |
\& $z = $x / $y; # becomes 2 as a Math::BigInt due to downgrading |
| 132 |
.Ve |
| 133 |
.PP |
| 134 |
Equivalently, by default, when the result of a computation is a finite |
| 135 |
non-integer, the result is upgraded even when all the operands are instances of |
| 136 |
the downgrade class. |
| 137 |
.PP |
| 138 |
.Vb 4 |
| 139 |
\& use bignum; |
| 140 |
\& $x = 7; # becomes 7 as a Math::BigInt |
| 141 |
\& $y = 2; # becomes 2 as a Math::BigInt |
| 142 |
\& $z = $x / $y; # becomes 3.5 as a Math::BigFloat due to upgrading |
| 143 |
.Ve |
| 144 |
.PP |
| 145 |
The classes used for downgrading and upgrading can be set at runtime with the |
| 146 |
"\fBdowngrade()\fR" and "\fBupgrade()\fR" methods, but see "CAVEATS" below. |
| 147 |
.PP |
| 148 |
The upgrade and downgrade classes don't have to be Math::BigInt and |
| 149 |
Math::BigFloat. For example, to use Math::BigRat as the upgrade class, use |
| 150 |
.PP |
| 151 |
.Vb 3 |
| 152 |
\& use bignum upgrade => "Math::BigRat"; |
| 153 |
\& $x = 2; # becomes 2 as a Math::BigInt |
| 154 |
\& $y = 3.6; # becomes 18/5 as a Math::BigRat |
| 155 |
.Ve |
| 156 |
.PP |
| 157 |
The upgrade and downgrade classes can be modified at runtime |
| 158 |
.PP |
| 159 |
.Vb 4 |
| 160 |
\& use bignum; |
| 161 |
\& $x = 3; # becomes 3 as a Math::BigInt |
| 162 |
\& $y = 2; # becomes 2 as a Math::BigInt |
| 163 |
\& $z = $x / $y; # becomes 1.5 as a Math::BigFlaot |
| 164 |
\& |
| 165 |
\& bignum \-> upgrade("Math::BigRat"); |
| 166 |
\& $w = $x / $y; # becomes 3/2 as a Math::BigRat |
| 167 |
.Ve |
| 168 |
.PP |
| 169 |
Disabling downgrading doesn't change the fact that literal constant integers are |
| 170 |
converted to the downgrade class, it only prevents downgrading as a result of a |
| 171 |
computation. E.g., |
| 172 |
.PP |
| 173 |
.Vb 5 |
| 174 |
\& use bignum downgrade => undef; |
| 175 |
\& $x = 2; # becomes 2 as a Math::BigInt |
| 176 |
\& $y = 2.4; # becomes 2.4 as a Math::BigFloat |
| 177 |
\& $z = 1.2; # becomes 1.2 as a Math::BigFloat |
| 178 |
\& $w = $x / $y; # becomes 2 as a Math::BigFloat due to no downgrading |
| 179 |
.Ve |
| 180 |
.PP |
| 181 |
If you want all numeric literals, both integers and non-integers, to become |
| 182 |
Math::BigFloat objects, use the bigfloat pragma. |
| 183 |
.PP |
| 184 |
Equivalently, disabling upgrading doesn't change the fact that literal constant |
| 185 |
non-integers are converted to the upgrade class, it only prevents upgrading as a |
| 186 |
result of a computation. E.g., |
| 187 |
.PP |
| 188 |
.Vb 5 |
| 189 |
\& use bignum upgrade => undef; |
| 190 |
\& $x = 2.5; # becomes 2.5 as a Math::BigFloat |
| 191 |
\& $y = 7; # becomes 7 as a Math::BigInt |
| 192 |
\& $z = 2; # becomes 2 as a Math::BigInt |
| 193 |
\& $w = $x / $y; # becomes 3 as a Math::BigInt due to no upgrading |
| 194 |
.Ve |
| 195 |
.PP |
| 196 |
If you want all numeric literals, both integers and non-integers, to become |
| 197 |
Math::BigInt objects, use the bigint pragma. |
| 198 |
.PP |
| 199 |
You can even do |
| 200 |
.PP |
| 201 |
.Vb 1 |
| 202 |
\& use bignum upgrade => "Math::BigRat", upgrade => undef; |
| 203 |
.Ve |
| 204 |
.PP |
| 205 |
which converts all integer literals to Math::BigInt objects and all non-integer |
| 206 |
literals to Math::BigRat objects. However, when the result of a computation |
| 207 |
involving two Math::BigInt objects results in a non-integer (e.g., 7/2), the |
| 208 |
result will be truncted to a Math::BigInt rather than being upgraded to a |
| 209 |
Math::BigRat, since upgrading is disabled. |
| 210 |
.SS Overloading |
| 211 |
.IX Subsection "Overloading" |
| 212 |
Since all numeric literals become objects, you can call all the usual methods |
| 213 |
from Math::BigInt and Math::BigFloat on them. This even works to some extent on |
| 214 |
expressions: |
| 215 |
.PP |
| 216 |
.Vb 3 |
| 217 |
\& perl \-Mbignum \-le \*(Aq$x = 1234; print $x\->bdec()\*(Aq |
| 218 |
\& perl \-Mbignum \-le \*(Aqprint 1234\->copy()\->binc();\*(Aq |
| 219 |
\& perl \-Mbignum \-le \*(Aqprint 1234\->copy()\->binc()\->badd(6);\*(Aq |
| 220 |
.Ve |
| 221 |
.SS Options |
| 222 |
.IX Subsection "Options" |
| 223 |
\&\f(CW\*(C`bignum\*(C'\fR recognizes some options that can be passed while loading it via via |
| 224 |
\&\f(CW\*(C`use\*(C'\fR. The following options exist: |
| 225 |
.IP "a or accuracy" 4 |
| 226 |
.IX Item "a or accuracy" |
| 227 |
This sets the accuracy for all math operations. The argument must be greater |
| 228 |
than or equal to zero. See Math::BigInt's \fBbround()\fR method for details. |
| 229 |
.Sp |
| 230 |
.Vb 1 |
| 231 |
\& perl \-Mbignum=a,50 \-le \*(Aqprint sqrt(20)\*(Aq |
| 232 |
.Ve |
| 233 |
.Sp |
| 234 |
Note that setting precision and accuracy at the same time is not possible. |
| 235 |
.IP "p or precision" 4 |
| 236 |
.IX Item "p or precision" |
| 237 |
This sets the precision for all math operations. The argument can be any |
| 238 |
integer. Negative values mean a fixed number of digits after the dot, while a |
| 239 |
positive value rounds to this digit left from the dot. 0 means round to integer. |
| 240 |
See Math::BigInt's \fBbfround()\fR method for details. |
| 241 |
.Sp |
| 242 |
.Vb 1 |
| 243 |
\& perl \-Mbignum=p,\-50 \-le \*(Aqprint sqrt(20)\*(Aq |
| 244 |
.Ve |
| 245 |
.Sp |
| 246 |
Note that setting precision and accuracy at the same time is not possible. |
| 247 |
.IP "l, lib, try, or only" 4 |
| 248 |
.IX Item "l, lib, try, or only" |
| 249 |
Load a different math lib, see "Math Library". |
| 250 |
.Sp |
| 251 |
.Vb 4 |
| 252 |
\& perl \-Mbignum=l,GMP \-e \*(Aqprint 2 ** 512\*(Aq |
| 253 |
\& perl \-Mbignum=lib,GMP \-e \*(Aqprint 2 ** 512\*(Aq |
| 254 |
\& perl \-Mbignum=try,GMP \-e \*(Aqprint 2 ** 512\*(Aq |
| 255 |
\& perl \-Mbignum=only,GMP \-e \*(Aqprint 2 ** 512\*(Aq |
| 256 |
.Ve |
| 257 |
.IP hex 4 |
| 258 |
.IX Item "hex" |
| 259 |
Override the built-in \fBhex()\fR method with a version that can handle big numbers. |
| 260 |
This overrides it by exporting it to the current package. Under Perl v5.10.0 and |
| 261 |
higher, this is not so necessary, as \fBhex()\fR is lexically overridden in the |
| 262 |
current scope whenever the \f(CW\*(C`bignum\*(C'\fR pragma is active. |
| 263 |
.IP oct 4 |
| 264 |
.IX Item "oct" |
| 265 |
Override the built-in \fBoct()\fR method with a version that can handle big numbers. |
| 266 |
This overrides it by exporting it to the current package. Under Perl v5.10.0 and |
| 267 |
higher, this is not so necessary, as \fBoct()\fR is lexically overridden in the |
| 268 |
current scope whenever the \f(CW\*(C`bignum\*(C'\fR pragma is active. |
| 269 |
.IP "v or version" 4 |
| 270 |
.IX Item "v or version" |
| 271 |
this prints out the name and version of the modules and then exits. |
| 272 |
.Sp |
| 273 |
.Vb 1 |
| 274 |
\& perl \-Mbignum=v |
| 275 |
.Ve |
| 276 |
.SS "Math Library" |
| 277 |
.IX Subsection "Math Library" |
| 278 |
Math with the numbers is done (by default) by a backend library module called |
| 279 |
Math::BigInt::Calc. The default is equivalent to saying: |
| 280 |
.PP |
| 281 |
.Vb 1 |
| 282 |
\& use bignum lib => \*(AqCalc\*(Aq; |
| 283 |
.Ve |
| 284 |
.PP |
| 285 |
you can change this by using: |
| 286 |
.PP |
| 287 |
.Vb 1 |
| 288 |
\& use bignum lib => \*(AqGMP\*(Aq; |
| 289 |
.Ve |
| 290 |
.PP |
| 291 |
The following would first try to find Math::BigInt::Foo, then Math::BigInt::Bar, |
| 292 |
and if this also fails, revert to Math::BigInt::Calc: |
| 293 |
.PP |
| 294 |
.Vb 1 |
| 295 |
\& use bignum lib => \*(AqFoo,Math::BigInt::Bar\*(Aq; |
| 296 |
.Ve |
| 297 |
.PP |
| 298 |
Using c<lib> warns if none of the specified libraries can be found and |
| 299 |
Math::BigInt and Math::BigFloat fell back to one of the default |
| 300 |
libraries. To suppress this warning, use \f(CW\*(C`try\*(C'\fR instead: |
| 301 |
.PP |
| 302 |
.Vb 1 |
| 303 |
\& use bignum try => \*(AqGMP\*(Aq; |
| 304 |
.Ve |
| 305 |
.PP |
| 306 |
If you want the code to die instead of falling back, use \f(CW\*(C`only\*(C'\fR instead: |
| 307 |
.PP |
| 308 |
.Vb 1 |
| 309 |
\& use bignum only => \*(AqGMP\*(Aq; |
| 310 |
.Ve |
| 311 |
.PP |
| 312 |
Please see respective module documentation for further details. |
| 313 |
.SS "Method calls" |
| 314 |
.IX Subsection "Method calls" |
| 315 |
Since all numbers are now objects, you can use the methods that are part of the |
| 316 |
Math::BigInt and Math::BigFloat API. |
| 317 |
.PP |
| 318 |
But a warning is in order. When using the following to make a copy of a number, |
| 319 |
only a shallow copy will be made. |
| 320 |
.PP |
| 321 |
.Vb 2 |
| 322 |
\& $x = 9; $y = $x; |
| 323 |
\& $x = $y = 7; |
| 324 |
.Ve |
| 325 |
.PP |
| 326 |
Using the copy or the original with overloaded math is okay, e.g., the following |
| 327 |
work: |
| 328 |
.PP |
| 329 |
.Vb 2 |
| 330 |
\& $x = 9; $y = $x; |
| 331 |
\& print $x + 1, " ", $y,"\en"; # prints 10 9 |
| 332 |
.Ve |
| 333 |
.PP |
| 334 |
but calling any method that modifies the number directly will result in \fBboth\fR |
| 335 |
the original and the copy being destroyed: |
| 336 |
.PP |
| 337 |
.Vb 2 |
| 338 |
\& $x = 9; $y = $x; |
| 339 |
\& print $x\->badd(1), " ", $y,"\en"; # prints 10 10 |
| 340 |
\& |
| 341 |
\& $x = 9; $y = $x; |
| 342 |
\& print $x\->binc(1), " ", $y,"\en"; # prints 10 10 |
| 343 |
\& |
| 344 |
\& $x = 9; $y = $x; |
| 345 |
\& print $x\->bmul(2), " ", $y,"\en"; # prints 18 18 |
| 346 |
.Ve |
| 347 |
.PP |
| 348 |
Using methods that do not modify, but test that the contents works: |
| 349 |
.PP |
| 350 |
.Vb 2 |
| 351 |
\& $x = 9; $y = $x; |
| 352 |
\& $z = 9 if $x\->is_zero(); # works fine |
| 353 |
.Ve |
| 354 |
.PP |
| 355 |
See the documentation about the copy constructor and \f(CW\*(C`=\*(C'\fR in overload, as well |
| 356 |
as the documentation in Math::BigFloat for further details. |
| 357 |
.SS Methods |
| 358 |
.IX Subsection "Methods" |
| 359 |
.IP \fBinf()\fR 4 |
| 360 |
.IX Item "inf()" |
| 361 |
A shortcut to return \f(CW\*(C`inf\*(C'\fR as an object. Useful because Perl does not always |
| 362 |
handle bareword \f(CW\*(C`inf\*(C'\fR properly. |
| 363 |
.IP \fBNaN()\fR 4 |
| 364 |
.IX Item "NaN()" |
| 365 |
A shortcut to return \f(CW\*(C`NaN\*(C'\fR as an object. Useful because Perl does not always |
| 366 |
handle bareword \f(CW\*(C`NaN\*(C'\fR properly. |
| 367 |
.IP e 4 |
| 368 |
.IX Item "e" |
| 369 |
.Vb 1 |
| 370 |
\& # perl \-Mbignum=e \-wle \*(Aqprint e\*(Aq |
| 371 |
.Ve |
| 372 |
.Sp |
| 373 |
Returns Euler's number \f(CW\*(C`e\*(C'\fR, aka \fBexp\fR\|(1) (= 2.7182818284...). |
| 374 |
.IP PI 4 |
| 375 |
.IX Item "PI" |
| 376 |
.Vb 1 |
| 377 |
\& # perl \-Mbignum=PI \-wle \*(Aqprint PI\*(Aq |
| 378 |
.Ve |
| 379 |
.Sp |
| 380 |
Returns PI (= 3.1415926532..). |
| 381 |
.IP \fBbexp()\fR 4 |
| 382 |
.IX Item "bexp()" |
| 383 |
.Vb 1 |
| 384 |
\& bexp($power, $accuracy); |
| 385 |
.Ve |
| 386 |
.Sp |
| 387 |
Returns Euler's number \f(CW\*(C`e\*(C'\fR raised to the appropriate power, to the wanted |
| 388 |
accuracy. |
| 389 |
.Sp |
| 390 |
Example: |
| 391 |
.Sp |
| 392 |
.Vb 1 |
| 393 |
\& # perl \-Mbignum=bexp \-wle \*(Aqprint bexp(1,80)\*(Aq |
| 394 |
.Ve |
| 395 |
.IP \fBbpi()\fR 4 |
| 396 |
.IX Item "bpi()" |
| 397 |
.Vb 1 |
| 398 |
\& bpi($accuracy); |
| 399 |
.Ve |
| 400 |
.Sp |
| 401 |
Returns PI to the wanted accuracy. |
| 402 |
.Sp |
| 403 |
Example: |
| 404 |
.Sp |
| 405 |
.Vb 1 |
| 406 |
\& # perl \-Mbignum=bpi \-wle \*(Aqprint bpi(80)\*(Aq |
| 407 |
.Ve |
| 408 |
.IP \fBaccuracy()\fR 4 |
| 409 |
.IX Item "accuracy()" |
| 410 |
Set or get the accuracy. |
| 411 |
.IP \fBprecision()\fR 4 |
| 412 |
.IX Item "precision()" |
| 413 |
Set or get the precision. |
| 414 |
.IP \fBround_mode()\fR 4 |
| 415 |
.IX Item "round_mode()" |
| 416 |
Set or get the rounding mode. |
| 417 |
.IP \fBdiv_scale()\fR 4 |
| 418 |
.IX Item "div_scale()" |
| 419 |
Set or get the division scale. |
| 420 |
.IP \fBupgrade()\fR 4 |
| 421 |
.IX Item "upgrade()" |
| 422 |
Set or get the class that the downgrade class upgrades to, if any. Set the |
| 423 |
upgrade class to \f(CW\*(C`undef\*(C'\fR to disable upgrading. See \f(CW\*(C`/CAVEATS\*(C'\fR below. |
| 424 |
.IP \fBdowngrade()\fR 4 |
| 425 |
.IX Item "downgrade()" |
| 426 |
Set or get the class that the upgrade class downgrades to, if any. Set the |
| 427 |
downgrade class to \f(CW\*(C`undef\*(C'\fR to disable upgrading. See "CAVEATS" below. |
| 428 |
.IP \fBin_effect()\fR 4 |
| 429 |
.IX Item "in_effect()" |
| 430 |
.Vb 1 |
| 431 |
\& use bignum; |
| 432 |
\& |
| 433 |
\& print "in effect\en" if bignum::in_effect; # true |
| 434 |
\& { |
| 435 |
\& no bignum; |
| 436 |
\& print "in effect\en" if bignum::in_effect; # false |
| 437 |
\& } |
| 438 |
.Ve |
| 439 |
.Sp |
| 440 |
Returns true or false if \f(CW\*(C`bignum\*(C'\fR is in effect in the current scope. |
| 441 |
.Sp |
| 442 |
This method only works on Perl v5.9.4 or later. |
| 443 |
.SH CAVEATS |
| 444 |
.IX Header "CAVEATS" |
| 445 |
.IP "The \fBupgrade()\fR and \fBdowngrade()\fR methods" 4 |
| 446 |
.IX Item "The upgrade() and downgrade() methods" |
| 447 |
Note that setting both the upgrade and downgrade classes at runtime with the |
| 448 |
"\fBupgrade()\fR" and "\fBdowngrade()\fR" methods, might not do what you expect: |
| 449 |
.Sp |
| 450 |
.Vb 4 |
| 451 |
\& # Assuming that downgrading and upgrading hasn\*(Aqt been modified so far, so |
| 452 |
\& # the downgrade and upgrade classes are Math::BigInt and Math::BigFloat, |
| 453 |
\& # respectively, the following sets the upgrade class to Math::BigRat, i.e., |
| 454 |
\& # makes Math::BigInt upgrade to Math::BigRat: |
| 455 |
\& |
| 456 |
\& bignum \-> upgrade("Math::BigRat"); |
| 457 |
\& |
| 458 |
\& # The following sets the downgrade class to Math::BigInt::Lite, i.e., makes |
| 459 |
\& # the new upgrade class Math::BigRat downgrade to Math::BigInt::Lite |
| 460 |
\& |
| 461 |
\& bignum \-> downgrade("Math::BigInt::Lite"); |
| 462 |
\& |
| 463 |
\& # Note that at this point, it is still Math::BigInt, not Math::BigInt::Lite, |
| 464 |
\& # that upgrades to Math::BigRat, so to get Math::BigInt::Lite to upgrade to |
| 465 |
\& # Math::BigRat, we need to do the following (again): |
| 466 |
\& |
| 467 |
\& bignum \-> upgrade("Math::BigRat"); |
| 468 |
.Ve |
| 469 |
.Sp |
| 470 |
A simpler way to do this at runtime is to use \fBimport()\fR, |
| 471 |
.Sp |
| 472 |
.Vb 2 |
| 473 |
\& bignum \-> import(upgrade => "Math::BigRat", |
| 474 |
\& downgrade => "Math::BigInt::Lite"); |
| 475 |
.Ve |
| 476 |
.IP "Hexadecimal, octal, and binary floating point literals" 4 |
| 477 |
.IX Item "Hexadecimal, octal, and binary floating point literals" |
| 478 |
Perl (and this module) accepts hexadecimal, octal, and binary floating point |
| 479 |
literals, but use them with care with Perl versions before v5.32.0, because some |
| 480 |
versions of Perl silently give the wrong result. |
| 481 |
.IP "Operator vs literal overloading" 4 |
| 482 |
.IX Item "Operator vs literal overloading" |
| 483 |
\&\f(CW\*(C`bigrat\*(C'\fR works by overloading handling of integer and floating point literals, |
| 484 |
converting them to Math::BigRat objects. |
| 485 |
.Sp |
| 486 |
This means that arithmetic involving only string values or string literals are |
| 487 |
performed using Perl's built-in operators. |
| 488 |
.Sp |
| 489 |
For example: |
| 490 |
.Sp |
| 491 |
.Vb 4 |
| 492 |
\& use bigrat; |
| 493 |
\& my $x = "900000000000000009"; |
| 494 |
\& my $y = "900000000000000007"; |
| 495 |
\& print $x \- $y; |
| 496 |
.Ve |
| 497 |
.Sp |
| 498 |
outputs \f(CW0\fR on default 32\-bit builds, since \f(CW\*(C`bignum\*(C'\fR never sees the string |
| 499 |
literals. To ensure the expression is all treated as \f(CW\*(C`Math::BigFloat\*(C'\fR objects, |
| 500 |
use a literal number in the expression: |
| 501 |
.Sp |
| 502 |
.Vb 1 |
| 503 |
\& print +(0+$x) \- $y; |
| 504 |
.Ve |
| 505 |
.IP Ranges 4 |
| 506 |
.IX Item "Ranges" |
| 507 |
Perl does not allow overloading of ranges, so you can neither safely use ranges |
| 508 |
with \f(CW\*(C`bignum\*(C'\fR endpoints, nor is the iterator variable a \f(CW\*(C`Math::BigFloat\*(C'\fR. |
| 509 |
.Sp |
| 510 |
.Vb 7 |
| 511 |
\& use 5.010; |
| 512 |
\& for my $i (12..13) { |
| 513 |
\& for my $j (20..21) { |
| 514 |
\& say $i ** $j; # produces a floating\-point number, |
| 515 |
\& # not an object |
| 516 |
\& } |
| 517 |
\& } |
| 518 |
.Ve |
| 519 |
.IP \fBin_effect()\fR 4 |
| 520 |
.IX Item "in_effect()" |
| 521 |
This method only works on Perl v5.9.4 or later. |
| 522 |
.IP \fBhex()\fR/\fBoct()\fR 4 |
| 523 |
.IX Item "hex()/oct()" |
| 524 |
\&\f(CW\*(C`bignum\*(C'\fR overrides these routines with versions that can also handle big |
| 525 |
integer values. Under Perl prior to version v5.9.4, however, this will not |
| 526 |
happen unless you specifically ask for it with the two import tags "hex" and |
| 527 |
"oct" \- and then it will be global and cannot be disabled inside a scope with |
| 528 |
\&\f(CW\*(C`no bignum\*(C'\fR: |
| 529 |
.Sp |
| 530 |
.Vb 1 |
| 531 |
\& use bignum qw/hex oct/; |
| 532 |
\& |
| 533 |
\& print hex("0x1234567890123456"); |
| 534 |
\& { |
| 535 |
\& no bignum; |
| 536 |
\& print hex("0x1234567890123456"); |
| 537 |
\& } |
| 538 |
.Ve |
| 539 |
.Sp |
| 540 |
The second call to \fBhex()\fR will warn about a non-portable constant. |
| 541 |
.Sp |
| 542 |
Compare this to: |
| 543 |
.Sp |
| 544 |
.Vb 1 |
| 545 |
\& use bignum; |
| 546 |
\& |
| 547 |
\& # will warn only under Perl older than v5.9.4 |
| 548 |
\& print hex("0x1234567890123456"); |
| 549 |
.Ve |
| 550 |
.SH EXAMPLES |
| 551 |
.IX Header "EXAMPLES" |
| 552 |
Some cool command line examples to impress the Python crowd ;) |
| 553 |
.PP |
| 554 |
.Vb 10 |
| 555 |
\& perl \-Mbignum \-le \*(Aqprint sqrt(33)\*(Aq |
| 556 |
\& perl \-Mbignum \-le \*(Aqprint 2**255\*(Aq |
| 557 |
\& perl \-Mbignum \-le \*(Aqprint 4.5+2**255\*(Aq |
| 558 |
\& perl \-Mbignum \-le \*(Aqprint 3/7 + 5/7 + 8/3\*(Aq |
| 559 |
\& perl \-Mbignum \-le \*(Aqprint 123\->is_odd()\*(Aq |
| 560 |
\& perl \-Mbignum \-le \*(Aqprint log(2)\*(Aq |
| 561 |
\& perl \-Mbignum \-le \*(Aqprint exp(1)\*(Aq |
| 562 |
\& perl \-Mbignum \-le \*(Aqprint 2 ** 0.5\*(Aq |
| 563 |
\& perl \-Mbignum=a,65 \-le \*(Aqprint 2 ** 0.2\*(Aq |
| 564 |
\& perl \-Mbignum=l,GMP \-le \*(Aqprint 7 ** 7777\*(Aq |
| 565 |
.Ve |
| 566 |
.SH BUGS |
| 567 |
.IX Header "BUGS" |
| 568 |
Please report any bugs or feature requests to |
| 569 |
\&\f(CW\*(C`bug\-bignum at rt.cpan.org\*(C'\fR, or through the web interface at |
| 570 |
<https://rt.cpan.org/Ticket/Create.html?Queue=bignum> (requires login). |
| 571 |
We will be notified, and then you'll automatically be notified of |
| 572 |
progress on your bug as I make changes. |
| 573 |
.SH SUPPORT |
| 574 |
.IX Header "SUPPORT" |
| 575 |
You can find documentation for this module with the perldoc command. |
| 576 |
.PP |
| 577 |
.Vb 1 |
| 578 |
\& perldoc bignum |
| 579 |
.Ve |
| 580 |
.PP |
| 581 |
You can also look for information at: |
| 582 |
.IP \(bu 4 |
| 583 |
GitHub |
| 584 |
.Sp |
| 585 |
<https://github.com/pjacklam/p5\-bignum> |
| 586 |
.IP \(bu 4 |
| 587 |
RT: CPAN's request tracker |
| 588 |
.Sp |
| 589 |
<https://rt.cpan.org/Dist/Display.html?Name=bignum> |
| 590 |
.IP \(bu 4 |
| 591 |
MetaCPAN |
| 592 |
.Sp |
| 593 |
<https://metacpan.org/release/bignum> |
| 594 |
.IP \(bu 4 |
| 595 |
CPAN Testers Matrix |
| 596 |
.Sp |
| 597 |
<http://matrix.cpantesters.org/?dist=bignum> |
| 598 |
.SH LICENSE |
| 599 |
.IX Header "LICENSE" |
| 600 |
This program is free software; you may redistribute it and/or modify it under |
| 601 |
the same terms as Perl itself. |
| 602 |
.SH "SEE ALSO" |
| 603 |
.IX Header "SEE ALSO" |
| 604 |
bigint and bigrat. |
| 605 |
.PP |
| 606 |
Math::BigInt, Math::BigFloat, Math::BigRat and Math::Big as well as |
| 607 |
Math::BigInt::FastCalc, Math::BigInt::Pari and Math::BigInt::GMP. |
| 608 |
.SH AUTHORS |
| 609 |
.IX Header "AUTHORS" |
| 610 |
.IP \(bu 4 |
| 611 |
(C) by Tels <http://bloodgate.com/> in early 2002 \- 2007. |
| 612 |
.IP \(bu 4 |
| 613 |
Maintained by Peter John Acklam <[email protected]>, 2014\-. |