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


-- | Scientific notation intended for tokenization
--   
--   This library provides a type used to represent a number in scientific
--   notation. This is most frequently useful when tokenizing or parsing a
--   language. Languages like JSON and SQL support numberic literals
--   written in scientific notation, even though backends frequently reject
--   numbers outside a given range. This library provides a compact
--   representation of numbers in scientific notation. In the common case
--   of the coefficient and then exponent each being small enough to be
--   represented by a machine word, this library avoids the need for any
--   indirections to retrieve the number. Consider some tokenization
--   scheme: `data Token = ... | Number {--} !Scientific`. In this case,
--   the unboxed coefficient and exponent are unpacked into the
--   <a>Number</a> data constructor if they can each be represented by a
--   machine word.
--   
--   The internal representation does not normalize numbers. That is,
--   parsing `300e-2` resulting in a representation that uses `300` and
--   `-2` rather than `3` and `0`. This work is deferred with the
--   expectation that a number in scientific notation is consumed either
--   zero or one times. This library is not optimized for use-cases that
--   consume a <a>Scientific</a> more than once since normalization is
--   reapplied every time.
--   
--   The primary library that operates in this same space is
--   <a>scientific</a>. Compared to <a>scientific</a>, this library
--   distinguishes itself from <a>scientific</a> in the following ways:
--   
--   <ul>
--   <li>Correctness: <a>scientific</a> does not correctly handle large
--   exponents. See <a>issue #62</a>.</li>
--   <li>Parsing: The `scientific-notation` parser outperforms the
--   <a>scientific</a> parser that ships with <a>aeson</a> by a factor of
--   five on small numbers.</li>
--   </ul>
@package scientific-notation
@version 0.1.1.0

module Data.Number.Scientific
data Scientific
type Scientific# = (# Int#, Int#, LargeScientific #)

-- | Construct a <a>Scientific</a> from a coefficient and exponent that fit
--   in a machine word.
small :: Int -> Int -> Scientific

-- | Construct a <a>Scientific</a> from a coefficient and exponent of
--   arbitrary size.
large :: Integer -> Integer -> Scientific

-- | Construct a <a>Scientific</a> from a fixed-precision number. This does
--   not perform well and is only included for convenience.
fromFixed :: HasResolution e => Fixed e -> Scientific
toWord :: Scientific -> Maybe Word
toWord8 :: Scientific -> Maybe Word8
toWord16 :: Scientific -> Maybe Word16
toWord32 :: Scientific -> Maybe Word32
toWord64 :: Scientific -> Maybe Word64
toInt :: Scientific -> Maybe Int
toInt32 :: Scientific -> Maybe Int32
toInt64 :: Scientific -> Maybe Int64

-- | Expose the non-normalized exponent and coefficient.
withExposed :: (Int -> Int -> a) -> (Integer -> Integer -> a) -> Scientific -> a

-- | Parse a number that is encoded in UTF-8 and in scientific notation.
--   All of these are accepted:
--   
--   <ul>
--   <li>330e-1</li>
--   <li>330e+1</li>
--   <li>330e1</li>
--   <li>330.0e1</li>
--   <li>-330.0e1</li>
--   <li>12</li>
--   <li>00012</li>
--   <li>2.05</li>
--   <li>+2.05</li>
--   <li>+33.6e+1</li>
--   </ul>
parserSignedUtf8Bytes :: e -> Parser e s Scientific
parserTrailingUtf8Bytes :: e -> Int -> Parser e s Scientific

-- | Variant of <a>parserSignedUtf8Bytes</a> that rejects strings with a
--   leading plus or minus sign.
parserUnsignedUtf8Bytes :: e -> Parser e s Scientific

-- | Variant of <a>parserUnsignedUtf8Bytes</a> that negates the result.
parserNegatedUtf8Bytes :: e -> Parser e s Scientific
parserNegatedTrailingUtf8Bytes :: e -> Int -> Parser e s Scientific
parserSignedUtf8Bytes# :: e -> Parser e s Scientific#
parserTrailingUtf8Bytes# :: e -> Int# -> Parser e s Scientific#

-- | Variant of <tt>parseUnsignedUtf8Bytes</tt> where all arguments are
--   unboxed.
parserUnsignedUtf8Bytes# :: e -> Parser e s Scientific#
parserNegatedUtf8Bytes# :: e -> Parser e s Scientific#
parserNegatedTrailingUtf8Bytes# :: e -> Int# -> Parser e s Scientific#
instance GHC.Show.Show Data.Number.Scientific.Scientific
instance GHC.Classes.Eq Data.Number.Scientific.Scientific