diff options
Diffstat (limited to 'upstream/debian-bookworm/man3/Math::BigFloat.3perl')
| -rw-r--r-- | upstream/debian-bookworm/man3/Math::BigFloat.3perl | 1030 |
1 files changed, 1030 insertions, 0 deletions
diff --git a/upstream/debian-bookworm/man3/Math::BigFloat.3perl b/upstream/debian-bookworm/man3/Math::BigFloat.3perl new file mode 100644 index 00000000..644ffc89 --- /dev/null +++ b/upstream/debian-bookworm/man3/Math::BigFloat.3perl @@ -0,0 +1,1030 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "Math::BigFloat 3perl" +.TH Math::BigFloat 3perl "2023-11-25" "perl v5.36.0" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +Math::BigFloat \- arbitrary size floating point math package +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 1 +\& use Math::BigFloat; +\& +\& # Configuration methods (may be used as class methods and instance methods) +\& +\& Math::BigFloat\->accuracy(); # get class accuracy +\& Math::BigFloat\->accuracy($n); # set class accuracy +\& Math::BigFloat\->precision(); # get class precision +\& Math::BigFloat\->precision($n); # set class precision +\& Math::BigFloat\->round_mode(); # get class rounding mode +\& Math::BigFloat\->round_mode($m); # set global round mode, must be one of +\& # \*(Aqeven\*(Aq, \*(Aqodd\*(Aq, \*(Aq+inf\*(Aq, \*(Aq\-inf\*(Aq, \*(Aqzero\*(Aq, +\& # \*(Aqtrunc\*(Aq, or \*(Aqcommon\*(Aq +\& Math::BigFloat\->config("lib"); # name of backend math library +\& +\& # Constructor methods (when the class methods below are used as instance +\& # methods, the value is assigned the invocand) +\& +\& $x = Math::BigFloat\->new($str); # defaults to 0 +\& $x = Math::BigFloat\->new(\*(Aq0x123\*(Aq); # from hexadecimal +\& $x = Math::BigFloat\->new(\*(Aq0o377\*(Aq); # from octal +\& $x = Math::BigFloat\->new(\*(Aq0b101\*(Aq); # from binary +\& $x = Math::BigFloat\->from_hex(\*(Aq0xc.afep+3\*(Aq); # from hex +\& $x = Math::BigFloat\->from_hex(\*(Aqcafe\*(Aq); # ditto +\& $x = Math::BigFloat\->from_oct(\*(Aq1.3267p\-4\*(Aq); # from octal +\& $x = Math::BigFloat\->from_oct(\*(Aq01.3267p\-4\*(Aq); # ditto +\& $x = Math::BigFloat\->from_oct(\*(Aq0o1.3267p\-4\*(Aq); # ditto +\& $x = Math::BigFloat\->from_oct(\*(Aq0377\*(Aq); # ditto +\& $x = Math::BigFloat\->from_bin(\*(Aq0b1.1001p\-4\*(Aq); # from binary +\& $x = Math::BigFloat\->from_bin(\*(Aq0101\*(Aq); # ditto +\& $x = Math::BigFloat\->from_ieee754($b, "binary64"); # from IEEE\-754 bytes +\& $x = Math::BigFloat\->bzero(); # create a +0 +\& $x = Math::BigFloat\->bone(); # create a +1 +\& $x = Math::BigFloat\->bone(\*(Aq\-\*(Aq); # create a \-1 +\& $x = Math::BigFloat\->binf(); # create a +inf +\& $x = Math::BigFloat\->binf(\*(Aq\-\*(Aq); # create a \-inf +\& $x = Math::BigFloat\->bnan(); # create a Not\-A\-Number +\& $x = Math::BigFloat\->bpi(); # returns pi +\& +\& $y = $x\->copy(); # make a copy (unlike $y = $x) +\& $y = $x\->as_int(); # return as BigInt +\& +\& # Boolean methods (these don\*(Aqt modify the invocand) +\& +\& $x\->is_zero(); # if $x is 0 +\& $x\->is_one(); # if $x is +1 +\& $x\->is_one("+"); # ditto +\& $x\->is_one("\-"); # if $x is \-1 +\& $x\->is_inf(); # if $x is +inf or \-inf +\& $x\->is_inf("+"); # if $x is +inf +\& $x\->is_inf("\-"); # if $x is \-inf +\& $x\->is_nan(); # if $x is NaN +\& +\& $x\->is_positive(); # if $x > 0 +\& $x\->is_pos(); # ditto +\& $x\->is_negative(); # if $x < 0 +\& $x\->is_neg(); # ditto +\& +\& $x\->is_odd(); # if $x is odd +\& $x\->is_even(); # if $x is even +\& $x\->is_int(); # if $x is an integer +\& +\& # Comparison methods +\& +\& $x\->bcmp($y); # compare numbers (undef, < 0, == 0, > 0) +\& $x\->bacmp($y); # compare absolutely (undef, < 0, == 0, > 0) +\& $x\->beq($y); # true if and only if $x == $y +\& $x\->bne($y); # true if and only if $x != $y +\& $x\->blt($y); # true if and only if $x < $y +\& $x\->ble($y); # true if and only if $x <= $y +\& $x\->bgt($y); # true if and only if $x > $y +\& $x\->bge($y); # true if and only if $x >= $y +\& +\& # Arithmetic methods +\& +\& $x\->bneg(); # negation +\& $x\->babs(); # absolute value +\& $x\->bsgn(); # sign function (\-1, 0, 1, or NaN) +\& $x\->bnorm(); # normalize (no\-op) +\& $x\->binc(); # increment $x by 1 +\& $x\->bdec(); # decrement $x by 1 +\& $x\->badd($y); # addition (add $y to $x) +\& $x\->bsub($y); # subtraction (subtract $y from $x) +\& $x\->bmul($y); # multiplication (multiply $x by $y) +\& $x\->bmuladd($y,$z); # $x = $x * $y + $z +\& $x\->bdiv($y); # division (floored), set $x to quotient +\& # return (quo,rem) or quo if scalar +\& $x\->btdiv($y); # division (truncated), set $x to quotient +\& # return (quo,rem) or quo if scalar +\& $x\->bmod($y); # modulus (x % y) +\& $x\->btmod($y); # modulus (truncated) +\& $x\->bmodinv($mod); # modular multiplicative inverse +\& $x\->bmodpow($y,$mod); # modular exponentiation (($x ** $y) % $mod) +\& $x\->bpow($y); # power of arguments (x ** y) +\& $x\->blog(); # logarithm of $x to base e (Euler\*(Aqs number) +\& $x\->blog($base); # logarithm of $x to base $base (e.g., base 2) +\& $x\->bexp(); # calculate e ** $x where e is Euler\*(Aqs number +\& $x\->bnok($y); # x over y (binomial coefficient n over k) +\& $x\->bsin(); # sine +\& $x\->bcos(); # cosine +\& $x\->batan(); # inverse tangent +\& $x\->batan2($y); # two\-argument inverse tangent +\& $x\->bsqrt(); # calculate square root +\& $x\->broot($y); # $y\*(Aqth root of $x (e.g. $y == 3 => cubic root) +\& $x\->bfac(); # factorial of $x (1*2*3*4*..$x) +\& +\& $x\->blsft($n); # left shift $n places in base 2 +\& $x\->blsft($n,$b); # left shift $n places in base $b +\& # returns (quo,rem) or quo (scalar context) +\& $x\->brsft($n); # right shift $n places in base 2 +\& $x\->brsft($n,$b); # right shift $n places in base $b +\& # returns (quo,rem) or quo (scalar context) +\& +\& # Bitwise methods +\& +\& $x\->band($y); # bitwise and +\& $x\->bior($y); # bitwise inclusive or +\& $x\->bxor($y); # bitwise exclusive or +\& $x\->bnot(); # bitwise not (two\*(Aqs complement) +\& +\& # Rounding methods +\& $x\->round($A,$P,$mode); # round to accuracy or precision using +\& # rounding mode $mode +\& $x\->bround($n); # accuracy: preserve $n digits +\& $x\->bfround($n); # $n > 0: round to $nth digit left of dec. point +\& # $n < 0: round to $nth digit right of dec. point +\& $x\->bfloor(); # round towards minus infinity +\& $x\->bceil(); # round towards plus infinity +\& $x\->bint(); # round towards zero +\& +\& # Other mathematical methods +\& +\& $x\->bgcd($y); # greatest common divisor +\& $x\->blcm($y); # least common multiple +\& +\& # Object property methods (do not modify the invocand) +\& +\& $x\->sign(); # the sign, either +, \- or NaN +\& $x\->digit($n); # the nth digit, counting from the right +\& $x\->digit(\-$n); # the nth digit, counting from the left +\& $x\->length(); # return number of digits in number +\& ($xl,$f) = $x\->length(); # length of number and length of fraction +\& # part, latter is always 0 digits long +\& # for Math::BigInt objects +\& $x\->mantissa(); # return (signed) mantissa as BigInt +\& $x\->exponent(); # return exponent as BigInt +\& $x\->parts(); # return (mantissa,exponent) as BigInt +\& $x\->sparts(); # mantissa and exponent (as integers) +\& $x\->nparts(); # mantissa and exponent (normalised) +\& $x\->eparts(); # mantissa and exponent (engineering notation) +\& $x\->dparts(); # integer and fraction part +\& $x\->fparts(); # numerator and denominator +\& $x\->numerator(); # numerator +\& $x\->denominator(); # denominator +\& +\& # Conversion methods (do not modify the invocand) +\& +\& $x\->bstr(); # decimal notation, possibly zero padded +\& $x\->bsstr(); # string in scientific notation with integers +\& $x\->bnstr(); # string in normalized notation +\& $x\->bestr(); # string in engineering notation +\& $x\->bdstr(); # string in decimal notation +\& $x\->as_hex(); # as signed hexadecimal string with prefixed 0x +\& $x\->as_bin(); # as signed binary string with prefixed 0b +\& $x\->as_oct(); # as signed octal string with prefixed 0 +\& $x\->to_ieee754($format); # to bytes encoded according to IEEE 754\-2008 +\& +\& # Other conversion methods +\& +\& $x\->numify(); # return as scalar (might overflow or underflow) +.Ve +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Math::BigFloat provides support for arbitrary precision floating point. +Overloading is also provided for Perl operators. +.PP +All operators (including basic math operations) are overloaded if you +declare your big floating point numbers as +.PP +.Vb 1 +\& $x = Math::BigFloat \-> new(\*(Aq12_3.456_789_123_456_789E\-2\*(Aq); +.Ve +.PP +Operations with overloaded operators preserve the arguments, which is +exactly what you expect. +.SS "Input" +.IX Subsection "Input" +Input values to these routines may be any scalar number or string that looks +like a number. Anything that is accepted by Perl as a literal numeric constant +should be accepted by this module. +.IP "\(bu" 4 +Leading and trailing whitespace is ignored. +.IP "\(bu" 4 +Leading zeros are ignored, except for floating point numbers with a binary +exponent, in which case the number is interpreted as an octal floating point +number. For example, \*(L"01.4p+0\*(R" gives 1.5, \*(L"00.4p+0\*(R" gives 0.5, but \*(L"0.4p+0\*(R" +gives a NaN. And while \*(L"0377\*(R" gives 255, \*(L"0377p0\*(R" gives 255. +.IP "\(bu" 4 +If the string has a \*(L"0x\*(R" or \*(L"0X\*(R" prefix, it is interpreted as a hexadecimal +number. +.IP "\(bu" 4 +If the string has a \*(L"0o\*(R" or \*(L"0O\*(R" prefix, it is interpreted as an octal number. A +floating point literal with a \*(L"0\*(R" prefix is also interpreted as an octal number. +.IP "\(bu" 4 +If the string has a \*(L"0b\*(R" or \*(L"0B\*(R" prefix, it is interpreted as a binary number. +.IP "\(bu" 4 +Underline characters are allowed in the same way as they are allowed in literal +numerical constants. +.IP "\(bu" 4 +If the string can not be interpreted, NaN is returned. +.IP "\(bu" 4 +For hexadecimal, octal, and binary floating point numbers, the exponent must be +separated from the significand (mantissa) by the letter \*(L"p\*(R" or \*(L"P\*(R", not \*(L"e\*(R" or +\&\*(L"E\*(R" as with decimal numbers. +.PP +Some examples of valid string input +.PP +.Vb 1 +\& Input string Resulting value +\& +\& 123 123 +\& 1.23e2 123 +\& 12300e\-2 123 +\& +\& 67_538_754 67538754 +\& \-4_5_6.7_8_9e+0_1_0 \-4567890000000 +\& +\& 0x13a 314 +\& 0x13ap0 314 +\& 0x1.3ap+8 314 +\& 0x0.00013ap+24 314 +\& 0x13a000p\-12 314 +\& +\& 0o472 314 +\& 0o1.164p+8 314 +\& 0o0.0001164p+20 314 +\& 0o1164000p\-10 314 +\& +\& 0472 472 Note! +\& 01.164p+8 314 +\& 00.0001164p+20 314 +\& 01164000p\-10 314 +\& +\& 0b100111010 314 +\& 0b1.0011101p+8 314 +\& 0b0.00010011101p+12 314 +\& 0b100111010000p\-3 314 +\& +\& 0x1.921fb5p+1 3.14159262180328369140625e+0 +\& 0o1.2677025p1 2.71828174591064453125 +\& 01.2677025p1 2.71828174591064453125 +\& 0b1.1001p\-4 9.765625e\-2 +.Ve +.SS "Output" +.IX Subsection "Output" +Output values are usually Math::BigFloat objects. +.PP +Boolean operators \f(CW\*(C`is_zero()\*(C'\fR, \f(CW\*(C`is_one()\*(C'\fR, \f(CW\*(C`is_inf()\*(C'\fR, etc. return true or +false. +.PP +Comparison operators \f(CW\*(C`bcmp()\*(C'\fR and \f(CW\*(C`bacmp()\*(C'\fR) return \-1, 0, 1, or +undef. +.SH "METHODS" +.IX Header "METHODS" +Math::BigFloat supports all methods that Math::BigInt supports, except it +calculates non-integer results when possible. Please see Math::BigInt for a +full description of each method. Below are just the most important differences: +.SS "Configuration methods" +.IX Subsection "Configuration methods" +.IP "\fBaccuracy()\fR" 4 +.IX Item "accuracy()" +.Vb 3 +\& $x\->accuracy(5); # local for $x +\& CLASS\->accuracy(5); # global for all members of CLASS +\& # Note: This also applies to new()! +\& +\& $A = $x\->accuracy(); # read out accuracy that affects $x +\& $A = CLASS\->accuracy(); # read out global accuracy +.Ve +.Sp +Set or get the global or local accuracy, aka how many significant digits the +results have. If you set a global accuracy, then this also applies to \fBnew()\fR! +.Sp +Warning! The accuracy \fIsticks\fR, e.g. once you created a number under the +influence of \f(CW\*(C`CLASS\->accuracy($A)\*(C'\fR, all results from math operations with +that number will also be rounded. +.Sp +In most cases, you should probably round the results explicitly using one of +\&\*(L"\fBround()\fR\*(R" in Math::BigInt, \*(L"\fBbround()\fR\*(R" in Math::BigInt or \*(L"\fBbfround()\fR\*(R" in Math::BigInt +or by passing the desired accuracy to the math operation as additional +parameter: +.Sp +.Vb 4 +\& my $x = Math::BigInt\->new(30000); +\& my $y = Math::BigInt\->new(7); +\& print scalar $x\->copy()\->bdiv($y, 2); # print 4300 +\& print scalar $x\->copy()\->bdiv($y)\->bround(2); # print 4300 +.Ve +.IP "\fBprecision()\fR" 4 +.IX Item "precision()" +.Vb 4 +\& $x\->precision(\-2); # local for $x, round at the second +\& # digit right of the dot +\& $x\->precision(2); # ditto, round at the second digit +\& # left of the dot +\& +\& CLASS\->precision(5); # Global for all members of CLASS +\& # This also applies to new()! +\& CLASS\->precision(\-5); # ditto +\& +\& $P = CLASS\->precision(); # read out global precision +\& $P = $x\->precision(); # read out precision that affects $x +.Ve +.Sp +Note: You probably want to use \*(L"\fBaccuracy()\fR\*(R" instead. With \*(L"\fBaccuracy()\fR\*(R" you +set the number of digits each result should have, with \*(L"\fBprecision()\fR\*(R" you +set the place where to round! +.SS "Constructor methods" +.IX Subsection "Constructor methods" +.IP "\fBfrom_hex()\fR" 4 +.IX Item "from_hex()" +.Vb 2 +\& $x \-> from_hex("0x1.921fb54442d18p+1"); +\& $x = Math::BigFloat \-> from_hex("0x1.921fb54442d18p+1"); +.Ve +.Sp +Interpret input as a hexadecimal string.A prefix (\*(L"0x\*(R", \*(L"x\*(R", ignoring case) is +optional. A single underscore character (\*(L"_\*(R") may be placed between any two +digits. If the input is invalid, a NaN is returned. The exponent is in base 2 +using decimal digits. +.Sp +If called as an instance method, the value is assigned to the invocand. +.IP "\fBfrom_oct()\fR" 4 +.IX Item "from_oct()" +.Vb 2 +\& $x \-> from_oct("1.3267p\-4"); +\& $x = Math::BigFloat \-> from_oct("1.3267p\-4"); +.Ve +.Sp +Interpret input as an octal string. A single underscore character (\*(L"_\*(R") may be +placed between any two digits. If the input is invalid, a NaN is returned. The +exponent is in base 2 using decimal digits. +.Sp +If called as an instance method, the value is assigned to the invocand. +.IP "\fBfrom_bin()\fR" 4 +.IX Item "from_bin()" +.Vb 2 +\& $x \-> from_bin("0b1.1001p\-4"); +\& $x = Math::BigFloat \-> from_bin("0b1.1001p\-4"); +.Ve +.Sp +Interpret input as a hexadecimal string. A prefix (\*(L"0b\*(R" or \*(L"b\*(R", ignoring case) +is optional. A single underscore character (\*(L"_\*(R") may be placed between any two +digits. If the input is invalid, a NaN is returned. The exponent is in base 2 +using decimal digits. +.Sp +If called as an instance method, the value is assigned to the invocand. +.IP "\fBfrom_ieee754()\fR" 4 +.IX Item "from_ieee754()" +Interpret the input as a value encoded as described in \s-1IEEE754\-2008.\s0 The input +can be given as a byte string, hex string or binary string. The input is +assumed to be in big-endian byte-order. +.Sp +.Vb 4 +\& # both $dbl and $mbf are 3.141592... +\& $bytes = "\ex40\ex09\ex21\exfb\ex54\ex44\ex2d\ex18"; +\& $dbl = unpack "d>", $bytes; +\& $mbf = Math::BigFloat \-> from_ieee754($bytes, "binary64"); +.Ve +.IP "\fBbpi()\fR" 4 +.IX Item "bpi()" +.Vb 1 +\& print Math::BigFloat\->bpi(100), "\en"; +.Ve +.Sp +Calculate \s-1PI\s0 to N digits (including the 3 before the dot). The result is +rounded according to the current rounding mode, which defaults to \*(L"even\*(R". +.Sp +This method was added in v1.87 of Math::BigInt (June 2007). +.SS "Arithmetic methods" +.IX Subsection "Arithmetic methods" +.IP "\fBbmuladd()\fR" 4 +.IX Item "bmuladd()" +.Vb 1 +\& $x\->bmuladd($y,$z); +.Ve +.Sp +Multiply \f(CW$x\fR by \f(CW$y\fR, and then add \f(CW$z\fR to the result. +.Sp +This method was added in v1.87 of Math::BigInt (June 2007). +.IP "\fBbdiv()\fR" 4 +.IX Item "bdiv()" +.Vb 2 +\& $q = $x\->bdiv($y); +\& ($q, $r) = $x\->bdiv($y); +.Ve +.Sp +In scalar context, divides \f(CW$x\fR by \f(CW$y\fR and returns the result to the given or +default accuracy/precision. In list context, does floored division +(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 + +\&\f(CW$r\fR. The remainer (modulo) is equal to what is returned by \f(CW\*(C`$x\->bmod($y)\*(C'\fR. +.IP "\fBbmod()\fR" 4 +.IX Item "bmod()" +.Vb 1 +\& $x\->bmod($y); +.Ve +.Sp +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 +result is identical to the remainder after floored division (F\-division). If, +in addition, both \f(CW$x\fR and \f(CW$y\fR are integers, the result is identical to the result +from Perl's % operator. +.IP "\fBbexp()\fR" 4 +.IX Item "bexp()" +.Vb 1 +\& $x\->bexp($accuracy); # calculate e ** X +.Ve +.Sp +Calculates the expression \f(CW\*(C`e ** $x\*(C'\fR where \f(CW\*(C`e\*(C'\fR is Euler's number. +.Sp +This method was added in v1.82 of Math::BigInt (April 2007). +.IP "\fBbnok()\fR" 4 +.IX Item "bnok()" +.Vb 1 +\& $x\->bnok($y); # x over y (binomial coefficient n over k) +.Ve +.Sp +Calculates the binomial coefficient n over k, also called the \*(L"choose\*(R" +function. The result is equivalent to: +.Sp +.Vb 3 +\& ( n ) n! +\& | \- | = \-\-\-\-\-\-\- +\& ( k ) k!(n\-k)! +.Ve +.Sp +This method was added in v1.84 of Math::BigInt (April 2007). +.IP "\fBbsin()\fR" 4 +.IX Item "bsin()" +.Vb 2 +\& my $x = Math::BigFloat\->new(1); +\& print $x\->bsin(100), "\en"; +.Ve +.Sp +Calculate the sinus of \f(CW$x\fR, modifying \f(CW$x\fR in place. +.Sp +This method was added in v1.87 of Math::BigInt (June 2007). +.IP "\fBbcos()\fR" 4 +.IX Item "bcos()" +.Vb 2 +\& my $x = Math::BigFloat\->new(1); +\& print $x\->bcos(100), "\en"; +.Ve +.Sp +Calculate the cosinus of \f(CW$x\fR, modifying \f(CW$x\fR in place. +.Sp +This method was added in v1.87 of Math::BigInt (June 2007). +.IP "\fBbatan()\fR" 4 +.IX Item "batan()" +.Vb 2 +\& my $x = Math::BigFloat\->new(1); +\& print $x\->batan(100), "\en"; +.Ve +.Sp +Calculate the arcus tanges of \f(CW$x\fR, modifying \f(CW$x\fR in place. See also \*(L"\fBbatan2()\fR\*(R". +.Sp +This method was added in v1.87 of Math::BigInt (June 2007). +.IP "\fBbatan2()\fR" 4 +.IX Item "batan2()" +.Vb 3 +\& my $y = Math::BigFloat\->new(2); +\& my $x = Math::BigFloat\->new(3); +\& print $y\->batan2($x), "\en"; +.Ve +.Sp +Calculate the arcus tanges of \f(CW$y\fR divided by \f(CW$x\fR, modifying \f(CW$y\fR in place. +See also \*(L"\fBbatan()\fR\*(R". +.Sp +This method was added in v1.87 of Math::BigInt (June 2007). +.IP "\fBas_float()\fR" 4 +.IX Item "as_float()" +This method is called when Math::BigFloat encounters an object it doesn't know +how to handle. For instance, assume \f(CW$x\fR is a Math::BigFloat, or subclass +thereof, and \f(CW$y\fR is defined, but not a Math::BigFloat, or subclass thereof. If +you do +.Sp +.Vb 1 +\& $x \-> badd($y); +.Ve +.Sp +\&\f(CW$y\fR needs to be converted into an object that \f(CW$x\fR can deal with. This is done by +first checking if \f(CW$y\fR is something that \f(CW$x\fR might be upgraded to. If that is the +case, no further attempts are made. The next is to see if \f(CW$y\fR supports the +method \f(CW\*(C`as_float()\*(C'\fR. The method \f(CW\*(C`as_float()\*(C'\fR is expected to return either an +object that has the same class as \f(CW$x\fR, a subclass thereof, or a string that +\&\f(CW\*(C`ref($x)\->new()\*(C'\fR can parse to create an object. +.Sp +In Math::BigFloat, \f(CW\*(C`as_float()\*(C'\fR has the same effect as \f(CW\*(C`copy()\*(C'\fR. +.IP "\fBto_ieee754()\fR" 4 +.IX Item "to_ieee754()" +Encodes the invocand as a byte string in the given format as specified in \s-1IEEE +754\-2008.\s0 Note that the encoded value is the nearest possible representation of +the value. This value might not be exactly the same as the value in the +invocand. +.Sp +.Vb 2 +\& # $x = 3.1415926535897932385 +\& $x = Math::BigFloat \-> bpi(30); +\& +\& $b = $x \-> to_ieee754("binary64"); # encode as 8 bytes +\& $h = unpack "H*", $b; # "400921fb54442d18" +\& +\& # 3.141592653589793115997963... +\& $y = Math::BigFloat \-> from_ieee754($h, "binary64"); +.Ve +.Sp +All binary formats in \s-1IEEE 754\-2008\s0 are accepted. For convenience, som aliases +are recognized: \*(L"half\*(R" for \*(L"binary16\*(R", \*(L"single\*(R" for \*(L"binary32\*(R", \*(L"double\*(R" for +\&\*(L"binary64\*(R", \*(L"quadruple\*(R" for \*(L"binary128\*(R", \*(L"octuple\*(R" for \*(L"binary256\*(R", and +\&\*(L"sexdecuple\*(R" for \*(L"binary512\*(R". +.Sp +See also <https://en.wikipedia.org/wiki/IEEE_754>. +.SS "\s-1ACCURACY AND PRECISION\s0" +.IX Subsection "ACCURACY AND PRECISION" +See also: Rounding. +.PP +Math::BigFloat supports both precision (rounding to a certain place before or +after the dot) and accuracy (rounding to a certain number of digits). For a +full documentation, examples and tips on these topics please see the large +section about rounding in Math::BigInt. +.PP +Since things like \f(CWsqrt(2)\fR or \f(CW\*(C`1 / 3\*(C'\fR must presented with a limited +accuracy lest a operation consumes all resources, each operation produces +no more than the requested number of digits. +.PP +If there is no global precision or accuracy set, \fBand\fR the operation in +question was not called with a requested precision or accuracy, \fBand\fR the +input \f(CW$x\fR has no accuracy or precision set, then a fallback parameter will +be used. For historical reasons, it is called \f(CW\*(C`div_scale\*(C'\fR and can be accessed +via: +.PP +.Vb 2 +\& $d = Math::BigFloat\->div_scale(); # query +\& Math::BigFloat\->div_scale($n); # set to $n digits +.Ve +.PP +The default value for \f(CW\*(C`div_scale\*(C'\fR is 40. +.PP +In case the result of one operation has more digits than specified, +it is rounded. The rounding mode taken is either the default mode, or the one +supplied to the operation after the \fIscale\fR: +.PP +.Vb 7 +\& $x = Math::BigFloat\->new(2); +\& Math::BigFloat\->accuracy(5); # 5 digits max +\& $y = $x\->copy()\->bdiv(3); # gives 0.66667 +\& $y = $x\->copy()\->bdiv(3,6); # gives 0.666667 +\& $y = $x\->copy()\->bdiv(3,6,undef,\*(Aqodd\*(Aq); # gives 0.666667 +\& Math::BigFloat\->round_mode(\*(Aqzero\*(Aq); +\& $y = $x\->copy()\->bdiv(3,6); # will also give 0.666667 +.Ve +.PP +Note that \f(CW\*(C`Math::BigFloat\->accuracy()\*(C'\fR and \f(CW\*(C`Math::BigFloat\->precision()\*(C'\fR +set the global variables, and thus \fBany\fR newly created number will be subject +to the global rounding \fBimmediately\fR. This means that in the examples above, the +\&\f(CW3\fR as argument to \f(CW\*(C`bdiv()\*(C'\fR will also get an accuracy of \fB5\fR. +.PP +It is less confusing to either calculate the result fully, and afterwards +round it explicitly, or use the additional parameters to the math +functions like so: +.PP +.Vb 4 +\& use Math::BigFloat; +\& $x = Math::BigFloat\->new(2); +\& $y = $x\->copy()\->bdiv(3); +\& print $y\->bround(5),"\en"; # gives 0.66667 +\& +\& or +\& +\& use Math::BigFloat; +\& $x = Math::BigFloat\->new(2); +\& $y = $x\->copy()\->bdiv(3,5); # gives 0.66667 +\& print "$y\en"; +.Ve +.SS "Rounding" +.IX Subsection "Rounding" +.IP "bfround ( +$scale )" 4 +.IX Item "bfround ( +$scale )" +Rounds to the \f(CW$scale\fR'th place left from the '.', counting from the dot. +The first digit is numbered 1. +.IP "bfround ( \-$scale )" 4 +.IX Item "bfround ( -$scale )" +Rounds to the \f(CW$scale\fR'th place right from the '.', counting from the dot. +.IP "bfround ( 0 )" 4 +.IX Item "bfround ( 0 )" +Rounds to an integer. +.IP "bround ( +$scale )" 4 +.IX Item "bround ( +$scale )" +Preserves accuracy to \f(CW$scale\fR digits from the left (aka significant digits) and +pads the rest with zeros. If the number is between 1 and \-1, the significant +digits count from the first non-zero after the '.' +.IP "bround ( \-$scale ) and bround ( 0 )" 4 +.IX Item "bround ( -$scale ) and bround ( 0 )" +These are effectively no-ops. +.PP +All rounding functions take as a second parameter a rounding mode from one of +the following: 'even', 'odd', '+inf', '\-inf', 'zero', 'trunc' or 'common'. +.PP +The default rounding mode is 'even'. By using +\&\f(CW\*(C`Math::BigFloat\->round_mode($round_mode);\*(C'\fR you can get and set the default +mode for subsequent rounding. The usage of \f(CW\*(C`$Math::BigFloat::$round_mode\*(C'\fR is +no longer supported. +The second parameter to the round functions then overrides the default +temporarily. +.PP +The \f(CW\*(C`as_number()\*(C'\fR function returns a BigInt from a Math::BigFloat. It uses +\&'trunc' as rounding mode to make it equivalent to: +.PP +.Vb 2 +\& $x = 2.5; +\& $y = int($x) + 2; +.Ve +.PP +You can override this by passing the desired rounding mode as parameter to +\&\f(CW\*(C`as_number()\*(C'\fR: +.PP +.Vb 2 +\& $x = Math::BigFloat\->new(2.5); +\& $y = $x\->as_number(\*(Aqodd\*(Aq); # $y = 3 +.Ve +.SH "NUMERIC LITERALS" +.IX Header "NUMERIC LITERALS" +After \f(CW\*(C`use Math::BigFloat \*(Aq:constant\*(Aq\*(C'\fR all numeric literals in the given scope +are converted to \f(CW\*(C`Math::BigFloat\*(C'\fR objects. This conversion happens at compile +time. +.PP +For example, +.PP +.Vb 1 +\& perl \-MMath::BigFloat=:constant \-le \*(Aqprint 2e\-150\*(Aq +.Ve +.PP +prints the exact value of \f(CW\*(C`2e\-150\*(C'\fR. Note that without conversion of constants +the expression \f(CW\*(C`2e\-150\*(C'\fR is calculated using Perl scalars, which leads to an +inaccuracte result. +.PP +Note that strings are not affected, so that +.PP +.Vb 1 +\& use Math::BigFloat qw/:constant/; +\& +\& $y = "1234567890123456789012345678901234567890" +\& + "123456789123456789"; +.Ve +.PP +does not give you what you expect. You need an explicit Math::BigFloat\->\fBnew()\fR +around at least one of the operands. You should also quote large constants to +prevent loss of precision: +.PP +.Vb 1 +\& use Math::BigFloat; +\& +\& $x = Math::BigFloat\->new("1234567889123456789123456789123456789"); +.Ve +.PP +Without the quotes Perl converts the large number to a floating point constant +at compile time, and then converts the result to a Math::BigFloat object at +runtime, which results in an inaccurate result. +.SS "Hexadecimal, octal, and binary floating point literals" +.IX Subsection "Hexadecimal, octal, and binary floating point literals" +Perl (and this module) accepts hexadecimal, octal, and binary floating point +literals, but use them with care with Perl versions before v5.32.0, because some +versions of Perl silently give the wrong result. Below are some examples of +different ways to write the number decimal 314. +.PP +Hexadecimal floating point literals: +.PP +.Vb 3 +\& 0x1.3ap+8 0X1.3AP+8 +\& 0x1.3ap8 0X1.3AP8 +\& 0x13a0p\-4 0X13A0P\-4 +.Ve +.PP +Octal floating point literals (with \*(L"0\*(R" prefix): +.PP +.Vb 3 +\& 01.164p+8 01.164P+8 +\& 01.164p8 01.164P8 +\& 011640p\-4 011640P\-4 +.Ve +.PP +Octal floating point literals (with \*(L"0o\*(R" prefix) (requires v5.34.0): +.PP +.Vb 3 +\& 0o1.164p+8 0O1.164P+8 +\& 0o1.164p8 0O1.164P8 +\& 0o11640p\-4 0O11640P\-4 +.Ve +.PP +Binary floating point literals: +.PP +.Vb 3 +\& 0b1.0011101p+8 0B1.0011101P+8 +\& 0b1.0011101p8 0B1.0011101P8 +\& 0b10011101000p\-2 0B10011101000P\-2 +.Ve +.SS "Math library" +.IX Subsection "Math library" +Math with the numbers is done (by default) by a module called +Math::BigInt::Calc. This is equivalent to saying: +.PP +.Vb 1 +\& use Math::BigFloat lib => "Calc"; +.Ve +.PP +You can change this by using: +.PP +.Vb 1 +\& use Math::BigFloat lib => "GMP"; +.Ve +.PP +\&\fBNote\fR: General purpose packages should not be explicit about the library to +use; let the script author decide which is best. +.PP +Note: The keyword 'lib' will warn when the requested library could not be +loaded. To suppress the warning use 'try' instead: +.PP +.Vb 1 +\& use Math::BigFloat try => "GMP"; +.Ve +.PP +If your script works with huge numbers and Calc is too slow for them, you can +also for the loading of one of these libraries and if none of them can be used, +the code will die: +.PP +.Vb 1 +\& use Math::BigFloat only => "GMP,Pari"; +.Ve +.PP +The following would first try to find Math::BigInt::Foo, then Math::BigInt::Bar, +and when this also fails, revert to Math::BigInt::Calc: +.PP +.Vb 1 +\& use Math::BigFloat lib => "Foo,Math::BigInt::Bar"; +.Ve +.PP +See the respective low-level library documentation for further details. +.PP +See Math::BigInt for more details about using a different low-level library. +.SS "Using Math::BigInt::Lite" +.IX Subsection "Using Math::BigInt::Lite" +For backwards compatibility reasons it is still possible to +request a different storage class for use with Math::BigFloat: +.PP +.Vb 1 +\& use Math::BigFloat with => \*(AqMath::BigInt::Lite\*(Aq; +.Ve +.PP +However, this request is ignored, as the current code now uses the low-level +math library for directly storing the number parts. +.SH "EXPORTS" +.IX Header "EXPORTS" +\&\f(CW\*(C`Math::BigFloat\*(C'\fR exports nothing by default, but can export the \f(CW\*(C`bpi()\*(C'\fR method: +.PP +.Vb 1 +\& use Math::BigFloat qw/bpi/; +\& +\& print bpi(10), "\en"; +.Ve +.SH "CAVEATS" +.IX Header "CAVEATS" +Do not try to be clever to insert some operations in between switching +libraries: +.PP +.Vb 4 +\& require Math::BigFloat; +\& my $matter = Math::BigFloat\->bone() + 4; # load BigInt and Calc +\& Math::BigFloat\->import( lib => \*(AqPari\*(Aq ); # load Pari, too +\& my $anti_matter = Math::BigFloat\->bone()+4; # now use Pari +.Ve +.PP +This will create objects with numbers stored in two different backend libraries, +and \fB\s-1VERY BAD THINGS\s0\fR will happen when you use these together: +.PP +.Vb 1 +\& my $flash_and_bang = $matter + $anti_matter; # Don\*(Aqt do this! +.Ve +.IP "stringify, \fBbstr()\fR" 4 +.IX Item "stringify, bstr()" +Both stringify and \fBbstr()\fR now drop the leading '+'. The old code would return +\&'+1.23', the new returns '1.23'. See the documentation in Math::BigInt for +reasoning and details. +.IP "\fBbrsft()\fR" 4 +.IX Item "brsft()" +The following will probably not print what you expect: +.Sp +.Vb 2 +\& my $c = Math::BigFloat\->new(\*(Aq3.14159\*(Aq); +\& print $c\->brsft(3,10),"\en"; # prints 0.00314153.1415 +.Ve +.Sp +It prints both quotient and remainder, since print calls \f(CW\*(C`brsft()\*(C'\fR in list +context. Also, \f(CW\*(C`$c\->brsft()\*(C'\fR will modify \f(CW$c\fR, so be careful. +You probably want to use +.Sp +.Vb 3 +\& print scalar $c\->copy()\->brsft(3,10),"\en"; +\& # or if you really want to modify $c +\& print scalar $c\->brsft(3,10),"\en"; +.Ve +.Sp +instead. +.IP "Modifying and =" 4 +.IX Item "Modifying and =" +Beware of: +.Sp +.Vb 2 +\& $x = Math::BigFloat\->new(5); +\& $y = $x; +.Ve +.Sp +It will not do what you think, e.g. making a copy of \f(CW$x\fR. Instead it just makes +a second reference to the \fBsame\fR object and stores it in \f(CW$y\fR. Thus anything +that modifies \f(CW$x\fR will modify \f(CW$y\fR (except overloaded math operators), and vice +versa. See Math::BigInt for details and how to avoid that. +.IP "\fBprecision()\fR vs. \fBaccuracy()\fR" 4 +.IX Item "precision() vs. accuracy()" +A common pitfall is to use \*(L"\fBprecision()\fR\*(R" when you want to round a result to +a certain number of digits: +.Sp +.Vb 1 +\& use Math::BigFloat; +\& +\& Math::BigFloat\->precision(4); # does not do what you +\& # think it does +\& my $x = Math::BigFloat\->new(12345); # rounds $x to "12000"! +\& print "$x\en"; # print "12000" +\& my $y = Math::BigFloat\->new(3); # rounds $y to "0"! +\& print "$y\en"; # print "0" +\& $z = $x / $y; # 12000 / 0 => NaN! +\& print "$z\en"; +\& print $z\->precision(),"\en"; # 4 +.Ve +.Sp +Replacing \*(L"\fBprecision()\fR\*(R" with \*(L"\fBaccuracy()\fR\*(R" is probably not what you want, either: +.Sp +.Vb 1 +\& use Math::BigFloat; +\& +\& Math::BigFloat\->accuracy(4); # enables global rounding: +\& my $x = Math::BigFloat\->new(123456); # rounded immediately +\& # to "12350" +\& print "$x\en"; # print "123500" +\& my $y = Math::BigFloat\->new(3); # rounded to "3 +\& print "$y\en"; # print "3" +\& print $z = $x\->copy()\->bdiv($y),"\en"; # 41170 +\& print $z\->accuracy(),"\en"; # 4 +.Ve +.Sp +What you want to use instead is: +.Sp +.Vb 1 +\& use Math::BigFloat; +\& +\& my $x = Math::BigFloat\->new(123456); # no rounding +\& print "$x\en"; # print "123456" +\& my $y = Math::BigFloat\->new(3); # no rounding +\& print "$y\en"; # print "3" +\& print $z = $x\->copy()\->bdiv($y,4),"\en"; # 41150 +\& print $z\->accuracy(),"\en"; # undef +.Ve +.Sp +In addition to computing what you expected, the last example also does \fBnot\fR +\&\*(L"taint\*(R" the result with an accuracy or precision setting, which would +influence any further operation. +.SH "BUGS" +.IX Header "BUGS" +Please report any bugs or feature requests to +\&\f(CW\*(C`bug\-math\-bigint at rt.cpan.org\*(C'\fR, or through the web interface at +<https://rt.cpan.org/Ticket/Create.html?Queue=Math\-BigInt> (requires login). +We will be notified, and then you'll automatically be notified of progress on +your bug as I make changes. +.SH "SUPPORT" +.IX Header "SUPPORT" +You can find documentation for this module with the perldoc command. +.PP +.Vb 1 +\& perldoc Math::BigFloat +.Ve +.PP +You can also look for information at: +.IP "\(bu" 4 +GitHub +.Sp +<https://github.com/pjacklam/p5\-Math\-BigInt> +.IP "\(bu" 4 +\&\s-1RT: CPAN\s0's request tracker +.Sp +<https://rt.cpan.org/Dist/Display.html?Name=Math\-BigInt> +.IP "\(bu" 4 +MetaCPAN +.Sp +<https://metacpan.org/release/Math\-BigInt> +.IP "\(bu" 4 +\&\s-1CPAN\s0 Testers Matrix +.Sp +<http://matrix.cpantesters.org/?dist=Math\-BigInt> +.IP "\(bu" 4 +\&\s-1CPAN\s0 Ratings +.Sp +<https://cpanratings.perl.org/dist/Math\-BigInt> +.IP "\(bu" 4 +The Bignum mailing list +.RS 4 +.IP "\(bu" 4 +Post to mailing list +.Sp +\&\f(CW\*(C`bignum at lists.scsys.co.uk\*(C'\fR +.IP "\(bu" 4 +View mailing list +.Sp +<http://lists.scsys.co.uk/pipermail/bignum/> +.IP "\(bu" 4 +Subscribe/Unsubscribe +.Sp +<http://lists.scsys.co.uk/cgi\-bin/mailman/listinfo/bignum> +.RE +.RS 4 +.RE +.SH "LICENSE" +.IX Header "LICENSE" +This program is free software; you may redistribute it and/or modify it under +the same terms as Perl itself. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +Math::BigInt and Math::BigInt as well as the backends +Math::BigInt::FastCalc, Math::BigInt::GMP, and Math::BigInt::Pari. +.PP +The pragmas bignum, bigint and bigrat. +.SH "AUTHORS" +.IX Header "AUTHORS" +.IP "\(bu" 4 +Mark Biggar, overloaded interface by Ilya Zakharevich, 1996\-2001. +.IP "\(bu" 4 +Completely rewritten by Tels <http://bloodgate.com> in 2001\-2008. +.IP "\(bu" 4 +Florian Ragwitz <flora@cpan.org>, 2010. +.IP "\(bu" 4 +Peter John Acklam <pjacklam@gmail.com>, 2011\-. |