This file contains a short description of what the goals of this project are,
building guidelines etc. This was born after discussions with John Peacock, who
provided helpfull feedback.

* Favour correctness over speed
* Make your code maintable, so avoid Copy&Paste.
* Optimize more for the average case than the worst, while trying to avoid 
  performance hits for the worst case.
  The average case is more for longer numbers than short, based on the
  assumption that if you wanted to add 1 and 2 _fast_ together, you wouldn't
  use BigInt nor Perl, now would you? ;)
* Make subclassing as easy and painless as possible. This means clean
  inheritance and overload section, no C&P code etc.
* Make mixing of classes work, like in:

	$x = Math::BigFloat->new(10);
	$y = Math::BigInt->new(2);
	$z = $x / $y;			# $z = Math::BigFloat = 5

  See also BUGS.

##############################################################################
 Some thoughts about using Bit::Vector as under-the-hood package for BigInt:

Bit::Vector (BV) provides fast calculation routines in C, but some (possible)
problems remain. (Note: The same "problems" apply to other math packages in C)

+ Representation:

First, it uses base2, instead of base10 for the internal representation: 

* This means things like 2**1024 are much faster to calculate (basically a one
  padded by many zeros) than with MBI's way.
* OTOH printing a number needs to convert it to decimal, and this takes some
  time (even with sophisticated algorithmns like FFT). Printing the largest
  known prime (until today) takes some _dozend seconds_ on a 800 Mhz machine
  using a FFT in c implementation. Note that it is trivial to calculate the
  number 2**1024, the base2-to-base10 conversation is costly. MBI currently
  has it the other way round, calculation is very slow, but printing easy.
  The same time-limit applies in constructing numbers, because they will
  likely be given in base10 (although input numbers tend to be small).

It remains to be seen wether the "wasted" time in new() and bstr() is
compensated for in the faster calculation routines or not. 

Note: The current implementation using arrays has the same trade-off: slower
new() and bstr() compared to storing the number as string, but faster internal
calculation compared agains the original v0.01 BigInt. When doing benchmarks,
even for small numbers the "wasted" time in new() and bstr() is usually 
compensated for by the faster internal math, thus speeding up programs on the
average. F.i. factorial() is now about 2.6 times faster than with the old code
(of course it is still factor 30 away from a c-library like SSLeay::BN).

+ Sign:

BV also has two's-complement as negative numbers. This means neg() takes a
O(N) time going trough the entire number instead of simple flipping the sign.
(In new code, sub uses neg(), but with two-complement there is no overhead)

It is probably still better to still have an "external" sign and use only
positive BV's in calculation, this also would let us keep the current
implementation.

+ Auto-extend:

BV does not extend the operands automatically on overflow. So a wrapper must
extend the operand prior to the op, then do the calculation and then shrink
the result (normalisation) properly. (Or find out beforehand wether an overflow
would be possible, or ask B::V afterwards if an overflow happened, depending
on what B::V can deliver)

For add/sub:

 + take max( $x->length(), $y->length) + 1
 + add
 + shrink

For mul: max ($x->length(), $y->length())*2+1, mul, shrink, etc

All the wrappers overhead would make it pretty slow for small numbers, probably
even slower than it is now. So the real performance boost will come only for
really long numbers like 2**654321. It remains to be seen were the tradeoff
will occur, f.i. when the numbers must get insanly big to pay off, it is better
to use the old way, but if it is faster for relatively small numbers like
1234567890123456789, that is the way to go.

Of course I have not tried anything yet. Stand by...

##############################################################################

More to come later.

Please send me test-reports, your experiences with this and your ideas - I love
to hear about my work!

Tels <http://bloodgate.com/>
