diff options
Diffstat (limited to 'upstream/archlinux/man3/bigfloat.3perl')
| -rw-r--r-- | upstream/archlinux/man3/bigfloat.3perl | 507 |
1 files changed, 507 insertions, 0 deletions
diff --git a/upstream/archlinux/man3/bigfloat.3perl b/upstream/archlinux/man3/bigfloat.3perl new file mode 100644 index 00000000..8c1648df --- /dev/null +++ b/upstream/archlinux/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-02-11 "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\-. |