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