upgrade bignum to v0.13: fix test failures and update docs

p4raw-id: //depot/perl@17779

3 files changed, 121 insertions, 12 deletions

diff --git a/lib/bignum.pm b/lib/bignum.pm
index 235f9d6a64..fb7db9f074 100644
--- a/lib/bignum.pm
+++ b/lib/bignum.pm
@@ -1,7 +1,7 @@
 package bignum;
 require 5.005;
 
-$VERSION = '0.12';
+$VERSION = '0.13';
 use Exporter;
 @EXPORT_OK 	= qw( ); 
 @EXPORT 	= qw( inf NaN ); 
@@ -196,6 +196,101 @@ All operators (including basic math operations) are overloaded. Integer and
 floating-point constants are created as proper BigInts or BigFloats,
 respectively.
 
+If you do 
+
+        use bignum;
+
+at the top of your script, Math::BigFloat and Math::BigInt will be loaded
+and any constant number will be converted to an object (Math::BigFloat for
+floats like 3.1415 and Math::BigInt for integers like 1234).
+
+So, the following line:
+
+        $x = 1234;
+
+creates actually a Math::BigInt and stores a reference to in $x.
+This happens transparently and behind your back, so to speak.
+
+You can see this with the following:
+
+        perl -Mbignum -le 'print ref(1234)'
+
+Don't worry if it says Math::BigInt::Lite, bignum and friends will use Lite
+if it is installed since it is faster for some operations. It will be
+automatically upgraded to BigInt whenever neccessary:
+
+        perl -Mbignum -le 'print ref(2**255)'
+
+This also means it is a bad idea to check for some specific package, since
+the actual contents of $x might be something unexpected. Due to the
+transparent way of bignum C<ref()> should not be neccessary, anyway.
+
+Since Math::BigInt and BigFloat also overload the normal math operations,
+the following line will still work:
+
+        perl -Mbignum -le 'print ref(1234+1234)'
+
+Since numbers are actually objects, you can call all the usual methods from
+BigInt/BigFloat on them. This even works to some extent on expressions:
+
+        perl -Mbignum -le '$x = 1234; print $x->bdec()'
+        perl -Mbignum -le 'print 1234->binc();'
+        perl -Mbignum -le 'print 1234->binc->badd(6);'
+        perl -Mbignum -le 'print +(1234)->binc()'
+
+(Note that print doesn't do what you expect if the expression starts with
+'(' hence the C<+>)
+
+You can even chain the operations together as usual:
+
+        perl -Mbignum -le 'print 1234->binc->badd(6);'
+        1241
+
+Under bignum (or bigint or bigrat), Perl will "upgrade" the numbers
+appropriately. This means that:
+
+        perl -Mbignum -le 'print 1234+4.5'
+        1238.5
+
+will work correctly. These mixed cases don't do always work when using
+Math::BigInt or Math::BigFloat alone, or at least not in the way normal Perl
+scalars work. 
+
+If you do want to work with large integers like under C<use integer;>, try
+C<use bigint;>:
+
+        perl -Mbigint -le 'print 1234.5+4.5'
+        1238
+
+There is also C<use bigrat;> which gives you big rationals:
+
+        perl -Mbigrat -le 'print 1234+4.1'
+        12381/10
+
+The entire upgrading/downgrading is still experimental and might not work
+as you expect or may even have bugs.
+
+You might get errors like this:
+
+        Can't use an undefined value as an ARRAY reference at
+        /usr/local/lib/perl5/5.8.0/Math/BigInt/Calc.pm line 864
+
+This means somewhere a routine got a BigFloat/Lite but expected a BigInt (or
+vice versa) and the upgrade/downgrad path was missing. This is a bug, please
+report it so that we can fix it.
+
+You might consider using just Math::BigInt or Math::BigFloat, since they
+allow you finer control over what get's done in which module/space. For
+instance, simple loop counters will be Math::BigInts under C<use bignum;> and
+this is slower than keeping them as Perl scalars:
+
+        perl -Mbignum -le 'for ($i = 0; $i < 10; $i++) { print ref($i); }'
+
+Please note the following does not work as expected (prints nothing), since
+overloading of '..' is not yet possible in Perl (as of v5.8.0):
+
+        perl -Mbignum -le 'for (1..2) { print ref($_); }'
+
 =head2 OPTIONS
 
 bignum recognizes some options that can be passed while loading it via use.
@@ -244,6 +339,11 @@ This prints out the name and version of all modules used and then exits.
 
 Beside import() and AUTOLOAD() there are only a few other methods.
 
+Since all numbers are now objects, you can use all functions that are part of
+the BigInt or BigFloat API. It is wise to use only the bxxx() notation, and not
+the fxxx() notation, though. This makes it possible that the underlying object
+might morph into a different class than BigFloat.
+
 =over 2
 
 =item inf()
@@ -303,13 +403,6 @@ numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively
 minus infinity. You will get '+inf' when dividing a positive number by 0, and
 '-inf' when dividing any negative number by 0.
 
-=head2 METHODS
-
-Since all numbers are now objects, you can use all functions that are part of
-the BigInt or BigFloat API. It is wise to use only the bxxx() notation, and not
-the fxxx() notation, though. This makes it possible that the underlying object
-might morph into a different class than BigFloat.
-
 =head1 MODULES USED
 
 C<bignum> is just a thin wrapper around various modules of the Math::BigInt
diff --git a/lib/bignum/t/bignum.t b/lib/bignum/t/bignum.t
index 21a70e39dc..32235ea2d5 100755
--- a/lib/bignum/t/bignum.t
+++ b/lib/bignum/t/bignum.t
@@ -35,8 +35,6 @@ ok (2/3,"0.6666666666666666666666666666666666666667");
 
 #ok (2 ** 0.5, 'NaN');	# should be sqrt(2);
 
-print "huh\n";
-
 ok (12->bfac(),479001600);
 
 # see if Math::BigFloat constant works
diff --git a/lib/bignum/t/bninfnan.t b/lib/bignum/t/bninfnan.t
index d097215b9e..9fac5bde55 100644
--- a/lib/bignum/t/bninfnan.t
+++ b/lib/bignum/t/bninfnan.t
@@ -8,8 +8,26 @@ use strict;
 BEGIN
   {
   $| = 1;
-  chdir 't' if -d 't';
-  unshift @INC, '../lib';
+  my $location = $0; $location =~ s/biinfnan.t//i;
+  if ($ENV{PERL_CORE})
+    {
+    @INC = qw(../lib);          # testing with the core distribution
+    }
+  else
+    {
+    unshift @INC, '../lib';     # for testing manually
+    }
+  if (-d 't')
+    {
+    chdir 't';
+    require File::Spec;
+    unshift @INC, File::Spec->catdir(File::Spec->updir, $location);
+    }
+  else
+    {
+    unshift @INC, $location;
+    }
+  print "# INC = @INC\n";
   plan tests => 26;
   }