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

NAME

6       bigint - transparent big integer support for Perl
7

SYNOPSIS

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

CAVEATS

299       Hexadecimal, octal, and binary floating point literals
300           Perl (and this module) accepts hexadecimal, octal, and binary
301           floating point literals, but use them with care with Perl versions
302           before v5.32.0, because some versions of Perl silently give the
303           wrong result.
304
305       Operator vs literal overloading
306           "bigint" works by overloading handling of integer and floating
307           point literals, converting them to Math::BigInt objects.
308
309           This means that arithmetic involving only string values or string
310           literals are performed using Perl's built-in operators.
311
312           For example:
313
314               use bigint;
315               my $x = "900000000000000009";
316               my $y = "900000000000000007";
317               print $x - $y;
318
319           outputs 0 on default 32-bit builds, since "bigint" never sees the
320           string literals. To ensure the expression is all treated as
321           "Math::BigInt" objects, use a literal number in the expression:
322
323               print +(0+$x) - $y;
324
325       Ranges
326           Perl does not allow overloading of ranges, so you can neither
327           safely use ranges with "bigint" endpoints, nor is the iterator
328           variable a "Math::BigInt".
329
330               use 5.010;
331               for my $i (12..13) {
332                 for my $j (20..21) {
333                   say $i ** $j;  # produces a floating-point number,
334                                  # not an object
335                 }
336               }
337
338       in_effect()
339           This method only works on Perl v5.9.4 or later.
340
341       hex()/oct()
342           "bigint" overrides these routines with versions that can also
343           handle big integer values. Under Perl prior to version v5.9.4,
344           however, this will not happen unless you specifically ask for it
345           with the two import tags "hex" and "oct" - and then it will be
346           global and cannot be disabled inside a scope with "no bigint":
347
348               use bigint qw/hex oct/;
349
350               print hex("0x1234567890123456");
351               {
352                   no bigint;
353                   print hex("0x1234567890123456");
354               }
355
356           The second call to hex() will warn about a non-portable constant.
357
358           Compare this to:
359
360               use bigint;
361
362               # will warn only under Perl older than v5.9.4
363               print hex("0x1234567890123456");
364

EXAMPLES

366       Some cool command line examples to impress the Python crowd ;) You
367       might want to compare them to the results under -Mbigfloat or -Mbigrat:
368
369           perl -Mbigint -le 'print sqrt(33)'
370           perl -Mbigint -le 'print 2*255'
371           perl -Mbigint -le 'print 4.5+2*255'
372           perl -Mbigint -le 'print 123->is_odd()'
373           perl -Mbigint=l,GMP -le 'print 7 ** 7777'
374

BUGS

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

SUPPORT

383       You can find documentation for this module with the perldoc command.
384
385           perldoc bigint
386
387       You can also look for information at:
388
389       •   GitHub
390
391           <https://github.com/pjacklam/p5-bignum>
392
393       •   RT: CPAN's request tracker
394
395           <https://rt.cpan.org/Dist/Display.html?Name=bignum>
396
397       •   MetaCPAN
398
399           <https://metacpan.org/release/bignum>
400
401       •   CPAN Testers Matrix
402
403           <http://matrix.cpantesters.org/?dist=bignum>
404
405       •   CPAN Ratings
406
407           <https://cpanratings.perl.org/dist/bignum>
408

LICENSE

410       This program is free software; you may redistribute it and/or modify it
411       under the same terms as Perl itself.
412

SEE ALSO

414       bignum and bigrat.
415
416       Math::BigInt, Math::BigFloat, Math::BigRat and Math::Big as well as
417       Math::BigInt::FastCalc, Math::BigInt::Pari and Math::BigInt::GMP.
418

AUTHORS

420       •   (C) by Tels <http://bloodgate.com/> in early 2002 - 2007.
421
422       •   Maintained by Peter John Acklam <pjacklam@gmail.com>, 2014-.
423
424
425
426perl v5.34.1                      2022-04-13                         bigint(3)
Impressum