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