Debian Codegraph @

upstream/debian-unstable/man3/Math::BigFloat.3perl

raw
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\-.