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

NAME

6       bigint - Transparent BigInteger support for Perl
7

SYNOPSIS

9         use bigint;
10
11         $x = 2 + 4.5,"\n";                    # BigInt 6
12         print 2 ** 512,"\n";                  # really is what you think it is
13         print inf + 42,"\n";                  # inf
14         print NaN * 7,"\n";                   # NaN
15         print hex("0x1234567890123490"),"\n"; # Perl v5.10.0 or later
16
17         {
18           no bigint;
19           print 2 ** 256,"\n";                # a normal Perl scalar now
20         }
21
22         # Import into current package:
23         use bigint qw/hex oct/;
24         print hex("0x1234567890123490"),"\n";
25         print oct("01234567890123490"),"\n";
26

DESCRIPTION

28       All operators (including basic math operations) except the range
29       operator ".."  are overloaded. Integer constants are created as proper
30       BigInts.
31
32       Floating point constants are truncated to integer. All parts and
33       results of expressions are also truncated.
34
35       Unlike integer, this pragma creates integer constants that are only
36       limited in their size by the available memory and CPU time.
37
38   use integer vs. use bigint
39       There is one small difference between "use integer" and "use bigint":
40       the former will not affect assignments to variables and the return
41       value of some functions. "bigint" truncates these results to integer
42       too:
43
44               # perl -Minteger -wle 'print 3.2'
45               3.2
46               # perl -Minteger -wle 'print 3.2 + 0'
47               3
48               # perl -Mbigint -wle 'print 3.2'
49               3
50               # perl -Mbigint -wle 'print 3.2 + 0'
51               3
52
53               # perl -Mbigint -wle 'print exp(1) + 0'
54               2
55               # perl -Mbigint -wle 'print exp(1)'
56               2
57               # perl -Minteger -wle 'print exp(1)'
58               2.71828182845905
59               # perl -Minteger -wle 'print exp(1) + 0'
60               2
61
62       In practice this makes seldom a difference as parts and results of
63       expressions will be truncated anyway, but this can, for instance,
64       affect the return value of subroutines:
65
66           sub three_integer { use integer; return 3.2; }
67           sub three_bigint { use bigint; return 3.2; }
68
69           print three_integer(), " ", three_bigint(),"\n";    # prints "3.2 3"
70
71   Options
72       bigint recognizes some options that can be passed while loading it via
73       use.  The options can (currently) be either a single letter form, or
74       the long form.  The following options exist:
75
76       a or accuracy
77         This sets the accuracy for all math operations. The argument must be
78         greater than or equal to zero. See Math::BigInt's bround() function
79         for details.
80
81                 perl -Mbigint=a,2 -le 'print 12345+1'
82
83         Note that setting precision and accuracy at the same time is not
84         possible.
85
86       p or precision
87         This sets the precision for all math operations. The argument can be
88         any integer. Negative values mean a fixed number of digits after the
89         dot, and are <B>ignored</B> since all operations happen in integer
90         space.  A positive value rounds to this digit left from the dot. 0 or
91         1 mean round to integer and are ignore like negative values.
92
93         See Math::BigInt's bfround() function for details.
94
95                 perl -Mbignum=p,5 -le 'print 123456789+123'
96
97         Note that setting precision and accuracy at the same time is not
98         possible.
99
100       t or trace
101         This enables a trace mode and is primarily for debugging bigint or
102         Math::BigInt.
103
104       hex
105         Override the built-in hex() method with a version that can handle big
106         integers. This overrides it by exporting it to the current package.
107         Under Perl v5.10.0 and higher, this is not so necessary, as hex() is
108         lexically overridden in the current scope whenever the bigint pragma
109         is active.
110
111       oct
112         Override the built-in oct() method with a version that can handle big
113         integers. This overrides it by exporting it to the current package.
114         Under Perl v5.10.0 and higher, this is not so necessary, as oct() is
115         lexically overridden in the current scope whenever the bigint pragma
116         is active.
117
118       l, lib, try or only
119         Load a different math lib, see "Math Library".
120
121                 perl -Mbigint=lib,GMP -e 'print 2 ** 512'
122                 perl -Mbigint=try,GMP -e 'print 2 ** 512'
123                 perl -Mbigint=only,GMP -e 'print 2 ** 512'
124
125         Currently there is no way to specify more than one library on the
126         command line. This means the following does not work:
127
128                 perl -Mbignum=l,GMP,Pari -e 'print 2 ** 512'
129
130         This will be hopefully fixed soon ;)
131
132       v or version
133         This prints out the name and version of all modules used and then
134         exits.
135
136                 perl -Mbigint=v
137
138   Math Library
139       Math with the numbers is done (by default) by a module called
140       Math::BigInt::Calc. This is equivalent to saying:
141
142               use bigint lib => 'Calc';
143
144       You can change this by using:
145
146               use bignum lib => 'GMP';
147
148       The following would first try to find Math::BigInt::Foo, then
149       Math::BigInt::Bar, and when this also fails, revert to
150       Math::BigInt::Calc:
151
152               use bigint lib => 'Foo,Math::BigInt::Bar';
153
154       Using "lib" warns if none of the specified libraries can be found and
155       Math::BigInt did fall back to one of the default libraries.  To
156       suppress this warning, use "try" instead:
157
158               use bignum try => 'GMP';
159
160       If you want the code to die instead of falling back, use "only"
161       instead:
162
163               use bignum only => 'GMP';
164
165       Please see respective module documentation for further details.
166
167   Internal Format
168       The numbers are stored as objects, and their internals might change at
169       anytime, especially between math operations. The objects also might
170       belong to different classes, like Math::BigInt, or Math::BigInt::Lite.
171       Mixing them together, even with normal scalars is not extraordinary,
172       but normal and expected.
173
174       You should not depend on the internal format, all accesses must go
175       through accessor methods. E.g. looking at $x->{sign} is not a good idea
176       since there is no guaranty that the object in question has such a hash
177       key, nor is a hash underneath at all.
178
179   Sign
180       The sign is either '+', '-', 'NaN', '+inf' or '-inf'.  You can access
181       it with the sign() method.
182
183       A sign of 'NaN' is used to represent the result when input arguments
184       are not numbers or as a result of 0/0. '+inf' and '-inf' represent plus
185       respectively minus infinity. You will get '+inf' when dividing a
186       positive number by 0, and '-inf' when dividing any negative number by
187       0.
188
189   Method calls
190       Since all numbers are now objects, you can use all functions that are
191       part of the BigInt API. You can only use the bxxx() notation, and not
192       the fxxx() notation, though.
193
194       But a warning is in order. When using the following to make a copy of a
195       number, only a shallow copy will be made.
196
197               $x = 9; $y = $x;
198               $x = $y = 7;
199
200       Using the copy or the original with overloaded math is okay, e.g. the
201       following work:
202
203               $x = 9; $y = $x;
204               print $x + 1, " ", $y,"\n";     # prints 10 9
205
206       but calling any method that modifies the number directly will result in
207       both the original and the copy being destroyed:
208
209               $x = 9; $y = $x;
210               print $x->badd(1), " ", $y,"\n";        # prints 10 10
211
212               $x = 9; $y = $x;
213               print $x->binc(1), " ", $y,"\n";        # prints 10 10
214
215               $x = 9; $y = $x;
216               print $x->bmul(2), " ", $y,"\n";        # prints 18 18
217
218       Using methods that do not modify, but test that the contents works:
219
220               $x = 9; $y = $x;
221               $z = 9 if $x->is_zero();                # works fine
222
223       See the documentation about the copy constructor and "=" in overload,
224       as well as the documentation in BigInt for further details.
225
226   Methods
227       inf()
228         A shortcut to return Math::BigInt->binf(). Useful because Perl does
229         not always handle bareword "inf" properly.
230
231       NaN()
232         A shortcut to return Math::BigInt->bnan(). Useful because Perl does
233         not always handle bareword "NaN" properly.
234
235       e
236                 # perl -Mbigint=e -wle 'print e'
237
238         Returns Euler's number "e", aka exp(1). Note that under bigint, this
239         is truncated to an integer, and hence simple '2'.
240
241       PI
242                 # perl -Mbigint=PI -wle 'print PI'
243
244         Returns PI. Note that under bigint, this is truncated to an integer,
245         and hence simple '3'.
246
247       bexp()
248                 bexp($power,$accuracy);
249
250         Returns Euler's number "e" raised to the appropriate power, to the
251         wanted accuracy.
252
253         Note that under bigint, the result is truncated to an integer.
254
255         Example:
256
257                 # perl -Mbigint=bexp -wle 'print bexp(1,80)'
258
259       bpi()
260                 bpi($accuracy);
261
262         Returns PI to the wanted accuracy. Note that under bigint, this is
263         truncated to an integer, and hence simple '3'.
264
265         Example:
266
267                 # perl -Mbigint=bpi -wle 'print bpi(80)'
268
269       upgrade()
270         Return the class that numbers are upgraded to, is in fact returning
271         $Math::BigInt::upgrade.
272
273       in_effect()
274                 use bigint;
275
276                 print "in effect\n" if bigint::in_effect;       # true
277                 {
278                   no bigint;
279                   print "in effect\n" if bigint::in_effect;     # false
280                 }
281
282         Returns true or false if "bigint" is in effect in the current scope.
283
284         This method only works on Perl v5.9.4 or later.
285

CAVEATS

287       Operator vs literal overloading
288         "bigint" works by overloading handling of integer and floating point
289         literals, converting them to Math::BigInt objects.
290
291         This means that arithmetic involving only string values or string
292         literals will be performed using Perl's built-in operators.
293
294         For example:
295
296             use bignum;
297             my $x = "900000000000000009";
298             my $y = "900000000000000007";
299             print $x - $y;
300
301         will output 0 on default 32-bit builds, since "bigint" never sees the
302         string literals.  To ensure the expression is all treated as
303         "Math::BigInt" objects, use a literal number in the expression:
304
305             print +(0+$x) - $y;
306
307       ranges
308         Perl does not allow overloading of ranges, so you can neither safely
309         use ranges with bigint endpoints, nor is the iterator variable a
310         bigint.
311
312                 use 5.010;
313                 for my $i (12..13) {
314                   for my $j (20..21) {
315                     say $i ** $j;  # produces a floating-point number,
316                                    # not a big integer
317                   }
318                 }
319
320       in_effect()
321         This method only works on Perl v5.9.4 or later.
322
323       hex()/oct()
324         "bigint" overrides these routines with versions that can also handle
325         big integer values. Under Perl prior to version v5.9.4, however, this
326         will not happen unless you specifically ask for it with the two
327         import tags "hex" and "oct" - and then it will be global and cannot
328         be disabled inside a scope with "no bigint":
329
330                 use bigint qw/hex oct/;
331
332                 print hex("0x1234567890123456");
333                 {
334                         no bigint;
335                         print hex("0x1234567890123456");
336                 }
337
338         The second call to hex() will warn about a non-portable constant.
339
340         Compare this to:
341
342                 use bigint;
343
344                 # will warn only under Perl older than v5.9.4
345                 print hex("0x1234567890123456");
346

MODULES USED

348       "bigint" is just a thin wrapper around various modules of the
349       Math::BigInt family. Think of it as the head of the family, who runs
350       the shop, and orders the others to do the work.
351
352       The following modules are currently used by bigint:
353
354               Math::BigInt::Lite      (for speed, and only if it is loadable)
355               Math::BigInt
356

EXAMPLES

358       Some cool command line examples to impress the Python crowd ;) You
359       might want to compare them to the results under -Mbignum or -Mbigrat:
360
361               perl -Mbigint -le 'print sqrt(33)'
362               perl -Mbigint -le 'print 2*255'
363               perl -Mbigint -le 'print 4.5+2*255'
364               perl -Mbigint -le 'print 3/7 + 5/7 + 8/3'
365               perl -Mbigint -le 'print 123->is_odd()'
366               perl -Mbigint -le 'print log(2)'
367               perl -Mbigint -le 'print 2 ** 0.5'
368               perl -Mbigint=a,65 -le 'print 2 ** 0.2'
369               perl -Mbignum=a,65,l,GMP -le 'print 7 ** 7777'
370

BUGS

372       For information about bugs and how to report them, see the BUGS section
373       in the documentation available with the perldoc command.
374
375           perldoc bignum
376

SUPPORT

378       You can find documentation for this module with the perldoc command.
379
380           perldoc bigint
381
382       For more information, see the SUPPORT section in the documentation
383       available with the perldoc command.
384
385           perldoc bignum
386

LICENSE

388       This program is free software; you may redistribute it and/or modify it
389       under the same terms as Perl itself.
390

SEE ALSO

392       bignum and bigrat.
393
394       Math::BigInt, Math::BigFloat, Math::BigRat and Math::Big as well as
395       Math::BigInt::FastCalc, Math::BigInt::Pari and Math::BigInt::GMP.
396

AUTHORS

398       •   (C) by Tels <http://bloodgate.com/> in early 2002 - 2007.
399
400       •   Maintained by Peter John Acklam <pjacklam@gmail.com<gt>, 2014-.
401
402
403
404perl v5.32.1                      2021-01-27                         bigint(3)
Impressum