bigfloat(3pm)

1bigfloat(3)           User Contributed Perl Documentation          bigfloat(3)
2
3
4

NAME

6       bigfloat - transparent big floating point number support for Perl
7

SYNOPSIS

9           use bigfloat;
10
11           $x = 2 + 4.5;                       # Math::BigFloat 6.5
12           print 2 ** 512 * 0.1;               # Math::BigFloat 134...09.6
13           print inf + 42;                     # Math::BigFloat inf
14           print NaN * 7;                      # Math::BigFloat NaN
15           print hex("0x1234567890123490");    # Perl v5.10.0 or later
16
17           {
18               no bigfloat;
19               print 2 ** 256;                 # a normal Perl scalar now
20           }
21
22           # for older Perls, import into current package:
23           use bigfloat qw/hex oct/;
24           print hex("0x1234567890123490");
25           print oct("01234567890123490");
26

DESCRIPTION

28       All numeric literals in the given scope are converted to Math::BigFloat
29       objects.
30
31       All operators (including basic math operations) except the range
32       operator ".."  are overloaded.
33
34       So, the following:
35
36           use bigfloat;
37           $x = 1234;
38
39       creates a Math::BigFloat and stores a reference to in $x. This happens
40       transparently and behind your back, so to speak.
41
42       You can see this with the following:
43
44           perl -Mbigfloat -le 'print ref(1234)'
45
46       Since numbers are actually objects, you can call all the usual methods
47       from Math::BigFloat on them. This even works to some extent on
48       expressions:
49
50           perl -Mbigfloat -le '$x = 1234; print $x->bdec()'
51           perl -Mbigfloat -le 'print 1234->copy()->binc();'
52           perl -Mbigfloat -le 'print 1234->copy()->binc->badd(6);'
53           perl -Mbigfloat -le 'print +(1234)->copy()->binc()'
54
55       (Note that print doesn't do what you expect if the expression starts
56       with '(' hence the "+")
57
58       You can even chain the operations together as usual:
59
60           perl -Mbigfloat -le 'print 1234->copy()->binc->badd(6);'
61           1241
62
63       Please note the following does not work as expected (prints nothing),
64       since overloading of '..' is not yet possible in Perl (as of v5.8.0):
65
66           perl -Mbigfloat -le 'for (1..2) { print ref($_); }'
67
68   Options
69       "bigfloat" recognizes some options that can be passed while loading it
70       via via "use". The following options exist:
71
72       a or accuracy
73           This sets the accuracy for all math operations. The argument must
74           be greater than or equal to zero. See Math::BigInt's bround()
75           method for details.
76
77               perl -Mbigfloat=a,50 -le 'print sqrt(20)'
78
79           Note that setting precision and accuracy at the same time is not
80           possible.
81
82       p or precision
83           This sets the precision for all math operations. The argument can
84           be any integer. Negative values mean a fixed number of digits after
85           the dot, while a positive value rounds to this digit left from the
86           dot. 0 means round to integer.  See Math::BigInt's bfround() method
87           for details.
88
89               perl -Mbigfloat=p,-50 -le 'print sqrt(20)'
90
91           Note that setting precision and accuracy at the same time is not
92           possible.
93
94       t or trace
95           This enables a trace mode and is primarily for debugging.
96
97       l, lib, try, or only
98           Load a different math lib, see "Math Library".
99
100               perl -Mbigfloat=l,GMP -e 'print 2 ** 512'
101               perl -Mbigfloat=lib,GMP -e 'print 2 ** 512'
102               perl -Mbigfloat=try,GMP -e 'print 2 ** 512'
103               perl -Mbigfloat=only,GMP -e 'print 2 ** 512'
104
105       hex Override the built-in hex() method with a version that can handle
106           big numbers.  This overrides it by exporting it to the current
107           package. Under Perl v5.10.0 and higher, this is not so necessary,
108           as hex() is lexically overridden in the current scope whenever the
109           "bigfloat" pragma is active.
110
111       oct Override the built-in oct() method with a version that can handle
112           big numbers.  This overrides it by exporting it to the current
113           package. Under Perl v5.10.0 and higher, this is not so necessary,
114           as oct() is lexically overridden in the current scope whenever the
115           "bigfloat" pragma is active.
116
117       v or version
118           this prints out the name and version of the modules and then exits.
119
120               perl -Mbigfloat=v
121
122   Math Library
123       Math with the numbers is done (by default) by a backend library module
124       called Math::BigInt::Calc. The default is equivalent to saying:
125
126           use bigfloat lib => 'Calc';
127
128       you can change this by using:
129
130           use bigfloat lib => 'GMP';
131
132       The following would first try to find Math::BigInt::Foo, then
133       Math::BigInt::Bar, and if this also fails, revert to
134       Math::BigInt::Calc:
135
136           use bigfloat lib => 'Foo,Math::BigInt::Bar';
137
138       Using c<lib> warns if none of the specified libraries can be found and
139       Math::BigInt fell back to one of the default libraries. To suppress
140       this warning, use c<try> instead:
141
142           use bigfloat try => 'GMP';
143
144       If you want the code to die instead of falling back, use "only"
145       instead:
146
147           use bigfloat only => 'GMP';
148
149       Please see respective module documentation for further details.
150
151   Method calls
152       Since all numbers are now objects, you can use all methods that are
153       part of the Math::BigFloat API.
154
155       But a warning is in order. When using the following to make a copy of a
156       number, only a shallow copy will be made.
157
158           $x = 9; $y = $x;
159           $x = $y = 7;
160
161       Using the copy or the original with overloaded math is okay, e.g., the
162       following work:
163
164           $x = 9; $y = $x;
165           print $x + 1, " ", $y,"\n";     # prints 10 9
166
167       but calling any method that modifies the number directly will result in
168       both the original and the copy being destroyed:
169
170           $x = 9; $y = $x;
171           print $x->badd(1), " ", $y,"\n";        # prints 10 10
172
173           $x = 9; $y = $x;
174           print $x->binc(1), " ", $y,"\n";        # prints 10 10
175
176           $x = 9; $y = $x;
177           print $x->bmul(2), " ", $y,"\n";        # prints 18 18
178
179       Using methods that do not modify, but test that the contents works:
180
181           $x = 9; $y = $x;
182           $z = 9 if $x->is_zero();                # works fine
183
184       See the documentation about the copy constructor and "=" in overload,
185       as well as the documentation in Math::BigFloat for further details.
186
187   Methods
188       inf()
189           A shortcut to return Math::BigFloat->binf(). Useful because Perl
190           does not always handle bareword "inf" properly.
191
192       NaN()
193           A shortcut to return Math::BigFloat->bnan(). Useful because Perl
194           does not always handle bareword "NaN" properly.
195
196       e
197               # perl -Mbigfloat=e -wle 'print e'
198
199           Returns Euler's number "e", aka exp(1)
200
201       PI
202               # perl -Mbigfloat=PI -wle 'print PI'
203
204           Returns PI.
205
206       bexp()
207               bexp($power, $accuracy);
208
209           Returns Euler's number "e" raised to the appropriate power, to the
210           wanted accuracy.
211
212           Example:
213
214               # perl -Mbigfloat=bexp -wle 'print bexp(1,80)'
215
216       bpi()
217               bpi($accuracy);
218
219           Returns PI to the wanted accuracy.
220
221           Example:
222
223               # perl -Mbigfloat=bpi -wle 'print bpi(80)'
224
225       accuracy()
226           Set or get the accuracy.
227
228       precision()
229           Set or get the precision.
230
231       round_mode()
232           Set or get the rounding mode.
233
234       div_scale()
235           Set or get the division scale.
236
237       upgrade()
238           Set or get the class that the downgrade class upgrades to, if any.
239           Set the upgrade class to "undef" to disable upgrading.
240
241           Upgrading is disabled by default.
242
243       downgrade()
244           Set or get the class that the upgrade class downgrades to, if any.
245           Set the downgrade class to "undef" to disable upgrading.
246
247           Downgrading is disabled by default.
248
249       in_effect()
250               use bigfloat;
251
252               print "in effect\n" if bigfloat::in_effect;       # true
253               {
254                   no bigfloat;
255                   print "in effect\n" if bigfloat::in_effect;   # false
256               }
257
258           Returns true or false if "bigfloat" is in effect in the current
259           scope.
260
261           This method only works on Perl v5.9.4 or later.
262

CAVEATS

264       Hexadecimal, octal, and binary floating point literals
265           Perl (and this module) accepts hexadecimal, octal, and binary
266           floating point literals, but use them with care with Perl versions
267           before v5.32.0, because some versions of Perl silently give the
268           wrong result.
269
270       Operator vs literal overloading
271           "bigrat" works by overloading handling of integer and floating
272           point literals, converting them to Math::BigRat objects.
273
274           This means that arithmetic involving only string values or string
275           literals are performed using Perl's built-in operators.
276
277           For example:
278
279               use bigrat;
280               my $x = "900000000000000009";
281               my $y = "900000000000000007";
282               print $x - $y;
283
284           outputs 0 on default 32-bit builds, since "bigfloat" never sees the
285           string literals. To ensure the expression is all treated as
286           "Math::BigFloat" objects, use a literal number in the expression:
287
288               print +(0+$x) - $y;
289
290       Ranges
291           Perl does not allow overloading of ranges, so you can neither
292           safely use ranges with "bigfloat" endpoints, nor is the iterator
293           variable a "Math::BigFloat".
294
295               use 5.010;
296               for my $i (12..13) {
297                 for my $j (20..21) {
298                   say $i ** $j;  # produces a floating-point number,
299                                  # not an object
300                 }
301               }
302
303       in_effect()
304           This method only works on Perl v5.9.4 or later.
305
306       hex()/oct()
307           "bigfloat" overrides these routines with versions that can also
308           handle big integer values. Under Perl prior to version v5.9.4,
309           however, this will not happen unless you specifically ask for it
310           with the two import tags "hex" and "oct" - and then it will be
311           global and cannot be disabled inside a scope with "no bigfloat":
312
313               use bigfloat qw/hex oct/;
314
315               print hex("0x1234567890123456");
316               {
317                   no bigfloat;
318                   print hex("0x1234567890123456");
319               }
320
321           The second call to hex() will warn about a non-portable constant.
322
323           Compare this to:
324
325               use bigfloat;
326
327               # will warn only under Perl older than v5.9.4
328               print hex("0x1234567890123456");
329

EXAMPLES

331       Some cool command line examples to impress the Python crowd ;)
332
333           perl -Mbigfloat -le 'print sqrt(33)'
334           perl -Mbigfloat -le 'print 2**255'
335           perl -Mbigfloat -le 'print 4.5+2**255'
336           perl -Mbigfloat -le 'print 3/7 + 5/7 + 8/3'
337           perl -Mbigfloat -le 'print 123->is_odd()'
338           perl -Mbigfloat -le 'print log(2)'
339           perl -Mbigfloat -le 'print exp(1)'
340           perl -Mbigfloat -le 'print 2 ** 0.5'
341           perl -Mbigfloat=a,65 -le 'print 2 ** 0.2'
342           perl -Mbigfloat=l,GMP -le 'print 7 ** 7777'
343

BUGS

345       Please report any bugs or feature requests to "bug-bignum at
346       rt.cpan.org", or through the web interface at
347       <https://rt.cpan.org/Ticket/Create.html?Queue=bignum> (requires login).
348       We will be notified, and then you'll automatically be notified of
349       progress on your bug as I make changes.
350

SUPPORT

352       You can find documentation for this module with the perldoc command.
353
354           perldoc bigfloat
355
356       You can also look for information at:
357
358       •   GitHub
359
360           <https://github.com/pjacklam/p5-bignum>
361
362       •   RT: CPAN's request tracker
363
364           <https://rt.cpan.org/Dist/Display.html?Name=bignum>
365
366       •   MetaCPAN
367
368           <https://metacpan.org/release/bignum>
369
370       •   CPAN Testers Matrix
371
372           <http://matrix.cpantesters.org/?dist=bignum>
373
374       •   CPAN Ratings
375
376           <https://cpanratings.perl.org/dist/bignum>
377

LICENSE

379       This program is free software; you may redistribute it and/or modify it
380       under the same terms as Perl itself.
381

AUTHORS

389       •   (C) by Tels <http://bloodgate.com/> in early 2002 - 2007.
390
391       •   Maintained by Peter John Acklam <pjacklam@gmail.com>, 2014-.
392
393
394
395perl v5.38.0                      2023-07-21                       bigfloat(3)