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