lib/bignum.pm

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