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