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