-- 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
--   <a>ByteString</a> 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:
--   <a>https://github.com/wrengr/bytestring-lexing/tree/master/bench/html</a>
@package bytestring-lexing
@version 0.5.0.15


-- | Functions for parsing and producing <a>Integral</a> values from/to
--   <a>ByteString</a>s based on the "Char8" encoding. That is, we assume
--   an ASCII-compatible encoding of alphanumeric characters.
--   
--   <i>Since: 0.3.0</i>
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 <tt>Nothing</tt> if there is no integer at the beginning of
--   the string, otherwise returns <tt>Just</tt> 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 <tt>Int</tt> or <tt>Word</tt> and
--   then to call <a>fromIntegral</a> 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 <tt>Int</tt>.
readDecimal :: Integral a => ByteString -> Maybe (a, ByteString)

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

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

-- | Read a non-negative integral value in ASCII hexadecimal format.
--   Returns <tt>Nothing</tt> if there is no integer at the beginning of
--   the string, otherwise returns <tt>Just</tt> 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 <tt>Nothing</tt> 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
--   <tt>Nothing</tt> if there is no integer at the beginning of the
--   string, otherwise returns <tt>Just</tt> 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
--   <tt>Nothing</tt> on negative inputs.
packOctal :: Integral a => a -> Maybe ByteString


-- | Functions for parsing and producing <a>Fractional</a> values from/to
--   <a>ByteString</a>s based on the "Char8" encoding. That is, we assume
--   an ASCII-compatible encoding of alphanumeric characters.
--   
--   <i>Since: 0.5.0</i>
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 <tt>\d+(\.\d+)?</tt>.
--   Returns <tt>Nothing</tt> if there is no such number at the beginning
--   of the string, otherwise returns <tt>Just</tt> the number read and the
--   remainder of the string.
--   
--   N.B., see <a>readDecimalLimited</a> 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., <a>Rational</a>), you may want to check out
--   <a>readDecimalLimited</a>.
readDecimal :: Fractional a => ByteString -> Maybe (a, ByteString)

-- | Read a non-negative integral value in ASCII hexadecimal format.
--   Returns <tt>Nothing</tt> if there is no integer at the beginning of
--   the string, otherwise returns <tt>Just</tt> 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 <a>readHexadecimal</a>.
readHexadecimal :: Fractional a => ByteString -> Maybe (a, ByteString)

-- | Read a non-negative integral value in ASCII octal format. Returns
--   <tt>Nothing</tt> if there is no integer at the beginning of the
--   string, otherwise returns <tt>Just</tt> 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 <a>readOctal</a>.
readOctal :: Fractional a => ByteString -> Maybe (a, ByteString)

-- | Read an unsigned/non-negative fractional value in ASCII exponential
--   format; that is, anything matching the regex
--   <tt>\d+(\.\d+)?([eE][\+\-]?\d+)?</tt>. Returns <tt>Nothing</tt> if
--   there is no such number at the beginning of the string, otherwise
--   returns <tt>Just</tt> the number read and the remainder of the string.
--   
--   N.B., the current implementation assumes the exponent is small enough
--   to fit into an <a>Int</a>. This gives a significant performance
--   increase for <tt>a ~ Float</tt> and <tt>a ~ Double</tt> and agrees
--   with the <a>RealFloat</a> class which has <a>exponent</a> returning an
--   <a>Int</a>. If you need a larger exponent, contact the maintainer.
--   
--   N.B., see <a>readExponentialLimited</a> 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 <a>readExponentialLimited</a>.
readExponential :: Fractional a => ByteString -> Maybe (a, ByteString)

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

-- | A variant of <a>readDecimal</a> 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., <a>Float</a> and
--   <a>Double</a>), when you pass in the precision limit (cf.,
--   <a>decimalPrecision</a>) this is far more efficient than
--   <a>readDecimal</a>. However, passing in a precision limit which is
--   greater than the type's inherent limitation will degrate performance
--   compared to <a>readDecimal</a>.
--   
--   For types with unlimited precision (e.g., <a>Rational</a>) this may
--   still be far more efficient than <a>readDecimal</a> (it is for
--   <a>Rational</a>, 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
--   <a>readExponentialLimited</a>). 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 <a>readExponential</a> which only reads up to some
--   limited precision. The first argument gives the number of decimal
--   digits at which to limit the precision. See <a>readDecimalLimited</a>
--   for more discussion of the performance benefits of using this
--   function.
readExponentialLimited :: Fractional a => Int -> ByteString -> Maybe (a, ByteString)
