Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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