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