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

NAME

6       bignum - transparent big number support for Perl
7

SYNOPSIS

9           use bignum;
10
11           $x = 2 + 4.5;                       # Math::BigFloat 6.5
12           print 2 ** 512 * 0.1;               # Math::BigFloat 134...09.6
13           print 2 ** 512;                     # Math::BigInt 134...096
14           print inf + 42;                     # Math::BigInt inf
15           print NaN * 7;                      # Math::BigInt NaN
16           print hex("0x1234567890123490");    # Perl v5.10.0 or later
17
18           {
19               no bignum;
20               print 2 ** 256;                 # a normal Perl scalar now
21           }
22
23           # for older Perls, import into current package:
24           use bignum qw/hex oct/;
25           print hex("0x1234567890123490");
26           print oct("01234567890123490");
27

DESCRIPTION

29   Literal numeric constants
30       By default, every literal integer becomes a Math::BigInt object, and
31       literal non-integer becomes a Math::BigFloat object. Whether a numeric
32       literal is considered an integer or non-integers depends only on the
33       value of the constant, not on how it is represented. For instance, the
34       constants 3.14e2 and 0x1.3ap8 become Math::BigInt objects, because they
35       both represent the integer value decimal 314.
36
37       The default "use bignum;" is equivalent to
38
39           use bignum downgrade => "Math::BigInt", upgrade => "Math::BigFloat";
40
41       The classes used for integers and non-integers can be set at compile
42       time with the "downgrade" and "upgrade" options, for example
43
44           # use Math::BigInt for integers and Math::BigRat for non-integers
45           use bignum upgrade => "Math::BigRat";
46
47       Note that disabling downgrading and upgrading does not affect how
48       numeric literals are converted to objects
49
50           # disable both downgrading and upgrading
51           use bignum downgrade => undef, upgrade => undef;
52           $x = 2.4;       # becomes 2.4 as a Math::BigFloat
53           $y = 2;         # becomes 2 as a Math::BigInt
54
55   Upgrading and downgrading
56       By default, when the result of a computation is an integer, an Inf, or
57       a NaN, the result is downgraded even when all the operands are
58       instances of the upgrade class.
59
60           use bignum;
61           $x = 2.4;       # becomes 2.4 as a Math::BigFloat
62           $y = 1.2;       # becomes 1.2 as a Math::BigFloat
63           $z = $x / $y;   # becomes 2 as a Math::BigInt due to downgrading
64
65       Equivalently, by default, when the result of a computation is a finite
66       non-integer, the result is upgraded even when all the operands are
67       instances of the downgrade class.
68
69           use bignum;
70           $x = 7;         # becomes 7 as a Math::BigInt
71           $y = 2;         # becomes 2 as a Math::BigInt
72           $z = $x / $y;   # becomes 3.5 as a Math::BigFloat due to upgrading
73
74       The classes used for downgrading and upgrading can be set at runtime
75       with the "downgrade()" and "upgrade()" methods, but see "CAVEATS"
76       below.
77
78       The upgrade and downgrade classes don't have to be Math::BigInt and
79       Math::BigFloat. For example, to use Math::BigRat as the upgrade class,
80       use
81
82           use bignum upgrade => "Math::BigRat";
83           $x = 2;         # becomes 2 as a Math::BigInt
84           $y = 3.6;       # becomes 18/5 as a Math::BigRat
85
86       The upgrade and downgrade classes can be modified at runtime
87
88           use bignum;
89           $x = 3;         # becomes 3 as a Math::BigInt
90           $y = 2;         # becomes 2 as a Math::BigInt
91           $z = $x / $y;   # becomes 1.5 as a Math::BigFlaot
92
93           bignum -> upgrade("Math::BigRat");
94           $w = $x / $y;   # becomes 3/2 as a Math::BigRat
95
96       Disabling downgrading doesn't change the fact that literal constant
97       integers are converted to the downgrade class, it only prevents
98       downgrading as a result of a computation. E.g.,
99
100           use bignum downgrade => undef;
101           $x = 2;         # becomes 2 as a Math::BigInt
102           $y = 2.4;       # becomes 2.4 as a Math::BigFloat
103           $z = 1.2;       # becomes 1.2 as a Math::BigFloat
104           $w = $x / $y;   # becomes 2 as a Math::BigFloat due to no downgrading
105
106       If you want all numeric literals, both integers and non-integers, to
107       become Math::BigFloat objects, use the bigfloat pragma.
108
109       Equivalently, disabling upgrading doesn't change the fact that literal
110       constant non-integers are converted to the upgrade class, it only
111       prevents upgrading as a result of a computation. E.g.,
112
113           use bignum upgrade => undef;
114           $x = 2.5;       # becomes 2.5 as a Math::BigFloat
115           $y = 7;         # becomes 7 as a Math::BigInt
116           $z = 2;         # becomes 2 as a Math::BigInt
117           $w = $x / $y;   # becomes 3 as a Math::BigInt due to no upgrading
118
119       If you want all numeric literals, both integers and non-integers, to
120       become Math::BigInt objects, use the bigint pragma.
121
122       You can even do
123
124           use bignum upgrade => "Math::BigRat", upgrade => undef;
125
126       which converts all integer literals to Math::BigInt objects and all
127       non-integer literals to Math::BigRat objects. However, when the result
128       of a computation involving two Math::BigInt objects results in a non-
129       integer (e.g., 7/2), the result will be truncted to a Math::BigInt
130       rather than being upgraded to a Math::BigRat, since upgrading is
131       disabled.
132
133   Overloading
134       Since all numeric literals become objects, you can call all the usual
135       methods from Math::BigInt and Math::BigFloat on them. This even works
136       to some extent on expressions:
137
138           perl -Mbignum -le '$x = 1234; print $x->bdec()'
139           perl -Mbignum -le 'print 1234->copy()->binc();'
140           perl -Mbignum -le 'print 1234->copy()->binc()->badd(6);'
141
142   Options
143       "bignum" recognizes some options that can be passed while loading it
144       via via "use". The following options exist:
145
146       a or accuracy
147           This sets the accuracy for all math operations. The argument must
148           be greater than or equal to zero. See Math::BigInt's bround()
149           method for details.
150
151               perl -Mbignum=a,50 -le 'print sqrt(20)'
152
153           Note that setting precision and accuracy at the same time is not
154           possible.
155
156       p or precision
157           This sets the precision for all math operations. The argument can
158           be any integer. Negative values mean a fixed number of digits after
159           the dot, while a positive value rounds to this digit left from the
160           dot. 0 means round to integer.  See Math::BigInt's bfround() method
161           for details.
162
163               perl -Mbignum=p,-50 -le 'print sqrt(20)'
164
165           Note that setting precision and accuracy at the same time is not
166           possible.
167
168       l, lib, try, or only
169           Load a different math lib, see "Math Library".
170
171               perl -Mbignum=l,GMP -e 'print 2 ** 512'
172               perl -Mbignum=lib,GMP -e 'print 2 ** 512'
173               perl -Mbignum=try,GMP -e 'print 2 ** 512'
174               perl -Mbignum=only,GMP -e 'print 2 ** 512'
175
176       hex Override the built-in hex() method with a version that can handle
177           big numbers.  This overrides it by exporting it to the current
178           package. Under Perl v5.10.0 and higher, this is not so necessary,
179           as hex() is lexically overridden in the current scope whenever the
180           "bignum" pragma is active.
181
182       oct Override the built-in oct() method with a version that can handle
183           big numbers.  This overrides it by exporting it to the current
184           package. Under Perl v5.10.0 and higher, this is not so necessary,
185           as oct() is lexically overridden in the current scope whenever the
186           "bignum" pragma is active.
187
188       v or version
189           this prints out the name and version of the modules and then exits.
190
191               perl -Mbignum=v
192
193   Math Library
194       Math with the numbers is done (by default) by a backend library module
195       called Math::BigInt::Calc. The default is equivalent to saying:
196
197           use bignum lib => 'Calc';
198
199       you can change this by using:
200
201           use bignum lib => 'GMP';
202
203       The following would first try to find Math::BigInt::Foo, then
204       Math::BigInt::Bar, and if this also fails, revert to
205       Math::BigInt::Calc:
206
207           use bignum lib => 'Foo,Math::BigInt::Bar';
208
209       Using c<lib> warns if none of the specified libraries can be found and
210       Math::BigInt and Math::BigFloat fell back to one of the default
211       libraries. To suppress this warning, use "try" instead:
212
213           use bignum try => 'GMP';
214
215       If you want the code to die instead of falling back, use "only"
216       instead:
217
218           use bignum only => 'GMP';
219
220       Please see respective module documentation for further details.
221
222   Method calls
223       Since all numbers are now objects, you can use the methods that are
224       part of the Math::BigInt and Math::BigFloat API.
225
226       But a warning is in order. When using the following to make a copy of a
227       number, only a shallow copy will be made.
228
229           $x = 9; $y = $x;
230           $x = $y = 7;
231
232       Using the copy or the original with overloaded math is okay, e.g., the
233       following work:
234
235           $x = 9; $y = $x;
236           print $x + 1, " ", $y,"\n";     # prints 10 9
237
238       but calling any method that modifies the number directly will result in
239       both the original and the copy being destroyed:
240
241           $x = 9; $y = $x;
242           print $x->badd(1), " ", $y,"\n";        # prints 10 10
243
244           $x = 9; $y = $x;
245           print $x->binc(1), " ", $y,"\n";        # prints 10 10
246
247           $x = 9; $y = $x;
248           print $x->bmul(2), " ", $y,"\n";        # prints 18 18
249
250       Using methods that do not modify, but test that the contents works:
251
252           $x = 9; $y = $x;
253           $z = 9 if $x->is_zero();                # works fine
254
255       See the documentation about the copy constructor and "=" in overload,
256       as well as the documentation in Math::BigFloat for further details.
257
258   Methods
259       inf()
260           A shortcut to return "inf" as an object. Useful because Perl does
261           not always handle bareword "inf" properly.
262
263       NaN()
264           A shortcut to return "NaN" as an object. Useful because Perl does
265           not always handle bareword "NaN" properly.
266
267       e
268               # perl -Mbignum=e -wle 'print e'
269
270           Returns Euler's number "e", aka exp(1) (= 2.7182818284...).
271
272       PI
273               # perl -Mbignum=PI -wle 'print PI'
274
275           Returns PI (= 3.1415926532..).
276
277       bexp()
278               bexp($power, $accuracy);
279
280           Returns Euler's number "e" raised to the appropriate power, to the
281           wanted accuracy.
282
283           Example:
284
285               # perl -Mbignum=bexp -wle 'print bexp(1,80)'
286
287       bpi()
288               bpi($accuracy);
289
290           Returns PI to the wanted accuracy.
291
292           Example:
293
294               # perl -Mbignum=bpi -wle 'print bpi(80)'
295
296       accuracy()
297           Set or get the accuracy.
298
299       precision()
300           Set or get the precision.
301
302       round_mode()
303           Set or get the rounding mode.
304
305       div_scale()
306           Set or get the division scale.
307
308       upgrade()
309           Set or get the class that the downgrade class upgrades to, if any.
310           Set the upgrade class to "undef" to disable upgrading. See
311           "/CAVEATS" below.
312
313       downgrade()
314           Set or get the class that the upgrade class downgrades to, if any.
315           Set the downgrade class to "undef" to disable upgrading. See
316           "CAVEATS" below.
317
318       in_effect()
319               use bignum;
320
321               print "in effect\n" if bignum::in_effect;       # true
322               {
323                   no bignum;
324                   print "in effect\n" if bignum::in_effect;   # false
325               }
326
327           Returns true or false if "bignum" is in effect in the current
328           scope.
329
330           This method only works on Perl v5.9.4 or later.
331

CAVEATS

333       The upgrade() and downgrade() methods
334           Note that setting both the upgrade and downgrade classes at runtime
335           with the "upgrade()" and "downgrade()" methods, might not do what
336           you expect:
337
338               # Assuming that downgrading and upgrading hasn't been modified so far, so
339               # the downgrade and upgrade classes are Math::BigInt and Math::BigFloat,
340               # respectively, the following sets the upgrade class to Math::BigRat, i.e.,
341               # makes Math::BigInt upgrade to Math::BigRat:
342
343               bignum -> upgrade("Math::BigRat");
344
345               # The following sets the downgrade class to Math::BigInt::Lite, i.e., makes
346               # the new upgrade class Math::BigRat downgrade to Math::BigInt::Lite
347
348               bignum -> downgrade("Math::BigInt::Lite");
349
350               # Note that at this point, it is still Math::BigInt, not Math::BigInt::Lite,
351               # that upgrades to Math::BigRat, so to get Math::BigInt::Lite to upgrade to
352               # Math::BigRat, we need to do the following (again):
353
354               bignum -> upgrade("Math::BigRat");
355
356           A simpler way to do this at runtime is to use import(),
357
358               bignum -> import(upgrade => "Math::BigRat",
359                                downgrade => "Math::BigInt::Lite");
360
361       Hexadecimal, octal, and binary floating point literals
362           Perl (and this module) accepts hexadecimal, octal, and binary
363           floating point literals, but use them with care with Perl versions
364           before v5.32.0, because some versions of Perl silently give the
365           wrong result.
366
367       Operator vs literal overloading
368           "bigrat" works by overloading handling of integer and floating
369           point literals, converting them to Math::BigRat objects.
370
371           This means that arithmetic involving only string values or string
372           literals are performed using Perl's built-in operators.
373
374           For example:
375
376               use bigrat;
377               my $x = "900000000000000009";
378               my $y = "900000000000000007";
379               print $x - $y;
380
381           outputs 0 on default 32-bit builds, since "bignum" never sees the
382           string literals. To ensure the expression is all treated as
383           "Math::BigFloat" objects, use a literal number in the expression:
384
385               print +(0+$x) - $y;
386
387       Ranges
388           Perl does not allow overloading of ranges, so you can neither
389           safely use ranges with "bignum" endpoints, nor is the iterator
390           variable a "Math::BigFloat".
391
392               use 5.010;
393               for my $i (12..13) {
394                 for my $j (20..21) {
395                   say $i ** $j;  # produces a floating-point number,
396                                  # not an object
397                 }
398               }
399
400       in_effect()
401           This method only works on Perl v5.9.4 or later.
402
403       hex()/oct()
404           "bignum" overrides these routines with versions that can also
405           handle big integer values. Under Perl prior to version v5.9.4,
406           however, this will not happen unless you specifically ask for it
407           with the two import tags "hex" and "oct" - and then it will be
408           global and cannot be disabled inside a scope with "no bignum":
409
410               use bignum qw/hex oct/;
411
412               print hex("0x1234567890123456");
413               {
414                   no bignum;
415                   print hex("0x1234567890123456");
416               }
417
418           The second call to hex() will warn about a non-portable constant.
419
420           Compare this to:
421
422               use bignum;
423
424               # will warn only under Perl older than v5.9.4
425               print hex("0x1234567890123456");
426

EXAMPLES

428       Some cool command line examples to impress the Python crowd ;)
429
430           perl -Mbignum -le 'print sqrt(33)'
431           perl -Mbignum -le 'print 2**255'
432           perl -Mbignum -le 'print 4.5+2**255'
433           perl -Mbignum -le 'print 3/7 + 5/7 + 8/3'
434           perl -Mbignum -le 'print 123->is_odd()'
435           perl -Mbignum -le 'print log(2)'
436           perl -Mbignum -le 'print exp(1)'
437           perl -Mbignum -le 'print 2 ** 0.5'
438           perl -Mbignum=a,65 -le 'print 2 ** 0.2'
439           perl -Mbignum=l,GMP -le 'print 7 ** 7777'
440

BUGS

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

SUPPORT

449       You can find documentation for this module with the perldoc command.
450
451           perldoc bignum
452
453       You can also look for information at:
454
455       •   GitHub
456
457           <https://github.com/pjacklam/p5-bignum>
458
459       •   RT: CPAN's request tracker
460
461           <https://rt.cpan.org/Dist/Display.html?Name=bignum>
462
463       •   MetaCPAN
464
465           <https://metacpan.org/release/bignum>
466
467       •   CPAN Testers Matrix
468
469           <http://matrix.cpantesters.org/?dist=bignum>
470
471       •   CPAN Ratings
472
473           <https://cpanratings.perl.org/dist/bignum>
474

LICENSE

476       This program is free software; you may redistribute it and/or modify it
477       under the same terms as Perl itself.
478

SEE ALSO

480       bigint and bigrat.
481
482       Math::BigInt, Math::BigFloat, Math::BigRat and Math::Big as well as
483       Math::BigInt::FastCalc, Math::BigInt::Pari and Math::BigInt::GMP.
484

AUTHORS

486       •   (C) by Tels <http://bloodgate.com/> in early 2002 - 2007.
487
488       •   Maintained by Peter John Acklam <pjacklam@gmail.com>, 2014-.
489
490
491
492perl v5.38.0                      2023-07-21                         bignum(3)
Impressum