Module documentation for 0.3.4.9

Data.Scientific provides the number type Scientific. Scientific numbers are
arbitrary precision and space efficient. They are represented using
scientific notation.
The implementation uses a coefficient c :: Integer and a base-10 exponent
e :: Int. A scientific number corresponds to the
Fractional number: fromInteger c * 10 ^^ e.

Note that since we're using an Int to represent the exponent these numbers
aren't truly arbitrary precision. I intend to change the type of the exponent
to Integer in a future release.

The main application of Scientific is to be used as the target of parsing
arbitrary precision numbers coming from an untrusted source. The advantages
over using Rational for this are that:

A Scientific is more efficient to construct. Rational numbers need to be
constructed using % which has to compute the gcd of the numerator and
denominator.

Scientific is safe against numbers with huge exponents. For example:
1e1000000000 :: Rational will fill up all space and crash your
program. Scientific works as expected:

read "1e1000000000" :: Scientific

1.0e1000000000

Also, the space usage of converting scientific numbers with huge exponents to
Integrals (like: Int) or RealFloats (like: Double or Float)
will always be bounded by the target type.

Changes

0.3.6.2 * Due to a regression introduced in 0.3.4.14 the RealFrac methods and floatingOrInteger became vulnerable to a space blowup when applied to scientifics with huge exponents. This has now been fixed again.

0.3.6.1 * Fix build on GHC < 8.

0.3.6.0 * Make the methods of the Hashable, Eq and Ord instances safe to use when applied to scientific numbers coming from untrusted sources. Previously these methods first converted their arguments to Rational before applying the operation. This is unsafe because converting a Scientific to a Rational could fill up all space and crash your program when the Scientific has a huge base10Exponent.

Do note that the hash computation of the Hashable Scientific instance has been changed because of this improvement!

* fromRational :: Rational -> Scientific now throws an error instead of diverging when applied to a repeating decimal. This does mean it will consume space linear in the number of digits of the resulting scientific. This makes "fromRational" and the other Fractional methods "recip" and "/" a bit safer to use.

* To get the old unsafe but more efficient behaviour the following function was added: unsafeFromRational :: Rational -> Scientific.

0.3.3.6 * Fixed bug in the x / y method for Scientific. Since I was using the default implementation: `x * recip y` the operation would diverge when `recip y` had an infinite decimal output. This shouldn't happen when the result of / is finite again. For example: 0.6 / 0.3 should yield 2.0.

This is now fixed by using the following implementation:

`x / y = fromRational $ toRational x / toRational y`

0.3.3.5 * Fixed bug when converting the Scientific: `scientific 0 someBigExponent` to a bounded Integral using toBoundedInteger or to a bounded RealFloat using toBoundedRealFloat. If someBigExponent was big enough to trigger the big-exponent protection the beforementioned functions didn't return 0.

This is fixed by explicitly handling a coefficient of 0.

0.3.3.4 * Relax upper version bounds of base and deepseq for the test suite and benchmarks.

0.3.2.2 * Enable package to link with integer-simple instead of integer-gmp using the -finteger-simple cabal flag. Courtesy of @k0ral.

0.3.2.1

* Parameterize inclusion of the Data.ByteString.Builder.Scientific module using the bytestring-builder flag. Disabling this flag allows building on GHC-7.0.4 which has bytestring-0.9 installed by default.

0.3.2.0

* Add the floatingOrInteger function * Fix build on GHC-7.0.4 * More efficient and better behaving magnitude computation * Lower the number of cached magnitudes to 324 (same as GHC.Float)

* Fix a DoS vulnerability that allowed an attacker to crash the process by sending a scientific with a huge exponent like 1e1000000000. * Fix various RealFrac methods. * Cache some powers of 10 to speed up the magnitude computation. * Normalize scientific numbers on construction. * Move the Text Builder to its own module & provide a ByteString builder * Added more documentation