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