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

CAVEATS

285       in_effect()
286         This method only works on Perl v5.9.4 or later.
287
288       hex()/oct()
289         "bigint" overrides these routines with versions that can also handle
290         big integer values. Under Perl prior to version v5.9.4, however, this
291         will not happen unless you specifically ask for it with the two
292         import tags "hex" and "oct" - and then it will be global and cannot
293         be disabled inside a scope with "no bigint":
294
295                 use bigint qw/hex oct/;
296
297                 print hex("0x1234567890123456");
298                 {
299                         no bigint;
300                         print hex("0x1234567890123456");
301                 }
302
303         The second call to hex() will warn about a non-portable constant.
304
305         Compare this to:
306
307                 use bigint;
308
309                 # will warn only under Perl older than v5.9.4
310                 print hex("0x1234567890123456");
311

MODULES USED

313       "bigint" is just a thin wrapper around various modules of the
314       Math::BigInt family. Think of it as the head of the family, who runs
315       the shop, and orders the others to do the work.
316
317       The following modules are currently used by bigint:
318
319               Math::BigInt::Lite      (for speed, and only if it is loadable)
320               Math::BigInt
321

EXAMPLES

323       Some cool command line examples to impress the Python crowd ;) You
324       might want to compare them to the results under -Mbignum or -Mbigrat:
325
326               perl -Mbigint -le 'print sqrt(33)'
327               perl -Mbigint -le 'print 2*255'
328               perl -Mbigint -le 'print 4.5+2*255'
329               perl -Mbigint -le 'print 3/7 + 5/7 + 8/3'
330               perl -Mbigint -le 'print 123->is_odd()'
331               perl -Mbigint -le 'print log(2)'
332               perl -Mbigint -le 'print 2 ** 0.5'
333               perl -Mbigint=a,65 -le 'print 2 ** 0.2'
334               perl -Mbignum=a,65,l,GMP -le 'print 7 ** 7777'
335

LICENSE

337       This program is free software; you may redistribute it and/or modify it
338       under the same terms as Perl itself.
339

SEE ALSO

341       Especially bigrat as in "perl -Mbigrat -le 'print 1/3+1/4'" and bignum
342       as in "perl -Mbignum -le 'print sqrt(2)'".
343
344       Math::BigInt, Math::BigRat and Math::Big as well as
345       Math::BigInt::BitVect, Math::BigInt::Pari and  Math::BigInt::GMP.
346

AUTHORS

348       (C) by Tels <http://bloodgate.com/> in early 2002 - 2007.
349
350
351
352perl v5.16.3                      2013-03-04                       bigint(3pm)
Impressum