| 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::BigInt 3perl" |
| 58 |
.TH Math::BigInt 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::BigInt \- arbitrary size integer math package |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
.Vb 1 |
| 68 |
\& use Math::BigInt; |
| 69 |
\& |
| 70 |
\& # or make it faster with huge numbers: install (optional) |
| 71 |
\& # Math::BigInt::GMP and always use (it falls back to |
| 72 |
\& # pure Perl if the GMP library is not installed): |
| 73 |
\& # (See also the L<MATH LIBRARY> section!) |
| 74 |
\& |
| 75 |
\& # to warn if Math::BigInt::GMP cannot be found, use |
| 76 |
\& use Math::BigInt lib => \*(AqGMP\*(Aq; |
| 77 |
\& |
| 78 |
\& # to suppress the warning if Math::BigInt::GMP cannot be found, use |
| 79 |
\& # use Math::BigInt try => \*(AqGMP\*(Aq; |
| 80 |
\& |
| 81 |
\& # to die if Math::BigInt::GMP cannot be found, use |
| 82 |
\& # use Math::BigInt only => \*(AqGMP\*(Aq; |
| 83 |
\& |
| 84 |
\& # Configuration methods (may be used as class methods and instance methods) |
| 85 |
\& |
| 86 |
\& Math::BigInt\->accuracy(); # get class accuracy |
| 87 |
\& Math::BigInt\->accuracy($n); # set class accuracy |
| 88 |
\& Math::BigInt\->precision(); # get class precision |
| 89 |
\& Math::BigInt\->precision($n); # set class precision |
| 90 |
\& Math::BigInt\->round_mode(); # get class rounding mode |
| 91 |
\& Math::BigInt\->round_mode($m); # set global round mode, must be one of |
| 92 |
\& # \*(Aqeven\*(Aq, \*(Aqodd\*(Aq, \*(Aq+inf\*(Aq, \*(Aq\-inf\*(Aq, \*(Aqzero\*(Aq, |
| 93 |
\& # \*(Aqtrunc\*(Aq, or \*(Aqcommon\*(Aq |
| 94 |
\& Math::BigInt\->div_scale($n); # set fallback accuracy |
| 95 |
\& Math::BigInt\->trap_inf($b); # trap infinities or not |
| 96 |
\& Math::BigInt\->trap_nan($b); # trap NaNs or not |
| 97 |
\& Math::BigInt\->config(); # return hash with configuration |
| 98 |
\& |
| 99 |
\& # Constructor methods (when the class methods below are used as instance |
| 100 |
\& # methods, the value is assigned the invocand) |
| 101 |
\& |
| 102 |
\& $x = Math::BigInt\->new($str); # defaults to 0 |
| 103 |
\& $x = Math::BigInt\->new(\*(Aq0x123\*(Aq); # from hexadecimal |
| 104 |
\& $x = Math::BigInt\->new(\*(Aq0b101\*(Aq); # from binary |
| 105 |
\& $x = Math::BigInt\->from_hex(\*(Aqcafe\*(Aq); # from hexadecimal |
| 106 |
\& $x = Math::BigInt\->from_oct(\*(Aq377\*(Aq); # from octal |
| 107 |
\& $x = Math::BigInt\->from_bin(\*(Aq1101\*(Aq); # from binary |
| 108 |
\& $x = Math::BigInt\->from_base(\*(Aqwhy\*(Aq, 36); # from any base |
| 109 |
\& $x = Math::BigInt\->from_base_num([1, 0], 2); # from any base |
| 110 |
\& $x = Math::BigInt\->bzero(); # create a +0 |
| 111 |
\& $x = Math::BigInt\->bone(); # create a +1 |
| 112 |
\& $x = Math::BigInt\->bone(\*(Aq\-\*(Aq); # create a \-1 |
| 113 |
\& $x = Math::BigInt\->binf(); # create a +inf |
| 114 |
\& $x = Math::BigInt\->binf(\*(Aq\-\*(Aq); # create a \-inf |
| 115 |
\& $x = Math::BigInt\->bnan(); # create a Not\-A\-Number |
| 116 |
\& $x = Math::BigInt\->bpi(); # returns pi |
| 117 |
\& |
| 118 |
\& $y = $x\->copy(); # make a copy (unlike $y = $x) |
| 119 |
\& $y = $x\->as_int(); # return as a Math::BigInt |
| 120 |
\& $y = $x\->as_float(); # return as a Math::BigFloat |
| 121 |
\& $y = $x\->as_rat(); # return as a Math::BigRat |
| 122 |
\& |
| 123 |
\& # Boolean methods (these don\*(Aqt modify the invocand) |
| 124 |
\& |
| 125 |
\& $x\->is_zero(); # if $x is 0 |
| 126 |
\& $x\->is_one(); # if $x is +1 |
| 127 |
\& $x\->is_one("+"); # ditto |
| 128 |
\& $x\->is_one("\-"); # if $x is \-1 |
| 129 |
\& $x\->is_inf(); # if $x is +inf or \-inf |
| 130 |
\& $x\->is_inf("+"); # if $x is +inf |
| 131 |
\& $x\->is_inf("\-"); # if $x is \-inf |
| 132 |
\& $x\->is_nan(); # if $x is NaN |
| 133 |
\& |
| 134 |
\& $x\->is_positive(); # if $x > 0 |
| 135 |
\& $x\->is_pos(); # ditto |
| 136 |
\& $x\->is_negative(); # if $x < 0 |
| 137 |
\& $x\->is_neg(); # ditto |
| 138 |
\& |
| 139 |
\& $x\->is_odd(); # if $x is odd |
| 140 |
\& $x\->is_even(); # if $x is even |
| 141 |
\& $x\->is_int(); # if $x is an integer |
| 142 |
\& |
| 143 |
\& # Comparison methods |
| 144 |
\& |
| 145 |
\& $x\->bcmp($y); # compare numbers (undef, < 0, == 0, > 0) |
| 146 |
\& $x\->bacmp($y); # compare absolutely (undef, < 0, == 0, > 0) |
| 147 |
\& $x\->beq($y); # true if and only if $x == $y |
| 148 |
\& $x\->bne($y); # true if and only if $x != $y |
| 149 |
\& $x\->blt($y); # true if and only if $x < $y |
| 150 |
\& $x\->ble($y); # true if and only if $x <= $y |
| 151 |
\& $x\->bgt($y); # true if and only if $x > $y |
| 152 |
\& $x\->bge($y); # true if and only if $x >= $y |
| 153 |
\& |
| 154 |
\& # Arithmetic methods |
| 155 |
\& |
| 156 |
\& $x\->bneg(); # negation |
| 157 |
\& $x\->babs(); # absolute value |
| 158 |
\& $x\->bsgn(); # sign function (\-1, 0, 1, or NaN) |
| 159 |
\& $x\->bnorm(); # normalize (no\-op) |
| 160 |
\& $x\->binc(); # increment $x by 1 |
| 161 |
\& $x\->bdec(); # decrement $x by 1 |
| 162 |
\& $x\->badd($y); # addition (add $y to $x) |
| 163 |
\& $x\->bsub($y); # subtraction (subtract $y from $x) |
| 164 |
\& $x\->bmul($y); # multiplication (multiply $x by $y) |
| 165 |
\& $x\->bmuladd($y,$z); # $x = $x * $y + $z |
| 166 |
\& $x\->bdiv($y); # division (floored), set $x to quotient |
| 167 |
\& # return (quo,rem) or quo if scalar |
| 168 |
\& $x\->btdiv($y); # division (truncated), set $x to quotient |
| 169 |
\& # return (quo,rem) or quo if scalar |
| 170 |
\& $x\->bmod($y); # modulus (x % y) |
| 171 |
\& $x\->btmod($y); # modulus (truncated) |
| 172 |
\& $x\->bmodinv($mod); # modular multiplicative inverse |
| 173 |
\& $x\->bmodpow($y,$mod); # modular exponentiation (($x ** $y) % $mod) |
| 174 |
\& $x\->binv() # inverse (1/$x) |
| 175 |
\& $x\->bpow($y); # power of arguments (x ** y) |
| 176 |
\& $x\->blog(); # logarithm of $x to base e (Euler\*(Aqs number) |
| 177 |
\& $x\->blog($base); # logarithm of $x to base $base (e.g., base 2) |
| 178 |
\& $x\->bexp(); # calculate e ** $x where e is Euler\*(Aqs number |
| 179 |
\& $x\->bilog2(); # log2($x) rounded down to nearest int |
| 180 |
\& $x\->bilog10(); # log10($x) rounded down to nearest int |
| 181 |
\& $x\->bclog2(); # log2($x) rounded up to nearest int |
| 182 |
\& $x\->bclog10(); # log19($x) rounded up to nearest int |
| 183 |
\& $x\->bnok($y); # x over y (binomial coefficient n over k) |
| 184 |
\& $x\->buparrow($n, $y); # Knuth\*(Aqs up\-arrow notation |
| 185 |
\& $x\->backermann($y); # the Ackermann function |
| 186 |
\& $x\->bsin(); # sine |
| 187 |
\& $x\->bcos(); # cosine |
| 188 |
\& $x\->batan(); # inverse tangent |
| 189 |
\& $x\->batan2($y); # two\-argument inverse tangent |
| 190 |
\& $x\->bsqrt(); # calculate square root |
| 191 |
\& $x\->broot($y); # $y\*(Aqth root of $x (e.g. $y == 3 => cubic root) |
| 192 |
\& $x\->bfac(); # factorial of $x (1*2*3*4*..$x) |
| 193 |
\& $x\->bdfac(); # double factorial of $x ($x*($x\-2)*($x\-4)*...) |
| 194 |
\& $x\->btfac(); # triple factorial of $x ($x*($x\-3)*($x\-6)*...) |
| 195 |
\& $x\->bmfac($k); # $k\*(Aqth multi\-factorial of $x ($x*($x\-$k)*...) |
| 196 |
\& |
| 197 |
\& $x\->blsft($n); # left shift $n places in base 2 |
| 198 |
\& $x\->blsft($n,$b); # left shift $n places in base $b |
| 199 |
\& # returns (quo,rem) or quo (scalar context) |
| 200 |
\& $x\->brsft($n); # right shift $n places in base 2 |
| 201 |
\& $x\->brsft($n,$b); # right shift $n places in base $b |
| 202 |
\& # returns (quo,rem) or quo (scalar context) |
| 203 |
\& |
| 204 |
\& # Bitwise methods |
| 205 |
\& |
| 206 |
\& $x\->bblsft($y); # bitwise left shift |
| 207 |
\& $x\->bbrsft($y); # bitwise right shift |
| 208 |
\& $x\->band($y); # bitwise and |
| 209 |
\& $x\->bior($y); # bitwise inclusive or |
| 210 |
\& $x\->bxor($y); # bitwise exclusive or |
| 211 |
\& $x\->bnot(); # bitwise not (two\*(Aqs complement) |
| 212 |
\& |
| 213 |
\& # Rounding methods |
| 214 |
\& $x\->round($A,$P,$mode); # round to accuracy or precision using |
| 215 |
\& # rounding mode $mode |
| 216 |
\& $x\->bround($n); # accuracy: preserve $n digits |
| 217 |
\& $x\->bfround($n); # $n > 0: round to $nth digit left of dec. point |
| 218 |
\& # $n < 0: round to $nth digit right of dec. point |
| 219 |
\& $x\->bfloor(); # round towards minus infinity |
| 220 |
\& $x\->bceil(); # round towards plus infinity |
| 221 |
\& $x\->bint(); # round towards zero |
| 222 |
\& |
| 223 |
\& # Other mathematical methods |
| 224 |
\& |
| 225 |
\& $x\->bgcd($y); # greatest common divisor |
| 226 |
\& $x\->blcm($y); # least common multiple |
| 227 |
\& |
| 228 |
\& # Object property methods (do not modify the invocand) |
| 229 |
\& |
| 230 |
\& $x\->sign(); # the sign, either +, \- or NaN |
| 231 |
\& $x\->digit($n); # the nth digit, counting from the right |
| 232 |
\& $x\->digit(\-$n); # the nth digit, counting from the left |
| 233 |
\& $x\->length(); # return number of digits in number |
| 234 |
\& ($xl,$f) = $x\->length(); # length of number and length of fraction |
| 235 |
\& # part, latter is always 0 digits long |
| 236 |
\& # for Math::BigInt objects |
| 237 |
\& $x\->mantissa(); # return (signed) mantissa as a Math::BigInt |
| 238 |
\& $x\->exponent(); # return exponent as a Math::BigInt |
| 239 |
\& $x\->parts(); # return (mantissa,exponent) as a Math::BigInt |
| 240 |
\& $x\->sparts(); # mantissa and exponent (as integers) |
| 241 |
\& $x\->nparts(); # mantissa and exponent (normalised) |
| 242 |
\& $x\->eparts(); # mantissa and exponent (engineering notation) |
| 243 |
\& $x\->dparts(); # integer and fraction part |
| 244 |
\& $x\->fparts(); # numerator and denominator |
| 245 |
\& $x\->numerator(); # numerator |
| 246 |
\& $x\->denominator(); # denominator |
| 247 |
\& |
| 248 |
\& # Conversion methods (do not modify the invocand) |
| 249 |
\& |
| 250 |
\& $x\->bstr(); # decimal notation, possibly zero padded |
| 251 |
\& $x\->bsstr(); # string in scientific notation with integers |
| 252 |
\& $x\->bnstr(); # string in normalized notation |
| 253 |
\& $x\->bestr(); # string in engineering notation |
| 254 |
\& $x\->bfstr(); # string in fractional notation |
| 255 |
\& |
| 256 |
\& $x\->to_hex(); # as signed hexadecimal string |
| 257 |
\& $x\->to_bin(); # as signed binary string |
| 258 |
\& $x\->to_oct(); # as signed octal string |
| 259 |
\& $x\->to_bytes(); # as byte string |
| 260 |
\& $x\->to_base($b); # as string in any base |
| 261 |
\& $x\->to_base_num($b); # as array of integers in any base |
| 262 |
\& |
| 263 |
\& $x\->as_hex(); # as signed hexadecimal string with prefixed 0x |
| 264 |
\& $x\->as_bin(); # as signed binary string with prefixed 0b |
| 265 |
\& $x\->as_oct(); # as signed octal string with prefixed 0 |
| 266 |
\& |
| 267 |
\& # Other conversion methods |
| 268 |
\& |
| 269 |
\& $x\->numify(); # return as scalar (might overflow or underflow) |
| 270 |
.Ve |
| 271 |
.SH DESCRIPTION |
| 272 |
.IX Header "DESCRIPTION" |
| 273 |
Math::BigInt provides support for arbitrary precision integers. Overloading is |
| 274 |
also provided for Perl operators. |
| 275 |
.SS Input |
| 276 |
.IX Subsection "Input" |
| 277 |
Input values to these routines may be any scalar number or string that looks |
| 278 |
like a number and represents an integer. Anything that is accepted by Perl as a |
| 279 |
literal numeric constant should be accepted by this module, except that finite |
| 280 |
non-integers return NaN. |
| 281 |
.IP \(bu 4 |
| 282 |
Leading and trailing whitespace is ignored. |
| 283 |
.IP \(bu 4 |
| 284 |
Leading zeros are ignored, except for floating point numbers with a binary |
| 285 |
exponent, in which case the number is interpreted as an octal floating point |
| 286 |
number. For example, "01.4p+0" gives 1.5, "00.4p+0" gives 0.5, but "0.4p+0" |
| 287 |
gives a NaN. And while "0377" gives 255, "0377p0" gives 255. |
| 288 |
.IP \(bu 4 |
| 289 |
If the string has a "0x" or "0X" prefix, it is interpreted as a hexadecimal |
| 290 |
number. |
| 291 |
.IP \(bu 4 |
| 292 |
If the string has a "0o" or "0O" prefix, it is interpreted as an octal number. A |
| 293 |
floating point literal with a "0" prefix is also interpreted as an octal number. |
| 294 |
.IP \(bu 4 |
| 295 |
If the string has a "0b" or "0B" prefix, it is interpreted as a binary number. |
| 296 |
.IP \(bu 4 |
| 297 |
Underline characters are allowed in the same way as they are allowed in literal |
| 298 |
numerical constants. |
| 299 |
.IP \(bu 4 |
| 300 |
If the string can not be interpreted, or does not represent a finite integer, |
| 301 |
NaN is returned. |
| 302 |
.IP \(bu 4 |
| 303 |
For hexadecimal, octal, and binary floating point numbers, the exponent must be |
| 304 |
separated from the significand (mantissa) by the letter "p" or "P", not "e" or |
| 305 |
"E" as with decimal numbers. |
| 306 |
.PP |
| 307 |
Some examples of valid string input |
| 308 |
.PP |
| 309 |
.Vb 1 |
| 310 |
\& Input string Resulting value |
| 311 |
\& |
| 312 |
\& 123 123 |
| 313 |
\& 1.23e2 123 |
| 314 |
\& 12300e\-2 123 |
| 315 |
\& |
| 316 |
\& 67_538_754 67538754 |
| 317 |
\& \-4_5_6.7_8_9e+0_1_0 \-4567890000000 |
| 318 |
\& |
| 319 |
\& 0x13a 314 |
| 320 |
\& 0x13ap0 314 |
| 321 |
\& 0x1.3ap+8 314 |
| 322 |
\& 0x0.00013ap+24 314 |
| 323 |
\& 0x13a000p\-12 314 |
| 324 |
\& |
| 325 |
\& 0o472 314 |
| 326 |
\& 0o1.164p+8 314 |
| 327 |
\& 0o0.0001164p+20 314 |
| 328 |
\& 0o1164000p\-10 314 |
| 329 |
\& |
| 330 |
\& 0472 472 Note! |
| 331 |
\& 01.164p+8 314 |
| 332 |
\& 00.0001164p+20 314 |
| 333 |
\& 01164000p\-10 314 |
| 334 |
\& |
| 335 |
\& 0b100111010 314 |
| 336 |
\& 0b1.0011101p+8 314 |
| 337 |
\& 0b0.00010011101p+12 314 |
| 338 |
\& 0b100111010000p\-3 314 |
| 339 |
.Ve |
| 340 |
.PP |
| 341 |
Input given as scalar numbers might lose precision. Quote your input to ensure |
| 342 |
that no digits are lost: |
| 343 |
.PP |
| 344 |
.Vb 2 |
| 345 |
\& $x = Math::BigInt\->new( 56789012345678901234 ); # bad |
| 346 |
\& $x = Math::BigInt\->new(\*(Aq56789012345678901234\*(Aq); # good |
| 347 |
.Ve |
| 348 |
.PP |
| 349 |
Currently, \f(CW\*(C`Math::BigInt\-\*(C'\fR\fBnew()\fR> (no input argument) and |
| 350 |
\&\f(CW\*(C`Math::BigInt\-\*(C'\fRnew("")> return 0. This might change in the future, so always |
| 351 |
use the following explicit forms to get a zero: |
| 352 |
.PP |
| 353 |
.Vb 1 |
| 354 |
\& $zero = Math::BigInt\->bzero(); |
| 355 |
.Ve |
| 356 |
.SS Output |
| 357 |
.IX Subsection "Output" |
| 358 |
Output values are usually Math::BigInt objects. |
| 359 |
.PP |
| 360 |
Boolean operators \f(CWis_zero()\fR, \f(CWis_one()\fR, \f(CWis_inf()\fR, etc. return true or |
| 361 |
false. |
| 362 |
.PP |
| 363 |
Comparison operators \f(CWbcmp()\fR and \f(CWbacmp()\fR) return \-1, 0, 1, or |
| 364 |
undef. |
| 365 |
.SH METHODS |
| 366 |
.IX Header "METHODS" |
| 367 |
.SS "Configuration methods" |
| 368 |
.IX Subsection "Configuration methods" |
| 369 |
Each of the methods below (except \fBconfig()\fR, \fBaccuracy()\fR and \fBprecision()\fR) accepts |
| 370 |
three additional parameters. These arguments \f(CW$A\fR, \f(CW$P\fR and \f(CW$R\fR are |
| 371 |
\&\f(CW\*(C`accuracy\*(C'\fR, \f(CW\*(C`precision\*(C'\fR and \f(CW\*(C`round_mode\*(C'\fR. Please see the section about |
| 372 |
"ACCURACY and PRECISION" for more information. |
| 373 |
.PP |
| 374 |
Setting a class variable effects all object instance that are created |
| 375 |
afterwards. |
| 376 |
.IP \fBaccuracy()\fR 4 |
| 377 |
.IX Item "accuracy()" |
| 378 |
.Vb 2 |
| 379 |
\& Math::BigInt\->accuracy(5); # set class accuracy |
| 380 |
\& $x\->accuracy(5); # set instance accuracy |
| 381 |
\& |
| 382 |
\& $A = Math::BigInt\->accuracy(); # get class accuracy |
| 383 |
\& $A = $x\->accuracy(); # get instance accuracy |
| 384 |
.Ve |
| 385 |
.Sp |
| 386 |
Set or get the accuracy, i.e., the number of significant digits. The accuracy |
| 387 |
must be an integer. If the accuracy is set to \f(CW\*(C`undef\*(C'\fR, no rounding is done. |
| 388 |
.Sp |
| 389 |
Alternatively, one can round the results explicitly using one of "\fBround()\fR", |
| 390 |
"\fBbround()\fR" or "\fBbfround()\fR" or by passing the desired accuracy to the method |
| 391 |
as an additional parameter: |
| 392 |
.Sp |
| 393 |
.Vb 4 |
| 394 |
\& my $x = Math::BigInt\->new(30000); |
| 395 |
\& my $y = Math::BigInt\->new(7); |
| 396 |
\& print scalar $x\->copy()\->bdiv($y, 2); # prints 4300 |
| 397 |
\& print scalar $x\->copy()\->bdiv($y)\->bround(2); # prints 4300 |
| 398 |
.Ve |
| 399 |
.Sp |
| 400 |
Please see the section about "ACCURACY and PRECISION" for further details. |
| 401 |
.Sp |
| 402 |
.Vb 4 |
| 403 |
\& $y = Math::BigInt\->new(1234567); # $y is not rounded |
| 404 |
\& Math::BigInt\->accuracy(4); # set class accuracy to 4 |
| 405 |
\& $x = Math::BigInt\->new(1234567); # $x is rounded automatically |
| 406 |
\& print "$x $y"; # prints "1235000 1234567" |
| 407 |
\& |
| 408 |
\& print $x\->accuracy(); # prints "4" |
| 409 |
\& print $y\->accuracy(); # also prints "4", since |
| 410 |
\& # class accuracy is 4 |
| 411 |
\& |
| 412 |
\& Math::BigInt\->accuracy(5); # set class accuracy to 5 |
| 413 |
\& print $x\->accuracy(); # prints "4", since instance |
| 414 |
\& # accuracy is 4 |
| 415 |
\& print $y\->accuracy(); # prints "5", since no instance |
| 416 |
\& # accuracy, and class accuracy is 5 |
| 417 |
.Ve |
| 418 |
.Sp |
| 419 |
Note: Each class has it's own globals separated from Math::BigInt, but it is |
| 420 |
possible to subclass Math::BigInt and make the globals of the subclass aliases |
| 421 |
to the ones from Math::BigInt. |
| 422 |
.IP \fBprecision()\fR 4 |
| 423 |
.IX Item "precision()" |
| 424 |
.Vb 2 |
| 425 |
\& Math::BigInt\->precision(\-2); # set class precision |
| 426 |
\& $x\->precision(\-2); # set instance precision |
| 427 |
\& |
| 428 |
\& $P = Math::BigInt\->precision(); # get class precision |
| 429 |
\& $P = $x\->precision(); # get instance precision |
| 430 |
.Ve |
| 431 |
.Sp |
| 432 |
Set or get the precision, i.e., the place to round relative to the decimal |
| 433 |
point. The precision must be a integer. Setting the precision to \f(CW$P\fR means that |
| 434 |
each number is rounded up or down, depending on the rounding mode, to the |
| 435 |
nearest multiple of 10**$P. If the precision is set to \f(CW\*(C`undef\*(C'\fR, no rounding is |
| 436 |
done. |
| 437 |
.Sp |
| 438 |
You might want to use "\fBaccuracy()\fR" instead. With "\fBaccuracy()\fR" you set the |
| 439 |
number of digits each result should have, with "\fBprecision()\fR" you set the |
| 440 |
place where to round. |
| 441 |
.Sp |
| 442 |
Please see the section about "ACCURACY and PRECISION" for further details. |
| 443 |
.Sp |
| 444 |
.Vb 4 |
| 445 |
\& $y = Math::BigInt\->new(1234567); # $y is not rounded |
| 446 |
\& Math::BigInt\->precision(4); # set class precision to 4 |
| 447 |
\& $x = Math::BigInt\->new(1234567); # $x is rounded automatically |
| 448 |
\& print $x; # prints "1230000" |
| 449 |
.Ve |
| 450 |
.Sp |
| 451 |
Note: Each class has its own globals separated from Math::BigInt, but it is |
| 452 |
possible to subclass Math::BigInt and make the globals of the subclass aliases |
| 453 |
to the ones from Math::BigInt. |
| 454 |
.IP \fBdiv_scale()\fR 4 |
| 455 |
.IX Item "div_scale()" |
| 456 |
Set/get the fallback accuracy. This is the accuracy used when neither accuracy |
| 457 |
nor precision is set explicitly. It is used when a computation might otherwise |
| 458 |
attempt to return an infinite number of digits. |
| 459 |
.IP \fBround_mode()\fR 4 |
| 460 |
.IX Item "round_mode()" |
| 461 |
Set/get the rounding mode. |
| 462 |
.IP \fBtrap_inf()\fR 4 |
| 463 |
.IX Item "trap_inf()" |
| 464 |
Set/get the value determining whether infinities should cause a fatal error or |
| 465 |
not. |
| 466 |
.IP \fBtrap_nan()\fR 4 |
| 467 |
.IX Item "trap_nan()" |
| 468 |
Set/get the value determining whether NaNs should cause a fatal error or not. |
| 469 |
.IP \fBupgrade()\fR 4 |
| 470 |
.IX Item "upgrade()" |
| 471 |
Set/get the class for upgrading. When a computation might result in a |
| 472 |
non-integer, the operands are upgraded to this class. This is used for instance |
| 473 |
by bignum. The default is \f(CW\*(C`undef\*(C'\fR, i.e., no upgrading. |
| 474 |
.Sp |
| 475 |
.Vb 4 |
| 476 |
\& # with no upgrading |
| 477 |
\& $x = Math::BigInt\->new(12); |
| 478 |
\& $y = Math::BigInt\->new(5); |
| 479 |
\& print $x / $y, "\en"; # 2 as a Math::BigInt |
| 480 |
\& |
| 481 |
\& # with upgrading to Math::BigFloat |
| 482 |
\& Math::BigInt \-> upgrade("Math::BigFloat"); |
| 483 |
\& print $x / $y, "\en"; # 2.4 as a Math::BigFloat |
| 484 |
\& |
| 485 |
\& # with upgrading to Math::BigRat (after loading Math::BigRat) |
| 486 |
\& Math::BigInt \-> upgrade("Math::BigRat"); |
| 487 |
\& print $x / $y, "\en"; # 12/5 as a Math::BigRat |
| 488 |
.Ve |
| 489 |
.IP \fBdowngrade()\fR 4 |
| 490 |
.IX Item "downgrade()" |
| 491 |
Set/get the class for downgrading. The default is \f(CW\*(C`undef\*(C'\fR, i.e., no |
| 492 |
downgrading. Downgrading is not done by Math::BigInt. |
| 493 |
.IP \fBmodify()\fR 4 |
| 494 |
.IX Item "modify()" |
| 495 |
.Vb 1 |
| 496 |
\& $x\->modify(\*(Aqbpowd\*(Aq); |
| 497 |
.Ve |
| 498 |
.Sp |
| 499 |
This method returns 0 if the object can be modified with the given operation, |
| 500 |
or 1 if not. |
| 501 |
.Sp |
| 502 |
This is used for instance by Math::BigInt::Constant. |
| 503 |
.IP \fBconfig()\fR 4 |
| 504 |
.IX Item "config()" |
| 505 |
.Vb 2 |
| 506 |
\& Math::BigInt\->config("trap_nan" => 1); # set |
| 507 |
\& $accu = Math::BigInt\->config("accuracy"); # get |
| 508 |
.Ve |
| 509 |
.Sp |
| 510 |
Set or get class variables. Read-only parameters are marked as RO. Read-write |
| 511 |
parameters are marked as RW. The following parameters are supported. |
| 512 |
.Sp |
| 513 |
.Vb 10 |
| 514 |
\& Parameter RO/RW Description |
| 515 |
\& Example |
| 516 |
\& ============================================================ |
| 517 |
\& lib RO Name of the math backend library |
| 518 |
\& Math::BigInt::Calc |
| 519 |
\& lib_version RO Version of the math backend library |
| 520 |
\& 0.30 |
| 521 |
\& class RO The class of config you just called |
| 522 |
\& Math::BigRat |
| 523 |
\& version RO version number of the class you used |
| 524 |
\& 0.10 |
| 525 |
\& upgrade RW To which class numbers are upgraded |
| 526 |
\& undef |
| 527 |
\& downgrade RW To which class numbers are downgraded |
| 528 |
\& undef |
| 529 |
\& precision RW Global precision |
| 530 |
\& undef |
| 531 |
\& accuracy RW Global accuracy |
| 532 |
\& undef |
| 533 |
\& round_mode RW Global round mode |
| 534 |
\& even |
| 535 |
\& div_scale RW Fallback accuracy for division etc. |
| 536 |
\& 40 |
| 537 |
\& trap_nan RW Trap NaNs |
| 538 |
\& undef |
| 539 |
\& trap_inf RW Trap +inf/\-inf |
| 540 |
\& undef |
| 541 |
.Ve |
| 542 |
.SS "Constructor methods" |
| 543 |
.IX Subsection "Constructor methods" |
| 544 |
.IP \fBnew()\fR 4 |
| 545 |
.IX Item "new()" |
| 546 |
.Vb 1 |
| 547 |
\& $x = Math::BigInt\->new($str,$A,$P,$R); |
| 548 |
.Ve |
| 549 |
.Sp |
| 550 |
Creates a new Math::BigInt object from a scalar or another Math::BigInt object. |
| 551 |
The input is accepted as decimal, hexadecimal (with leading '0x'), octal (with |
| 552 |
leading ('0o') or binary (with leading '0b'). |
| 553 |
.Sp |
| 554 |
See "Input" for more info on accepted input formats. |
| 555 |
.IP \fBfrom_dec()\fR 4 |
| 556 |
.IX Item "from_dec()" |
| 557 |
.Vb 1 |
| 558 |
\& $x = Math::BigInt\->from_dec("314159"); # input is decimal |
| 559 |
.Ve |
| 560 |
.Sp |
| 561 |
Interpret input as a decimal. It is equivalent to \fBnew()\fR, but does not accept |
| 562 |
anything but strings representing finite, decimal numbers. |
| 563 |
.IP \fBfrom_hex()\fR 4 |
| 564 |
.IX Item "from_hex()" |
| 565 |
.Vb 1 |
| 566 |
\& $x = Math::BigInt\->from_hex("0xcafe"); # input is hexadecimal |
| 567 |
.Ve |
| 568 |
.Sp |
| 569 |
Interpret input as a hexadecimal string. A "0x" or "x" prefix is optional. A |
| 570 |
single underscore character may be placed right after the prefix, if present, |
| 571 |
or between any two digits. If the input is invalid, a NaN is returned. |
| 572 |
.IP \fBfrom_oct()\fR 4 |
| 573 |
.IX Item "from_oct()" |
| 574 |
.Vb 1 |
| 575 |
\& $x = Math::BigInt\->from_oct("0775"); # input is octal |
| 576 |
.Ve |
| 577 |
.Sp |
| 578 |
Interpret the input as an octal string and return the corresponding value. A |
| 579 |
"0" (zero) prefix is optional. A single underscore character may be placed |
| 580 |
right after the prefix, if present, or between any two digits. If the input is |
| 581 |
invalid, a NaN is returned. |
| 582 |
.IP \fBfrom_bin()\fR 4 |
| 583 |
.IX Item "from_bin()" |
| 584 |
.Vb 1 |
| 585 |
\& $x = Math::BigInt\->from_bin("0b10011"); # input is binary |
| 586 |
.Ve |
| 587 |
.Sp |
| 588 |
Interpret the input as a binary string. A "0b" or "b" prefix is optional. A |
| 589 |
single underscore character may be placed right after the prefix, if present, |
| 590 |
or between any two digits. If the input is invalid, a NaN is returned. |
| 591 |
.IP \fBfrom_bytes()\fR 4 |
| 592 |
.IX Item "from_bytes()" |
| 593 |
.Vb 1 |
| 594 |
\& $x = Math::BigInt\->from_bytes("\exf3\ex6b"); # $x = 62315 |
| 595 |
.Ve |
| 596 |
.Sp |
| 597 |
Interpret the input as a byte string, assuming big endian byte order. The |
| 598 |
output is always a non-negative, finite integer. |
| 599 |
.Sp |
| 600 |
In some special cases, \fBfrom_bytes()\fR matches the conversion done by \fBunpack()\fR: |
| 601 |
.Sp |
| 602 |
.Vb 3 |
| 603 |
\& $b = "\ex4e"; # one char byte string |
| 604 |
\& $x = Math::BigInt\->from_bytes($b); # = 78 |
| 605 |
\& $y = unpack "C", $b; # ditto, but scalar |
| 606 |
\& |
| 607 |
\& $b = "\exf3\ex6b"; # two char byte string |
| 608 |
\& $x = Math::BigInt\->from_bytes($b); # = 62315 |
| 609 |
\& $y = unpack "S>", $b; # ditto, but scalar |
| 610 |
\& |
| 611 |
\& $b = "\ex2d\exe0\ex49\exad"; # four char byte string |
| 612 |
\& $x = Math::BigInt\->from_bytes($b); # = 769673645 |
| 613 |
\& $y = unpack "L>", $b; # ditto, but scalar |
| 614 |
\& |
| 615 |
\& $b = "\ex2d\exe0\ex49\exad\ex2d\exe0\ex49\exad"; # eight char byte string |
| 616 |
\& $x = Math::BigInt\->from_bytes($b); # = 3305723134637787565 |
| 617 |
\& $y = unpack "Q>", $b; # ditto, but scalar |
| 618 |
.Ve |
| 619 |
.IP \fBfrom_base()\fR 4 |
| 620 |
.IX Item "from_base()" |
| 621 |
Given a string, a base, and an optional collation sequence, interpret the |
| 622 |
string as a number in the given base. The collation sequence describes the |
| 623 |
value of each character in the string. |
| 624 |
.Sp |
| 625 |
If a collation sequence is not given, a default collation sequence is used. If |
| 626 |
the base is less than or equal to 36, the collation sequence is the string |
| 627 |
consisting of the 36 characters "0" to "9" and "A" to "Z". In this case, the |
| 628 |
letter case in the input is ignored. If the base is greater than 36, and |
| 629 |
smaller than or equal to 62, the collation sequence is the string consisting of |
| 630 |
the 62 characters "0" to "9", "A" to "Z", and "a" to "z". A base larger than 62 |
| 631 |
requires the collation sequence to be specified explicitly. |
| 632 |
.Sp |
| 633 |
These examples show standard binary, octal, and hexadecimal conversion. All |
| 634 |
cases return 250. |
| 635 |
.Sp |
| 636 |
.Vb 3 |
| 637 |
\& $x = Math::BigInt\->from_base("11111010", 2); |
| 638 |
\& $x = Math::BigInt\->from_base("372", 8); |
| 639 |
\& $x = Math::BigInt\->from_base("fa", 16); |
| 640 |
.Ve |
| 641 |
.Sp |
| 642 |
When the base is less than or equal to 36, and no collation sequence is given, |
| 643 |
the letter case is ignored, so both of these also return 250: |
| 644 |
.Sp |
| 645 |
.Vb 2 |
| 646 |
\& $x = Math::BigInt\->from_base("6Y", 16); |
| 647 |
\& $x = Math::BigInt\->from_base("6y", 16); |
| 648 |
.Ve |
| 649 |
.Sp |
| 650 |
When the base greater than 36, and no collation sequence is given, the default |
| 651 |
collation sequence contains both uppercase and lowercase letters, so |
| 652 |
the letter case in the input is not ignored: |
| 653 |
.Sp |
| 654 |
.Vb 5 |
| 655 |
\& $x = Math::BigInt\->from_base("6S", 37); # $x is 250 |
| 656 |
\& $x = Math::BigInt\->from_base("6s", 37); # $x is 276 |
| 657 |
\& $x = Math::BigInt\->from_base("121", 3); # $x is 16 |
| 658 |
\& $x = Math::BigInt\->from_base("XYZ", 36); # $x is 44027 |
| 659 |
\& $x = Math::BigInt\->from_base("Why", 42); # $x is 58314 |
| 660 |
.Ve |
| 661 |
.Sp |
| 662 |
The collation sequence can be any set of unique characters. These two cases |
| 663 |
are equivalent |
| 664 |
.Sp |
| 665 |
.Vb 2 |
| 666 |
\& $x = Math::BigInt\->from_base("100", 2, "01"); # $x is 4 |
| 667 |
\& $x = Math::BigInt\->from_base("|\-\-", 2, "\-|"); # $x is 4 |
| 668 |
.Ve |
| 669 |
.IP \fBfrom_base_num()\fR 4 |
| 670 |
.IX Item "from_base_num()" |
| 671 |
Returns a new Math::BigInt object given an array of values and a base. This |
| 672 |
method is equivalent to \f(CWfrom_base()\fR, but works on numbers in an array rather |
| 673 |
than characters in a string. Unlike \f(CWfrom_base()\fR, all input values may be |
| 674 |
arbitrarily large. |
| 675 |
.Sp |
| 676 |
.Vb 2 |
| 677 |
\& $x = Math::BigInt\->from_base_num([1, 1, 0, 1], 2) # $x is 13 |
| 678 |
\& $x = Math::BigInt\->from_base_num([3, 125, 39], 128) # $x is 65191 |
| 679 |
.Ve |
| 680 |
.IP \fBbzero()\fR 4 |
| 681 |
.IX Item "bzero()" |
| 682 |
.Vb 2 |
| 683 |
\& $x = Math::BigInt\->bzero(); |
| 684 |
\& $x\->bzero(); |
| 685 |
.Ve |
| 686 |
.Sp |
| 687 |
Returns a new Math::BigInt object representing zero. If used as an instance |
| 688 |
method, assigns the value to the invocand. |
| 689 |
.IP \fBbone()\fR 4 |
| 690 |
.IX Item "bone()" |
| 691 |
.Vb 6 |
| 692 |
\& $x = Math::BigInt\->bone(); # +1 |
| 693 |
\& $x = Math::BigInt\->bone("+"); # +1 |
| 694 |
\& $x = Math::BigInt\->bone("\-"); # \-1 |
| 695 |
\& $x\->bone(); # +1 |
| 696 |
\& $x\->bone("+"); # +1 |
| 697 |
\& $x\->bone(\*(Aq\-\*(Aq); # \-1 |
| 698 |
.Ve |
| 699 |
.Sp |
| 700 |
Creates a new Math::BigInt object representing one. The optional argument is |
| 701 |
either '\-' or '+', indicating whether you want plus one or minus one. If used |
| 702 |
as an instance method, assigns the value to the invocand. |
| 703 |
.IP \fBbinf()\fR 4 |
| 704 |
.IX Item "binf()" |
| 705 |
.Vb 1 |
| 706 |
\& $x = Math::BigInt\->binf($sign); |
| 707 |
.Ve |
| 708 |
.Sp |
| 709 |
Creates a new Math::BigInt object representing infinity. The optional argument |
| 710 |
is either '\-' or '+', indicating whether you want infinity or minus infinity. |
| 711 |
If used as an instance method, assigns the value to the invocand. |
| 712 |
.Sp |
| 713 |
.Vb 2 |
| 714 |
\& $x\->binf(); |
| 715 |
\& $x\->binf(\*(Aq\-\*(Aq); |
| 716 |
.Ve |
| 717 |
.IP \fBbnan()\fR 4 |
| 718 |
.IX Item "bnan()" |
| 719 |
.Vb 1 |
| 720 |
\& $x = Math::BigInt\->bnan(); |
| 721 |
.Ve |
| 722 |
.Sp |
| 723 |
Creates a new Math::BigInt object representing NaN (Not A Number). If used as |
| 724 |
an instance method, assigns the value to the invocand. |
| 725 |
.Sp |
| 726 |
.Vb 1 |
| 727 |
\& $x\->bnan(); |
| 728 |
.Ve |
| 729 |
.IP \fBbpi()\fR 4 |
| 730 |
.IX Item "bpi()" |
| 731 |
.Vb 2 |
| 732 |
\& $x = Math::BigInt\->bpi(100); # 3 |
| 733 |
\& $x\->bpi(100); # 3 |
| 734 |
.Ve |
| 735 |
.Sp |
| 736 |
Creates a new Math::BigInt object representing PI. If used as an instance |
| 737 |
method, assigns the value to the invocand. With Math::BigInt this always |
| 738 |
returns 3. |
| 739 |
.Sp |
| 740 |
If upgrading is in effect, returns PI, rounded to N digits with the current |
| 741 |
rounding mode: |
| 742 |
.Sp |
| 743 |
.Vb 4 |
| 744 |
\& use Math::BigFloat; |
| 745 |
\& use Math::BigInt upgrade => "Math::BigFloat"; |
| 746 |
\& print Math::BigInt\->bpi(3), "\en"; # 3.14 |
| 747 |
\& print Math::BigInt\->bpi(100), "\en"; # 3.1415.... |
| 748 |
.Ve |
| 749 |
.IP \fBcopy()\fR 4 |
| 750 |
.IX Item "copy()" |
| 751 |
.Vb 1 |
| 752 |
\& $x\->copy(); # make a true copy of $x (unlike $y = $x) |
| 753 |
.Ve |
| 754 |
.IP \fBas_int()\fR 4 |
| 755 |
.IX Item "as_int()" |
| 756 |
.PD 0 |
| 757 |
.IP \fBas_number()\fR 4 |
| 758 |
.IX Item "as_number()" |
| 759 |
.PD |
| 760 |
These methods are called when Math::BigInt encounters an object it doesn't know |
| 761 |
how to handle. For instance, assume \f(CW$x\fR is a Math::BigInt, or subclass thereof, |
| 762 |
and \f(CW$y\fR is defined, but not a Math::BigInt, or subclass thereof. If you do |
| 763 |
.Sp |
| 764 |
.Vb 1 |
| 765 |
\& $x \-> badd($y); |
| 766 |
.Ve |
| 767 |
.Sp |
| 768 |
\&\f(CW$y\fR needs to be converted into an object that \f(CW$x\fR can deal with. This is done by |
| 769 |
first checking if \f(CW$y\fR is something that \f(CW$x\fR might be upgraded to. If that is the |
| 770 |
case, no further attempts are made. The next is to see if \f(CW$y\fR supports the |
| 771 |
method \f(CWas_int()\fR. If it does, \f(CWas_int()\fR is called, but if it doesn't, the |
| 772 |
next thing is to see if \f(CW$y\fR supports the method \f(CWas_number()\fR. If it does, |
| 773 |
\&\f(CWas_number()\fR is called. The method \f(CWas_int()\fR (and \f(CWas_number()\fR) is |
| 774 |
expected to return either an object that has the same class as \f(CW$x\fR, a subclass |
| 775 |
thereof, or a string that \f(CW\*(C`ref($x)\->new()\*(C'\fR can parse to create an object. |
| 776 |
.Sp |
| 777 |
\&\f(CWas_number()\fR is an alias to \f(CWas_int()\fR. \f(CW\*(C`as_number\*(C'\fR was introduced in |
| 778 |
v1.22, while \f(CWas_int()\fR was introduced in v1.68. |
| 779 |
.Sp |
| 780 |
In Math::BigInt, \f(CWas_int()\fR has the same effect as \f(CWcopy()\fR. |
| 781 |
.IP \fBas_float()\fR 4 |
| 782 |
.IX Item "as_float()" |
| 783 |
Return the argument as a Math::BigFloat object. |
| 784 |
.IP \fBas_rat()\fR 4 |
| 785 |
.IX Item "as_rat()" |
| 786 |
Return the argument as a Math::BigRat object. |
| 787 |
.SS "Boolean methods" |
| 788 |
.IX Subsection "Boolean methods" |
| 789 |
None of these methods modify the invocand object. |
| 790 |
.IP \fBis_zero()\fR 4 |
| 791 |
.IX Item "is_zero()" |
| 792 |
.Vb 1 |
| 793 |
\& $x\->is_zero(); # true if $x is 0 |
| 794 |
.Ve |
| 795 |
.Sp |
| 796 |
Returns true if the invocand is zero and false otherwise. |
| 797 |
.IP "is_one( [ SIGN ])" 4 |
| 798 |
.IX Item "is_one( [ SIGN ])" |
| 799 |
.Vb 3 |
| 800 |
\& $x\->is_one(); # true if $x is +1 |
| 801 |
\& $x\->is_one("+"); # ditto |
| 802 |
\& $x\->is_one("\-"); # true if $x is \-1 |
| 803 |
.Ve |
| 804 |
.Sp |
| 805 |
Returns true if the invocand is one and false otherwise. |
| 806 |
.IP \fBis_finite()\fR 4 |
| 807 |
.IX Item "is_finite()" |
| 808 |
.Vb 1 |
| 809 |
\& $x\->is_finite(); # true if $x is not +inf, \-inf or NaN |
| 810 |
.Ve |
| 811 |
.Sp |
| 812 |
Returns true if the invocand is a finite number, i.e., it is neither +inf, |
| 813 |
\&\-inf, nor NaN. |
| 814 |
.IP "is_inf( [ SIGN ] )" 4 |
| 815 |
.IX Item "is_inf( [ SIGN ] )" |
| 816 |
.Vb 3 |
| 817 |
\& $x\->is_inf(); # true if $x is +inf |
| 818 |
\& $x\->is_inf("+"); # ditto |
| 819 |
\& $x\->is_inf("\-"); # true if $x is \-inf |
| 820 |
.Ve |
| 821 |
.Sp |
| 822 |
Returns true if the invocand is infinite and false otherwise. |
| 823 |
.IP \fBis_nan()\fR 4 |
| 824 |
.IX Item "is_nan()" |
| 825 |
.Vb 1 |
| 826 |
\& $x\->is_nan(); # true if $x is NaN |
| 827 |
.Ve |
| 828 |
.IP \fBis_positive()\fR 4 |
| 829 |
.IX Item "is_positive()" |
| 830 |
.PD 0 |
| 831 |
.IP \fBis_pos()\fR 4 |
| 832 |
.IX Item "is_pos()" |
| 833 |
.PD |
| 834 |
.Vb 2 |
| 835 |
\& $x\->is_positive(); # true if > 0 |
| 836 |
\& $x\->is_pos(); # ditto |
| 837 |
.Ve |
| 838 |
.Sp |
| 839 |
Returns true if the invocand is positive and false otherwise. A \f(CW\*(C`NaN\*(C'\fR is |
| 840 |
neither positive nor negative. |
| 841 |
.IP \fBis_negative()\fR 4 |
| 842 |
.IX Item "is_negative()" |
| 843 |
.PD 0 |
| 844 |
.IP \fBis_neg()\fR 4 |
| 845 |
.IX Item "is_neg()" |
| 846 |
.PD |
| 847 |
.Vb 2 |
| 848 |
\& $x\->is_negative(); # true if < 0 |
| 849 |
\& $x\->is_neg(); # ditto |
| 850 |
.Ve |
| 851 |
.Sp |
| 852 |
Returns true if the invocand is negative and false otherwise. A \f(CW\*(C`NaN\*(C'\fR is |
| 853 |
neither positive nor negative. |
| 854 |
.IP \fBis_non_positive()\fR 4 |
| 855 |
.IX Item "is_non_positive()" |
| 856 |
.Vb 1 |
| 857 |
\& $x\->is_non_positive(); # true if <= 0 |
| 858 |
.Ve |
| 859 |
.Sp |
| 860 |
Returns true if the invocand is negative or zero. |
| 861 |
.IP \fBis_non_negative()\fR 4 |
| 862 |
.IX Item "is_non_negative()" |
| 863 |
.Vb 1 |
| 864 |
\& $x\->is_non_negative(); # true if >= 0 |
| 865 |
.Ve |
| 866 |
.Sp |
| 867 |
Returns true if the invocand is positive or zero. |
| 868 |
.IP \fBis_odd()\fR 4 |
| 869 |
.IX Item "is_odd()" |
| 870 |
.Vb 1 |
| 871 |
\& $x\->is_odd(); # true if odd, false for even |
| 872 |
.Ve |
| 873 |
.Sp |
| 874 |
Returns true if the invocand is odd and false otherwise. \f(CW\*(C`NaN\*(C'\fR, \f(CW\*(C`+inf\*(C'\fR, and |
| 875 |
\&\f(CW\*(C`\-inf\*(C'\fR are neither odd nor even. |
| 876 |
.IP \fBis_even()\fR 4 |
| 877 |
.IX Item "is_even()" |
| 878 |
.Vb 1 |
| 879 |
\& $x\->is_even(); # true if $x is even |
| 880 |
.Ve |
| 881 |
.Sp |
| 882 |
Returns true if the invocand is even and false otherwise. \f(CW\*(C`NaN\*(C'\fR, \f(CW\*(C`+inf\*(C'\fR, |
| 883 |
\&\f(CW\*(C`\-inf\*(C'\fR are not integers and are neither odd nor even. |
| 884 |
.IP \fBis_int()\fR 4 |
| 885 |
.IX Item "is_int()" |
| 886 |
.Vb 1 |
| 887 |
\& $x\->is_int(); # true if $x is an integer |
| 888 |
.Ve |
| 889 |
.Sp |
| 890 |
Returns true if the invocand is an integer and false otherwise. \f(CW\*(C`NaN\*(C'\fR, |
| 891 |
\&\f(CW\*(C`+inf\*(C'\fR, \f(CW\*(C`\-inf\*(C'\fR are not integers. |
| 892 |
.SS "Comparison methods" |
| 893 |
.IX Subsection "Comparison methods" |
| 894 |
None of these methods modify the invocand object. Note that a \f(CW\*(C`NaN\*(C'\fR is neither |
| 895 |
less than, greater than, or equal to anything else, even a \f(CW\*(C`NaN\*(C'\fR. |
| 896 |
.IP \fBbcmp()\fR 4 |
| 897 |
.IX Item "bcmp()" |
| 898 |
.Vb 1 |
| 899 |
\& $x\->bcmp($y); |
| 900 |
.Ve |
| 901 |
.Sp |
| 902 |
Returns \-1, 0, 1 depending on whether \f(CW$x\fR is less than, equal to, or grater than |
| 903 |
\&\f(CW$y\fR. Returns undef if any operand is a NaN. |
| 904 |
.IP \fBbacmp()\fR 4 |
| 905 |
.IX Item "bacmp()" |
| 906 |
.Vb 1 |
| 907 |
\& $x\->bacmp($y); |
| 908 |
.Ve |
| 909 |
.Sp |
| 910 |
Returns \-1, 0, 1 depending on whether the absolute value of \f(CW$x\fR is less than, |
| 911 |
equal to, or grater than the absolute value of \f(CW$y\fR. Returns undef if any operand |
| 912 |
is a NaN. |
| 913 |
.IP \fBbeq()\fR 4 |
| 914 |
.IX Item "beq()" |
| 915 |
.Vb 1 |
| 916 |
\& $x \-> beq($y); |
| 917 |
.Ve |
| 918 |
.Sp |
| 919 |
Returns true if and only if \f(CW$x\fR is equal to \f(CW$y\fR, and false otherwise. |
| 920 |
.IP \fBbne()\fR 4 |
| 921 |
.IX Item "bne()" |
| 922 |
.Vb 1 |
| 923 |
\& $x \-> bne($y); |
| 924 |
.Ve |
| 925 |
.Sp |
| 926 |
Returns true if and only if \f(CW$x\fR is not equal to \f(CW$y\fR, and false otherwise. |
| 927 |
.IP \fBblt()\fR 4 |
| 928 |
.IX Item "blt()" |
| 929 |
.Vb 1 |
| 930 |
\& $x \-> blt($y); |
| 931 |
.Ve |
| 932 |
.Sp |
| 933 |
Returns true if and only if \f(CW$x\fR is equal to \f(CW$y\fR, and false otherwise. |
| 934 |
.IP \fBble()\fR 4 |
| 935 |
.IX Item "ble()" |
| 936 |
.Vb 1 |
| 937 |
\& $x \-> ble($y); |
| 938 |
.Ve |
| 939 |
.Sp |
| 940 |
Returns true if and only if \f(CW$x\fR is less than or equal to \f(CW$y\fR, and false |
| 941 |
otherwise. |
| 942 |
.IP \fBbgt()\fR 4 |
| 943 |
.IX Item "bgt()" |
| 944 |
.Vb 1 |
| 945 |
\& $x \-> bgt($y); |
| 946 |
.Ve |
| 947 |
.Sp |
| 948 |
Returns true if and only if \f(CW$x\fR is greater than \f(CW$y\fR, and false otherwise. |
| 949 |
.IP \fBbge()\fR 4 |
| 950 |
.IX Item "bge()" |
| 951 |
.Vb 1 |
| 952 |
\& $x \-> bge($y); |
| 953 |
.Ve |
| 954 |
.Sp |
| 955 |
Returns true if and only if \f(CW$x\fR is greater than or equal to \f(CW$y\fR, and false |
| 956 |
otherwise. |
| 957 |
.SS "Arithmetic methods" |
| 958 |
.IX Subsection "Arithmetic methods" |
| 959 |
These methods modify the invocand object and returns it. |
| 960 |
.IP \fBbneg()\fR 4 |
| 961 |
.IX Item "bneg()" |
| 962 |
.Vb 1 |
| 963 |
\& $x\->bneg(); |
| 964 |
.Ve |
| 965 |
.Sp |
| 966 |
Negate the number, e.g. change the sign between '+' and '\-', or between '+inf' |
| 967 |
and '\-inf', respectively. Does nothing for NaN or zero. |
| 968 |
.IP \fBbabs()\fR 4 |
| 969 |
.IX Item "babs()" |
| 970 |
.Vb 1 |
| 971 |
\& $x\->babs(); |
| 972 |
.Ve |
| 973 |
.Sp |
| 974 |
Set the number to its absolute value, e.g. change the sign from '\-' to '+' |
| 975 |
and from '\-inf' to '+inf', respectively. Does nothing for NaN or positive |
| 976 |
numbers. |
| 977 |
.IP \fBbsgn()\fR 4 |
| 978 |
.IX Item "bsgn()" |
| 979 |
.Vb 1 |
| 980 |
\& $x\->bsgn(); |
| 981 |
.Ve |
| 982 |
.Sp |
| 983 |
Signum function. Set the number to \-1, 0, or 1, depending on whether the |
| 984 |
number is negative, zero, or positive, respectively. Does not modify NaNs. |
| 985 |
.IP \fBbnorm()\fR 4 |
| 986 |
.IX Item "bnorm()" |
| 987 |
.Vb 1 |
| 988 |
\& $x\->bnorm(); # normalize (no\-op) |
| 989 |
.Ve |
| 990 |
.Sp |
| 991 |
Normalize the number. This is a no-op and is provided only for backwards |
| 992 |
compatibility. |
| 993 |
.IP \fBbinc()\fR 4 |
| 994 |
.IX Item "binc()" |
| 995 |
.Vb 1 |
| 996 |
\& $x\->binc(); # increment x by 1 |
| 997 |
.Ve |
| 998 |
.IP \fBbdec()\fR 4 |
| 999 |
.IX Item "bdec()" |
| 1000 |
.Vb 1 |
| 1001 |
\& $x\->bdec(); # decrement x by 1 |
| 1002 |
.Ve |
| 1003 |
.IP \fBbadd()\fR 4 |
| 1004 |
.IX Item "badd()" |
| 1005 |
.Vb 1 |
| 1006 |
\& $x\->badd($y); # addition (add $y to $x) |
| 1007 |
.Ve |
| 1008 |
.IP \fBbsub()\fR 4 |
| 1009 |
.IX Item "bsub()" |
| 1010 |
.Vb 1 |
| 1011 |
\& $x\->bsub($y); # subtraction (subtract $y from $x) |
| 1012 |
.Ve |
| 1013 |
.IP \fBbmul()\fR 4 |
| 1014 |
.IX Item "bmul()" |
| 1015 |
.Vb 1 |
| 1016 |
\& $x\->bmul($y); # multiplication (multiply $x by $y) |
| 1017 |
.Ve |
| 1018 |
.IP \fBbmuladd()\fR 4 |
| 1019 |
.IX Item "bmuladd()" |
| 1020 |
.Vb 1 |
| 1021 |
\& $x\->bmuladd($y,$z); |
| 1022 |
.Ve |
| 1023 |
.Sp |
| 1024 |
Multiply \f(CW$x\fR by \f(CW$y\fR, and then add \f(CW$z\fR to the result, |
| 1025 |
.Sp |
| 1026 |
This method was added in v1.87 of Math::BigInt (June 2007). |
| 1027 |
.IP \fBbinv()\fR 4 |
| 1028 |
.IX Item "binv()" |
| 1029 |
.Vb 1 |
| 1030 |
\& $x\->binv(); |
| 1031 |
.Ve |
| 1032 |
.Sp |
| 1033 |
Invert the value of \f(CW$x\fR, i.e., compute 1/$x. |
| 1034 |
.IP \fBbdiv()\fR 4 |
| 1035 |
.IX Item "bdiv()" |
| 1036 |
.Vb 1 |
| 1037 |
\& $x\->bdiv($y); # divide, set $x to quotient |
| 1038 |
.Ve |
| 1039 |
.Sp |
| 1040 |
Divides \f(CW$x\fR by \f(CW$y\fR by doing floored division (F\-division), where the quotient is |
| 1041 |
the floored (rounded towards negative infinity) quotient of the two operands. |
| 1042 |
In list context, returns the quotient and the remainder. The remainder is |
| 1043 |
either zero or has the same sign as the second operand. In scalar context, only |
| 1044 |
the quotient is returned. |
| 1045 |
.Sp |
| 1046 |
The quotient is always the greatest integer less than or equal to the |
| 1047 |
real-valued quotient of the two operands, and the remainder (when it is |
| 1048 |
non-zero) always has the same sign as the second operand; so, for example, |
| 1049 |
.Sp |
| 1050 |
.Vb 6 |
| 1051 |
\& 1 / 4 => ( 0, 1) |
| 1052 |
\& 1 / \-4 => (\-1, \-3) |
| 1053 |
\& \-3 / 4 => (\-1, 1) |
| 1054 |
\& \-3 / \-4 => ( 0, \-3) |
| 1055 |
\& \-11 / 2 => (\-5, 1) |
| 1056 |
\& 11 / \-2 => (\-5, \-1) |
| 1057 |
.Ve |
| 1058 |
.Sp |
| 1059 |
The behavior of the overloaded operator % agrees with the behavior of Perl's |
| 1060 |
built-in % operator (as documented in the perlop manpage), and the equation |
| 1061 |
.Sp |
| 1062 |
.Vb 1 |
| 1063 |
\& $x == ($x / $y) * $y + ($x % $y) |
| 1064 |
.Ve |
| 1065 |
.Sp |
| 1066 |
holds true for any finite \f(CW$x\fR and finite, non-zero \f(CW$y\fR. |
| 1067 |
.Sp |
| 1068 |
Perl's "use integer" might change the behaviour of % and / for scalars. This is |
| 1069 |
because under 'use integer' Perl does what the underlying C library thinks is |
| 1070 |
right, and this varies. However, "use integer" does not change the way things |
| 1071 |
are done with Math::BigInt objects. |
| 1072 |
.IP \fBbtdiv()\fR 4 |
| 1073 |
.IX Item "btdiv()" |
| 1074 |
.Vb 1 |
| 1075 |
\& $x\->btdiv($y); # divide, set $x to quotient |
| 1076 |
.Ve |
| 1077 |
.Sp |
| 1078 |
Divides \f(CW$x\fR by \f(CW$y\fR by doing truncated division (T\-division), where quotient is |
| 1079 |
the truncated (rouneded towards zero) quotient of the two operands. In list |
| 1080 |
context, returns the quotient and the remainder. The remainder is either zero |
| 1081 |
or has the same sign as the first operand. In scalar context, only the quotient |
| 1082 |
is returned. |
| 1083 |
.IP \fBbmod()\fR 4 |
| 1084 |
.IX Item "bmod()" |
| 1085 |
.Vb 1 |
| 1086 |
\& $x\->bmod($y); # modulus (x % y) |
| 1087 |
.Ve |
| 1088 |
.Sp |
| 1089 |
Returns \f(CW$x\fR modulo \f(CW$y\fR, i.e., the remainder after floored division (F\-division). |
| 1090 |
This method is like Perl's % operator. See "\fBbdiv()\fR". |
| 1091 |
.IP \fBbtmod()\fR 4 |
| 1092 |
.IX Item "btmod()" |
| 1093 |
.Vb 1 |
| 1094 |
\& $x\->btmod($y); # modulus |
| 1095 |
.Ve |
| 1096 |
.Sp |
| 1097 |
Returns the remainer after truncated division (T\-division). See "\fBbtdiv()\fR". |
| 1098 |
.IP \fBbmodinv()\fR 4 |
| 1099 |
.IX Item "bmodinv()" |
| 1100 |
.Vb 1 |
| 1101 |
\& $x\->bmodinv($mod); # modular multiplicative inverse |
| 1102 |
.Ve |
| 1103 |
.Sp |
| 1104 |
Returns the multiplicative inverse of \f(CW$x\fR modulo \f(CW$mod\fR. If |
| 1105 |
.Sp |
| 1106 |
.Vb 1 |
| 1107 |
\& $y = $x \-> copy() \-> bmodinv($mod) |
| 1108 |
.Ve |
| 1109 |
.Sp |
| 1110 |
then \f(CW$y\fR is the number closest to zero, and with the same sign as \f(CW$mod\fR, |
| 1111 |
satisfying |
| 1112 |
.Sp |
| 1113 |
.Vb 1 |
| 1114 |
\& ($x * $y) % $mod = 1 % $mod |
| 1115 |
.Ve |
| 1116 |
.Sp |
| 1117 |
If \f(CW$x\fR and \f(CW$y\fR are non-zero, they must be relative primes, i.e., |
| 1118 |
\&\f(CW\*(C`bgcd($y, $mod)==1\*(C'\fR. '\f(CW\*(C`NaN\*(C'\fR' is returned when no modular multiplicative |
| 1119 |
inverse exists. |
| 1120 |
.IP \fBbmodpow()\fR 4 |
| 1121 |
.IX Item "bmodpow()" |
| 1122 |
.Vb 2 |
| 1123 |
\& $num\->bmodpow($exp,$mod); # modular exponentiation |
| 1124 |
\& # ($num**$exp % $mod) |
| 1125 |
.Ve |
| 1126 |
.Sp |
| 1127 |
Returns the value of \f(CW$num\fR taken to the power \f(CW$exp\fR in the modulus |
| 1128 |
\&\f(CW$mod\fR using binary exponentiation. \f(CW\*(C`bmodpow\*(C'\fR is far superior to |
| 1129 |
writing |
| 1130 |
.Sp |
| 1131 |
.Vb 1 |
| 1132 |
\& $num ** $exp % $mod |
| 1133 |
.Ve |
| 1134 |
.Sp |
| 1135 |
because it is much faster \- it reduces internal variables into |
| 1136 |
the modulus whenever possible, so it operates on smaller numbers. |
| 1137 |
.Sp |
| 1138 |
\&\f(CW\*(C`bmodpow\*(C'\fR also supports negative exponents. |
| 1139 |
.Sp |
| 1140 |
.Vb 1 |
| 1141 |
\& bmodpow($num, \-1, $mod) |
| 1142 |
.Ve |
| 1143 |
.Sp |
| 1144 |
is exactly equivalent to |
| 1145 |
.Sp |
| 1146 |
.Vb 1 |
| 1147 |
\& bmodinv($num, $mod) |
| 1148 |
.Ve |
| 1149 |
.IP \fBbpow()\fR 4 |
| 1150 |
.IX Item "bpow()" |
| 1151 |
.Vb 1 |
| 1152 |
\& $x\->bpow($y); # power of arguments (x ** y) |
| 1153 |
.Ve |
| 1154 |
.Sp |
| 1155 |
\&\f(CWbpow()\fR (and the rounding functions) now modifies the first argument and |
| 1156 |
returns it, unlike the old code which left it alone and only returned the |
| 1157 |
result. This is to be consistent with \f(CWbadd()\fR etc. The first three modifies |
| 1158 |
\&\f(CW$x\fR, the last one won't: |
| 1159 |
.Sp |
| 1160 |
.Vb 4 |
| 1161 |
\& print bpow($x,$i),"\en"; # modify $x |
| 1162 |
\& print $x\->bpow($i),"\en"; # ditto |
| 1163 |
\& print $x **= $i,"\en"; # the same |
| 1164 |
\& print $x ** $i,"\en"; # leave $x alone |
| 1165 |
.Ve |
| 1166 |
.Sp |
| 1167 |
The form \f(CW\*(C`$x **= $y\*(C'\fR is faster than \f(CW\*(C`$x = $x ** $y;\*(C'\fR, though. |
| 1168 |
.IP \fBblog()\fR 4 |
| 1169 |
.IX Item "blog()" |
| 1170 |
.Vb 1 |
| 1171 |
\& $x\->blog($base, $accuracy); # logarithm of x to the base $base |
| 1172 |
.Ve |
| 1173 |
.Sp |
| 1174 |
If \f(CW$base\fR is not defined, Euler's number (e) is used: |
| 1175 |
.Sp |
| 1176 |
.Vb 1 |
| 1177 |
\& print $x\->blog(undef, 100); # log(x) to 100 digits |
| 1178 |
.Ve |
| 1179 |
.IP \fBbexp()\fR 4 |
| 1180 |
.IX Item "bexp()" |
| 1181 |
.Vb 1 |
| 1182 |
\& $x\->bexp($accuracy); # calculate e ** X |
| 1183 |
.Ve |
| 1184 |
.Sp |
| 1185 |
Calculates the expression \f(CW\*(C`e ** $x\*(C'\fR where \f(CW\*(C`e\*(C'\fR is Euler's number. |
| 1186 |
.Sp |
| 1187 |
This method was added in v1.82 of Math::BigInt (April 2007). |
| 1188 |
.Sp |
| 1189 |
See also "\fBblog()\fR". |
| 1190 |
.IP \fBbilog2()\fR 4 |
| 1191 |
.IX Item "bilog2()" |
| 1192 |
Base 2 logarithm rounded down towards the nearest integer. |
| 1193 |
.Sp |
| 1194 |
.Vb 1 |
| 1195 |
\& $x\->bilog2(); # int(log2(x)) = int(log(x)/log(2)) |
| 1196 |
.Ve |
| 1197 |
.Sp |
| 1198 |
In list context a second argument is returned. This is 1 if the result is |
| 1199 |
exact, i.e., the input is an exact power of 2, and 0 otherwise. |
| 1200 |
.IP \fBbilog10()\fR 4 |
| 1201 |
.IX Item "bilog10()" |
| 1202 |
Base 10 logarithm rounded down towards the nearest integer. |
| 1203 |
.Sp |
| 1204 |
.Vb 1 |
| 1205 |
\& $x\->bilog10(); # int(log10(x)) = int(log(x)/log(10)) |
| 1206 |
.Ve |
| 1207 |
.Sp |
| 1208 |
In list context a second argument is returned. This is 1 if the result is |
| 1209 |
exact, i.e., the input is an exact power of 10, and 0 otherwise. |
| 1210 |
.IP \fBbclog2()\fR 4 |
| 1211 |
.IX Item "bclog2()" |
| 1212 |
Base 2 logarithm rounded up towards the nearest integer. |
| 1213 |
.Sp |
| 1214 |
.Vb 1 |
| 1215 |
\& $x\->bclog2(); # ceil(log2(x)) = ceil(log(x)/log(2)) |
| 1216 |
.Ve |
| 1217 |
.Sp |
| 1218 |
In list context a second argument is returned. This is 1 if the result is |
| 1219 |
exact, i.e., the input is an exact power of 2, and 0 otherwise. |
| 1220 |
.IP \fBbclog10()\fR 4 |
| 1221 |
.IX Item "bclog10()" |
| 1222 |
Base 10 logarithm rounded up towards the nearest integer. |
| 1223 |
.Sp |
| 1224 |
.Vb 1 |
| 1225 |
\& $x\->bclog10(); # ceil(log10(x)) = ceil(log(x)/log(10)) |
| 1226 |
.Ve |
| 1227 |
.Sp |
| 1228 |
In list context a second argument is returned. This is 1 if the result is |
| 1229 |
exact, i.e., the input is an exact power of 10, and 0 otherwise. |
| 1230 |
.IP \fBbnok()\fR 4 |
| 1231 |
.IX Item "bnok()" |
| 1232 |
.Vb 1 |
| 1233 |
\& $x\->bnok($y); # x over y (binomial coefficient n over k) |
| 1234 |
.Ve |
| 1235 |
.Sp |
| 1236 |
Calculates the binomial coefficient n over k, also called the "choose" |
| 1237 |
function, which is |
| 1238 |
.Sp |
| 1239 |
.Vb 3 |
| 1240 |
\& ( n ) n! |
| 1241 |
\& | | = \-\-\-\-\-\-\-\- |
| 1242 |
\& ( k ) k!(n\-k)! |
| 1243 |
.Ve |
| 1244 |
.Sp |
| 1245 |
when n and k are non-negative. This method implements the full Kronenburg |
| 1246 |
extension (Kronenburg, M.J. "The Binomial Coefficient for Negative Arguments." |
| 1247 |
18 May 2011. http://arxiv.org/abs/1105.3689/) illustrated by the following |
| 1248 |
pseudo-code: |
| 1249 |
.Sp |
| 1250 |
.Vb 8 |
| 1251 |
\& if n >= 0 and k >= 0: |
| 1252 |
\& return binomial(n, k) |
| 1253 |
\& if k >= 0: |
| 1254 |
\& return (\-1)^k*binomial(\-n+k\-1, k) |
| 1255 |
\& if k <= n: |
| 1256 |
\& return (\-1)^(n\-k)*binomial(\-k\-1, n\-k) |
| 1257 |
\& else |
| 1258 |
\& return 0 |
| 1259 |
.Ve |
| 1260 |
.Sp |
| 1261 |
The behaviour is identical to the behaviour of the Maple and Mathematica |
| 1262 |
function for negative integers n, k. |
| 1263 |
.IP \fBbuparrow()\fR 4 |
| 1264 |
.IX Item "buparrow()" |
| 1265 |
.PD 0 |
| 1266 |
.IP \fBuparrow()\fR 4 |
| 1267 |
.IX Item "uparrow()" |
| 1268 |
.PD |
| 1269 |
.Vb 2 |
| 1270 |
\& $a \-> buparrow($n, $b); # modifies $a |
| 1271 |
\& $x = $a \-> uparrow($n, $b); # does not modify $a |
| 1272 |
.Ve |
| 1273 |
.Sp |
| 1274 |
This method implements Knuth's up-arrow notation, where \f(CW$n\fR is a non-negative |
| 1275 |
integer representing the number of up-arrows. \f(CW$n\fR = 0 gives multiplication, \f(CW$n\fR = |
| 1276 |
1 gives exponentiation, \f(CW$n\fR = 2 gives tetration, \f(CW$n\fR = 3 gives hexation etc. The |
| 1277 |
following illustrates the relation between the first values of \f(CW$n\fR. |
| 1278 |
.Sp |
| 1279 |
See <https://en.wikipedia.org/wiki/Knuth%27s_up\-arrow_notation>. |
| 1280 |
.IP \fBbackermann()\fR 4 |
| 1281 |
.IX Item "backermann()" |
| 1282 |
.PD 0 |
| 1283 |
.IP \fBackermann()\fR 4 |
| 1284 |
.IX Item "ackermann()" |
| 1285 |
.PD |
| 1286 |
.Vb 2 |
| 1287 |
\& $m \-> backermann($n); # modifies $a |
| 1288 |
\& $x = $m \-> ackermann($n); # does not modify $a |
| 1289 |
.Ve |
| 1290 |
.Sp |
| 1291 |
This method implements the Ackermann function: |
| 1292 |
.Sp |
| 1293 |
.Vb 3 |
| 1294 |
\& / n + 1 if m = 0 |
| 1295 |
\& A(m, n) = | A(m\-1, 1) if m > 0 and n = 0 |
| 1296 |
\& \e A(m\-1, A(m, n\-1)) if m > 0 and n > 0 |
| 1297 |
.Ve |
| 1298 |
.Sp |
| 1299 |
Its value grows rapidly, even for small inputs. For example, A(4, 2) is an |
| 1300 |
integer of 19729 decimal digits. |
| 1301 |
.Sp |
| 1302 |
See https://en.wikipedia.org/wiki/Ackermann_function |
| 1303 |
.IP \fBbsin()\fR 4 |
| 1304 |
.IX Item "bsin()" |
| 1305 |
.Vb 2 |
| 1306 |
\& my $x = Math::BigInt\->new(1); |
| 1307 |
\& print $x\->bsin(100), "\en"; |
| 1308 |
.Ve |
| 1309 |
.Sp |
| 1310 |
Calculate the sine of \f(CW$x\fR, modifying \f(CW$x\fR in place. |
| 1311 |
.Sp |
| 1312 |
In Math::BigInt, unless upgrading is in effect, the result is truncated to an |
| 1313 |
integer. |
| 1314 |
.Sp |
| 1315 |
This method was added in v1.87 of Math::BigInt (June 2007). |
| 1316 |
.IP \fBbcos()\fR 4 |
| 1317 |
.IX Item "bcos()" |
| 1318 |
.Vb 2 |
| 1319 |
\& my $x = Math::BigInt\->new(1); |
| 1320 |
\& print $x\->bcos(100), "\en"; |
| 1321 |
.Ve |
| 1322 |
.Sp |
| 1323 |
Calculate the cosine of \f(CW$x\fR, modifying \f(CW$x\fR in place. |
| 1324 |
.Sp |
| 1325 |
In Math::BigInt, unless upgrading is in effect, the result is truncated to an |
| 1326 |
integer. |
| 1327 |
.Sp |
| 1328 |
This method was added in v1.87 of Math::BigInt (June 2007). |
| 1329 |
.IP \fBbatan()\fR 4 |
| 1330 |
.IX Item "batan()" |
| 1331 |
.Vb 2 |
| 1332 |
\& my $x = Math::BigFloat\->new(0.5); |
| 1333 |
\& print $x\->batan(100), "\en"; |
| 1334 |
.Ve |
| 1335 |
.Sp |
| 1336 |
Calculate the arcus tangens of \f(CW$x\fR, modifying \f(CW$x\fR in place. |
| 1337 |
.Sp |
| 1338 |
In Math::BigInt, unless upgrading is in effect, the result is truncated to an |
| 1339 |
integer. |
| 1340 |
.Sp |
| 1341 |
This method was added in v1.87 of Math::BigInt (June 2007). |
| 1342 |
.IP \fBbatan2()\fR 4 |
| 1343 |
.IX Item "batan2()" |
| 1344 |
.Vb 3 |
| 1345 |
\& my $x = Math::BigInt\->new(1); |
| 1346 |
\& my $y = Math::BigInt\->new(1); |
| 1347 |
\& print $y\->batan2($x), "\en"; |
| 1348 |
.Ve |
| 1349 |
.Sp |
| 1350 |
Calculate the arcus tangens of \f(CW$y\fR divided by \f(CW$x\fR, modifying \f(CW$y\fR in place. |
| 1351 |
.Sp |
| 1352 |
In Math::BigInt, unless upgrading is in effect, the result is truncated to an |
| 1353 |
integer. |
| 1354 |
.Sp |
| 1355 |
This method was added in v1.87 of Math::BigInt (June 2007). |
| 1356 |
.IP \fBbsqrt()\fR 4 |
| 1357 |
.IX Item "bsqrt()" |
| 1358 |
.Vb 1 |
| 1359 |
\& $x\->bsqrt(); # calculate square root |
| 1360 |
.Ve |
| 1361 |
.Sp |
| 1362 |
\&\f(CWbsqrt()\fR returns the square root truncated to an integer. |
| 1363 |
.Sp |
| 1364 |
If you want a better approximation of the square root, then use: |
| 1365 |
.Sp |
| 1366 |
.Vb 4 |
| 1367 |
\& $x = Math::BigFloat\->new(12); |
| 1368 |
\& Math::BigFloat\->precision(0); |
| 1369 |
\& Math::BigFloat\->round_mode(\*(Aqeven\*(Aq); |
| 1370 |
\& print $x\->copy\->bsqrt(),"\en"; # 4 |
| 1371 |
\& |
| 1372 |
\& Math::BigFloat\->precision(2); |
| 1373 |
\& print $x\->bsqrt(),"\en"; # 3.46 |
| 1374 |
\& print $x\->bsqrt(3),"\en"; # 3.464 |
| 1375 |
.Ve |
| 1376 |
.IP \fBbroot()\fR 4 |
| 1377 |
.IX Item "broot()" |
| 1378 |
.Vb 1 |
| 1379 |
\& $x\->broot($N); |
| 1380 |
.Ve |
| 1381 |
.Sp |
| 1382 |
Calculates the N'th root of \f(CW$x\fR. |
| 1383 |
.IP \fBbfac()\fR 4 |
| 1384 |
.IX Item "bfac()" |
| 1385 |
.Vb 1 |
| 1386 |
\& $x\->bfac(); # factorial of $x |
| 1387 |
.Ve |
| 1388 |
.Sp |
| 1389 |
Returns the factorial of \f(CW$x\fR, i.e., \f(CW$x\fR*($x\-1)*($x\-2)*...*2*1, the product of |
| 1390 |
all positive integers up to and including \f(CW$x\fR. \f(CW$x\fR must be > \-1. The |
| 1391 |
factorial of N is commonly written as N!, or N!1, when using the multifactorial |
| 1392 |
notation. |
| 1393 |
.IP \fBbdfac()\fR 4 |
| 1394 |
.IX Item "bdfac()" |
| 1395 |
.Vb 1 |
| 1396 |
\& $x\->bdfac(); # double factorial of $x |
| 1397 |
.Ve |
| 1398 |
.Sp |
| 1399 |
Returns the double factorial of \f(CW$x\fR, i.e., \f(CW$x\fR*($x\-2)*($x\-4)*... \f(CW$x\fR must be |
| 1400 |
> \-2. The double factorial of N is commonly written as N!!, or N!2, when using |
| 1401 |
the multifactorial notation. |
| 1402 |
.IP \fBbtfac()\fR 4 |
| 1403 |
.IX Item "btfac()" |
| 1404 |
.Vb 1 |
| 1405 |
\& $x\->btfac(); # triple factorial of $x |
| 1406 |
.Ve |
| 1407 |
.Sp |
| 1408 |
Returns the triple factorial of \f(CW$x\fR, i.e., \f(CW$x\fR*($x\-3)*($x\-6)*... \f(CW$x\fR must be |
| 1409 |
> \-3. The triple factorial of N is commonly written as N!!!, or N!3, when using |
| 1410 |
the multifactorial notation. |
| 1411 |
.IP \fBbmfac()\fR 4 |
| 1412 |
.IX Item "bmfac()" |
| 1413 |
.Vb 1 |
| 1414 |
\& $x\->bmfac($k); # $k\*(Aqth multifactorial of $x |
| 1415 |
.Ve |
| 1416 |
.Sp |
| 1417 |
Returns the multi-factorial of \f(CW$x\fR, i.e., \f(CW$x\fR*($x\-$k)*($x\-2*$k)*... \f(CW$x\fR must |
| 1418 |
be > \-$k. The multi-factorial of N is commonly written as N!K. |
| 1419 |
.IP \fBbfib()\fR 4 |
| 1420 |
.IX Item "bfib()" |
| 1421 |
.Vb 2 |
| 1422 |
\& $F = $n\->bfib(); # a single Fibonacci number |
| 1423 |
\& @F = $n\->bfib(); # a list of Fibonacci numbers |
| 1424 |
.Ve |
| 1425 |
.Sp |
| 1426 |
In scalar context, returns a single Fibonacci number. In list context, returns |
| 1427 |
a list of Fibonacci numbers. The invocand is the last element in the output. |
| 1428 |
.Sp |
| 1429 |
The Fibonacci sequence is defined by |
| 1430 |
.Sp |
| 1431 |
.Vb 3 |
| 1432 |
\& F(0) = 0 |
| 1433 |
\& F(1) = 1 |
| 1434 |
\& F(n) = F(n\-1) + F(n\-2) |
| 1435 |
.Ve |
| 1436 |
.Sp |
| 1437 |
In list context, F(0) and F(n) is the first and last number in the output, |
| 1438 |
respectively. For example, if \f(CW$n\fR is 12, then \f(CW\*(C`@F = $n\->bfib()\*(C'\fR returns the |
| 1439 |
following values, F(0) to F(12): |
| 1440 |
.Sp |
| 1441 |
.Vb 1 |
| 1442 |
\& 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144 |
| 1443 |
.Ve |
| 1444 |
.Sp |
| 1445 |
The sequence can also be extended to negative index n using the re-arranged |
| 1446 |
recurrence relation |
| 1447 |
.Sp |
| 1448 |
.Vb 1 |
| 1449 |
\& F(n\-2) = F(n) \- F(n\-1) |
| 1450 |
.Ve |
| 1451 |
.Sp |
| 1452 |
giving the bidirectional sequence |
| 1453 |
.Sp |
| 1454 |
.Vb 2 |
| 1455 |
\& n \-7 \-6 \-5 \-4 \-3 \-2 \-1 0 1 2 3 4 5 6 7 |
| 1456 |
\& F(n) 13 \-8 5 \-3 2 \-1 1 0 1 1 2 3 5 8 13 |
| 1457 |
.Ve |
| 1458 |
.Sp |
| 1459 |
If \f(CW$n\fR is \-12, the following values, F(0) to F(12), are returned: |
| 1460 |
.Sp |
| 1461 |
.Vb 1 |
| 1462 |
\& 0, 1, \-1, 2, \-3, 5, \-8, 13, \-21, 34, \-55, 89, \-144 |
| 1463 |
.Ve |
| 1464 |
.IP \fBblucas()\fR 4 |
| 1465 |
.IX Item "blucas()" |
| 1466 |
.Vb 2 |
| 1467 |
\& $F = $n\->blucas(); # a single Lucas number |
| 1468 |
\& @F = $n\->blucas(); # a list of Lucas numbers |
| 1469 |
.Ve |
| 1470 |
.Sp |
| 1471 |
In scalar context, returns a single Lucas number. In list context, returns a |
| 1472 |
list of Lucas numbers. The invocand is the last element in the output. |
| 1473 |
.Sp |
| 1474 |
The Lucas sequence is defined by |
| 1475 |
.Sp |
| 1476 |
.Vb 3 |
| 1477 |
\& L(0) = 2 |
| 1478 |
\& L(1) = 1 |
| 1479 |
\& L(n) = L(n\-1) + L(n\-2) |
| 1480 |
.Ve |
| 1481 |
.Sp |
| 1482 |
In list context, L(0) and L(n) is the first and last number in the output, |
| 1483 |
respectively. For example, if \f(CW$n\fR is 12, then \f(CW\*(C`@L = $n\->blucas()\*(C'\fR returns |
| 1484 |
the following values, L(0) to L(12): |
| 1485 |
.Sp |
| 1486 |
.Vb 1 |
| 1487 |
\& 2, 1, 3, 4, 7, 11, 18, 29, 47, 76, 123, 199, 322 |
| 1488 |
.Ve |
| 1489 |
.Sp |
| 1490 |
The sequence can also be extended to negative index n using the re-arranged |
| 1491 |
recurrence relation |
| 1492 |
.Sp |
| 1493 |
.Vb 1 |
| 1494 |
\& L(n\-2) = L(n) \- L(n\-1) |
| 1495 |
.Ve |
| 1496 |
.Sp |
| 1497 |
giving the bidirectional sequence |
| 1498 |
.Sp |
| 1499 |
.Vb 2 |
| 1500 |
\& n \-7 \-6 \-5 \-4 \-3 \-2 \-1 0 1 2 3 4 5 6 7 |
| 1501 |
\& L(n) 29 \-18 11 \-7 4 \-3 1 2 1 3 4 7 11 18 29 |
| 1502 |
.Ve |
| 1503 |
.Sp |
| 1504 |
If \f(CW$n\fR is \-12, the following values, L(0) to L(\-12), are returned: |
| 1505 |
.Sp |
| 1506 |
.Vb 1 |
| 1507 |
\& 2, 1, \-3, 4, \-7, 11, \-18, 29, \-47, 76, \-123, 199, \-322 |
| 1508 |
.Ve |
| 1509 |
.IP \fBbrsft()\fR 4 |
| 1510 |
.IX Item "brsft()" |
| 1511 |
Right shift. |
| 1512 |
.Sp |
| 1513 |
.Vb 2 |
| 1514 |
\& $x\->brsft($n); # right shift $n places in base 2 |
| 1515 |
\& $x\->brsft($n, $b); # right shift $n places in base $b |
| 1516 |
.Ve |
| 1517 |
.Sp |
| 1518 |
The latter is equivalent to |
| 1519 |
.Sp |
| 1520 |
.Vb 1 |
| 1521 |
\& $x \-> bdiv($b \-> copy() \-> bpow($n)); |
| 1522 |
.Ve |
| 1523 |
.IP \fBblsft()\fR 4 |
| 1524 |
.IX Item "blsft()" |
| 1525 |
Left shift. |
| 1526 |
.Sp |
| 1527 |
.Vb 2 |
| 1528 |
\& $x\->blsft($n); # left shift $n places in base 2 |
| 1529 |
\& $x\->blsft($n, $b); # left shift $n places in base $b |
| 1530 |
.Ve |
| 1531 |
.Sp |
| 1532 |
The latter is equivalent to |
| 1533 |
.Sp |
| 1534 |
.Vb 1 |
| 1535 |
\& $x \-> bmul($b \-> copy() \-> bpow($n)); |
| 1536 |
.Ve |
| 1537 |
.SS "Bitwise methods" |
| 1538 |
.IX Subsection "Bitwise methods" |
| 1539 |
For all bitwise methods, the operands are truncated to integers, i.e., rounded |
| 1540 |
towards zero, if necessary, before the method is applied. The bitwise methods |
| 1541 |
never upgrade, and they always return an integer. |
| 1542 |
.IP \fBbbrsft()\fR 4 |
| 1543 |
.IX Item "bbrsft()" |
| 1544 |
Bitwise right shift. This is equivalent to Perl's \f(CW\*(C`>>\*(C'\fR operator. |
| 1545 |
.Sp |
| 1546 |
.Vb 1 |
| 1547 |
\& $x \-> bbrsft($n); # right shift $n places in base 2 |
| 1548 |
.Ve |
| 1549 |
.Sp |
| 1550 |
If \f(CW$n\fR is negative, the shifting is done in the opposite direction, so these |
| 1551 |
two are equivalent for all \f(CW$x\fR and \f(CW$n\fR |
| 1552 |
.Sp |
| 1553 |
.Vb 2 |
| 1554 |
\& $y = $x \-> bbrsft($n); |
| 1555 |
\& $y = $x \-> bblsft(\-$n); |
| 1556 |
.Ve |
| 1557 |
.Sp |
| 1558 |
and also equivalent to |
| 1559 |
.Sp |
| 1560 |
.Vb 2 |
| 1561 |
\& $y = $x \-> bdiv(ref($x) \-> new(2) \-> bpow($n)); # if $n > 0 |
| 1562 |
\& $y = $x \-> bmul(ref($x) \-> new(2) \-> bpow(\-$n)); # if $n < 0 |
| 1563 |
.Ve |
| 1564 |
.IP \fBbblsft()\fR 4 |
| 1565 |
.IX Item "bblsft()" |
| 1566 |
Bitwise left shift. This is equivalent to Perl's \f(CW\*(C`<<\*(C'\fR operator. |
| 1567 |
.Sp |
| 1568 |
.Vb 1 |
| 1569 |
\& $x \-> bblsft($n); # left shift $n places in base 2 |
| 1570 |
.Ve |
| 1571 |
.Sp |
| 1572 |
If \f(CW$n\fR is negative, the shifting is done in the opposite direction, so these |
| 1573 |
two are equivalent for all \f(CW$x\fR and \f(CW$n\fR |
| 1574 |
.Sp |
| 1575 |
.Vb 2 |
| 1576 |
\& $y = $x \-> bblsft($n); |
| 1577 |
\& $y = $x \-> bbrsft(\-$n); |
| 1578 |
.Ve |
| 1579 |
.Sp |
| 1580 |
and also equivalent to |
| 1581 |
.Sp |
| 1582 |
.Vb 2 |
| 1583 |
\& $y = $x \-> bmul(ref($x) \-> new(2) \-> bpow($n)); # if $n > 0 |
| 1584 |
\& $y = $x \-> bdiv(ref($x) \-> new(2) \-> bpow($n)); # if $n < 0 |
| 1585 |
.Ve |
| 1586 |
.IP \fBband()\fR 4 |
| 1587 |
.IX Item "band()" |
| 1588 |
.Vb 1 |
| 1589 |
\& $x\->band($y); # bitwise and |
| 1590 |
.Ve |
| 1591 |
.IP \fBbior()\fR 4 |
| 1592 |
.IX Item "bior()" |
| 1593 |
.Vb 1 |
| 1594 |
\& $x\->bior($y); # bitwise inclusive or |
| 1595 |
.Ve |
| 1596 |
.IP \fBbxor()\fR 4 |
| 1597 |
.IX Item "bxor()" |
| 1598 |
.Vb 1 |
| 1599 |
\& $x\->bxor($y); # bitwise exclusive or |
| 1600 |
.Ve |
| 1601 |
.IP \fBbnot()\fR 4 |
| 1602 |
.IX Item "bnot()" |
| 1603 |
.Vb 1 |
| 1604 |
\& $x\->bnot(); # bitwise not (two\*(Aqs complement) |
| 1605 |
.Ve |
| 1606 |
.Sp |
| 1607 |
Two's complement (bitwise not). This is equivalent to, but faster than, |
| 1608 |
.Sp |
| 1609 |
.Vb 1 |
| 1610 |
\& $x\->binc()\->bneg(); |
| 1611 |
.Ve |
| 1612 |
.SS "Rounding methods" |
| 1613 |
.IX Subsection "Rounding methods" |
| 1614 |
.IP \fBround()\fR 4 |
| 1615 |
.IX Item "round()" |
| 1616 |
.Vb 1 |
| 1617 |
\& $x\->round($A,$P,$round_mode); |
| 1618 |
.Ve |
| 1619 |
.Sp |
| 1620 |
Round \f(CW$x\fR to accuracy \f(CW$A\fR or precision \f(CW$P\fR using the round mode |
| 1621 |
\&\f(CW$round_mode\fR. |
| 1622 |
.IP \fBbround()\fR 4 |
| 1623 |
.IX Item "bround()" |
| 1624 |
.Vb 1 |
| 1625 |
\& $x\->bround($N); # accuracy: preserve $N digits |
| 1626 |
.Ve |
| 1627 |
.Sp |
| 1628 |
Rounds \f(CW$x\fR to an accuracy of \f(CW$N\fR digits. |
| 1629 |
.IP \fBbfround()\fR 4 |
| 1630 |
.IX Item "bfround()" |
| 1631 |
.Vb 1 |
| 1632 |
\& $x\->bfround($N); |
| 1633 |
.Ve |
| 1634 |
.Sp |
| 1635 |
Rounds to a multiple of 10**$N. Examples: |
| 1636 |
.Sp |
| 1637 |
.Vb 1 |
| 1638 |
\& Input N Result |
| 1639 |
\& |
| 1640 |
\& 123456.123456 3 123500 |
| 1641 |
\& 123456.123456 2 123450 |
| 1642 |
\& 123456.123456 \-2 123456.12 |
| 1643 |
\& 123456.123456 \-3 123456.123 |
| 1644 |
.Ve |
| 1645 |
.IP \fBbfloor()\fR 4 |
| 1646 |
.IX Item "bfloor()" |
| 1647 |
.Vb 1 |
| 1648 |
\& $x\->bfloor(); |
| 1649 |
.Ve |
| 1650 |
.Sp |
| 1651 |
Round \f(CW$x\fR towards minus infinity, i.e., set \f(CW$x\fR to the largest integer less than |
| 1652 |
or equal to \f(CW$x\fR. |
| 1653 |
.IP \fBbceil()\fR 4 |
| 1654 |
.IX Item "bceil()" |
| 1655 |
.Vb 1 |
| 1656 |
\& $x\->bceil(); |
| 1657 |
.Ve |
| 1658 |
.Sp |
| 1659 |
Round \f(CW$x\fR towards plus infinity, i.e., set \f(CW$x\fR to the smallest integer greater |
| 1660 |
than or equal to \f(CW$x\fR). |
| 1661 |
.IP \fBbint()\fR 4 |
| 1662 |
.IX Item "bint()" |
| 1663 |
.Vb 1 |
| 1664 |
\& $x\->bint(); |
| 1665 |
.Ve |
| 1666 |
.Sp |
| 1667 |
Round \f(CW$x\fR towards zero. |
| 1668 |
.SS "Other mathematical methods" |
| 1669 |
.IX Subsection "Other mathematical methods" |
| 1670 |
.IP \fBbgcd()\fR 4 |
| 1671 |
.IX Item "bgcd()" |
| 1672 |
.Vb 2 |
| 1673 |
\& $x \-> bgcd($y); # GCD of $x and $y |
| 1674 |
\& $x \-> bgcd($y, $z, ...); # GCD of $x, $y, $z, ... |
| 1675 |
.Ve |
| 1676 |
.Sp |
| 1677 |
Returns the greatest common divisor (GCD). |
| 1678 |
.IP \fBblcm()\fR 4 |
| 1679 |
.IX Item "blcm()" |
| 1680 |
.Vb 2 |
| 1681 |
\& $x \-> blcm($y); # LCM of $x and $y |
| 1682 |
\& $x \-> blcm($y, $z, ...); # LCM of $x, $y, $z, ... |
| 1683 |
.Ve |
| 1684 |
.Sp |
| 1685 |
Returns the least common multiple (LCM). |
| 1686 |
.SS "Object property methods" |
| 1687 |
.IX Subsection "Object property methods" |
| 1688 |
.IP \fBsign()\fR 4 |
| 1689 |
.IX Item "sign()" |
| 1690 |
.Vb 1 |
| 1691 |
\& $x\->sign(); |
| 1692 |
.Ve |
| 1693 |
.Sp |
| 1694 |
Return the sign, of \f(CW$x\fR, meaning either \f(CW\*(C`+\*(C'\fR, \f(CW\*(C`\-\*(C'\fR, \f(CW\*(C`\-inf\*(C'\fR, \f(CW\*(C`+inf\*(C'\fR or NaN. |
| 1695 |
.Sp |
| 1696 |
If you want \f(CW$x\fR to have a certain sign, use one of the following methods: |
| 1697 |
.Sp |
| 1698 |
.Vb 5 |
| 1699 |
\& $x\->babs(); # \*(Aq+\*(Aq |
| 1700 |
\& $x\->babs()\->bneg(); # \*(Aq\-\*(Aq |
| 1701 |
\& $x\->bnan(); # \*(AqNaN\*(Aq |
| 1702 |
\& $x\->binf(); # \*(Aq+inf\*(Aq |
| 1703 |
\& $x\->binf(\*(Aq\-\*(Aq); # \*(Aq\-inf\*(Aq |
| 1704 |
.Ve |
| 1705 |
.IP \fBdigit()\fR 4 |
| 1706 |
.IX Item "digit()" |
| 1707 |
.Vb 1 |
| 1708 |
\& $x\->digit($n); # return the nth digit, counting from right |
| 1709 |
.Ve |
| 1710 |
.Sp |
| 1711 |
If \f(CW$n\fR is negative, returns the digit counting from left. |
| 1712 |
.IP \fBdigitsum()\fR 4 |
| 1713 |
.IX Item "digitsum()" |
| 1714 |
.Vb 1 |
| 1715 |
\& $x\->digitsum(); |
| 1716 |
.Ve |
| 1717 |
.Sp |
| 1718 |
Computes the sum of the base 10 digits and returns it. |
| 1719 |
.IP \fBbdigitsum()\fR 4 |
| 1720 |
.IX Item "bdigitsum()" |
| 1721 |
.Vb 1 |
| 1722 |
\& $x\->bdigitsum(); |
| 1723 |
.Ve |
| 1724 |
.Sp |
| 1725 |
Computes the sum of the base 10 digits and assigns the result to the invocand. |
| 1726 |
.IP \fBlength()\fR 4 |
| 1727 |
.IX Item "length()" |
| 1728 |
.Vb 2 |
| 1729 |
\& $x\->length(); |
| 1730 |
\& ($xl, $fl) = $x\->length(); |
| 1731 |
.Ve |
| 1732 |
.Sp |
| 1733 |
Returns the number of digits in the decimal representation of the number. In |
| 1734 |
list context, returns the length of the integer and fraction part. For |
| 1735 |
Math::BigInt objects, the length of the fraction part is always 0. |
| 1736 |
.Sp |
| 1737 |
The following probably doesn't do what you expect: |
| 1738 |
.Sp |
| 1739 |
.Vb 2 |
| 1740 |
\& $c = Math::BigInt\->new(123); |
| 1741 |
\& print $c\->length(),"\en"; # prints 30 |
| 1742 |
.Ve |
| 1743 |
.Sp |
| 1744 |
It prints both the number of digits in the number and in the fraction part |
| 1745 |
since print calls \f(CWlength()\fR in list context. Use something like: |
| 1746 |
.Sp |
| 1747 |
.Vb 1 |
| 1748 |
\& print scalar $c\->length(),"\en"; # prints 3 |
| 1749 |
.Ve |
| 1750 |
.IP \fBmantissa()\fR 4 |
| 1751 |
.IX Item "mantissa()" |
| 1752 |
.Vb 1 |
| 1753 |
\& $x\->mantissa(); |
| 1754 |
.Ve |
| 1755 |
.Sp |
| 1756 |
Return the signed mantissa of \f(CW$x\fR as a Math::BigInt. |
| 1757 |
.IP \fBexponent()\fR 4 |
| 1758 |
.IX Item "exponent()" |
| 1759 |
.Vb 1 |
| 1760 |
\& $x\->exponent(); |
| 1761 |
.Ve |
| 1762 |
.Sp |
| 1763 |
Return the exponent of \f(CW$x\fR as a Math::BigInt. |
| 1764 |
.IP \fBparts()\fR 4 |
| 1765 |
.IX Item "parts()" |
| 1766 |
.Vb 1 |
| 1767 |
\& $x\->parts(); |
| 1768 |
.Ve |
| 1769 |
.Sp |
| 1770 |
Returns the significand (mantissa) and the exponent as integers. In |
| 1771 |
Math::BigFloat, both are returned as Math::BigInt objects. |
| 1772 |
.IP \fBsparts()\fR 4 |
| 1773 |
.IX Item "sparts()" |
| 1774 |
Returns the significand (mantissa) and the exponent as integers. In scalar |
| 1775 |
context, only the significand is returned. The significand is the integer with |
| 1776 |
the smallest absolute value. The output of \f(CWsparts()\fR corresponds to the |
| 1777 |
output from \f(CWbsstr()\fR. |
| 1778 |
.Sp |
| 1779 |
In Math::BigInt, this method is identical to \f(CWparts()\fR. |
| 1780 |
.IP \fBnparts()\fR 4 |
| 1781 |
.IX Item "nparts()" |
| 1782 |
Returns the significand (mantissa) and exponent corresponding to normalized |
| 1783 |
notation. In scalar context, only the significand is returned. For finite |
| 1784 |
non-zero numbers, the significand's absolute value is greater than or equal to |
| 1785 |
1 and less than 10. The output of \f(CWnparts()\fR corresponds to the output from |
| 1786 |
\&\f(CWbnstr()\fR. In Math::BigInt, if the significand can not be represented as an |
| 1787 |
integer, upgrading is performed or NaN is returned. |
| 1788 |
.IP \fBeparts()\fR 4 |
| 1789 |
.IX Item "eparts()" |
| 1790 |
Returns the significand (mantissa) and exponent corresponding to engineering |
| 1791 |
notation. In scalar context, only the significand is returned. For finite |
| 1792 |
non-zero numbers, the significand's absolute value is greater than or equal to |
| 1793 |
1 and less than 1000, and the exponent is a multiple of 3. The output of |
| 1794 |
\&\f(CWeparts()\fR corresponds to the output from \f(CWbestr()\fR. In Math::BigInt, if the |
| 1795 |
significand can not be represented as an integer, upgrading is performed or NaN |
| 1796 |
is returned. |
| 1797 |
.IP \fBdparts()\fR 4 |
| 1798 |
.IX Item "dparts()" |
| 1799 |
Returns the integer part and the fraction part. If the fraction part can not be |
| 1800 |
represented as an integer, upgrading is performed or NaN is returned. The |
| 1801 |
output of \f(CWdparts()\fR corresponds to the output from \f(CWbdstr()\fR. |
| 1802 |
.IP \fBfparts()\fR 4 |
| 1803 |
.IX Item "fparts()" |
| 1804 |
Returns the smallest possible numerator and denominator so that the numerator |
| 1805 |
divided by the denominator gives back the original value. For finite numbers, |
| 1806 |
both values are integers. Mnemonic: fraction. |
| 1807 |
.IP \fBnumerator()\fR 4 |
| 1808 |
.IX Item "numerator()" |
| 1809 |
Together with "\fBdenominator()\fR", returns the smallest integers so that the |
| 1810 |
numerator divided by the denominator reproduces the original value. With |
| 1811 |
Math::BigInt, \fBnumerator()\fR simply returns a copy of the invocand. |
| 1812 |
.IP \fBdenominator()\fR 4 |
| 1813 |
.IX Item "denominator()" |
| 1814 |
Together with "\fBnumerator()\fR", returns the smallest integers so that the |
| 1815 |
numerator divided by the denominator reproduces the original value. With |
| 1816 |
Math::BigInt, \fBdenominator()\fR always returns either a 1 or a NaN. |
| 1817 |
.SS "String conversion methods" |
| 1818 |
.IX Subsection "String conversion methods" |
| 1819 |
.IP \fBbstr()\fR 4 |
| 1820 |
.IX Item "bstr()" |
| 1821 |
Returns a string representing the number using decimal notation. In |
| 1822 |
Math::BigFloat, the output is zero padded according to the current accuracy or |
| 1823 |
precision, if any of those are defined. |
| 1824 |
.IP \fBbsstr()\fR 4 |
| 1825 |
.IX Item "bsstr()" |
| 1826 |
Returns a string representing the number using scientific notation where both |
| 1827 |
the significand (mantissa) and the exponent are integers. The output |
| 1828 |
corresponds to the output from \f(CWsparts()\fR. |
| 1829 |
.Sp |
| 1830 |
.Vb 5 |
| 1831 |
\& 123 is returned as "123e+0" |
| 1832 |
\& 1230 is returned as "123e+1" |
| 1833 |
\& 12300 is returned as "123e+2" |
| 1834 |
\& 12000 is returned as "12e+3" |
| 1835 |
\& 10000 is returned as "1e+4" |
| 1836 |
.Ve |
| 1837 |
.IP \fBbnstr()\fR 4 |
| 1838 |
.IX Item "bnstr()" |
| 1839 |
Returns a string representing the number using normalized notation, the most |
| 1840 |
common variant of scientific notation. For finite non-zero numbers, the |
| 1841 |
absolute value of the significand is greater than or equal to 1 and less than |
| 1842 |
10. The output corresponds to the output from \f(CWnparts()\fR. |
| 1843 |
.Sp |
| 1844 |
.Vb 5 |
| 1845 |
\& 123 is returned as "1.23e+2" |
| 1846 |
\& 1230 is returned as "1.23e+3" |
| 1847 |
\& 12300 is returned as "1.23e+4" |
| 1848 |
\& 12000 is returned as "1.2e+4" |
| 1849 |
\& 10000 is returned as "1e+4" |
| 1850 |
.Ve |
| 1851 |
.IP \fBbestr()\fR 4 |
| 1852 |
.IX Item "bestr()" |
| 1853 |
Returns a string representing the number using engineering notation. For finite |
| 1854 |
non-zero numbers, the absolute value of the significand is greater than or |
| 1855 |
equal to 1 and less than 1000, and the exponent is a multiple of 3. The output |
| 1856 |
corresponds to the output from \f(CWeparts()\fR. |
| 1857 |
.Sp |
| 1858 |
.Vb 5 |
| 1859 |
\& 123 is returned as "123e+0" |
| 1860 |
\& 1230 is returned as "1.23e+3" |
| 1861 |
\& 12300 is returned as "12.3e+3" |
| 1862 |
\& 12000 is returned as "12e+3" |
| 1863 |
\& 10000 is returned as "10e+3" |
| 1864 |
.Ve |
| 1865 |
.IP \fBbdstr()\fR 4 |
| 1866 |
.IX Item "bdstr()" |
| 1867 |
Returns a string representing the number using decimal notation. The output |
| 1868 |
corresponds to the output from \f(CWdparts()\fR. |
| 1869 |
.Sp |
| 1870 |
.Vb 5 |
| 1871 |
\& 123 is returned as "123" |
| 1872 |
\& 1230 is returned as "1230" |
| 1873 |
\& 12300 is returned as "12300" |
| 1874 |
\& 12000 is returned as "12000" |
| 1875 |
\& 10000 is returned as "10000" |
| 1876 |
.Ve |
| 1877 |
.IP \fBbfstr()\fR 4 |
| 1878 |
.IX Item "bfstr()" |
| 1879 |
Returns a string representing the number using fractional notation. The output |
| 1880 |
corresponds to the output from \f(CWfparts()\fR. |
| 1881 |
.Sp |
| 1882 |
.Vb 5 |
| 1883 |
\& 12.345 is returned as "2469/200" |
| 1884 |
\& 123.45 is returned as "2469/20" |
| 1885 |
\& 1234.5 is returned as "2469/2" |
| 1886 |
\& 12345 is returned as "12345" |
| 1887 |
\& 123450 is returned as "123450" |
| 1888 |
.Ve |
| 1889 |
.IP \fBto_hex()\fR 4 |
| 1890 |
.IX Item "to_hex()" |
| 1891 |
.Vb 1 |
| 1892 |
\& $x\->to_hex(); |
| 1893 |
.Ve |
| 1894 |
.Sp |
| 1895 |
Returns a hexadecimal string representation of the number. See also \fBfrom_hex()\fR. |
| 1896 |
.IP \fBto_bin()\fR 4 |
| 1897 |
.IX Item "to_bin()" |
| 1898 |
.Vb 1 |
| 1899 |
\& $x\->to_bin(); |
| 1900 |
.Ve |
| 1901 |
.Sp |
| 1902 |
Returns a binary string representation of the number. See also \fBfrom_bin()\fR. |
| 1903 |
.IP \fBto_oct()\fR 4 |
| 1904 |
.IX Item "to_oct()" |
| 1905 |
.Vb 1 |
| 1906 |
\& $x\->to_oct(); |
| 1907 |
.Ve |
| 1908 |
.Sp |
| 1909 |
Returns an octal string representation of the number. See also \fBfrom_oct()\fR. |
| 1910 |
.IP \fBto_bytes()\fR 4 |
| 1911 |
.IX Item "to_bytes()" |
| 1912 |
.Vb 2 |
| 1913 |
\& $x = Math::BigInt\->new("1667327589"); |
| 1914 |
\& $s = $x\->to_bytes(); # $s = "cafe" |
| 1915 |
.Ve |
| 1916 |
.Sp |
| 1917 |
Returns a byte string representation of the number using big endian byte order. |
| 1918 |
The invocand must be a non-negative, finite integer. See also \fBfrom_bytes()\fR. |
| 1919 |
.IP \fBto_base()\fR 4 |
| 1920 |
.IX Item "to_base()" |
| 1921 |
.Vb 4 |
| 1922 |
\& $x = Math::BigInt\->new("250"); |
| 1923 |
\& $x\->to_base(2); # returns "11111010" |
| 1924 |
\& $x\->to_base(8); # returns "372" |
| 1925 |
\& $x\->to_base(16); # returns "fa" |
| 1926 |
.Ve |
| 1927 |
.Sp |
| 1928 |
Returns a string representation of the number in the given base. If a collation |
| 1929 |
sequence is given, the collation sequence determines which characters are used |
| 1930 |
in the output. |
| 1931 |
.Sp |
| 1932 |
Here are some more examples |
| 1933 |
.Sp |
| 1934 |
.Vb 4 |
| 1935 |
\& $x = Math::BigInt\->new("16")\->to_base(3); # returns "121" |
| 1936 |
\& $x = Math::BigInt\->new("44027")\->to_base(36); # returns "XYZ" |
| 1937 |
\& $x = Math::BigInt\->new("58314")\->to_base(42); # returns "Why" |
| 1938 |
\& $x = Math::BigInt\->new("4")\->to_base(2, "\-|"); # returns "|\-\-" |
| 1939 |
.Ve |
| 1940 |
.Sp |
| 1941 |
See \fBfrom_base()\fR for information and examples. |
| 1942 |
.IP \fBto_base_num()\fR 4 |
| 1943 |
.IX Item "to_base_num()" |
| 1944 |
Converts the given number to the given base. This method is equivalent to |
| 1945 |
\&\f(CW_to_base()\fR, but returns numbers in an array rather than characters in a |
| 1946 |
string. In the output, the first element is the most significant. Unlike |
| 1947 |
\&\f(CW_to_base()\fR, all input values may be arbitrarily large. |
| 1948 |
.Sp |
| 1949 |
.Vb 2 |
| 1950 |
\& $x = Math::BigInt\->new(13); |
| 1951 |
\& $x\->to_base_num(2); # returns [1, 1, 0, 1] |
| 1952 |
\& |
| 1953 |
\& $x = Math::BigInt\->new(65191); |
| 1954 |
\& $x\->to_base_num(128); # returns [3, 125, 39] |
| 1955 |
.Ve |
| 1956 |
.IP \fBas_hex()\fR 4 |
| 1957 |
.IX Item "as_hex()" |
| 1958 |
.Vb 1 |
| 1959 |
\& $x\->as_hex(); |
| 1960 |
.Ve |
| 1961 |
.Sp |
| 1962 |
As, \f(CWto_hex()\fR, but with a "0x" prefix. |
| 1963 |
.IP \fBas_bin()\fR 4 |
| 1964 |
.IX Item "as_bin()" |
| 1965 |
.Vb 1 |
| 1966 |
\& $x\->as_bin(); |
| 1967 |
.Ve |
| 1968 |
.Sp |
| 1969 |
As, \f(CWto_bin()\fR, but with a "0b" prefix. |
| 1970 |
.IP \fBas_oct()\fR 4 |
| 1971 |
.IX Item "as_oct()" |
| 1972 |
.Vb 1 |
| 1973 |
\& $x\->as_oct(); |
| 1974 |
.Ve |
| 1975 |
.Sp |
| 1976 |
As, \f(CWto_oct()\fR, but with a "0" prefix. |
| 1977 |
.IP \fBas_bytes()\fR 4 |
| 1978 |
.IX Item "as_bytes()" |
| 1979 |
This is just an alias for \f(CWto_bytes()\fR. |
| 1980 |
.SS "Other conversion methods" |
| 1981 |
.IX Subsection "Other conversion methods" |
| 1982 |
.IP \fBnumify()\fR 4 |
| 1983 |
.IX Item "numify()" |
| 1984 |
.Vb 1 |
| 1985 |
\& print $x\->numify(); |
| 1986 |
.Ve |
| 1987 |
.Sp |
| 1988 |
Returns a Perl scalar from \f(CW$x\fR. It is used automatically whenever a scalar is |
| 1989 |
needed, for instance in array index operations. |
| 1990 |
.SS "Utility methods" |
| 1991 |
.IX Subsection "Utility methods" |
| 1992 |
These utility methods are made public |
| 1993 |
.IP \fBdec_str_to_dec_flt_str()\fR 4 |
| 1994 |
.IX Item "dec_str_to_dec_flt_str()" |
| 1995 |
Takes a string representing any valid number using decimal notation and converts |
| 1996 |
it to a string representing the same number using decimal floating point |
| 1997 |
notation. The output consists of five parts joined together: the sign of the |
| 1998 |
significand, the absolute value of the significand as the smallest possible |
| 1999 |
integer, the letter "e", the sign of the exponent, and the absolute value of the |
| 2000 |
exponent. If the input is invalid, nothing is returned. |
| 2001 |
.Sp |
| 2002 |
.Vb 1 |
| 2003 |
\& $str2 = $class \-> dec_str_to_dec_flt_str($str1); |
| 2004 |
.Ve |
| 2005 |
.Sp |
| 2006 |
Some examples |
| 2007 |
.Sp |
| 2008 |
.Vb 4 |
| 2009 |
\& Input Output |
| 2010 |
\& 31400.00e\-4 +314e\-2 |
| 2011 |
\& \-0.00012300e8 \-123e+2 |
| 2012 |
\& 0 +0e+0 |
| 2013 |
.Ve |
| 2014 |
.IP \fBhex_str_to_dec_flt_str()\fR 4 |
| 2015 |
.IX Item "hex_str_to_dec_flt_str()" |
| 2016 |
Takes a string representing any valid number using hexadecimal notation and |
| 2017 |
converts it to a string representing the same number using decimal floating |
| 2018 |
point notation. The output has the same format as that of |
| 2019 |
"\fBdec_str_to_dec_flt_str()\fR". |
| 2020 |
.Sp |
| 2021 |
.Vb 1 |
| 2022 |
\& $str2 = $class \-> hex_str_to_dec_flt_str($str1); |
| 2023 |
.Ve |
| 2024 |
.Sp |
| 2025 |
Some examples |
| 2026 |
.Sp |
| 2027 |
.Vb 2 |
| 2028 |
\& Input Output |
| 2029 |
\& 0xff +255e+0 |
| 2030 |
.Ve |
| 2031 |
.Sp |
| 2032 |
Some examples |
| 2033 |
.IP \fBoct_str_to_dec_flt_str()\fR 4 |
| 2034 |
.IX Item "oct_str_to_dec_flt_str()" |
| 2035 |
Takes a string representing any valid number using octal notation and converts |
| 2036 |
it to a string representing the same number using decimal floating point |
| 2037 |
notation. The output has the same format as that of |
| 2038 |
"\fBdec_str_to_dec_flt_str()\fR". |
| 2039 |
.Sp |
| 2040 |
.Vb 1 |
| 2041 |
\& $str2 = $class \-> oct_str_to_dec_flt_str($str1); |
| 2042 |
.Ve |
| 2043 |
.IP \fBbin_str_to_dec_flt_str()\fR 4 |
| 2044 |
.IX Item "bin_str_to_dec_flt_str()" |
| 2045 |
Takes a string representing any valid number using binary notation and converts |
| 2046 |
it to a string representing the same number using decimal floating point |
| 2047 |
notation. The output has the same format as that of |
| 2048 |
"\fBdec_str_to_dec_flt_str()\fR". |
| 2049 |
.Sp |
| 2050 |
.Vb 1 |
| 2051 |
\& $str2 = $class \-> bin_str_to_dec_flt_str($str1); |
| 2052 |
.Ve |
| 2053 |
.IP \fBdec_str_to_dec_str()\fR 4 |
| 2054 |
.IX Item "dec_str_to_dec_str()" |
| 2055 |
Takes a string representing any valid number using decimal notation and converts |
| 2056 |
it to a string representing the same number using decimal notation. If the |
| 2057 |
number represents an integer, the output consists of a sign and the absolute |
| 2058 |
value. If the number represents a non-integer, the output consists of a sign, |
| 2059 |
the integer part of the number, the decimal point ".", and the fraction part of |
| 2060 |
the number without any trailing zeros. If the input is invalid, nothing is |
| 2061 |
returned. |
| 2062 |
.IP \fBhex_str_to_dec_str()\fR 4 |
| 2063 |
.IX Item "hex_str_to_dec_str()" |
| 2064 |
Takes a string representing any valid number using hexadecimal notation and |
| 2065 |
converts it to a string representing the same number using decimal notation. The |
| 2066 |
output has the same format as that of "\fBdec_str_to_dec_str()\fR". |
| 2067 |
.IP \fBoct_str_to_dec_str()\fR 4 |
| 2068 |
.IX Item "oct_str_to_dec_str()" |
| 2069 |
Takes a string representing any valid number using octal notation and converts |
| 2070 |
it to a string representing the same number using decimal notation. The |
| 2071 |
output has the same format as that of "\fBdec_str_to_dec_str()\fR". |
| 2072 |
.IP \fBbin_str_to_dec_str()\fR 4 |
| 2073 |
.IX Item "bin_str_to_dec_str()" |
| 2074 |
Takes a string representing any valid number using binary notation and converts |
| 2075 |
it to a string representing the same number using decimal notation. The output |
| 2076 |
has the same format as that of "\fBdec_str_to_dec_str()\fR". |
| 2077 |
.SH "ACCURACY and PRECISION" |
| 2078 |
.IX Header "ACCURACY and PRECISION" |
| 2079 |
Math::BigInt and Math::BigFloat have full support for accuracy and precision |
| 2080 |
based rounding, both automatically after every operation, as well as manually. |
| 2081 |
.PP |
| 2082 |
This section describes the accuracy/precision handling in Math::BigInt and |
| 2083 |
Math::BigFloat as it used to be and as it is now, complete with an explanation |
| 2084 |
of all terms and abbreviations. |
| 2085 |
.PP |
| 2086 |
Not yet implemented things (but with correct description) are marked with '!', |
| 2087 |
things that need to be answered are marked with '?'. |
| 2088 |
.PP |
| 2089 |
In the next paragraph follows a short description of terms used here (because |
| 2090 |
these may differ from terms used by others people or documentation). |
| 2091 |
.PP |
| 2092 |
During the rest of this document, the shortcuts A (for accuracy), P (for |
| 2093 |
precision), F (fallback) and R (rounding mode) are be used. |
| 2094 |
.SS "Precision P" |
| 2095 |
.IX Subsection "Precision P" |
| 2096 |
Precision is a fixed number of digits before (positive) or after (negative) the |
| 2097 |
decimal point. For example, 123.45 has a precision of \-2. 0 means an integer |
| 2098 |
like 123 (or 120). A precision of 2 means at least two digits to the left of |
| 2099 |
the decimal point are zero, so 123 with P = 1 becomes 120. Note that numbers |
| 2100 |
with zeros before the decimal point may have different precisions, because 1200 |
| 2101 |
can have P = 0, 1 or 2 (depending on what the initial value was). It could also |
| 2102 |
have p < 0, when the digits after the decimal point are zero. |
| 2103 |
.PP |
| 2104 |
The string output (of floating point numbers) is padded with zeros: |
| 2105 |
.PP |
| 2106 |
.Vb 9 |
| 2107 |
\& Initial value P A Result String |
| 2108 |
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- |
| 2109 |
\& 1234.01 \-3 1000 1000 |
| 2110 |
\& 1234 \-2 1200 1200 |
| 2111 |
\& 1234.5 \-1 1230 1230 |
| 2112 |
\& 1234.001 1 1234 1234.0 |
| 2113 |
\& 1234.01 0 1234 1234 |
| 2114 |
\& 1234.01 2 1234.01 1234.01 |
| 2115 |
\& 1234.01 5 1234.01 1234.01000 |
| 2116 |
.Ve |
| 2117 |
.PP |
| 2118 |
For Math::BigInt objects, no padding occurs. |
| 2119 |
.SS "Accuracy A" |
| 2120 |
.IX Subsection "Accuracy A" |
| 2121 |
Number of significant digits. Leading zeros are not counted. A number may have |
| 2122 |
an accuracy greater than the non-zero digits when there are zeros in it or |
| 2123 |
trailing zeros. For example, 123.456 has A of 6, 10203 has 5, 123.0506 has 7, |
| 2124 |
123.45000 has 8 and 0.000123 has 3. |
| 2125 |
.PP |
| 2126 |
The string output (of floating point numbers) is padded with zeros: |
| 2127 |
.PP |
| 2128 |
.Vb 5 |
| 2129 |
\& Initial value P A Result String |
| 2130 |
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- |
| 2131 |
\& 1234.01 3 1230 1230 |
| 2132 |
\& 1234.01 6 1234.01 1234.01 |
| 2133 |
\& 1234.1 8 1234.1 1234.1000 |
| 2134 |
.Ve |
| 2135 |
.PP |
| 2136 |
For Math::BigInt objects, no padding occurs. |
| 2137 |
.SS "Fallback F" |
| 2138 |
.IX Subsection "Fallback F" |
| 2139 |
When both A and P are undefined, this is used as a fallback accuracy when |
| 2140 |
dividing numbers. |
| 2141 |
.SS "Rounding mode R" |
| 2142 |
.IX Subsection "Rounding mode R" |
| 2143 |
When rounding a number, different 'styles' or 'kinds' of rounding are possible. |
| 2144 |
(Note that random rounding, as in Math::Round, is not implemented.) |
| 2145 |
.PP |
| 2146 |
\fIDirected rounding\fR |
| 2147 |
.IX Subsection "Directed rounding" |
| 2148 |
.PP |
| 2149 |
These round modes always round in the same direction. |
| 2150 |
.IP 'trunc' 4 |
| 2151 |
.IX Item "'trunc'" |
| 2152 |
Round towards zero. Remove all digits following the rounding place, i.e., |
| 2153 |
replace them with zeros. Thus, 987.65 rounded to tens (P=1) becomes 980, and |
| 2154 |
rounded to the fourth significant digit becomes 987.6 (A=4). 123.456 rounded to |
| 2155 |
the second place after the decimal point (P=\-2) becomes 123.46. This |
| 2156 |
corresponds to the IEEE 754 rounding mode 'roundTowardZero'. |
| 2157 |
.PP |
| 2158 |
\fIRounding to nearest\fR |
| 2159 |
.IX Subsection "Rounding to nearest" |
| 2160 |
.PP |
| 2161 |
These rounding modes round to the nearest digit. They differ in how they |
| 2162 |
determine which way to round in the ambiguous case when there is a tie. |
| 2163 |
.IP 'even' 4 |
| 2164 |
.IX Item "'even'" |
| 2165 |
Round towards the nearest even digit, e.g., when rounding to nearest integer, |
| 2166 |
\&\-5.5 becomes \-6, 4.5 becomes 4, but 4.501 becomes 5. This corresponds to the |
| 2167 |
IEEE 754 rounding mode 'roundTiesToEven'. |
| 2168 |
.IP 'odd' 4 |
| 2169 |
.IX Item "'odd'" |
| 2170 |
Round towards the nearest odd digit, e.g., when rounding to nearest integer, |
| 2171 |
4.5 becomes 5, \-5.5 becomes \-5, but 5.501 becomes 6. This corresponds to the |
| 2172 |
IEEE 754 rounding mode 'roundTiesToOdd'. |
| 2173 |
.IP '+inf' 4 |
| 2174 |
.IX Item "'+inf'" |
| 2175 |
Round towards plus infinity, i.e., always round up. E.g., when rounding to the |
| 2176 |
nearest integer, 4.5 becomes 5, \-5.5 becomes \-5, and 4.501 also becomes 5. This |
| 2177 |
corresponds to the IEEE 754 rounding mode 'roundTiesToPositive'. |
| 2178 |
.IP '\-inf' 4 |
| 2179 |
.IX Item "'-inf'" |
| 2180 |
Round towards minus infinity, i.e., always round down. E.g., when rounding to |
| 2181 |
the nearest integer, 4.5 becomes 4, \-5.5 becomes \-6, but 4.501 becomes 5. This |
| 2182 |
corresponds to the IEEE 754 rounding mode 'roundTiesToNegative'. |
| 2183 |
.IP 'zero' 4 |
| 2184 |
.IX Item "'zero'" |
| 2185 |
Round towards zero, i.e., round positive numbers down and negative numbers up. |
| 2186 |
E.g., when rounding to the nearest integer, 4.5 becomes 4, \-5.5 becomes \-5, but |
| 2187 |
4.501 becomes 5. This corresponds to the IEEE 754 rounding mode |
| 2188 |
\&'roundTiesToZero'. |
| 2189 |
.IP 'common' 4 |
| 2190 |
.IX Item "'common'" |
| 2191 |
Round away from zero, i.e., round to the number with the largest absolute |
| 2192 |
value. E.g., when rounding to the nearest integer, \-1.5 becomes \-2, 1.5 becomes |
| 2193 |
2 and 1.49 becomes 1. This corresponds to the IEEE 754 rounding mode |
| 2194 |
\&'roundTiesToAway'. |
| 2195 |
.PP |
| 2196 |
The handling of A & P in MBI/MBF (the old core code shipped with Perl versions |
| 2197 |
<= 5.7.2) is like this: |
| 2198 |
.IP Precision 4 |
| 2199 |
.IX Item "Precision" |
| 2200 |
.Vb 3 |
| 2201 |
\& * bfround($p) is able to round to $p number of digits after the decimal |
| 2202 |
\& point |
| 2203 |
\& * otherwise P is unused |
| 2204 |
.Ve |
| 2205 |
.IP "Accuracy (significant digits)" 4 |
| 2206 |
.IX Item "Accuracy (significant digits)" |
| 2207 |
.Vb 10 |
| 2208 |
\& * bround($a) rounds to $a significant digits |
| 2209 |
\& * only bdiv() and bsqrt() take A as (optional) parameter |
| 2210 |
\& + other operations simply create the same number (bneg etc), or |
| 2211 |
\& more (bmul) of digits |
| 2212 |
\& + rounding/truncating is only done when explicitly calling one |
| 2213 |
\& of bround or bfround, and never for Math::BigInt (not implemented) |
| 2214 |
\& * bsqrt() simply hands its accuracy argument over to bdiv. |
| 2215 |
\& * the documentation and the comment in the code indicate two |
| 2216 |
\& different ways on how bdiv() determines the maximum number |
| 2217 |
\& of digits it should calculate, and the actual code does yet |
| 2218 |
\& another thing |
| 2219 |
\& POD: |
| 2220 |
\& max($Math::BigFloat::div_scale,length(dividend)+length(divisor)) |
| 2221 |
\& Comment: |
| 2222 |
\& result has at most max(scale, length(dividend), length(divisor)) digits |
| 2223 |
\& Actual code: |
| 2224 |
\& scale = max(scale, length(dividend)\-1,length(divisor)\-1); |
| 2225 |
\& scale += length(divisor) \- length(dividend); |
| 2226 |
\& So for lx = 3, ly = 9, scale = 10, scale will actually be 16 (10 |
| 2227 |
\& So for lx = 3, ly = 9, scale = 10, scale will actually be 16 |
| 2228 |
\& (10+9\-3). Actually, the \*(Aqdifference\*(Aq added to the scale is cal\- |
| 2229 |
\& culated from the number of "significant digits" in dividend and |
| 2230 |
\& divisor, which is derived by looking at the length of the man\- |
| 2231 |
\& tissa. Which is wrong, since it includes the + sign (oops) and |
| 2232 |
\& actually gets 2 for \*(Aq+100\*(Aq and 4 for \*(Aq+101\*(Aq. Oops again. Thus |
| 2233 |
\& 124/3 with div_scale=1 will get you \*(Aq41.3\*(Aq based on the strange |
| 2234 |
\& assumption that 124 has 3 significant digits, while 120/7 will |
| 2235 |
\& get you \*(Aq17\*(Aq, not \*(Aq17.1\*(Aq since 120 is thought to have 2 signif\- |
| 2236 |
\& icant digits. The rounding after the division then uses the |
| 2237 |
\& remainder and $y to determine whether it must round up or down. |
| 2238 |
\& ? I have no idea which is the right way. That\*(Aqs why I used a slightly more |
| 2239 |
\& ? simple scheme and tweaked the few failing testcases to match it. |
| 2240 |
.Ve |
| 2241 |
.PP |
| 2242 |
This is how it works now: |
| 2243 |
.IP Setting/Accessing 4 |
| 2244 |
.IX Item "Setting/Accessing" |
| 2245 |
.Vb 10 |
| 2246 |
\& * You can set the A global via Math::BigInt\->accuracy() or |
| 2247 |
\& Math::BigFloat\->accuracy() or whatever class you are using. |
| 2248 |
\& * You can also set P globally by using Math::SomeClass\->precision() |
| 2249 |
\& likewise. |
| 2250 |
\& * Globals are classwide, and not inherited by subclasses. |
| 2251 |
\& * to undefine A, use Math::SomeClass\->accuracy(undef); |
| 2252 |
\& * to undefine P, use Math::SomeClass\->precision(undef); |
| 2253 |
\& * Setting Math::SomeClass\->accuracy() clears automatically |
| 2254 |
\& Math::SomeClass\->precision(), and vice versa. |
| 2255 |
\& * To be valid, A must be > 0, P can have any value. |
| 2256 |
\& * If P is negative, this means round to the P\*(Aqth place to the right of the |
| 2257 |
\& decimal point; positive values mean to the left of the decimal point. |
| 2258 |
\& P of 0 means round to integer. |
| 2259 |
\& * to find out the current global A, use Math::SomeClass\->accuracy() |
| 2260 |
\& * to find out the current global P, use Math::SomeClass\->precision() |
| 2261 |
\& * use $x\->accuracy() respective $x\->precision() for the local |
| 2262 |
\& setting of $x. |
| 2263 |
\& * Please note that $x\->accuracy() respective $x\->precision() |
| 2264 |
\& return eventually defined global A or P, when $x\*(Aqs A or P is not |
| 2265 |
\& set. |
| 2266 |
.Ve |
| 2267 |
.IP "Creating numbers" 4 |
| 2268 |
.IX Item "Creating numbers" |
| 2269 |
.Vb 12 |
| 2270 |
\& * When you create a number, you can give the desired A or P via: |
| 2271 |
\& $x = Math::BigInt\->new($number,$A,$P); |
| 2272 |
\& * Only one of A or P can be defined, otherwise the result is NaN |
| 2273 |
\& * If no A or P is give ($x = Math::BigInt\->new($number) form), then the |
| 2274 |
\& globals (if set) will be used. Thus changing the global defaults later on |
| 2275 |
\& will not change the A or P of previously created numbers (i.e., A and P of |
| 2276 |
\& $x will be what was in effect when $x was created) |
| 2277 |
\& * If given undef for A and P, NO rounding will occur, and the globals will |
| 2278 |
\& NOT be used. This is used by subclasses to create numbers without |
| 2279 |
\& suffering rounding in the parent. Thus a subclass is able to have its own |
| 2280 |
\& globals enforced upon creation of a number by using |
| 2281 |
\& $x = Math::BigInt\->new($number,undef,undef): |
| 2282 |
\& |
| 2283 |
\& use Math::BigInt::SomeSubclass; |
| 2284 |
\& use Math::BigInt; |
| 2285 |
\& |
| 2286 |
\& Math::BigInt\->accuracy(2); |
| 2287 |
\& Math::BigInt::SomeSubclass\->accuracy(3); |
| 2288 |
\& $x = Math::BigInt::SomeSubclass\->new(1234); |
| 2289 |
\& |
| 2290 |
\& $x is now 1230, and not 1200. A subclass might choose to implement |
| 2291 |
\& this otherwise, e.g. falling back to the parent\*(Aqs A and P. |
| 2292 |
.Ve |
| 2293 |
.IP Usage 4 |
| 2294 |
.IX Item "Usage" |
| 2295 |
.Vb 7 |
| 2296 |
\& * If A or P are enabled/defined, they are used to round the result of each |
| 2297 |
\& operation according to the rules below |
| 2298 |
\& * Negative P is ignored in Math::BigInt, since Math::BigInt objects never |
| 2299 |
\& have digits after the decimal point |
| 2300 |
\& * Math::BigFloat uses Math::BigInt internally, but setting A or P inside |
| 2301 |
\& Math::BigInt as globals does not tamper with the parts of a Math::BigFloat. |
| 2302 |
\& A flag is used to mark all Math::BigFloat numbers as \*(Aqnever round\*(Aq. |
| 2303 |
.Ve |
| 2304 |
.IP Precedence 4 |
| 2305 |
.IX Item "Precedence" |
| 2306 |
.Vb 10 |
| 2307 |
\& * It only makes sense that a number has only one of A or P at a time. |
| 2308 |
\& If you set either A or P on one object, or globally, the other one will |
| 2309 |
\& be automatically cleared. |
| 2310 |
\& * If two objects are involved in an operation, and one of them has A in |
| 2311 |
\& effect, and the other P, this results in an error (NaN). |
| 2312 |
\& * A takes precedence over P (Hint: A comes before P). |
| 2313 |
\& If neither of them is defined, nothing is used, i.e. the result will have |
| 2314 |
\& as many digits as it can (with an exception for bdiv/bsqrt) and will not |
| 2315 |
\& be rounded. |
| 2316 |
\& * There is another setting for bdiv() (and thus for bsqrt()). If neither of |
| 2317 |
\& A or P is defined, bdiv() will use a fallback (F) of $div_scale digits. |
| 2318 |
\& If either the dividend\*(Aqs or the divisor\*(Aqs mantissa has more digits than |
| 2319 |
\& the value of F, the higher value will be used instead of F. |
| 2320 |
\& This is to limit the digits (A) of the result (just consider what would |
| 2321 |
\& happen with unlimited A and P in the case of 1/3 :\-) |
| 2322 |
\& * bdiv will calculate (at least) 4 more digits than required (determined by |
| 2323 |
\& A, P or F), and, if F is not used, round the result |
| 2324 |
\& (this will still fail in the case of a result like 0.12345000000001 with A |
| 2325 |
\& or P of 5, but this can not be helped \- or can it?) |
| 2326 |
\& * Thus you can have the math done by on Math::Big* class in two modi: |
| 2327 |
\& + never round (this is the default): |
| 2328 |
\& This is done by setting A and P to undef. No math operation |
| 2329 |
\& will round the result, with bdiv() and bsqrt() as exceptions to guard |
| 2330 |
\& against overflows. You must explicitly call bround(), bfround() or |
| 2331 |
\& round() (the latter with parameters). |
| 2332 |
\& Note: Once you have rounded a number, the settings will \*(Aqstick\*(Aq on it |
| 2333 |
\& and \*(Aqinfect\*(Aq all other numbers engaged in math operations with it, since |
| 2334 |
\& local settings have the highest precedence. So, to get SaferRound[tm], |
| 2335 |
\& use a copy() before rounding like this: |
| 2336 |
\& |
| 2337 |
\& $x = Math::BigFloat\->new(12.34); |
| 2338 |
\& $y = Math::BigFloat\->new(98.76); |
| 2339 |
\& $z = $x * $y; # 1218.6984 |
| 2340 |
\& print $x\->copy()\->bround(3); # 12.3 (but A is now 3!) |
| 2341 |
\& $z = $x * $y; # still 1218.6984, without |
| 2342 |
\& # copy would have been 1210! |
| 2343 |
\& |
| 2344 |
\& + round after each op: |
| 2345 |
\& After each single operation (except for testing like is_zero()), the |
| 2346 |
\& method round() is called and the result is rounded appropriately. By |
| 2347 |
\& setting proper values for A and P, you can have all\-the\-same\-A or |
| 2348 |
\& all\-the\-same\-P modes. For example, Math::Currency might set A to undef, |
| 2349 |
\& and P to \-2, globally. |
| 2350 |
\& |
| 2351 |
\& ?Maybe an extra option that forbids local A & P settings would be in order, |
| 2352 |
\& ?so that intermediate rounding does not \*(Aqpoison\*(Aq further math? |
| 2353 |
.Ve |
| 2354 |
.IP "Overriding globals" 4 |
| 2355 |
.IX Item "Overriding globals" |
| 2356 |
.Vb 10 |
| 2357 |
\& * you will be able to give A, P and R as an argument to all the calculation |
| 2358 |
\& routines; the second parameter is A, the third one is P, and the fourth is |
| 2359 |
\& R (shift right by one for binary operations like badd). P is used only if |
| 2360 |
\& the first parameter (A) is undefined. These three parameters override the |
| 2361 |
\& globals in the order detailed as follows, i.e. the first defined value |
| 2362 |
\& wins: |
| 2363 |
\& (local: per object, global: global default, parameter: argument to sub) |
| 2364 |
\& + parameter A |
| 2365 |
\& + parameter P |
| 2366 |
\& + local A (if defined on both of the operands: smaller one is taken) |
| 2367 |
\& + local P (if defined on both of the operands: bigger one is taken) |
| 2368 |
\& + global A |
| 2369 |
\& + global P |
| 2370 |
\& + global F |
| 2371 |
\& * bsqrt() will hand its arguments to bdiv(), as it used to, only now for two |
| 2372 |
\& arguments (A and P) instead of one |
| 2373 |
.Ve |
| 2374 |
.IP "Local settings" 4 |
| 2375 |
.IX Item "Local settings" |
| 2376 |
.Vb 5 |
| 2377 |
\& * You can set A or P locally by using $x\->accuracy() or |
| 2378 |
\& $x\->precision() |
| 2379 |
\& and thus force different A and P for different objects/numbers. |
| 2380 |
\& * Setting A or P this way immediately rounds $x to the new value. |
| 2381 |
\& * $x\->accuracy() clears $x\->precision(), and vice versa. |
| 2382 |
.Ve |
| 2383 |
.IP Rounding 4 |
| 2384 |
.IX Item "Rounding" |
| 2385 |
.Vb 10 |
| 2386 |
\& * the rounding routines will use the respective global or local settings. |
| 2387 |
\& bround() is for accuracy rounding, while bfround() is for precision |
| 2388 |
\& * the two rounding functions take as the second parameter one of the |
| 2389 |
\& following rounding modes (R): |
| 2390 |
\& \*(Aqeven\*(Aq, \*(Aqodd\*(Aq, \*(Aq+inf\*(Aq, \*(Aq\-inf\*(Aq, \*(Aqzero\*(Aq, \*(Aqtrunc\*(Aq, \*(Aqcommon\*(Aq |
| 2391 |
\& * you can set/get the global R by using Math::SomeClass\->round_mode() |
| 2392 |
\& or by setting $Math::SomeClass::round_mode |
| 2393 |
\& * after each operation, $result\->round() is called, and the result may |
| 2394 |
\& eventually be rounded (that is, if A or P were set either locally, |
| 2395 |
\& globally or as parameter to the operation) |
| 2396 |
\& * to manually round a number, call $x\->round($A,$P,$round_mode); |
| 2397 |
\& this will round the number by using the appropriate rounding function |
| 2398 |
\& and then normalize it. |
| 2399 |
\& * rounding modifies the local settings of the number: |
| 2400 |
\& |
| 2401 |
\& $x = Math::BigFloat\->new(123.456); |
| 2402 |
\& $x\->accuracy(5); |
| 2403 |
\& $x\->bround(4); |
| 2404 |
\& |
| 2405 |
\& Here 4 takes precedence over 5, so 123.5 is the result and $x\->accuracy() |
| 2406 |
\& will be 4 from now on. |
| 2407 |
.Ve |
| 2408 |
.IP "Default values" 4 |
| 2409 |
.IX Item "Default values" |
| 2410 |
.Vb 4 |
| 2411 |
\& * R: \*(Aqeven\*(Aq |
| 2412 |
\& * F: 40 |
| 2413 |
\& * A: undef |
| 2414 |
\& * P: undef |
| 2415 |
.Ve |
| 2416 |
.IP Remarks 4 |
| 2417 |
.IX Item "Remarks" |
| 2418 |
.Vb 5 |
| 2419 |
\& * The defaults are set up so that the new code gives the same results as |
| 2420 |
\& the old code (except in a few cases on bdiv): |
| 2421 |
\& + Both A and P are undefined and thus will not be used for rounding |
| 2422 |
\& after each operation. |
| 2423 |
\& + round() is thus a no\-op, unless given extra parameters A and P |
| 2424 |
.Ve |
| 2425 |
.SH "Infinity and Not a Number" |
| 2426 |
.IX Header "Infinity and Not a Number" |
| 2427 |
While Math::BigInt has extensive handling of inf and NaN, certain quirks |
| 2428 |
remain. |
| 2429 |
.IP \fBoct()\fR/\fBhex()\fR 4 |
| 2430 |
.IX Item "oct()/hex()" |
| 2431 |
These perl routines currently (as of Perl v.5.8.6) cannot handle passed inf. |
| 2432 |
.Sp |
| 2433 |
.Vb 9 |
| 2434 |
\& te@linux:~> perl \-wle \*(Aqprint 2 ** 3333\*(Aq |
| 2435 |
\& Inf |
| 2436 |
\& te@linux:~> perl \-wle \*(Aqprint 2 ** 3333 == 2 ** 3333\*(Aq |
| 2437 |
\& 1 |
| 2438 |
\& te@linux:~> perl \-wle \*(Aqprint oct(2 ** 3333)\*(Aq |
| 2439 |
\& 0 |
| 2440 |
\& te@linux:~> perl \-wle \*(Aqprint hex(2 ** 3333)\*(Aq |
| 2441 |
\& Illegal hexadecimal digit \*(AqI\*(Aq ignored at \-e line 1. |
| 2442 |
\& 0 |
| 2443 |
.Ve |
| 2444 |
.Sp |
| 2445 |
The same problems occur if you pass them Math::BigInt\->\fBbinf()\fR objects. Since |
| 2446 |
overloading these routines is not possible, this cannot be fixed from |
| 2447 |
Math::BigInt. |
| 2448 |
.SH INTERNALS |
| 2449 |
.IX Header "INTERNALS" |
| 2450 |
You should neither care about nor depend on the internal representation; it |
| 2451 |
might change without notice. Use \fBONLY\fR method calls like \f(CW\*(C`$x\->sign();\*(C'\fR |
| 2452 |
instead relying on the internal representation. |
| 2453 |
.SS "MATH LIBRARY" |
| 2454 |
.IX Subsection "MATH LIBRARY" |
| 2455 |
The mathematical computations are performed by a backend library. It is not |
| 2456 |
required to specify which backend library to use, but some backend libraries |
| 2457 |
are much faster than the default library. |
| 2458 |
.PP |
| 2459 |
\fIThe default library\fR |
| 2460 |
.IX Subsection "The default library" |
| 2461 |
.PP |
| 2462 |
The default library is Math::BigInt::Calc, which is implemented in pure Perl |
| 2463 |
and hence does not require a compiler. |
| 2464 |
.PP |
| 2465 |
\fISpecifying a library\fR |
| 2466 |
.IX Subsection "Specifying a library" |
| 2467 |
.PP |
| 2468 |
The simple case |
| 2469 |
.PP |
| 2470 |
.Vb 1 |
| 2471 |
\& use Math::BigInt; |
| 2472 |
.Ve |
| 2473 |
.PP |
| 2474 |
is equivalent to saying |
| 2475 |
.PP |
| 2476 |
.Vb 1 |
| 2477 |
\& use Math::BigInt try => \*(AqCalc\*(Aq; |
| 2478 |
.Ve |
| 2479 |
.PP |
| 2480 |
You can use a different backend library with, e.g., |
| 2481 |
.PP |
| 2482 |
.Vb 1 |
| 2483 |
\& use Math::BigInt try => \*(AqGMP\*(Aq; |
| 2484 |
.Ve |
| 2485 |
.PP |
| 2486 |
which attempts to load the Math::BigInt::GMP library, and falls back to the |
| 2487 |
default library if the specified library can't be loaded. |
| 2488 |
.PP |
| 2489 |
Multiple libraries can be specified by separating them by a comma, e.g., |
| 2490 |
.PP |
| 2491 |
.Vb 1 |
| 2492 |
\& use Math::BigInt try => \*(AqGMP,Pari\*(Aq; |
| 2493 |
.Ve |
| 2494 |
.PP |
| 2495 |
If you request a specific set of libraries and do not allow fallback to the |
| 2496 |
default library, specify them using "only", |
| 2497 |
.PP |
| 2498 |
.Vb 1 |
| 2499 |
\& use Math::BigInt only => \*(AqGMP,Pari\*(Aq; |
| 2500 |
.Ve |
| 2501 |
.PP |
| 2502 |
If you prefer a specific set of libraries, but want to see a warning if the |
| 2503 |
fallback library is used, specify them using "lib", |
| 2504 |
.PP |
| 2505 |
.Vb 1 |
| 2506 |
\& use Math::BigInt lib => \*(AqGMP,Pari\*(Aq; |
| 2507 |
.Ve |
| 2508 |
.PP |
| 2509 |
The following first tries to find Math::BigInt::Foo, then Math::BigInt::Bar, and |
| 2510 |
if this also fails, reverts to Math::BigInt::Calc: |
| 2511 |
.PP |
| 2512 |
.Vb 1 |
| 2513 |
\& use Math::BigInt try => \*(AqFoo,Math::BigInt::Bar\*(Aq; |
| 2514 |
.Ve |
| 2515 |
.PP |
| 2516 |
\fIWhich library to use?\fR |
| 2517 |
.IX Subsection "Which library to use?" |
| 2518 |
.PP |
| 2519 |
\&\fBNote\fR: General purpose packages should not be explicit about the library to |
| 2520 |
use; let the script author decide which is best. |
| 2521 |
.PP |
| 2522 |
Math::BigInt::GMP, Math::BigInt::Pari, and Math::BigInt::GMPz are in |
| 2523 |
cases involving big numbers much faster than Math::BigInt::Calc. However |
| 2524 |
these libraries are slower when dealing with very small numbers (less than about |
| 2525 |
20 digits) and when converting very large numbers to decimal (for instance for |
| 2526 |
printing, rounding, calculating their length in decimal etc.). |
| 2527 |
.PP |
| 2528 |
So please select carefully what library you want to use. |
| 2529 |
.PP |
| 2530 |
Different low-level libraries use different formats to store the numbers, so |
| 2531 |
mixing them won't work. You should not depend on the number having a specific |
| 2532 |
internal format. |
| 2533 |
.PP |
| 2534 |
See the respective math library module documentation for further details. |
| 2535 |
.PP |
| 2536 |
\fILoading multiple libraries\fR |
| 2537 |
.IX Subsection "Loading multiple libraries" |
| 2538 |
.PP |
| 2539 |
The first library that is successfully loaded is the one that will be used. Any |
| 2540 |
further attempts at loading a different module will be ignored. This is to avoid |
| 2541 |
the situation where module A requires math library X, and module B requires math |
| 2542 |
library Y, causing modules A and B to be incompatible. For example, |
| 2543 |
.PP |
| 2544 |
.Vb 2 |
| 2545 |
\& use Math::BigInt; # loads default "Calc" |
| 2546 |
\& use Math::BigFloat only => "GMP"; # ignores "GMP" |
| 2547 |
.Ve |
| 2548 |
.SS SIGN |
| 2549 |
.IX Subsection "SIGN" |
| 2550 |
The sign is either '+', '\-', 'NaN', '+inf' or '\-inf'. |
| 2551 |
.PP |
| 2552 |
A sign of 'NaN' is used to represent the result when input arguments are not |
| 2553 |
numbers or as a result of 0/0. '+inf' and '\-inf' represent plus respectively |
| 2554 |
minus infinity. You get '+inf' when dividing a positive number by 0, and '\-inf' |
| 2555 |
when dividing any negative number by 0. |
| 2556 |
.SH EXAMPLES |
| 2557 |
.IX Header "EXAMPLES" |
| 2558 |
.Vb 1 |
| 2559 |
\& use Math::BigInt; |
| 2560 |
\& |
| 2561 |
\& sub bigint { Math::BigInt\->new(shift); } |
| 2562 |
\& |
| 2563 |
\& $x = Math::BigInt\->bstr("1234") # string "1234" |
| 2564 |
\& $x = "$x"; # same as bstr() |
| 2565 |
\& $x = Math::BigInt\->bneg("1234"); # Math::BigInt "\-1234" |
| 2566 |
\& $x = Math::BigInt\->babs("\-12345"); # Math::BigInt "12345" |
| 2567 |
\& $x = Math::BigInt\->bnorm("\-0.00"); # Math::BigInt "0" |
| 2568 |
\& $x = bigint(1) + bigint(2); # Math::BigInt "3" |
| 2569 |
\& $x = bigint(1) + "2"; # ditto ("2" becomes a Math::BigInt) |
| 2570 |
\& $x = bigint(1); # Math::BigInt "1" |
| 2571 |
\& $x = $x + 5 / 2; # Math::BigInt "3" |
| 2572 |
\& $x = $x ** 3; # Math::BigInt "27" |
| 2573 |
\& $x *= 2; # Math::BigInt "54" |
| 2574 |
\& $x = Math::BigInt\->new(0); # Math::BigInt "0" |
| 2575 |
\& $x\-\-; # Math::BigInt "\-1" |
| 2576 |
\& $x = Math::BigInt\->badd(4,5) # Math::BigInt "9" |
| 2577 |
\& print $x\->bsstr(); # 9e+0 |
| 2578 |
.Ve |
| 2579 |
.PP |
| 2580 |
Examples for rounding: |
| 2581 |
.PP |
| 2582 |
.Vb 2 |
| 2583 |
\& use Math::BigFloat; |
| 2584 |
\& use Test::More; |
| 2585 |
\& |
| 2586 |
\& $x = Math::BigFloat\->new(123.4567); |
| 2587 |
\& $y = Math::BigFloat\->new(123.456789); |
| 2588 |
\& Math::BigFloat\->accuracy(4); # no more A than 4 |
| 2589 |
\& |
| 2590 |
\& is ($x\->copy()\->bround(),123.4); # even rounding |
| 2591 |
\& print $x\->copy()\->bround(),"\en"; # 123.4 |
| 2592 |
\& Math::BigFloat\->round_mode(\*(Aqodd\*(Aq); # round to odd |
| 2593 |
\& print $x\->copy()\->bround(),"\en"; # 123.5 |
| 2594 |
\& Math::BigFloat\->accuracy(5); # no more A than 5 |
| 2595 |
\& Math::BigFloat\->round_mode(\*(Aqodd\*(Aq); # round to odd |
| 2596 |
\& print $x\->copy()\->bround(),"\en"; # 123.46 |
| 2597 |
\& $y = $x\->copy()\->bround(4),"\en"; # A = 4: 123.4 |
| 2598 |
\& print "$y, ",$y\->accuracy(),"\en"; # 123.4, 4 |
| 2599 |
\& |
| 2600 |
\& Math::BigFloat\->accuracy(undef); # A not important now |
| 2601 |
\& Math::BigFloat\->precision(2); # P important |
| 2602 |
\& print $x\->copy()\->bnorm(),"\en"; # 123.46 |
| 2603 |
\& print $x\->copy()\->bround(),"\en"; # 123.46 |
| 2604 |
.Ve |
| 2605 |
.PP |
| 2606 |
Examples for converting: |
| 2607 |
.PP |
| 2608 |
.Vb 2 |
| 2609 |
\& my $x = Math::BigInt\->new(\*(Aq0b1\*(Aq.\*(Aq01\*(Aq x 123); |
| 2610 |
\& print "bin: ",$x\->as_bin()," hex:",$x\->as_hex()," dec: ",$x,"\en"; |
| 2611 |
.Ve |
| 2612 |
.SH "NUMERIC LITERALS" |
| 2613 |
.IX Header "NUMERIC LITERALS" |
| 2614 |
After \f(CW\*(C`use Math::BigInt \*(Aq:constant\*(Aq\*(C'\fR all numeric literals in the given scope |
| 2615 |
are converted to \f(CW\*(C`Math::BigInt\*(C'\fR objects. This conversion happens at compile |
| 2616 |
time. Every non-integer is convert to a NaN. |
| 2617 |
.PP |
| 2618 |
For example, |
| 2619 |
.PP |
| 2620 |
.Vb 1 |
| 2621 |
\& perl \-MMath::BigInt=:constant \-le \*(Aqprint 2**150\*(Aq |
| 2622 |
.Ve |
| 2623 |
.PP |
| 2624 |
prints the exact value of \f(CW\*(C`2**150\*(C'\fR. Note that without conversion of constants |
| 2625 |
to objects the expression \f(CW\*(C`2**150\*(C'\fR is calculated using Perl scalars, which |
| 2626 |
leads to an inaccurate result. |
| 2627 |
.PP |
| 2628 |
Please note that strings are not affected, so that |
| 2629 |
.PP |
| 2630 |
.Vb 1 |
| 2631 |
\& use Math::BigInt qw/:constant/; |
| 2632 |
\& |
| 2633 |
\& $x = "1234567890123456789012345678901234567890" |
| 2634 |
\& + "123456789123456789"; |
| 2635 |
.Ve |
| 2636 |
.PP |
| 2637 |
does give you what you expect. You need an explicit Math::BigInt\->\fBnew()\fR around |
| 2638 |
at least one of the operands. You should also quote large constants to prevent |
| 2639 |
loss of precision: |
| 2640 |
.PP |
| 2641 |
.Vb 1 |
| 2642 |
\& use Math::BigInt; |
| 2643 |
\& |
| 2644 |
\& $x = Math::BigInt\->new("1234567889123456789123456789123456789"); |
| 2645 |
.Ve |
| 2646 |
.PP |
| 2647 |
Without the quotes Perl first converts the large number to a floating point |
| 2648 |
constant at compile time, and then converts the result to a Math::BigInt object |
| 2649 |
at run time, which results in an inaccurate result. |
| 2650 |
.SS "Hexadecimal, octal, and binary floating point literals" |
| 2651 |
.IX Subsection "Hexadecimal, octal, and binary floating point literals" |
| 2652 |
Perl (and this module) accepts hexadecimal, octal, and binary floating point |
| 2653 |
literals, but use them with care with Perl versions before v5.32.0, because some |
| 2654 |
versions of Perl silently give the wrong result. Below are some examples of |
| 2655 |
different ways to write the number decimal 314. |
| 2656 |
.PP |
| 2657 |
Hexadecimal floating point literals: |
| 2658 |
.PP |
| 2659 |
.Vb 3 |
| 2660 |
\& 0x1.3ap+8 0X1.3AP+8 |
| 2661 |
\& 0x1.3ap8 0X1.3AP8 |
| 2662 |
\& 0x13a0p\-4 0X13A0P\-4 |
| 2663 |
.Ve |
| 2664 |
.PP |
| 2665 |
Octal floating point literals (with "0" prefix): |
| 2666 |
.PP |
| 2667 |
.Vb 3 |
| 2668 |
\& 01.164p+8 01.164P+8 |
| 2669 |
\& 01.164p8 01.164P8 |
| 2670 |
\& 011640p\-4 011640P\-4 |
| 2671 |
.Ve |
| 2672 |
.PP |
| 2673 |
Octal floating point literals (with "0o" prefix) (requires v5.34.0): |
| 2674 |
.PP |
| 2675 |
.Vb 3 |
| 2676 |
\& 0o1.164p+8 0O1.164P+8 |
| 2677 |
\& 0o1.164p8 0O1.164P8 |
| 2678 |
\& 0o11640p\-4 0O11640P\-4 |
| 2679 |
.Ve |
| 2680 |
.PP |
| 2681 |
Binary floating point literals: |
| 2682 |
.PP |
| 2683 |
.Vb 3 |
| 2684 |
\& 0b1.0011101p+8 0B1.0011101P+8 |
| 2685 |
\& 0b1.0011101p8 0B1.0011101P8 |
| 2686 |
\& 0b10011101000p\-2 0B10011101000P\-2 |
| 2687 |
.Ve |
| 2688 |
.SH PERFORMANCE |
| 2689 |
.IX Header "PERFORMANCE" |
| 2690 |
Using the form \f(CW$x\fR += \f(CW$y\fR; etc over \f(CW$x\fR = \f(CW$x\fR + \f(CW$y\fR is faster, since a copy of \f(CW$x\fR |
| 2691 |
must be made in the second case. For long numbers, the copy can eat up to 20% |
| 2692 |
of the work (in the case of addition/subtraction, less for |
| 2693 |
multiplication/division). If \f(CW$y\fR is very small compared to \f(CW$x\fR, the form \f(CW$x\fR += \f(CW$y\fR |
| 2694 |
is MUCH faster than \f(CW$x\fR = \f(CW$x\fR + \f(CW$y\fR since making the copy of \f(CW$x\fR takes more time |
| 2695 |
then the actual addition. |
| 2696 |
.PP |
| 2697 |
With a technique called copy-on-write, the cost of copying with overload could |
| 2698 |
be minimized or even completely avoided. A test implementation of COW did show |
| 2699 |
performance gains for overloaded math, but introduced a performance loss due to |
| 2700 |
a constant overhead for all other operations. So Math::BigInt does currently |
| 2701 |
not COW. |
| 2702 |
.PP |
| 2703 |
The rewritten version of this module (vs. v0.01) is slower on certain |
| 2704 |
operations, like \f(CWnew()\fR, \f(CWbstr()\fR and \f(CWnumify()\fR. The reason are that it |
| 2705 |
does now more work and handles much more cases. The time spent in these |
| 2706 |
operations is usually gained in the other math operations so that code on the |
| 2707 |
average should get (much) faster. If they don't, please contact the author. |
| 2708 |
.PP |
| 2709 |
Some operations may be slower for small numbers, but are significantly faster |
| 2710 |
for big numbers. Other operations are now constant (O(1), like \f(CWbneg()\fR, |
| 2711 |
\&\f(CWbabs()\fR etc), instead of O(N) and thus nearly always take much less time. |
| 2712 |
These optimizations were done on purpose. |
| 2713 |
.PP |
| 2714 |
If you find the Calc module to slow, try to install any of the replacement |
| 2715 |
modules and see if they help you. |
| 2716 |
.SS "Alternative math libraries" |
| 2717 |
.IX Subsection "Alternative math libraries" |
| 2718 |
You can use an alternative library to drive Math::BigInt. See the section |
| 2719 |
"MATH LIBRARY" for more information. |
| 2720 |
.PP |
| 2721 |
For more benchmark results see <http://bloodgate.com/perl/benchmarks.html>. |
| 2722 |
.SH SUBCLASSING |
| 2723 |
.IX Header "SUBCLASSING" |
| 2724 |
.SS "Subclassing Math::BigInt" |
| 2725 |
.IX Subsection "Subclassing Math::BigInt" |
| 2726 |
The basic design of Math::BigInt allows simple subclasses with very little |
| 2727 |
work, as long as a few simple rules are followed: |
| 2728 |
.IP \(bu 4 |
| 2729 |
The public API must remain consistent, i.e. if a sub-class is overloading |
| 2730 |
addition, the sub-class must use the same name, in this case \fBbadd()\fR. The reason |
| 2731 |
for this is that Math::BigInt is optimized to call the object methods directly. |
| 2732 |
.IP \(bu 4 |
| 2733 |
The private object hash keys like \f(CW\*(C`$x\->{sign}\*(C'\fR may not be changed, but |
| 2734 |
additional keys can be added, like \f(CW\*(C`$x\->{_custom}\*(C'\fR. |
| 2735 |
.IP \(bu 4 |
| 2736 |
Accessor functions are available for all existing object hash keys and should |
| 2737 |
be used instead of directly accessing the internal hash keys. The reason for |
| 2738 |
this is that Math::BigInt itself has a pluggable interface which permits it to |
| 2739 |
support different storage methods. |
| 2740 |
.PP |
| 2741 |
More complex sub-classes may have to replicate more of the logic internal of |
| 2742 |
Math::BigInt if they need to change more basic behaviors. A subclass that needs |
| 2743 |
to merely change the output only needs to overload \f(CWbstr()\fR. |
| 2744 |
.PP |
| 2745 |
All other object methods and overloaded functions can be directly inherited |
| 2746 |
from the parent class. |
| 2747 |
.PP |
| 2748 |
At the very minimum, any subclass needs to provide its own \f(CWnew()\fR and can |
| 2749 |
store additional hash keys in the object. There are also some package globals |
| 2750 |
that must be defined, e.g.: |
| 2751 |
.PP |
| 2752 |
.Vb 5 |
| 2753 |
\& # Globals |
| 2754 |
\& our $accuracy = 2; # round to 2 decimal places |
| 2755 |
\& our $precision = undef; |
| 2756 |
\& our $round_mode = \*(Aqeven\*(Aq; |
| 2757 |
\& our $div_scale = 40; |
| 2758 |
.Ve |
| 2759 |
.PP |
| 2760 |
Additionally, you might want to provide the following two globals to allow |
| 2761 |
auto-upgrading and auto-downgrading: |
| 2762 |
.PP |
| 2763 |
.Vb 2 |
| 2764 |
\& our $upgrade = undef; |
| 2765 |
\& our $downgrade = undef; |
| 2766 |
.Ve |
| 2767 |
.PP |
| 2768 |
This allows Math::BigInt to correctly retrieve package globals from the |
| 2769 |
subclass, like \f(CW$SubClass::precision\fR. See \f(CW\*(C`t/Math/BigInt/Subclass.pm\*(C'\fR, |
| 2770 |
\&\f(CW\*(C`t/Math/BigFloat/SubClass.pm\*(C'\fR, or \f(CW\*(C`t/Math/BigRat/SubClass.pm\*(C'\fR for subclass |
| 2771 |
examples. |
| 2772 |
.PP |
| 2773 |
Don't forget to |
| 2774 |
.PP |
| 2775 |
.Vb 1 |
| 2776 |
\& use overload; |
| 2777 |
.Ve |
| 2778 |
.PP |
| 2779 |
in your subclass to automatically inherit the overloading from the parent. If |
| 2780 |
you like, you can change part of the overloading, look at Math::String for an |
| 2781 |
example. |
| 2782 |
.SH UPGRADING |
| 2783 |
.IX Header "UPGRADING" |
| 2784 |
When used like this: |
| 2785 |
.PP |
| 2786 |
.Vb 1 |
| 2787 |
\& use Math::BigInt upgrade => \*(AqFoo::Bar\*(Aq; |
| 2788 |
.Ve |
| 2789 |
.PP |
| 2790 |
any operation whose result cannot be represented as an integer is upgraded to |
| 2791 |
the class Foo::Bar. Usually this is used in conjunction with Math::BigFloat: |
| 2792 |
.PP |
| 2793 |
.Vb 1 |
| 2794 |
\& use Math::BigInt upgrade => \*(AqMath::BigFloat\*(Aq; |
| 2795 |
.Ve |
| 2796 |
.PP |
| 2797 |
For example, the following returns 3 as a Math::BigInt when no upgrading is |
| 2798 |
defined, and 3.125 as a Math::BigFloat if Math::BigInt is set to upgrade to |
| 2799 |
Math::BigFloat: |
| 2800 |
.PP |
| 2801 |
.Vb 1 |
| 2802 |
\& $x = Math::BigInt \-> new(25) \-> bdiv(8); |
| 2803 |
.Ve |
| 2804 |
.PP |
| 2805 |
As a shortcut, you can use the module bignum: |
| 2806 |
.PP |
| 2807 |
.Vb 1 |
| 2808 |
\& use bignum; |
| 2809 |
.Ve |
| 2810 |
.PP |
| 2811 |
which is also good for one-liners: |
| 2812 |
.PP |
| 2813 |
.Vb 1 |
| 2814 |
\& perl \-Mbignum \-le \*(Aqprint 2 ** 255\*(Aq |
| 2815 |
.Ve |
| 2816 |
.PP |
| 2817 |
This makes it possible to mix arguments of different classes (as in 2.5 + 2) as |
| 2818 |
well es preserve accuracy (as in \fBsqrt\fR\|(3)). |
| 2819 |
.PP |
| 2820 |
Beware: This feature is not fully implemented yet. |
| 2821 |
.SS Auto-upgrade |
| 2822 |
.IX Subsection "Auto-upgrade" |
| 2823 |
The following methods upgrade themselves unconditionally; that is if upgrade is |
| 2824 |
in effect, they always hands up their work: |
| 2825 |
.PP |
| 2826 |
.Vb 1 |
| 2827 |
\& div bsqrt blog bexp bpi bsin bcos batan batan2 |
| 2828 |
.Ve |
| 2829 |
.PP |
| 2830 |
All other methods upgrade themselves only when one (or all) of their arguments |
| 2831 |
are of the class mentioned in \f(CW$upgrade\fR. |
| 2832 |
.SH EXPORTS |
| 2833 |
.IX Header "EXPORTS" |
| 2834 |
\&\f(CW\*(C`Math::BigInt\*(C'\fR exports nothing by default, but can export the following |
| 2835 |
methods: |
| 2836 |
.PP |
| 2837 |
.Vb 2 |
| 2838 |
\& bgcd |
| 2839 |
\& blcm |
| 2840 |
.Ve |
| 2841 |
.SH CAVEATS |
| 2842 |
.IX Header "CAVEATS" |
| 2843 |
Some things might not work as you expect them. Below is documented what is |
| 2844 |
known to be troublesome: |
| 2845 |
.IP "Comparing numbers as strings" 4 |
| 2846 |
.IX Item "Comparing numbers as strings" |
| 2847 |
Both \f(CWbstr()\fR and \f(CWbsstr()\fR as well as stringify via overload drop the |
| 2848 |
leading '+'. This is to be consistent with Perl and to make \f(CW\*(C`cmp\*(C'\fR (especially |
| 2849 |
with overloading) to work as you expect. It also solves problems with |
| 2850 |
\&\f(CW\*(C`Test.pm\*(C'\fR and Test::More, which stringify arguments before comparing them. |
| 2851 |
.Sp |
| 2852 |
Mark Biggar said, when asked about to drop the '+' altogether, or make only |
| 2853 |
\&\f(CW\*(C`cmp\*(C'\fR work: |
| 2854 |
.Sp |
| 2855 |
.Vb 4 |
| 2856 |
\& I agree (with the first alternative), don\*(Aqt add the \*(Aq+\*(Aq on positive |
| 2857 |
\& numbers. It\*(Aqs not as important anymore with the new internal form |
| 2858 |
\& for numbers. It made doing things like abs and neg easier, but |
| 2859 |
\& those have to be done differently now anyway. |
| 2860 |
.Ve |
| 2861 |
.Sp |
| 2862 |
So, the following examples now works as expected: |
| 2863 |
.Sp |
| 2864 |
.Vb 2 |
| 2865 |
\& use Test::More tests => 1; |
| 2866 |
\& use Math::BigInt; |
| 2867 |
\& |
| 2868 |
\& my $x = Math::BigInt \-> new(3*3); |
| 2869 |
\& my $y = Math::BigInt \-> new(3*3); |
| 2870 |
\& |
| 2871 |
\& is($x,3*3, \*(Aqmultiplication\*(Aq); |
| 2872 |
\& print "$x eq 9" if $x eq $y; |
| 2873 |
\& print "$x eq 9" if $x eq \*(Aq9\*(Aq; |
| 2874 |
\& print "$x eq 9" if $x eq 3*3; |
| 2875 |
.Ve |
| 2876 |
.Sp |
| 2877 |
Additionally, the following still works: |
| 2878 |
.Sp |
| 2879 |
.Vb 3 |
| 2880 |
\& print "$x == 9" if $x == $y; |
| 2881 |
\& print "$x == 9" if $x == 9; |
| 2882 |
\& print "$x == 9" if $x == 3*3; |
| 2883 |
.Ve |
| 2884 |
.Sp |
| 2885 |
There is now a \f(CWbsstr()\fR method to get the string in scientific notation aka |
| 2886 |
\&\f(CW1e+2\fR instead of \f(CW100\fR. Be advised that overloaded 'eq' always uses \fBbstr()\fR |
| 2887 |
for comparison, but Perl represents some numbers as 100 and others as 1e+308. |
| 2888 |
If in doubt, convert both arguments to Math::BigInt before comparing them as |
| 2889 |
strings: |
| 2890 |
.Sp |
| 2891 |
.Vb 2 |
| 2892 |
\& use Test::More tests => 3; |
| 2893 |
\& use Math::BigInt; |
| 2894 |
\& |
| 2895 |
\& $x = Math::BigInt\->new(\*(Aq1e56\*(Aq); |
| 2896 |
\& $y = 1e56; |
| 2897 |
\& is($x,$y); # fails |
| 2898 |
\& is($x\->bsstr(), $y); # okay |
| 2899 |
\& $y = Math::BigInt\->new($y); |
| 2900 |
\& is($x, $y); # okay |
| 2901 |
.Ve |
| 2902 |
.Sp |
| 2903 |
Alternatively, simply use \f(CW\*(C`<=>\*(C'\fR for comparisons, this always gets it |
| 2904 |
right. There is not yet a way to get a number automatically represented as a |
| 2905 |
string that matches exactly the way Perl represents it. |
| 2906 |
.Sp |
| 2907 |
See also the section about "Infinity and Not a Number" for problems in |
| 2908 |
comparing NaNs. |
| 2909 |
.IP \fBint()\fR 4 |
| 2910 |
.IX Item "int()" |
| 2911 |
\&\f(CWint()\fR returns (at least for Perl v5.7.1 and up) another Math::BigInt, not a |
| 2912 |
Perl scalar: |
| 2913 |
.Sp |
| 2914 |
.Vb 4 |
| 2915 |
\& $x = Math::BigInt\->new(123); |
| 2916 |
\& $y = int($x); # 123 as a Math::BigInt |
| 2917 |
\& $x = Math::BigFloat\->new(123.45); |
| 2918 |
\& $y = int($x); # 123 as a Math::BigFloat |
| 2919 |
.Ve |
| 2920 |
.Sp |
| 2921 |
If you want a real Perl scalar, use \f(CWnumify()\fR: |
| 2922 |
.Sp |
| 2923 |
.Vb 1 |
| 2924 |
\& $y = $x\->numify(); # 123 as a scalar |
| 2925 |
.Ve |
| 2926 |
.Sp |
| 2927 |
This is seldom necessary, though, because this is done automatically, like when |
| 2928 |
you access an array: |
| 2929 |
.Sp |
| 2930 |
.Vb 1 |
| 2931 |
\& $z = $array[$x]; # does work automatically |
| 2932 |
.Ve |
| 2933 |
.IP "Modifying and =" 4 |
| 2934 |
.IX Item "Modifying and =" |
| 2935 |
Beware of: |
| 2936 |
.Sp |
| 2937 |
.Vb 2 |
| 2938 |
\& $x = Math::BigFloat\->new(5); |
| 2939 |
\& $y = $x; |
| 2940 |
.Ve |
| 2941 |
.Sp |
| 2942 |
This makes a second reference to the \fBsame\fR object and stores it in \f(CW$y\fR. Thus |
| 2943 |
anything that modifies \f(CW$x\fR (except overloaded operators) also modifies \f(CW$y\fR, and |
| 2944 |
vice versa. Or in other words, \f(CW\*(C`=\*(C'\fR is only safe if you modify your |
| 2945 |
Math::BigInt objects only via overloaded math. As soon as you use a method call |
| 2946 |
it breaks: |
| 2947 |
.Sp |
| 2948 |
.Vb 2 |
| 2949 |
\& $x\->bmul(2); |
| 2950 |
\& print "$x, $y\en"; # prints \*(Aq10, 10\*(Aq |
| 2951 |
.Ve |
| 2952 |
.Sp |
| 2953 |
If you want a true copy of \f(CW$x\fR, use: |
| 2954 |
.Sp |
| 2955 |
.Vb 1 |
| 2956 |
\& $y = $x\->copy(); |
| 2957 |
.Ve |
| 2958 |
.Sp |
| 2959 |
You can also chain the calls like this, this first makes a copy and then |
| 2960 |
multiply it by 2: |
| 2961 |
.Sp |
| 2962 |
.Vb 1 |
| 2963 |
\& $y = $x\->copy()\->bmul(2); |
| 2964 |
.Ve |
| 2965 |
.Sp |
| 2966 |
See also the documentation for overload.pm regarding \f(CW\*(C`=\*(C'\fR. |
| 2967 |
.IP "Overloading \-$x" 4 |
| 2968 |
.IX Item "Overloading -$x" |
| 2969 |
The following: |
| 2970 |
.Sp |
| 2971 |
.Vb 1 |
| 2972 |
\& $x = \-$x; |
| 2973 |
.Ve |
| 2974 |
.Sp |
| 2975 |
is slower than |
| 2976 |
.Sp |
| 2977 |
.Vb 1 |
| 2978 |
\& $x\->bneg(); |
| 2979 |
.Ve |
| 2980 |
.Sp |
| 2981 |
since overload calls \f(CW\*(C`sub($x,0,1);\*(C'\fR instead of \f(CWneg($x)\fR. The first variant |
| 2982 |
needs to preserve \f(CW$x\fR since it does not know that it later gets overwritten. |
| 2983 |
This makes a copy of \f(CW$x\fR and takes O(N), but \f(CW$x\fR\->\fBbneg()\fR is O(1). |
| 2984 |
.IP "Mixing different object types" 4 |
| 2985 |
.IX Item "Mixing different object types" |
| 2986 |
With overloaded operators, it is the first (dominating) operand that determines |
| 2987 |
which method is called. Here are some examples showing what actually gets |
| 2988 |
called in various cases. |
| 2989 |
.Sp |
| 2990 |
.Vb 2 |
| 2991 |
\& use Math::BigInt; |
| 2992 |
\& use Math::BigFloat; |
| 2993 |
\& |
| 2994 |
\& $mbf = Math::BigFloat\->new(5); |
| 2995 |
\& $mbi2 = Math::BigInt\->new(5); |
| 2996 |
\& $mbi = Math::BigInt\->new(2); |
| 2997 |
\& # what actually gets called: |
| 2998 |
\& $float = $mbf + $mbi; # $mbf\->badd($mbi) |
| 2999 |
\& $float = $mbf / $mbi; # $mbf\->bdiv($mbi) |
| 3000 |
\& $integer = $mbi + $mbf; # $mbi\->badd($mbf) |
| 3001 |
\& $integer = $mbi2 / $mbi; # $mbi2\->bdiv($mbi) |
| 3002 |
\& $integer = $mbi2 / $mbf; # $mbi2\->bdiv($mbf) |
| 3003 |
.Ve |
| 3004 |
.Sp |
| 3005 |
For instance, Math::BigInt\->\fBbdiv()\fR always returns a Math::BigInt, regardless of |
| 3006 |
whether the second operant is a Math::BigFloat. To get a Math::BigFloat you |
| 3007 |
either need to call the operation manually, make sure each operand already is a |
| 3008 |
Math::BigFloat, or cast to that type via Math::BigFloat\->\fBnew()\fR: |
| 3009 |
.Sp |
| 3010 |
.Vb 1 |
| 3011 |
\& $float = Math::BigFloat\->new($mbi2) / $mbi; # = 2.5 |
| 3012 |
.Ve |
| 3013 |
.Sp |
| 3014 |
Beware of casting the entire expression, as this would cast the |
| 3015 |
result, at which point it is too late: |
| 3016 |
.Sp |
| 3017 |
.Vb 1 |
| 3018 |
\& $float = Math::BigFloat\->new($mbi2 / $mbi); # = 2 |
| 3019 |
.Ve |
| 3020 |
.Sp |
| 3021 |
Beware also of the order of more complicated expressions like: |
| 3022 |
.Sp |
| 3023 |
.Vb 2 |
| 3024 |
\& $integer = ($mbi2 + $mbi) / $mbf; # int / float => int |
| 3025 |
\& $integer = $mbi2 / Math::BigFloat\->new($mbi); # ditto |
| 3026 |
.Ve |
| 3027 |
.Sp |
| 3028 |
If in doubt, break the expression into simpler terms, or cast all operands |
| 3029 |
to the desired resulting type. |
| 3030 |
.Sp |
| 3031 |
Scalar values are a bit different, since: |
| 3032 |
.Sp |
| 3033 |
.Vb 2 |
| 3034 |
\& $float = 2 + $mbf; |
| 3035 |
\& $float = $mbf + 2; |
| 3036 |
.Ve |
| 3037 |
.Sp |
| 3038 |
both result in the proper type due to the way the overloaded math works. |
| 3039 |
.Sp |
| 3040 |
This section also applies to other overloaded math packages, like Math::String. |
| 3041 |
.Sp |
| 3042 |
One solution to you problem might be autoupgrading|upgrading. See the |
| 3043 |
pragmas bignum, bigint and bigrat for an easy way to do this. |
| 3044 |
.SH BUGS |
| 3045 |
.IX Header "BUGS" |
| 3046 |
Please report any bugs or feature requests to |
| 3047 |
\&\f(CW\*(C`bug\-math\-bigint at rt.cpan.org\*(C'\fR, or through the web interface at |
| 3048 |
<https://rt.cpan.org/Ticket/Create.html?Queue=Math\-BigInt> (requires login). |
| 3049 |
We will be notified, and then you'll automatically be notified of progress on |
| 3050 |
your bug as I make changes. |
| 3051 |
.SH SUPPORT |
| 3052 |
.IX Header "SUPPORT" |
| 3053 |
You can find documentation for this module with the perldoc command. |
| 3054 |
.PP |
| 3055 |
.Vb 1 |
| 3056 |
\& perldoc Math::BigInt |
| 3057 |
.Ve |
| 3058 |
.PP |
| 3059 |
You can also look for information at: |
| 3060 |
.IP \(bu 4 |
| 3061 |
GitHub |
| 3062 |
.Sp |
| 3063 |
<https://github.com/pjacklam/p5\-Math\-BigInt> |
| 3064 |
.IP \(bu 4 |
| 3065 |
RT: CPAN's request tracker |
| 3066 |
.Sp |
| 3067 |
<https://rt.cpan.org/Dist/Display.html?Name=Math\-BigInt> |
| 3068 |
.IP \(bu 4 |
| 3069 |
MetaCPAN |
| 3070 |
.Sp |
| 3071 |
<https://metacpan.org/release/Math\-BigInt> |
| 3072 |
.IP \(bu 4 |
| 3073 |
CPAN Testers Matrix |
| 3074 |
.Sp |
| 3075 |
<http://matrix.cpantesters.org/?dist=Math\-BigInt> |
| 3076 |
.SH LICENSE |
| 3077 |
.IX Header "LICENSE" |
| 3078 |
This program is free software; you may redistribute it and/or modify it under |
| 3079 |
the same terms as Perl itself. |
| 3080 |
.SH "SEE ALSO" |
| 3081 |
.IX Header "SEE ALSO" |
| 3082 |
Math::BigFloat and Math::BigRat as well as the backend libraries |
| 3083 |
Math::BigInt::FastCalc, Math::BigInt::GMP, and Math::BigInt::Pari, |
| 3084 |
Math::BigInt::GMPz, and Math::BigInt::BitVect. |
| 3085 |
.PP |
| 3086 |
The pragmas bigint, bigfloat, and bigrat might also be of interest. In |
| 3087 |
addition there is the bignum pragma which does upgrading and downgrading. |
| 3088 |
.SH AUTHORS |
| 3089 |
.IX Header "AUTHORS" |
| 3090 |
.IP \(bu 4 |
| 3091 |
Mark Biggar, overloaded interface by Ilya Zakharevich, 1996\-2001. |
| 3092 |
.IP \(bu 4 |
| 3093 |
Completely rewritten by Tels <http://bloodgate.com>, 2001\-2008. |
| 3094 |
.IP \(bu 4 |
| 3095 |
Florian Ragwitz <[email protected]>, 2010. |
| 3096 |
.IP \(bu 4 |
| 3097 |
Peter John Acklam <[email protected]>, 2011\-. |
| 3098 |
.PP |
| 3099 |
Many people contributed in one or more ways to the final beast, see the file |
| 3100 |
CREDITS for an (incomplete) list. If you miss your name, please drop me a |
| 3101 |
mail. Thank you! |