This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Upgrade bignum from version 0.42 to 0.43
[perl5.git] / cpan / bignum / lib / bigrat.pm
1 package bigrat;
2
3 use 5.006;
4 use strict;
5 use warnings;
6
7 our $VERSION = '0.43';
8
9 use Exporter;
10 our @ISA            = qw( bigint );
11 our @EXPORT_OK      = qw( PI e bpi bexp hex oct );
12 our @EXPORT         = qw( inf NaN );
13
14 use overload;
15 use bigint ();
16
17 ##############################################################################
18
19 BEGIN {
20     *inf = \&bigint::inf;
21     *NaN = \&bigint::NaN;
22     *hex = \&bigint::hex;
23     *oct = \&bigint::oct;
24 }
25
26 # These are all alike, and thus faked by AUTOLOAD
27
28 my @faked = qw/round_mode accuracy precision div_scale/;
29 our ($AUTOLOAD, $_lite);        # _lite for testsuite
30
31 sub AUTOLOAD {
32     my $name = $AUTOLOAD;
33
34     $name =~ s/.*:://;          # split package
35     no strict 'refs';
36     foreach my $n (@faked) {
37         if ($n eq $name) {
38             *{"bigrat::$name"} =
39               sub {
40                   my $self = shift;
41                   no strict 'refs';
42                   if (defined $_[0]) {
43                       Math::BigInt->$name($_[0]);
44                       Math::BigFloat->$name($_[0]);
45                       return Math::BigRat->$name($_[0]);
46                   }
47                   return Math::BigInt->$name();
48               };
49             return &$name;
50         }
51     }
52
53     # delayed load of Carp and avoid recursion
54     require Carp;
55     Carp::croak ("Can't call bigrat\-\>$name, not a valid method");
56 }
57
58 sub unimport {
59     $^H{bigrat} = undef;        # no longer in effect
60     overload::remove_constant('binary', '', 'float', '', 'integer');
61 }
62
63 sub in_effect {
64     my $level = shift || 0;
65     my $hinthash = (caller($level))[10];
66     $hinthash->{bigrat};
67 }
68
69 #############################################################################
70
71 sub import {
72     my $self = shift;
73
74     # see also bignum->import() for additional comments
75
76     $^H{bigrat} = 1;                            # we are in effect
77
78     # for newer Perls always override hex() and oct() with a lexical version:
79     if ($] > 5.009004) {
80         bigint::_override();
81     }
82     # some defaults
83     my $lib      = '';
84     my $lib_kind = 'try';
85     my $upgrade  = 'Math::BigFloat';
86
87     my @import = (':constant');                 # drive it w/ constant
88     my @a = @_;
89     my $l = scalar @_;
90     my $j = 0;
91     my ($a, $p);
92     my ($ver, $trace);                          # version? trace?
93     for (my $i = 0; $i < $l ; $i++, $j++) {
94         if ($_[$i] eq 'upgrade') {
95             # this causes upgrading
96             $upgrade = $_[$i + 1];              # or undef to disable
97             my $s = 2;
98             $s = 1 if @a - $j < 2;  # avoid "can not modify non-existent..."
99             splice @a, $j, $s;
100             $j -= $s;
101         }
102         elsif ($_[$i] =~ /^(l|lib|try|only)$/) {
103             # this causes a different low lib to take care...
104             $lib_kind = $1;
105             $lib_kind = 'lib' if $lib_kind eq 'l';
106             $lib = $_[$i + 1] || '';
107             my $s = 2;
108             $s = 1 if @a - $j < 2;  # avoid "can not modify non-existent..."
109             splice @a, $j, $s;
110             $j -= $s;
111             $i++;
112         }
113         elsif ($_[$i] =~ /^(a|accuracy)$/) {
114             $a = $_[$i + 1];
115             my $s = 2;
116             $s = 1 if @a - $j < 2;  # avoid "can not modify non-existent..."
117             splice @a, $j, $s;
118             $j -= $s;
119             $i++;
120         }
121         elsif ($_[$i] =~ /^(p|precision)$/) {
122             $p = $_[$i + 1];
123             my $s = 2;
124             $s = 1 if @a - $j < 2;  # avoid "can not modify non-existent..."
125             splice @a, $j, $s;
126             $j -= $s;
127             $i++;
128         }
129         elsif ($_[$i] =~ /^(v|version)$/) {
130             $ver = 1;
131             splice @a, $j, 1;
132             $j--;
133         }
134         elsif ($_[$i] =~ /^(t|trace)$/) {
135             $trace = 1;
136             splice @a, $j, 1;
137             $j--;
138         }
139         elsif ($_[$i] !~ /^(PI|e|bpi|bexp|hex|oct)\z/) {
140             die ("unknown option $_[$i]");
141         }
142     }
143     my $class;
144     $_lite = 0;                                 # using M::BI::L ?
145     if ($trace) {
146         require Math::BigInt::Trace;
147         $class   = 'Math::BigInt::Trace';
148         $upgrade = 'Math::BigFloat::Trace';
149     }
150     else {
151         # see if we can find Math::BigInt::Lite
152         if (!defined $a && !defined $p) {       # rounding won't work to well
153             if (eval { require Math::BigInt::Lite; 1 }) {
154                 @import = ();                   # :constant in Lite, not MBI
155                 Math::BigInt::Lite->import(':constant');
156                 $_lite = 1;                     # signal okay
157             }
158         }
159         require Math::BigInt if $_lite == 0;    # not already loaded?
160         $class = 'Math::BigInt';                # regardless of MBIL or not
161     }
162     push @import, $lib_kind => $lib if $lib ne '';
163     # Math::BigInt::Trace or plain Math::BigInt
164     $class->import(@import, upgrade => $upgrade);
165
166     require Math::BigFloat;
167     Math::BigFloat->import(upgrade => 'Math::BigRat', ':constant');
168     require Math::BigRat;
169     Math::BigRat->import(@import);
170
171     bigrat->accuracy($a)  if defined $a;
172     bigrat->precision($p) if defined $p;
173     if ($ver) {
174         print "bigrat\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         print "Math::BigFloat\t\t v$Math::BigFloat::VERSION\n";
180         print "Math::BigRat\t\t v$Math::BigRat::VERSION\n";
181         exit;
182     }
183
184     # Take care of octal/hexadecimal constants
185     overload::constant binary =>
186         sub {
187             bigint::_binary_constant(shift);
188           };
189
190     # if another big* was already loaded:
191     my ($package) = caller();
192
193     no strict 'refs';
194     if (!defined *{"${package}::inf"}) {
195         $self->export_to_level(1, $self, @a);   # export inf and NaN
196     }
197 }
198
199 sub PI () { Math::BigFloat->new('3.141592653589793238462643383279502884197'); }
200 sub e  () { Math::BigFloat->new('2.718281828459045235360287471352662497757'); }
201
202 sub bpi ($) {
203     local $Math::BigFloat::upgrade;
204     Math::BigFloat->bpi(@_);
205 }
206
207 sub bexp ($$) {
208     local $Math::BigFloat::upgrade;
209     my $x = Math::BigFloat->new($_[0]);
210     $x->bexp($_[1]);
211 }
212
213 1;
214
215 __END__
216
217 =pod
218
219 =head1 NAME
220
221 bigrat - Transparent BigNumber/BigRational support for Perl
222
223 =head1 SYNOPSIS
224
225   use bigrat;
226
227   print 2 + 4.5,"\n";                   # BigFloat 6.5
228   print 1/3 + 1/4,"\n";                 # produces 7/12
229
230   {
231     no bigrat;
232     print 1/3,"\n";                     # 0.33333...
233   }
234
235   # Import into current package:
236   use bigrat qw/hex oct/;
237   print hex("0x1234567890123490"),"\n";
238   print oct("01234567890123490"),"\n";
239
240 =head1 DESCRIPTION
241
242 All operators (including basic math operations) are overloaded. Integer and
243 floating-point constants are created as proper BigInts or BigFloats,
244 respectively.
245
246 Other than L<bignum>, this module upgrades to Math::BigRat, meaning that
247 instead of 2.5 you will get 2+1/2 as output.
248
249 =head2 Modules Used
250
251 C<bigrat> is just a thin wrapper around various modules of the Math::BigInt
252 family. Think of it as the head of the family, who runs the shop, and orders
253 the others to do the work.
254
255 The following modules are currently used by bignum:
256
257         Math::BigInt::Lite      (for speed, and only if it is loadable)
258         Math::BigInt
259         Math::BigFloat
260         Math::BigRat
261
262 =head2 Math Library
263
264 Math with the numbers is done (by default) by a module called
265 Math::BigInt::Calc. This is equivalent to saying:
266
267         use bigrat lib => 'Calc';
268
269 You can change this by using:
270
271         use bignum lib => 'GMP';
272
273 The following would first try to find Math::BigInt::Foo, then
274 Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:
275
276         use bigrat lib => 'Foo,Math::BigInt::Bar';
277
278 Using C<lib> warns if none of the specified libraries can be found and
279 L<Math::BigInt> did fall back to one of the default libraries.
280 To suppress this warning, use C<try> instead:
281
282         use bignum try => 'GMP';
283
284 If you want the code to die instead of falling back, use C<only> instead:
285
286         use bignum only => 'GMP';
287
288 Please see respective module documentation for further details.
289
290 =head2 Sign
291
292 The sign is either '+', '-', 'NaN', '+inf' or '-inf'.
293
294 A sign of 'NaN' is used to represent the result when input arguments are not
295 numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively
296 minus infinity. You will get '+inf' when dividing a positive number by 0, and
297 '-inf' when dividing any negative number by 0.
298
299 =head2 Methods
300
301 Since all numbers are not objects, you can use all functions that are part of
302 the BigInt or BigFloat API. It is wise to use only the bxxx() notation, and not
303 the fxxx() notation, though. This makes you independent on the fact that the
304 underlying object might morph into a different class than BigFloat.
305
306 =over 2
307
308 =item inf()
309
310 A shortcut to return Math::BigInt->binf(). Useful because Perl does not always
311 handle bareword C<inf> properly.
312
313 =item NaN()
314
315 A shortcut to return Math::BigInt->bnan(). Useful because Perl does not always
316 handle bareword C<NaN> properly.
317
318 =item e
319
320         # perl -Mbigrat=e -wle 'print e'
321
322 Returns Euler's number C<e>, aka exp(1).
323
324 =item PI
325
326         # perl -Mbigrat=PI -wle 'print PI'
327
328 Returns PI.
329
330 =item bexp()
331
332         bexp($power,$accuracy);
333
334 Returns Euler's number C<e> raised to the appropriate power, to
335 the wanted accuracy.
336
337 Example:
338
339         # perl -Mbigrat=bexp -wle 'print bexp(1,80)'
340
341 =item bpi()
342
343         bpi($accuracy);
344
345 Returns PI to the wanted accuracy.
346
347 Example:
348
349         # perl -Mbigrat=bpi -wle 'print bpi(80)'
350
351 =item upgrade()
352
353 Return the class that numbers are upgraded to, is in fact returning
354 C<$Math::BigInt::upgrade>.
355
356 =item in_effect()
357
358         use bigrat;
359
360         print "in effect\n" if bigrat::in_effect;       # true
361         {
362           no bigrat;
363           print "in effect\n" if bigrat::in_effect;     # false
364         }
365
366 Returns true or false if C<bigrat> is in effect in the current scope.
367
368 This method only works on Perl v5.9.4 or later.
369
370 =back
371
372 =head2 MATH LIBRARY
373
374 Math with the numbers is done (by default) by a module called
375
376 =head2 Caveat
377
378 But a warning is in order. When using the following to make a copy of a number,
379 only a shallow copy will be made.
380
381         $x = 9; $y = $x;
382         $x = $y = 7;
383
384 If you want to make a real copy, use the following:
385
386         $y = $x->copy();
387
388 Using the copy or the original with overloaded math is okay, e.g. the
389 following work:
390
391         $x = 9; $y = $x;
392         print $x + 1, " ", $y,"\n";     # prints 10 9
393
394 but calling any method that modifies the number directly will result in
395 B<both> the original and the copy being destroyed:
396
397         $x = 9; $y = $x;
398         print $x->badd(1), " ", $y,"\n";        # prints 10 10
399
400         $x = 9; $y = $x;
401         print $x->binc(1), " ", $y,"\n";        # prints 10 10
402
403         $x = 9; $y = $x;
404         print $x->bmul(2), " ", $y,"\n";        # prints 18 18
405
406 Using methods that do not modify, but testthe contents works:
407
408         $x = 9; $y = $x;
409         $z = 9 if $x->is_zero();                # works fine
410
411 See the documentation about the copy constructor and C<=> in overload, as
412 well as the documentation in BigInt for further details.
413
414 =head2 Options
415
416 bignum recognizes some options that can be passed while loading it via use.
417 The options can (currently) be either a single letter form, or the long form.
418 The following options exist:
419
420 =over 2
421
422 =item a or accuracy
423
424 This sets the accuracy for all math operations. The argument must be greater
425 than or equal to zero. See Math::BigInt's bround() function for details.
426
427         perl -Mbigrat=a,50 -le 'print sqrt(20)'
428
429 Note that setting precision and accuracy at the same time is not possible.
430
431 =item p or precision
432
433 This sets the precision for all math operations. The argument can be any
434 integer. Negative values mean a fixed number of digits after the dot, while
435 a positive value rounds to this digit left from the dot. 0 or 1 mean round to
436 integer. See Math::BigInt's bfround() function for details.
437
438         perl -Mbigrat=p,-50 -le 'print sqrt(20)'
439
440 Note that setting precision and accuracy at the same time is not possible.
441
442 =item t or trace
443
444 This enables a trace mode and is primarily for debugging bignum or
445 Math::BigInt/Math::BigFloat.
446
447 =item l or lib
448
449 Load a different math lib, see L<MATH LIBRARY>.
450
451         perl -Mbigrat=l,GMP -e 'print 2 ** 512'
452
453 Currently there is no way to specify more than one library on the command
454 line. This means the following does not work:
455
456         perl -Mbignum=l,GMP,Pari -e 'print 2 ** 512'
457
458 This will be hopefully fixed soon ;)
459
460 =item hex
461
462 Override the built-in hex() method with a version that can handle big
463 numbers. This overrides it by exporting it to the current package. Under
464 Perl v5.10.0 and higher, this is not so necessary, as hex() is lexically
465 overridden in the current scope whenever the bigrat pragma is active.
466
467 =item oct
468
469 Override the built-in oct() method with a version that can handle big
470 numbers. This overrides it by exporting it to the current package. Under
471 Perl v5.10.0 and higher, this is not so necessary, as oct() is lexically
472 overridden in the current scope whenever the bigrat pragma is active.
473
474 =item v or version
475
476 This prints out the name and version of all modules used and then exits.
477
478         perl -Mbigrat=v
479
480 =back
481
482 =head1 CAVEATS
483
484 =over 2
485
486 =item Operator vs literal overloading
487
488 C<bigrat> works by overloading handling of integer and floating point
489 literals, converting them to L<Math::BigInt> or L<Math::BigRat>
490 objects.
491
492 This means that arithmetic involving only string values or string
493 literals will be performed using Perl's built-in operators.
494
495 For example:
496
497     use bigrat;
498     my $x = "900000000000000009";
499     my $y = "900000000000000007";
500     print $x - $y;
501
502 will output C<0> on default 32-bit builds, since C<bigrat> never sees
503 the string literals.  To ensure the expression is all treated as
504 C<Math::BigInt> or C<Math::BigRat> objects, use a literal number in
505 the expression:
506
507     print +(0+$x) - $y;
508
509 =item in_effect()
510
511 This method only works on Perl v5.9.4 or later.
512
513 =item hex()/oct()
514
515 C<bigint> overrides these routines with versions that can also handle
516 big integer values. Under Perl prior to version v5.9.4, however, this
517 will not happen unless you specifically ask for it with the two
518 import tags "hex" and "oct" - and then it will be global and cannot be
519 disabled inside a scope with "no bigint":
520
521         use bigint qw/hex oct/;
522
523         print hex("0x1234567890123456");
524         {
525                 no bigint;
526                 print hex("0x1234567890123456");
527         }
528
529 The second call to hex() will warn about a non-portable constant.
530
531 Compare this to:
532
533         use bigint;
534
535         # will warn only under Perl older than v5.9.4
536         print hex("0x1234567890123456");
537
538 =back
539
540 =head1 EXAMPLES
541
542         perl -Mbigrat -le 'print sqrt(33)'
543         perl -Mbigrat -le 'print 2*255'
544         perl -Mbigrat -le 'print 4.5+2*255'
545         perl -Mbigrat -le 'print 3/7 + 5/7 + 8/3'
546         perl -Mbigrat -le 'print 12->is_odd()';
547         perl -Mbignum=l,GMP -le 'print 7 ** 7777'
548
549 =head1 LICENSE
550
551 This program is free software; you may redistribute it and/or modify it under
552 the same terms as Perl itself.
553
554 =head1 SEE ALSO
555
556 Especially L<bignum>.
557
558 L<Math::BigFloat>, L<Math::BigInt>, L<Math::BigRat> and L<Math::Big> as well
559 as L<Math::BigInt::Pari> and  L<Math::BigInt::GMP>.
560
561 =head1 AUTHORS
562
563 (C) by Tels L<http://bloodgate.com/> in early 2002 - 2007.
564
565 =cut