lib/bignum.pm

   1 package bignum;
   2 require 5.005;
   3
   4 $VERSION = '0.11';
   5 use Exporter;
   6 @ISA =       qw( Exporter );
   7 @EXPORT_OK = qw( );
   8
   9 use strict;
  10
  11 ##############################################################################
  12
  13 # These are all alike, and thus faked by AUTOLOAD
  14
  15 my @faked = qw/round_mode accuracy precision div_scale/;
  16 use vars qw/$VERSION $AUTOLOAD $_lite/;         # _lite for testsuite
  17
  18 sub AUTOLOAD
  19   {
  20   my $name = $AUTOLOAD;
  21
  22   $name =~ s/.*:://;    # split package
  23   no strict 'refs';
  24   foreach my $n (@faked)
  25     {
  26     if ($n eq $name)
  27       {
  28       *{"bignum::$name"} = sub
  29         {
  30         my $self = shift;
  31         no strict 'refs';
  32         if (defined $_[0])
  33           {
  34           Math::BigInt->$name($_[0]);
  35           Math::BigFloat->$name($_[0]);
  36           }
  37         return Math::BigInt->$name();
  38         };
  39       return &$name;
  40       }
  41     }
  42
  43   # delayed load of Carp and avoid recursion
  44   require Carp;
  45   Carp::croak ("Can't call bignum\-\>$name, not a valid method");
  46   }
  47
  48 sub upgrade
  49   {
  50   my $self = shift;
  51   no strict 'refs';
  52 #  if (defined $_[0])
  53 #    {
  54 #    $Math::BigInt::upgrade = $_[0];
  55 #    $Math::BigFloat::upgrade = $_[0];
  56 #    }
  57   return $Math::BigInt::upgrade;
  58   }
  59
  60 sub import
  61   {
  62   my $self = shift;
  63
  64   # some defaults
  65   my $lib = 'Calc';
  66   my $upgrade = 'Math::BigFloat';
  67   my $downgrade = 'Math::BigInt';
  68
  69   my @import = ( ':constant' );                         # drive it w/ constant
  70   my @a = @_; my $l = scalar @_; my $j = 0;
  71   my ($ver,$trace);                                     # version? trace?
  72   my ($a,$p);                                           # accuracy, precision
  73   for ( my $i = 0; $i < $l ; $i++,$j++ )
  74     {
  75     if ($_[$i] eq 'upgrade')
  76       {
  77       # this causes upgrading
  78       $upgrade = $_[$i+1];              # or undef to disable
  79       my $s = 2; $s = 1 if @a-$j < 2;   # avoid "can not modify non-existant..."
  80       splice @a, $j, $s; $j -= $s; $i++;
  81       }
  82     elsif ($_[$i] eq 'downgrade')
  83       {
  84       # this causes downgrading
  85       $downgrade = $_[$i+1];            # or undef to disable
  86       my $s = 2; $s = 1 if @a-$j < 2;   # avoid "can not modify non-existant..."
  87       splice @a, $j, $s; $j -= $s; $i++;
  88       }
  89     elsif ($_[$i] =~ /^(l|lib)$/)
  90       {
  91       # this causes a different low lib to take care...
  92       $lib = $_[$i+1] || '';
  93       my $s = 2; $s = 1 if @a-$j < 2;   # avoid "can not modify non-existant..."
  94       splice @a, $j, $s; $j -= $s; $i++;
  95       }
  96     elsif ($_[$i] =~ /^(a|accuracy)$/)
  97       {
  98       $a = $_[$i+1];
  99       my $s = 2; $s = 1 if @a-$j < 2;   # avoid "can not modify non-existant..."
 100       splice @a, $j, $s; $j -= $s; $i++;
 101       }
 102     elsif ($_[$i] =~ /^(p|precision)$/)
 103       {
 104       $p = $_[$i+1];
 105       my $s = 2; $s = 1 if @a-$j < 2;   # avoid "can not modify non-existant..."
 106       splice @a, $j, $s; $j -= $s; $i++;
 107       }
 108     elsif ($_[$i] =~ /^(v|version)$/)
 109       {
 110       $ver = 1;
 111       splice @a, $j, 1; $j --;
 112       }
 113     elsif ($_[$i] =~ /^(t|trace)$/)
 114       {
 115       $trace = 1;
 116       splice @a, $j, 1; $j --;
 117       }
 118     else { die "unknown option $_[$i]"; }
 119     }
 120   my $class;
 121   $_lite = 0;                                   # using M::BI::L ?
 122   if ($trace)
 123     {
 124     require Math::BigInt::Trace; $class = 'Math::BigInt::Trace';
 125     $upgrade = 'Math::BigFloat::Trace';
 126     }
 127   else
 128     {
 129     # see if we can find Math::BigInt::Lite
 130     if (!defined $a && !defined $p)             # rounding won't work to well
 131       {
 132       eval 'require Math::BigInt::Lite;';
 133       if ($@ eq '')
 134         {
 135         @import = ( );                          # :constant in Lite, not MBI
 136         Math::BigInt::Lite->import( ':constant' );
 137         $_lite= 1;                              # signal okay
 138         }
 139       }
 140     require Math::BigInt if $_lite == 0;        # not already loaded?
 141     $class = 'Math::BigInt';                    # regardless of MBIL or not
 142     }
 143   # Math::BigInt::Trace or plain Math::BigInt
 144   $class->import(@import, upgrade => $upgrade, lib => $lib);
 145
 146   if ($trace)
 147     {
 148     require Math::BigFloat::Trace; $class = 'Math::BigFloat::Trace';
 149     $downgrade = 'Math::BigInt::Trace';
 150     }
 151   else
 152     {
 153     require Math::BigFloat; $class = 'Math::BigFloat';
 154     }
 155   $class->import(':constant','downgrade',$downgrade);
 156
 157   bignum->accuracy($a) if defined $a;
 158   bignum->precision($p) if defined $p;
 159   if ($ver)
 160     {
 161     print "bignum\t\t\t v$VERSION\n";
 162     print "Math::BigInt::Lite\t v$Math::BigInt::Lite::VERSION\n" if $_lite;
 163     print "Math::BigInt\t\t v$Math::BigInt::VERSION";
 164     my $config = Math::BigInt->config();
 165     print " lib => $config->{lib} v$config->{lib_version}\n";
 166     print "Math::BigFloat\t\t v$Math::BigFloat::VERSION\n";
 167     exit;
 168     }
 169   }
 170
 171 1;
 172
 173 __END__
 174
 175 =head1 NAME
 176
 177 bignum - Transparent BigNumber support for Perl
 178
 179 =head1 SYNOPSIS
 180
 181   use bignum;
 182
 183   $x = 2 + 4.5,"\n";                    # BigFloat 6.5
 184   print 2 ** 512 * 0.1;                 # really is what you think it is
 185
 186 =head1 DESCRIPTION
 187
 188 All operators (including basic math operations) are overloaded. Integer and
 189 floating-point constants are created as proper BigInts or BigFloats,
 190 respectively.
 191
 192 =head2 OPTIONS
 193
 194 bignum recognizes some options that can be passed while loading it via use.
 195 The options can (currently) be either a single letter form, or the long form.
 196 The following options exist:
 197
 198 =over 2
 199
 200 =item a or accuracy
 201
 202 This sets the accuracy for all math operations. The argument must be greater
 203 than or equal to zero. See Math::BigInt's bround() function for details.
 204
 205         perl -Mbignum=a,50 -le 'print sqrt(20)'
 206
 207 =item p or precision
 208
 209 This sets the precision for all math operations. The argument can be any
 210 integer. Negative values mean a fixed number of digits after the dot, while
 211 a positive value rounds to this digit left from the dot. 0 or 1 mean round to
 212 integer. See Math::BigInt's bfround() function for details.
 213
 214         perl -Mbignum=p,-50 -le 'print sqrt(20)'
 215
 216 =item t or trace
 217
 218 This enables a trace mode and is primarily for debugging bignum or
 219 Math::BigInt/Math::BigFloat.
 220
 221 =item l or lib
 222
 223 Load a different math lib, see L<MATH LIBRARY>.
 224
 225         perl -Mbignum=l,GMP -e 'print 2 ** 512'
 226
 227 Currently there is no way to specify more than one library on the command
 228 line. This will be hopefully fixed soon ;)
 229
 230 =item v or version
 231
 232 This prints out the name and version of all modules used and then exits.
 233
 234         perl -Mbignum=v -e ''
 235
 236 =head2 MATH LIBRARY
 237
 238 Math with the numbers is done (by default) by a module called
 239 Math::BigInt::Calc. This is equivalent to saying:
 240
 241         use bignum lib => 'Calc';
 242
 243 You can change this by using:
 244
 245         use bignum lib => 'BitVect';
 246
 247 The following would first try to find Math::BigInt::Foo, then
 248 Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:
 249
 250         use bignum lib => 'Foo,Math::BigInt::Bar';
 251
 252 Please see respective module documentation for further details.
 253
 254 =head2 INTERNAL FORMAT
 255
 256 The numbers are stored as objects, and their internals might change at anytime,
 257 especially between math operations. The objects also might belong to different
 258 classes, like Math::BigInt, or Math::BigFLoat. Mixing them together, even
 259 with normal scalars is not extraordinary, but normal and expected.
 260
 261 You should not depend on the internal format, all accesses must go through
 262 accessor methods. E.g. looking at $x->{sign} is not a bright idea since there
 263 is no guaranty that the object in question has such a hashkey, nor is a hash
 264 underneath at all.
 265
 266 =head2 SIGN
 267
 268 The sign is either '+', '-', 'NaN', '+inf' or '-inf' and stored seperately.
 269 You can access it with the sign() method.
 270
 271 A sign of 'NaN' is used to represent the result when input arguments are not
 272 numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively
 273 minus infinity. You will get '+inf' when dividing a positive number by 0, and
 274 '-inf' when dividing any negative number by 0.
 275
 276 =head2 METHODS
 277
 278 Since all numbers are now objects, you can use all functions that are part of
 279 the BigInt or BigFloat API. It is wise to use only the bxxx() notation, and not
 280 the fxxx() notation, though. This makes it possible that the underlying object
 281 might morph into a different class than BigFloat.
 282
 283 =head1 MODULES USED
 284
 285 C<bignum> is just a thin wrapper around various modules of the Math::BigInt
 286 family. Think of it as the head of the family, who runs the shop, and orders
 287 the others to do the work.
 288
 289 The following modules are currently used by bignum:
 290
 291         Math::BigInt::Lite      (for speed, and only if it is loadable)
 292         Math::BigInt
 293         Math::BigFloat
 294
 295 =head1 EXAMPLES
 296
 297 Some cool command line examples to impress the Python crowd ;)
 298
 299         perl -Mbignum -le 'print sqrt(33)'
 300         perl -Mbignum -le 'print 2*255'
 301         perl -Mbignum -le 'print 4.5+2*255'
 302         perl -Mbignum -le 'print 3/7 + 5/7 + 8/3'
 303         perl -Mbignum -le 'print 123->is_odd()'
 304         perl -Mbignum -le 'print log(2)'
 305         perl -Mbignum -le 'print 2 ** 0.5'
 306         perl -Mbignum=a,65 -le 'print 2 ** 0.2'
 307
 308 =head1 LICENSE
 309
 310 This program is free software; you may redistribute it and/or modify it under
 311 the same terms as Perl itself.
 312
 313 =head1 SEE ALSO
 314
 315 Especially L<bigrat> as in C<perl -Mbigrat -le 'print 1/3+1/4'>.
 316
 317 L<Math::BigFloat>, L<Math::BigInt>, L<Math::BigRat> and L<Math::Big> as well
 318 as L<Math::BigInt::BitVect>, L<Math::BigInt::Pari> and  L<Math::BigInt::GMP>.
 319
 320 =head1 AUTHORS
 321
 322 (C) by Tels L<http://bloodgate.com/> in early 2002.
 323
 324 =cut