Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 507 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man3/bigfloat.3perl b/upstream/debian-unstable/man3/bigfloat.3perl
new file mode 100644
index 00000000..19431a3d
--- /dev/null
+++ b/upstream/debian-unstable/man3/bigfloat.3perl
@@ -0,0 +1,507 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (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
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    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 "bigfloat 3perl"
+.TH bigfloat 3perl 2024-01-12 "perl v5.38.2" "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
+bigfloat \- transparent big floating point number support for Perl
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\&    use bigfloat;
+\&
+\&    $x = 2 + 4.5;                       # Math::BigFloat 6.5
+\&    print 2 ** 512 * 0.1;               # Math::BigFloat 134...09.6
+\&    print inf + 42;                     # Math::BigFloat inf
+\&    print NaN * 7;                      # Math::BigFloat NaN
+\&    print hex("0x1234567890123490");    # Perl v5.10.0 or later
+\&
+\&    {
+\&        no bigfloat;
+\&        print 2 ** 256;                 # a normal Perl scalar now
+\&    }
+\&
+\&    # for older Perls, import into current package:
+\&    use bigfloat qw/hex oct/;
+\&    print hex("0x1234567890123490");
+\&    print oct("01234567890123490");
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+All numeric literals in the given scope are converted to Math::BigFloat objects.
+.PP
+All operators (including basic math operations) except the range operator \f(CW\*(C`..\*(C'\fR
+are overloaded.
+.PP
+So, the following:
+.PP
+.Vb 2
+\&    use bigfloat;
+\&    $x = 1234;
+.Ve
+.PP
+creates a Math::BigFloat and stores a reference to in \f(CW$x\fR. This happens
+transparently and behind your back, so to speak.
+.PP
+You can see this with the following:
+.PP
+.Vb 1
+\&    perl \-Mbigfloat \-le \*(Aqprint ref(1234)\*(Aq
+.Ve
+.PP
+Since numbers are actually objects, you can call all the usual methods from
+Math::BigFloat on them. This even works to some extent on expressions:
+.PP
+.Vb 4
+\&    perl \-Mbigfloat \-le \*(Aq$x = 1234; print $x\->bdec()\*(Aq
+\&    perl \-Mbigfloat \-le \*(Aqprint 1234\->copy()\->binc();\*(Aq
+\&    perl \-Mbigfloat \-le \*(Aqprint 1234\->copy()\->binc\->badd(6);\*(Aq
+\&    perl \-Mbigfloat \-le \*(Aqprint +(1234)\->copy()\->binc()\*(Aq
+.Ve
+.PP
+(Note that print doesn't do what you expect if the expression starts with
+\&'(' hence the \f(CW\*(C`+\*(C'\fR)
+.PP
+You can even chain the operations together as usual:
+.PP
+.Vb 2
+\&    perl \-Mbigfloat \-le \*(Aqprint 1234\->copy()\->binc\->badd(6);\*(Aq
+\&    1241
+.Ve
+.PP
+Please note the following does not work as expected (prints nothing), since
+overloading of '..' is not yet possible in Perl (as of v5.8.0):
+.PP
+.Vb 1
+\&    perl \-Mbigfloat \-le \*(Aqfor (1..2) { print ref($_); }\*(Aq
+.Ve
+.SS Options
+.IX Subsection "Options"
+\&\f(CW\*(C`bigfloat\*(C'\fR recognizes some options that can be passed while loading it via via
+\&\f(CW\*(C`use\*(C'\fR. The following options exist:
+.IP "a or accuracy" 4
+.IX Item "a or accuracy"
+This sets the accuracy for all math operations. The argument must be greater
+than or equal to zero. See Math::BigInt's \fBbround()\fR method for details.
+.Sp
+.Vb 1
+\&    perl \-Mbigfloat=a,50 \-le \*(Aqprint sqrt(20)\*(Aq
+.Ve
+.Sp
+Note that setting precision and accuracy at the same time is not possible.
+.IP "p or precision" 4
+.IX Item "p or precision"
+This sets the precision for all math operations. The argument can be any
+integer. Negative values mean a fixed number of digits after the dot, while a
+positive value rounds to this digit left from the dot. 0 means round to integer.
+See Math::BigInt's \fBbfround()\fR method for details.
+.Sp
+.Vb 1
+\&    perl \-Mbigfloat=p,\-50 \-le \*(Aqprint sqrt(20)\*(Aq
+.Ve
+.Sp
+Note that setting precision and accuracy at the same time is not possible.
+.IP "t or trace" 4
+.IX Item "t or trace"
+This enables a trace mode and is primarily for debugging.
+.IP "l, lib, try, or only" 4
+.IX Item "l, lib, try, or only"
+Load a different math lib, see "Math Library".
+.Sp
+.Vb 4
+\&    perl \-Mbigfloat=l,GMP \-e \*(Aqprint 2 ** 512\*(Aq
+\&    perl \-Mbigfloat=lib,GMP \-e \*(Aqprint 2 ** 512\*(Aq
+\&    perl \-Mbigfloat=try,GMP \-e \*(Aqprint 2 ** 512\*(Aq
+\&    perl \-Mbigfloat=only,GMP \-e \*(Aqprint 2 ** 512\*(Aq
+.Ve
+.IP hex 4
+.IX Item "hex"
+Override the built-in \fBhex()\fR method with a version that can handle big numbers.
+This overrides it by exporting it to the current package. Under Perl v5.10.0 and
+higher, this is not so necessary, as \fBhex()\fR is lexically overridden in the
+current scope whenever the \f(CW\*(C`bigfloat\*(C'\fR pragma is active.
+.IP oct 4
+.IX Item "oct"
+Override the built-in \fBoct()\fR method with a version that can handle big numbers.
+This overrides it by exporting it to the current package. Under Perl v5.10.0 and
+higher, this is not so necessary, as \fBoct()\fR is lexically overridden in the
+current scope whenever the \f(CW\*(C`bigfloat\*(C'\fR pragma is active.
+.IP "v or version" 4
+.IX Item "v or version"
+this prints out the name and version of the modules and then exits.
+.Sp
+.Vb 1
+\&    perl \-Mbigfloat=v
+.Ve
+.SS "Math Library"
+.IX Subsection "Math Library"
+Math with the numbers is done (by default) by a backend library module called
+Math::BigInt::Calc. The default is equivalent to saying:
+.PP
+.Vb 1
+\&    use bigfloat lib => \*(AqCalc\*(Aq;
+.Ve
+.PP
+you can change this by using:
+.PP
+.Vb 1
+\&    use bigfloat lib => \*(AqGMP\*(Aq;
+.Ve
+.PP
+The following would first try to find Math::BigInt::Foo, then Math::BigInt::Bar,
+and if this also fails, revert to Math::BigInt::Calc:
+.PP
+.Vb 1
+\&    use bigfloat lib => \*(AqFoo,Math::BigInt::Bar\*(Aq;
+.Ve
+.PP
+Using c<lib> warns if none of the specified libraries can be found and
+Math::BigInt fell back to one of the default libraries. To suppress this
+warning, use c<try> instead:
+.PP
+.Vb 1
+\&    use bigfloat try => \*(AqGMP\*(Aq;
+.Ve
+.PP
+If you want the code to die instead of falling back, use \f(CW\*(C`only\*(C'\fR instead:
+.PP
+.Vb 1
+\&    use bigfloat only => \*(AqGMP\*(Aq;
+.Ve
+.PP
+Please see respective module documentation for further details.
+.SS "Method calls"
+.IX Subsection "Method calls"
+Since all numbers are now objects, you can use all methods that are part of the
+Math::BigFloat API.
+.PP
+But a warning is in order. When using the following to make a copy of a number,
+only a shallow copy will be made.
+.PP
+.Vb 2
+\&    $x = 9; $y = $x;
+\&    $x = $y = 7;
+.Ve
+.PP
+Using the copy or the original with overloaded math is okay, e.g., the following
+work:
+.PP
+.Vb 2
+\&    $x = 9; $y = $x;
+\&    print $x + 1, " ", $y,"\en";     # prints 10 9
+.Ve
+.PP
+but calling any method that modifies the number directly will result in \fBboth\fR
+the original and the copy being destroyed:
+.PP
+.Vb 2
+\&    $x = 9; $y = $x;
+\&    print $x\->badd(1), " ", $y,"\en";        # prints 10 10
+\&
+\&    $x = 9; $y = $x;
+\&    print $x\->binc(1), " ", $y,"\en";        # prints 10 10
+\&
+\&    $x = 9; $y = $x;
+\&    print $x\->bmul(2), " ", $y,"\en";        # prints 18 18
+.Ve
+.PP
+Using methods that do not modify, but test that the contents works:
+.PP
+.Vb 2
+\&    $x = 9; $y = $x;
+\&    $z = 9 if $x\->is_zero();                # works fine
+.Ve
+.PP
+See the documentation about the copy constructor and \f(CW\*(C`=\*(C'\fR in overload, as well
+as the documentation in Math::BigFloat for further details.
+.SS Methods
+.IX Subsection "Methods"
+.IP \fBinf()\fR 4
+.IX Item "inf()"
+A shortcut to return Math::BigFloat\->\fBbinf()\fR. Useful because Perl does not always
+handle bareword \f(CW\*(C`inf\*(C'\fR properly.
+.IP \fBNaN()\fR 4
+.IX Item "NaN()"
+A shortcut to return Math::BigFloat\->\fBbnan()\fR. Useful because Perl does not always
+handle bareword \f(CW\*(C`NaN\*(C'\fR properly.
+.IP e 4
+.IX Item "e"
+.Vb 1
+\&    # perl \-Mbigfloat=e \-wle \*(Aqprint e\*(Aq
+.Ve
+.Sp
+Returns Euler's number \f(CW\*(C`e\*(C'\fR, aka \fBexp\fR\|(1)
+.IP PI 4
+.IX Item "PI"
+.Vb 1
+\&    # perl \-Mbigfloat=PI \-wle \*(Aqprint PI\*(Aq
+.Ve
+.Sp
+Returns PI.
+.IP \fBbexp()\fR 4
+.IX Item "bexp()"
+.Vb 1
+\&    bexp($power, $accuracy);
+.Ve
+.Sp
+Returns Euler's number \f(CW\*(C`e\*(C'\fR raised to the appropriate power, to the wanted
+accuracy.
+.Sp
+Example:
+.Sp
+.Vb 1
+\&    # perl \-Mbigfloat=bexp \-wle \*(Aqprint bexp(1,80)\*(Aq
+.Ve
+.IP \fBbpi()\fR 4
+.IX Item "bpi()"
+.Vb 1
+\&    bpi($accuracy);
+.Ve
+.Sp
+Returns PI to the wanted accuracy.
+.Sp
+Example:
+.Sp
+.Vb 1
+\&    # perl \-Mbigfloat=bpi \-wle \*(Aqprint bpi(80)\*(Aq
+.Ve
+.IP \fBaccuracy()\fR 4
+.IX Item "accuracy()"
+Set or get the accuracy.
+.IP \fBprecision()\fR 4
+.IX Item "precision()"
+Set or get the precision.
+.IP \fBround_mode()\fR 4
+.IX Item "round_mode()"
+Set or get the rounding mode.
+.IP \fBdiv_scale()\fR 4
+.IX Item "div_scale()"
+Set or get the division scale.
+.IP \fBupgrade()\fR 4
+.IX Item "upgrade()"
+Set or get the class that the downgrade class upgrades to, if any. Set the
+upgrade class to \f(CW\*(C`undef\*(C'\fR to disable upgrading.
+.Sp
+Upgrading is disabled by default.
+.IP \fBdowngrade()\fR 4
+.IX Item "downgrade()"
+Set or get the class that the upgrade class downgrades to, if any. Set the
+downgrade class to \f(CW\*(C`undef\*(C'\fR to disable upgrading.
+.Sp
+Downgrading is disabled by default.
+.IP \fBin_effect()\fR 4
+.IX Item "in_effect()"
+.Vb 1
+\&    use bigfloat;
+\&
+\&    print "in effect\en" if bigfloat::in_effect;       # true
+\&    {
+\&        no bigfloat;
+\&        print "in effect\en" if bigfloat::in_effect;   # false
+\&    }
+.Ve
+.Sp
+Returns true or false if \f(CW\*(C`bigfloat\*(C'\fR is in effect in the current scope.
+.Sp
+This method only works on Perl v5.9.4 or later.
+.SH CAVEATS
+.IX Header "CAVEATS"
+.IP "Hexadecimal, octal, and binary floating point literals" 4
+.IX Item "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.
+.IP "Operator vs literal overloading" 4
+.IX Item "Operator vs literal overloading"
+\&\f(CW\*(C`bigrat\*(C'\fR works by overloading handling of integer and floating point literals,
+converting them to Math::BigRat objects.
+.Sp
+This means that arithmetic involving only string values or string literals are
+performed using Perl's built-in operators.
+.Sp
+For example:
+.Sp
+.Vb 4
+\&    use bigrat;
+\&    my $x = "900000000000000009";
+\&    my $y = "900000000000000007";
+\&    print $x \- $y;
+.Ve
+.Sp
+outputs \f(CW0\fR on default 32\-bit builds, since \f(CW\*(C`bigfloat\*(C'\fR never sees the string
+literals. To ensure the expression is all treated as \f(CW\*(C`Math::BigFloat\*(C'\fR objects,
+use a literal number in the expression:
+.Sp
+.Vb 1
+\&    print +(0+$x) \- $y;
+.Ve
+.IP Ranges 4
+.IX Item "Ranges"
+Perl does not allow overloading of ranges, so you can neither safely use ranges
+with \f(CW\*(C`bigfloat\*(C'\fR endpoints, nor is the iterator variable a \f(CW\*(C`Math::BigFloat\*(C'\fR.
+.Sp
+.Vb 7
+\&    use 5.010;
+\&    for my $i (12..13) {
+\&      for my $j (20..21) {
+\&        say $i ** $j;  # produces a floating\-point number,
+\&                       # not an object
+\&      }
+\&    }
+.Ve
+.IP \fBin_effect()\fR 4
+.IX Item "in_effect()"
+This method only works on Perl v5.9.4 or later.
+.IP \fBhex()\fR/\fBoct()\fR 4
+.IX Item "hex()/oct()"
+\&\f(CW\*(C`bigfloat\*(C'\fR overrides these routines with versions that can also handle big
+integer values. Under Perl prior to version v5.9.4, however, this will not
+happen unless you specifically ask for it with the two import tags "hex" and
+"oct" \- and then it will be global and cannot be disabled inside a scope with
+\&\f(CW\*(C`no bigfloat\*(C'\fR:
+.Sp
+.Vb 1
+\&    use bigfloat qw/hex oct/;
+\&
+\&    print hex("0x1234567890123456");
+\&    {
+\&        no bigfloat;
+\&        print hex("0x1234567890123456");
+\&    }
+.Ve
+.Sp
+The second call to \fBhex()\fR will warn about a non-portable constant.
+.Sp
+Compare this to:
+.Sp
+.Vb 1
+\&    use bigfloat;
+\&
+\&    # will warn only under Perl older than v5.9.4
+\&    print hex("0x1234567890123456");
+.Ve
+.SH EXAMPLES
+.IX Header "EXAMPLES"
+Some cool command line examples to impress the Python crowd ;)
+.PP
+.Vb 10
+\&    perl \-Mbigfloat \-le \*(Aqprint sqrt(33)\*(Aq
+\&    perl \-Mbigfloat \-le \*(Aqprint 2**255\*(Aq
+\&    perl \-Mbigfloat \-le \*(Aqprint 4.5+2**255\*(Aq
+\&    perl \-Mbigfloat \-le \*(Aqprint 3/7 + 5/7 + 8/3\*(Aq
+\&    perl \-Mbigfloat \-le \*(Aqprint 123\->is_odd()\*(Aq
+\&    perl \-Mbigfloat \-le \*(Aqprint log(2)\*(Aq
+\&    perl \-Mbigfloat \-le \*(Aqprint exp(1)\*(Aq
+\&    perl \-Mbigfloat \-le \*(Aqprint 2 ** 0.5\*(Aq
+\&    perl \-Mbigfloat=a,65 \-le \*(Aqprint 2 ** 0.2\*(Aq
+\&    perl \-Mbigfloat=l,GMP \-le \*(Aqprint 7 ** 7777\*(Aq
+.Ve
+.SH BUGS
+.IX Header "BUGS"
+Please report any bugs or feature requests to
+\&\f(CW\*(C`bug\-bignum at rt.cpan.org\*(C'\fR, or through the web interface at
+<https://rt.cpan.org/Ticket/Create.html?Queue=bignum> (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 bigfloat
+.Ve
+.PP
+You can also look for information at:
+.IP \(bu 4
+GitHub
+.Sp
+<https://github.com/pjacklam/p5\-bignum>
+.IP \(bu 4
+RT: CPAN's request tracker
+.Sp
+<https://rt.cpan.org/Dist/Display.html?Name=bignum>
+.IP \(bu 4
+MetaCPAN
+.Sp
+<https://metacpan.org/release/bignum>
+.IP \(bu 4
+CPAN Testers Matrix
+.Sp
+<http://matrix.cpantesters.org/?dist=bignum>
+.IP \(bu 4
+CPAN Ratings
+.Sp
+<https://cpanratings.perl.org/dist/bignum>
+.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"
+bigint and bigrat.
+.PP
+Math::BigInt, Math::BigFloat, Math::BigRat and Math::Big as well as
+Math::BigInt::FastCalc, Math::BigInt::Pari and Math::BigInt::GMP.
+.SH AUTHORS
+.IX Header "AUTHORS"
+.IP \(bu 4
+(C) by Tels <http://bloodgate.com/> in early 2002 \- 2007.
+.IP \(bu 4
+Maintained by Peter John Acklam <pjacklam@gmail.com>, 2014\-.