This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[perl #43010] [PATCH] Deparse, ''->(), ::(), sub :: {}, etc.
[perl5.git] / lib / bignum.pm
CommitLineData
126f3c5f 1package bignum;
95a2d02c 2use 5.006002;
126f3c5f 3
48441d71 4$VERSION = '0.21_02';
126f3c5f 5use Exporter;
b4bc5691
T
6@EXPORT_OK = qw( );
7@EXPORT = qw( inf NaN );
8@ISA = qw( Exporter );
126f3c5f
JH
9
10use strict;
95a2d02c 11use overload;
126f3c5f
JH
12
13##############################################################################
14
15# These are all alike, and thus faked by AUTOLOAD
16
17my @faked = qw/round_mode accuracy precision div_scale/;
18use vars qw/$VERSION $AUTOLOAD $_lite/; # _lite for testsuite
19
20sub 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 *{"bignum::$name"} = sub
31 {
32 my $self = shift;
33 no strict 'refs';
34 if (defined $_[0])
35 {
36 Math::BigInt->$name($_[0]);
990fb837 37 return Math::BigFloat->$name($_[0]);
126f3c5f
JH
38 }
39 return Math::BigInt->$name();
40 };
41 return &$name;
42 }
43 }
44
45 # delayed load of Carp and avoid recursion
46 require Carp;
47 Carp::croak ("Can't call bignum\-\>$name, not a valid method");
48 }
49
50sub upgrade
51 {
52 my $self = shift;
53 no strict 'refs';
54# if (defined $_[0])
55# {
56# $Math::BigInt::upgrade = $_[0];
57# $Math::BigFloat::upgrade = $_[0];
58# }
95a2d02c
T
59 $Math::BigInt::upgrade;
60 }
61
62sub _binary_constant
63 {
64 # this takes a binary/hexadecimal/octal constant string and returns it
65 # as string suitable for new. Basically it converts octal to decimal, and
66 # passes every thing else unmodified back.
67 my $string = shift;
68
69 return Math::BigInt->new($string) if $string =~ /^0[bx]/;
70
71 # so it must be an octal constant
72 Math::BigInt->from_oct($string);
126f3c5f
JH
73 }
74
75sub import
76 {
77 my $self = shift;
78
79 # some defaults
bd49aa09 80 my $lib = ''; my $lib_kind = 'try';
126f3c5f
JH
81 my $upgrade = 'Math::BigFloat';
82 my $downgrade = 'Math::BigInt';
83
84 my @import = ( ':constant' ); # drive it w/ constant
85 my @a = @_; my $l = scalar @_; my $j = 0;
86 my ($ver,$trace); # version? trace?
87 my ($a,$p); # accuracy, precision
88 for ( my $i = 0; $i < $l ; $i++,$j++ )
89 {
90 if ($_[$i] eq 'upgrade')
91 {
92 # this causes upgrading
93 $upgrade = $_[$i+1]; # or undef to disable
94 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
95 splice @a, $j, $s; $j -= $s; $i++;
96 }
97 elsif ($_[$i] eq 'downgrade')
98 {
99 # this causes downgrading
100 $downgrade = $_[$i+1]; # or undef to disable
101 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
102 splice @a, $j, $s; $j -= $s; $i++;
103 }
bd49aa09 104 elsif ($_[$i] =~ /^(l|lib|try|only)$/)
126f3c5f
JH
105 {
106 # this causes a different low lib to take care...
bd49aa09 107 $lib_kind = $1; $lib_kind = 'lib' if $lib_kind eq 'l';
126f3c5f
JH
108 $lib = $_[$i+1] || '';
109 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
110 splice @a, $j, $s; $j -= $s; $i++;
111 }
112 elsif ($_[$i] =~ /^(a|accuracy)$/)
113 {
114 $a = $_[$i+1];
115 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
116 splice @a, $j, $s; $j -= $s; $i++;
117 }
118 elsif ($_[$i] =~ /^(p|precision)$/)
119 {
120 $p = $_[$i+1];
121 my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
122 splice @a, $j, $s; $j -= $s; $i++;
123 }
124 elsif ($_[$i] =~ /^(v|version)$/)
125 {
126 $ver = 1;
127 splice @a, $j, 1; $j --;
128 }
129 elsif ($_[$i] =~ /^(t|trace)$/)
130 {
131 $trace = 1;
132 splice @a, $j, 1; $j --;
133 }
134 else { die "unknown option $_[$i]"; }
135 }
136 my $class;
137 $_lite = 0; # using M::BI::L ?
138 if ($trace)
139 {
140 require Math::BigInt::Trace; $class = 'Math::BigInt::Trace';
141 $upgrade = 'Math::BigFloat::Trace';
126f3c5f
JH
142 }
143 else
144 {
145 # see if we can find Math::BigInt::Lite
146 if (!defined $a && !defined $p) # rounding won't work to well
147 {
148 eval 'require Math::BigInt::Lite;';
149 if ($@ eq '')
150 {
151 @import = ( ); # :constant in Lite, not MBI
152 Math::BigInt::Lite->import( ':constant' );
153 $_lite= 1; # signal okay
154 }
155 }
156 require Math::BigInt if $_lite == 0; # not already loaded?
157 $class = 'Math::BigInt'; # regardless of MBIL or not
233f7bc0 158 }
48441d71 159 push @import, $lib_kind => $lib if $lib ne '';
126f3c5f 160 # Math::BigInt::Trace or plain Math::BigInt
233f7bc0 161 $class->import(@import, upgrade => $upgrade);
126f3c5f
JH
162
163 if ($trace)
164 {
165 require Math::BigFloat::Trace; $class = 'Math::BigFloat::Trace';
166 $downgrade = 'Math::BigInt::Trace';
126f3c5f
JH
167 }
168 else
169 {
170 require Math::BigFloat; $class = 'Math::BigFloat';
171 }
172 $class->import(':constant','downgrade',$downgrade);
173
174 bignum->accuracy($a) if defined $a;
175 bignum->precision($p) if defined $p;
176 if ($ver)
177 {
178 print "bignum\t\t\t v$VERSION\n";
179 print "Math::BigInt::Lite\t v$Math::BigInt::Lite::VERSION\n" if $_lite;
180 print "Math::BigInt\t\t v$Math::BigInt::VERSION";
181 my $config = Math::BigInt->config();
182 print " lib => $config->{lib} v$config->{lib_version}\n";
183 print "Math::BigFloat\t\t v$Math::BigFloat::VERSION\n";
184 exit;
185 }
95a2d02c
T
186
187 # Take care of octal/hexadecimal constants
188 overload::constant 'binary' => sub { _binary_constant(shift) };
189
b4bc5691 190 $self->export_to_level(1,$self,@a); # export inf and NaN
126f3c5f
JH
191 }
192
b4bc5691
T
193sub inf () { Math::BigInt->binf(); }
194sub NaN () { Math::BigInt->bnan(); }
195
126f3c5f
JH
1961;
197
198__END__
199
200=head1 NAME
201
202bignum - Transparent BigNumber support for Perl
203
204=head1 SYNOPSIS
205
206 use bignum;
207
208 $x = 2 + 4.5,"\n"; # BigFloat 6.5
b4bc5691
T
209 print 2 ** 512 * 0.1,"\n"; # really is what you think it is
210 print inf * inf,"\n"; # prints inf
211 print NaN * 3,"\n"; # prints NaN
126f3c5f
JH
212
213=head1 DESCRIPTION
214
215All operators (including basic math operations) are overloaded. Integer and
216floating-point constants are created as proper BigInts or BigFloats,
217respectively.
218
24716a00
HS
219If you do
220
221 use bignum;
222
223at the top of your script, Math::BigFloat and Math::BigInt will be loaded
224and any constant number will be converted to an object (Math::BigFloat for
225floats like 3.1415 and Math::BigInt for integers like 1234).
226
227So, the following line:
228
229 $x = 1234;
230
231creates actually a Math::BigInt and stores a reference to in $x.
232This happens transparently and behind your back, so to speak.
233
234You can see this with the following:
235
236 perl -Mbignum -le 'print ref(1234)'
237
238Don't worry if it says Math::BigInt::Lite, bignum and friends will use Lite
239if it is installed since it is faster for some operations. It will be
3c4b39be 240automatically upgraded to BigInt whenever necessary:
24716a00
HS
241
242 perl -Mbignum -le 'print ref(2**255)'
243
244This also means it is a bad idea to check for some specific package, since
245the actual contents of $x might be something unexpected. Due to the
3c4b39be 246transparent way of bignum C<ref()> should not be necessary, anyway.
24716a00
HS
247
248Since Math::BigInt and BigFloat also overload the normal math operations,
249the following line will still work:
250
251 perl -Mbignum -le 'print ref(1234+1234)'
252
253Since numbers are actually objects, you can call all the usual methods from
254BigInt/BigFloat on them. This even works to some extent on expressions:
255
256 perl -Mbignum -le '$x = 1234; print $x->bdec()'
257 perl -Mbignum -le 'print 1234->binc();'
258 perl -Mbignum -le 'print 1234->binc->badd(6);'
259 perl -Mbignum -le 'print +(1234)->binc()'
260
261(Note that print doesn't do what you expect if the expression starts with
262'(' hence the C<+>)
263
264You can even chain the operations together as usual:
265
266 perl -Mbignum -le 'print 1234->binc->badd(6);'
267 1241
268
269Under bignum (or bigint or bigrat), Perl will "upgrade" the numbers
270appropriately. This means that:
271
272 perl -Mbignum -le 'print 1234+4.5'
273 1238.5
274
275will work correctly. These mixed cases don't do always work when using
276Math::BigInt or Math::BigFloat alone, or at least not in the way normal Perl
277scalars work.
278
279If you do want to work with large integers like under C<use integer;>, try
280C<use bigint;>:
281
282 perl -Mbigint -le 'print 1234.5+4.5'
283 1238
284
285There is also C<use bigrat;> which gives you big rationals:
286
287 perl -Mbigrat -le 'print 1234+4.1'
288 12381/10
289
290The entire upgrading/downgrading is still experimental and might not work
291as you expect or may even have bugs.
292
293You might get errors like this:
294
295 Can't use an undefined value as an ARRAY reference at
296 /usr/local/lib/perl5/5.8.0/Math/BigInt/Calc.pm line 864
297
298This means somewhere a routine got a BigFloat/Lite but expected a BigInt (or
299vice versa) and the upgrade/downgrad path was missing. This is a bug, please
300report it so that we can fix it.
301
302You might consider using just Math::BigInt or Math::BigFloat, since they
303allow you finer control over what get's done in which module/space. For
304instance, simple loop counters will be Math::BigInts under C<use bignum;> and
305this is slower than keeping them as Perl scalars:
306
307 perl -Mbignum -le 'for ($i = 0; $i < 10; $i++) { print ref($i); }'
308
309Please note the following does not work as expected (prints nothing), since
310overloading of '..' is not yet possible in Perl (as of v5.8.0):
311
312 perl -Mbignum -le 'for (1..2) { print ref($_); }'
313
b68b7ab1 314=head2 Options
126f3c5f
JH
315
316bignum recognizes some options that can be passed while loading it via use.
317The options can (currently) be either a single letter form, or the long form.
318The following options exist:
319
320=over 2
321
322=item a or accuracy
323
324This sets the accuracy for all math operations. The argument must be greater
325than or equal to zero. See Math::BigInt's bround() function for details.
326
327 perl -Mbignum=a,50 -le 'print sqrt(20)'
328
95a2d02c
T
329Note that setting precision and accurary at the same time is not possible.
330
126f3c5f
JH
331=item p or precision
332
333This sets the precision for all math operations. The argument can be any
334integer. Negative values mean a fixed number of digits after the dot, while
335a positive value rounds to this digit left from the dot. 0 or 1 mean round to
336integer. See Math::BigInt's bfround() function for details.
337
338 perl -Mbignum=p,-50 -le 'print sqrt(20)'
339
95a2d02c
T
340Note that setting precision and accurary at the same time is not possible.
341
126f3c5f
JH
342=item t or trace
343
344This enables a trace mode and is primarily for debugging bignum or
345Math::BigInt/Math::BigFloat.
346
347=item l or lib
348
349Load a different math lib, see L<MATH LIBRARY>.
350
351 perl -Mbignum=l,GMP -e 'print 2 ** 512'
352
353Currently there is no way to specify more than one library on the command
95a2d02c
T
354line. This means the following does not work:
355
356 perl -Mbignum=l,GMP,Pari -e 'print 2 ** 512'
357
358This will be hopefully fixed soon ;)
126f3c5f
JH
359
360=item v or version
361
362This prints out the name and version of all modules used and then exits.
363
b68b7ab1 364 perl -Mbignum=v
126f3c5f 365
95a2d02c
T
366=back
367
b68b7ab1 368=head2 Methods
b4bc5691
T
369
370Beside import() and AUTOLOAD() there are only a few other methods.
371
24716a00
HS
372Since all numbers are now objects, you can use all functions that are part of
373the BigInt or BigFloat API. It is wise to use only the bxxx() notation, and not
374the fxxx() notation, though. This makes it possible that the underlying object
375might morph into a different class than BigFloat.
376
b68b7ab1 377=head2 Caveat
990fb837
RGS
378
379But a warning is in order. When using the following to make a copy of a number,
380only a shallow copy will be made.
381
382 $x = 9; $y = $x;
383 $x = $y = 7;
384
b68b7ab1
T
385If you want to make a real copy, use the following:
386
387 $y = $x->copy();
388
990fb837
RGS
389Using the copy or the original with overloaded math is okay, e.g. the
390following work:
391
392 $x = 9; $y = $x;
393 print $x + 1, " ", $y,"\n"; # prints 10 9
394
395but calling any method that modifies the number directly will result in
3c4b39be 396B<both> the original and the copy being destroyed:
990fb837
RGS
397
398 $x = 9; $y = $x;
399 print $x->badd(1), " ", $y,"\n"; # prints 10 10
400
401 $x = 9; $y = $x;
402 print $x->binc(1), " ", $y,"\n"; # prints 10 10
403
404 $x = 9; $y = $x;
405 print $x->bmul(2), " ", $y,"\n"; # prints 18 18
406
407Using methods that do not modify, but testthe contents works:
408
409 $x = 9; $y = $x;
410 $z = 9 if $x->is_zero(); # works fine
411
412See the documentation about the copy constructor and C<=> in overload, as
413well as the documentation in BigInt for further details.
414
b4bc5691
T
415=over 2
416
417=item inf()
418
3c4b39be 419A shortcut to return Math::BigInt->binf(). Useful because Perl does not always
b4bc5691
T
420handle bareword C<inf> properly.
421
422=item NaN()
423
3c4b39be 424A shortcut to return Math::BigInt->bnan(). Useful because Perl does not always
b4bc5691
T
425handle bareword C<NaN> properly.
426
427=item upgrade()
428
429Return the class that numbers are upgraded to, is in fact returning
430C<$Math::BigInt::upgrade>.
431
432=back
433
bd49aa09 434=head2 Math Library
126f3c5f
JH
435
436Math with the numbers is done (by default) by a module called
437Math::BigInt::Calc. This is equivalent to saying:
438
439 use bignum lib => 'Calc';
440
441You can change this by using:
442
bd49aa09 443 use bignum lib => 'GMP';
126f3c5f
JH
444
445The following would first try to find Math::BigInt::Foo, then
446Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:
447
448 use bignum lib => 'Foo,Math::BigInt::Bar';
449
450Please see respective module documentation for further details.
451
bd49aa09
SP
452Using C<lib> warns if none of the specified libraries can be found and
453L<Math::BigInt> did fall back to one of the default libraries.
454To supress this warning, use C<try> instead:
455
456 use bignum try => 'GMP';
457
458If you want the code to die instead of falling back, use C<only> instead:
459
460 use bignum only => 'GMP';
461
126f3c5f
JH
462=head2 INTERNAL FORMAT
463
464The numbers are stored as objects, and their internals might change at anytime,
465especially between math operations. The objects also might belong to different
466classes, like Math::BigInt, or Math::BigFLoat. Mixing them together, even
467with normal scalars is not extraordinary, but normal and expected.
468
469You should not depend on the internal format, all accesses must go through
470accessor methods. E.g. looking at $x->{sign} is not a bright idea since there
471is no guaranty that the object in question has such a hashkey, nor is a hash
472underneath at all.
473
474=head2 SIGN
475
476The sign is either '+', '-', 'NaN', '+inf' or '-inf' and stored seperately.
477You can access it with the sign() method.
478
479A sign of 'NaN' is used to represent the result when input arguments are not
480numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively
481minus infinity. You will get '+inf' when dividing a positive number by 0, and
482'-inf' when dividing any negative number by 0.
483
126f3c5f
JH
484=head1 MODULES USED
485
486C<bignum> is just a thin wrapper around various modules of the Math::BigInt
487family. Think of it as the head of the family, who runs the shop, and orders
488the others to do the work.
489
490The following modules are currently used by bignum:
491
492 Math::BigInt::Lite (for speed, and only if it is loadable)
493 Math::BigInt
494 Math::BigFloat
495
496=head1 EXAMPLES
497
498Some cool command line examples to impress the Python crowd ;)
499
500 perl -Mbignum -le 'print sqrt(33)'
501 perl -Mbignum -le 'print 2*255'
502 perl -Mbignum -le 'print 4.5+2*255'
503 perl -Mbignum -le 'print 3/7 + 5/7 + 8/3'
504 perl -Mbignum -le 'print 123->is_odd()'
505 perl -Mbignum -le 'print log(2)'
bce28014 506 perl -Mbignum -le 'print exp(1)'
126f3c5f
JH
507 perl -Mbignum -le 'print 2 ** 0.5'
508 perl -Mbignum=a,65 -le 'print 2 ** 0.2'
95a2d02c 509 perl -Mbignum=a,65,l,GMP -le 'print 7 ** 7777'
126f3c5f
JH
510
511=head1 LICENSE
512
513This program is free software; you may redistribute it and/or modify it under
514the same terms as Perl itself.
515
516=head1 SEE ALSO
517
518Especially L<bigrat> as in C<perl -Mbigrat -le 'print 1/3+1/4'>.
519
520L<Math::BigFloat>, L<Math::BigInt>, L<Math::BigRat> and L<Math::Big> as well
521as L<Math::BigInt::BitVect>, L<Math::BigInt::Pari> and L<Math::BigInt::GMP>.
522
523=head1 AUTHORS
524
95a2d02c 525(C) by Tels L<http://bloodgate.com/> in early 2002 - 2007.
126f3c5f
JH
526
527=cut