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