-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Numbers represented using scientific notation
--   
--   <tt>Data.Scientific</tt> provides the number type <a>Scientific</a>.
--   Scientific numbers are arbitrary precision and space efficient. They
--   are represented using <a>scientific notation</a>. The implementation
--   uses a coefficient <tt>c :: <a>Integer</a></tt> and a base-10 exponent
--   <tt>e :: <a>Int</a></tt>. A scientific number corresponds to the
--   <a>Fractional</a> number: <tt><a>fromInteger</a> c * 10 <a>^^</a>
--   e</tt>.
--   
--   Note that since we're using an <a>Int</a> to represent the exponent
--   these numbers aren't truly arbitrary precision. I intend to change the
--   type of the exponent to <a>Integer</a> in a future release.
--   
--   The main application of <a>Scientific</a> is to be used as the target
--   of parsing arbitrary precision numbers coming from an untrusted
--   source. The advantages over using <a>Rational</a> for this are that:
--   
--   <ul>
--   <li>A <a>Scientific</a> is more efficient to construct. Rational
--   numbers need to be constructed using <a>%</a> which has to compute the
--   <a>gcd</a> of the <a>numerator</a> and <a>denominator</a>.</li>
--   <li><a>Scientific</a> is safe against numbers with huge exponents. For
--   example: <tt>1e1000000000 :: <a>Rational</a></tt> will fill up all
--   space and crash your program. Scientific works as expected:</li>
--   </ul>
--   
--   <pre>
--   &gt; read "1e1000000000" :: Scientific
--   1.0e1000000000
--   </pre>
--   
--   <ul>
--   <li>Also, the space usage of converting scientific numbers with huge
--   exponents to <tt><a>Integral</a>s</tt> (like: <a>Int</a>) or
--   <tt><a>RealFloat</a>s</tt> (like: <a>Double</a> or <a>Float</a>) will
--   always be bounded by the target type.</li>
--   </ul>
@package scientific
@version 0.3.4.2


-- | This module provides the number type <a>Scientific</a>. Scientific
--   numbers are arbitrary precision and space efficient. They are
--   represented using <a>scientific notation</a>. The implementation uses
--   an <a>Integer</a> <a>coefficient</a> <tt>c</tt> and an <a>Int</a>
--   <a>base10Exponent</a> <tt>e</tt>. A scientific number corresponds to
--   the <a>Fractional</a> number: <tt><a>fromInteger</a> c * 10 <a>^^</a>
--   e</tt>.
--   
--   Note that since we're using an <a>Int</a> to represent the exponent
--   these numbers aren't truly arbitrary precision. I intend to change the
--   type of the exponent to <a>Integer</a> in a future release.
--   
--   The main application of <a>Scientific</a> is to be used as the target
--   of parsing arbitrary precision numbers coming from an untrusted
--   source. The advantages over using <a>Rational</a> for this are that:
--   
--   <ul>
--   <li>A <a>Scientific</a> is more efficient to construct. Rational
--   numbers need to be constructed using <a>%</a> which has to compute the
--   <a>gcd</a> of the <a>numerator</a> and <a>denominator</a>.</li>
--   <li><a>Scientific</a> is safe against numbers with huge exponents. For
--   example: <tt>1e1000000000 :: <a>Rational</a></tt> will fill up all
--   space and crash your program. Scientific works as expected:</li>
--   </ul>
--   
--   <pre>
--   &gt; read "1e1000000000" :: Scientific
--   1.0e1000000000
--   </pre>
--   
--   <ul>
--   <li>Also, the space usage of converting scientific numbers with huge
--   exponents to <tt><a>Integral</a>s</tt> (like: <a>Int</a>) or
--   <tt><a>RealFloat</a>s</tt> (like: <a>Double</a> or <a>Float</a>) will
--   always be bounded by the target type.</li>
--   </ul>
--   
--   <i>WARNING:</i> Although <tt>Scientific</tt> is an instance of
--   <a>Fractional</a>, the methods are only partially defined!
--   Specifically <a>recip</a> and <a>/</a> will diverge (i.e. loop and
--   consume all space) when their outputs have an infinite decimal
--   expansion. <a>fromRational</a> will diverge when the input
--   <a>Rational</a> has an infinite decimal expansion. Consider using
--   <a>fromRationalRepetend</a> for these rationals which will detect the
--   repetition and indicate where it starts.
--   
--   This module is designed to be imported qualified:
--   
--   <pre>
--   import Data.Scientific as Scientific
--   </pre>
module Data.Scientific

-- | An arbitrary-precision number represented using <a>scientific
--   notation</a>.
--   
--   This type describes the set of all <tt><a>Real</a>s</tt> which have a
--   finite decimal expansion.
--   
--   A scientific number with <a>coefficient</a> <tt>c</tt> and
--   <a>base10Exponent</a> <tt>e</tt> corresponds to the <a>Fractional</a>
--   number: <tt><a>fromInteger</a> c * 10 <a>^^</a> e</tt>
data Scientific

-- | <tt>scientific c e</tt> constructs a scientific number which
--   corresponds to the <a>Fractional</a> number: <tt><a>fromInteger</a> c
--   * 10 <a>^^</a> e</tt>.
scientific :: Integer -> Int -> Scientific

-- | The coefficient of a scientific number.
--   
--   Note that this number is not necessarily normalized, i.e. it could
--   contain trailing zeros.
--   
--   Scientific numbers are automatically normalized when pretty printed or
--   in <a>toDecimalDigits</a>.
--   
--   Use <a>normalize</a> to do manual normalization.
coefficient :: Scientific -> Integer

-- | The base-10 exponent of a scientific number.
base10Exponent :: Scientific -> Int

-- | Return <a>True</a> if the scientific is a floating point, <a>False</a>
--   otherwise.
--   
--   Also see: <a>floatingOrInteger</a>.
isFloating :: Scientific -> Bool

-- | Return <a>True</a> if the scientific is an integer, <a>False</a>
--   otherwise.
--   
--   Also see: <a>floatingOrInteger</a>.
isInteger :: Scientific -> Bool

-- | Like <a>fromRational</a>, this function converts a <a>Rational</a> to
--   a <a>Scientific</a> but instead of diverging (i.e loop and consume all
--   space) on <a>repeating decimals</a> it detects the repeating part, the
--   <i>repetend</i>, and returns where it starts.
--   
--   To detect the repetition this function consumes space linear in the
--   number of digits in the resulting scientific. In order to bound the
--   space usage an optional limit can be specified. If the number of
--   digits reaches this limit <tt>Left (s, r)</tt> will be returned. Here
--   <tt>s</tt> is the <a>Scientific</a> constructed so far and <tt>r</tt>
--   is the remaining <a>Rational</a>. <tt>toRational s + r</tt> yields the
--   original <a>Rational</a>
--   
--   If the limit is not reached or no limit was specified <tt>Right (s,
--   mbRepetendIx)</tt> will be returned. Here <tt>s</tt> is the
--   <a>Scientific</a> without any repetition and <tt>mbRepetendIx</tt>
--   specifies if and where in the fractional part the repetend begins.
--   
--   For example:
--   
--   <pre>
--   fromRationalRepetend Nothing (1 % 28) == Right (3.571428e-2, Just 2)
--   </pre>
--   
--   This represents the repeating decimal:
--   <tt>0.03571428571428571428...</tt> which is sometimes also
--   unambiguously denoted as <tt>0.03(571428)</tt>. Here the repetend is
--   enclosed in parentheses and starts at the 3rd digit (index 2) in the
--   fractional part. Specifying a limit results in the following:
--   
--   <pre>
--   fromRationalRepetend (Just 4) (1 % 28) == Left (3.5e-2, 1 % 1400)
--   </pre>
--   
--   You can expect the following property to hold.
--   
--   <pre>
--   forall (mbLimit :: Maybe Int) (r :: Rational).
--   r == (case <a>fromRationalRepetend</a> mbLimit r of
--          Left (s, r') -&gt; toRational s + r'
--          Right (s, mbRepetendIx) -&gt;
--            case mbRepetendIx of
--              Nothing         -&gt; toRational s
--              Just repetendIx -&gt; <a>toRationalRepetend</a> s repetendIx)
--   </pre>
fromRationalRepetend :: Maybe Int -> Rational -> Either (Scientific, Rational) (Scientific, Maybe Int)

-- | Converts a <a>Scientific</a> with a <i>repetend</i> (a repeating part
--   in the fraction), which starts at the given index, into its
--   corresponding <a>Rational</a>.
--   
--   For example to convert the repeating decimal <tt>0.03(571428)</tt> you
--   would use: <tt>toRationalRepetend 0.03571428 2 == 1 % 28</tt>
--   
--   Preconditions for <tt>toRationalRepetend s r</tt>:
--   
--   <ul>
--   <li><pre>r &gt;= 0</pre></li>
--   <li><pre>r &lt; -(base10Exponent s)</pre></li>
--   </ul>
--   
--   The formula to convert the <tt>Scientific</tt> <tt>s</tt> with a
--   repetend starting at index <tt>r</tt> is described in the paper:
--   <a>turning_repeating_decimals_into_fractions.pdf</a> and is defined as
--   follows:
--   
--   <pre>
--     (fromInteger nonRepetend + repetend % nines) /
--     fromInteger (10^^r)
--   where
--     c  = coefficient s
--     e  = base10Exponent s
--   
--     -- Size of the fractional part.
--     f = (-e)
--   
--     -- Size of the repetend.
--     n = f - r
--   
--     m = 10^^n
--   
--     (nonRepetend, repetend) = c `quotRem` m
--   
--     nines = m - 1
--   </pre>
--   
--   Also see: <a>fromRationalRepetend</a>.
toRationalRepetend :: Scientific -> Int -> Rational

-- | <tt>floatingOrInteger</tt> determines if the scientific is floating
--   point or integer. In case it's floating-point the scientific is
--   converted to the desired <a>RealFloat</a> using <a>toRealFloat</a>.
--   
--   Also see: <a>isFloating</a> or <a>isInteger</a>.
floatingOrInteger :: (RealFloat r, Integral i) => Scientific -> Either r i

-- | Safely convert a <a>Scientific</a> number into a <a>RealFloat</a>
--   (like a <a>Double</a> or a <a>Float</a>).
--   
--   Note that this function uses <a>realToFrac</a>
--   (<tt><a>fromRational</a> . <a>toRational</a></tt>) internally but it
--   guards against computing huge Integer magnitudes (<tt>10^e</tt>) that
--   could fill up all space and crash your program. If the
--   <a>base10Exponent</a> of the given <a>Scientific</a> is too big or too
--   small to be represented in the target type, Infinity or 0 will be
--   returned respectively. Use <a>toBoundedRealFloat</a> which explicitly
--   handles this case by returning <a>Left</a>.
--   
--   Always prefer <a>toRealFloat</a> over <a>realToFrac</a> when
--   converting from scientific numbers coming from an untrusted source.
toRealFloat :: (RealFloat a) => Scientific -> a

-- | Preciser version of <a>toRealFloat</a>. If the <a>base10Exponent</a>
--   of the given <a>Scientific</a> is too big or too small to be
--   represented in the target type, Infinity or 0 will be returned as
--   <a>Left</a>.
toBoundedRealFloat :: (RealFloat a) => Scientific -> Either a a

-- | Convert a <a>Scientific</a> to a bounded integer.
--   
--   If the given <a>Scientific</a> doesn't fit in the target
--   representation, it will return <a>Nothing</a>.
--   
--   This function also guards against computing huge Integer magnitudes
--   (<tt>10^e</tt>) that could fill up all space and crash your program.
toBoundedInteger :: (Integral i, Bounded i) => Scientific -> Maybe i

-- | Convert a <a>RealFloat</a> (like a <a>Double</a> or <a>Float</a>) into
--   a <a>Scientific</a> number.
--   
--   Note that this function uses <a>floatToDigits</a> to compute the
--   digits and exponent of the <a>RealFloat</a> number. Be aware that the
--   algorithm used in <a>floatToDigits</a> doesn't work as expected for
--   some numbers, e.g. as the <a>Double</a> <tt>1e23</tt> is converted to
--   <tt>9.9999999999999991611392e22</tt>, and that value is shown as
--   <tt>9.999999999999999e22</tt> rather than the shorter <tt>1e23</tt>;
--   the algorithm doesn't take the rounding direction for values exactly
--   half-way between two adjacent representable values into account, so if
--   you have a value with a short decimal representation exactly half-way
--   between two adjacent representable values, like <tt>5^23*2^e</tt> for
--   <tt>e</tt> close to 23, the algorithm doesn't know in which direction
--   the short decimal representation would be rounded and computes more
--   digits
fromFloatDigits :: (RealFloat a) => a -> Scientific

-- | Like <a>show</a> but provides rendering options.
formatScientific :: FPFormat -> Maybe Int -> Scientific -> String

-- | Control the rendering of floating point numbers.
data FPFormat :: *

-- | Scientific notation (e.g. <tt>2.3e123</tt>).
Exponent :: FPFormat

-- | Standard decimal notation.
Fixed :: FPFormat

-- | Use decimal notation for values between <tt>0.1</tt> and
--   <tt>9,999,999</tt>, and scientific notation otherwise.
Generic :: FPFormat

-- | Similar to <a>floatToDigits</a>, <tt>toDecimalDigits</tt> takes a
--   positive <a>Scientific</a> number, and returns a list of digits and a
--   base-10 exponent. In particular, if <tt>x&gt;=0</tt>, and
--   
--   <pre>
--   toDecimalDigits x = ([d1,d2,...,dn], e)
--   </pre>
--   
--   then
--   
--   <ol>
--   <li><pre>n &gt;= 1</pre></li>
--   <li><pre>x = 0.d1d2...dn * (10^^e)</pre></li>
--   <li><pre>0 &lt;= di &lt;= 9</pre></li>
--   <li><pre>null $ takeWhile (==0) $ reverse [d1,d2,...,dn]</pre></li>
--   </ol>
--   
--   The last property means that the coefficient will be normalized, i.e.
--   doesn't contain trailing zeros.
toDecimalDigits :: Scientific -> ([Int], Int)

-- | Normalize a scientific number by dividing out powers of 10 from the
--   <a>coefficient</a> and incrementing the <a>base10Exponent</a> each
--   time.
--   
--   You should rarely have a need for this function since scientific
--   numbers are automatically normalized when pretty-printed and in
--   <a>toDecimalDigits</a>.
normalize :: Scientific -> Scientific
instance Data.Data.Data Data.Scientific.Scientific
instance Control.DeepSeq.NFData Data.Scientific.Scientific
instance Data.Hashable.Class.Hashable Data.Scientific.Scientific
instance Data.Binary.Class.Binary Data.Scientific.Scientific
instance GHC.Classes.Eq Data.Scientific.Scientific
instance GHC.Classes.Ord Data.Scientific.Scientific
instance GHC.Num.Num Data.Scientific.Scientific
instance GHC.Real.Real Data.Scientific.Scientific
instance GHC.Real.Fractional Data.Scientific.Scientific
instance GHC.Real.RealFrac Data.Scientific.Scientific
instance GHC.Read.Read Data.Scientific.Scientific
instance GHC.Show.Show Data.Scientific.Scientific

module Data.Text.Lazy.Builder.Scientific

-- | A <tt>Text</tt> <tt>Builder</tt> which renders a scientific number to
--   full precision, using standard decimal notation for arguments whose
--   absolute value lies between <tt>0.1</tt> and <tt>9,999,999</tt>, and
--   scientific notation otherwise.
scientificBuilder :: Scientific -> Builder

-- | Like <a>scientificBuilder</a> but provides rendering options.
formatScientificBuilder :: FPFormat -> Maybe Int -> Scientific -> Builder

-- | Control the rendering of floating point numbers.
data FPFormat :: *

-- | Scientific notation (e.g. <tt>2.3e123</tt>).
Exponent :: FPFormat

-- | Standard decimal notation.
Fixed :: FPFormat

-- | Use decimal notation for values between <tt>0.1</tt> and
--   <tt>9,999,999</tt>, and scientific notation otherwise.
Generic :: FPFormat

module Data.ByteString.Builder.Scientific

-- | A <tt>ByteString</tt> <tt>Builder</tt> which renders a scientific
--   number to full precision, using standard decimal notation for
--   arguments whose absolute value lies between <tt>0.1</tt> and
--   <tt>9,999,999</tt>, and scientific notation otherwise.
scientificBuilder :: Scientific -> Builder

-- | Like <a>scientificBuilder</a> but provides rendering options.
formatScientificBuilder :: FPFormat -> Maybe Int -> Scientific -> Builder

-- | Control the rendering of floating point numbers.
data FPFormat :: *

-- | Scientific notation (e.g. <tt>2.3e123</tt>).
Exponent :: FPFormat

-- | Standard decimal notation.
Fixed :: FPFormat

-- | Use decimal notation for values between <tt>0.1</tt> and
--   <tt>9,999,999</tt>, and scientific notation otherwise.
Generic :: FPFormat
