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

-- | Efficiently parse and produce common integral and fractional numbers.
--   
--   The bytestring-lexing package offers extremely efficient
--   ByteString parsers for some common lexemes: namely integral and
--   fractional numbers. In addition, it provides efficient serializers for
--   (some of) the formats it parses.
--   
--   As of version 0.3.0, bytestring-lexing offers the best-in-show parsers
--   for integral values. (According to the Warp web server's benchmark of
--   parsing the Content-Length field of HTTP headers.) And as of version
--   0.5.0 it offers (to my knowledge) the best-in-show parser for
--   fractional/floating numbers.
--   
--   Some benchmarks for this package can be found at:
--   https://github.com/wrengr/bytestring-lexing/tree/master/bench/html
@package bytestring-lexing
@version 0.5.0.15

-- | Functions for parsing and producing Integral values from/to
--   ByteStrings based on the "Char8" encoding. That is, we assume
--   an ASCII-compatible encoding of alphanumeric characters.
--   
--   Since: 0.3.0
module Data.ByteString.Lex.Integral

-- | Adjust a reading function to recognize an optional leading sign. As
--   with the other functions, we assume an ASCII-compatible encoding of
--   the sign characters.
readSigned :: Num a => (ByteString -> Maybe (a, ByteString)) -> ByteString -> Maybe (a, ByteString)

-- | Read an unsigned/non-negative integral value in ASCII decimal format.
--   Returns Nothing if there is no integer at the beginning of
--   the string, otherwise returns Just the integer read and the
--   remainder of the string.
--   
--   If you are extremely concerned with performance, then it is more
--   performant to use this function at Int or Word and
--   then to call fromIntegral to perform the conversion at the end.
--   However, doing this will make your code succeptible to overflow bugs
--   if the target type is larger than Int.
readDecimal :: Integral a => ByteString -> Maybe (a, ByteString)

-- | A variant of readDecimal which does not return the tail of the
--   string, and returns 0 instead of Nothing. This is
--   twice as fast for Int64 on 32-bit systems, but has identical
--   performance to readDecimal for all other types and
--   architectures.
--   
--   Since: 0.4.0
readDecimal_ :: Integral a => ByteString -> a

-- | Convert a non-negative integer into an (unsigned) ASCII decimal
--   string. Returns Nothing on negative inputs.
packDecimal :: Integral a => a -> Maybe ByteString

-- | Read a non-negative integral value in ASCII hexadecimal format.
--   Returns Nothing if there is no integer at the beginning of
--   the string, otherwise returns Just the integer read and the
--   remainder of the string.
--   
--   This function does not recognize the various hexadecimal sigils like
--   "0x", but because there are so many different variants, those are best
--   handled by helper functions which then use this function for the
--   actual numerical parsing. This function recognizes both upper-case,
--   lower-case, and mixed-case hexadecimal.
readHexadecimal :: Integral a => ByteString -> Maybe (a, ByteString)

-- | Convert a non-negative integer into a lower-case ASCII hexadecimal
--   string. Returns Nothing on negative inputs.
packHexadecimal :: Integral a => a -> Maybe ByteString

-- | Convert a bitvector into a lower-case ASCII hexadecimal string. This
--   is helpful for visualizing raw binary data, rather than for parsing as
--   such.
asHexadecimal :: ByteString -> ByteString

-- | Read a non-negative integral value in ASCII octal format. Returns
--   Nothing if there is no integer at the beginning of the
--   string, otherwise returns Just the integer read and the
--   remainder of the string.
--   
--   This function does not recognize the various octal sigils like "0o",
--   but because there are different variants, those are best handled by
--   helper functions which then use this function for the actual numerical
--   parsing.
readOctal :: Integral a => ByteString -> Maybe (a, ByteString)

-- | Convert a non-negative integer into an ASCII octal string. Returns
--   Nothing on negative inputs.
packOctal :: Integral a => a -> Maybe ByteString

-- | Functions for parsing and producing Fractional values from/to
--   ByteStrings based on the "Char8" encoding. That is, we assume
--   an ASCII-compatible encoding of alphanumeric characters.
--   
--   Since: 0.5.0
module Data.ByteString.Lex.Fractional

-- | Adjust a reading function to recognize an optional leading sign. As
--   with the other functions, we assume an ASCII-compatible encoding of
--   the sign characters.
readSigned :: Num a => (ByteString -> Maybe (a, ByteString)) -> ByteString -> Maybe (a, ByteString)

-- | Read an unsigned/non-negative fractional value in ASCII decimal
--   format; that is, anything matching the regex \d+(\.\d+)?.
--   Returns Nothing if there is no such number at the beginning
--   of the string, otherwise returns Just the number read and the
--   remainder of the string.
--   
--   N.B., see readDecimalLimited if your fractional type has
--   limited precision and you expect your inputs to have greater precision
--   than can be represented. Even for types with unlimited precision
--   (e.g., Rational), you may want to check out
--   readDecimalLimited.
readDecimal :: Fractional a => ByteString -> Maybe (a, ByteString)

-- | Read a non-negative integral value in ASCII hexadecimal format.
--   Returns Nothing if there is no integer at the beginning of
--   the string, otherwise returns Just the integer read and the
--   remainder of the string.
--   
--   This function does not recognize the various hexadecimal sigils like
--   "0x", but because there are so many different variants, those are best
--   handled by helper functions which then use this function for the
--   actual numerical parsing. This function recognizes both upper-case,
--   lower-case, and mixed-case hexadecimal.
--   
--   This is just a thin wrapper around readHexadecimal.
readHexadecimal :: Fractional a => ByteString -> Maybe (a, ByteString)

-- | Read a non-negative integral value in ASCII octal format. Returns
--   Nothing if there is no integer at the beginning of the
--   string, otherwise returns Just the integer read and the
--   remainder of the string.
--   
--   This function does not recognize the various octal sigils like "0o",
--   but because there are different variants, those are best handled by
--   helper functions which then use this function for the actual numerical
--   parsing.
--   
--   This is just a thin wrapper around readOctal.
readOctal :: Fractional a => ByteString -> Maybe (a, ByteString)

-- | Read an unsigned/non-negative fractional value in ASCII exponential
--   format; that is, anything matching the regex
--   \d+(\.\d+)?([eE][\+\-]?\d+)?. Returns Nothing if
--   there is no such number at the beginning of the string, otherwise
--   returns Just the number read and the remainder of the string.
--   
--   N.B., the current implementation assumes the exponent is small enough
--   to fit into an Int. This gives a significant performance
--   increase for a ~ Float and a ~ Double and agrees
--   with the RealFloat class which has exponent returning an
--   Int. If you need a larger exponent, contact the maintainer.
--   
--   N.B., see readExponentialLimited if your fractional type has
--   limited precision and you expect your inputs to have greater precision
--   than can be represented. Even for types with unlimited precision, you
--   may want to check out readExponentialLimited.
readExponential :: Fractional a => ByteString -> Maybe (a, ByteString)

-- | Return the RealFloat type's inherent decimal precision
--   limitation. This is the number of decimal digits in floatRadix
--   proxy ^ floatDigits proxy.
decimalPrecision :: forall proxy a. RealFloat a => proxy a -> Int

-- | A variant of readDecimal which only reads up to some limited
--   precision. The first argument gives the number of decimal digits at
--   which to limit the precision.
--   
--   For types with inherently limited precision (e.g., Float and
--   Double), when you pass in the precision limit (cf.,
--   decimalPrecision) this is far more efficient than
--   readDecimal. However, passing in a precision limit which is
--   greater than the type's inherent limitation will degrate performance
--   compared to readDecimal.
--   
--   For types with unlimited precision (e.g., Rational) this may
--   still be far more efficient than readDecimal (it is for
--   Rational, in fact). The reason being that it delays the scaling
--   the significand/mantissa by the exponent, thus allowing you to further
--   adjust the exponent before computing the final value (e.g., as in
--   readExponentialLimited). This avoids the need to renormalize
--   intermediate results, and allows faster computation of the scaling
--   factor by doing it all at once.
readDecimalLimited :: Fractional a => Int -> ByteString -> Maybe (a, ByteString)

-- | A variant of readExponential which only reads up to some
--   limited precision. The first argument gives the number of decimal
--   digits at which to limit the precision. See readDecimalLimited
--   for more discussion of the performance benefits of using this
--   function.
readExponentialLimited :: Fractional a => Int -> ByteString -> Maybe (a, ByteString)
