Debian Codegraph @

upstream/opensuse-tumbleweed/man3/bigrat.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "bigrat 3pm"
61 .TH bigrat 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 bigrat \- transparent big rational number support for Perl
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use bigrat;
72 \&
73 \& print 2 + 4.5; # Math::BigRat 13/2
74 \& print 1/3 + 1/4; # Math::BigRat 7/12
75 \& print inf + 42; # Math::BigRat inf
76 \& print NaN * 7; # Math::BigRat NaN
77 \& print hex("0x1234567890123490"); # Perl v5.10.0 or later
78 \&
79 \& {
80 \& no bigrat;
81 \& print 1/3; # 0.33333...
82 \& }
83 \&
84 \& # for older Perls, import into current package:
85 \& use bigrat qw/hex oct/;
86 \& print hex("0x1234567890123490");
87 \& print oct("01234567890123490");
88 .Ve
89 .SH DESCRIPTION
90 .IX Header "DESCRIPTION"
91 All numeric literal in the given scope are converted to Math::BigRat objects.
92 .PP
93 All operators (including basic math operations) except the range operator \f(CW\*(C`..\*(C'\fR
94 are overloaded.
95 .PP
96 So, the following:
97 .PP
98 .Vb 2
99 \& use bigrat;
100 \& $x = 1234;
101 .Ve
102 .PP
103 creates a Math::BigRat and stores a reference to in \f(CW$x\fR. This happens
104 transparently and behind your back, so to speak.
105 .PP
106 You can see this with the following:
107 .PP
108 .Vb 1
109 \& perl \-Mbigrat \-le \*(Aqprint ref(1234)\*(Aq
110 .Ve
111 .PP
112 Since numbers are actually objects, you can call all the usual methods from
113 Math::BigRat on them. This even works to some extent on expressions:
114 .PP
115 .Vb 4
116 \& perl \-Mbigrat \-le \*(Aq$x = 1234; print $x\->bdec()\*(Aq
117 \& perl \-Mbigrat \-le \*(Aqprint 1234\->copy()\->binc();\*(Aq
118 \& perl \-Mbigrat \-le \*(Aqprint 1234\->copy()\->binc\->badd(6);\*(Aq
119 \& perl \-Mbigrat \-le \*(Aqprint +(1234)\->copy()\->binc()\*(Aq
120 .Ve
121 .PP
122 (Note that print doesn\*(Aqt do what you expect if the expression starts with
123 \&\*(Aq(\*(Aq hence the \f(CW\*(C`+\*(C'\fR)
124 .PP
125 You can even chain the operations together as usual:
126 .PP
127 .Vb 2
128 \& perl \-Mbigrat \-le \*(Aqprint 1234\->copy()\->binc\->badd(6);\*(Aq
129 \& 1241
130 .Ve
131 .PP
132 Please note the following does not work as expected (prints nothing), since
133 overloading of \*(Aq..\*(Aq is not yet possible in Perl (as of v5.8.0):
134 .PP
135 .Vb 1
136 \& perl \-Mbigrat \-le \*(Aqfor (1..2) { print ref($_); }\*(Aq
137 .Ve
138 .SS Options
139 .IX Subsection "Options"
140 \&\f(CW\*(C`bigrat\*(C'\fR recognizes some options that can be passed while loading it via
141 \&\f(CW\*(C`use\*(C'\fR. The following options exist:
142 .IP "a or accuracy" 4
143 .IX Item "a or accuracy"
144 This sets the accuracy for all math operations. The argument must be greater
145 than or equal to zero. See Math::BigInt\*(Aqs \fBbround()\fR method for details.
146 .Sp
147 .Vb 1
148 \& perl \-Mbigrat=a,50 \-le \*(Aqprint sqrt(20)\*(Aq
149 .Ve
150 .Sp
151 Note that setting precision and accuracy at the same time is not possible.
152 .IP "p or precision" 4
153 .IX Item "p or precision"
154 This sets the precision for all math operations. The argument can be any
155 integer. Negative values mean a fixed number of digits after the dot, while a
156 positive value rounds to this digit left from the dot. 0 means round to integer.
157 See Math::BigInt\*(Aqs \fBbfround()\fR method for details.
158 .Sp
159 .Vb 1
160 \& perl \-Mbigrat=p,\-50 \-le \*(Aqprint sqrt(20)\*(Aq
161 .Ve
162 .Sp
163 Note that setting precision and accuracy at the same time is not possible.
164 .IP "t or trace" 4
165 .IX Item "t or trace"
166 This enables a trace mode and is primarily for debugging.
167 .IP "l, lib, try, or only" 4
168 .IX Item "l, lib, try, or only"
169 Load a different math lib, see "Math Library".
170 .Sp
171 .Vb 4
172 \& perl \-Mbigrat=l,GMP \-e \*(Aqprint 2 ** 512\*(Aq
173 \& perl \-Mbigrat=lib,GMP \-e \*(Aqprint 2 ** 512\*(Aq
174 \& perl \-Mbigrat=try,GMP \-e \*(Aqprint 2 ** 512\*(Aq
175 \& perl \-Mbigrat=only,GMP \-e \*(Aqprint 2 ** 512\*(Aq
176 .Ve
177 .IP hex 4
178 .IX Item "hex"
179 Override the built\-in \fBhex()\fR method with a version that can handle big numbers.
180 This overrides it by exporting it to the current package. Under Perl v5.10.0 and
181 higher, this is not so necessary, as \fBhex()\fR is lexically overridden in the
182 current scope whenever the \f(CW\*(C`bigrat\*(C'\fR pragma is active.
183 .IP oct 4
184 .IX Item "oct"
185 Override the built\-in \fBoct()\fR method with a version that can handle big numbers.
186 This overrides it by exporting it to the current package. Under Perl v5.10.0 and
187 higher, this is not so necessary, as \fBoct()\fR is lexically overridden in the
188 current scope whenever the \f(CW\*(C`bigrat\*(C'\fR pragma is active.
189 .IP "v or version" 4
190 .IX Item "v or version"
191 this prints out the name and version of the modules and then exits.
192 .Sp
193 .Vb 1
194 \& perl \-Mbigrat=v
195 .Ve
196 .SS "Math Library"
197 .IX Subsection "Math Library"
198 Math with the numbers is done (by default) by a backend library module called
199 Math::BigInt::Calc. The default is equivalent to saying:
200 .PP
201 .Vb 1
202 \& use bigrat lib => \*(AqCalc\*(Aq;
203 .Ve
204 .PP
205 you can change this by using:
206 .PP
207 .Vb 1
208 \& use bigrat lib => \*(AqGMP\*(Aq;
209 .Ve
210 .PP
211 The following would first try to find Math::BigInt::Foo, then Math::BigInt::Bar,
212 and if this also fails, revert to Math::BigInt::Calc:
213 .PP
214 .Vb 1
215 \& use bigrat lib => \*(AqFoo,Math::BigInt::Bar\*(Aq;
216 .Ve
217 .PP
218 Using c<lib> warns if none of the specified libraries can be found and
219 Math::BigInt fell back to one of the default libraries. To suppress this
220 warning, use c<try> instead:
221 .PP
222 .Vb 1
223 \& use bigrat try => \*(AqGMP\*(Aq;
224 .Ve
225 .PP
226 If you want the code to die instead of falling back, use \f(CW\*(C`only\*(C'\fR instead:
227 .PP
228 .Vb 1
229 \& use bigrat only => \*(AqGMP\*(Aq;
230 .Ve
231 .PP
232 Please see the respective module documentation for further details.
233 .SS "Method calls"
234 .IX Subsection "Method calls"
235 Since all numbers are now objects, you can use all methods that are part of the
236 Math::BigRat API.
237 .PP
238 But a warning is in order. When using the following to make a copy of a number,
239 only a shallow copy will be made.
240 .PP
241 .Vb 2
242 \& $x = 9; $y = $x;
243 \& $x = $y = 7;
244 .Ve
245 .PP
246 Using the copy or the original with overloaded math is okay, e.g., the following
247 work:
248 .PP
249 .Vb 2
250 \& $x = 9; $y = $x;
251 \& print $x + 1, " ", $y,"\en"; # prints 10 9
252 .Ve
253 .PP
254 but calling any method that modifies the number directly will result in \fBboth\fR
255 the original and the copy being destroyed:
256 .PP
257 .Vb 2
258 \& $x = 9; $y = $x;
259 \& print $x\->badd(1), " ", $y,"\en"; # prints 10 10
260 \&
261 \& $x = 9; $y = $x;
262 \& print $x\->binc(1), " ", $y,"\en"; # prints 10 10
263 \&
264 \& $x = 9; $y = $x;
265 \& print $x\->bmul(2), " ", $y,"\en"; # prints 18 18
266 .Ve
267 .PP
268 Using methods that do not modify, but test that the contents works:
269 .PP
270 .Vb 2
271 \& $x = 9; $y = $x;
272 \& $z = 9 if $x\->is_zero(); # works fine
273 .Ve
274 .PP
275 See the documentation about the copy constructor and \f(CW\*(C`=\*(C'\fR in overload, as well
276 as the documentation in Math::BigFloat for further details.
277 .SS Methods
278 .IX Subsection "Methods"
279 .IP \fBinf()\fR 4
280 .IX Item "inf()"
281 A shortcut to return Math::BigRat\->\fBbinf()\fR. Useful because Perl does not always
282 handle bareword \f(CW\*(C`inf\*(C'\fR properly.
283 .IP \fBNaN()\fR 4
284 .IX Item "NaN()"
285 A shortcut to return Math::BigRat\->\fBbnan()\fR. Useful because Perl does not always
286 handle bareword \f(CW\*(C`NaN\*(C'\fR properly.
287 .IP e 4
288 .IX Item "e"
289 .Vb 1
290 \& # perl \-Mbigrat=e \-wle \*(Aqprint e\*(Aq
291 .Ve
292 .Sp
293 Returns Euler\*(Aqs number \f(CW\*(C`e\*(C'\fR, aka \fBexp\fR\|(1).
294 .IP PI 4
295 .IX Item "PI"
296 .Vb 1
297 \& # perl \-Mbigrat=PI \-wle \*(Aqprint PI\*(Aq
298 .Ve
299 .Sp
300 Returns PI.
301 .IP \fBbexp()\fR 4
302 .IX Item "bexp()"
303 .Vb 1
304 \& bexp($power, $accuracy);
305 .Ve
306 .Sp
307 Returns Euler\*(Aqs number \f(CW\*(C`e\*(C'\fR raised to the appropriate power, to the wanted
308 accuracy.
309 .Sp
310 Example:
311 .Sp
312 .Vb 1
313 \& # perl \-Mbigrat=bexp \-wle \*(Aqprint bexp(1,80)\*(Aq
314 .Ve
315 .IP \fBbpi()\fR 4
316 .IX Item "bpi()"
317 .Vb 1
318 \& bpi($accuracy);
319 .Ve
320 .Sp
321 Returns PI to the wanted accuracy.
322 .Sp
323 Example:
324 .Sp
325 .Vb 1
326 \& # perl \-Mbigrat=bpi \-wle \*(Aqprint bpi(80)\*(Aq
327 .Ve
328 .IP \fBaccuracy()\fR 4
329 .IX Item "accuracy()"
330 Set or get the accuracy.
331 .IP \fBprecision()\fR 4
332 .IX Item "precision()"
333 Set or get the precision.
334 .IP \fBround_mode()\fR 4
335 .IX Item "round_mode()"
336 Set or get the rounding mode.
337 .IP \fBdiv_scale()\fR 4
338 .IX Item "div_scale()"
339 Set or get the division scale.
340 .IP \fBin_effect()\fR 4
341 .IX Item "in_effect()"
342 .Vb 1
343 \& use bigrat;
344 \&
345 \& print "in effect\en" if bigrat::in_effect; # true
346 \& {
347 \& no bigrat;
348 \& print "in effect\en" if bigrat::in_effect; # false
349 \& }
350 .Ve
351 .Sp
352 Returns true or false if \f(CW\*(C`bigrat\*(C'\fR is in effect in the current scope.
353 .Sp
354 This method only works on Perl v5.9.4 or later.
355 .SH CAVEATS
356 .IX Header "CAVEATS"
357 .IP "Hexadecimal, octal, and binary floating point literals" 4
358 .IX Item "Hexadecimal, octal, and binary floating point literals"
359 Perl (and this module) accepts hexadecimal, octal, and binary floating point
360 literals, but use them with care with Perl versions before v5.32.0, because some
361 versions of Perl silently give the wrong result.
362 .IP "Operator vs literal overloading" 4
363 .IX Item "Operator vs literal overloading"
364 \&\f(CW\*(C`bigrat\*(C'\fR works by overloading handling of integer and floating point literals,
365 converting them to Math::BigRat objects.
366 .Sp
367 This means that arithmetic involving only string values or string literals are
368 performed using Perl\*(Aqs built\-in operators.
369 .Sp
370 For example:
371 .Sp
372 .Vb 4
373 \& use bigrat;
374 \& my $x = "900000000000000009";
375 \& my $y = "900000000000000007";
376 \& print $x \- $y;
377 .Ve
378 .Sp
379 outputs \f(CW0\fR on default 32\-bit builds, since \f(CW\*(C`bigrat\*(C'\fR never sees the string
380 literals. To ensure the expression is all treated as \f(CW\*(C`Math::BigRat\*(C'\fR objects,
381 use a literal number in the expression:
382 .Sp
383 .Vb 1
384 \& print +(0+$x) \- $y;
385 .Ve
386 .IP Ranges 4
387 .IX Item "Ranges"
388 Perl does not allow overloading of ranges, so you can neither safely use ranges
389 with \f(CW\*(C`bigrat\*(C'\fR endpoints, nor is the iterator variable a \f(CW\*(C`Math::BigRat\*(C'\fR.
390 .Sp
391 .Vb 7
392 \& use 5.010;
393 \& for my $i (12..13) {
394 \& for my $j (20..21) {
395 \& say $i ** $j; # produces a floating\-point number,
396 \& # not an object
397 \& }
398 \& }
399 .Ve
400 .IP \fBin_effect()\fR 4
401 .IX Item "in_effect()"
402 This method only works on Perl v5.9.4 or later.
403 .IP \fBhex()\fR/\fBoct()\fR 4
404 .IX Item "hex()/oct()"
405 \&\f(CW\*(C`bigrat\*(C'\fR overrides these routines with versions that can also handle big
406 integer values. Under Perl prior to version v5.9.4, however, this will not
407 happen unless you specifically ask for it with the two import tags "hex" and
408 "oct" \- and then it will be global and cannot be disabled inside a scope with
409 \&\f(CW\*(C`no bigrat\*(C'\fR:
410 .Sp
411 .Vb 1
412 \& use bigrat qw/hex oct/;
413 \&
414 \& print hex("0x1234567890123456");
415 \& {
416 \& no bigrat;
417 \& print hex("0x1234567890123456");
418 \& }
419 .Ve
420 .Sp
421 The second call to \fBhex()\fR will warn about a non\-portable constant.
422 .Sp
423 Compare this to:
424 .Sp
425 .Vb 1
426 \& use bigrat;
427 \&
428 \& # will warn only under Perl older than v5.9.4
429 \& print hex("0x1234567890123456");
430 .Ve
431 .SH EXAMPLES
432 .IX Header "EXAMPLES"
433 .Vb 6
434 \& perl \-Mbigrat \-le \*(Aqprint sqrt(33)\*(Aq
435 \& perl \-Mbigrat \-le \*(Aqprint 2**255\*(Aq
436 \& perl \-Mbigrat \-le \*(Aqprint 4.5+2**255\*(Aq
437 \& perl \-Mbigrat \-le \*(Aqprint 3/7 + 5/7 + 8/3\*(Aq
438 \& perl \-Mbigrat \-le \*(Aqprint 12\->is_odd()\*(Aq;
439 \& perl \-Mbigrat=l,GMP \-le \*(Aqprint 7 ** 7777\*(Aq
440 .Ve
441 .SH BUGS
442 .IX Header "BUGS"
443 Please report any bugs or feature requests to
444 \&\f(CW\*(C`bug\-bignum at rt.cpan.org\*(C'\fR, or through the web interface at
445 <https://rt.cpan.org/Ticket/Create.html?Queue=bignum> (requires login).
446 We will be notified, and then you\*(Aqll automatically be notified of
447 progress on your bug as I make changes.
448 .SH SUPPORT
449 .IX Header "SUPPORT"
450 You can find documentation for this module with the perldoc command.
451 .PP
452 .Vb 1
453 \& perldoc bigrat
454 .Ve
455 .PP
456 You can also look for information at:
457 .IP \(bu 4
458 GitHub
459 .Sp
460 <https://github.com/pjacklam/p5\-bignum>
461 .IP \(bu 4
462 RT: CPAN\*(Aqs request tracker
463 .Sp
464 <https://rt.cpan.org/Dist/Display.html?Name=bignum>
465 .IP \(bu 4
466 MetaCPAN
467 .Sp
468 <https://metacpan.org/release/bignum>
469 .IP \(bu 4
470 CPAN Testers Matrix
471 .Sp
472 <http://matrix.cpantesters.org/?dist=bignum>
473 .SH LICENSE
474 .IX Header "LICENSE"
475 This program is free software; you may redistribute it and/or modify it under
476 the same terms as Perl itself.
477 .SH "SEE ALSO"
478 .IX Header "SEE ALSO"
479 bignum and bigint.
480 .PP
481 Math::BigInt, Math::BigFloat, Math::BigRat and Math::Big as well as
482 Math::BigInt::FastCalc, Math::BigInt::Pari and Math::BigInt::GMP.
483 .SH AUTHORS
484 .IX Header "AUTHORS"
485 .IP \(bu 4
486 (C) by Tels <http://bloodgate.com/> in early 2002 \- 2007.
487 .IP \(bu 4
488 Maintained by Peter John Acklam <[email protected]>, 2014\-.