bignum(3pm)

1bignum(3pm)            Perl Programmers Reference Guide            bignum(3pm)
2
3
4

NAME

6       bignum - Transparent BigNumber support for Perl
7

SYNOPSIS

9         use bignum;
10
11         $x = 2 + 4.5,"\n";                    # BigFloat 6.5
12         print 2 ** 512 * 0.1,"\n";            # really is what you think it is
13         print inf * inf,"\n";                 # prints inf
14         print NaN * 3,"\n";                   # prints NaN
15

DESCRIPTION

17       All operators (including basic math operations) are overloaded. Integer
18       and floating-point constants are created as proper BigInts or
19       BigFloats, respectively.
20
21       If you do
22
23               use bignum;
24
25       at the top of your script, Math::BigFloat and Math::BigInt will be
26       loaded and any constant number will be converted to an object
27       (Math::BigFloat for floats like 3.1415 and Math::BigInt for integers
28       like 1234).
29
30       So, the following line:
31
32               $x = 1234;
33
34       creates actually a Math::BigInt and stores a reference to in $x.  This
35       happens transparently and behind your back, so to speak.
36
37       You can see this with the following:
38
39               perl -Mbignum -le 'print ref(1234)'
40
41       Don't worry if it says Math::BigInt::Lite, bignum and friends will use
42       Lite if it is installed since it is faster for some operations. It will
43       be automatically upgraded to BigInt whenever neccessary:
44
45               perl -Mbignum -le 'print ref(2**255)'
46
47       This also means it is a bad idea to check for some specific package,
48       since the actual contents of $x might be something unexpected. Due to
49       the transparent way of bignum "ref()" should not be neccessary, anyway.
50
51       Since Math::BigInt and BigFloat also overload the normal math opera‐
52       tions, the following line will still work:
53
54               perl -Mbignum -le 'print ref(1234+1234)'
55
56       Since numbers are actually objects, you can call all the usual methods
57       from BigInt/BigFloat on them. This even works to some extent on expres‐
58       sions:
59
60               perl -Mbignum -le '$x = 1234; print $x->bdec()'
61               perl -Mbignum -le 'print 1234->binc();'
62               perl -Mbignum -le 'print 1234->binc->badd(6);'
63               perl -Mbignum -le 'print +(1234)->binc()'
64
65       (Note that print doesn't do what you expect if the expression starts
66       with '(' hence the "+")
67
68       You can even chain the operations together as usual:
69
70               perl -Mbignum -le 'print 1234->binc->badd(6);'
71               1241
72
73       Under bignum (or bigint or bigrat), Perl will "upgrade" the numbers
74       appropriately. This means that:
75
76               perl -Mbignum -le 'print 1234+4.5'
77               1238.5
78
79       will work correctly. These mixed cases don't do always work when using
80       Math::BigInt or Math::BigFloat alone, or at least not in the way normal
81       Perl scalars work.
82
83       If you do want to work with large integers like under "use integer;",
84       try "use bigint;":
85
86               perl -Mbigint -le 'print 1234.5+4.5'
87               1238
88
89       There is also "use bigrat;" which gives you big rationals:
90
91               perl -Mbigrat -le 'print 1234+4.1'
92               12381/10
93
94       The entire upgrading/downgrading is still experimental and might not
95       work as you expect or may even have bugs.
96
97       You might get errors like this:
98
99               Can't use an undefined value as an ARRAY reference at
100               /usr/local/lib/perl5/5.8.0/Math/BigInt/Calc.pm line 864
101
102       This means somewhere a routine got a BigFloat/Lite but expected a Big‐
103       Int (or vice versa) and the upgrade/downgrad path was missing. This is
104       a bug, please report it so that we can fix it.
105
106       You might consider using just Math::BigInt or Math::BigFloat, since
107       they allow you finer control over what get's done in which mod‐
108       ule/space. For instance, simple loop counters will be Math::BigInts
109       under "use bignum;" and this is slower than keeping them as Perl
110       scalars:
111
112               perl -Mbignum -le 'for ($i = 0; $i < 10; $i++) { print ref($i); }'
113
114       Please note the following does not work as expected (prints nothing),
115       since overloading of '..' is not yet possible in Perl (as of v5.8.0):
116
117               perl -Mbignum -le 'for (1..2) { print ref($_); }'
118
119       Options
120
121       bignum recognizes some options that can be passed while loading it via
122       use.  The options can (currently) be either a single letter form, or
123       the long form.  The following options exist:
124
125       a or accuracy
126         This sets the accuracy for all math operations. The argument must be
127         greater than or equal to zero. See Math::BigInt's bround() function
128         for details.
129
130                 perl -Mbignum=a,50 -le 'print sqrt(20)'
131
132       p or precision
133         This sets the precision for all math operations. The argument can be
134         any integer. Negative values mean a fixed number of digits after the
135         dot, while a positive value rounds to this digit left from the dot. 0
136         or 1 mean round to integer. See Math::BigInt's bfround() function for
137         details.
138
139                 perl -Mbignum=p,-50 -le 'print sqrt(20)'
140
141       t or trace
142         This enables a trace mode and is primarily for debugging bignum or
143         Math::BigInt/Math::BigFloat.
144
145       l or lib
146         Load a different math lib, see "MATH LIBRARY".
147
148                 perl -Mbignum=l,GMP -e 'print 2 ** 512'
149
150         Currently there is no way to specify more than one library on the
151         command line. This will be hopefully fixed soon ;)
152
153       v or version
154         This prints out the name and version of all modules used and then
155         exits.
156
157                 perl -Mbignum=v
158
159       Methods
160
161       Beside import() and AUTOLOAD() there are only a few other methods.
162
163       Since all numbers are now objects, you can use all functions that are
164       part of the BigInt or BigFloat API. It is wise to use only the bxxx()
165       notation, and not the fxxx() notation, though. This makes it possible
166       that the underlying object might morph into a different class than
167       BigFloat.
168
169       Caveat
170
171       But a warning is in order. When using the following to make a copy of a
172       number, only a shallow copy will be made.
173
174               $x = 9; $y = $x;
175               $x = $y = 7;
176
177       If you want to make a real copy, use the following:
178
179               $y = $x->copy();
180
181       Using the copy or the original with overloaded math is okay, e.g. the
182       following work:
183
184               $x = 9; $y = $x;
185               print $x + 1, " ", $y,"\n";     # prints 10 9
186
187       but calling any method that modifies the number directly will result in
188       both the original and the copy beeing destroyed:
189
190               $x = 9; $y = $x;
191               print $x->badd(1), " ", $y,"\n";        # prints 10 10
192
193               $x = 9; $y = $x;
194               print $x->binc(1), " ", $y,"\n";        # prints 10 10
195
196               $x = 9; $y = $x;
197               print $x->bmul(2), " ", $y,"\n";        # prints 18 18
198
199       Using methods that do not modify, but testthe contents works:
200
201               $x = 9; $y = $x;
202               $z = 9 if $x->is_zero();                # works fine
203
204       See the documentation about the copy constructor and "=" in overload,
205       as well as the documentation in BigInt for further details.
206
207         inf()
208           A shortcut to return Math::BigInt->binf(). Usefull because Perl
209           does not always handle bareword "inf" properly.
210
211         NaN()
212           A shortcut to return Math::BigInt->bnan(). Usefull because Perl
213           does not always handle bareword "NaN" properly.
214
215         upgrade()
216           Return the class that numbers are upgraded to, is in fact returning
217           $Math::BigInt::upgrade.
218
219         MATH LIBRARY
220
221         Math with the numbers is done (by default) by a module called
222         Math::BigInt::Calc. This is equivalent to saying:
223
224                 use bignum lib => 'Calc';
225
226         You can change this by using:
227
228                 use bignum lib => 'BitVect';
229
230         The following would first try to find Math::BigInt::Foo, then
231         Math::BigInt::Bar, and when this also fails, revert to Math::Big‐
232         Int::Calc:
233
234                 use bignum lib => 'Foo,Math::BigInt::Bar';
235
236         Please see respective module documentation for further details.
237
238         INTERNAL FORMAT
239
240         The numbers are stored as objects, and their internals might change
241         at anytime, especially between math operations. The objects also
242         might belong to different classes, like Math::BigInt, or
243         Math::BigFLoat. Mixing them together, even with normal scalars is not
244         extraordinary, but normal and expected.
245
246         You should not depend on the internal format, all accesses must go
247         through accessor methods. E.g. looking at $x->{sign} is not a bright
248         idea since there is no guaranty that the object in question has such
249         a hashkey, nor is a hash underneath at all.
250
251         SIGN
252
253         The sign is either '+', '-', 'NaN', '+inf' or '-inf' and stored
254         seperately.  You can access it with the sign() method.
255
256         A sign of 'NaN' is used to represent the result when input arguments
257         are not numbers or as a result of 0/0. '+inf' and '-inf' represent
258         plus respectively minus infinity. You will get '+inf' when dividing a
259         positive number by 0, and '-inf' when dividing any negative number by
260         0.
261

MODULES USED

263       "bignum" is just a thin wrapper around various modules of the
264       Math::BigInt family. Think of it as the head of the family, who runs
265       the shop, and orders the others to do the work.
266
267       The following modules are currently used by bignum:
268
269               Math::BigInt::Lite      (for speed, and only if it is loadable)
270               Math::BigInt
271               Math::BigFloat
272

EXAMPLES

274       Some cool command line examples to impress the Python crowd ;)
275
276               perl -Mbignum -le 'print sqrt(33)'
277               perl -Mbignum -le 'print 2*255'
278               perl -Mbignum -le 'print 4.5+2*255'
279               perl -Mbignum -le 'print 3/7 + 5/7 + 8/3'
280               perl -Mbignum -le 'print 123->is_odd()'
281               perl -Mbignum -le 'print log(2)'
282               perl -Mbignum -le 'print 2 ** 0.5'
283               perl -Mbignum=a,65 -le 'print 2 ** 0.2'
284

LICENSE

286       This program is free software; you may redistribute it and/or modify it
287       under the same terms as Perl itself.
288

AUTHORS

296       (C) by Tels <http://bloodgate.com/> in early 2002, 2003.
297
298
299
300perl v5.8.8                       2001-09-21                       bignum(3pm)