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


-- | Numbers represented using scientific notation
--   
--   <tt>Data.Scientific</tt> provides a space efficient and arbitrary
--   precision scientific number type.
--   
--   <a>Scientific</a> numbers are represented using <a>scientific
--   notation</a>. It uses a coefficient <tt>c :: <a>Integer</a></tt> and a
--   base-10 exponent <tt>e :: <a>Int</a></tt> (do note that since we're
--   using an <a>Int</a> to represent the exponent these numbers aren't
--   truly arbitrary precision). A scientific number corresponds to the
--   <a>Fractional</a> number: <tt><a>fromInteger</a> c * 10 <a>^^</a>
--   e</tt>.
--   
--   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.3.1


-- | <tt>Data.Scientific</tt> provides a space efficient and arbitrary
--   precision scientific number type.
--   
--   <a>Scientific</a> numbers are represented using <a>scientific
--   notation</a>. It uses an <a>Integer</a> <a>coefficient</a> <tt>c</tt>
--   and an <a>Int</a> <a>base10Exponent</a> <tt>e</tt> (do note that since
--   we're using an <a>Int</a> to represent the exponent these numbers
--   aren't truly arbitrary precision). A scientific number corresponds to
--   the <a>Fractional</a> number: <tt><a>fromInteger</a> c * 10 <a>^^</a>
--   e</tt>.
--   
--   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.
--   
--   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

-- | <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
--   non-negative <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 Typeable Scientific
instance Data Scientific
instance Show Scientific
instance Read Scientific
instance RealFrac Scientific
instance Fractional Scientific
instance Real Scientific
instance Num Scientific
instance Ord Scientific
instance Eq Scientific
instance Hashable Scientific
instance NFData 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
