| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man v6.0.2 (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 |
.\" Required to disable full justification in groff 1.23.0. |
| 57 |
.if n .ds AD l |
| 58 |
.\" ======================================================================== |
| 59 |
.\" |
| 60 |
.IX Title "Math::BigRat 3pm" |
| 61 |
.TH Math::BigRat 3pm 2025-06-24 "perl v5.42.0" "Perl Programmers Reference Guide" |
| 62 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 63 |
.\" way too many mistakes in technical documents. |
| 64 |
.if n .ad l |
| 65 |
.nh |
| 66 |
.SH NAME |
| 67 |
Math::BigRat \- arbitrary size rational number math package |
| 68 |
.SH SYNOPSIS |
| 69 |
.IX Header "SYNOPSIS" |
| 70 |
.Vb 1 |
| 71 |
\& use Math::BigRat; |
| 72 |
\& |
| 73 |
\& # Generic constructor method (always returns a new object) |
| 74 |
\& |
| 75 |
\& $x = Math::BigRat\->new($str); # defaults to 0 |
| 76 |
\& $x = Math::BigRat\->new(\*(Aq256\*(Aq); # from decimal |
| 77 |
\& $x = Math::BigRat\->new(\*(Aq0256\*(Aq); # from decimal |
| 78 |
\& $x = Math::BigRat\->new(\*(Aq0xcafe\*(Aq); # from hexadecimal |
| 79 |
\& $x = Math::BigRat\->new(\*(Aq0x1.fap+7\*(Aq); # from hexadecimal |
| 80 |
\& $x = Math::BigRat\->new(\*(Aq0o377\*(Aq); # from octal |
| 81 |
\& $x = Math::BigRat\->new(\*(Aq0o1.35p+6\*(Aq); # from octal |
| 82 |
\& $x = Math::BigRat\->new(\*(Aq0b101\*(Aq); # from binary |
| 83 |
\& $x = Math::BigRat\->new(\*(Aq0b1.101p+3\*(Aq); # from binary |
| 84 |
\& |
| 85 |
\& # Specific constructor methods (no prefix needed; when used as |
| 86 |
\& # instance method, the value is assigned to the invocand) |
| 87 |
\& |
| 88 |
\& $x = Math::BigRat\->from_dec(\*(Aq234\*(Aq); # from decimal |
| 89 |
\& $x = Math::BigRat\->from_hex(\*(Aqcafe\*(Aq); # from hexadecimal |
| 90 |
\& $x = Math::BigRat\->from_hex(\*(Aq1.fap+7\*(Aq); # from hexadecimal |
| 91 |
\& $x = Math::BigRat\->from_oct(\*(Aq377\*(Aq); # from octal |
| 92 |
\& $x = Math::BigRat\->from_oct(\*(Aq1.35p+6\*(Aq); # from octal |
| 93 |
\& $x = Math::BigRat\->from_bin(\*(Aq1101\*(Aq); # from binary |
| 94 |
\& $x = Math::BigRat\->from_bin(\*(Aq1.101p+3\*(Aq); # from binary |
| 95 |
\& $x = Math::BigRat\->from_bytes($bytes); # from byte string |
| 96 |
\& $x = Math::BigRat\->from_base(\*(Aqwhy\*(Aq, 36); # from any base |
| 97 |
\& $x = Math::BigRat\->from_base_num([1, 0], 2); # from any base |
| 98 |
\& $x = Math::BigRat\->from_ieee754($b, $fmt); # from IEEE\-754 bytes |
| 99 |
\& $x = Math::BigRat\->bzero(); # create a +0 |
| 100 |
\& $x = Math::BigRat\->bone(); # create a +1 |
| 101 |
\& $x = Math::BigRat\->bone(\*(Aq\-\*(Aq); # create a \-1 |
| 102 |
\& $x = Math::BigRat\->binf(); # create a +inf |
| 103 |
\& $x = Math::BigRat\->binf(\*(Aq\-\*(Aq); # create a \-inf |
| 104 |
\& $x = Math::BigRat\->bnan(); # create a Not\-A\-Number |
| 105 |
\& $x = Math::BigRat\->bpi(); # returns pi |
| 106 |
\& |
| 107 |
\& $y = $x\->copy(); # make a copy (unlike $y = $x) |
| 108 |
\& $y = $x\->as_int(); # return as a Math::BigInt |
| 109 |
\& $y = $x\->as_float(); # return as a Math::BigFloat |
| 110 |
\& $y = $x\->as_rat(); # return as a Math::BigRat |
| 111 |
\& |
| 112 |
\& # Boolean methods (these don\*(Aqt modify the invocand) |
| 113 |
\& |
| 114 |
\& $x\->is_zero(); # true if $x is 0 |
| 115 |
\& $x\->is_one(); # true if $x is +1 |
| 116 |
\& $x\->is_one("+"); # true if $x is +1 |
| 117 |
\& $x\->is_one("\-"); # true if $x is \-1 |
| 118 |
\& $x\->is_inf(); # true if $x is +inf or \-inf |
| 119 |
\& $x\->is_inf("+"); # true if $x is +inf |
| 120 |
\& $x\->is_inf("\-"); # true if $x is \-inf |
| 121 |
\& $x\->is_nan(); # true if $x is NaN |
| 122 |
\& |
| 123 |
\& $x\->is_finite(); # true if \-inf < $x < inf |
| 124 |
\& $x\->is_positive(); # true if $x > 0 |
| 125 |
\& $x\->is_pos(); # true if $x > 0 |
| 126 |
\& $x\->is_negative(); # true if $x < 0 |
| 127 |
\& $x\->is_neg(); # true if $x < 0 |
| 128 |
\& $x\->is_non_positive() # true if $x <= 0 |
| 129 |
\& $x\->is_non_negative() # true if $x >= 0 |
| 130 |
\& |
| 131 |
\& $x\->is_odd(); # true if $x is odd |
| 132 |
\& $x\->is_even(); # true if $x is even |
| 133 |
\& $x\->is_int(); # true if $x is an integer |
| 134 |
\& |
| 135 |
\& # Comparison methods (these don\*(Aqt modify the invocand) |
| 136 |
\& |
| 137 |
\& $x\->bcmp($y); # compare numbers (undef, < 0, == 0, > 0) |
| 138 |
\& $x\->bacmp($y); # compare abs values (undef, < 0, == 0, > 0) |
| 139 |
\& $x\->beq($y); # true if $x == $y |
| 140 |
\& $x\->bne($y); # true if $x != $y |
| 141 |
\& $x\->blt($y); # true if $x < $y |
| 142 |
\& $x\->ble($y); # true if $x <= $y |
| 143 |
\& $x\->bgt($y); # true if $x > $y |
| 144 |
\& $x\->bge($y); # true if $x >= $y |
| 145 |
\& |
| 146 |
\& # Arithmetic methods (these modify the invocand) |
| 147 |
\& |
| 148 |
\& $x\->bneg(); # negation |
| 149 |
\& $x\->babs(); # absolute value |
| 150 |
\& $x\->bsgn(); # sign function (\-1, 0, 1, or NaN) |
| 151 |
\& $x\->bdigitsum(); # sum of decimal digits |
| 152 |
\& $x\->binc(); # increment $x by 1 |
| 153 |
\& $x\->bdec(); # decrement $x by 1 |
| 154 |
\& $x\->badd($y); # addition (add $y to $x) |
| 155 |
\& $x\->bsub($y); # subtraction (subtract $y from $x) |
| 156 |
\& $x\->bmul($y); # multiplication (multiply $x by $y) |
| 157 |
\& $x\->bmuladd($y, $z); # $x = $x * $y + $z |
| 158 |
\& $x\->bdiv($y); # division (floored) |
| 159 |
\& $x\->bmod($y); # modulus (x % y) |
| 160 |
\& $x\->bmodinv($mod); # modular multiplicative inverse |
| 161 |
\& $x\->bmodpow($y, $mod); # modular exponentiation (($x ** $y) % $mod) |
| 162 |
\& $x\->btdiv($y); # division (truncated), set $x to quotient |
| 163 |
\& $x\->btmod($y); # modulus (truncated) |
| 164 |
\& $x\->binv() # inverse (1/$x) |
| 165 |
\& $x\->bpow($y); # power of arguments (x ** y) |
| 166 |
\& $x\->blog(); # logarithm of $x to base e (Euler\*(Aqs number) |
| 167 |
\& $x\->blog($base); # logarithm of $x to base $base (e.g., base 2) |
| 168 |
\& $x\->bexp(); # calculate e ** $x where e is Euler\*(Aqs number |
| 169 |
\& $x\->bilog2(); # log2($x) rounded down to nearest int |
| 170 |
\& $x\->bilog10(); # log10($x) rounded down to nearest int |
| 171 |
\& $x\->bclog2(); # log2($x) rounded up to nearest int |
| 172 |
\& $x\->bclog10(); # log10($x) rounded up to nearest int |
| 173 |
\& $x\->bnok($y); # combinations (binomial coefficient n over k) |
| 174 |
\& $x\->bperm($y); # permutations |
| 175 |
\& $x\->buparrow($n, $y); # Knuth\*(Aqs up\-arrow notation |
| 176 |
\& $x\->bhyperop($n, $y); # n\*(Aqth hyperoprator |
| 177 |
\& $x\->backermann($y); # the Ackermann function |
| 178 |
\& $x\->bsin(); # sine |
| 179 |
\& $x\->bcos(); # cosine |
| 180 |
\& $x\->batan(); # inverse tangent |
| 181 |
\& $x\->batan2($y); # two\-argument inverse tangent |
| 182 |
\& $x\->bsqrt(); # calculate square root |
| 183 |
\& $x\->broot($y); # $y\*(Aqth root of $x (e.g. $y == 3 => cubic root) |
| 184 |
\& $x\->bfac(); # factorial of $x (1*2*3*4*..$x) |
| 185 |
\& $x\->bdfac(); # double factorial of $x ($x*($x\-2)*($x\-4)*...) |
| 186 |
\& $x\->btfac(); # triple factorial of $x ($x*($x\-3)*($x\-6)*...) |
| 187 |
\& $x\->bmfac($k); # $k\*(Aqth multi\-factorial of $x ($x*($x\-$k)*...) |
| 188 |
\& $x\->bfib($k); # $k\*(Aqth Fibonacci number |
| 189 |
\& $x\->blucas($k); # $k\*(Aqth Lucas number |
| 190 |
\& |
| 191 |
\& $x\->blsft($n); # left shift $n places in base 2 |
| 192 |
\& $x\->blsft($n, $b); # left shift $n places in base $b |
| 193 |
\& $x\->brsft($n); # right shift $n places in base 2 |
| 194 |
\& $x\->brsft($n, $b); # right shift $n places in base $b |
| 195 |
\& |
| 196 |
\& # Bitwise methods (these modify the invocand) |
| 197 |
\& |
| 198 |
\& $x\->bblsft($y); # bitwise left shift |
| 199 |
\& $x\->bbrsft($y); # bitwise right shift |
| 200 |
\& $x\->band($y); # bitwise and |
| 201 |
\& $x\->bior($y); # bitwise inclusive or |
| 202 |
\& $x\->bxor($y); # bitwise exclusive or |
| 203 |
\& $x\->bnot(); # bitwise not (two\*(Aqs complement) |
| 204 |
\& |
| 205 |
\& # Rounding methods (these modify the invocand) |
| 206 |
\& |
| 207 |
\& $x\->round($A, $P, $R); # round to accuracy or precision using |
| 208 |
\& # rounding mode $R |
| 209 |
\& $x\->bround($n); # accuracy: preserve $n digits |
| 210 |
\& $x\->bfround($n); # $n > 0: round to $nth digit left of dec. point |
| 211 |
\& # $n < 0: round to $nth digit right of dec. point |
| 212 |
\& $x\->bfloor(); # round towards minus infinity |
| 213 |
\& $x\->bceil(); # round towards plus infinity |
| 214 |
\& $x\->bint(); # round towards zero |
| 215 |
\& |
| 216 |
\& # Other mathematical methods (these don\*(Aqt modify the invocand) |
| 217 |
\& |
| 218 |
\& $x\->bgcd($y); # greatest common divisor |
| 219 |
\& $x\->blcm($y); # least common multiple |
| 220 |
\& |
| 221 |
\& # Object property methods (these don\*(Aqt modify the invocand) |
| 222 |
\& |
| 223 |
\& $x\->sign(); # the sign, either +, \- or NaN |
| 224 |
\& $x\->digit($n); # the nth digit, counting from the right |
| 225 |
\& $x\->digit(\-$n); # the nth digit, counting from the left |
| 226 |
\& $x\->digitsum(); # sum of decimal digits |
| 227 |
\& $x\->length(); # return number of digits in number |
| 228 |
\& $x\->mantissa(); # return (signed) mantissa as a Math::BigInt |
| 229 |
\& $x\->exponent(); # return exponent as a Math::BigInt |
| 230 |
\& $x\->parts(); # return (mantissa,exponent) as a Math::BigInt |
| 231 |
\& $x\->sparts(); # mantissa and exponent (as integers) |
| 232 |
\& $x\->nparts(); # mantissa and exponent (normalised) |
| 233 |
\& $x\->eparts(); # mantissa and exponent (engineering notation) |
| 234 |
\& $x\->dparts(); # integer and fraction part |
| 235 |
\& $x\->fparts(); # numerator and denominator |
| 236 |
\& $x\->numerator(); # numerator |
| 237 |
\& $x\->denominator(); # denominator |
| 238 |
\& |
| 239 |
\& # Conversion methods (these don\*(Aqt modify the invocand) |
| 240 |
\& |
| 241 |
\& $x\->bstr(); # decimal notation (possibly zero padded) |
| 242 |
\& $x\->bnstr(); # string in normalized notation |
| 243 |
\& $x\->bestr(); # string in engineering notation |
| 244 |
\& $x\->bdstr(); # string in decimal notation (no padding) |
| 245 |
\& $x\->bfstr(); # string in fractional notation |
| 246 |
\& |
| 247 |
\& $x\->to_hex(); # as signed hexadecimal string |
| 248 |
\& $x\->to_bin(); # as signed binary string |
| 249 |
\& $x\->to_oct(); # as signed octal string |
| 250 |
\& $x\->to_bytes(); # as byte string |
| 251 |
\& $x\->to_base($b); # as string in any base |
| 252 |
\& $x\->to_base_num($b); # as array of integers in any base |
| 253 |
\& $x\->to_ieee754($fmt); # to bytes encoded according to IEEE 754\-2008 |
| 254 |
\& |
| 255 |
\& $x\->as_hex(); # as signed hexadecimal string with "0x" prefix |
| 256 |
\& $x\->as_bin(); # as signed binary string with "0b" prefix |
| 257 |
\& $x\->as_oct(); # as signed octal string with "0" prefix |
| 258 |
\& |
| 259 |
\& # Other conversion methods (these don\*(Aqt modify the invocand) |
| 260 |
\& |
| 261 |
\& $x\->numify(); # return as scalar (might overflow or underflow) |
| 262 |
.Ve |
| 263 |
.SH DESCRIPTION |
| 264 |
.IX Header "DESCRIPTION" |
| 265 |
Math::BigRat complements Math::BigInt and Math::BigFloat by providing |
| 266 |
support for arbitrary big rational numbers. |
| 267 |
.SS "Math Library" |
| 268 |
.IX Subsection "Math Library" |
| 269 |
You can change the underlying module that does the low\-level |
| 270 |
math operations by using: |
| 271 |
.PP |
| 272 |
.Vb 1 |
| 273 |
\& use Math::BigRat try => \*(AqGMP\*(Aq; |
| 274 |
.Ve |
| 275 |
.PP |
| 276 |
Note: This needs Math::BigInt::GMP installed. |
| 277 |
.PP |
| 278 |
The following would first try to find Math::BigInt::Foo, then |
| 279 |
Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc: |
| 280 |
.PP |
| 281 |
.Vb 1 |
| 282 |
\& use Math::BigRat try => \*(AqFoo,Math::BigInt::Bar\*(Aq; |
| 283 |
.Ve |
| 284 |
.PP |
| 285 |
If you want to get warned when the fallback occurs, replace "try" with "lib": |
| 286 |
.PP |
| 287 |
.Vb 1 |
| 288 |
\& use Math::BigRat lib => \*(AqFoo,Math::BigInt::Bar\*(Aq; |
| 289 |
.Ve |
| 290 |
.PP |
| 291 |
If you want the code to die instead, replace "try" with "only": |
| 292 |
.PP |
| 293 |
.Vb 1 |
| 294 |
\& use Math::BigRat only => \*(AqFoo,Math::BigInt::Bar\*(Aq; |
| 295 |
.Ve |
| 296 |
.SH METHODS |
| 297 |
.IX Header "METHODS" |
| 298 |
Any methods not listed here are derived from Math::BigFloat (or |
| 299 |
Math::BigInt), so make sure you check these two modules for further |
| 300 |
information. |
| 301 |
.IP \fBnew()\fR 4 |
| 302 |
.IX Item "new()" |
| 303 |
.Vb 1 |
| 304 |
\& $x = Math::BigRat\->new(\*(Aq1/3\*(Aq); |
| 305 |
.Ve |
| 306 |
.Sp |
| 307 |
Create a new Math::BigRat object. Input can come in various forms: |
| 308 |
.Sp |
| 309 |
.Vb 9 |
| 310 |
\& $x = Math::BigRat\->new(123); # scalars |
| 311 |
\& $x = Math::BigRat\->new(\*(Aqinf\*(Aq); # infinity |
| 312 |
\& $x = Math::BigRat\->new(\*(Aq123.3\*(Aq); # float |
| 313 |
\& $x = Math::BigRat\->new(\*(Aq1/3\*(Aq); # simple string |
| 314 |
\& $x = Math::BigRat\->new(\*(Aq1 / 3\*(Aq); # spaced |
| 315 |
\& $x = Math::BigRat\->new(\*(Aq1 / 0.1\*(Aq); # w/ floats |
| 316 |
\& $x = Math::BigRat\->new(Math::BigInt\->new(3)); # BigInt |
| 317 |
\& $x = Math::BigRat\->new(Math::BigFloat\->new(\*(Aq3.1\*(Aq)); # BigFloat |
| 318 |
\& $x = Math::BigRat\->new(Math::BigInt::Lite\->new(\*(Aq2\*(Aq)); # BigLite |
| 319 |
\& |
| 320 |
\& # You can also give D and N as different objects: |
| 321 |
\& $x = Math::BigRat\->new( |
| 322 |
\& Math::BigInt\->new(\-123), |
| 323 |
\& Math::BigInt\->new(7), |
| 324 |
\& ); # => \-123/7 |
| 325 |
.Ve |
| 326 |
.IP \fBfrom_dec()\fR 4 |
| 327 |
.IX Item "from_dec()" |
| 328 |
.Vb 1 |
| 329 |
\& my $h = Math::BigRat\->from_dec("1.2"); |
| 330 |
.Ve |
| 331 |
.Sp |
| 332 |
Create a BigRat from a decimal number in string form. It is equivalent to |
| 333 |
"\fBnew()\fR", but does not accept anything but strings representing finite, |
| 334 |
decimal numbers. |
| 335 |
.IP \fBfrom_hex()\fR 4 |
| 336 |
.IX Item "from_hex()" |
| 337 |
.Vb 1 |
| 338 |
\& my $h = Math::BigRat\->from_hex("0x10"); |
| 339 |
.Ve |
| 340 |
.Sp |
| 341 |
Create a BigRat from a hexadecimal number in string form. |
| 342 |
.IP \fBfrom_oct()\fR 4 |
| 343 |
.IX Item "from_oct()" |
| 344 |
.Vb 1 |
| 345 |
\& my $o = Math::BigRat\->from_oct("020"); |
| 346 |
.Ve |
| 347 |
.Sp |
| 348 |
Create a BigRat from an octal number in string form. |
| 349 |
.IP \fBfrom_bin()\fR 4 |
| 350 |
.IX Item "from_bin()" |
| 351 |
.Vb 1 |
| 352 |
\& my $b = Math::BigRat\->from_bin("0b10000000"); |
| 353 |
.Ve |
| 354 |
.Sp |
| 355 |
Create a BigRat from an binary number in string form. |
| 356 |
.IP \fBfrom_bytes()\fR 4 |
| 357 |
.IX Item "from_bytes()" |
| 358 |
.Vb 1 |
| 359 |
\& $x = Math::BigRat\->from_bytes("\exf3\ex6b"); # $x = 62315 |
| 360 |
.Ve |
| 361 |
.Sp |
| 362 |
Interpret the input as a byte string, assuming big endian byte order. The |
| 363 |
output is always a non\-negative, finite integer. |
| 364 |
.Sp |
| 365 |
See "\fBfrom_bytes()\fR" in Math::BigInt. |
| 366 |
.IP \fBfrom_ieee754()\fR 4 |
| 367 |
.IX Item "from_ieee754()" |
| 368 |
.Vb 3 |
| 369 |
\& # set $x to 13176795/4194304, the closest value to pi that can be |
| 370 |
\& # represented in the binary32 (single) format |
| 371 |
\& $x = Math::BigRat \-> from_ieee754("40490fdb", "binary32"); |
| 372 |
.Ve |
| 373 |
.Sp |
| 374 |
Interpret the input as a value encoded as described in IEEE754\-2008. |
| 375 |
.Sp |
| 376 |
See "\fBfrom_ieee754()\fR" in Math::BigFloat. |
| 377 |
.IP \fBfrom_base()\fR 4 |
| 378 |
.IX Item "from_base()" |
| 379 |
See "\fBfrom_base()\fR" in Math::BigInt. |
| 380 |
.IP \fBbzero()\fR 4 |
| 381 |
.IX Item "bzero()" |
| 382 |
.Vb 1 |
| 383 |
\& $x = Math::BigRat\->bzero(); |
| 384 |
.Ve |
| 385 |
.Sp |
| 386 |
Creates a new BigRat object representing zero. |
| 387 |
If used on an object, it will set it to zero: |
| 388 |
.Sp |
| 389 |
.Vb 1 |
| 390 |
\& $x\->bzero(); |
| 391 |
.Ve |
| 392 |
.IP \fBbone()\fR 4 |
| 393 |
.IX Item "bone()" |
| 394 |
.Vb 1 |
| 395 |
\& $x = Math::BigRat\->bone($sign); |
| 396 |
.Ve |
| 397 |
.Sp |
| 398 |
Creates a new BigRat object representing one. The optional argument is |
| 399 |
either \*(Aq\-\*(Aq or \*(Aq+\*(Aq, indicating whether you want one or minus one. |
| 400 |
If used on an object, it will set it to one: |
| 401 |
.Sp |
| 402 |
.Vb 2 |
| 403 |
\& $x\->bone(); # +1 |
| 404 |
\& $x\->bone(\*(Aq\-\*(Aq); # \-1 |
| 405 |
.Ve |
| 406 |
.IP \fBbinf()\fR 4 |
| 407 |
.IX Item "binf()" |
| 408 |
.Vb 1 |
| 409 |
\& $x = Math::BigRat\->binf($sign); |
| 410 |
.Ve |
| 411 |
.Sp |
| 412 |
Creates a new BigRat object representing infinity. The optional argument is |
| 413 |
either \*(Aq\-\*(Aq or \*(Aq+\*(Aq, indicating whether you want infinity or minus infinity. |
| 414 |
If used on an object, it will set it to infinity: |
| 415 |
.Sp |
| 416 |
.Vb 2 |
| 417 |
\& $x\->binf(); |
| 418 |
\& $x\->binf(\*(Aq\-\*(Aq); |
| 419 |
.Ve |
| 420 |
.IP \fBbnan()\fR 4 |
| 421 |
.IX Item "bnan()" |
| 422 |
.Vb 1 |
| 423 |
\& $x = Math::BigRat\->bnan(); |
| 424 |
.Ve |
| 425 |
.Sp |
| 426 |
Creates a new BigRat object representing NaN (Not A Number). |
| 427 |
If used on an object, it will set it to NaN: |
| 428 |
.Sp |
| 429 |
.Vb 1 |
| 430 |
\& $x\->bnan(); |
| 431 |
.Ve |
| 432 |
.IP \fBbpi()\fR 4 |
| 433 |
.IX Item "bpi()" |
| 434 |
.Vb 2 |
| 435 |
\& $x = Math::BigRat \-> bpi(); # default accuracy |
| 436 |
\& $x = Math::BigRat \-> bpi(7); # specified accuracy |
| 437 |
.Ve |
| 438 |
.Sp |
| 439 |
Returns a rational approximation of PI accurate to the specified accuracy or |
| 440 |
the default accuracy if no accuracy is specified. If called as an instance |
| 441 |
method, the value is assigned to the invocand. |
| 442 |
.Sp |
| 443 |
.Vb 3 |
| 444 |
\& $x = Math::BigRat \-> bpi(1); # returns "3" |
| 445 |
\& $x = Math::BigRat \-> bpi(3); # returns "22/7" |
| 446 |
\& $x = Math::BigRat \-> bpi(7); # returns "355/113" |
| 447 |
.Ve |
| 448 |
.IP \fBcopy()\fR 4 |
| 449 |
.IX Item "copy()" |
| 450 |
.Vb 1 |
| 451 |
\& my $z = $x\->copy(); |
| 452 |
.Ve |
| 453 |
.Sp |
| 454 |
Makes a deep copy of the object. |
| 455 |
.Sp |
| 456 |
Please see the documentation in Math::BigInt for further details. |
| 457 |
.IP \fBas_int()\fR 4 |
| 458 |
.IX Item "as_int()" |
| 459 |
.Vb 1 |
| 460 |
\& $y = $x \-> as_int(); # $y is a Math::BigInt |
| 461 |
.Ve |
| 462 |
.Sp |
| 463 |
Returns \f(CW$x\fR as a Math::BigInt object regardless of upgrading and downgrading. If |
| 464 |
\&\f(CW$x\fR is finite, but not an integer, \f(CW$x\fR is truncated. |
| 465 |
.IP \fBas_rat()\fR 4 |
| 466 |
.IX Item "as_rat()" |
| 467 |
.Vb 1 |
| 468 |
\& $y = $x \-> as_rat(); # $y is a Math::BigRat |
| 469 |
.Ve |
| 470 |
.Sp |
| 471 |
Returns \f(CW$x\fR a Math::BigRat object regardless of upgrading and downgrading. The |
| 472 |
invocand is not modified. |
| 473 |
.IP \fBas_float()\fR 4 |
| 474 |
.IX Item "as_float()" |
| 475 |
.Vb 2 |
| 476 |
\& $x = Math::BigRat\->new(\*(Aq13/7\*(Aq); |
| 477 |
\& print $x\->as_float(), "\en"; # \*(Aq1\*(Aq |
| 478 |
\& |
| 479 |
\& $x = Math::BigRat\->new(\*(Aq2/3\*(Aq); |
| 480 |
\& print $x\->as_float(5), "\en"; # \*(Aq0.66667\*(Aq |
| 481 |
.Ve |
| 482 |
.Sp |
| 483 |
Returns a copy of the object as Math::BigFloat object regardless of upgrading |
| 484 |
and downgrading, preserving the accuracy as wanted, or the default of 40 |
| 485 |
digits. |
| 486 |
.IP \fBbround()\fR/\fBround()\fR/\fBbfround()\fR 4 |
| 487 |
.IX Item "bround()/round()/bfround()" |
| 488 |
Are not yet implemented. |
| 489 |
.IP \fBis_zero()\fR 4 |
| 490 |
.IX Item "is_zero()" |
| 491 |
.Vb 1 |
| 492 |
\& print "$x is 0\en" if $x\->is_zero(); |
| 493 |
.Ve |
| 494 |
.Sp |
| 495 |
Return true if \f(CW$x\fR is exactly zero, otherwise false. |
| 496 |
.IP \fBis_one()\fR 4 |
| 497 |
.IX Item "is_one()" |
| 498 |
.Vb 1 |
| 499 |
\& print "$x is 1\en" if $x\->is_one(); |
| 500 |
.Ve |
| 501 |
.Sp |
| 502 |
Return true if \f(CW$x\fR is exactly one, otherwise false. |
| 503 |
.IP \fBis_finite()\fR 4 |
| 504 |
.IX Item "is_finite()" |
| 505 |
.Vb 1 |
| 506 |
\& $x\->is_finite(); # true if $x is not +inf, \-inf or NaN |
| 507 |
.Ve |
| 508 |
.Sp |
| 509 |
Returns true if the invocand is a finite number, i.e., it is neither +inf, |
| 510 |
\&\-inf, nor NaN. |
| 511 |
.IP \fBis_positive()\fR 4 |
| 512 |
.IX Item "is_positive()" |
| 513 |
.PD 0 |
| 514 |
.IP \fBis_pos()\fR 4 |
| 515 |
.IX Item "is_pos()" |
| 516 |
.PD |
| 517 |
.Vb 1 |
| 518 |
\& print "$x is >= 0\en" if $x\->is_positive(); |
| 519 |
.Ve |
| 520 |
.Sp |
| 521 |
Return true if \f(CW$x\fR is positive (greater than or equal to zero), otherwise |
| 522 |
false. Please note that \*(Aq+inf\*(Aq is also positive, while \*(AqNaN\*(Aq and \*(Aq\-inf\*(Aq aren\*(Aqt. |
| 523 |
.Sp |
| 524 |
"\fBis_positive()\fR" is an alias for "\fBis_pos()\fR". |
| 525 |
.IP \fBis_negative()\fR 4 |
| 526 |
.IX Item "is_negative()" |
| 527 |
.PD 0 |
| 528 |
.IP \fBis_neg()\fR 4 |
| 529 |
.IX Item "is_neg()" |
| 530 |
.PD |
| 531 |
.Vb 1 |
| 532 |
\& print "$x is < 0\en" if $x\->is_negative(); |
| 533 |
.Ve |
| 534 |
.Sp |
| 535 |
Return true if \f(CW$x\fR is negative (smaller than zero), otherwise false. Please |
| 536 |
note that \*(Aq\-inf\*(Aq is also negative, while \*(AqNaN\*(Aq and \*(Aq+inf\*(Aq aren\*(Aqt. |
| 537 |
.Sp |
| 538 |
"\fBis_negative()\fR" is an alias for "\fBis_neg()\fR". |
| 539 |
.IP \fBis_odd()\fR 4 |
| 540 |
.IX Item "is_odd()" |
| 541 |
.Vb 1 |
| 542 |
\& print "$x is odd\en" if $x\->is_odd(); |
| 543 |
.Ve |
| 544 |
.Sp |
| 545 |
Return true if \f(CW$x\fR is odd, otherwise false. |
| 546 |
.IP \fBis_even()\fR 4 |
| 547 |
.IX Item "is_even()" |
| 548 |
.Vb 1 |
| 549 |
\& print "$x is even\en" if $x\->is_even(); |
| 550 |
.Ve |
| 551 |
.Sp |
| 552 |
Return true if \f(CW$x\fR is even, otherwise false. |
| 553 |
.IP \fBis_int()\fR 4 |
| 554 |
.IX Item "is_int()" |
| 555 |
.Vb 1 |
| 556 |
\& print "$x is an integer\en" if $x\->is_int(); |
| 557 |
.Ve |
| 558 |
.Sp |
| 559 |
Return true if \f(CW$x\fR has a denominator of 1 (e.g. no fraction parts), otherwise |
| 560 |
false. Please note that \*(Aq\-inf\*(Aq, \*(Aqinf\*(Aq and \*(AqNaN\*(Aq aren\*(Aqt integer. |
| 561 |
.SS "Comparison methods" |
| 562 |
.IX Subsection "Comparison methods" |
| 563 |
None of these methods modify the invocand object. Note that a \f(CW\*(C`NaN\*(C'\fR is neither |
| 564 |
less than, greater than, or equal to anything else, even a \f(CW\*(C`NaN\*(C'\fR. |
| 565 |
.IP \fBbcmp()\fR 4 |
| 566 |
.IX Item "bcmp()" |
| 567 |
.Vb 1 |
| 568 |
\& $x\->bcmp($y); |
| 569 |
.Ve |
| 570 |
.Sp |
| 571 |
Compares \f(CW$x\fR with \f(CW$y\fR and takes the sign into account. |
| 572 |
Returns \-1, 0, 1 or undef. |
| 573 |
.IP \fBbacmp()\fR 4 |
| 574 |
.IX Item "bacmp()" |
| 575 |
.Vb 1 |
| 576 |
\& $x\->bacmp($y); |
| 577 |
.Ve |
| 578 |
.Sp |
| 579 |
Compares \f(CW$x\fR with \f(CW$y\fR while ignoring their sign. Returns \-1, 0, 1 or undef. |
| 580 |
.IP \fBbeq()\fR 4 |
| 581 |
.IX Item "beq()" |
| 582 |
.Vb 1 |
| 583 |
\& $x \-> beq($y); |
| 584 |
.Ve |
| 585 |
.Sp |
| 586 |
Returns true if and only if \f(CW$x\fR is equal to \f(CW$y\fR, and false otherwise. |
| 587 |
.IP \fBbne()\fR 4 |
| 588 |
.IX Item "bne()" |
| 589 |
.Vb 1 |
| 590 |
\& $x \-> bne($y); |
| 591 |
.Ve |
| 592 |
.Sp |
| 593 |
Returns true if and only if \f(CW$x\fR is not equal to \f(CW$y\fR, and false otherwise. |
| 594 |
.IP \fBblt()\fR 4 |
| 595 |
.IX Item "blt()" |
| 596 |
.Vb 1 |
| 597 |
\& $x \-> blt($y); |
| 598 |
.Ve |
| 599 |
.Sp |
| 600 |
Returns true if and only if \f(CW$x\fR is equal to \f(CW$y\fR, and false otherwise. |
| 601 |
.IP \fBble()\fR 4 |
| 602 |
.IX Item "ble()" |
| 603 |
.Vb 1 |
| 604 |
\& $x \-> ble($y); |
| 605 |
.Ve |
| 606 |
.Sp |
| 607 |
Returns true if and only if \f(CW$x\fR is less than or equal to \f(CW$y\fR, and false |
| 608 |
otherwise. |
| 609 |
.IP \fBbgt()\fR 4 |
| 610 |
.IX Item "bgt()" |
| 611 |
.Vb 1 |
| 612 |
\& $x \-> bgt($y); |
| 613 |
.Ve |
| 614 |
.Sp |
| 615 |
Returns true if and only if \f(CW$x\fR is greater than \f(CW$y\fR, and false otherwise. |
| 616 |
.IP \fBbge()\fR 4 |
| 617 |
.IX Item "bge()" |
| 618 |
.Vb 1 |
| 619 |
\& $x \-> bge($y); |
| 620 |
.Ve |
| 621 |
.Sp |
| 622 |
Returns true if and only if \f(CW$x\fR is greater than or equal to \f(CW$y\fR, and false |
| 623 |
otherwise. |
| 624 |
.IP \fBblsft()\fR/\fBbrsft()\fR 4 |
| 625 |
.IX Item "blsft()/brsft()" |
| 626 |
Used to shift numbers left/right. |
| 627 |
.Sp |
| 628 |
Please see the documentation in Math::BigInt for further details. |
| 629 |
.IP \fBbneg()\fR 4 |
| 630 |
.IX Item "bneg()" |
| 631 |
.Vb 1 |
| 632 |
\& $x\->bneg(); |
| 633 |
.Ve |
| 634 |
.Sp |
| 635 |
Used to negate the object in\-place. |
| 636 |
.IP \fBbnorm()\fR 4 |
| 637 |
.IX Item "bnorm()" |
| 638 |
.Vb 1 |
| 639 |
\& $x\->bnorm(); |
| 640 |
.Ve |
| 641 |
.Sp |
| 642 |
Reduce the number to the shortest form. This routine is called |
| 643 |
automatically whenever it is needed. |
| 644 |
.IP \fBbinc()\fR 4 |
| 645 |
.IX Item "binc()" |
| 646 |
.Vb 1 |
| 647 |
\& $x\->binc(); |
| 648 |
.Ve |
| 649 |
.Sp |
| 650 |
Increments \f(CW$x\fR by 1 and returns the result. |
| 651 |
.IP \fBbdec()\fR 4 |
| 652 |
.IX Item "bdec()" |
| 653 |
.Vb 1 |
| 654 |
\& $x\->bdec(); |
| 655 |
.Ve |
| 656 |
.Sp |
| 657 |
Decrements \f(CW$x\fR by 1 and returns the result. |
| 658 |
.IP \fBbadd()\fR 4 |
| 659 |
.IX Item "badd()" |
| 660 |
.Vb 1 |
| 661 |
\& $x\->badd($y); |
| 662 |
.Ve |
| 663 |
.Sp |
| 664 |
Adds \f(CW$y\fR to \f(CW$x\fR and returns the result. |
| 665 |
.IP \fBbsub()\fR 4 |
| 666 |
.IX Item "bsub()" |
| 667 |
.Vb 1 |
| 668 |
\& $x\->bsub($y); |
| 669 |
.Ve |
| 670 |
.Sp |
| 671 |
Subtracts \f(CW$y\fR from \f(CW$x\fR and returns the result. |
| 672 |
.IP \fBbmul()\fR 4 |
| 673 |
.IX Item "bmul()" |
| 674 |
.Vb 1 |
| 675 |
\& $x\->bmul($y); |
| 676 |
.Ve |
| 677 |
.Sp |
| 678 |
Multiplies \f(CW$y\fR to \f(CW$x\fR and returns the result. |
| 679 |
.IP \fBbdiv()\fR 4 |
| 680 |
.IX Item "bdiv()" |
| 681 |
.Vb 2 |
| 682 |
\& $q = $x\->bdiv($y); |
| 683 |
\& ($q, $r) = $x\->bdiv($y); |
| 684 |
.Ve |
| 685 |
.Sp |
| 686 |
In scalar context, divides \f(CW$x\fR by \f(CW$y\fR and returns the result. In list context, |
| 687 |
does floored division (F\-division), returning an integer \f(CW$q\fR and a remainder \f(CW$r\fR |
| 688 |
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 |
| 689 |
by \f(CW\*(C`$x\->bmod($y)\*(C'\fR. |
| 690 |
.IP \fBbmod()\fR 4 |
| 691 |
.IX Item "bmod()" |
| 692 |
.Vb 1 |
| 693 |
\& $x\->bmod($y); |
| 694 |
.Ve |
| 695 |
.Sp |
| 696 |
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 |
| 697 |
result is identical to the remainder after floored division (F\-division). If, |
| 698 |
in addition, both \f(CW$x\fR and \f(CW$y\fR are integers, the result is identical to the result |
| 699 |
from Perl\*(Aqs % operator. |
| 700 |
.IP \fBbinv()\fR 4 |
| 701 |
.IX Item "binv()" |
| 702 |
.Vb 1 |
| 703 |
\& $x\->binv(); |
| 704 |
.Ve |
| 705 |
.Sp |
| 706 |
Inverse of \f(CW$x\fR. |
| 707 |
.IP \fBbsqrt()\fR 4 |
| 708 |
.IX Item "bsqrt()" |
| 709 |
.Vb 1 |
| 710 |
\& $x\->bsqrt(); |
| 711 |
.Ve |
| 712 |
.Sp |
| 713 |
Calculate the square root of \f(CW$x\fR. |
| 714 |
.IP \fBbpow()\fR 4 |
| 715 |
.IX Item "bpow()" |
| 716 |
.Vb 1 |
| 717 |
\& $x\->bpow($y); |
| 718 |
.Ve |
| 719 |
.Sp |
| 720 |
Compute \f(CW$x\fR ** \f(CW$y\fR. |
| 721 |
.Sp |
| 722 |
Please see the documentation in Math::BigInt for further details. |
| 723 |
.IP \fBbroot()\fR 4 |
| 724 |
.IX Item "broot()" |
| 725 |
.Vb 1 |
| 726 |
\& $x\->broot($n); |
| 727 |
.Ve |
| 728 |
.Sp |
| 729 |
Calculate the N\*(Aqth root of \f(CW$x\fR. |
| 730 |
.IP \fBbmodpow()\fR 4 |
| 731 |
.IX Item "bmodpow()" |
| 732 |
.Vb 2 |
| 733 |
\& $num\->bmodpow($exp,$mod); # modular exponentiation |
| 734 |
\& # ($num**$exp % $mod) |
| 735 |
.Ve |
| 736 |
.Sp |
| 737 |
Returns the value of \f(CW$num\fR taken to the power \f(CW$exp\fR in the modulus |
| 738 |
\&\f(CW$mod\fR using binary exponentiation. \f(CW\*(C`bmodpow\*(C'\fR is far superior to |
| 739 |
writing |
| 740 |
.Sp |
| 741 |
.Vb 1 |
| 742 |
\& $num ** $exp % $mod |
| 743 |
.Ve |
| 744 |
.Sp |
| 745 |
because it is much faster \- it reduces internal variables into |
| 746 |
the modulus whenever possible, so it operates on smaller numbers. |
| 747 |
.Sp |
| 748 |
\&\f(CW\*(C`bmodpow\*(C'\fR also supports negative exponents. |
| 749 |
.Sp |
| 750 |
.Vb 1 |
| 751 |
\& bmodpow($num, \-1, $mod) |
| 752 |
.Ve |
| 753 |
.Sp |
| 754 |
is exactly equivalent to |
| 755 |
.Sp |
| 756 |
.Vb 1 |
| 757 |
\& bmodinv($num, $mod) |
| 758 |
.Ve |
| 759 |
.IP \fBbmodinv()\fR 4 |
| 760 |
.IX Item "bmodinv()" |
| 761 |
.Vb 1 |
| 762 |
\& $x\->bmodinv($mod); # modular multiplicative inverse |
| 763 |
.Ve |
| 764 |
.Sp |
| 765 |
Returns the multiplicative inverse of \f(CW$x\fR modulo \f(CW$mod\fR. If |
| 766 |
.Sp |
| 767 |
.Vb 1 |
| 768 |
\& $y = $x \-> copy() \-> bmodinv($mod) |
| 769 |
.Ve |
| 770 |
.Sp |
| 771 |
then \f(CW$y\fR is the number closest to zero, and with the same sign as \f(CW$mod\fR, |
| 772 |
satisfying |
| 773 |
.Sp |
| 774 |
.Vb 1 |
| 775 |
\& ($x * $y) % $mod = 1 % $mod |
| 776 |
.Ve |
| 777 |
.Sp |
| 778 |
If \f(CW$x\fR and \f(CW$y\fR are non\-zero, they must be relative primes, i.e., |
| 779 |
\&\f(CW\*(C`bgcd($y, $mod)==1\*(C'\fR. \*(Aq\f(CW\*(C`NaN\*(C'\fR\*(Aq is returned when no modular multiplicative |
| 780 |
inverse exists. |
| 781 |
.IP \fBblog()\fR 4 |
| 782 |
.IX Item "blog()" |
| 783 |
.Vb 1 |
| 784 |
\& $x\->blog($base, $accuracy); # logarithm of x to the base $base |
| 785 |
.Ve |
| 786 |
.Sp |
| 787 |
If \f(CW$base\fR is not defined, Euler\*(Aqs number (e) is used: |
| 788 |
.Sp |
| 789 |
.Vb 1 |
| 790 |
\& print $x\->blog(undef, 100); # log(x) to 100 digits |
| 791 |
.Ve |
| 792 |
.IP \fBbexp()\fR 4 |
| 793 |
.IX Item "bexp()" |
| 794 |
.Vb 1 |
| 795 |
\& $x\->bexp($accuracy); # calculate e ** X |
| 796 |
.Ve |
| 797 |
.Sp |
| 798 |
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 |
| 799 |
Euler\*(Aqs number. |
| 800 |
.Sp |
| 801 |
This method was added in v0.20 of Math::BigRat (May 2007). |
| 802 |
.Sp |
| 803 |
See also "\fBblog()\fR". |
| 804 |
.IP \fBbnok()\fR 4 |
| 805 |
.IX Item "bnok()" |
| 806 |
See "\fBbnok()\fR" in Math::BigInt. |
| 807 |
.IP \fBbperm()\fR 4 |
| 808 |
.IX Item "bperm()" |
| 809 |
See "\fBbperm()\fR" in Math::BigInt. |
| 810 |
.IP \fBbfac()\fR 4 |
| 811 |
.IX Item "bfac()" |
| 812 |
.Vb 1 |
| 813 |
\& $x\->bfac(); |
| 814 |
.Ve |
| 815 |
.Sp |
| 816 |
Calculates the factorial of \f(CW$x\fR. For instance: |
| 817 |
.Sp |
| 818 |
.Vb 2 |
| 819 |
\& print Math::BigRat\->new(\*(Aq3/1\*(Aq)\->bfac(), "\en"; # 1*2*3 |
| 820 |
\& print Math::BigRat\->new(\*(Aq5/1\*(Aq)\->bfac(), "\en"; # 1*2*3*4*5 |
| 821 |
.Ve |
| 822 |
.Sp |
| 823 |
Works currently only for integers. |
| 824 |
.IP \fBband()\fR 4 |
| 825 |
.IX Item "band()" |
| 826 |
.Vb 1 |
| 827 |
\& $x\->band($y); # bitwise and |
| 828 |
.Ve |
| 829 |
.IP \fBbior()\fR 4 |
| 830 |
.IX Item "bior()" |
| 831 |
.Vb 1 |
| 832 |
\& $x\->bior($y); # bitwise inclusive or |
| 833 |
.Ve |
| 834 |
.IP \fBbxor()\fR 4 |
| 835 |
.IX Item "bxor()" |
| 836 |
.Vb 1 |
| 837 |
\& $x\->bxor($y); # bitwise exclusive or |
| 838 |
.Ve |
| 839 |
.IP \fBbnot()\fR 4 |
| 840 |
.IX Item "bnot()" |
| 841 |
.Vb 1 |
| 842 |
\& $x\->bnot(); # bitwise not (two\*(Aqs complement) |
| 843 |
.Ve |
| 844 |
.IP \fBbfloor()\fR 4 |
| 845 |
.IX Item "bfloor()" |
| 846 |
.Vb 1 |
| 847 |
\& $x\->bfloor(); |
| 848 |
.Ve |
| 849 |
.Sp |
| 850 |
Round \f(CW$x\fR towards minus infinity, i.e., set \f(CW$x\fR to the largest integer less than |
| 851 |
or equal to \f(CW$x\fR. |
| 852 |
.IP \fBbceil()\fR 4 |
| 853 |
.IX Item "bceil()" |
| 854 |
.Vb 1 |
| 855 |
\& $x\->bceil(); |
| 856 |
.Ve |
| 857 |
.Sp |
| 858 |
Round \f(CW$x\fR towards plus infinity, i.e., set \f(CW$x\fR to the smallest integer greater |
| 859 |
than or equal to \f(CW$x\fR. |
| 860 |
.IP \fBbint()\fR 4 |
| 861 |
.IX Item "bint()" |
| 862 |
.Vb 1 |
| 863 |
\& $x\->bint(); |
| 864 |
.Ve |
| 865 |
.Sp |
| 866 |
Round \f(CW$x\fR towards zero. |
| 867 |
.IP \fBbgcd()\fR 4 |
| 868 |
.IX Item "bgcd()" |
| 869 |
.Vb 2 |
| 870 |
\& $x \-> bgcd($y); # GCD of $x and $y |
| 871 |
\& $x \-> bgcd($y, $z, ...); # GCD of $x, $y, $z, ... |
| 872 |
.Ve |
| 873 |
.Sp |
| 874 |
Returns the greatest common divisor (GCD), which is the number with the largest |
| 875 |
absolute value such that \f(CW$x\fR/$gcd, \f(CW$y\fR/$gcd, ... is an integer. For example, when |
| 876 |
the operands are 4/5 and 6/5, the GCD is 2/5. This is a generalisation of the |
| 877 |
ordinary GCD for integers. See "\fBgcd()\fR" in Math::BigInt. |
| 878 |
.IP \fBdigit()\fR 4 |
| 879 |
.IX Item "digit()" |
| 880 |
.Vb 2 |
| 881 |
\& print Math::BigRat\->new(\*(Aq123/1\*(Aq)\->digit(1); # 1 |
| 882 |
\& print Math::BigRat\->new(\*(Aq123/1\*(Aq)\->digit(\-1); # 3 |
| 883 |
.Ve |
| 884 |
.Sp |
| 885 |
Return the N\*(Aqths digit from X when X is an integer value. |
| 886 |
.IP \fBlength()\fR 4 |
| 887 |
.IX Item "length()" |
| 888 |
.Vb 1 |
| 889 |
\& $len = $x\->length(); |
| 890 |
.Ve |
| 891 |
.Sp |
| 892 |
Return the length of \f(CW$x\fR in digits for integer values. |
| 893 |
.IP \fBparts()\fR 4 |
| 894 |
.IX Item "parts()" |
| 895 |
.Vb 1 |
| 896 |
\& ($n, $d) = $x\->parts(); |
| 897 |
.Ve |
| 898 |
.Sp |
| 899 |
Return a list consisting of (signed) numerator and (unsigned) denominator as |
| 900 |
BigInts. |
| 901 |
.IP \fBdparts()\fR 4 |
| 902 |
.IX Item "dparts()" |
| 903 |
Returns the integer part and the fraction part. |
| 904 |
.IP \fBfparts()\fR 4 |
| 905 |
.IX Item "fparts()" |
| 906 |
Returns the smallest possible numerator and denominator so that the numerator |
| 907 |
divided by the denominator gives back the original value. For finite numbers, |
| 908 |
both values are integers. Mnemonic: fraction. |
| 909 |
.IP \fBnumerator()\fR 4 |
| 910 |
.IX Item "numerator()" |
| 911 |
.Vb 1 |
| 912 |
\& $n = $x\->numerator(); |
| 913 |
.Ve |
| 914 |
.Sp |
| 915 |
Returns a copy of the numerator (the part above the line) as signed BigInt. |
| 916 |
.IP \fBdenominator()\fR 4 |
| 917 |
.IX Item "denominator()" |
| 918 |
.Vb 1 |
| 919 |
\& $d = $x\->denominator(); |
| 920 |
.Ve |
| 921 |
.Sp |
| 922 |
Returns a copy of the denominator (the part under the line) as positive BigInt. |
| 923 |
.SS "String conversion methods" |
| 924 |
.IX Subsection "String conversion methods" |
| 925 |
.IP \fBbstr()\fR 4 |
| 926 |
.IX Item "bstr()" |
| 927 |
.Vb 2 |
| 928 |
\& my $x = Math::BigRat\->new(\*(Aq8/4\*(Aq); |
| 929 |
\& print $x\->bstr(), "\en"; # prints 1/2 |
| 930 |
.Ve |
| 931 |
.Sp |
| 932 |
Returns a string representing the number. |
| 933 |
.IP \fBbnstr()\fR 4 |
| 934 |
.IX Item "bnstr()" |
| 935 |
See "\fBbnstr()\fR" in Math::BigInt. |
| 936 |
.IP \fBbestr()\fR 4 |
| 937 |
.IX Item "bestr()" |
| 938 |
See "\fBbestr()\fR" in Math::BigInt. |
| 939 |
.IP \fBbdstr()\fR 4 |
| 940 |
.IX Item "bdstr()" |
| 941 |
See "\fBbdstr()\fR" in Math::BigInt. |
| 942 |
.IP \fBto_bytes()\fR 4 |
| 943 |
.IX Item "to_bytes()" |
| 944 |
See "\fBto_bytes()\fR" in Math::BigInt. |
| 945 |
.IP \fBto_ieee754()\fR 4 |
| 946 |
.IX Item "to_ieee754()" |
| 947 |
See "\fBto_ieee754()\fR" in Math::BigFloat. |
| 948 |
.IP \fBas_hex()\fR 4 |
| 949 |
.IX Item "as_hex()" |
| 950 |
.Vb 2 |
| 951 |
\& $x = Math::BigRat\->new(\*(Aq13\*(Aq); |
| 952 |
\& print $x\->as_hex(), "\en"; # \*(Aq0xd\*(Aq |
| 953 |
.Ve |
| 954 |
.Sp |
| 955 |
Returns the BigRat as hexadecimal string. Works only for integers. |
| 956 |
.IP \fBas_oct()\fR 4 |
| 957 |
.IX Item "as_oct()" |
| 958 |
.Vb 2 |
| 959 |
\& $x = Math::BigRat\->new(\*(Aq13\*(Aq); |
| 960 |
\& print $x\->as_oct(), "\en"; # \*(Aq015\*(Aq |
| 961 |
.Ve |
| 962 |
.Sp |
| 963 |
Returns the BigRat as octal string. Works only for integers. |
| 964 |
.IP \fBas_bin()\fR 4 |
| 965 |
.IX Item "as_bin()" |
| 966 |
.Vb 2 |
| 967 |
\& $x = Math::BigRat\->new(\*(Aq13\*(Aq); |
| 968 |
\& print $x\->as_bin(), "\en"; # \*(Aq0x1101\*(Aq |
| 969 |
.Ve |
| 970 |
.Sp |
| 971 |
Returns the BigRat as binary string. Works only for integers. |
| 972 |
.IP \fBnumify()\fR 4 |
| 973 |
.IX Item "numify()" |
| 974 |
.Vb 1 |
| 975 |
\& my $y = $x\->numify(); |
| 976 |
.Ve |
| 977 |
.Sp |
| 978 |
Returns the object as a scalar. This will lose some data if the object |
| 979 |
cannot be represented by a normal Perl scalar (integer or float), so |
| 980 |
use "\fBas_int()\fR" or "\fBas_float()\fR" instead. |
| 981 |
.Sp |
| 982 |
This routine is automatically used whenever a scalar is required: |
| 983 |
.Sp |
| 984 |
.Vb 3 |
| 985 |
\& my $x = Math::BigRat\->new(\*(Aq3/1\*(Aq); |
| 986 |
\& @array = (0, 1, 2, 3); |
| 987 |
\& $y = $array[$x]; # set $y to 3 |
| 988 |
.Ve |
| 989 |
.IP \fBconfig()\fR 4 |
| 990 |
.IX Item "config()" |
| 991 |
.Vb 2 |
| 992 |
\& Math::BigRat\->config("trap_nan" => 1); # set |
| 993 |
\& $accu = Math::BigRat\->config("accuracy"); # get |
| 994 |
.Ve |
| 995 |
.Sp |
| 996 |
Set or get configuration parameter values. Read\-only parameters are marked as |
| 997 |
RO. Read\-write parameters are marked as RW. The following parameters are |
| 998 |
supported. |
| 999 |
.Sp |
| 1000 |
.Vb 10 |
| 1001 |
\& Parameter RO/RW Description |
| 1002 |
\& Example |
| 1003 |
\& ============================================================ |
| 1004 |
\& lib RO Name of the math backend library |
| 1005 |
\& Math::BigInt::Calc |
| 1006 |
\& lib_version RO Version of the math backend library |
| 1007 |
\& 0.30 |
| 1008 |
\& class RO The class of config you just called |
| 1009 |
\& Math::BigRat |
| 1010 |
\& version RO version number of the class you used |
| 1011 |
\& 0.10 |
| 1012 |
\& upgrade RW To which class numbers are upgraded |
| 1013 |
\& undef |
| 1014 |
\& downgrade RW To which class numbers are downgraded |
| 1015 |
\& undef |
| 1016 |
\& precision RW Global precision |
| 1017 |
\& undef |
| 1018 |
\& accuracy RW Global accuracy |
| 1019 |
\& undef |
| 1020 |
\& round_mode RW Global round mode |
| 1021 |
\& even |
| 1022 |
\& div_scale RW Fallback accuracy for div, sqrt etc. |
| 1023 |
\& 40 |
| 1024 |
\& trap_nan RW Trap NaNs |
| 1025 |
\& undef |
| 1026 |
\& trap_inf RW Trap +inf/\-inf |
| 1027 |
\& undef |
| 1028 |
.Ve |
| 1029 |
.SH "NUMERIC LITERALS" |
| 1030 |
.IX Header "NUMERIC LITERALS" |
| 1031 |
After \f(CW\*(C`use Math::BigRat \*(Aq:constant\*(Aq\*(C'\fR all numeric literals in the given scope |
| 1032 |
are converted to \f(CW\*(C`Math::BigRat\*(C'\fR objects. This conversion happens at compile |
| 1033 |
time. Every non\-integer is convert to a NaN. |
| 1034 |
.PP |
| 1035 |
For example, |
| 1036 |
.PP |
| 1037 |
.Vb 1 |
| 1038 |
\& perl \-MMath::BigRat=:constant \-le \*(Aqprint 2**150\*(Aq |
| 1039 |
.Ve |
| 1040 |
.PP |
| 1041 |
prints the exact value of \f(CW\*(C`2**150\*(C'\fR. Note that without conversion of constants |
| 1042 |
to objects the expression \f(CW\*(C`2**150\*(C'\fR is calculated using Perl scalars, which |
| 1043 |
leads to an inaccurate result. |
| 1044 |
.PP |
| 1045 |
Please note that strings are not affected, so that |
| 1046 |
.PP |
| 1047 |
.Vb 1 |
| 1048 |
\& use Math::BigRat qw/:constant/; |
| 1049 |
\& |
| 1050 |
\& $x = "1234567890123456789012345678901234567890" |
| 1051 |
\& + "123456789123456789"; |
| 1052 |
.Ve |
| 1053 |
.PP |
| 1054 |
does give you what you expect. You need an explicit Math::BigRat\->\fBnew()\fR around |
| 1055 |
at least one of the operands. You should also quote large constants to prevent |
| 1056 |
loss of precision: |
| 1057 |
.PP |
| 1058 |
.Vb 1 |
| 1059 |
\& use Math::BigRat; |
| 1060 |
\& |
| 1061 |
\& $x = Math::BigRat\->new("1234567889123456789123456789123456789"); |
| 1062 |
.Ve |
| 1063 |
.PP |
| 1064 |
Without the quotes Perl first converts the large number to a floating point |
| 1065 |
constant at compile time, and then converts the result to a Math::BigRat object |
| 1066 |
at run time, which results in an inaccurate result. |
| 1067 |
.SS "Hexadecimal, octal, and binary floating point literals" |
| 1068 |
.IX Subsection "Hexadecimal, octal, and binary floating point literals" |
| 1069 |
Perl (and this module) accepts hexadecimal, octal, and binary floating point |
| 1070 |
literals, but use them with care with Perl versions before v5.32.0, because some |
| 1071 |
versions of Perl silently give the wrong result. Below are some examples of |
| 1072 |
different ways to write the number decimal 314. |
| 1073 |
.PP |
| 1074 |
Hexadecimal floating point literals: |
| 1075 |
.PP |
| 1076 |
.Vb 3 |
| 1077 |
\& 0x1.3ap+8 0X1.3AP+8 |
| 1078 |
\& 0x1.3ap8 0X1.3AP8 |
| 1079 |
\& 0x13a0p\-4 0X13A0P\-4 |
| 1080 |
.Ve |
| 1081 |
.PP |
| 1082 |
Octal floating point literals (with "0" prefix): |
| 1083 |
.PP |
| 1084 |
.Vb 3 |
| 1085 |
\& 01.164p+8 01.164P+8 |
| 1086 |
\& 01.164p8 01.164P8 |
| 1087 |
\& 011640p\-4 011640P\-4 |
| 1088 |
.Ve |
| 1089 |
.PP |
| 1090 |
Octal floating point literals (with "0o" prefix) (requires v5.34.0): |
| 1091 |
.PP |
| 1092 |
.Vb 3 |
| 1093 |
\& 0o1.164p+8 0O1.164P+8 |
| 1094 |
\& 0o1.164p8 0O1.164P8 |
| 1095 |
\& 0o11640p\-4 0O11640P\-4 |
| 1096 |
.Ve |
| 1097 |
.PP |
| 1098 |
Binary floating point literals: |
| 1099 |
.PP |
| 1100 |
.Vb 3 |
| 1101 |
\& 0b1.0011101p+8 0B1.0011101P+8 |
| 1102 |
\& 0b1.0011101p8 0B1.0011101P8 |
| 1103 |
\& 0b10011101000p\-2 0B10011101000P\-2 |
| 1104 |
.Ve |
| 1105 |
.SH BUGS |
| 1106 |
.IX Header "BUGS" |
| 1107 |
Please report any bugs or feature requests to |
| 1108 |
\&\f(CW\*(C`bug\-math\-bigint at rt.cpan.org\*(C'\fR, or through the web interface at |
| 1109 |
<https://rt.cpan.org/Ticket/Create.html?Queue=Math\-BigInt> (requires login). |
| 1110 |
We will be notified, and then you\*(Aqll automatically be notified of progress on |
| 1111 |
your bug as I make changes. |
| 1112 |
.SH SUPPORT |
| 1113 |
.IX Header "SUPPORT" |
| 1114 |
You can find documentation for this module with the perldoc command. |
| 1115 |
.PP |
| 1116 |
.Vb 1 |
| 1117 |
\& perldoc Math::BigInt |
| 1118 |
.Ve |
| 1119 |
.PP |
| 1120 |
You can also look for information at: |
| 1121 |
.IP \(bu 4 |
| 1122 |
GitHub |
| 1123 |
.Sp |
| 1124 |
<https://github.com/pjacklam/p5\-Math\-BigInt> |
| 1125 |
.IP \(bu 4 |
| 1126 |
RT: CPAN\*(Aqs request tracker |
| 1127 |
.Sp |
| 1128 |
<https://rt.cpan.org/Dist/Display.html?Name=Math\-BigInt> |
| 1129 |
.IP \(bu 4 |
| 1130 |
MetaCPAN |
| 1131 |
.Sp |
| 1132 |
<https://metacpan.org/release/Math\-BigInt> |
| 1133 |
.IP \(bu 4 |
| 1134 |
CPAN Testers Matrix |
| 1135 |
.Sp |
| 1136 |
<http://matrix.cpantesters.org/?dist=Math\-BigInt> |
| 1137 |
.SH LICENSE |
| 1138 |
.IX Header "LICENSE" |
| 1139 |
This program is free software; you may redistribute it and/or modify it under |
| 1140 |
the same terms as Perl itself. |
| 1141 |
.SH "SEE ALSO" |
| 1142 |
.IX Header "SEE ALSO" |
| 1143 |
Math::BigInt and Math::BigFloat as well as the backend libraries |
| 1144 |
Math::BigInt::FastCalc, Math::BigInt::GMP, and Math::BigInt::Pari, |
| 1145 |
Math::BigInt::GMPz, and Math::BigInt::BitVect. |
| 1146 |
.PP |
| 1147 |
The pragmas bigint, bigfloat, and bigrat might also be of interest. In |
| 1148 |
addition there is the bignum pragma which does upgrading and downgrading. |
| 1149 |
.SH AUTHORS |
| 1150 |
.IX Header "AUTHORS" |
| 1151 |
.IP \(bu 4 |
| 1152 |
Tels <http://bloodgate.com/> 2001\-2009. |
| 1153 |
.IP \(bu 4 |
| 1154 |
Maintained by Peter John Acklam <[email protected]> 2011\- |