This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Upgrade bignum from version 0.42 to 0.43
[perl5.git] / cpan / bignum / lib / bigint.pm
CommitLineData
126f3c5f 1package bigint;
91f07087 2
9de9b613 3use 5.006;
91f07087
SH
4use strict;
5use warnings;
6
fb7f2fa3 7our $VERSION = '0.43';
126f3c5f 8
126f3c5f 9use Exporter;
91f07087
SH
10our @ISA = qw( Exporter );
11our @EXPORT_OK = qw( PI e bpi bexp hex oct );
12our @EXPORT = qw( inf NaN );
126f3c5f 13
126f3c5f
JH
14use overload;
15
56e812ab 16##############################################################################
126f3c5f
JH
17
18# These are all alike, and thus faked by AUTOLOAD
19
20my @faked = qw/round_mode accuracy precision div_scale/;
91f07087 21our ($AUTOLOAD, $_lite); # _lite for testsuite
56e812ab
PJA
22
23sub AUTOLOAD {
24 my $name = $AUTOLOAD;
25
26 $name =~ s/.*:://; # split package
27 no strict 'refs';
28 foreach my $n (@faked) {
29 if ($n eq $name) {
30 *{"bigint::$name"} =
31 sub {
32 my $self = shift;
33 no strict 'refs';
34 if (defined $_[0]) {
35 return Math::BigInt->$name($_[0]);
36 }
37 return Math::BigInt->$name();
38 };
39 return &$name;
40 }
126f3c5f 41 }
126f3c5f 42
56e812ab
PJA
43 # delayed load of Carp and avoid recursion
44 require Carp;
45 Carp::croak ("Can't call bigint\-\>$name, not a valid method");
46}
126f3c5f 47
56e812ab
PJA
48sub upgrade {
49 $Math::BigInt::upgrade;
50}
95a2d02c 51
56e812ab
PJA
52sub _binary_constant {
53 # this takes a binary/hexadecimal/octal constant string and returns it
54 # as string suitable for new. Basically it converts octal to decimal, and
55 # passes every thing else unmodified back.
56 my $string = shift;
95a2d02c 57
56e812ab 58 return Math::BigInt->new($string) if $string =~ /^0[bx]/;
95a2d02c 59
56e812ab
PJA
60 # so it must be an octal constant
61 Math::BigInt->from_oct($string);
62}
63
64sub _float_constant {
65 # this takes a floating point constant string and returns it truncated to
66 # integer. For instance, '4.5' => '4', '1.234e2' => '123' etc
67 my $float = shift;
68
69 # some simple cases first
70 return $float if ($float =~ /^[+-]?[0-9]+$/); # '+123','-1','0' etc
71 return $float
72 if ($float =~ /^[+-]?[0-9]+\.?[eE]\+?[0-9]+$/); # 123e2, 123.e+2
73 return '0' if ($float =~ /^[+-]?[0]*\.[0-9]+$/); # .2, 0.2, -.1
74 if ($float =~ /^[+-]?[0-9]+\.[0-9]*$/) { # 1., 1.23, -1.2 etc
75 $float =~ s/\..*//;
76 return $float;
126f3c5f 77 }
56e812ab
PJA
78 my ($mis, $miv, $mfv, $es, $ev) = Math::BigInt::_split($float);
79 return $float if !defined $mis; # doesn't look like a number to me
80 my $ec = int($$ev);
81 my $sign = $$mis;
82 $sign = '' if $sign eq '+';
83 if ($$es eq '-') {
84 # ignore fraction part entirely
85 if ($ec >= length($$miv)) { # 123.23E-4
86 return '0';
87 }
88 return $sign . substr($$miv, 0, length($$miv) - $ec); # 1234.45E-2 = 12
126f3c5f 89 }
56e812ab
PJA
90 # xE+y
91 if ($ec >= length($$mfv)) {
92 $ec -= length($$mfv);
93 return $sign.$$miv.$$mfv if $ec == 0; # 123.45E+2 => 12345
94 return $sign.$$miv.$$mfv.'E'.$ec; # 123.45e+3 => 12345e1
126f3c5f 95 }
56e812ab
PJA
96 $mfv = substr($$mfv, 0, $ec);
97 $sign.$$miv.$mfv; # 123.45e+1 => 1234
98}
126f3c5f 99
56e812ab
PJA
100sub unimport {
101 $^H{bigint} = undef; # no longer in effect
102 overload::remove_constant('binary', '', 'float', '', 'integer');
103}
4440d13a 104
56e812ab
PJA
105sub in_effect {
106 my $level = shift || 0;
107 my $hinthash = (caller($level))[10];
108 $hinthash->{bigint};
109}
4440d13a 110
d1a15766
T
111#############################################################################
112# the following two routines are for "use bigint qw/hex oct/;":
113
9663a7f5
FC
114use constant LEXICAL => $] > 5.009004;
115
c6824fe7
SH
116# Internal function with the same semantics as CORE::hex(). This function is
117# not used directly, but rather by other front-end functions.
118
119sub _hex_core {
120 my $str = shift;
121
122 # Strip off, clean, and parse as much as we can from the beginning.
123
124 my $x;
125 if ($str =~ s/ ^ (0?[xX])? ( [0-9a-fA-F]* ( _ [0-9a-fA-F]+ )* ) //x) {
126 my $chrs = $2;
127 $chrs =~ tr/_//d;
128 $chrs = '0' unless CORE::length $chrs;
129 $x = Math::BigInt -> from_hex($chrs);
130 } else {
131 $x = Math::BigInt -> bzero();
132 }
133
134 # Warn about trailing garbage.
135
136 if (CORE::length($str)) {
137 require Carp;
138 Carp::carp(sprintf("Illegal hexadecimal digit '%s' ignored",
139 substr($str, 0, 1)));
140 }
141
142 return $x;
143}
144
145# Internal function with the same semantics as CORE::oct(). This function is
146# not used directly, but rather by other front-end functions.
147
148sub _oct_core {
149 my $str = shift;
150
151 $str =~ s/^\s*//;
152
153 # Hexadecimal input.
154
155 return _hex_core($str) if $str =~ /^0?[xX]/;
156
157 my $x;
158
159 # Binary input.
160
161 if ($str =~ /^0?[bB]/) {
162
163 # Strip off, clean, and parse as much as we can from the beginning.
164
165 if ($str =~ s/ ^ (0?[bB])? ( [01]* ( _ [01]+ )* ) //x) {
166 my $chrs = $2;
167 $chrs =~ tr/_//d;
168 $chrs = '0' unless CORE::length $chrs;
169 $x = Math::BigInt -> from_bin($chrs);
170 }
171
172 # Warn about trailing garbage.
173
174 if (CORE::length($str)) {
175 require Carp;
176 Carp::carp(sprintf("Illegal binary digit '%s' ignored",
177 substr($str, 0, 1)));
178 }
179
180 return $x;
181 }
182
183 # Octal input. Strip off, clean, and parse as much as we can from the
184 # beginning.
185
186 if ($str =~ s/ ^ ( [0-7]* ( _ [0-7]+ )* ) //x) {
187 my $chrs = $1;
188 $chrs =~ tr/_//d;
189 $chrs = '0' unless CORE::length $chrs;
190 $x = Math::BigInt -> from_oct($chrs);
191 }
192
193 # Warn about trailing garbage. CORE::oct() only warns about 8 and 9.
194
195 if (CORE::length($str)) {
196 my $chr = substr($str, 0, 1);
197 if ($chr eq '8' || $chr eq '9') {
198 require Carp;
199 Carp::carp(sprintf("Illegal octal digit '%s' ignored", $chr));
200 }
201 }
202
203 return $x;
204}
205
9663a7f5
FC
206{
207 my $proto = LEXICAL ? '_' : ';$';
208 eval '
56e812ab 209sub hex(' . $proto . ') {' . <<'.';
c6824fe7
SH
210 my $str = @_ ? $_[0] : $_;
211 _hex_core($str);
56e812ab 212}
9663a7f5 213.
c6824fe7 214
9663a7f5 215 eval '
56e812ab 216sub oct(' . $proto . ') {' . <<'.';
c6824fe7
SH
217 my $str = @_ ? $_[0] : $_;
218 _oct_core($str);
56e812ab 219}
9663a7f5
FC
220.
221}
d1a15766
T
222
223#############################################################################
224# the following two routines are for Perl 5.9.4 or later and are lexical
225
9663a7f5
FC
226my ($prev_oct, $prev_hex, $overridden);
227
228if (LEXICAL) { eval <<'.' }
56e812ab
PJA
229sub _hex(_) {
230 my $hh = (caller 0)[10];
231 return $prev_hex ? &$prev_hex($_[0]) : CORE::hex($_[0])
232 unless $$hh{bigint}||$$hh{bignum}||$$hh{bigrat};
c6824fe7 233 _hex_core($_[0]);
56e812ab 234}
d1a15766 235
56e812ab
PJA
236sub _oct(_) {
237 my $hh = (caller 0)[10];
238 return $prev_oct ? &$prev_oct($_[0]) : CORE::oct($_[0])
239 unless $$hh{bigint}||$$hh{bignum}||$$hh{bigrat};
c6824fe7 240 _oct_core($_[0]);
56e812ab 241}
9663a7f5
FC
242.
243
56e812ab
PJA
244sub _override {
245 return if $overridden;
246 $prev_oct = *CORE::GLOBAL::oct{CODE};
247 $prev_hex = *CORE::GLOBAL::hex{CODE};
248 no warnings 'redefine';
249 *CORE::GLOBAL::oct = \&_oct;
250 *CORE::GLOBAL::hex = \&_hex;
251 $overridden++;
252}
d1a15766 253
56e812ab
PJA
254sub import {
255 my $self = shift;
126f3c5f 256
56e812ab 257 $^H{bigint} = 1; # we are in effect
4440d13a 258
56e812ab
PJA
259 # for newer Perls always override hex() and oct() with a lexical version:
260 if (LEXICAL) {
261 _override();
d1a15766 262 }
56e812ab
PJA
263 # some defaults
264 my $lib = '';
265 my $lib_kind = 'try';
266
267 my @import = (':constant'); # drive it w/ constant
268 my @a = @_;
269 my $l = scalar @_;
270 my $j = 0;
271 my ($ver, $trace); # version? trace?
272 my ($a, $p); # accuracy, precision
273 for (my $i = 0; $i < $l; $i++, $j++) {
274 if ($_[$i] =~ /^(l|lib|try|only)$/) {
275 # this causes a different low lib to take care...
276 $lib_kind = $1;
277 $lib_kind = 'lib' if $lib_kind eq 'l';
278 $lib = $_[$i + 1] || '';
279 my $s = 2;
280 $s = 1 if @a - $j < 2; # avoid "can not modify non-existent..."
281 splice @a, $j, $s;
282 $j -= $s;
283 $i++;
284 } elsif ($_[$i] =~ /^(a|accuracy)$/) {
285 $a = $_[$i + 1];
286 my $s = 2;
287 $s = 1 if @a - $j < 2; # avoid "can not modify non-existent..."
288 splice @a, $j, $s;
289 $j -= $s;
290 $i++;
291 } elsif ($_[$i] =~ /^(p|precision)$/) {
292 $p = $_[$i + 1];
293 my $s = 2;
294 $s = 1 if @a - $j < 2; # avoid "can not modify non-existent..."
295 splice @a, $j, $s;
296 $j -= $s;
297 $i++;
298 } elsif ($_[$i] =~ /^(v|version)$/) {
299 $ver = 1;
300 splice @a, $j, 1;
301 $j--;
302 } elsif ($_[$i] =~ /^(t|trace)$/) {
303 $trace = 1;
304 splice @a, $j, 1;
305 $j--;
306 } elsif ($_[$i] !~ /^(PI|e|bpi|bexp|hex|oct)\z/) {
307 die ("unknown option $_[$i]");
308 }
126f3c5f 309 }
56e812ab
PJA
310 my $class;
311 $_lite = 0; # using M::BI::L ?
312 if ($trace) {
313 require Math::BigInt::Trace;
314 $class = 'Math::BigInt::Trace';
315 } else {
316 # see if we can find Math::BigInt::Lite
317 if (!defined $a && !defined $p) { # rounding won't work to well
318 if (eval { require Math::BigInt::Lite; 1 }) {
319 @import = (); # :constant in Lite, not MBI
320 Math::BigInt::Lite->import(':constant');
321 $_lite = 1; # signal okay
322 }
126f3c5f 323 }
56e812ab
PJA
324 require Math::BigInt if $_lite == 0; # not already loaded?
325 $class = 'Math::BigInt'; # regardless of MBIL or not
233f7bc0 326 }
56e812ab
PJA
327 push @import, $lib_kind => $lib if $lib ne '';
328 # Math::BigInt::Trace or plain Math::BigInt
329 $class->import(@import);
330
331 bigint->accuracy($a) if defined $a;
332 bigint->precision($p) if defined $p;
333 if ($ver) {
334 print "bigint\t\t\t v$VERSION\n";
335 print "Math::BigInt::Lite\t v$Math::BigInt::Lite::VERSION\n" if $_lite;
336 print "Math::BigInt\t\t v$Math::BigInt::VERSION";
337 my $config = Math::BigInt->config();
338 print " lib => $config->{lib} v$config->{lib_version}\n";
339 exit;
126f3c5f 340 }
56e812ab
PJA
341 # we take care of floating point constants, since BigFloat isn't available
342 # and BigInt doesn't like them:
343 overload::constant float =>
344 sub {
345 Math::BigInt->new(_float_constant(shift));
346 };
347 # Take care of octal/hexadecimal constants
348 overload::constant binary =>
349 sub {
350 _binary_constant(shift);
351 };
352
353 # if another big* was already loaded:
354 my ($package) = caller();
355
356 no strict 'refs';
357 if (!defined *{"${package}::inf"}) {
358 $self->export_to_level(1, $self, @a); # export inf and NaN, e and PI
4440d13a 359 }
56e812ab 360}
126f3c5f 361
fb7f2fa3
SH
362sub inf () { Math::BigInt->binf(); }
363sub NaN () { Math::BigInt->bnan(); }
d98d5fa0
T
364
365sub PI () { Math::BigInt->new(3); }
366sub e () { Math::BigInt->new(2); }
367sub bpi ($) { Math::BigInt->new(3); }
56e812ab
PJA
368sub bexp ($$) {
369 my $x = Math::BigInt->new($_[0]);
370 $x->bexp($_[1]);
371}
b4bc5691 372
126f3c5f
JH
3731;
374
375__END__
376
91f07087
SH
377=pod
378
126f3c5f
JH
379=head1 NAME
380
b4bc5691 381bigint - Transparent BigInteger support for Perl
126f3c5f
JH
382
383=head1 SYNOPSIS
384
f9156151 385 use bigint;
126f3c5f 386
56e812ab
PJA
387 $x = 2 + 4.5,"\n"; # BigInt 6
388 print 2 ** 512,"\n"; # really is what you think it is
389 print inf + 42,"\n"; # inf
390 print NaN * 7,"\n"; # NaN
391 print hex("0x1234567890123490"),"\n"; # Perl v5.10.0 or later
126f3c5f 392
4440d13a
T
393 {
394 no bigint;
56e812ab 395 print 2 ** 256,"\n"; # a normal Perl scalar now
4440d13a
T
396 }
397
9663a7f5 398 # Import into current package:
d1a15766
T
399 use bigint qw/hex oct/;
400 print hex("0x1234567890123490"),"\n";
401 print oct("01234567890123490"),"\n";
402
126f3c5f
JH
403=head1 DESCRIPTION
404
45e230de
ML
405All operators (including basic math operations) except the range operator C<..>
406are overloaded. Integer constants are created as proper BigInts.
126f3c5f 407
1ad2138d
T
408Floating point constants are truncated to integer. All parts and results of
409expressions are also truncated.
410
411Unlike L<integer>, this pragma creates integer constants that are only
412limited in their size by the available memory and CPU time.
413
414=head2 use integer vs. use bigint
415
416There is one small difference between C<use integer> and C<use bigint>: the
417former will not affect assignments to variables and the return value of
418some functions. C<bigint> truncates these results to integer too:
419
56e812ab
PJA
420 # perl -Minteger -wle 'print 3.2'
421 3.2
422 # perl -Minteger -wle 'print 3.2 + 0'
423 3
424 # perl -Mbigint -wle 'print 3.2'
425 3
426 # perl -Mbigint -wle 'print 3.2 + 0'
427 3
428
429 # perl -Mbigint -wle 'print exp(1) + 0'
430 2
431 # perl -Mbigint -wle 'print exp(1)'
432 2
433 # perl -Minteger -wle 'print exp(1)'
434 2.71828182845905
435 # perl -Minteger -wle 'print exp(1) + 0'
436 2
1ad2138d
T
437
438In practice this makes seldom a difference as B<parts and results> of
439expressions will be truncated anyway, but this can, for instance, affect the
440return value of subroutines:
441
56e812ab 442 sub three_integer { use integer; return 3.2; }
ba048c24 443 sub three_bigint { use bigint; return 3.2; }
f703fc96 444
56e812ab 445 print three_integer(), " ", three_bigint(),"\n"; # prints "3.2 3"
126f3c5f 446
b68b7ab1 447=head2 Options
126f3c5f
JH
448
449bigint recognizes some options that can be passed while loading it via use.
450The options can (currently) be either a single letter form, or the long form.
451The following options exist:
452
453=over 2
454
455=item a or accuracy
456
457This sets the accuracy for all math operations. The argument must be greater
458than or equal to zero. See Math::BigInt's bround() function for details.
459
56e812ab 460 perl -Mbigint=a,2 -le 'print 12345+1'
126f3c5f 461
c4a6f826 462Note that setting precision and accuracy at the same time is not possible.
95a2d02c 463
126f3c5f
JH
464=item p or precision
465
466This sets the precision for all math operations. The argument can be any
467integer. Negative values mean a fixed number of digits after the dot, and
468are <B>ignored</B> since all operations happen in integer space.
469A positive value rounds to this digit left from the dot. 0 or 1 mean round to
470integer and are ignore like negative values.
471
472See Math::BigInt's bfround() function for details.
473
56e812ab 474 perl -Mbignum=p,5 -le 'print 123456789+123'
126f3c5f 475
c4a6f826 476Note that setting precision and accuracy at the same time is not possible.
95a2d02c 477
126f3c5f
JH
478=item t or trace
479
480This enables a trace mode and is primarily for debugging bigint or
481Math::BigInt.
482
d1a15766
T
483=item hex
484
43cde5e1 485Override the built-in hex() method with a version that can handle big
9663a7f5
FC
486integers. This overrides it by exporting it to the current package. Under
487Perl v5.10.0 and higher, this is not so necessary, as hex() is lexically
488overridden in the current scope whenever the bigint pragma is active.
d1a15766
T
489
490=item oct
491
43cde5e1 492Override the built-in oct() method with a version that can handle big
9663a7f5
FC
493integers. This overrides it by exporting it to the current package. Under
494Perl v5.10.0 and higher, this is not so necessary, as oct() is lexically
495overridden in the current scope whenever the bigint pragma is active.
d1a15766 496
bd49aa09 497=item l, lib, try or only
126f3c5f 498
bd49aa09 499Load a different math lib, see L<Math Library>.
126f3c5f 500
56e812ab
PJA
501 perl -Mbigint=lib,GMP -e 'print 2 ** 512'
502 perl -Mbigint=try,GMP -e 'print 2 ** 512'
503 perl -Mbigint=only,GMP -e 'print 2 ** 512'
126f3c5f
JH
504
505Currently there is no way to specify more than one library on the command
95a2d02c
T
506line. This means the following does not work:
507
56e812ab 508 perl -Mbignum=l,GMP,Pari -e 'print 2 ** 512'
95a2d02c
T
509
510This will be hopefully fixed soon ;)
126f3c5f
JH
511
512=item v or version
513
514This prints out the name and version of all modules used and then exits.
515
56e812ab 516 perl -Mbigint=v
126f3c5f 517
95a2d02c
T
518=back
519
b68b7ab1 520=head2 Math Library
126f3c5f
JH
521
522Math with the numbers is done (by default) by a module called
523Math::BigInt::Calc. This is equivalent to saying:
524
56e812ab 525 use bigint lib => 'Calc';
126f3c5f
JH
526
527You can change this by using:
528
56e812ab 529 use bignum lib => 'GMP';
126f3c5f
JH
530
531The following would first try to find Math::BigInt::Foo, then
532Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:
533
56e812ab 534 use bigint lib => 'Foo,Math::BigInt::Bar';
126f3c5f 535
bd49aa09
SP
536Using C<lib> warns if none of the specified libraries can be found and
537L<Math::BigInt> did fall back to one of the default libraries.
c4a6f826 538To suppress this warning, use C<try> instead:
bd49aa09
SP
539
540 use bignum try => 'GMP';
541
542If you want the code to die instead of falling back, use C<only> instead:
543
544 use bignum only => 'GMP';
545
126f3c5f
JH
546Please see respective module documentation for further details.
547
b68b7ab1 548=head2 Internal Format
126f3c5f
JH
549
550The numbers are stored as objects, and their internals might change at anytime,
551especially between math operations. The objects also might belong to different
552classes, like Math::BigInt, or Math::BigInt::Lite. Mixing them together, even
553with normal scalars is not extraordinary, but normal and expected.
554
555You should not depend on the internal format, all accesses must go through
990fb837 556accessor methods. E.g. looking at $x->{sign} is not a good idea since there
126f3c5f
JH
557is no guaranty that the object in question has such a hash key, nor is a hash
558underneath at all.
559
b68b7ab1 560=head2 Sign
126f3c5f 561
b68b7ab1 562The sign is either '+', '-', 'NaN', '+inf' or '-inf'.
126f3c5f
JH
563You can access it with the sign() method.
564
565A sign of 'NaN' is used to represent the result when input arguments are not
566numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively
567minus infinity. You will get '+inf' when dividing a positive number by 0, and
568'-inf' when dividing any negative number by 0.
569
a7a0833f 570=head2 Method calls
126f3c5f
JH
571
572Since all numbers are now objects, you can use all functions that are part of
573the BigInt API. You can only use the bxxx() notation, and not the fxxx()
56e812ab 574notation, though.
126f3c5f 575
a7a0833f
HS
576But a warning is in order. When using the following to make a copy of a number,
577only a shallow copy will be made.
578
56e812ab
PJA
579 $x = 9; $y = $x;
580 $x = $y = 7;
a7a0833f
HS
581
582Using the copy or the original with overloaded math is okay, e.g. the
583following work:
584
56e812ab
PJA
585 $x = 9; $y = $x;
586 print $x + 1, " ", $y,"\n"; # prints 10 9
a7a0833f
HS
587
588but calling any method that modifies the number directly will result in
589B<both> the original and the copy being destroyed:
590
56e812ab
PJA
591 $x = 9; $y = $x;
592 print $x->badd(1), " ", $y,"\n"; # prints 10 10
a7a0833f 593
56e812ab
PJA
594 $x = 9; $y = $x;
595 print $x->binc(1), " ", $y,"\n"; # prints 10 10
a7a0833f 596
56e812ab
PJA
597 $x = 9; $y = $x;
598 print $x->bmul(2), " ", $y,"\n"; # prints 18 18
a7a0833f 599
dbeba1b0 600Using methods that do not modify, but test that the contents works:
a7a0833f 601
56e812ab
PJA
602 $x = 9; $y = $x;
603 $z = 9 if $x->is_zero(); # works fine
a7a0833f
HS
604
605See the documentation about the copy constructor and C<=> in overload, as
606well as the documentation in BigInt for further details.
607
608=head2 Methods
609
95a2d02c
T
610=over 2
611
612=item inf()
613
614A shortcut to return Math::BigInt->binf(). Useful because Perl does not always
615handle bareword C<inf> properly.
616
617=item NaN()
618
619A shortcut to return Math::BigInt->bnan(). Useful because Perl does not always
620handle bareword C<NaN> properly.
621
d98d5fa0
T
622=item e
623
56e812ab 624 # perl -Mbigint=e -wle 'print e'
d98d5fa0
T
625
626Returns Euler's number C<e>, aka exp(1). Note that under bigint, this is
627truncated to an integer, and hence simple '2'.
628
629=item PI
630
56e812ab 631 # perl -Mbigint=PI -wle 'print PI'
d98d5fa0
T
632
633Returns PI. Note that under bigint, this is truncated to an integer, and hence
634simple '3'.
635
636=item bexp()
637
56e812ab 638 bexp($power,$accuracy);
d98d5fa0
T
639
640Returns Euler's number C<e> raised to the appropriate power, to
641the wanted accuracy.
642
643Note that under bigint, the result is truncated to an integer.
644
645Example:
646
56e812ab 647 # perl -Mbigint=bexp -wle 'print bexp(1,80)'
d98d5fa0
T
648
649=item bpi()
650
56e812ab 651 bpi($accuracy);
fade31f0 652
d98d5fa0
T
653Returns PI to the wanted accuracy. Note that under bigint, this is truncated
654to an integer, and hence simple '3'.
fade31f0 655
d98d5fa0 656Example:
fade31f0 657
56e812ab 658 # perl -Mbigint=bpi -wle 'print bpi(80)'
fade31f0 659
95a2d02c
T
660=item upgrade()
661
662Return the class that numbers are upgraded to, is in fact returning
663C<$Math::BigInt::upgrade>.
664
4440d13a
T
665=item in_effect()
666
56e812ab 667 use bigint;
4440d13a 668
56e812ab
PJA
669 print "in effect\n" if bigint::in_effect; # true
670 {
671 no bigint;
672 print "in effect\n" if bigint::in_effect; # false
673 }
4440d13a
T
674
675Returns true or false if C<bigint> is in effect in the current scope.
676
677This method only works on Perl v5.9.4 or later.
678
95a2d02c
T
679=back
680
7ed767c4 681=head1 CAVEATS
d1a15766
T
682
683=over 2
684
fa7b7678
TC
685=item Operator vs literal overloading
686
687C<bigint> works by overloading handling of integer and floating point
688literals, converting them to L<Math::BigInt> objects.
689
690This means that arithmetic involving only string values or string
691literals will be performed using Perl's built-in operators.
692
693For example:
694
695 use bignum;
696 my $x = "900000000000000009";
697 my $y = "900000000000000007";
698 print $x - $y;
699
700will output C<0> on default 32-bit builds, since C<bigint> never sees
701the string literals. To ensure the expression is all treated as
702C<Math::BigInt> objects, use a literal number in the expression:
703
704 print +(0+$x) - $y;
705
45e230de
ML
706=item ranges
707
708Perl does not allow overloading of ranges, so you can neither safely use
709ranges with bigint endpoints, nor is the iterator variable a bigint.
710
56e812ab
PJA
711 use 5.010;
712 for my $i (12..13) {
713 for my $j (20..21) {
714 say $i ** $j; # produces a floating-point number,
715 # not a big integer
716 }
717 }
45e230de 718
d1a15766
T
719=item in_effect()
720
721This method only works on Perl v5.9.4 or later.
722
723=item hex()/oct()
724
725C<bigint> overrides these routines with versions that can also handle
726big integer values. Under Perl prior to version v5.9.4, however, this
727will not happen unless you specifically ask for it with the two
728import tags "hex" and "oct" - and then it will be global and cannot be
729disabled inside a scope with "no bigint":
730
56e812ab 731 use bigint qw/hex oct/;
d1a15766 732
56e812ab
PJA
733 print hex("0x1234567890123456");
734 {
735 no bigint;
736 print hex("0x1234567890123456");
737 }
d1a15766
T
738
739The second call to hex() will warn about a non-portable constant.
740
741Compare this to:
742
56e812ab 743 use bigint;
d1a15766 744
56e812ab
PJA
745 # will warn only under Perl older than v5.9.4
746 print hex("0x1234567890123456");
d1a15766
T
747
748=back
749
126f3c5f
JH
750=head1 MODULES USED
751
752C<bigint> is just a thin wrapper around various modules of the Math::BigInt
753family. Think of it as the head of the family, who runs the shop, and orders
754the others to do the work.
755
756The following modules are currently used by bigint:
757
56e812ab
PJA
758 Math::BigInt::Lite (for speed, and only if it is loadable)
759 Math::BigInt
126f3c5f
JH
760
761=head1 EXAMPLES
762
763Some cool command line examples to impress the Python crowd ;) You might want
764to compare them to the results under -Mbignum or -Mbigrat:
f703fc96 765
56e812ab
PJA
766 perl -Mbigint -le 'print sqrt(33)'
767 perl -Mbigint -le 'print 2*255'
768 perl -Mbigint -le 'print 4.5+2*255'
769 perl -Mbigint -le 'print 3/7 + 5/7 + 8/3'
770 perl -Mbigint -le 'print 123->is_odd()'
771 perl -Mbigint -le 'print log(2)'
772 perl -Mbigint -le 'print 2 ** 0.5'
773 perl -Mbigint=a,65 -le 'print 2 ** 0.2'
774 perl -Mbignum=a,65,l,GMP -le 'print 7 ** 7777'
126f3c5f
JH
775
776=head1 LICENSE
777
778This program is free software; you may redistribute it and/or modify it under
779the same terms as Perl itself.
780
781=head1 SEE ALSO
782
783Especially L<bigrat> as in C<perl -Mbigrat -le 'print 1/3+1/4'> and
784L<bignum> as in C<perl -Mbignum -le 'print sqrt(2)'>.
785
786L<Math::BigInt>, L<Math::BigRat> and L<Math::Big> as well
326f3c9d 787as L<Math::BigInt::Pari> and L<Math::BigInt::GMP>.
126f3c5f
JH
788
789=head1 AUTHORS
790
95a2d02c 791(C) by Tels L<http://bloodgate.com/> in early 2002 - 2007.
126f3c5f
JH
792
793=cut