1bigint(3pm) Perl Programmers Reference Guide bigint(3pm)
2
6 bigint - Transparent BigInteger support for Perl
7
9 use bigint;
10 $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 {
18 no bigint;
19 print 2 ** 256,"\n"; # a normal Perl scalar now
20 }
21 # Note that this will be global:
23 use bigint qw/hex oct/;
24 print hex("0x1234567890123490"),"\n";
25 print oct("01234567890123490"),"\n";
26
28 All operators (including basic math operations) are overloaded. Integer
29 constants are created as proper BigInts.
30 Floating point constants are truncated to integer. All parts and
32 results of expressions are also truncated.
33 Unlike integer, this pragma creates integer constants that are only
35 limited in their size by the available memory and CPU time.
36 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 # 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 # 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 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 sub three_integer { use integer; return 3.2; }
66 sub three_bigint { use bigint; return 3.2; }
67 print three_integer(), " ", three_bigint(),"\n"; # prints "3.2 3"
69 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 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 perl -Mbigint=a,2 -le 'print 12345+1'
81 Note that setting precision and accurary at the same time is not
83 possible.
84 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 See Math::BigInt's bfround() function for details.
93 perl -Mbignum=p,5 -le 'print 123456789+123'
95 Note that setting precision and accurary at the same time is not
97 possible.
98 t or trace
100 This enables a trace mode and is primarily for debugging bigint or
101 Math::BigInt.
102 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 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 l, lib, try or only
114 Load a different math lib, see "Math Library".
115 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 Currently there is no way to specify more than one library on the
121 command line. This means the following does not work:
122 perl -Mbignum=l,GMP,Pari -e 'print 2 ** 512'
124 This will be hopefully fixed soon ;)
126 v or version
128 This prints out the name and version of all modules used and then
129 exits.
130 perl -Mbigint=v
132 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 use bigint lib => 'Calc';
138 You can change this by using:
140 use bignum lib => 'GMP';
142 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 use bigint lib => 'Foo,Math::BigInt::Bar';
148 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 supress
151 this warning, use "try" instead:
152 use bignum try => 'GMP';
154 If you want the code to die instead of falling back, use "only"
156 instead:
157 use bignum only => 'GMP';
159 Please see respective module documentation for further details.
161 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 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 Sign
175 The sign is either '+', '-', 'NaN', '+inf' or '-inf'. You can access
176 it with the sign() method.
177 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 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 inf()
190 A shortcut to return Math::BigInt->binf(). Useful because Perl does
191 not always handle bareword "inf" properly.
192 NaN()
194 A shortcut to return Math::BigInt->bnan(). Useful because Perl does
195 not always handle bareword "NaN" properly.
196 e
198 # perl -Mbigint=e -wle 'print e'
199 Returns Euler's number "e", aka exp(1). Note that under bigint, this
201 is truncated to an integer, and hence simple '2'.
202 PI
204 # perl -Mbigint=PI -wle 'print PI'
205 Returns PI. Note that under bigint, this is truncated to an integer,
207 and hence simple '3'.
208 bexp()
210 bexp($power,$accuracy);
211 Returns Euler's number "e" raised to the appropriate power, to the
213 wanted accuracy.
214 Note that under bigint, the result is truncated to an integer.
216 Example:
218 # perl -Mbigint=bexp -wle 'print bexp(1,80)'
220 bpi()
222 bpi($accuracy);
223 Returns PI to the wanted accuracy. Note that under bigint, this is
225 truncated to an integer, and hence simple '3'.
226 Example:
228 # perl -Mbigint=bpi -wle 'print bpi(80)'
230 upgrade()
232 Return the class that numbers are upgraded to, is in fact returning
233 $Math::BigInt::upgrade.
234 in_effect()
236 use bigint;
237 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 Returns true or false if "bigint" is in effect in the current scope.
245 This method only works on Perl v5.9.4 or later.
247 MATH LIBRARY
249 Math with the numbers is done (by default) by a module called
250 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 $x = 9; $y = $x;
256 $x = $y = 7;
257 Using the copy or the original with overloaded math is okay, e.g. the
259 following work:
260 $x = 9; $y = $x;
262 print $x + 1, " ", $y,"\n"; # prints 10 9
263 but calling any method that modifies the number directly will result in
265 both the original and the copy being destroyed:
266 $x = 9; $y = $x;
268 print $x->badd(1), " ", $y,"\n"; # prints 10 10
269 $x = 9; $y = $x;
271 print $x->binc(1), " ", $y,"\n"; # prints 10 10
272 $x = 9; $y = $x;
274 print $x->bmul(2), " ", $y,"\n"; # prints 18 18
275 Using methods that do not modify, but testthe contents works:
277 $x = 9; $y = $x;
279 $z = 9 if $x->is_zero(); # works fine
280 See the documentation about the copy constructor and "=" in overload,
282 as well as the documentation in BigInt for further details.
283
285 in_effect()
286 This method only works on Perl v5.9.4 or later.
287 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 use bigint qw/hex oct/;
296 print hex("0x1234567890123456");
298 {
299 no bigint;
300 print hex("0x1234567890123456");
301 }
302 The second call to hex() will warn about a non-portable constant.
304 Compare this to:
306 use bigint;
308 # will warn only under Perl older than v5.9.4
310 print hex("0x1234567890123456");
311
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 The following modules are currently used by bigint:
318 Math::BigInt::Lite (for speed, and only if it is loadable)
320 Math::BigInt
321
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 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
337 This program is free software; you may redistribute it and/or modify it
338 under the same terms as Perl itself.
339
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 Math::BigInt, Math::BigRat and Math::Big as well as
345 Math::BigInt::BitVect, Math::BigInt::Pari and Math::BigInt::GMP.
346
348 (C) by Tels <http://bloodgate.com/> in early 2002 - 2007.
349perl v5.12.4 2011-06-20 bigint(3pm)