| 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::BigFloat 3perl" |
| 58 |
.TH Math::BigFloat 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::BigFloat \- arbitrary size floating point math package |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
.Vb 1 |
| 68 |
\& use Math::BigFloat; |
| 69 |
\& |
| 70 |
\& # Configuration methods (may be used as class methods and instance methods) |
| 71 |
\& |
| 72 |
\& Math::BigFloat\->accuracy(); # get class accuracy |
| 73 |
\& Math::BigFloat\->accuracy($n); # set class accuracy |
| 74 |
\& Math::BigFloat\->precision(); # get class precision |
| 75 |
\& Math::BigFloat\->precision($n); # set class precision |
| 76 |
\& Math::BigFloat\->round_mode(); # get class rounding mode |
| 77 |
\& Math::BigFloat\->round_mode($m); # set global round mode, must be one of |
| 78 |
\& # \*(Aqeven\*(Aq, \*(Aqodd\*(Aq, \*(Aq+inf\*(Aq, \*(Aq\-inf\*(Aq, \*(Aqzero\*(Aq, |
| 79 |
\& # \*(Aqtrunc\*(Aq, or \*(Aqcommon\*(Aq |
| 80 |
\& Math::BigFloat\->config("lib"); # name of backend math library |
| 81 |
\& |
| 82 |
\& # Constructor methods (when the class methods below are used as instance |
| 83 |
\& # methods, the value is assigned the invocand) |
| 84 |
\& |
| 85 |
\& $x = Math::BigFloat\->new($str); # defaults to 0 |
| 86 |
\& $x = Math::BigFloat\->new(\*(Aq0x123\*(Aq); # from hexadecimal |
| 87 |
\& $x = Math::BigFloat\->new(\*(Aq0o377\*(Aq); # from octal |
| 88 |
\& $x = Math::BigFloat\->new(\*(Aq0b101\*(Aq); # from binary |
| 89 |
\& $x = Math::BigFloat\->from_hex(\*(Aq0xc.afep+3\*(Aq); # from hex |
| 90 |
\& $x = Math::BigFloat\->from_hex(\*(Aqcafe\*(Aq); # ditto |
| 91 |
\& $x = Math::BigFloat\->from_oct(\*(Aq1.3267p\-4\*(Aq); # from octal |
| 92 |
\& $x = Math::BigFloat\->from_oct(\*(Aq01.3267p\-4\*(Aq); # ditto |
| 93 |
\& $x = Math::BigFloat\->from_oct(\*(Aq0o1.3267p\-4\*(Aq); # ditto |
| 94 |
\& $x = Math::BigFloat\->from_oct(\*(Aq0377\*(Aq); # ditto |
| 95 |
\& $x = Math::BigFloat\->from_bin(\*(Aq0b1.1001p\-4\*(Aq); # from binary |
| 96 |
\& $x = Math::BigFloat\->from_bin(\*(Aq0101\*(Aq); # ditto |
| 97 |
\& $x = Math::BigFloat\->from_ieee754($b, "binary64"); # from IEEE\-754 bytes |
| 98 |
\& $x = Math::BigFloat\->bzero(); # create a +0 |
| 99 |
\& $x = Math::BigFloat\->bone(); # create a +1 |
| 100 |
\& $x = Math::BigFloat\->bone(\*(Aq\-\*(Aq); # create a \-1 |
| 101 |
\& $x = Math::BigFloat\->binf(); # create a +inf |
| 102 |
\& $x = Math::BigFloat\->binf(\*(Aq\-\*(Aq); # create a \-inf |
| 103 |
\& $x = Math::BigFloat\->bnan(); # create a Not\-A\-Number |
| 104 |
\& $x = Math::BigFloat\->bpi(); # returns pi |
| 105 |
\& |
| 106 |
\& $y = $x\->copy(); # make a copy (unlike $y = $x) |
| 107 |
\& $y = $x\->as_int(); # return as BigInt |
| 108 |
\& $y = $x\->as_float(); # return as a Math::BigFloat |
| 109 |
\& $y = $x\->as_rat(); # return as a Math::BigRat |
| 110 |
\& |
| 111 |
\& # Boolean methods (these don\*(Aqt modify the invocand) |
| 112 |
\& |
| 113 |
\& $x\->is_zero(); # if $x is 0 |
| 114 |
\& $x\->is_one(); # if $x is +1 |
| 115 |
\& $x\->is_one("+"); # ditto |
| 116 |
\& $x\->is_one("\-"); # if $x is \-1 |
| 117 |
\& $x\->is_inf(); # if $x is +inf or \-inf |
| 118 |
\& $x\->is_inf("+"); # if $x is +inf |
| 119 |
\& $x\->is_inf("\-"); # if $x is \-inf |
| 120 |
\& $x\->is_nan(); # if $x is NaN |
| 121 |
\& |
| 122 |
\& $x\->is_positive(); # if $x > 0 |
| 123 |
\& $x\->is_pos(); # ditto |
| 124 |
\& $x\->is_negative(); # if $x < 0 |
| 125 |
\& $x\->is_neg(); # ditto |
| 126 |
\& |
| 127 |
\& $x\->is_odd(); # if $x is odd |
| 128 |
\& $x\->is_even(); # if $x is even |
| 129 |
\& $x\->is_int(); # if $x is an integer |
| 130 |
\& |
| 131 |
\& # Comparison methods |
| 132 |
\& |
| 133 |
\& $x\->bcmp($y); # compare numbers (undef, < 0, == 0, > 0) |
| 134 |
\& $x\->bacmp($y); # compare absolutely (undef, < 0, == 0, > 0) |
| 135 |
\& $x\->beq($y); # true if and only if $x == $y |
| 136 |
\& $x\->bne($y); # true if and only if $x != $y |
| 137 |
\& $x\->blt($y); # true if and only if $x < $y |
| 138 |
\& $x\->ble($y); # true if and only if $x <= $y |
| 139 |
\& $x\->bgt($y); # true if and only if $x > $y |
| 140 |
\& $x\->bge($y); # true if and only if $x >= $y |
| 141 |
\& |
| 142 |
\& # Arithmetic methods |
| 143 |
\& |
| 144 |
\& $x\->bneg(); # negation |
| 145 |
\& $x\->babs(); # absolute value |
| 146 |
\& $x\->bsgn(); # sign function (\-1, 0, 1, or NaN) |
| 147 |
\& $x\->bnorm(); # normalize (no\-op) |
| 148 |
\& $x\->binc(); # increment $x by 1 |
| 149 |
\& $x\->bdec(); # decrement $x by 1 |
| 150 |
\& $x\->badd($y); # addition (add $y to $x) |
| 151 |
\& $x\->bsub($y); # subtraction (subtract $y from $x) |
| 152 |
\& $x\->bmul($y); # multiplication (multiply $x by $y) |
| 153 |
\& $x\->bmuladd($y,$z); # $x = $x * $y + $z |
| 154 |
\& $x\->bdiv($y); # division (floored), set $x to quotient |
| 155 |
\& # return (quo,rem) or quo if scalar |
| 156 |
\& $x\->btdiv($y); # division (truncated), set $x to quotient |
| 157 |
\& # return (quo,rem) or quo if scalar |
| 158 |
\& $x\->bmod($y); # modulus (x % y) |
| 159 |
\& $x\->btmod($y); # modulus (truncated) |
| 160 |
\& $x\->bmodinv($mod); # modular multiplicative inverse |
| 161 |
\& $x\->bmodpow($y,$mod); # modular exponentiation (($x ** $y) % $mod) |
| 162 |
\& $x\->bpow($y); # power of arguments (x ** y) |
| 163 |
\& $x\->blog(); # logarithm of $x to base e (Euler\*(Aqs number) |
| 164 |
\& $x\->blog($base); # logarithm of $x to base $base (e.g., base 2) |
| 165 |
\& $x\->bexp(); # calculate e ** $x where e is Euler\*(Aqs number |
| 166 |
\& $x\->bnok($y); # x over y (binomial coefficient n over k) |
| 167 |
\& $x\->bsin(); # sine |
| 168 |
\& $x\->bcos(); # cosine |
| 169 |
\& $x\->batan(); # inverse tangent |
| 170 |
\& $x\->batan2($y); # two\-argument inverse tangent |
| 171 |
\& $x\->bsqrt(); # calculate square root |
| 172 |
\& $x\->broot($y); # $y\*(Aqth root of $x (e.g. $y == 3 => cubic root) |
| 173 |
\& $x\->bfac(); # factorial of $x (1*2*3*4*..$x) |
| 174 |
\& |
| 175 |
\& $x\->blsft($n); # left shift $n places in base 2 |
| 176 |
\& $x\->blsft($n,$b); # left shift $n places in base $b |
| 177 |
\& # returns (quo,rem) or quo (scalar context) |
| 178 |
\& $x\->brsft($n); # right shift $n places in base 2 |
| 179 |
\& $x\->brsft($n,$b); # right shift $n places in base $b |
| 180 |
\& # returns (quo,rem) or quo (scalar context) |
| 181 |
\& |
| 182 |
\& # Bitwise methods |
| 183 |
\& |
| 184 |
\& $x\->bblsft($y); # bitwise left shift |
| 185 |
\& $x\->bbrsft($y); # bitwise right shift |
| 186 |
\& $x\->band($y); # bitwise and |
| 187 |
\& $x\->bior($y); # bitwise inclusive or |
| 188 |
\& $x\->bxor($y); # bitwise exclusive or |
| 189 |
\& $x\->bnot(); # bitwise not (two\*(Aqs complement) |
| 190 |
\& |
| 191 |
\& # Rounding methods |
| 192 |
\& $x\->round($A,$P,$mode); # round to accuracy or precision using |
| 193 |
\& # rounding mode $mode |
| 194 |
\& $x\->bround($n); # accuracy: preserve $n digits |
| 195 |
\& $x\->bfround($n); # $n > 0: round to $nth digit left of dec. point |
| 196 |
\& # $n < 0: round to $nth digit right of dec. point |
| 197 |
\& $x\->bfloor(); # round towards minus infinity |
| 198 |
\& $x\->bceil(); # round towards plus infinity |
| 199 |
\& $x\->bint(); # round towards zero |
| 200 |
\& |
| 201 |
\& # Other mathematical methods |
| 202 |
\& |
| 203 |
\& $x\->bgcd($y); # greatest common divisor |
| 204 |
\& $x\->blcm($y); # least common multiple |
| 205 |
\& |
| 206 |
\& # Object property methods (do not modify the invocand) |
| 207 |
\& |
| 208 |
\& $x\->sign(); # the sign, either +, \- or NaN |
| 209 |
\& $x\->digit($n); # the nth digit, counting from the right |
| 210 |
\& $x\->digit(\-$n); # the nth digit, counting from the left |
| 211 |
\& $x\->length(); # return number of digits in number |
| 212 |
\& ($xl,$f) = $x\->length(); # length of number and length of fraction |
| 213 |
\& # part, latter is always 0 digits long |
| 214 |
\& # for Math::BigInt objects |
| 215 |
\& $x\->mantissa(); # return (signed) mantissa as BigInt |
| 216 |
\& $x\->exponent(); # return exponent as BigInt |
| 217 |
\& $x\->parts(); # return (mantissa,exponent) as BigInt |
| 218 |
\& $x\->sparts(); # mantissa and exponent (as integers) |
| 219 |
\& $x\->nparts(); # mantissa and exponent (normalised) |
| 220 |
\& $x\->eparts(); # mantissa and exponent (engineering notation) |
| 221 |
\& $x\->dparts(); # integer and fraction part |
| 222 |
\& $x\->fparts(); # numerator and denominator |
| 223 |
\& $x\->numerator(); # numerator |
| 224 |
\& $x\->denominator(); # denominator |
| 225 |
\& |
| 226 |
\& # Conversion methods (do not modify the invocand) |
| 227 |
\& |
| 228 |
\& $x\->bstr(); # decimal notation, possibly zero padded |
| 229 |
\& $x\->bsstr(); # string in scientific notation with integers |
| 230 |
\& $x\->bnstr(); # string in normalized notation |
| 231 |
\& $x\->bestr(); # string in engineering notation |
| 232 |
\& $x\->bdstr(); # string in decimal notation |
| 233 |
\& $x\->bfstr(); # string in fractional notation |
| 234 |
\& |
| 235 |
\& $x\->as_hex(); # as signed hexadecimal string with prefixed 0x |
| 236 |
\& $x\->as_bin(); # as signed binary string with prefixed 0b |
| 237 |
\& $x\->as_oct(); # as signed octal string with prefixed 0 |
| 238 |
\& $x\->to_ieee754($format); # to bytes encoded according to IEEE 754\-2008 |
| 239 |
\& |
| 240 |
\& # Other conversion methods |
| 241 |
\& |
| 242 |
\& $x\->numify(); # return as scalar (might overflow or underflow) |
| 243 |
.Ve |
| 244 |
.SH DESCRIPTION |
| 245 |
.IX Header "DESCRIPTION" |
| 246 |
Math::BigFloat provides support for arbitrary precision floating point. |
| 247 |
Overloading is also provided for Perl operators. |
| 248 |
.PP |
| 249 |
All operators (including basic math operations) are overloaded if you |
| 250 |
declare your big floating point numbers as |
| 251 |
.PP |
| 252 |
.Vb 1 |
| 253 |
\& $x = Math::BigFloat \-> new(\*(Aq12_3.456_789_123_456_789E\-2\*(Aq); |
| 254 |
.Ve |
| 255 |
.PP |
| 256 |
Operations with overloaded operators preserve the arguments, which is |
| 257 |
exactly what you expect. |
| 258 |
.SS Input |
| 259 |
.IX Subsection "Input" |
| 260 |
Input values to these routines may be any scalar number or string that looks |
| 261 |
like a number. Anything that is accepted by Perl as a literal numeric constant |
| 262 |
should be accepted by this module. |
| 263 |
.IP \(bu 4 |
| 264 |
Leading and trailing whitespace is ignored. |
| 265 |
.IP \(bu 4 |
| 266 |
Leading zeros are ignored, except for floating point numbers with a binary |
| 267 |
exponent, in which case the number is interpreted as an octal floating point |
| 268 |
number. For example, "01.4p+0" gives 1.5, "00.4p+0" gives 0.5, but "0.4p+0" |
| 269 |
gives a NaN. And while "0377" gives 255, "0377p0" gives 255. |
| 270 |
.IP \(bu 4 |
| 271 |
If the string has a "0x" or "0X" prefix, it is interpreted as a hexadecimal |
| 272 |
number. |
| 273 |
.IP \(bu 4 |
| 274 |
If the string has a "0o" or "0O" prefix, it is interpreted as an octal number. A |
| 275 |
floating point literal with a "0" prefix is also interpreted as an octal number. |
| 276 |
.IP \(bu 4 |
| 277 |
If the string has a "0b" or "0B" prefix, it is interpreted as a binary number. |
| 278 |
.IP \(bu 4 |
| 279 |
Underline characters are allowed in the same way as they are allowed in literal |
| 280 |
numerical constants. |
| 281 |
.IP \(bu 4 |
| 282 |
If the string can not be interpreted, NaN is returned. |
| 283 |
.IP \(bu 4 |
| 284 |
For hexadecimal, octal, and binary floating point numbers, the exponent must be |
| 285 |
separated from the significand (mantissa) by the letter "p" or "P", not "e" or |
| 286 |
"E" as with decimal numbers. |
| 287 |
.PP |
| 288 |
Some examples of valid string input |
| 289 |
.PP |
| 290 |
.Vb 1 |
| 291 |
\& Input string Resulting value |
| 292 |
\& |
| 293 |
\& 123 123 |
| 294 |
\& 1.23e2 123 |
| 295 |
\& 12300e\-2 123 |
| 296 |
\& |
| 297 |
\& 67_538_754 67538754 |
| 298 |
\& \-4_5_6.7_8_9e+0_1_0 \-4567890000000 |
| 299 |
\& |
| 300 |
\& 0x13a 314 |
| 301 |
\& 0x13ap0 314 |
| 302 |
\& 0x1.3ap+8 314 |
| 303 |
\& 0x0.00013ap+24 314 |
| 304 |
\& 0x13a000p\-12 314 |
| 305 |
\& |
| 306 |
\& 0o472 314 |
| 307 |
\& 0o1.164p+8 314 |
| 308 |
\& 0o0.0001164p+20 314 |
| 309 |
\& 0o1164000p\-10 314 |
| 310 |
\& |
| 311 |
\& 0472 472 Note! |
| 312 |
\& 01.164p+8 314 |
| 313 |
\& 00.0001164p+20 314 |
| 314 |
\& 01164000p\-10 314 |
| 315 |
\& |
| 316 |
\& 0b100111010 314 |
| 317 |
\& 0b1.0011101p+8 314 |
| 318 |
\& 0b0.00010011101p+12 314 |
| 319 |
\& 0b100111010000p\-3 314 |
| 320 |
\& |
| 321 |
\& 0x1.921fb5p+1 3.14159262180328369140625e+0 |
| 322 |
\& 0o1.2677025p1 2.71828174591064453125 |
| 323 |
\& 01.2677025p1 2.71828174591064453125 |
| 324 |
\& 0b1.1001p\-4 9.765625e\-2 |
| 325 |
.Ve |
| 326 |
.SS Output |
| 327 |
.IX Subsection "Output" |
| 328 |
Output values are usually Math::BigFloat objects. |
| 329 |
.PP |
| 330 |
Boolean operators \f(CWis_zero()\fR, \f(CWis_one()\fR, \f(CWis_inf()\fR, etc. return true or |
| 331 |
false. |
| 332 |
.PP |
| 333 |
Comparison operators \f(CWbcmp()\fR and \f(CWbacmp()\fR) return \-1, 0, 1, or |
| 334 |
undef. |
| 335 |
.SH METHODS |
| 336 |
.IX Header "METHODS" |
| 337 |
Math::BigFloat supports all methods that Math::BigInt supports, except it |
| 338 |
calculates non-integer results when possible. Please see Math::BigInt for a |
| 339 |
full description of each method. Below are just the most important differences: |
| 340 |
.SS "Configuration methods" |
| 341 |
.IX Subsection "Configuration methods" |
| 342 |
.IP \fBaccuracy()\fR 4 |
| 343 |
.IX Item "accuracy()" |
| 344 |
.Vb 3 |
| 345 |
\& $x\->accuracy(5); # local for $x |
| 346 |
\& CLASS\->accuracy(5); # global for all members of CLASS |
| 347 |
\& # Note: This also applies to new()! |
| 348 |
\& |
| 349 |
\& $A = $x\->accuracy(); # read out accuracy that affects $x |
| 350 |
\& $A = CLASS\->accuracy(); # read out global accuracy |
| 351 |
.Ve |
| 352 |
.Sp |
| 353 |
Set or get the global or local accuracy, aka how many significant digits the |
| 354 |
results have. If you set a global accuracy, then this also applies to \fBnew()\fR! |
| 355 |
.Sp |
| 356 |
Warning! The accuracy \fIsticks\fR, e.g. once you created a number under the |
| 357 |
influence of \f(CW\*(C`CLASS\->accuracy($A)\*(C'\fR, all results from math operations with |
| 358 |
that number will also be rounded. |
| 359 |
.Sp |
| 360 |
In most cases, you should probably round the results explicitly using one of |
| 361 |
"\fBround()\fR" in Math::BigInt, "\fBbround()\fR" in Math::BigInt or "\fBbfround()\fR" in Math::BigInt |
| 362 |
or by passing the desired accuracy to the math operation as additional |
| 363 |
parameter: |
| 364 |
.Sp |
| 365 |
.Vb 4 |
| 366 |
\& my $x = Math::BigInt\->new(30000); |
| 367 |
\& my $y = Math::BigInt\->new(7); |
| 368 |
\& print scalar $x\->copy()\->bdiv($y, 2); # print 4300 |
| 369 |
\& print scalar $x\->copy()\->bdiv($y)\->bround(2); # print 4300 |
| 370 |
.Ve |
| 371 |
.IP \fBprecision()\fR 4 |
| 372 |
.IX Item "precision()" |
| 373 |
.Vb 4 |
| 374 |
\& $x\->precision(\-2); # local for $x, round at the second |
| 375 |
\& # digit right of the dot |
| 376 |
\& $x\->precision(2); # ditto, round at the second digit |
| 377 |
\& # left of the dot |
| 378 |
\& |
| 379 |
\& CLASS\->precision(5); # Global for all members of CLASS |
| 380 |
\& # This also applies to new()! |
| 381 |
\& CLASS\->precision(\-5); # ditto |
| 382 |
\& |
| 383 |
\& $P = CLASS\->precision(); # read out global precision |
| 384 |
\& $P = $x\->precision(); # read out precision that affects $x |
| 385 |
.Ve |
| 386 |
.Sp |
| 387 |
Note: You probably want to use "\fBaccuracy()\fR" instead. With "\fBaccuracy()\fR" you |
| 388 |
set the number of digits each result should have, with "\fBprecision()\fR" you |
| 389 |
set the place where to round! |
| 390 |
.SS "Constructor methods" |
| 391 |
.IX Subsection "Constructor methods" |
| 392 |
.IP \fBfrom_hex()\fR 4 |
| 393 |
.IX Item "from_hex()" |
| 394 |
.Vb 2 |
| 395 |
\& $x \-> from_hex("0x1.921fb54442d18p+1"); |
| 396 |
\& $x = Math::BigFloat \-> from_hex("0x1.921fb54442d18p+1"); |
| 397 |
.Ve |
| 398 |
.Sp |
| 399 |
Interpret input as a hexadecimal string.A prefix ("0x", "x", ignoring case) is |
| 400 |
optional. A single underscore character ("_") may be placed between any two |
| 401 |
digits. If the input is invalid, a NaN is returned. The exponent is in base 2 |
| 402 |
using decimal digits. |
| 403 |
.Sp |
| 404 |
If called as an instance method, the value is assigned to the invocand. |
| 405 |
.IP \fBfrom_oct()\fR 4 |
| 406 |
.IX Item "from_oct()" |
| 407 |
.Vb 2 |
| 408 |
\& $x \-> from_oct("1.3267p\-4"); |
| 409 |
\& $x = Math::BigFloat \-> from_oct("1.3267p\-4"); |
| 410 |
.Ve |
| 411 |
.Sp |
| 412 |
Interpret input as an octal string. A single underscore character ("_") may be |
| 413 |
placed between any two digits. If the input is invalid, a NaN is returned. The |
| 414 |
exponent is in base 2 using decimal digits. |
| 415 |
.Sp |
| 416 |
If called as an instance method, the value is assigned to the invocand. |
| 417 |
.IP \fBfrom_bin()\fR 4 |
| 418 |
.IX Item "from_bin()" |
| 419 |
.Vb 2 |
| 420 |
\& $x \-> from_bin("0b1.1001p\-4"); |
| 421 |
\& $x = Math::BigFloat \-> from_bin("0b1.1001p\-4"); |
| 422 |
.Ve |
| 423 |
.Sp |
| 424 |
Interpret input as a hexadecimal string. A prefix ("0b" or "b", ignoring case) |
| 425 |
is optional. A single underscore character ("_") may be placed between any two |
| 426 |
digits. If the input is invalid, a NaN is returned. The exponent is in base 2 |
| 427 |
using decimal digits. |
| 428 |
.Sp |
| 429 |
If called as an instance method, the value is assigned to the invocand. |
| 430 |
.IP \fBfrom_ieee754()\fR 4 |
| 431 |
.IX Item "from_ieee754()" |
| 432 |
Interpret the input as a value encoded as described in IEEE754\-2008. The input |
| 433 |
can be given as a byte string, hex string or binary string. The input is |
| 434 |
assumed to be in big-endian byte-order. |
| 435 |
.Sp |
| 436 |
.Vb 4 |
| 437 |
\& # both $dbl and $mbf are 3.141592... |
| 438 |
\& $bytes = "\ex40\ex09\ex21\exfb\ex54\ex44\ex2d\ex18"; |
| 439 |
\& $dbl = unpack "d>", $bytes; |
| 440 |
\& $mbf = Math::BigFloat \-> from_ieee754($bytes, "binary64"); |
| 441 |
.Ve |
| 442 |
.IP \fBbpi()\fR 4 |
| 443 |
.IX Item "bpi()" |
| 444 |
.Vb 1 |
| 445 |
\& print Math::BigFloat\->bpi(100), "\en"; |
| 446 |
.Ve |
| 447 |
.Sp |
| 448 |
Calculate PI to N digits (including the 3 before the dot). The result is |
| 449 |
rounded according to the current rounding mode, which defaults to "even". |
| 450 |
.Sp |
| 451 |
This method was added in v1.87 of Math::BigInt (June 2007). |
| 452 |
.SS "Arithmetic methods" |
| 453 |
.IX Subsection "Arithmetic methods" |
| 454 |
.IP \fBbmuladd()\fR 4 |
| 455 |
.IX Item "bmuladd()" |
| 456 |
.Vb 1 |
| 457 |
\& $x\->bmuladd($y,$z); |
| 458 |
.Ve |
| 459 |
.Sp |
| 460 |
Multiply \f(CW$x\fR by \f(CW$y\fR, and then add \f(CW$z\fR to the result. |
| 461 |
.Sp |
| 462 |
This method was added in v1.87 of Math::BigInt (June 2007). |
| 463 |
.IP \fBbinv()\fR 4 |
| 464 |
.IX Item "binv()" |
| 465 |
.Vb 1 |
| 466 |
\& $x\->binv(); |
| 467 |
.Ve |
| 468 |
.Sp |
| 469 |
Invert the value of \f(CW$x\fR, i.e., compute 1/$x. |
| 470 |
.IP \fBbdiv()\fR 4 |
| 471 |
.IX Item "bdiv()" |
| 472 |
.Vb 2 |
| 473 |
\& $q = $x\->bdiv($y); |
| 474 |
\& ($q, $r) = $x\->bdiv($y); |
| 475 |
.Ve |
| 476 |
.Sp |
| 477 |
In scalar context, divides \f(CW$x\fR by \f(CW$y\fR and returns the result to the given or |
| 478 |
default accuracy/precision. In list context, does floored division |
| 479 |
(F\-division), returning an integer \f(CW$q\fR and a remainder \f(CW$r\fR so that \f(CW$x\fR = \f(CW$q\fR * \f(CW$y\fR + |
| 480 |
\&\f(CW$r\fR. The remainer (modulo) is equal to what is returned by \f(CW\*(C`$x\->bmod($y)\*(C'\fR. |
| 481 |
.IP \fBbmod()\fR 4 |
| 482 |
.IX Item "bmod()" |
| 483 |
.Vb 1 |
| 484 |
\& $x\->bmod($y); |
| 485 |
.Ve |
| 486 |
.Sp |
| 487 |
Returns \f(CW$x\fR modulo \f(CW$y\fR. When \f(CW$x\fR is finite, and \f(CW$y\fR is finite and non-zero, the |
| 488 |
result is identical to the remainder after floored division (F\-division). If, |
| 489 |
in addition, both \f(CW$x\fR and \f(CW$y\fR are integers, the result is identical to the result |
| 490 |
from Perl's % operator. |
| 491 |
.IP \fBbexp()\fR 4 |
| 492 |
.IX Item "bexp()" |
| 493 |
.Vb 1 |
| 494 |
\& $x\->bexp($accuracy); # calculate e ** X |
| 495 |
.Ve |
| 496 |
.Sp |
| 497 |
Calculates the expression \f(CW\*(C`e ** $x\*(C'\fR where \f(CW\*(C`e\*(C'\fR is Euler's number. |
| 498 |
.Sp |
| 499 |
This method was added in v1.82 of Math::BigInt (April 2007). |
| 500 |
.IP \fBbnok()\fR 4 |
| 501 |
.IX Item "bnok()" |
| 502 |
.Vb 1 |
| 503 |
\& $x\->bnok($y); # x over y (binomial coefficient n over k) |
| 504 |
.Ve |
| 505 |
.Sp |
| 506 |
Calculates the binomial coefficient n over k, also called the "choose" |
| 507 |
function. The result is equivalent to: |
| 508 |
.Sp |
| 509 |
.Vb 3 |
| 510 |
\& ( n ) n! |
| 511 |
\& | \- | = \-\-\-\-\-\-\- |
| 512 |
\& ( k ) k!(n\-k)! |
| 513 |
.Ve |
| 514 |
.Sp |
| 515 |
This method was added in v1.84 of Math::BigInt (April 2007). |
| 516 |
.IP \fBbsin()\fR 4 |
| 517 |
.IX Item "bsin()" |
| 518 |
.Vb 2 |
| 519 |
\& my $x = Math::BigFloat\->new(1); |
| 520 |
\& print $x\->bsin(100), "\en"; |
| 521 |
.Ve |
| 522 |
.Sp |
| 523 |
Calculate the sinus of \f(CW$x\fR, modifying \f(CW$x\fR in place. |
| 524 |
.Sp |
| 525 |
This method was added in v1.87 of Math::BigInt (June 2007). |
| 526 |
.IP \fBbcos()\fR 4 |
| 527 |
.IX Item "bcos()" |
| 528 |
.Vb 2 |
| 529 |
\& my $x = Math::BigFloat\->new(1); |
| 530 |
\& print $x\->bcos(100), "\en"; |
| 531 |
.Ve |
| 532 |
.Sp |
| 533 |
Calculate the cosinus of \f(CW$x\fR, modifying \f(CW$x\fR in place. |
| 534 |
.Sp |
| 535 |
This method was added in v1.87 of Math::BigInt (June 2007). |
| 536 |
.IP \fBbatan()\fR 4 |
| 537 |
.IX Item "batan()" |
| 538 |
.Vb 2 |
| 539 |
\& my $x = Math::BigFloat\->new(1); |
| 540 |
\& print $x\->batan(100), "\en"; |
| 541 |
.Ve |
| 542 |
.Sp |
| 543 |
Calculate the arcus tanges of \f(CW$x\fR, modifying \f(CW$x\fR in place. See also "\fBbatan2()\fR". |
| 544 |
.Sp |
| 545 |
This method was added in v1.87 of Math::BigInt (June 2007). |
| 546 |
.IP \fBbatan2()\fR 4 |
| 547 |
.IX Item "batan2()" |
| 548 |
.Vb 3 |
| 549 |
\& my $y = Math::BigFloat\->new(2); |
| 550 |
\& my $x = Math::BigFloat\->new(3); |
| 551 |
\& print $y\->batan2($x), "\en"; |
| 552 |
.Ve |
| 553 |
.Sp |
| 554 |
Calculate the arcus tanges of \f(CW$y\fR divided by \f(CW$x\fR, modifying \f(CW$y\fR in place. |
| 555 |
See also "\fBbatan()\fR". |
| 556 |
.Sp |
| 557 |
This method was added in v1.87 of Math::BigInt (June 2007). |
| 558 |
.IP \fBas_float()\fR 4 |
| 559 |
.IX Item "as_float()" |
| 560 |
This method is called when Math::BigFloat encounters an object it doesn't know |
| 561 |
how to handle. For instance, assume \f(CW$x\fR is a Math::BigFloat, or subclass |
| 562 |
thereof, and \f(CW$y\fR is defined, but not a Math::BigFloat, or subclass thereof. If |
| 563 |
you do |
| 564 |
.Sp |
| 565 |
.Vb 1 |
| 566 |
\& $x \-> badd($y); |
| 567 |
.Ve |
| 568 |
.Sp |
| 569 |
\&\f(CW$y\fR needs to be converted into an object that \f(CW$x\fR can deal with. This is done by |
| 570 |
first checking if \f(CW$y\fR is something that \f(CW$x\fR might be upgraded to. If that is the |
| 571 |
case, no further attempts are made. The next is to see if \f(CW$y\fR supports the |
| 572 |
method \f(CWas_float()\fR. The method \f(CWas_float()\fR is expected to return either an |
| 573 |
object that has the same class as \f(CW$x\fR, a subclass thereof, or a string that |
| 574 |
\&\f(CW\*(C`ref($x)\->new()\*(C'\fR can parse to create an object. |
| 575 |
.Sp |
| 576 |
In Math::BigFloat, \f(CWas_float()\fR has the same effect as \f(CWcopy()\fR. |
| 577 |
.IP \fBto_ieee754()\fR 4 |
| 578 |
.IX Item "to_ieee754()" |
| 579 |
Encodes the invocand as a byte string in the given format as specified in IEEE |
| 580 |
754\-2008. Note that the encoded value is the nearest possible representation of |
| 581 |
the value. This value might not be exactly the same as the value in the |
| 582 |
invocand. |
| 583 |
.Sp |
| 584 |
.Vb 2 |
| 585 |
\& # $x = 3.1415926535897932385 |
| 586 |
\& $x = Math::BigFloat \-> bpi(30); |
| 587 |
\& |
| 588 |
\& $b = $x \-> to_ieee754("binary64"); # encode as 8 bytes |
| 589 |
\& $h = unpack "H*", $b; # "400921fb54442d18" |
| 590 |
\& |
| 591 |
\& # 3.141592653589793115997963... |
| 592 |
\& $y = Math::BigFloat \-> from_ieee754($h, "binary64"); |
| 593 |
.Ve |
| 594 |
.Sp |
| 595 |
All binary formats in IEEE 754\-2008 are accepted. For convenience, som aliases |
| 596 |
are recognized: "half" for "binary16", "single" for "binary32", "double" for |
| 597 |
"binary64", "quadruple" for "binary128", "octuple" for "binary256", and |
| 598 |
"sexdecuple" for "binary512". |
| 599 |
.Sp |
| 600 |
See also <https://en.wikipedia.org/wiki/IEEE_754>. |
| 601 |
.SS "ACCURACY AND PRECISION" |
| 602 |
.IX Subsection "ACCURACY AND PRECISION" |
| 603 |
See also: Rounding. |
| 604 |
.PP |
| 605 |
Math::BigFloat supports both precision (rounding to a certain place before or |
| 606 |
after the dot) and accuracy (rounding to a certain number of digits). For a |
| 607 |
full documentation, examples and tips on these topics please see the large |
| 608 |
section about rounding in Math::BigInt. |
| 609 |
.PP |
| 610 |
Since things like \f(CWsqrt(2)\fR or \f(CW\*(C`1 / 3\*(C'\fR must presented with a limited |
| 611 |
accuracy lest a operation consumes all resources, each operation produces |
| 612 |
no more than the requested number of digits. |
| 613 |
.PP |
| 614 |
If there is no global precision or accuracy set, \fBand\fR the operation in |
| 615 |
question was not called with a requested precision or accuracy, \fBand\fR the |
| 616 |
input \f(CW$x\fR has no accuracy or precision set, then a fallback parameter will |
| 617 |
be used. For historical reasons, it is called \f(CW\*(C`div_scale\*(C'\fR and can be accessed |
| 618 |
via: |
| 619 |
.PP |
| 620 |
.Vb 2 |
| 621 |
\& $d = Math::BigFloat\->div_scale(); # query |
| 622 |
\& Math::BigFloat\->div_scale($n); # set to $n digits |
| 623 |
.Ve |
| 624 |
.PP |
| 625 |
The default value for \f(CW\*(C`div_scale\*(C'\fR is 40. |
| 626 |
.PP |
| 627 |
In case the result of one operation has more digits than specified, |
| 628 |
it is rounded. The rounding mode taken is either the default mode, or the one |
| 629 |
supplied to the operation after the \fIscale\fR: |
| 630 |
.PP |
| 631 |
.Vb 7 |
| 632 |
\& $x = Math::BigFloat\->new(2); |
| 633 |
\& Math::BigFloat\->accuracy(5); # 5 digits max |
| 634 |
\& $y = $x\->copy()\->bdiv(3); # gives 0.66667 |
| 635 |
\& $y = $x\->copy()\->bdiv(3,6); # gives 0.666667 |
| 636 |
\& $y = $x\->copy()\->bdiv(3,6,undef,\*(Aqodd\*(Aq); # gives 0.666667 |
| 637 |
\& Math::BigFloat\->round_mode(\*(Aqzero\*(Aq); |
| 638 |
\& $y = $x\->copy()\->bdiv(3,6); # will also give 0.666667 |
| 639 |
.Ve |
| 640 |
.PP |
| 641 |
Note that \f(CW\*(C`Math::BigFloat\->accuracy()\*(C'\fR and |
| 642 |
\&\f(CW\*(C`Math::BigFloat\->precision()\*(C'\fR set the global variables, and thus \fBany\fR |
| 643 |
newly created number will be subject to the global rounding \fBimmediately\fR. This |
| 644 |
means that in the examples above, the \f(CW3\fR as argument to \f(CWbdiv()\fR will also |
| 645 |
get an accuracy of \fB5\fR. |
| 646 |
.PP |
| 647 |
It is less confusing to either calculate the result fully, and afterwards |
| 648 |
round it explicitly, or use the additional parameters to the math |
| 649 |
functions like so: |
| 650 |
.PP |
| 651 |
.Vb 4 |
| 652 |
\& use Math::BigFloat; |
| 653 |
\& $x = Math::BigFloat\->new(2); |
| 654 |
\& $y = $x\->copy()\->bdiv(3); |
| 655 |
\& print $y\->bround(5),"\en"; # gives 0.66667 |
| 656 |
\& |
| 657 |
\& or |
| 658 |
\& |
| 659 |
\& use Math::BigFloat; |
| 660 |
\& $x = Math::BigFloat\->new(2); |
| 661 |
\& $y = $x\->copy()\->bdiv(3,5); # gives 0.66667 |
| 662 |
\& print "$y\en"; |
| 663 |
.Ve |
| 664 |
.SS Rounding |
| 665 |
.IX Subsection "Rounding" |
| 666 |
.IP "bfround ( +$scale )" 4 |
| 667 |
.IX Item "bfround ( +$scale )" |
| 668 |
Rounds to the \f(CW$scale\fR'th place left from the '.', counting from the dot. |
| 669 |
The first digit is numbered 1. |
| 670 |
.IP "bfround ( \-$scale )" 4 |
| 671 |
.IX Item "bfround ( -$scale )" |
| 672 |
Rounds to the \f(CW$scale\fR'th place right from the '.', counting from the dot. |
| 673 |
.IP "bfround ( 0 )" 4 |
| 674 |
.IX Item "bfround ( 0 )" |
| 675 |
Rounds to an integer. |
| 676 |
.IP "bround ( +$scale )" 4 |
| 677 |
.IX Item "bround ( +$scale )" |
| 678 |
Preserves accuracy to \f(CW$scale\fR digits from the left (aka significant digits) and |
| 679 |
pads the rest with zeros. If the number is between 1 and \-1, the significant |
| 680 |
digits count from the first non-zero after the '.' |
| 681 |
.IP "bround ( \-$scale ) and bround ( 0 )" 4 |
| 682 |
.IX Item "bround ( -$scale ) and bround ( 0 )" |
| 683 |
These are effectively no-ops. |
| 684 |
.PP |
| 685 |
All rounding functions take as a second parameter a rounding mode from one of |
| 686 |
the following: 'even', 'odd', '+inf', '\-inf', 'zero', 'trunc' or 'common'. |
| 687 |
.PP |
| 688 |
The default rounding mode is 'even'. By using |
| 689 |
\&\f(CW\*(C`Math::BigFloat\->round_mode($round_mode);\*(C'\fR you can get and set the default |
| 690 |
mode for subsequent rounding. The usage of \f(CW\*(C`$Math::BigFloat::$round_mode\*(C'\fR is |
| 691 |
no longer supported. |
| 692 |
The second parameter to the round functions then overrides the default |
| 693 |
temporarily. |
| 694 |
.PP |
| 695 |
The \f(CWas_number()\fR function returns a BigInt from a Math::BigFloat. It uses |
| 696 |
\&'trunc' as rounding mode to make it equivalent to: |
| 697 |
.PP |
| 698 |
.Vb 2 |
| 699 |
\& $x = 2.5; |
| 700 |
\& $y = int($x) + 2; |
| 701 |
.Ve |
| 702 |
.PP |
| 703 |
You can override this by passing the desired rounding mode as parameter to |
| 704 |
\&\f(CWas_number()\fR: |
| 705 |
.PP |
| 706 |
.Vb 2 |
| 707 |
\& $x = Math::BigFloat\->new(2.5); |
| 708 |
\& $y = $x\->as_number(\*(Aqodd\*(Aq); # $y = 3 |
| 709 |
.Ve |
| 710 |
.SH "NUMERIC LITERALS" |
| 711 |
.IX Header "NUMERIC LITERALS" |
| 712 |
After \f(CW\*(C`use Math::BigFloat \*(Aq:constant\*(Aq\*(C'\fR all numeric literals in the given scope |
| 713 |
are converted to \f(CW\*(C`Math::BigFloat\*(C'\fR objects. This conversion happens at compile |
| 714 |
time. |
| 715 |
.PP |
| 716 |
For example, |
| 717 |
.PP |
| 718 |
.Vb 1 |
| 719 |
\& perl \-MMath::BigFloat=:constant \-le \*(Aqprint 2e\-150\*(Aq |
| 720 |
.Ve |
| 721 |
.PP |
| 722 |
prints the exact value of \f(CW2e\-150\fR. Note that without conversion of constants |
| 723 |
the expression \f(CW2e\-150\fR is calculated using Perl scalars, which leads to an |
| 724 |
inaccuracte result. |
| 725 |
.PP |
| 726 |
Note that strings are not affected, so that |
| 727 |
.PP |
| 728 |
.Vb 1 |
| 729 |
\& use Math::BigFloat qw/:constant/; |
| 730 |
\& |
| 731 |
\& $y = "1234567890123456789012345678901234567890" |
| 732 |
\& + "123456789123456789"; |
| 733 |
.Ve |
| 734 |
.PP |
| 735 |
does not give you what you expect. You need an explicit Math::BigFloat\->\fBnew()\fR |
| 736 |
around at least one of the operands. You should also quote large constants to |
| 737 |
prevent loss of precision: |
| 738 |
.PP |
| 739 |
.Vb 1 |
| 740 |
\& use Math::BigFloat; |
| 741 |
\& |
| 742 |
\& $x = Math::BigFloat\->new("1234567889123456789123456789123456789"); |
| 743 |
.Ve |
| 744 |
.PP |
| 745 |
Without the quotes Perl converts the large number to a floating point constant |
| 746 |
at compile time, and then converts the result to a Math::BigFloat object at |
| 747 |
runtime, which results in an inaccurate result. |
| 748 |
.SS "Hexadecimal, octal, and binary floating point literals" |
| 749 |
.IX Subsection "Hexadecimal, octal, and binary floating point literals" |
| 750 |
Perl (and this module) accepts hexadecimal, octal, and binary floating point |
| 751 |
literals, but use them with care with Perl versions before v5.32.0, because some |
| 752 |
versions of Perl silently give the wrong result. Below are some examples of |
| 753 |
different ways to write the number decimal 314. |
| 754 |
.PP |
| 755 |
Hexadecimal floating point literals: |
| 756 |
.PP |
| 757 |
.Vb 3 |
| 758 |
\& 0x1.3ap+8 0X1.3AP+8 |
| 759 |
\& 0x1.3ap8 0X1.3AP8 |
| 760 |
\& 0x13a0p\-4 0X13A0P\-4 |
| 761 |
.Ve |
| 762 |
.PP |
| 763 |
Octal floating point literals (with "0" prefix): |
| 764 |
.PP |
| 765 |
.Vb 3 |
| 766 |
\& 01.164p+8 01.164P+8 |
| 767 |
\& 01.164p8 01.164P8 |
| 768 |
\& 011640p\-4 011640P\-4 |
| 769 |
.Ve |
| 770 |
.PP |
| 771 |
Octal floating point literals (with "0o" prefix) (requires v5.34.0): |
| 772 |
.PP |
| 773 |
.Vb 3 |
| 774 |
\& 0o1.164p+8 0O1.164P+8 |
| 775 |
\& 0o1.164p8 0O1.164P8 |
| 776 |
\& 0o11640p\-4 0O11640P\-4 |
| 777 |
.Ve |
| 778 |
.PP |
| 779 |
Binary floating point literals: |
| 780 |
.PP |
| 781 |
.Vb 3 |
| 782 |
\& 0b1.0011101p+8 0B1.0011101P+8 |
| 783 |
\& 0b1.0011101p8 0B1.0011101P8 |
| 784 |
\& 0b10011101000p\-2 0B10011101000P\-2 |
| 785 |
.Ve |
| 786 |
.SS "Math library" |
| 787 |
.IX Subsection "Math library" |
| 788 |
Math with the numbers is done (by default) by a module called |
| 789 |
Math::BigInt::Calc. This is equivalent to saying: |
| 790 |
.PP |
| 791 |
.Vb 1 |
| 792 |
\& use Math::BigFloat lib => "Calc"; |
| 793 |
.Ve |
| 794 |
.PP |
| 795 |
You can change this by using: |
| 796 |
.PP |
| 797 |
.Vb 1 |
| 798 |
\& use Math::BigFloat lib => "GMP"; |
| 799 |
.Ve |
| 800 |
.PP |
| 801 |
\&\fBNote\fR: General purpose packages should not be explicit about the library to |
| 802 |
use; let the script author decide which is best. |
| 803 |
.PP |
| 804 |
Note: The keyword 'lib' will warn when the requested library could not be |
| 805 |
loaded. To suppress the warning use 'try' instead: |
| 806 |
.PP |
| 807 |
.Vb 1 |
| 808 |
\& use Math::BigFloat try => "GMP"; |
| 809 |
.Ve |
| 810 |
.PP |
| 811 |
If your script works with huge numbers and Calc is too slow for them, you can |
| 812 |
also for the loading of one of these libraries and if none of them can be used, |
| 813 |
the code will die: |
| 814 |
.PP |
| 815 |
.Vb 1 |
| 816 |
\& use Math::BigFloat only => "GMP,Pari"; |
| 817 |
.Ve |
| 818 |
.PP |
| 819 |
The following would first try to find Math::BigInt::Foo, then Math::BigInt::Bar, |
| 820 |
and when this also fails, revert to Math::BigInt::Calc: |
| 821 |
.PP |
| 822 |
.Vb 1 |
| 823 |
\& use Math::BigFloat lib => "Foo,Math::BigInt::Bar"; |
| 824 |
.Ve |
| 825 |
.PP |
| 826 |
See the respective low-level library documentation for further details. |
| 827 |
.PP |
| 828 |
See Math::BigInt for more details about using a different low-level library. |
| 829 |
.SH EXPORTS |
| 830 |
.IX Header "EXPORTS" |
| 831 |
\&\f(CW\*(C`Math::BigFloat\*(C'\fR exports nothing by default, but can export the \f(CWbpi()\fR |
| 832 |
method: |
| 833 |
.PP |
| 834 |
.Vb 1 |
| 835 |
\& use Math::BigFloat qw/bpi/; |
| 836 |
\& |
| 837 |
\& print bpi(10), "\en"; |
| 838 |
.Ve |
| 839 |
.IP "stringify, \fBbstr()\fR" 4 |
| 840 |
.IX Item "stringify, bstr()" |
| 841 |
Both stringify and \fBbstr()\fR now drop the leading '+'. The old code would return |
| 842 |
\&'+1.23', the new returns '1.23'. See the documentation in Math::BigInt for |
| 843 |
reasoning and details. |
| 844 |
.IP \fBbrsft()\fR 4 |
| 845 |
.IX Item "brsft()" |
| 846 |
The following will probably not print what you expect: |
| 847 |
.Sp |
| 848 |
.Vb 2 |
| 849 |
\& my $c = Math::BigFloat\->new(\*(Aq3.14159\*(Aq); |
| 850 |
\& print $c\->brsft(3,10),"\en"; # prints 0.00314153.1415 |
| 851 |
.Ve |
| 852 |
.Sp |
| 853 |
It prints both quotient and remainder, since print calls \f(CWbrsft()\fR in list |
| 854 |
context. Also, \f(CW\*(C`$c\->brsft()\*(C'\fR will modify \f(CW$c\fR, so be careful. |
| 855 |
You probably want to use |
| 856 |
.Sp |
| 857 |
.Vb 3 |
| 858 |
\& print scalar $c\->copy()\->brsft(3,10),"\en"; |
| 859 |
\& # or if you really want to modify $c |
| 860 |
\& print scalar $c\->brsft(3,10),"\en"; |
| 861 |
.Ve |
| 862 |
.Sp |
| 863 |
instead. |
| 864 |
.IP "Modifying and =" 4 |
| 865 |
.IX Item "Modifying and =" |
| 866 |
Beware of: |
| 867 |
.Sp |
| 868 |
.Vb 2 |
| 869 |
\& $x = Math::BigFloat\->new(5); |
| 870 |
\& $y = $x; |
| 871 |
.Ve |
| 872 |
.Sp |
| 873 |
It will not do what you think, e.g. making a copy of \f(CW$x\fR. Instead it just makes |
| 874 |
a second reference to the \fBsame\fR object and stores it in \f(CW$y\fR. Thus anything |
| 875 |
that modifies \f(CW$x\fR will modify \f(CW$y\fR (except overloaded math operators), and vice |
| 876 |
versa. See Math::BigInt for details and how to avoid that. |
| 877 |
.IP "\fBprecision()\fR vs. \fBaccuracy()\fR" 4 |
| 878 |
.IX Item "precision() vs. accuracy()" |
| 879 |
A common pitfall is to use "\fBprecision()\fR" when you want to round a result to |
| 880 |
a certain number of digits: |
| 881 |
.Sp |
| 882 |
.Vb 1 |
| 883 |
\& use Math::BigFloat; |
| 884 |
\& |
| 885 |
\& Math::BigFloat\->precision(4); # does not do what you |
| 886 |
\& # think it does |
| 887 |
\& my $x = Math::BigFloat\->new(12345); # rounds $x to "12000"! |
| 888 |
\& print "$x\en"; # print "12000" |
| 889 |
\& my $y = Math::BigFloat\->new(3); # rounds $y to "0"! |
| 890 |
\& print "$y\en"; # print "0" |
| 891 |
\& $z = $x / $y; # 12000 / 0 => NaN! |
| 892 |
\& print "$z\en"; |
| 893 |
\& print $z\->precision(),"\en"; # 4 |
| 894 |
.Ve |
| 895 |
.Sp |
| 896 |
Replacing "\fBprecision()\fR" with "\fBaccuracy()\fR" is probably not what you want, |
| 897 |
either: |
| 898 |
.Sp |
| 899 |
.Vb 1 |
| 900 |
\& use Math::BigFloat; |
| 901 |
\& |
| 902 |
\& Math::BigFloat\->accuracy(4); # enables global rounding: |
| 903 |
\& my $x = Math::BigFloat\->new(123456); # rounded immediately |
| 904 |
\& # to "12350" |
| 905 |
\& print "$x\en"; # print "123500" |
| 906 |
\& my $y = Math::BigFloat\->new(3); # rounded to "3 |
| 907 |
\& print "$y\en"; # print "3" |
| 908 |
\& print $z = $x\->copy()\->bdiv($y),"\en"; # 41170 |
| 909 |
\& print $z\->accuracy(),"\en"; # 4 |
| 910 |
.Ve |
| 911 |
.Sp |
| 912 |
What you want to use instead is: |
| 913 |
.Sp |
| 914 |
.Vb 1 |
| 915 |
\& use Math::BigFloat; |
| 916 |
\& |
| 917 |
\& my $x = Math::BigFloat\->new(123456); # no rounding |
| 918 |
\& print "$x\en"; # print "123456" |
| 919 |
\& my $y = Math::BigFloat\->new(3); # no rounding |
| 920 |
\& print "$y\en"; # print "3" |
| 921 |
\& print $z = $x\->copy()\->bdiv($y,4),"\en"; # 41150 |
| 922 |
\& print $z\->accuracy(),"\en"; # undef |
| 923 |
.Ve |
| 924 |
.Sp |
| 925 |
In addition to computing what you expected, the last example also does \fBnot\fR |
| 926 |
"taint" the result with an accuracy or precision setting, which would |
| 927 |
influence any further operation. |
| 928 |
.SH BUGS |
| 929 |
.IX Header "BUGS" |
| 930 |
Please report any bugs or feature requests to |
| 931 |
\&\f(CW\*(C`bug\-math\-bigint at rt.cpan.org\*(C'\fR, or through the web interface at |
| 932 |
<https://rt.cpan.org/Ticket/Create.html?Queue=Math\-BigInt> (requires login). |
| 933 |
We will be notified, and then you'll automatically be notified of progress on |
| 934 |
your bug as I make changes. |
| 935 |
.SH SUPPORT |
| 936 |
.IX Header "SUPPORT" |
| 937 |
You can find documentation for this module with the perldoc command. |
| 938 |
.PP |
| 939 |
.Vb 1 |
| 940 |
\& perldoc Math::BigFloat |
| 941 |
.Ve |
| 942 |
.PP |
| 943 |
You can also look for information at: |
| 944 |
.IP \(bu 4 |
| 945 |
GitHub |
| 946 |
.Sp |
| 947 |
<https://github.com/pjacklam/p5\-Math\-BigInt> |
| 948 |
.IP \(bu 4 |
| 949 |
RT: CPAN's request tracker |
| 950 |
.Sp |
| 951 |
<https://rt.cpan.org/Dist/Display.html?Name=Math\-BigInt> |
| 952 |
.IP \(bu 4 |
| 953 |
MetaCPAN |
| 954 |
.Sp |
| 955 |
<https://metacpan.org/release/Math\-BigInt> |
| 956 |
.IP \(bu 4 |
| 957 |
CPAN Testers Matrix |
| 958 |
.Sp |
| 959 |
<http://matrix.cpantesters.org/?dist=Math\-BigInt> |
| 960 |
.SH LICENSE |
| 961 |
.IX Header "LICENSE" |
| 962 |
This program is free software; you may redistribute it and/or modify it under |
| 963 |
the same terms as Perl itself. |
| 964 |
.SH "SEE ALSO" |
| 965 |
.IX Header "SEE ALSO" |
| 966 |
Math::BigInt and Math::BigRat as well as the backend libraries |
| 967 |
Math::BigInt::FastCalc, Math::BigInt::GMP, and Math::BigInt::Pari, |
| 968 |
Math::BigInt::GMPz, and Math::BigInt::BitVect. |
| 969 |
.PP |
| 970 |
The pragmas bigint, bigfloat, and bigrat might also be of interest. In |
| 971 |
addition there is the bignum pragma which does upgrading and downgrading. |
| 972 |
.SH AUTHORS |
| 973 |
.IX Header "AUTHORS" |
| 974 |
.IP \(bu 4 |
| 975 |
Mark Biggar, overloaded interface by Ilya Zakharevich, 1996\-2001. |
| 976 |
.IP \(bu 4 |
| 977 |
Completely rewritten by Tels <http://bloodgate.com> in 2001\-2008. |
| 978 |
.IP \(bu 4 |
| 979 |
Florian Ragwitz <[email protected]>, 2010. |
| 980 |
.IP \(bu 4 |
| 981 |
Peter John Acklam <[email protected]>, 2011\-. |