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


-- | Parse and produce literals efficiently from strict or lazy bytestrings.
--   
--   Parse and produce literals efficiently from strict or lazy
--   bytestrings.
--   
--   Some benchmarks for this package can be found at:
--   <a>http://community.haskell.org/~wren/bytestring-lexing/test/bench/html</a>
@package bytestring-lexing
@version 0.4.3.2


-- | Efficiently parse floating point literals from a <tt>ByteString</tt>.
module Data.ByteString.Lex.Lazy.Double

-- | Parse the initial portion of the ByteString as a Double precision
--   floating point value. The expected form of the numeric literal is
--   given by:
--   
--   <ul>
--   <li>An optional <a>+</a> or <a>-</a> sign</li>
--   <li>Decimal digits, OR</li>
--   <li>0 [oO] and a sequence of octal digits, OR</li>
--   <li>0 [xX] and a sequence of hexadecimal digits, OR</li>
--   <li>An optional decimal point, followed by a sequence of decimal
--   digits,</li>
--   <li>And an optional exponent</li>
--   </ul>
--   
--   The result is returned as a pair of a double-precision floating point
--   value and the remaining input, or <tt>Nothing</tt> should no parse be
--   found.
--   
--   For example, to sum a file of floating point numbers, one per line,
--   
--   <pre>
--   import qualified Data.ByteString.Char8  as S
--   import qualified Data.ByteString.Unsafe as S
--   import Data.ByteString.Lex.Double
--   
--   main = print . go 0 =&lt;&lt; S.getContents
--     where
--       go n s = case readDouble s of
--                       Nothing       -&gt; n
--                       Just (k,rest) -&gt; go (n+k) (S.tail rest)
--   </pre>
readDouble :: ByteString -> Maybe (Double, ByteString)
instance Functor AlexLastAcc


-- | Efficiently parse floating point literals from a <a>ByteString</a>.
module Data.ByteString.Lex.Double

-- | Parse the initial portion of the ByteString as a Double precision
--   floating point value. The expected form of the numeric literal is
--   given by:
--   
--   <ul>
--   <li>An optional <a>+</a> or <a>-</a> sign</li>
--   <li>Decimal digits, OR</li>
--   <li>0 [oO] and a sequence of octal digits, OR</li>
--   <li>0 [xX] and a sequence of hexadecimal digits, OR</li>
--   <li>An optional decimal point, followed by a sequence of decimal
--   digits,</li>
--   <li>And an optional exponent</li>
--   </ul>
--   
--   The result is returned as a pair of a double-precision floating point
--   value and the remaining input, or <tt>Nothing</tt> should no parse be
--   found.
--   
--   For example, to sum a file of floating point numbers, one per line,
--   
--   <pre>
--   import qualified Data.ByteString.Char8  as S
--   import qualified Data.ByteString.Unsafe as S
--   import Data.ByteString.Lex.Double
--   
--   main = print . go 0 =&lt;&lt; S.getContents
--     where
--       go n s = case readDouble s of
--                       Nothing       -&gt; n
--                       Just (k,rest) -&gt; go (n+k) (S.tail rest)
--   </pre>
readDouble :: ByteString -> Maybe (Double, ByteString)

-- | Bare bones, unsafe wrapper for C's <tt>strtod(3)</tt>. This provides a
--   non-copying direct parsing of Double values from a ByteString. It uses
--   <tt>strtod</tt> directly on the bytestring buffer. <tt>strtod</tt>
--   requires the string to be null terminated, or for a guarantee that
--   parsing will find a floating point value before the end of the string.
unsafeReadDouble :: ByteString -> Maybe (Double, ByteString)
instance Functor AlexLastAcc


-- | 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.
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.
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
