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