bigrat(3pm)

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

NAME

6       bigrat - transparent big rational number support for Perl
7

SYNOPSIS

9           use bigrat;
10
11           print 2 + 4.5;                      # Math::BigRat 13/2
12           print 1/3 + 1/4;                    # Math::BigRat 7/12
13           print inf + 42;                     # Math::BigRat inf
14           print NaN * 7;                      # Math::BigRat NaN
15           print hex("0x1234567890123490");    # Perl v5.10.0 or later
16
17           {
18               no bigrat;
19               print 1/3;                      # 0.33333...
20           }
21
22           # for older Perls, import into current package:
23           use bigrat qw/hex oct/;
24           print hex("0x1234567890123490");
25           print oct("01234567890123490");
26

DESCRIPTION

28       All numeric literal in the given scope are converted to Math::BigRat
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 bigrat;
37           $x = 1234;
38
39       creates a Math::BigRat 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 -Mbigrat -le 'print ref(1234)'
45
46       Since numbers are actually objects, you can call all the usual methods
47       from Math::BigRat on them. This even works to some extent on
48       expressions:
49
50           perl -Mbigrat -le '$x = 1234; print $x->bdec()'
51           perl -Mbigrat -le 'print 1234->copy()->binc();'
52           perl -Mbigrat -le 'print 1234->copy()->binc->badd(6);'
53           perl -Mbigrat -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 -Mbigrat -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 -Mbigrat -le 'for (1..2) { print ref($_); }'
67
68   Options
69       "bigrat" recognizes some options that can be passed while loading it
70       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 -Mbigrat=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 -Mbigrat=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 -Mbigrat=l,GMP -e 'print 2 ** 512'
101               perl -Mbigrat=lib,GMP -e 'print 2 ** 512'
102               perl -Mbigrat=try,GMP -e 'print 2 ** 512'
103               perl -Mbigrat=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           "bigrat" 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           "bigrat" 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 -Mbigrat=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 bigrat lib => 'Calc';
127
128       you can change this by using:
129
130           use bigrat 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 bigrat 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 bigrat try => 'GMP';
143
144       If you want the code to die instead of falling back, use "only"
145       instead:
146
147           use bigrat only => 'GMP';
148
149       Please see the 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::BigRat 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::BigRat->binf(). Useful because Perl does
190           not always handle bareword "inf" properly.
191
192       NaN()
193           A shortcut to return Math::BigRat->bnan(). Useful because Perl does
194           not always handle bareword "NaN" properly.
195
196       e
197               # perl -Mbigrat=e -wle 'print e'
198
199           Returns Euler's number "e", aka exp(1).
200
201       PI
202               # perl -Mbigrat=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 -Mbigrat=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 -Mbigrat=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       in_effect()
238               use bigrat;
239
240               print "in effect\n" if bigrat::in_effect;       # true
241               {
242                   no bigrat;
243                   print "in effect\n" if bigrat::in_effect;   # false
244               }
245
246           Returns true or false if "bigrat" is in effect in the current
247           scope.
248
249           This method only works on Perl v5.9.4 or later.
250

CAVEATS

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

EXAMPLES

319           perl -Mbigrat -le 'print sqrt(33)'
320           perl -Mbigrat -le 'print 2**255'
321           perl -Mbigrat -le 'print 4.5+2**255'
322           perl -Mbigrat -le 'print 3/7 + 5/7 + 8/3'
323           perl -Mbigrat -le 'print 12->is_odd()';
324           perl -Mbigrat=l,GMP -le 'print 7 ** 7777'
325

BUGS

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

SUPPORT

334       You can find documentation for this module with the perldoc command.
335
336           perldoc bigrat
337
338       You can also look for information at:
339
340       •   GitHub
341
342           <https://github.com/pjacklam/p5-bignum>
343
344       •   RT: CPAN's request tracker
345
346           <https://rt.cpan.org/Dist/Display.html?Name=bignum>
347
348       •   MetaCPAN
349
350           <https://metacpan.org/release/bignum>
351
352       •   CPAN Testers Matrix
353
354           <http://matrix.cpantesters.org/?dist=bignum>
355
356       •   CPAN Ratings
357
358           <https://cpanratings.perl.org/dist/bignum>
359

LICENSE

361       This program is free software; you may redistribute it and/or modify it
362       under the same terms as Perl itself.
363

AUTHORS

371       •   (C) by Tels <http://bloodgate.com/> in early 2002 - 2007.
372
373       •   Maintained by Peter John Acklam <pjacklam@gmail.com>, 2014-.
374
375
376
377perl v5.38.0                      2023-07-21                         bigrat(3)