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


-- | Alternative faster String representations for Double and Float,
--   String representations for more general numeric types.
--   
--   The String representations provided by this package are generally
--   longer than show's output, which constructs the shortest string that
--   is parsed as the original number by read. This requires some
--   time-consuming checks, so show is slow for floating-point numbers. By
--   producing a digit-string guaranteed to be long enough to uniquely
--   determine the number without caring whether there's a shorter
--   representation, the display functions of this package can be faster,
--   sometimes by a big margin. Text.FShow.Raw provides building blocks for
--   representations of numeric types which don't belong to RealFloat but
--   have some of its functionality. The bulk of the code is a minor
--   modification of code from the base package, whence the GHC License is
--   included as an extra-source-file.
@package floatshow
@version 0.2.4


-- | Faster <a>String</a> representations for floating point types. The
--   code is largely taken from code in <a>GHC.Float</a> and the
--   <a>Show</a> instance of <a>Integer</a> in <a>GHC.Num</a> to get the
--   sequence of digits.
module Text.FShow.RealFloat

-- | A duplicate of the <a>Show</a> class.
class FShow a
fshow :: FShow a => a -> String
fshowsPrec :: FShow a => Int -> a -> ShowS
fshowList :: FShow a => [a] -> ShowS

-- | Same as <tt><a>shows</a></tt>, but using an <a>FShow</a> instance.
fshows :: FShow a => a -> ShowS

-- | Class for specifying display parameters. The type <tt>a</tt> is
--   supposed to be an IEEE-ish (real) floating-point type with
--   floating-point radix 2, such that the mantissa returned by
--   <a>decodeFloat</a> satisfies
--   
--   <pre>
--   2^(<a>binExp</a> x) &lt;= <a>fst</a> (<a>decodeFloat</a> x) &lt; 2^(<a>binExp</a> x + 1)
--   </pre>
--   
--   for <tt>x &gt; 0</tt>, so <tt><a>binExp</a> x = <a>floatDigits</a> x -
--   1</tt>. The number of decimal digits that may be required is
--   calculated with the formula
--   
--   <pre>
--   <a>decDigits</a> x = 2 + <a>floor</a> (<a>floatDigits</a> x * <a>logBase</a> 10 2).
--   </pre>
--   
--   The default implementation uses an approximation of <tt><a>logBase</a>
--   10 2</tt> sufficient for mantissae of up to several thousand bits.
--   Nevertheless, hardcoding the values in instance declarations may yield
--   better performance.
class (RealFloat a) => DispFloat a

-- | The number of decimal digits that may be needed to uniquely determine
--   a value of type <tt>a</tt>. For faster conversions which need not
--   satisfy
--   
--   <pre>
--   x == <a>read</a> (<a>fshow</a> x)
--   </pre>
--   
--   a smaller value can be given.
decDigits :: DispFloat a => a -> Int

-- | The base 2 logarithm of the mantissa returned by
--   <tt><a>decodeFloat</a> x</tt> for <tt>x &gt; 0</tt>.
binExp :: DispFloat a => a -> Int

-- | Show a signed <a>DispFloat</a> value 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. Analogous to <tt><tt>showFloat</tt></tt> from
--   <a>GHC.Float</a>.
fshowFloat :: (DispFloat a) => a -> ShowS

-- | Show a signed <a>DispFloat</a> value using scientific (exponential)
--   notation (e.g. <tt>2.45e2</tt>, <tt>1.5e-3</tt>).
--   
--   In the call <tt><a>fshowEFloat</a> digs val</tt>, if <tt>digs</tt> is
--   <a>Nothing</a>, the value is shown to full precision; if <tt>digs</tt>
--   is <tt><a>Just</a> d</tt>, then <tt><a>max</a> 1 d</tt> digits after
--   the decimal point are shown. Analogous to <tt><tt>showEFloat</tt></tt>
--   from <a>Numeric</a>.
fshowEFloat :: (DispFloat a) => Maybe Int -> a -> ShowS

-- | Show a signed <a>DispFloat</a> value using standard decimal notation
--   (e.g. <tt>245000</tt>, <tt>0.0015</tt>).
--   
--   In the call <tt><a>fshowFFloat</a> digs val</tt>, if <tt>digs</tt> is
--   <a>Nothing</a>, the value is shown to full precision; if <tt>digs</tt>
--   is <tt><a>Just</a> d</tt>, then <tt><a>max</a> 0 d</tt> digits after
--   the decimal point are shown. Analogous to <tt><tt>showFFloat</tt></tt>
--   from <a>Numeric</a>.
fshowFFloat :: (DispFloat a) => Maybe Int -> a -> ShowS

-- | Show a signed <a>DispFloat</a> value 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.
--   
--   In the call <tt><a>fshowGFloat</a> digs val</tt>, if <tt>digs</tt> is
--   <a>Nothing</a>, the value is shown to full precision; if <tt>digs</tt>
--   is <tt><a>Just</a> d</tt>, then <tt><a>max</a> 1 d</tt> digits after
--   the decimal point are shown. Analogous to <tt><tt>showGFloat</tt></tt>
--   from <a>Numeric</a>.
fshowGFloat :: (DispFloat a) => Maybe Int -> a -> ShowS

-- | newtype wrapper for <a>Double</a>. The <a>Show</a> (and <a>FShow</a>)
--   instance displays numbers rounded to seven significant digits.
newtype Double7
D7 :: Double -> Double7

-- | newtype wrapper for <a>Double</a>. The <a>Show</a> (and <a>FShow</a>)
--   instance displays all significant digits.
newtype FullDouble
FD :: Double -> FullDouble
[unFD] :: FullDouble -> Double

-- | newtype wrapper for <a>Float</a>. The <a>Show</a> (and <a>FShow</a>)
--   instance displays numbers rounded to seven significant digits.
newtype Float7
F7 :: Float -> Float7

-- | newtype wrapper for <a>Double</a>. The <a>Show</a> (and <a>FShow</a>)
--   instance displays all significant digits.
newtype FullFloat
FF :: Float -> FullFloat
[unFF] :: FullFloat -> Float
instance GHC.Float.RealFloat Text.FShow.RealFloat.FullFloat
instance GHC.Float.Floating Text.FShow.RealFloat.FullFloat
instance GHC.Real.RealFrac Text.FShow.RealFloat.FullFloat
instance GHC.Real.Real Text.FShow.RealFloat.FullFloat
instance GHC.Real.Fractional Text.FShow.RealFloat.FullFloat
instance GHC.Num.Num Text.FShow.RealFloat.FullFloat
instance GHC.Classes.Ord Text.FShow.RealFloat.FullFloat
instance GHC.Classes.Eq Text.FShow.RealFloat.FullFloat
instance GHC.Float.RealFloat Text.FShow.RealFloat.Float7
instance GHC.Float.Floating Text.FShow.RealFloat.Float7
instance GHC.Real.RealFrac Text.FShow.RealFloat.Float7
instance GHC.Real.Real Text.FShow.RealFloat.Float7
instance GHC.Real.Fractional Text.FShow.RealFloat.Float7
instance GHC.Num.Num Text.FShow.RealFloat.Float7
instance GHC.Classes.Ord Text.FShow.RealFloat.Float7
instance GHC.Classes.Eq Text.FShow.RealFloat.Float7
instance GHC.Float.RealFloat Text.FShow.RealFloat.FullDouble
instance GHC.Float.Floating Text.FShow.RealFloat.FullDouble
instance GHC.Real.RealFrac Text.FShow.RealFloat.FullDouble
instance GHC.Real.Real Text.FShow.RealFloat.FullDouble
instance GHC.Real.Fractional Text.FShow.RealFloat.FullDouble
instance GHC.Num.Num Text.FShow.RealFloat.FullDouble
instance GHC.Classes.Ord Text.FShow.RealFloat.FullDouble
instance GHC.Classes.Eq Text.FShow.RealFloat.FullDouble
instance GHC.Float.RealFloat Text.FShow.RealFloat.Double7
instance GHC.Float.Floating Text.FShow.RealFloat.Double7
instance GHC.Real.RealFrac Text.FShow.RealFloat.Double7
instance GHC.Real.Real Text.FShow.RealFloat.Double7
instance GHC.Real.Fractional Text.FShow.RealFloat.Double7
instance GHC.Num.Num Text.FShow.RealFloat.Double7
instance GHC.Classes.Ord Text.FShow.RealFloat.Double7
instance GHC.Classes.Eq Text.FShow.RealFloat.Double7
instance Text.FShow.RealFloat.FShow Text.FShow.RealFloat.Double7
instance Text.FShow.RealFloat.FShow Text.FShow.RealFloat.FullDouble
instance Text.FShow.RealFloat.FShow Text.FShow.RealFloat.Float7
instance Text.FShow.RealFloat.FShow Text.FShow.RealFloat.FullFloat
instance Text.FShow.RealFloat.FShow GHC.Types.Double
instance Text.FShow.RealFloat.FShow GHC.Types.Float
instance Text.FShow.RealFloat.FShow a => Text.FShow.RealFloat.FShow [a]
instance Text.FShow.RealFloat.DispFloat Text.FShow.RealFloat.FullFloat
instance GHC.Show.Show Text.FShow.RealFloat.FullFloat
instance GHC.Read.Read Text.FShow.RealFloat.FullFloat
instance Text.FShow.RealFloat.DispFloat Text.FShow.RealFloat.Float7
instance GHC.Show.Show Text.FShow.RealFloat.Float7
instance Text.FShow.RealFloat.DispFloat Text.FShow.RealFloat.FullDouble
instance GHC.Show.Show Text.FShow.RealFloat.FullDouble
instance GHC.Read.Read Text.FShow.RealFloat.FullDouble
instance Text.FShow.RealFloat.DispFloat Text.FShow.RealFloat.Double7
instance GHC.Show.Show Text.FShow.RealFloat.Double7
instance Text.FShow.RealFloat.DispFloat GHC.Types.Double
instance Text.FShow.RealFloat.DispFloat GHC.Types.Float


-- | Lower level conversion of base-2 numbers to base-10 representations.
--   These functions can be used to define <a>Show</a> instances for types
--   which don't support the full <a>RealFloat</a> interface but have an
--   analogue to <a>decodeFloat</a> (and maybe to <a>isNaN</a>,
--   <a>isInfinite</a> and <a>isNegativeZero</a>).
module Text.FShow.Raw

-- | Class for types whose values can be decoded into the form <tt>m *
--   2^e</tt> with an <a>Integer</a> mantissa <tt>m</tt> and an <a>Int</a>
--   exponent <tt>e</tt>.
--   
--   Minimal complete definition: one of <a>decode</a> and <a>decodeL</a>.
--   
--   It is strongly recommended to override the default implementation of
--   <a>showDigits</a> if the datatype allows distinguishing values without
--   using an exact representation.
class BinDecode a

-- | <a>decode</a> is analogous to <a>decodeFloat</a>.
decode :: BinDecode a => a -> (Integer, Int)

-- | <a>decodeL</a> gives the integer base-<tt>2</tt> logarithm of the
--   mantissa in addition to the result of <a>decode</a>. If the absolute
--   value of the mantissa always has the same highest set bit (excepting
--   <tt>0</tt>), specifying that as a constant will be faster than
--   calculating the logarithm for each individual mantissa. If <tt>x =
--   m*2^e</tt> with <tt>m /= 0</tt>, then <tt><a>decodeL</a> x ==
--   (<a>integerLog2</a> (<a>abs</a> m), m, e)</tt> must hold.
decodeL :: BinDecode a => a -> (Int, Integer, Int)

-- | The number of significant digits needed to uniquely determine the
--   value (or however many digits are desired). Usually, <a>showDigits</a>
--   will be a constant function, but that is not necessary. However, all
--   values of <a>showDigits</a> must be positive.
--   
--   If the mantissa always has the same highest bit, <tt>highBit</tt>, set
--   when it is nonzero,
--   
--   <pre>
--   <a>showDigits</a> _ = 2 + <a>floor</a> ((highBit+1) * <a>logBase</a> 10 2)
--   </pre>
--   
--   is sufficient to make the values and formatted <a>String</a>s uniquely
--   determine each other and in general this is the smallest number to
--   achieve that (calculate the number once and supply the result as a
--   constant).
--   
--   If the highest set bit of nonzero mantissae varies, things are not so
--   easy. If the width of mantissae is bounded, plugging the largest
--   possible value into the above formula works, but may yield an unduly
--   large number for common cases. Using the formula with <tt>highBit</tt>
--   determined by the mantissa almost works, but if the representation is
--   rounded at all, with sufficiently many bits in the mantissa, there
--   will be values between the original and the representation. So, with
--   mantissae of width varying over a large range, the only feasible way
--   of obtaining a bijection between values and their decimal
--   representations is printing to full precision in general, optionally
--   capping at the upper limit.
--   
--   The default implementation prints values exactly, which in general is
--   undesirable because it involves huge <a>Integer</a>s and long
--   representations.
showDigits :: BinDecode a => a -> Int

-- | Class for types whose values may be <tt>NaN</tt> or infinite and can
--   otherwise be decoded into the form <tt>m * 2^e</tt>.
class (Num a, Ord a, BinDecode a) => DecimalFormat a

-- | <tt><a>nanTest</a></tt> defaults to <tt><a>const</a> <a>False</a></tt>
nanTest :: DecimalFormat a => a -> Bool

-- | <tt><a>infTest</a></tt> defaults to <tt><a>const</a> <a>False</a></tt>
infTest :: DecimalFormat a => a -> Bool

-- | <tt><a>negTest</a> x</tt> defaults to <tt>x &lt; 0</tt>, it must be
--   overridden if negative zero has to be accounted for.
negTest :: DecimalFormat a => a -> Bool

-- | The Style in which to format the display <a>String</a>
data FormatStyle

-- | Display in scientific notation, e.g. <tt>1.234e-5</tt>
Exponent :: FormatStyle

-- | Display in standard decimal notation, e.g. <tt>0.0123</tt> or
--   <tt>123.456</tt>
Fixed :: FormatStyle

-- | Use <a>Fixed</a> for numbers with magnitude close enough to
--   <tt>1</tt>, <a>Exponent</a> otherwise. The default range for using
--   <a>Fixed</a> is <tt>0.1 &lt;= |x| &lt; 10^7</tt>, corresponding to
--   <tt><a>Generic</a> (<a>Just</a> (-1,7))</tt>.
Generic :: (Maybe (Int, Int)) -> FormatStyle

-- | <a>decimalFormat</a> is a slightly higher-level formatter, treating
--   the special cases of <tt>NaN</tt> and infinities.
decimalFormat :: DecimalFormat a => FormatStyle -> Maybe Int -> a -> String

-- | <a>binDecFormat</a> is the formatter for instances of the
--   <a>BinDecode</a> class. Any special values must be processed before it
--   is called. It fills in the missing arguments before calling
--   <a>rawFormat</a>.
binDecFormat :: BinDecode a => FormatStyle -> Maybe Int -> a -> String

-- | <a>rawFormat</a> is a low-level formatter. The sign is determined from
--   the sign of the mantissa.
rawFormat :: (a -> (Int, Integer, Int)) -> Int -> FormatStyle -> Maybe Int -> a -> String

-- | <a>fullRawFormat</a> is a low-level formatter producing an exact
--   representation of a value which can be decoded into the form <tt>m *
--   2^e</tt>.
fullRawFormat :: (a -> (Int, Integer, Int)) -> FormatStyle -> a -> String

-- | <a>formatDigits</a> builds the display <a>String</a> from the digits
--   and the exponent of a nonnegative number.
formatDigits :: FormatStyle -> Int -> Maybe Int -> [Int] -> Int -> String

-- | <a>posToDigits</a> converts a positive number into a list of digits
--   and an exponent. If <tt>x = 10^e*d_1.d_2...d_m...</tt> with <tt>d_1 /=
--   0</tt> and <tt>0 &lt;= d_i &lt;= 9</tt>, the result is
--   <tt>([d_1,d_2,...,d_m],e)</tt>, where <tt>m</tt> is one or two larger
--   than the number of requested digits, provided that <tt>2^(-70776)
--   &lt;= x &lt; 2^248236</tt> (with 64-bit <a>Int</a>s, the upper bound
--   is about <tt>2^1.3e9</tt>).
--   
--   The number <tt>x</tt> is (indirectly) given in the form <tt>mantissa *
--   2^exponent</tt>, similar to <a>encodeFloat</a>, as the final two
--   arguments. The second argument is the base-2 logarithm of the mantissa
--   and the first is the number of decimal digits needed to discriminate
--   between different numbers.
--   
--   In <tt><a>posToDigits</a> digs mlog mant exp</tt>, it is assumed that
--   
--   <ul>
--   <li><tt>digs &gt; 0</tt>, <tt>mlog &gt;= 0</tt>,</li>
--   <li><tt>2^mlog &lt;= mant &lt; 2^(mlog+1)</tt>.</li>
--   </ul>
--   
--   These assumptions are not checked, and if they're not satisfied, wrong
--   results or worse are the consequences. <i>You have been warned</i>.
--   
--   The digits argument may be smaller than would be necessary to uniquely
--   determine each value if that is not required. As a rule of thumb,
--   requiring fewer significant digits means faster generation of the
--   representation.
posToDigits :: Int -> Int -> Integer -> Int -> ([Int], Int)

-- | <tt><a>fullDecimalDigits</a> a e</tt> calculates the number of decimal
--   digits that may be required to exactly display a value <tt>x = m *
--   2^e</tt> where <tt>m</tt> is an <a>Integer</a> satisfying <tt>2^a
--   &lt;= m &lt; 2^(a+1)</tt>. Usually, the calculated value is not much
--   larger than the actual number of digits in the exact decimal
--   representation, but it will be if the exponent <tt>e</tt> is negative
--   and has large absolute value and the mantissa is divisible by a large
--   power of <tt>2</tt>.
fullDecimalDigits :: Int -> Int -> Int

-- | Integer base-<tt>2</tt> logarithm of a positive <a>Integer</a>.
integerLog2 :: Integer -> Int
