Debian Codegraph @

upstream/debian-unstable/man3/bigint.3perl

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