| 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 "Math::BigRat 3perl" |
| 58 |
.TH Math::BigRat 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 |
Math::BigRat \- arbitrary size rational number math package |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
.Vb 1 |
| 68 |
\& use Math::BigRat; |
| 69 |
\& |
| 70 |
\& my $x = Math::BigRat\->new(\*(Aq3/7\*(Aq); $x += \*(Aq5/9\*(Aq; |
| 71 |
\& |
| 72 |
\& print $x\->bstr(), "\en"; |
| 73 |
\& print $x ** 2, "\en"; |
| 74 |
\& |
| 75 |
\& my $y = Math::BigRat\->new(\*(Aqinf\*(Aq); |
| 76 |
\& print "$y ", ($y\->is_inf ? \*(Aqis\*(Aq : \*(Aqis not\*(Aq), " infinity\en"; |
| 77 |
\& |
| 78 |
\& my $z = Math::BigRat\->new(144); $z\->bsqrt(); |
| 79 |
.Ve |
| 80 |
.SH DESCRIPTION |
| 81 |
.IX Header "DESCRIPTION" |
| 82 |
Math::BigRat complements Math::BigInt and Math::BigFloat by providing support |
| 83 |
for arbitrary big rational numbers. |
| 84 |
.SS "MATH LIBRARY" |
| 85 |
.IX Subsection "MATH LIBRARY" |
| 86 |
You can change the underlying module that does the low-level |
| 87 |
math operations by using: |
| 88 |
.PP |
| 89 |
.Vb 1 |
| 90 |
\& use Math::BigRat try => \*(AqGMP\*(Aq; |
| 91 |
.Ve |
| 92 |
.PP |
| 93 |
Note: This needs Math::BigInt::GMP installed. |
| 94 |
.PP |
| 95 |
The following would first try to find Math::BigInt::Foo, then |
| 96 |
Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc: |
| 97 |
.PP |
| 98 |
.Vb 1 |
| 99 |
\& use Math::BigRat try => \*(AqFoo,Math::BigInt::Bar\*(Aq; |
| 100 |
.Ve |
| 101 |
.PP |
| 102 |
If you want to get warned when the fallback occurs, replace "try" with "lib": |
| 103 |
.PP |
| 104 |
.Vb 1 |
| 105 |
\& use Math::BigRat lib => \*(AqFoo,Math::BigInt::Bar\*(Aq; |
| 106 |
.Ve |
| 107 |
.PP |
| 108 |
If you want the code to die instead, replace "try" with "only": |
| 109 |
.PP |
| 110 |
.Vb 1 |
| 111 |
\& use Math::BigRat only => \*(AqFoo,Math::BigInt::Bar\*(Aq; |
| 112 |
.Ve |
| 113 |
.SH METHODS |
| 114 |
.IX Header "METHODS" |
| 115 |
Any methods not listed here are derived from Math::BigFloat (or |
| 116 |
Math::BigInt), so make sure you check these two modules for further |
| 117 |
information. |
| 118 |
.IP \fBnew()\fR 4 |
| 119 |
.IX Item "new()" |
| 120 |
.Vb 1 |
| 121 |
\& $x = Math::BigRat\->new(\*(Aq1/3\*(Aq); |
| 122 |
.Ve |
| 123 |
.Sp |
| 124 |
Create a new Math::BigRat object. Input can come in various forms: |
| 125 |
.Sp |
| 126 |
.Vb 9 |
| 127 |
\& $x = Math::BigRat\->new(123); # scalars |
| 128 |
\& $x = Math::BigRat\->new(\*(Aqinf\*(Aq); # infinity |
| 129 |
\& $x = Math::BigRat\->new(\*(Aq123.3\*(Aq); # float |
| 130 |
\& $x = Math::BigRat\->new(\*(Aq1/3\*(Aq); # simple string |
| 131 |
\& $x = Math::BigRat\->new(\*(Aq1 / 3\*(Aq); # spaced |
| 132 |
\& $x = Math::BigRat\->new(\*(Aq1 / 0.1\*(Aq); # w/ floats |
| 133 |
\& $x = Math::BigRat\->new(Math::BigInt\->new(3)); # BigInt |
| 134 |
\& $x = Math::BigRat\->new(Math::BigFloat\->new(\*(Aq3.1\*(Aq)); # BigFloat |
| 135 |
\& $x = Math::BigRat\->new(Math::BigInt::Lite\->new(\*(Aq2\*(Aq)); # BigLite |
| 136 |
\& |
| 137 |
\& # You can also give D and N as different objects: |
| 138 |
\& $x = Math::BigRat\->new( |
| 139 |
\& Math::BigInt\->new(\-123), |
| 140 |
\& Math::BigInt\->new(7), |
| 141 |
\& ); # => \-123/7 |
| 142 |
.Ve |
| 143 |
.IP \fBnumerator()\fR 4 |
| 144 |
.IX Item "numerator()" |
| 145 |
.Vb 1 |
| 146 |
\& $n = $x\->numerator(); |
| 147 |
.Ve |
| 148 |
.Sp |
| 149 |
Returns a copy of the numerator (the part above the line) as signed BigInt. |
| 150 |
.IP \fBdenominator()\fR 4 |
| 151 |
.IX Item "denominator()" |
| 152 |
.Vb 1 |
| 153 |
\& $d = $x\->denominator(); |
| 154 |
.Ve |
| 155 |
.Sp |
| 156 |
Returns a copy of the denominator (the part under the line) as positive BigInt. |
| 157 |
.IP \fBparts()\fR 4 |
| 158 |
.IX Item "parts()" |
| 159 |
.Vb 1 |
| 160 |
\& ($n, $d) = $x\->parts(); |
| 161 |
.Ve |
| 162 |
.Sp |
| 163 |
Return a list consisting of (signed) numerator and (unsigned) denominator as |
| 164 |
BigInts. |
| 165 |
.IP \fBdparts()\fR 4 |
| 166 |
.IX Item "dparts()" |
| 167 |
Returns the integer part and the fraction part. |
| 168 |
.IP \fBfparts()\fR 4 |
| 169 |
.IX Item "fparts()" |
| 170 |
Returns the smallest possible numerator and denominator so that the numerator |
| 171 |
divided by the denominator gives back the original value. For finite numbers, |
| 172 |
both values are integers. Mnemonic: fraction. |
| 173 |
.IP \fBnumify()\fR 4 |
| 174 |
.IX Item "numify()" |
| 175 |
.Vb 1 |
| 176 |
\& my $y = $x\->numify(); |
| 177 |
.Ve |
| 178 |
.Sp |
| 179 |
Returns the object as a scalar. This will lose some data if the object |
| 180 |
cannot be represented by a normal Perl scalar (integer or float), so |
| 181 |
use "\fBas_int()\fR" or "\fBas_float()\fR" instead. |
| 182 |
.Sp |
| 183 |
This routine is automatically used whenever a scalar is required: |
| 184 |
.Sp |
| 185 |
.Vb 3 |
| 186 |
\& my $x = Math::BigRat\->new(\*(Aq3/1\*(Aq); |
| 187 |
\& @array = (0, 1, 2, 3); |
| 188 |
\& $y = $array[$x]; # set $y to 3 |
| 189 |
.Ve |
| 190 |
.IP \fBas_int()\fR 4 |
| 191 |
.IX Item "as_int()" |
| 192 |
.PD 0 |
| 193 |
.IP \fBas_number()\fR 4 |
| 194 |
.IX Item "as_number()" |
| 195 |
.PD |
| 196 |
.Vb 2 |
| 197 |
\& $x = Math::BigRat\->new(\*(Aq13/7\*(Aq); |
| 198 |
\& print $x\->as_int(), "\en"; # \*(Aq1\*(Aq |
| 199 |
.Ve |
| 200 |
.Sp |
| 201 |
Returns a copy of the object as BigInt, truncated to an integer. |
| 202 |
.Sp |
| 203 |
\&\f(CWas_number()\fR is an alias for \f(CWas_int()\fR. |
| 204 |
.IP \fBas_float()\fR 4 |
| 205 |
.IX Item "as_float()" |
| 206 |
.Vb 2 |
| 207 |
\& $x = Math::BigRat\->new(\*(Aq13/7\*(Aq); |
| 208 |
\& print $x\->as_float(), "\en"; # \*(Aq1\*(Aq |
| 209 |
\& |
| 210 |
\& $x = Math::BigRat\->new(\*(Aq2/3\*(Aq); |
| 211 |
\& print $x\->as_float(5), "\en"; # \*(Aq0.66667\*(Aq |
| 212 |
.Ve |
| 213 |
.Sp |
| 214 |
Returns a copy of the object as BigFloat, preserving the |
| 215 |
accuracy as wanted, or the default of 40 digits. |
| 216 |
.Sp |
| 217 |
This method was added in v0.22 of Math::BigRat (April 2008). |
| 218 |
.IP \fBas_hex()\fR 4 |
| 219 |
.IX Item "as_hex()" |
| 220 |
.Vb 2 |
| 221 |
\& $x = Math::BigRat\->new(\*(Aq13\*(Aq); |
| 222 |
\& print $x\->as_hex(), "\en"; # \*(Aq0xd\*(Aq |
| 223 |
.Ve |
| 224 |
.Sp |
| 225 |
Returns the BigRat as hexadecimal string. Works only for integers. |
| 226 |
.IP \fBas_bin()\fR 4 |
| 227 |
.IX Item "as_bin()" |
| 228 |
.Vb 2 |
| 229 |
\& $x = Math::BigRat\->new(\*(Aq13\*(Aq); |
| 230 |
\& print $x\->as_bin(), "\en"; # \*(Aq0x1101\*(Aq |
| 231 |
.Ve |
| 232 |
.Sp |
| 233 |
Returns the BigRat as binary string. Works only for integers. |
| 234 |
.IP \fBas_oct()\fR 4 |
| 235 |
.IX Item "as_oct()" |
| 236 |
.Vb 2 |
| 237 |
\& $x = Math::BigRat\->new(\*(Aq13\*(Aq); |
| 238 |
\& print $x\->as_oct(), "\en"; # \*(Aq015\*(Aq |
| 239 |
.Ve |
| 240 |
.Sp |
| 241 |
Returns the BigRat as octal string. Works only for integers. |
| 242 |
.IP \fBfrom_hex()\fR 4 |
| 243 |
.IX Item "from_hex()" |
| 244 |
.Vb 1 |
| 245 |
\& my $h = Math::BigRat\->from_hex(\*(Aq0x10\*(Aq); |
| 246 |
.Ve |
| 247 |
.Sp |
| 248 |
Create a BigRat from a hexadecimal number in string form. |
| 249 |
.IP \fBfrom_oct()\fR 4 |
| 250 |
.IX Item "from_oct()" |
| 251 |
.Vb 1 |
| 252 |
\& my $o = Math::BigRat\->from_oct(\*(Aq020\*(Aq); |
| 253 |
.Ve |
| 254 |
.Sp |
| 255 |
Create a BigRat from an octal number in string form. |
| 256 |
.IP \fBfrom_bin()\fR 4 |
| 257 |
.IX Item "from_bin()" |
| 258 |
.Vb 1 |
| 259 |
\& my $b = Math::BigRat\->from_bin(\*(Aq0b10000000\*(Aq); |
| 260 |
.Ve |
| 261 |
.Sp |
| 262 |
Create a BigRat from an binary number in string form. |
| 263 |
.IP \fBbnan()\fR 4 |
| 264 |
.IX Item "bnan()" |
| 265 |
.Vb 1 |
| 266 |
\& $x = Math::BigRat\->bnan(); |
| 267 |
.Ve |
| 268 |
.Sp |
| 269 |
Creates a new BigRat object representing NaN (Not A Number). |
| 270 |
If used on an object, it will set it to NaN: |
| 271 |
.Sp |
| 272 |
.Vb 1 |
| 273 |
\& $x\->bnan(); |
| 274 |
.Ve |
| 275 |
.IP \fBbzero()\fR 4 |
| 276 |
.IX Item "bzero()" |
| 277 |
.Vb 1 |
| 278 |
\& $x = Math::BigRat\->bzero(); |
| 279 |
.Ve |
| 280 |
.Sp |
| 281 |
Creates a new BigRat object representing zero. |
| 282 |
If used on an object, it will set it to zero: |
| 283 |
.Sp |
| 284 |
.Vb 1 |
| 285 |
\& $x\->bzero(); |
| 286 |
.Ve |
| 287 |
.IP \fBbinf()\fR 4 |
| 288 |
.IX Item "binf()" |
| 289 |
.Vb 1 |
| 290 |
\& $x = Math::BigRat\->binf($sign); |
| 291 |
.Ve |
| 292 |
.Sp |
| 293 |
Creates a new BigRat object representing infinity. The optional argument is |
| 294 |
either '\-' or '+', indicating whether you want infinity or minus infinity. |
| 295 |
If used on an object, it will set it to infinity: |
| 296 |
.Sp |
| 297 |
.Vb 2 |
| 298 |
\& $x\->binf(); |
| 299 |
\& $x\->binf(\*(Aq\-\*(Aq); |
| 300 |
.Ve |
| 301 |
.IP \fBbone()\fR 4 |
| 302 |
.IX Item "bone()" |
| 303 |
.Vb 1 |
| 304 |
\& $x = Math::BigRat\->bone($sign); |
| 305 |
.Ve |
| 306 |
.Sp |
| 307 |
Creates a new BigRat object representing one. The optional argument is |
| 308 |
either '\-' or '+', indicating whether you want one or minus one. |
| 309 |
If used on an object, it will set it to one: |
| 310 |
.Sp |
| 311 |
.Vb 2 |
| 312 |
\& $x\->bone(); # +1 |
| 313 |
\& $x\->bone(\*(Aq\-\*(Aq); # \-1 |
| 314 |
.Ve |
| 315 |
.IP \fBlength()\fR 4 |
| 316 |
.IX Item "length()" |
| 317 |
.Vb 1 |
| 318 |
\& $len = $x\->length(); |
| 319 |
.Ve |
| 320 |
.Sp |
| 321 |
Return the length of \f(CW$x\fR in digits for integer values. |
| 322 |
.IP \fBdigit()\fR 4 |
| 323 |
.IX Item "digit()" |
| 324 |
.Vb 2 |
| 325 |
\& print Math::BigRat\->new(\*(Aq123/1\*(Aq)\->digit(1); # 1 |
| 326 |
\& print Math::BigRat\->new(\*(Aq123/1\*(Aq)\->digit(\-1); # 3 |
| 327 |
.Ve |
| 328 |
.Sp |
| 329 |
Return the N'ths digit from X when X is an integer value. |
| 330 |
.IP \fBbnorm()\fR 4 |
| 331 |
.IX Item "bnorm()" |
| 332 |
.Vb 1 |
| 333 |
\& $x\->bnorm(); |
| 334 |
.Ve |
| 335 |
.Sp |
| 336 |
Reduce the number to the shortest form. This routine is called |
| 337 |
automatically whenever it is needed. |
| 338 |
.IP \fBbfac()\fR 4 |
| 339 |
.IX Item "bfac()" |
| 340 |
.Vb 1 |
| 341 |
\& $x\->bfac(); |
| 342 |
.Ve |
| 343 |
.Sp |
| 344 |
Calculates the factorial of \f(CW$x\fR. For instance: |
| 345 |
.Sp |
| 346 |
.Vb 2 |
| 347 |
\& print Math::BigRat\->new(\*(Aq3/1\*(Aq)\->bfac(), "\en"; # 1*2*3 |
| 348 |
\& print Math::BigRat\->new(\*(Aq5/1\*(Aq)\->bfac(), "\en"; # 1*2*3*4*5 |
| 349 |
.Ve |
| 350 |
.Sp |
| 351 |
Works currently only for integers. |
| 352 |
.IP \fBbround()\fR/\fBround()\fR/\fBbfround()\fR 4 |
| 353 |
.IX Item "bround()/round()/bfround()" |
| 354 |
Are not yet implemented. |
| 355 |
.IP \fBbmod()\fR 4 |
| 356 |
.IX Item "bmod()" |
| 357 |
.Vb 1 |
| 358 |
\& $x\->bmod($y); |
| 359 |
.Ve |
| 360 |
.Sp |
| 361 |
Returns \f(CW$x\fR modulo \f(CW$y\fR. When \f(CW$x\fR is finite, and \f(CW$y\fR is finite and non-zero, the |
| 362 |
result is identical to the remainder after floored division (F\-division). If, |
| 363 |
in addition, both \f(CW$x\fR and \f(CW$y\fR are integers, the result is identical to the result |
| 364 |
from Perl's % operator. |
| 365 |
.IP \fBbmodinv()\fR 4 |
| 366 |
.IX Item "bmodinv()" |
| 367 |
.Vb 1 |
| 368 |
\& $x\->bmodinv($mod); # modular multiplicative inverse |
| 369 |
.Ve |
| 370 |
.Sp |
| 371 |
Returns the multiplicative inverse of \f(CW$x\fR modulo \f(CW$mod\fR. If |
| 372 |
.Sp |
| 373 |
.Vb 1 |
| 374 |
\& $y = $x \-> copy() \-> bmodinv($mod) |
| 375 |
.Ve |
| 376 |
.Sp |
| 377 |
then \f(CW$y\fR is the number closest to zero, and with the same sign as \f(CW$mod\fR, |
| 378 |
satisfying |
| 379 |
.Sp |
| 380 |
.Vb 1 |
| 381 |
\& ($x * $y) % $mod = 1 % $mod |
| 382 |
.Ve |
| 383 |
.Sp |
| 384 |
If \f(CW$x\fR and \f(CW$y\fR are non-zero, they must be relative primes, i.e., |
| 385 |
\&\f(CW\*(C`bgcd($y, $mod)==1\*(C'\fR. '\f(CW\*(C`NaN\*(C'\fR' is returned when no modular multiplicative |
| 386 |
inverse exists. |
| 387 |
.IP \fBbmodpow()\fR 4 |
| 388 |
.IX Item "bmodpow()" |
| 389 |
.Vb 2 |
| 390 |
\& $num\->bmodpow($exp,$mod); # modular exponentiation |
| 391 |
\& # ($num**$exp % $mod) |
| 392 |
.Ve |
| 393 |
.Sp |
| 394 |
Returns the value of \f(CW$num\fR taken to the power \f(CW$exp\fR in the modulus |
| 395 |
\&\f(CW$mod\fR using binary exponentiation. \f(CW\*(C`bmodpow\*(C'\fR is far superior to |
| 396 |
writing |
| 397 |
.Sp |
| 398 |
.Vb 1 |
| 399 |
\& $num ** $exp % $mod |
| 400 |
.Ve |
| 401 |
.Sp |
| 402 |
because it is much faster \- it reduces internal variables into |
| 403 |
the modulus whenever possible, so it operates on smaller numbers. |
| 404 |
.Sp |
| 405 |
\&\f(CW\*(C`bmodpow\*(C'\fR also supports negative exponents. |
| 406 |
.Sp |
| 407 |
.Vb 1 |
| 408 |
\& bmodpow($num, \-1, $mod) |
| 409 |
.Ve |
| 410 |
.Sp |
| 411 |
is exactly equivalent to |
| 412 |
.Sp |
| 413 |
.Vb 1 |
| 414 |
\& bmodinv($num, $mod) |
| 415 |
.Ve |
| 416 |
.IP \fBbneg()\fR 4 |
| 417 |
.IX Item "bneg()" |
| 418 |
.Vb 1 |
| 419 |
\& $x\->bneg(); |
| 420 |
.Ve |
| 421 |
.Sp |
| 422 |
Used to negate the object in-place. |
| 423 |
.IP \fBis_one()\fR 4 |
| 424 |
.IX Item "is_one()" |
| 425 |
.Vb 1 |
| 426 |
\& print "$x is 1\en" if $x\->is_one(); |
| 427 |
.Ve |
| 428 |
.Sp |
| 429 |
Return true if \f(CW$x\fR is exactly one, otherwise false. |
| 430 |
.IP \fBis_zero()\fR 4 |
| 431 |
.IX Item "is_zero()" |
| 432 |
.Vb 1 |
| 433 |
\& print "$x is 0\en" if $x\->is_zero(); |
| 434 |
.Ve |
| 435 |
.Sp |
| 436 |
Return true if \f(CW$x\fR is exactly zero, otherwise false. |
| 437 |
.IP \fBis_pos()\fR/\fBis_positive()\fR 4 |
| 438 |
.IX Item "is_pos()/is_positive()" |
| 439 |
.Vb 1 |
| 440 |
\& print "$x is >= 0\en" if $x\->is_positive(); |
| 441 |
.Ve |
| 442 |
.Sp |
| 443 |
Return true if \f(CW$x\fR is positive (greater than or equal to zero), otherwise |
| 444 |
false. Please note that '+inf' is also positive, while 'NaN' and '\-inf' aren't. |
| 445 |
.Sp |
| 446 |
\&\f(CWis_positive()\fR is an alias for \f(CWis_pos()\fR. |
| 447 |
.IP \fBis_neg()\fR/\fBis_negative()\fR 4 |
| 448 |
.IX Item "is_neg()/is_negative()" |
| 449 |
.Vb 1 |
| 450 |
\& print "$x is < 0\en" if $x\->is_negative(); |
| 451 |
.Ve |
| 452 |
.Sp |
| 453 |
Return true if \f(CW$x\fR is negative (smaller than zero), otherwise false. Please |
| 454 |
note that '\-inf' is also negative, while 'NaN' and '+inf' aren't. |
| 455 |
.Sp |
| 456 |
\&\f(CWis_negative()\fR is an alias for \f(CWis_neg()\fR. |
| 457 |
.IP \fBis_int()\fR 4 |
| 458 |
.IX Item "is_int()" |
| 459 |
.Vb 1 |
| 460 |
\& print "$x is an integer\en" if $x\->is_int(); |
| 461 |
.Ve |
| 462 |
.Sp |
| 463 |
Return true if \f(CW$x\fR has a denominator of 1 (e.g. no fraction parts), otherwise |
| 464 |
false. Please note that '\-inf', 'inf' and 'NaN' aren't integer. |
| 465 |
.IP \fBis_odd()\fR 4 |
| 466 |
.IX Item "is_odd()" |
| 467 |
.Vb 1 |
| 468 |
\& print "$x is odd\en" if $x\->is_odd(); |
| 469 |
.Ve |
| 470 |
.Sp |
| 471 |
Return true if \f(CW$x\fR is odd, otherwise false. |
| 472 |
.IP \fBis_even()\fR 4 |
| 473 |
.IX Item "is_even()" |
| 474 |
.Vb 1 |
| 475 |
\& print "$x is even\en" if $x\->is_even(); |
| 476 |
.Ve |
| 477 |
.Sp |
| 478 |
Return true if \f(CW$x\fR is even, otherwise false. |
| 479 |
.IP \fBbceil()\fR 4 |
| 480 |
.IX Item "bceil()" |
| 481 |
.Vb 1 |
| 482 |
\& $x\->bceil(); |
| 483 |
.Ve |
| 484 |
.Sp |
| 485 |
Set \f(CW$x\fR to the next bigger integer value (e.g. truncate the number to integer |
| 486 |
and then increment it by one). |
| 487 |
.IP \fBbfloor()\fR 4 |
| 488 |
.IX Item "bfloor()" |
| 489 |
.Vb 1 |
| 490 |
\& $x\->bfloor(); |
| 491 |
.Ve |
| 492 |
.Sp |
| 493 |
Truncate \f(CW$x\fR to an integer value. |
| 494 |
.IP \fBbint()\fR 4 |
| 495 |
.IX Item "bint()" |
| 496 |
.Vb 1 |
| 497 |
\& $x\->bint(); |
| 498 |
.Ve |
| 499 |
.Sp |
| 500 |
Round \f(CW$x\fR towards zero. |
| 501 |
.IP \fBbsqrt()\fR 4 |
| 502 |
.IX Item "bsqrt()" |
| 503 |
.Vb 1 |
| 504 |
\& $x\->bsqrt(); |
| 505 |
.Ve |
| 506 |
.Sp |
| 507 |
Calculate the square root of \f(CW$x\fR. |
| 508 |
.IP \fBbroot()\fR 4 |
| 509 |
.IX Item "broot()" |
| 510 |
.Vb 1 |
| 511 |
\& $x\->broot($n); |
| 512 |
.Ve |
| 513 |
.Sp |
| 514 |
Calculate the N'th root of \f(CW$x\fR. |
| 515 |
.IP \fBbadd()\fR 4 |
| 516 |
.IX Item "badd()" |
| 517 |
.Vb 1 |
| 518 |
\& $x\->badd($y); |
| 519 |
.Ve |
| 520 |
.Sp |
| 521 |
Adds \f(CW$y\fR to \f(CW$x\fR and returns the result. |
| 522 |
.IP \fBbmul()\fR 4 |
| 523 |
.IX Item "bmul()" |
| 524 |
.Vb 1 |
| 525 |
\& $x\->bmul($y); |
| 526 |
.Ve |
| 527 |
.Sp |
| 528 |
Multiplies \f(CW$y\fR to \f(CW$x\fR and returns the result. |
| 529 |
.IP \fBbsub()\fR 4 |
| 530 |
.IX Item "bsub()" |
| 531 |
.Vb 1 |
| 532 |
\& $x\->bsub($y); |
| 533 |
.Ve |
| 534 |
.Sp |
| 535 |
Subtracts \f(CW$y\fR from \f(CW$x\fR and returns the result. |
| 536 |
.IP \fBbdiv()\fR 4 |
| 537 |
.IX Item "bdiv()" |
| 538 |
.Vb 2 |
| 539 |
\& $q = $x\->bdiv($y); |
| 540 |
\& ($q, $r) = $x\->bdiv($y); |
| 541 |
.Ve |
| 542 |
.Sp |
| 543 |
In scalar context, divides \f(CW$x\fR by \f(CW$y\fR and returns the result. In list context, |
| 544 |
does floored division (F\-division), returning an integer \f(CW$q\fR and a remainder \f(CW$r\fR |
| 545 |
so that \f(CW$x\fR = \f(CW$q\fR * \f(CW$y\fR + \f(CW$r\fR. The remainer (modulo) is equal to what is returned |
| 546 |
by \f(CW\*(C`$x\->bmod($y)\*(C'\fR. |
| 547 |
.IP \fBbinv()\fR 4 |
| 548 |
.IX Item "binv()" |
| 549 |
.Vb 1 |
| 550 |
\& $x\->binv(); |
| 551 |
.Ve |
| 552 |
.Sp |
| 553 |
Inverse of \f(CW$x\fR. |
| 554 |
.IP \fBbdec()\fR 4 |
| 555 |
.IX Item "bdec()" |
| 556 |
.Vb 1 |
| 557 |
\& $x\->bdec(); |
| 558 |
.Ve |
| 559 |
.Sp |
| 560 |
Decrements \f(CW$x\fR by 1 and returns the result. |
| 561 |
.IP \fBbinc()\fR 4 |
| 562 |
.IX Item "binc()" |
| 563 |
.Vb 1 |
| 564 |
\& $x\->binc(); |
| 565 |
.Ve |
| 566 |
.Sp |
| 567 |
Increments \f(CW$x\fR by 1 and returns the result. |
| 568 |
.IP \fBcopy()\fR 4 |
| 569 |
.IX Item "copy()" |
| 570 |
.Vb 1 |
| 571 |
\& my $z = $x\->copy(); |
| 572 |
.Ve |
| 573 |
.Sp |
| 574 |
Makes a deep copy of the object. |
| 575 |
.Sp |
| 576 |
Please see the documentation in Math::BigInt for further details. |
| 577 |
.IP \fBbstr()\fR/\fBbsstr()\fR 4 |
| 578 |
.IX Item "bstr()/bsstr()" |
| 579 |
.Vb 3 |
| 580 |
\& my $x = Math::BigRat\->new(\*(Aq8/4\*(Aq); |
| 581 |
\& print $x\->bstr(), "\en"; # prints 1/2 |
| 582 |
\& print $x\->bsstr(), "\en"; # prints 1/2 |
| 583 |
.Ve |
| 584 |
.Sp |
| 585 |
Return a string representing this object. |
| 586 |
.IP \fBbcmp()\fR 4 |
| 587 |
.IX Item "bcmp()" |
| 588 |
.Vb 1 |
| 589 |
\& $x\->bcmp($y); |
| 590 |
.Ve |
| 591 |
.Sp |
| 592 |
Compares \f(CW$x\fR with \f(CW$y\fR and takes the sign into account. |
| 593 |
Returns \-1, 0, 1 or undef. |
| 594 |
.IP \fBbacmp()\fR 4 |
| 595 |
.IX Item "bacmp()" |
| 596 |
.Vb 1 |
| 597 |
\& $x\->bacmp($y); |
| 598 |
.Ve |
| 599 |
.Sp |
| 600 |
Compares \f(CW$x\fR with \f(CW$y\fR while ignoring their sign. Returns \-1, 0, 1 or undef. |
| 601 |
.IP \fBbeq()\fR 4 |
| 602 |
.IX Item "beq()" |
| 603 |
.Vb 1 |
| 604 |
\& $x \-> beq($y); |
| 605 |
.Ve |
| 606 |
.Sp |
| 607 |
Returns true if and only if \f(CW$x\fR is equal to \f(CW$y\fR, and false otherwise. |
| 608 |
.IP \fBbne()\fR 4 |
| 609 |
.IX Item "bne()" |
| 610 |
.Vb 1 |
| 611 |
\& $x \-> bne($y); |
| 612 |
.Ve |
| 613 |
.Sp |
| 614 |
Returns true if and only if \f(CW$x\fR is not equal to \f(CW$y\fR, and false otherwise. |
| 615 |
.IP \fBblt()\fR 4 |
| 616 |
.IX Item "blt()" |
| 617 |
.Vb 1 |
| 618 |
\& $x \-> blt($y); |
| 619 |
.Ve |
| 620 |
.Sp |
| 621 |
Returns true if and only if \f(CW$x\fR is equal to \f(CW$y\fR, and false otherwise. |
| 622 |
.IP \fBble()\fR 4 |
| 623 |
.IX Item "ble()" |
| 624 |
.Vb 1 |
| 625 |
\& $x \-> ble($y); |
| 626 |
.Ve |
| 627 |
.Sp |
| 628 |
Returns true if and only if \f(CW$x\fR is less than or equal to \f(CW$y\fR, and false |
| 629 |
otherwise. |
| 630 |
.IP \fBbgt()\fR 4 |
| 631 |
.IX Item "bgt()" |
| 632 |
.Vb 1 |
| 633 |
\& $x \-> bgt($y); |
| 634 |
.Ve |
| 635 |
.Sp |
| 636 |
Returns true if and only if \f(CW$x\fR is greater than \f(CW$y\fR, and false otherwise. |
| 637 |
.IP \fBbge()\fR 4 |
| 638 |
.IX Item "bge()" |
| 639 |
.Vb 1 |
| 640 |
\& $x \-> bge($y); |
| 641 |
.Ve |
| 642 |
.Sp |
| 643 |
Returns true if and only if \f(CW$x\fR is greater than or equal to \f(CW$y\fR, and false |
| 644 |
otherwise. |
| 645 |
.IP \fBblsft()\fR/\fBbrsft()\fR 4 |
| 646 |
.IX Item "blsft()/brsft()" |
| 647 |
Used to shift numbers left/right. |
| 648 |
.Sp |
| 649 |
Please see the documentation in Math::BigInt for further details. |
| 650 |
.IP \fBband()\fR 4 |
| 651 |
.IX Item "band()" |
| 652 |
.Vb 1 |
| 653 |
\& $x\->band($y); # bitwise and |
| 654 |
.Ve |
| 655 |
.IP \fBbior()\fR 4 |
| 656 |
.IX Item "bior()" |
| 657 |
.Vb 1 |
| 658 |
\& $x\->bior($y); # bitwise inclusive or |
| 659 |
.Ve |
| 660 |
.IP \fBbxor()\fR 4 |
| 661 |
.IX Item "bxor()" |
| 662 |
.Vb 1 |
| 663 |
\& $x\->bxor($y); # bitwise exclusive or |
| 664 |
.Ve |
| 665 |
.IP \fBbnot()\fR 4 |
| 666 |
.IX Item "bnot()" |
| 667 |
.Vb 1 |
| 668 |
\& $x\->bnot(); # bitwise not (two\*(Aqs complement) |
| 669 |
.Ve |
| 670 |
.IP \fBbpow()\fR 4 |
| 671 |
.IX Item "bpow()" |
| 672 |
.Vb 1 |
| 673 |
\& $x\->bpow($y); |
| 674 |
.Ve |
| 675 |
.Sp |
| 676 |
Compute \f(CW$x\fR ** \f(CW$y\fR. |
| 677 |
.Sp |
| 678 |
Please see the documentation in Math::BigInt for further details. |
| 679 |
.IP \fBblog()\fR 4 |
| 680 |
.IX Item "blog()" |
| 681 |
.Vb 1 |
| 682 |
\& $x\->blog($base, $accuracy); # logarithm of x to the base $base |
| 683 |
.Ve |
| 684 |
.Sp |
| 685 |
If \f(CW$base\fR is not defined, Euler's number (e) is used: |
| 686 |
.Sp |
| 687 |
.Vb 1 |
| 688 |
\& print $x\->blog(undef, 100); # log(x) to 100 digits |
| 689 |
.Ve |
| 690 |
.IP \fBbexp()\fR 4 |
| 691 |
.IX Item "bexp()" |
| 692 |
.Vb 1 |
| 693 |
\& $x\->bexp($accuracy); # calculate e ** X |
| 694 |
.Ve |
| 695 |
.Sp |
| 696 |
Calculates two integers A and B so that A/B is equal to \f(CW\*(C`e ** $x\*(C'\fR, where \f(CW\*(C`e\*(C'\fR is |
| 697 |
Euler's number. |
| 698 |
.Sp |
| 699 |
This method was added in v0.20 of Math::BigRat (May 2007). |
| 700 |
.Sp |
| 701 |
See also \f(CWblog()\fR. |
| 702 |
.IP \fBbnok()\fR 4 |
| 703 |
.IX Item "bnok()" |
| 704 |
.Vb 1 |
| 705 |
\& $x\->bnok($y); # x over y (binomial coefficient n over k) |
| 706 |
.Ve |
| 707 |
.Sp |
| 708 |
Calculates the binomial coefficient n over k, also called the "choose" |
| 709 |
function. The result is equivalent to: |
| 710 |
.Sp |
| 711 |
.Vb 3 |
| 712 |
\& ( n ) n! |
| 713 |
\& | \- | = \-\-\-\-\-\-\- |
| 714 |
\& ( k ) k!(n\-k)! |
| 715 |
.Ve |
| 716 |
.Sp |
| 717 |
This method was added in v0.20 of Math::BigRat (May 2007). |
| 718 |
.IP \fBconfig()\fR 4 |
| 719 |
.IX Item "config()" |
| 720 |
.Vb 2 |
| 721 |
\& Math::BigRat\->config("trap_nan" => 1); # set |
| 722 |
\& $accu = Math::BigRat\->config("accuracy"); # get |
| 723 |
.Ve |
| 724 |
.Sp |
| 725 |
Set or get configuration parameter values. Read-only parameters are marked as |
| 726 |
RO. Read-write parameters are marked as RW. The following parameters are |
| 727 |
supported. |
| 728 |
.Sp |
| 729 |
.Vb 10 |
| 730 |
\& Parameter RO/RW Description |
| 731 |
\& Example |
| 732 |
\& ============================================================ |
| 733 |
\& lib RO Name of the math backend library |
| 734 |
\& Math::BigInt::Calc |
| 735 |
\& lib_version RO Version of the math backend library |
| 736 |
\& 0.30 |
| 737 |
\& class RO The class of config you just called |
| 738 |
\& Math::BigRat |
| 739 |
\& version RO version number of the class you used |
| 740 |
\& 0.10 |
| 741 |
\& upgrade RW To which class numbers are upgraded |
| 742 |
\& undef |
| 743 |
\& downgrade RW To which class numbers are downgraded |
| 744 |
\& undef |
| 745 |
\& precision RW Global precision |
| 746 |
\& undef |
| 747 |
\& accuracy RW Global accuracy |
| 748 |
\& undef |
| 749 |
\& round_mode RW Global round mode |
| 750 |
\& even |
| 751 |
\& div_scale RW Fallback accuracy for div, sqrt etc. |
| 752 |
\& 40 |
| 753 |
\& trap_nan RW Trap NaNs |
| 754 |
\& undef |
| 755 |
\& trap_inf RW Trap +inf/\-inf |
| 756 |
\& undef |
| 757 |
.Ve |
| 758 |
.SH "NUMERIC LITERALS" |
| 759 |
.IX Header "NUMERIC LITERALS" |
| 760 |
After \f(CW\*(C`use Math::BigRat \*(Aq:constant\*(Aq\*(C'\fR all numeric literals in the given scope |
| 761 |
are converted to \f(CW\*(C`Math::BigRat\*(C'\fR objects. This conversion happens at compile |
| 762 |
time. Every non-integer is convert to a NaN. |
| 763 |
.PP |
| 764 |
For example, |
| 765 |
.PP |
| 766 |
.Vb 1 |
| 767 |
\& perl \-MMath::BigRat=:constant \-le \*(Aqprint 2**150\*(Aq |
| 768 |
.Ve |
| 769 |
.PP |
| 770 |
prints the exact value of \f(CW\*(C`2**150\*(C'\fR. Note that without conversion of constants |
| 771 |
to objects the expression \f(CW\*(C`2**150\*(C'\fR is calculated using Perl scalars, which |
| 772 |
leads to an inaccurate result. |
| 773 |
.PP |
| 774 |
Please note that strings are not affected, so that |
| 775 |
.PP |
| 776 |
.Vb 1 |
| 777 |
\& use Math::BigRat qw/:constant/; |
| 778 |
\& |
| 779 |
\& $x = "1234567890123456789012345678901234567890" |
| 780 |
\& + "123456789123456789"; |
| 781 |
.Ve |
| 782 |
.PP |
| 783 |
does give you what you expect. You need an explicit Math::BigRat\->\fBnew()\fR around |
| 784 |
at least one of the operands. You should also quote large constants to prevent |
| 785 |
loss of precision: |
| 786 |
.PP |
| 787 |
.Vb 1 |
| 788 |
\& use Math::BigRat; |
| 789 |
\& |
| 790 |
\& $x = Math::BigRat\->new("1234567889123456789123456789123456789"); |
| 791 |
.Ve |
| 792 |
.PP |
| 793 |
Without the quotes Perl first converts the large number to a floating point |
| 794 |
constant at compile time, and then converts the result to a Math::BigRat object |
| 795 |
at run time, which results in an inaccurate result. |
| 796 |
.SS "Hexadecimal, octal, and binary floating point literals" |
| 797 |
.IX Subsection "Hexadecimal, octal, and binary floating point literals" |
| 798 |
Perl (and this module) accepts hexadecimal, octal, and binary floating point |
| 799 |
literals, but use them with care with Perl versions before v5.32.0, because some |
| 800 |
versions of Perl silently give the wrong result. Below are some examples of |
| 801 |
different ways to write the number decimal 314. |
| 802 |
.PP |
| 803 |
Hexadecimal floating point literals: |
| 804 |
.PP |
| 805 |
.Vb 3 |
| 806 |
\& 0x1.3ap+8 0X1.3AP+8 |
| 807 |
\& 0x1.3ap8 0X1.3AP8 |
| 808 |
\& 0x13a0p\-4 0X13A0P\-4 |
| 809 |
.Ve |
| 810 |
.PP |
| 811 |
Octal floating point literals (with "0" prefix): |
| 812 |
.PP |
| 813 |
.Vb 3 |
| 814 |
\& 01.164p+8 01.164P+8 |
| 815 |
\& 01.164p8 01.164P8 |
| 816 |
\& 011640p\-4 011640P\-4 |
| 817 |
.Ve |
| 818 |
.PP |
| 819 |
Octal floating point literals (with "0o" prefix) (requires v5.34.0): |
| 820 |
.PP |
| 821 |
.Vb 3 |
| 822 |
\& 0o1.164p+8 0O1.164P+8 |
| 823 |
\& 0o1.164p8 0O1.164P8 |
| 824 |
\& 0o11640p\-4 0O11640P\-4 |
| 825 |
.Ve |
| 826 |
.PP |
| 827 |
Binary floating point literals: |
| 828 |
.PP |
| 829 |
.Vb 3 |
| 830 |
\& 0b1.0011101p+8 0B1.0011101P+8 |
| 831 |
\& 0b1.0011101p8 0B1.0011101P8 |
| 832 |
\& 0b10011101000p\-2 0B10011101000P\-2 |
| 833 |
.Ve |
| 834 |
.SH BUGS |
| 835 |
.IX Header "BUGS" |
| 836 |
Please report any bugs or feature requests to |
| 837 |
\&\f(CW\*(C`bug\-math\-bigint at rt.cpan.org\*(C'\fR, or through the web interface at |
| 838 |
<https://rt.cpan.org/Ticket/Create.html?Queue=Math\-BigInt> (requires login). |
| 839 |
We will be notified, and then you'll automatically be notified of progress on |
| 840 |
your bug as I make changes. |
| 841 |
.SH SUPPORT |
| 842 |
.IX Header "SUPPORT" |
| 843 |
You can find documentation for this module with the perldoc command. |
| 844 |
.PP |
| 845 |
.Vb 1 |
| 846 |
\& perldoc Math::BigInt |
| 847 |
.Ve |
| 848 |
.PP |
| 849 |
You can also look for information at: |
| 850 |
.IP \(bu 4 |
| 851 |
GitHub |
| 852 |
.Sp |
| 853 |
<https://github.com/pjacklam/p5\-Math\-BigInt> |
| 854 |
.IP \(bu 4 |
| 855 |
RT: CPAN's request tracker |
| 856 |
.Sp |
| 857 |
<https://rt.cpan.org/Dist/Display.html?Name=Math\-BigInt> |
| 858 |
.IP \(bu 4 |
| 859 |
MetaCPAN |
| 860 |
.Sp |
| 861 |
<https://metacpan.org/release/Math\-BigInt> |
| 862 |
.IP \(bu 4 |
| 863 |
CPAN Testers Matrix |
| 864 |
.Sp |
| 865 |
<http://matrix.cpantesters.org/?dist=Math\-BigInt> |
| 866 |
.SH LICENSE |
| 867 |
.IX Header "LICENSE" |
| 868 |
This program is free software; you may redistribute it and/or modify it under |
| 869 |
the same terms as Perl itself. |
| 870 |
.SH "SEE ALSO" |
| 871 |
.IX Header "SEE ALSO" |
| 872 |
Math::BigInt and Math::BigFloat as well as the backend libraries |
| 873 |
Math::BigInt::FastCalc, Math::BigInt::GMP, and Math::BigInt::Pari, |
| 874 |
Math::BigInt::GMPz, and Math::BigInt::BitVect. |
| 875 |
.PP |
| 876 |
The pragmas bigint, bigfloat, and bigrat might also be of interest. In |
| 877 |
addition there is the bignum pragma which does upgrading and downgrading. |
| 878 |
.SH AUTHORS |
| 879 |
.IX Header "AUTHORS" |
| 880 |
.IP \(bu 4 |
| 881 |
Tels <http://bloodgate.com/> 2001\-2009. |
| 882 |
.IP \(bu 4 |
| 883 |
Maintained by Peter John Acklam <[email protected]> 2011\- |