RE: Combining UTF-16 output with :crlf is awkward
[perl.git] / lib / bigint.pm
1 package bigint;
2 require 5.005;
3
4 $VERSION = '0.07';
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   my $self = shift;
52   no strict 'refs';
53 #  if (defined $_[0])
54 #    {
55 #    $Math::BigInt::upgrade = $_[0];
56 #    }
57   return $Math::BigInt::upgrade;
58   }
59
60 sub _constant
61   {
62   # this takes a floating point constant string and returns it truncated to
63   # integer. For instance, '4.5' => '4', '1.234e2' => '123' etc
64   my $float = shift;
65
66   # some simple cases first
67   return $float if ($float =~ /^[+-]?[0-9]+$/);         # '+123','-1','0' etc
68   return $float 
69     if ($float =~ /^[+-]?[0-9]+\.?[eE]\+?[0-9]+$/);     # 123e2, 123.e+2
70   return '0' if ($float =~ /^[+-]?[0]*\.[0-9]+$/);      # .2, 0.2, -.1
71   if ($float =~ /^[+-]?[0-9]+\.[0-9]*$/)                # 1., 1.23, -1.2 etc
72     {
73     $float =~ s/\..*//;
74     return $float;
75     }
76   my ($mis,$miv,$mfv,$es,$ev) = Math::BigInt::_split($float);
77   return $float if !defined $mis;       # doesn't look like a number to me
78   my $ec = int($$ev);
79   my $sign = $$mis; $sign = '' if $sign eq '+';
80   if ($$es eq '-')
81     {
82     # ignore fraction part entirely
83     if ($ec >= length($$miv))                   # 123.23E-4
84       {
85       return '0';
86       }
87     return $sign . substr ($$miv,0,length($$miv)-$ec);  # 1234.45E-2 = 12
88     }
89   # xE+y
90   if ($ec >= length($$mfv))
91     {
92     $ec -= length($$mfv);                       
93     return $sign.$$miv.$$mfv if $ec == 0;       # 123.45E+2 => 12345
94     return $sign.$$miv.$$mfv.'E'.$ec;           # 123.45e+3 => 12345e1
95     }
96   $mfv = substr($$mfv,0,$ec);
97   return $sign.$$miv.$mfv;                      # 123.45e+1 => 1234
98   }
99
100 sub import 
101   {
102   my $self = shift;
103
104   # some defaults
105   my $lib = '';
106
107   my @import = ( ':constant' );                         # drive it w/ constant
108   my @a = @_; my $l = scalar @_; my $j = 0;
109   my ($ver,$trace);                                     # version? trace?
110   my ($a,$p);                                           # accuracy, precision
111   for ( my $i = 0; $i < $l ; $i++,$j++ )
112     {
113     if ($_[$i] =~ /^(l|lib)$/)
114       {
115       # this causes a different low lib to take care...
116       $lib = $_[$i+1] || '';
117       my $s = 2; $s = 1 if @a-$j < 2;   # avoid "can not modify non-existant..."
118       splice @a, $j, $s; $j -= $s; $i++;
119       }
120     elsif ($_[$i] =~ /^(a|accuracy)$/)
121       {
122       $a = $_[$i+1];
123       my $s = 2; $s = 1 if @a-$j < 2;   # avoid "can not modify non-existant..."
124       splice @a, $j, $s; $j -= $s; $i++;
125       }
126     elsif ($_[$i] =~ /^(p|precision)$/)
127       {
128       $p = $_[$i+1];
129       my $s = 2; $s = 1 if @a-$j < 2;   # avoid "can not modify non-existant..."
130       splice @a, $j, $s; $j -= $s; $i++;
131       }
132     elsif ($_[$i] =~ /^(v|version)$/)
133       {
134       $ver = 1;
135       splice @a, $j, 1; $j --;
136       }
137     elsif ($_[$i] =~ /^(t|trace)$/)
138       {
139       $trace = 1;
140       splice @a, $j, 1; $j --;
141       }
142     else { die "unknown option $_[$i]"; }
143     }
144   my $class;
145   $_lite = 0;                                   # using M::BI::L ?
146   if ($trace)
147     {
148     require Math::BigInt::Trace; $class = 'Math::BigInt::Trace';
149     }
150   else
151     {
152     # see if we can find Math::BigInt::Lite
153     if (!defined $a && !defined $p)             # rounding won't work to well
154       {
155       eval 'require Math::BigInt::Lite;';
156       if ($@ eq '')
157         {
158         @import = ( );                          # :constant in Lite, not MBI
159         Math::BigInt::Lite->import( ':constant' );
160         $_lite= 1;                              # signal okay
161         }
162       }
163     require Math::BigInt if $_lite == 0;        # not already loaded?
164     $class = 'Math::BigInt';                    # regardless of MBIL or not
165     }
166   push @import, 'lib' => $lib if $lib ne '';
167   # Math::BigInt::Trace or plain Math::BigInt
168   $class->import(@import);
169
170   bigint->accuracy($a) if defined $a;
171   bigint->precision($p) if defined $p;
172   if ($ver)
173     {
174     print "bigint\t\t\t v$VERSION\n";
175     print "Math::BigInt::Lite\t v$Math::BigInt::Lite::VERSION\n" if $_lite;
176     print "Math::BigInt\t\t v$Math::BigInt::VERSION";
177     my $config = Math::BigInt->config();
178     print " lib => $config->{lib} v$config->{lib_version}\n";
179     exit;
180     }
181   # we take care of floating point constants, since BigFloat isn't available
182   # and BigInt doesn't like them:
183   overload::constant float => sub { Math::BigInt->new( _constant(shift) ); };
184
185   $self->export_to_level(1,$self,@a);           # export inf and NaN
186   }
187
188 sub inf () { Math::BigInt->binf(); }
189 sub NaN () { Math::BigInt->bnan(); }
190
191 1;
192
193 __END__
194
195 =head1 NAME
196
197 bigint - Transparent BigInteger support for Perl
198
199 =head1 SYNOPSIS
200
201   use bigint;
202
203   $x = 2 + 4.5,"\n";                    # BigInt 6
204   print 2 ** 512,"\n";                  # really is what you think it is
205   print inf + 42,"\n";                  # inf
206   print NaN * 7,"\n";                   # NaN
207
208 =head1 DESCRIPTION
209
210 All operators (including basic math operations) are overloaded. Integer
211 constants are created as proper BigInts.
212
213 Floating point constants are truncated to integer. All results are also
214 truncated.
215
216 =head2 Options
217
218 bigint recognizes some options that can be passed while loading it via use.
219 The options can (currently) be either a single letter form, or the long form.
220 The following options exist:
221
222 =over 2
223
224 =item a or accuracy
225
226 This sets the accuracy for all math operations. The argument must be greater
227 than or equal to zero. See Math::BigInt's bround() function for details.
228
229         perl -Mbigint=a,2 -le 'print 12345+1'
230
231 =item p or precision
232
233 This sets the precision for all math operations. The argument can be any
234 integer. Negative values mean a fixed number of digits after the dot, and
235 are <B>ignored</B> since all operations happen in integer space.
236 A positive value rounds to this digit left from the dot. 0 or 1 mean round to
237 integer and are ignore like negative values.
238
239 See Math::BigInt's bfround() function for details.
240
241         perl -Mbignum=p,5 -le 'print 123456789+123'
242
243 =item t or trace
244
245 This enables a trace mode and is primarily for debugging bigint or
246 Math::BigInt.
247
248 =item l or lib
249
250 Load a different math lib, see L<MATH LIBRARY>.
251
252         perl -Mbigint=l,GMP -e 'print 2 ** 512'
253
254 Currently there is no way to specify more than one library on the command
255 line. This will be hopefully fixed soon ;)
256
257 =item v or version
258
259 This prints out the name and version of all modules used and then exits.
260
261         perl -Mbigint=v
262
263 =head2 Math Library
264
265 Math with the numbers is done (by default) by a module called
266 Math::BigInt::Calc. This is equivalent to saying:
267
268         use bigint lib => 'Calc';
269
270 You can change this by using:
271
272         use bigint lib => 'BitVect';
273
274 The following would first try to find Math::BigInt::Foo, then
275 Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:
276
277         use bigint lib => 'Foo,Math::BigInt::Bar';
278
279 Please see respective module documentation for further details.
280
281 =head2 Internal Format
282
283 The numbers are stored as objects, and their internals might change at anytime,
284 especially between math operations. The objects also might belong to different
285 classes, like Math::BigInt, or Math::BigInt::Lite. Mixing them together, even
286 with normal scalars is not extraordinary, but normal and expected.
287
288 You should not depend on the internal format, all accesses must go through
289 accessor methods. E.g. looking at $x->{sign} is not a good idea since there
290 is no guaranty that the object in question has such a hash key, nor is a hash
291 underneath at all.
292
293 =head2 Sign
294
295 The sign is either '+', '-', 'NaN', '+inf' or '-inf'.
296 You can access it with the sign() method.
297
298 A sign of 'NaN' is used to represent the result when input arguments are not
299 numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively
300 minus infinity. You will get '+inf' when dividing a positive number by 0, and
301 '-inf' when dividing any negative number by 0.
302
303 =head2 Methods
304
305 Since all numbers are now objects, you can use all functions that are part of
306 the BigInt API. You can only use the bxxx() notation, and not the fxxx()
307 notation, though. 
308
309 =head2 Caveat
310
311 But a warning is in order. When using the following to make a copy of a number,
312 only a shallow copy will be made.
313
314         $x = 9; $y = $x;
315         $x = $y = 7;
316
317 Using the copy or the original with overloaded math is okay, e.g. the
318 following work:
319
320         $x = 9; $y = $x;
321         print $x + 1, " ", $y,"\n";     # prints 10 9
322
323 but calling any method that modifies the number directly will result in
324 B<both> the original and the copy being destroyed:
325         
326         $x = 9; $y = $x;
327         print $x->badd(1), " ", $y,"\n";        # prints 10 10
328         
329         $x = 9; $y = $x;
330         print $x->binc(1), " ", $y,"\n";        # prints 10 10
331         
332         $x = 9; $y = $x;
333         print $x->bmul(2), " ", $y,"\n";        # prints 18 18
334         
335 Using methods that do not modify, but testthe contents works:
336
337         $x = 9; $y = $x;
338         $z = 9 if $x->is_zero();                # works fine
339
340 See the documentation about the copy constructor and C<=> in overload, as
341 well as the documentation in BigInt for further details.
342
343 =head1 MODULES USED
344
345 C<bigint> is just a thin wrapper around various modules of the Math::BigInt
346 family. Think of it as the head of the family, who runs the shop, and orders
347 the others to do the work.
348
349 The following modules are currently used by bigint:
350
351         Math::BigInt::Lite      (for speed, and only if it is loadable)
352         Math::BigInt
353
354 =head1 EXAMPLES
355
356 Some cool command line examples to impress the Python crowd ;) You might want
357 to compare them to the results under -Mbignum or -Mbigrat:
358  
359         perl -Mbigint -le 'print sqrt(33)'
360         perl -Mbigint -le 'print 2*255'
361         perl -Mbigint -le 'print 4.5+2*255'
362         perl -Mbigint -le 'print 3/7 + 5/7 + 8/3'
363         perl -Mbigint -le 'print 123->is_odd()'
364         perl -Mbigint -le 'print log(2)'
365         perl -Mbigint -le 'print 2 ** 0.5'
366         perl -Mbigint=a,65 -le 'print 2 ** 0.2'
367
368 =head1 LICENSE
369
370 This program is free software; you may redistribute it and/or modify it under
371 the same terms as Perl itself.
372
373 =head1 SEE ALSO
374
375 Especially L<bigrat> as in C<perl -Mbigrat -le 'print 1/3+1/4'> and
376 L<bignum> as in C<perl -Mbignum -le 'print sqrt(2)'>.
377
378 L<Math::BigInt>, L<Math::BigRat> and L<Math::Big> as well
379 as L<Math::BigInt::BitVect>, L<Math::BigInt::Pari> and  L<Math::BigInt::GMP>.
380
381 =head1 AUTHORS
382
383 (C) by Tels L<http://bloodgate.com/> in early 2002 - 2005.
384
385 =cut