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


-- | Fast, compact, strict and lazy byte strings with a list interface
--   
--   An efficient compact, immutable byte string type (both strict and
--   lazy) suitable for binary or 8-bit character data.
--   
--   The <a>ByteString</a> type represents sequences of bytes or 8-bit
--   characters. It is suitable for high performance use, both in terms of
--   large data quantities, or high speed requirements. The
--   <a>ByteStrin</a>g functions follow the same style as Haskell's
--   ordinary lists, so it is easy to convert code from using <a>String</a>
--   to <a>ByteString</a>.
--   
--   Two <a>ByteString</a> variants are provided:
--   
--   <ul>
--   <li>Strict <a>ByteString</a>s keep the string as a single large array.
--   This makes them convenient for passing data between C and
--   Haskell.</li>
--   <li>Lazy <a>ByteString</a>s use a lazy list of strict chunks which
--   makes it suitable for I/O streaming tasks.</li>
--   </ul>
--   
--   The <tt>Char8</tt> modules provide a character-based view of the same
--   underlying <a>ByteString</a> types. This makes it convenient to handle
--   mixed binary and 8-bit character content (which is common in many file
--   formats and network protocols).
--   
--   The <a>Builder</a> module provides an efficient way to build up
--   <a>ByteString</a>s in an ad-hoc way by repeated concatenation. This is
--   ideal for fast serialisation or pretty printing.
--   
--   <a>ByteString</a>s are not designed for Unicode. For Unicode strings
--   you should use the <a>Text</a> type from the <tt>text</tt> package.
--   
--   These modules are intended to be imported qualified, to avoid name
--   clashes with <a>Prelude</a> functions, e.g.
--   
--   <pre>
--   import qualified Data.ByteString as BS
--   </pre>
@package bytestring
@version 0.10.0.2


-- | A module containing unsafe <a>ByteString</a> operations.
--   
--   While these functions have a stable API and you may use these
--   functions in applications, do carefully consider the documented
--   pre-conditions; incorrect use can break referential transparency or
--   worse.
module Data.ByteString.Unsafe

-- | A variety of <a>head</a> for non-empty ByteStrings. <a>unsafeHead</a>
--   omits the check for the empty case, so there is an obligation on the
--   programmer to provide a proof that the ByteString is non-empty.
unsafeHead :: ByteString -> Word8

-- | A variety of <a>tail</a> for non-empty ByteStrings. <a>unsafeTail</a>
--   omits the check for the empty case. As with <a>unsafeHead</a>, the
--   programmer must provide a separate proof that the ByteString is
--   non-empty.
unsafeTail :: ByteString -> ByteString

-- | Unsafe <a>ByteString</a> index (subscript) operator, starting from 0,
--   returning a <a>Word8</a> This omits the bounds check, which means
--   there is an accompanying obligation on the programmer to ensure the
--   bounds are checked in some other way.
unsafeIndex :: ByteString -> Int -> Word8

-- | A variety of <a>take</a> which omits the checks on <tt>n</tt> so there
--   is an obligation on the programmer to provide a proof that <tt>0 &lt;=
--   n &lt;= <a>length</a> xs</tt>.
unsafeTake :: Int -> ByteString -> ByteString

-- | A variety of <a>drop</a> which omits the checks on <tt>n</tt> so there
--   is an obligation on the programmer to provide a proof that <tt>0 &lt;=
--   n &lt;= <a>length</a> xs</tt>.
unsafeDrop :: Int -> ByteString -> ByteString

-- | <i>O(1) construction</i> Use a <tt>ByteString</tt> with a function
--   requiring a <tt>CString</tt>.
--   
--   This function does zero copying, and merely unwraps a
--   <tt>ByteString</tt> to appear as a <tt>CString</tt>. It is
--   <i>unsafe</i> in two ways:
--   
--   <ul>
--   <li>After calling this function the <tt>CString</tt> shares the
--   underlying byte buffer with the original <tt>ByteString</tt>. Thus
--   modifying the <tt>CString</tt>, either in C, or using poke, will cause
--   the contents of the <tt>ByteString</tt> to change, breaking
--   referential transparency. Other <tt>ByteStrings</tt> created by
--   sharing (such as those produced via <a>take</a> or <a>drop</a>) will
--   also reflect these changes. Modifying the <tt>CString</tt> will break
--   referential transparency. To avoid this, use <tt>useAsCString</tt>,
--   which makes a copy of the original <tt>ByteString</tt>.</li>
--   <li><tt>CStrings</tt> are often passed to functions that require them
--   to be null-terminated. If the original <tt>ByteString</tt> wasn't null
--   terminated, neither will the <tt>CString</tt> be. It is the
--   programmers responsibility to guarantee that the <tt>ByteString</tt>
--   is indeed null terminated. If in doubt, use
--   <tt>useAsCString</tt>.</li>
--   </ul>
unsafeUseAsCString :: ByteString -> (CString -> IO a) -> IO a

-- | <i>O(1) construction</i> Use a <tt>ByteString</tt> with a function
--   requiring a <tt>CStringLen</tt>.
--   
--   This function does zero copying, and merely unwraps a
--   <tt>ByteString</tt> to appear as a <tt>CStringLen</tt>. It is
--   <i>unsafe</i>:
--   
--   <ul>
--   <li>After calling this function the <tt>CStringLen</tt> shares the
--   underlying byte buffer with the original <tt>ByteString</tt>. Thus
--   modifying the <tt>CStringLen</tt>, either in C, or using poke, will
--   cause the contents of the <tt>ByteString</tt> to change, breaking
--   referential transparency. Other <tt>ByteStrings</tt> created by
--   sharing (such as those produced via <a>take</a> or <a>drop</a>) will
--   also reflect these changes. Modifying the <tt>CStringLen</tt> will
--   break referential transparency. To avoid this, use
--   <tt>useAsCStringLen</tt>, which makes a copy of the original
--   <tt>ByteString</tt>.</li>
--   </ul>
unsafeUseAsCStringLen :: ByteString -> (CStringLen -> IO a) -> IO a

-- | <i>O(n)</i> Build a <tt>ByteString</tt> from a <tt>CString</tt>. This
--   value will have <i>no</i> finalizer associated to it, and will not be
--   garbage collected by Haskell. The ByteString length is calculated
--   using <i>strlen(3)</i>, and thus the complexity is a <i>O(n)</i>.
--   
--   This function is <i>unsafe</i>. If the <tt>CString</tt> is later
--   modified, this change will be reflected in the resulting
--   <tt>ByteString</tt>, breaking referential transparency.
unsafePackCString :: CString -> IO ByteString

-- | <i>O(1)</i> Build a <tt>ByteString</tt> from a <tt>CStringLen</tt>.
--   This value will have <i>no</i> finalizer associated with it, and will
--   not be garbage collected by Haskell. This operation has <i>O(1)</i>
--   complexity as we already know the final size, so no <i>strlen(3)</i>
--   is required.
--   
--   This funtion is <i>unsafe</i>. If the original <tt>CStringLen</tt> is
--   later modified, this change will be reflected in the resulting
--   <tt>ByteString</tt>, breaking referential transparency.
unsafePackCStringLen :: CStringLen -> IO ByteString

-- | <i>O(n)</i> Build a <tt>ByteString</tt> from a malloced
--   <tt>CString</tt>. This value will have a <tt>free(3)</tt> finalizer
--   associated to it.
--   
--   This funtion is <i>unsafe</i>. If the original <tt>CString</tt> is
--   later modified, this change will be reflected in the resulting
--   <tt>ByteString</tt>, breaking referential transparency.
--   
--   This function is also unsafe if you call its finalizer twice, which
--   will result in a <i>double free</i> error, or if you pass it a CString
--   not allocated with <tt>malloc</tt>.
unsafePackMallocCString :: CString -> IO ByteString

-- | <i>O(n)</i> Pack a null-terminated sequence of bytes, pointed to by an
--   Addr# (an arbitrary machine address assumed to point outside the
--   garbage-collected heap) into a <tt>ByteString</tt>. A much faster way
--   to create an Addr# is with an unboxed string literal, than to pack a
--   boxed string. A unboxed string literal is compiled to a static
--   <tt>char []</tt> by GHC. Establishing the length of the string
--   requires a call to <tt>strlen(3)</tt>, so the Addr# must point to a
--   null-terminated buffer (as is the case with <a>string</a># literals in
--   GHC). Use <a>unsafePackAddressLen</a> if you know the length of the
--   string statically.
--   
--   An example:
--   
--   <pre>
--   literalFS = unsafePackAddress "literal"#
--   </pre>
--   
--   This function is <i>unsafe</i>. If you modify the buffer pointed to by
--   the original Addr# this modification will be reflected in the
--   resulting <tt>ByteString</tt>, breaking referential transparency.
--   
--   Note this also won't work if you Add# has embedded '\0' characters in
--   the string (strlen will fail).
unsafePackAddress :: Addr# -> IO ByteString

-- | <i>O(1)</i> <a>unsafePackAddressLen</a> provides constant-time
--   construction of <tt>ByteStrings</tt> which is ideal for string
--   literals. It packs a sequence of bytes into a <a>ByteString</a>, given
--   a raw <a>Addr#</a> to the string, and the length of the string.
--   
--   This function is <i>unsafe</i> in two ways:
--   
--   <ul>
--   <li>the length argument is assumed to be correct. If the length
--   argument is incorrect, it is possible to overstep the end of the byte
--   array.</li>
--   <li>if the underying Addr# is later modified, this change will be
--   reflected in resulting <tt>ByteString</tt>, breaking referential
--   transparency.</li>
--   </ul>
--   
--   If in doubt, don't use these functions.
unsafePackAddressLen :: Int -> Addr# -> IO ByteString

-- | <i>O(1)</i> Construct a <a>ByteString</a> given a Ptr Word8 to a
--   buffer, a length, and an IO action representing a finalizer. This
--   function is not available on Hugs.
--   
--   This function is <i>unsafe</i>, it is possible to break referential
--   transparency by modifying the underlying buffer pointed to by the
--   first argument. Any changes to the original buffer will be reflected
--   in the resulting <tt>ByteString</tt>.
unsafePackCStringFinalizer :: Ptr Word8 -> Int -> IO () -> IO ByteString

-- | Explicitly run the finaliser associated with a <a>ByteString</a>.
--   References to this value after finalisation may generate invalid
--   memory references.
--   
--   This function is <i>unsafe</i>, as there may be other
--   <tt>ByteStrings</tt> referring to the same underlying pages. If you
--   use this, you need to have a proof of some kind that all
--   <a>ByteString</a>s ever generated from the underlying byte array are
--   no longer live.
unsafeFinalize :: ByteString -> IO ()


-- | A time and space-efficient implementation of byte vectors using packed
--   Word8 arrays, suitable for high performance use, both in terms of
--   large data quantities, or high speed requirements. Byte vectors are
--   encoded as strict <a>Word8</a> arrays of bytes, held in a
--   <a>ForeignPtr</a>, and can be passed between C and Haskell with little
--   effort.
--   
--   This module is intended to be imported <tt>qualified</tt>, to avoid
--   name clashes with <a>Prelude</a> functions. eg.
--   
--   <pre>
--   import qualified Data.ByteString as B
--   </pre>
--   
--   Original GHC implementation by Bryan O'Sullivan. Rewritten to use
--   <a>UArray</a> by Simon Marlow. Rewritten to support slices and use
--   <a>ForeignPtr</a> by David Roundy. Rewritten again and extended by Don
--   Stewart and Duncan Coutts.
module Data.ByteString

-- | A space-efficient representation of a Word8 vector, supporting many
--   efficient operations. A <a>ByteString</a> contains 8-bit characters
--   only.
--   
--   Instances of Eq, Ord, Read, Show, Data, Typeable
data ByteString

-- | <i>O(1)</i> The empty <a>ByteString</a>
empty :: ByteString

-- | <i>O(1)</i> Convert a <a>Word8</a> into a <a>ByteString</a>
singleton :: Word8 -> ByteString

-- | <i>O(n)</i> Convert a '[Word8]' into a <a>ByteString</a>.
--   
--   For applications with large numbers of string literals, pack can be a
--   bottleneck. In such cases, consider using packAddress (GHC only).
pack :: [Word8] -> ByteString

-- | <i>O(n)</i> Converts a <a>ByteString</a> to a '[Word8]'.
unpack :: ByteString -> [Word8]

-- | <i>O(n)</i> <a>cons</a> is analogous to (:) for lists, but of
--   different complexity, as it requires a memcpy.
cons :: Word8 -> ByteString -> ByteString

-- | <i>O(n)</i> Append a byte to the end of a <a>ByteString</a>
snoc :: ByteString -> Word8 -> ByteString

-- | <i>O(n)</i> Append two ByteStrings
append :: ByteString -> ByteString -> ByteString

-- | <i>O(1)</i> Extract the first element of a ByteString, which must be
--   non-empty. An exception will be thrown in the case of an empty
--   ByteString.
head :: ByteString -> Word8

-- | <i>O(1)</i> Extract the head and tail of a ByteString, returning
--   Nothing if it is empty.
uncons :: ByteString -> Maybe (Word8, ByteString)

-- | <i>O(1)</i> Extract the last element of a ByteString, which must be
--   finite and non-empty. An exception will be thrown in the case of an
--   empty ByteString.
last :: ByteString -> Word8

-- | <i>O(1)</i> Extract the elements after the head of a ByteString, which
--   must be non-empty. An exception will be thrown in the case of an empty
--   ByteString.
tail :: ByteString -> ByteString

-- | <i>O(1)</i> Return all the elements of a <a>ByteString</a> except the
--   last one. An exception will be thrown in the case of an empty
--   ByteString.
init :: ByteString -> ByteString

-- | <i>O(1)</i> Test whether a ByteString is empty.
null :: ByteString -> Bool

-- | <i>O(1)</i> <a>length</a> returns the length of a ByteString as an
--   <a>Int</a>.
length :: ByteString -> Int

-- | <i>O(n)</i> <a>map</a> <tt>f xs</tt> is the ByteString obtained by
--   applying <tt>f</tt> to each element of <tt>xs</tt>.
map :: (Word8 -> Word8) -> ByteString -> ByteString

-- | <i>O(n)</i> <a>reverse</a> <tt>xs</tt> efficiently returns the
--   elements of <tt>xs</tt> in reverse order.
reverse :: ByteString -> ByteString

-- | <i>O(n)</i> The <a>intersperse</a> function takes a <a>Word8</a> and a
--   <a>ByteString</a> and `intersperses' that byte between the elements of
--   the <a>ByteString</a>. It is analogous to the intersperse function on
--   Lists.
intersperse :: Word8 -> ByteString -> ByteString

-- | <i>O(n)</i> The <a>intercalate</a> function takes a <a>ByteString</a>
--   and a list of <a>ByteString</a>s and concatenates the list after
--   interspersing the first argument between each element of the list.
intercalate :: ByteString -> [ByteString] -> ByteString

-- | The <a>transpose</a> function transposes the rows and columns of its
--   <a>ByteString</a> argument.
transpose :: [ByteString] -> [ByteString]

-- | <a>foldl</a>, applied to a binary operator, a starting value
--   (typically the left-identity of the operator), and a ByteString,
--   reduces the ByteString using the binary operator, from left to right.
foldl :: (a -> Word8 -> a) -> a -> ByteString -> a

-- | 'foldl\'' is like <a>foldl</a>, but strict in the accumulator.
--   However, for ByteStrings, all left folds are strict in the
--   accumulator.
foldl' :: (a -> Word8 -> a) -> a -> ByteString -> a

-- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value
--   argument, and thus must be applied to non-empty <tt>ByteStrings</tt>.
--   An exception will be thrown in the case of an empty ByteString.
foldl1 :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8

-- | 'foldl1\'' is like <a>foldl1</a>, but strict in the accumulator. An
--   exception will be thrown in the case of an empty ByteString.
foldl1' :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8

-- | <a>foldr</a>, applied to a binary operator, a starting value
--   (typically the right-identity of the operator), and a ByteString,
--   reduces the ByteString using the binary operator, from right to left.
foldr :: (Word8 -> a -> a) -> a -> ByteString -> a

-- | 'foldr\'' is like <a>foldr</a>, but strict in the accumulator.
foldr' :: (Word8 -> a -> a) -> a -> ByteString -> a

-- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value
--   argument, and thus must be applied to non-empty <a>ByteString</a>s An
--   exception will be thrown in the case of an empty ByteString.
foldr1 :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8

-- | 'foldr1\'' is a variant of <a>foldr1</a>, but is strict in the
--   accumulator.
foldr1' :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8

-- | <i>O(n)</i> Concatenate a list of ByteStrings.
concat :: [ByteString] -> ByteString

-- | Map a function over a <a>ByteString</a> and concatenate the results
concatMap :: (Word8 -> ByteString) -> ByteString -> ByteString

-- | <i>O(n)</i> Applied to a predicate and a ByteString, <a>any</a>
--   determines if any element of the <a>ByteString</a> satisfies the
--   predicate.
any :: (Word8 -> Bool) -> ByteString -> Bool

-- | <i>O(n)</i> Applied to a predicate and a <a>ByteString</a>, <a>all</a>
--   determines if all elements of the <a>ByteString</a> satisfy the
--   predicate.
all :: (Word8 -> Bool) -> ByteString -> Bool

-- | <i>O(n)</i> <a>maximum</a> returns the maximum value from a
--   <a>ByteString</a> This function will fuse. An exception will be thrown
--   in the case of an empty ByteString.
maximum :: ByteString -> Word8

-- | <i>O(n)</i> <a>minimum</a> returns the minimum value from a
--   <a>ByteString</a> This function will fuse. An exception will be thrown
--   in the case of an empty ByteString.
minimum :: ByteString -> Word8

-- | <a>scanl</a> is similar to <a>foldl</a>, but returns a list of
--   successive reduced values from the left. This function will fuse.
--   
--   <pre>
--   scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
--   </pre>
--   
--   Note that
--   
--   <pre>
--   last (scanl f z xs) == foldl f z xs.
--   </pre>
scanl :: (Word8 -> Word8 -> Word8) -> Word8 -> ByteString -> ByteString

-- | <a>scanl1</a> is a variant of <a>scanl</a> that has no starting value
--   argument. This function will fuse.
--   
--   <pre>
--   scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
--   </pre>
scanl1 :: (Word8 -> Word8 -> Word8) -> ByteString -> ByteString

-- | scanr is the right-to-left dual of scanl.
scanr :: (Word8 -> Word8 -> Word8) -> Word8 -> ByteString -> ByteString

-- | <a>scanr1</a> is a variant of <a>scanr</a> that has no starting value
--   argument.
scanr1 :: (Word8 -> Word8 -> Word8) -> ByteString -> ByteString

-- | The <a>mapAccumL</a> function behaves like a combination of <a>map</a>
--   and <a>foldl</a>; it applies a function to each element of a
--   ByteString, passing an accumulating parameter from left to right, and
--   returning a final value of this accumulator together with the new
--   list.
mapAccumL :: (acc -> Word8 -> (acc, Word8)) -> acc -> ByteString -> (acc, ByteString)

-- | The <a>mapAccumR</a> function behaves like a combination of <a>map</a>
--   and <a>foldr</a>; it applies a function to each element of a
--   ByteString, passing an accumulating parameter from right to left, and
--   returning a final value of this accumulator together with the new
--   ByteString.
mapAccumR :: (acc -> Word8 -> (acc, Word8)) -> acc -> ByteString -> (acc, ByteString)

-- | <i>O(n)</i> <a>replicate</a> <tt>n x</tt> is a ByteString of length
--   <tt>n</tt> with <tt>x</tt> the value of every element. The following
--   holds:
--   
--   <pre>
--   replicate w c = unfoldr w (\u -&gt; Just (u,u)) c
--   </pre>
--   
--   This implemenation uses <tt>memset(3)</tt>
replicate :: Int -> Word8 -> ByteString

-- | <i>O(n)</i>, where <i>n</i> is the length of the result. The
--   <a>unfoldr</a> function is analogous to the List 'unfoldr'.
--   <a>unfoldr</a> builds a ByteString from a seed value. The function
--   takes the element and returns <a>Nothing</a> if it is done producing
--   the ByteString or returns <a>Just</a> <tt>(a,b)</tt>, in which case,
--   <tt>a</tt> is the next byte in the string, and <tt>b</tt> is the seed
--   value for further production.
--   
--   Examples:
--   
--   <pre>
--      unfoldr (\x -&gt; if x &lt;= 5 then Just (x, x + 1) else Nothing) 0
--   == pack [0, 1, 2, 3, 4, 5]
--   </pre>
unfoldr :: (a -> Maybe (Word8, a)) -> a -> ByteString

-- | <i>O(n)</i> Like <a>unfoldr</a>, <a>unfoldrN</a> builds a ByteString
--   from a seed value. However, the length of the result is limited by the
--   first argument to <a>unfoldrN</a>. This function is more efficient
--   than <a>unfoldr</a> when the maximum length of the result is known.
--   
--   The following equation relates <a>unfoldrN</a> and <a>unfoldr</a>:
--   
--   <pre>
--   fst (unfoldrN n f s) == take n (unfoldr f s)
--   </pre>
unfoldrN :: Int -> (a -> Maybe (Word8, a)) -> a -> (ByteString, Maybe a)

-- | <i>O(1)</i> <a>take</a> <tt>n</tt>, applied to a ByteString
--   <tt>xs</tt>, returns the prefix of <tt>xs</tt> of length <tt>n</tt>,
--   or <tt>xs</tt> itself if <tt>n &gt; <a>length</a> xs</tt>.
take :: Int -> ByteString -> ByteString

-- | <i>O(1)</i> <a>drop</a> <tt>n xs</tt> returns the suffix of
--   <tt>xs</tt> after the first <tt>n</tt> elements, or <tt>[]</tt> if
--   <tt>n &gt; <a>length</a> xs</tt>.
drop :: Int -> ByteString -> ByteString

-- | <i>O(1)</i> <a>splitAt</a> <tt>n xs</tt> is equivalent to
--   <tt>(<a>take</a> n xs, <a>drop</a> n xs)</tt>.
splitAt :: Int -> ByteString -> (ByteString, ByteString)

-- | <a>takeWhile</a>, applied to a predicate <tt>p</tt> and a ByteString
--   <tt>xs</tt>, returns the longest prefix (possibly empty) of
--   <tt>xs</tt> of elements that satisfy <tt>p</tt>.
takeWhile :: (Word8 -> Bool) -> ByteString -> ByteString

-- | <a>dropWhile</a> <tt>p xs</tt> returns the suffix remaining after
--   <a>takeWhile</a> <tt>p xs</tt>.
dropWhile :: (Word8 -> Bool) -> ByteString -> ByteString

-- | <a>span</a> <tt>p xs</tt> breaks the ByteString into two segments. It
--   is equivalent to <tt>(<a>takeWhile</a> p xs, <a>dropWhile</a> p
--   xs)</tt>
span :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | <a>spanEnd</a> behaves like <a>span</a> but from the end of the
--   <a>ByteString</a>. We have
--   
--   <pre>
--   spanEnd (not.isSpace) "x y z" == ("x y ","z")
--   </pre>
--   
--   and
--   
--   <pre>
--   spanEnd (not . isSpace) ps
--      == 
--   let (x,y) = span (not.isSpace) (reverse ps) in (reverse y, reverse x) 
--   </pre>
spanEnd :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (<a>not</a> .
--   p)</tt>.
--   
--   Under GHC, a rewrite rule will transform break (==) into a call to the
--   specialised breakByte:
--   
--   <pre>
--   break ((==) x) = breakByte x
--   break (==x) = breakByte x
--   </pre>
break :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | <a>breakEnd</a> behaves like <a>break</a> but from the end of the
--   <a>ByteString</a>
--   
--   breakEnd p == spanEnd (not.p)
breakEnd :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | The <a>group</a> function takes a ByteString and returns a list of
--   ByteStrings such that the concatenation of the result is equal to the
--   argument. Moreover, each sublist in the result contains only equal
--   elements. For example,
--   
--   <pre>
--   group "Mississippi" = ["M","i","ss","i","ss","i","pp","i"]
--   </pre>
--   
--   It is a special case of <a>groupBy</a>, which allows the programmer to
--   supply their own equality test. It is about 40% faster than <i>groupBy
--   (==)</i>
group :: ByteString -> [ByteString]

-- | The <a>groupBy</a> function is the non-overloaded version of
--   <a>group</a>.
groupBy :: (Word8 -> Word8 -> Bool) -> ByteString -> [ByteString]

-- | <i>O(n)</i> Return all initial segments of the given
--   <a>ByteString</a>, shortest first.
inits :: ByteString -> [ByteString]

-- | <i>O(n)</i> Return all final segments of the given <a>ByteString</a>,
--   longest first.
tails :: ByteString -> [ByteString]

-- | <i>O(n)</i> Break a <a>ByteString</a> into pieces separated by the
--   byte argument, consuming the delimiter. I.e.
--   
--   <pre>
--   split '\n' "a\nb\nd\ne" == ["a","b","d","e"]
--   split 'a'  "aXaXaXa"    == ["","X","X","X",""]
--   split 'x'  "x"          == ["",""]
--   </pre>
--   
--   and
--   
--   <pre>
--   intercalate [c] . split c == id
--   split == splitWith . (==)
--   </pre>
--   
--   As for all splitting functions in this library, this function does not
--   copy the substrings, it just constructs new <tt>ByteStrings</tt> that
--   are slices of the original.
split :: Word8 -> ByteString -> [ByteString]

-- | <i>O(n)</i> Splits a <a>ByteString</a> into components delimited by
--   separators, where the predicate returns True for a separator element.
--   The resulting components do not contain the separators. Two adjacent
--   separators result in an empty component in the output. eg.
--   
--   <pre>
--   splitWith (=='a') "aabbaca" == ["","","bb","c",""]
--   splitWith (=='a') []        == []
--   </pre>
splitWith :: (Word8 -> Bool) -> ByteString -> [ByteString]

-- | <i>O(n)</i> The <a>isPrefixOf</a> function takes two ByteStrings and
--   returns <a>True</a> iff the first is a prefix of the second.
isPrefixOf :: ByteString -> ByteString -> Bool

-- | <i>O(n)</i> The <a>isSuffixOf</a> function takes two ByteStrings and
--   returns <a>True</a> iff the first is a suffix of the second.
--   
--   The following holds:
--   
--   <pre>
--   isSuffixOf x y == reverse x `isPrefixOf` reverse y
--   </pre>
--   
--   However, the real implemenation uses memcmp to compare the end of the
--   string only, with no reverse required..
isSuffixOf :: ByteString -> ByteString -> Bool

-- | Check whether one string is a substring of another. <tt>isInfixOf p
--   s</tt> is equivalent to <tt>not (null (findSubstrings p s))</tt>.
isInfixOf :: ByteString -> ByteString -> Bool

-- | Break a string on a substring, returning a pair of the part of the
--   string prior to the match, and the rest of the string.
--   
--   The following relationships hold:
--   
--   <pre>
--   break (== c) l == breakSubstring (singleton c) l
--   </pre>
--   
--   and:
--   
--   <pre>
--   findSubstring s l ==
--      if null s then Just 0
--                else case breakSubstring s l of
--                         (x,y) | null y    -&gt; Nothing
--                               | otherwise -&gt; Just (length x)
--   </pre>
--   
--   For example, to tokenise a string, dropping delimiters:
--   
--   <pre>
--   tokenise x y = h : if null t then [] else tokenise x (drop (length x) t)
--       where (h,t) = breakSubstring x y
--   </pre>
--   
--   To skip to the first occurence of a string:
--   
--   <pre>
--   snd (breakSubstring x y) 
--   </pre>
--   
--   To take the parts of a string before a delimiter:
--   
--   <pre>
--   fst (breakSubstring x y) 
--   </pre>
breakSubstring :: ByteString -> ByteString -> (ByteString, ByteString)

-- | Get the first index of a substring in another string, or
--   <a>Nothing</a> if the string is not found. <tt>findSubstring p s</tt>
--   is equivalent to <tt>listToMaybe (findSubstrings p s)</tt>.

-- | <i>Deprecated: findSubstring is deprecated in favour of
--   breakSubstring. </i>
findSubstring :: ByteString -> ByteString -> Maybe Int

-- | Find the indexes of all (possibly overlapping) occurances of a
--   substring in a string.

-- | <i>Deprecated: findSubstrings is deprecated in favour of
--   breakSubstring. </i>
findSubstrings :: ByteString -> ByteString -> [Int]

-- | <i>O(n)</i> <a>elem</a> is the <a>ByteString</a> membership predicate.
elem :: Word8 -> ByteString -> Bool

-- | <i>O(n)</i> <a>notElem</a> is the inverse of <a>elem</a>
notElem :: Word8 -> ByteString -> Bool

-- | <i>O(n)</i> The <a>find</a> function takes a predicate and a
--   ByteString, and returns the first element in matching the predicate,
--   or <a>Nothing</a> if there is no such element.
--   
--   <pre>
--   find f p = case findIndex f p of Just n -&gt; Just (p ! n) ; _ -&gt; Nothing
--   </pre>
find :: (Word8 -> Bool) -> ByteString -> Maybe Word8

-- | <i>O(n)</i> <a>filter</a>, applied to a predicate and a ByteString,
--   returns a ByteString containing those characters that satisfy the
--   predicate.
filter :: (Word8 -> Bool) -> ByteString -> ByteString

-- | <i>O(n)</i> The <a>partition</a> function takes a predicate a
--   ByteString and returns the pair of ByteStrings with elements which do
--   and do not satisfy the predicate, respectively; i.e.,
--   
--   <pre>
--   partition p bs == (filter p xs, filter (not . p) xs)
--   </pre>
partition :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | <i>O(1)</i> <a>ByteString</a> index (subscript) operator, starting
--   from 0.
index :: ByteString -> Int -> Word8

-- | <i>O(n)</i> The <a>elemIndex</a> function returns the index of the
--   first element in the given <a>ByteString</a> which is equal to the
--   query element, or <a>Nothing</a> if there is no such element. This
--   implementation uses memchr(3).
elemIndex :: Word8 -> ByteString -> Maybe Int

-- | <i>O(n)</i> The <a>elemIndices</a> function extends <a>elemIndex</a>,
--   by returning the indices of all elements equal to the query element,
--   in ascending order. This implementation uses memchr(3).
elemIndices :: Word8 -> ByteString -> [Int]

-- | <i>O(n)</i> The <a>elemIndexEnd</a> function returns the last index of
--   the element in the given <a>ByteString</a> which is equal to the query
--   element, or <a>Nothing</a> if there is no such element. The following
--   holds:
--   
--   <pre>
--   elemIndexEnd c xs == 
--   (-) (length xs - 1) `fmap` elemIndex c (reverse xs)
--   </pre>
elemIndexEnd :: Word8 -> ByteString -> Maybe Int

-- | The <a>findIndex</a> function takes a predicate and a
--   <a>ByteString</a> and returns the index of the first element in the
--   ByteString satisfying the predicate.
findIndex :: (Word8 -> Bool) -> ByteString -> Maybe Int

-- | The <a>findIndices</a> function extends <a>findIndex</a>, by returning
--   the indices of all elements satisfying the predicate, in ascending
--   order.
findIndices :: (Word8 -> Bool) -> ByteString -> [Int]

-- | count returns the number of times its argument appears in the
--   ByteString
--   
--   <pre>
--   count = length . elemIndices
--   </pre>
--   
--   But more efficiently than using length on the intermediate list.
count :: Word8 -> ByteString -> Int

-- | <i>O(n)</i> <a>zip</a> takes two ByteStrings and returns a list of
--   corresponding pairs of bytes. If one input ByteString is short, excess
--   elements of the longer ByteString are discarded. This is equivalent to
--   a pair of <a>unpack</a> operations.
zip :: ByteString -> ByteString -> [(Word8, Word8)]

-- | <a>zipWith</a> generalises <a>zip</a> by zipping with the function
--   given as the first argument, instead of a tupling function. For
--   example, <tt><a>zipWith</a> (+)</tt> is applied to two ByteStrings to
--   produce the list of corresponding sums.
zipWith :: (Word8 -> Word8 -> a) -> ByteString -> ByteString -> [a]

-- | <i>O(n)</i> <a>unzip</a> transforms a list of pairs of bytes into a
--   pair of ByteStrings. Note that this performs two <a>pack</a>
--   operations.
unzip :: [(Word8, Word8)] -> (ByteString, ByteString)

-- | <i>O(n)</i> Sort a ByteString efficiently, using counting sort.
sort :: ByteString -> ByteString

-- | <i>O(n)</i> Make a copy of the <a>ByteString</a> with its own storage.
--   This is mainly useful to allow the rest of the data pointed to by the
--   <a>ByteString</a> to be garbage collected, for example if a large
--   string has been read in, and only a small part of it is needed in the
--   rest of the program.
copy :: ByteString -> ByteString

-- | <i>O(n).</i> Construct a new <tt>ByteString</tt> from a
--   <tt>CString</tt>. The resulting <tt>ByteString</tt> is an immutable
--   copy of the original <tt>CString</tt>, and is managed on the Haskell
--   heap. The original <tt>CString</tt> must be null terminated.
packCString :: CString -> IO ByteString

-- | <i>O(n).</i> Construct a new <tt>ByteString</tt> from a
--   <tt>CStringLen</tt>. The resulting <tt>ByteString</tt> is an immutable
--   copy of the original <tt>CStringLen</tt>. The <tt>ByteString</tt> is a
--   normal Haskell value and will be managed on the Haskell heap.
packCStringLen :: CStringLen -> IO ByteString

-- | <i>O(n) construction</i> Use a <tt>ByteString</tt> with a function
--   requiring a null-terminated <tt>CString</tt>. The <tt>CString</tt>
--   will be freed automatically. This is a memcpy(3).
useAsCString :: ByteString -> (CString -> IO a) -> IO a

-- | <i>O(n) construction</i> Use a <tt>ByteString</tt> with a function
--   requiring a <tt>CStringLen</tt>. As for <tt>useAsCString</tt> this
--   function makes a copy of the original <tt>ByteString</tt>.
useAsCStringLen :: ByteString -> (CStringLen -> IO a) -> IO a

-- | Read a line from stdin.
getLine :: IO ByteString

-- | getContents. Read stdin strictly. Equivalent to hGetContents stdin The
--   <a>Handle</a> is closed after the contents have been read.
getContents :: IO ByteString

-- | Write a ByteString to stdout
putStr :: ByteString -> IO ()

-- | Write a ByteString to stdout, appending a newline byte

-- | <i>Deprecated: Use Data.ByteString.Char8.putStrLn instead. (Functions
--   that rely on ASCII encodings belong in Data.ByteString.Char8) </i>
putStrLn :: ByteString -> IO ()

-- | The interact function takes a function of type <tt>ByteString -&gt;
--   ByteString</tt> as its argument. The entire input from the standard
--   input device is passed to this function as its argument, and the
--   resulting string is output on the standard output device.
interact :: (ByteString -> ByteString) -> IO ()

-- | Read an entire file strictly into a <a>ByteString</a>. This is far
--   more efficient than reading the characters into a <a>String</a> and
--   then using <a>pack</a>. It also may be more efficient than opening the
--   file and reading it using <a>hGet</a>.
readFile :: FilePath -> IO ByteString

-- | Write a <a>ByteString</a> to a file.
writeFile :: FilePath -> ByteString -> IO ()

-- | Append a <a>ByteString</a> to a file.
appendFile :: FilePath -> ByteString -> IO ()

-- | Read a line from a handle
hGetLine :: Handle -> IO ByteString

-- | Read entire handle contents strictly into a <a>ByteString</a>.
--   
--   This function reads chunks at a time, doubling the chunksize on each
--   read. The final buffer is then realloced to the appropriate size. For
--   files &gt; half of available memory, this may lead to memory
--   exhaustion. Consider using <a>readFile</a> in this case.
--   
--   As with <a>hGet</a>, the string representation in the file is assumed
--   to be ISO-8859-1.
--   
--   The Handle is closed once the contents have been read, or if an
--   exception is thrown.
hGetContents :: Handle -> IO ByteString

-- | Read a <a>ByteString</a> directly from the specified <a>Handle</a>.
--   This is far more efficient than reading the characters into a
--   <a>String</a> and then using <a>pack</a>. First argument is the Handle
--   to read from, and the second is the number of bytes to read. It
--   returns the bytes read, up to n, or <a>null</a> if EOF has been
--   reached.
--   
--   <a>hGet</a> is implemented in terms of <a>hGetBuf</a>.
--   
--   If the handle is a pipe or socket, and the writing end is closed,
--   <a>hGet</a> will behave as if EOF was reached.
hGet :: Handle -> Int -> IO ByteString

-- | Like <a>hGet</a>, except that a shorter <a>ByteString</a> may be
--   returned if there are not enough bytes immediately available to
--   satisfy the whole request. <a>hGetSome</a> only blocks if there is no
--   data available, and EOF has not yet been reached.
hGetSome :: Handle -> Int -> IO ByteString

-- | hGetNonBlocking is similar to <a>hGet</a>, except that it will never
--   block waiting for data to become available, instead it returns only
--   whatever data is available. If there is no data available to be read,
--   <a>hGetNonBlocking</a> returns <a>empty</a>.
--   
--   Note: on Windows and with Haskell implementation other than GHC, this
--   function does not work correctly; it behaves identically to
--   <a>hGet</a>.
hGetNonBlocking :: Handle -> Int -> IO ByteString

-- | Outputs a <a>ByteString</a> to the specified <a>Handle</a>.
hPut :: Handle -> ByteString -> IO ()

-- | Similar to <a>hPut</a> except that it will never block. Instead it
--   returns any tail that did not get written. This tail may be
--   <a>empty</a> in the case that the whole string was written, or the
--   whole original string if nothing was written. Partial writes are also
--   possible.
--   
--   Note: on Windows and with Haskell implementation other than GHC, this
--   function does not work correctly; it behaves identically to
--   <a>hPut</a>.
hPutNonBlocking :: Handle -> ByteString -> IO ByteString

-- | A synonym for <tt>hPut</tt>, for compatibility
hPutStr :: Handle -> ByteString -> IO ()

-- | Write a ByteString to a handle, appending a newline byte

-- | <i>Deprecated: Use Data.ByteString.Char8.hPutStrLn instead. (Functions
--   that rely on ASCII encodings belong in Data.ByteString.Char8) </i>
hPutStrLn :: Handle -> ByteString -> IO ()

-- | <a>breakByte</a> breaks its ByteString argument at the first occurence
--   of the specified byte. It is more efficient than <a>break</a> as it is
--   implemented with <tt>memchr(3)</tt>. I.e.
--   
--   <pre>
--   break (=='c') "abcd" == breakByte 'c' "abcd"
--   </pre>
breakByte :: Word8 -> ByteString -> (ByteString, ByteString)


-- | Manipulate <a>ByteString</a>s using <a>Char</a> operations. All Chars
--   will be truncated to 8 bits. It can be expected that these functions
--   will run at identical speeds to their <a>Word8</a> equivalents in
--   <a>Data.ByteString</a>.
--   
--   More specifically these byte strings are taken to be in the subset of
--   Unicode covered by code points 0-255. This covers Unicode Basic Latin,
--   Latin-1 Supplement and C0+C1 Controls.
--   
--   See:
--   
--   <ul>
--   <li><a>http://www.unicode.org/charts/</a></li>
--   <li><a>http://www.unicode.org/charts/PDF/U0000.pdf</a></li>
--   <li><a>http://www.unicode.org/charts/PDF/U0080.pdf</a></li>
--   </ul>
--   
--   This module is intended to be imported <tt>qualified</tt>, to avoid
--   name clashes with <a>Prelude</a> functions. eg.
--   
--   <pre>
--   import qualified Data.ByteString.Char8 as C
--   </pre>
--   
--   The Char8 interface to bytestrings provides an instance of IsString
--   for the ByteString type, enabling you to use string literals, and have
--   them implicitly packed to ByteStrings. Use <tt>{-# LANGUAGE
--   OverloadedStrings #-}</tt> to enable this.
module Data.ByteString.Char8

-- | A space-efficient representation of a Word8 vector, supporting many
--   efficient operations. A <a>ByteString</a> contains 8-bit characters
--   only.
--   
--   Instances of Eq, Ord, Read, Show, Data, Typeable
data ByteString

-- | <i>O(1)</i> The empty <a>ByteString</a>
empty :: ByteString

-- | <i>O(1)</i> Convert a <a>Char</a> into a <a>ByteString</a>
singleton :: Char -> ByteString

-- | <i>O(n)</i> Convert a <a>String</a> into a <a>ByteString</a>
--   
--   For applications with large numbers of string literals, pack can be a
--   bottleneck.
pack :: String -> ByteString

-- | <i>O(n)</i> Converts a <a>ByteString</a> to a <a>String</a>.
unpack :: ByteString -> [Char]

-- | <i>O(n)</i> <a>cons</a> is analogous to (:) for lists, but of
--   different complexity, as it requires a memcpy.
cons :: Char -> ByteString -> ByteString

-- | <i>O(n)</i> Append a Char to the end of a <a>ByteString</a>. Similar
--   to <a>cons</a>, this function performs a memcpy.
snoc :: ByteString -> Char -> ByteString

-- | <i>O(n)</i> Append two ByteStrings
append :: ByteString -> ByteString -> ByteString

-- | <i>O(1)</i> Extract the first element of a ByteString, which must be
--   non-empty.
head :: ByteString -> Char

-- | <i>O(1)</i> Extract the head and tail of a ByteString, returning
--   Nothing if it is empty.
uncons :: ByteString -> Maybe (Char, ByteString)

-- | <i>O(1)</i> Extract the last element of a packed string, which must be
--   non-empty.
last :: ByteString -> Char

-- | <i>O(1)</i> Extract the elements after the head of a ByteString, which
--   must be non-empty. An exception will be thrown in the case of an empty
--   ByteString.
tail :: ByteString -> ByteString

-- | <i>O(1)</i> Return all the elements of a <a>ByteString</a> except the
--   last one. An exception will be thrown in the case of an empty
--   ByteString.
init :: ByteString -> ByteString

-- | <i>O(1)</i> Test whether a ByteString is empty.
null :: ByteString -> Bool

-- | <i>O(1)</i> <a>length</a> returns the length of a ByteString as an
--   <a>Int</a>.
length :: ByteString -> Int

-- | <i>O(n)</i> <a>map</a> <tt>f xs</tt> is the ByteString obtained by
--   applying <tt>f</tt> to each element of <tt>xs</tt>
map :: (Char -> Char) -> ByteString -> ByteString

-- | <i>O(n)</i> <a>reverse</a> <tt>xs</tt> efficiently returns the
--   elements of <tt>xs</tt> in reverse order.
reverse :: ByteString -> ByteString

-- | <i>O(n)</i> The <a>intersperse</a> function takes a Char and a
--   <a>ByteString</a> and `intersperses' that Char between the elements of
--   the <a>ByteString</a>. It is analogous to the intersperse function on
--   Lists.
intersperse :: Char -> ByteString -> ByteString

-- | <i>O(n)</i> The <a>intercalate</a> function takes a <a>ByteString</a>
--   and a list of <a>ByteString</a>s and concatenates the list after
--   interspersing the first argument between each element of the list.
intercalate :: ByteString -> [ByteString] -> ByteString

-- | The <a>transpose</a> function transposes the rows and columns of its
--   <a>ByteString</a> argument.
transpose :: [ByteString] -> [ByteString]

-- | <a>foldl</a>, applied to a binary operator, a starting value
--   (typically the left-identity of the operator), and a ByteString,
--   reduces the ByteString using the binary operator, from left to right.
foldl :: (a -> Char -> a) -> a -> ByteString -> a

-- | 'foldl\'' is like foldl, but strict in the accumulator.
foldl' :: (a -> Char -> a) -> a -> ByteString -> a

-- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value
--   argument, and thus must be applied to non-empty <tt>ByteStrings</tt>.
foldl1 :: (Char -> Char -> Char) -> ByteString -> Char

-- | A strict version of <a>foldl1</a>
foldl1' :: (Char -> Char -> Char) -> ByteString -> Char

-- | <a>foldr</a>, applied to a binary operator, a starting value
--   (typically the right-identity of the operator), and a packed string,
--   reduces the packed string using the binary operator, from right to
--   left.
foldr :: (Char -> a -> a) -> a -> ByteString -> a

-- | 'foldr\'' is a strict variant of foldr
foldr' :: (Char -> a -> a) -> a -> ByteString -> a

-- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value
--   argument, and thus must be applied to non-empty <a>ByteString</a>s
foldr1 :: (Char -> Char -> Char) -> ByteString -> Char

-- | A strict variant of foldr1
foldr1' :: (Char -> Char -> Char) -> ByteString -> Char

-- | <i>O(n)</i> Concatenate a list of ByteStrings.
concat :: [ByteString] -> ByteString

-- | Map a function over a <a>ByteString</a> and concatenate the results
concatMap :: (Char -> ByteString) -> ByteString -> ByteString

-- | Applied to a predicate and a ByteString, <a>any</a> determines if any
--   element of the <a>ByteString</a> satisfies the predicate.
any :: (Char -> Bool) -> ByteString -> Bool

-- | Applied to a predicate and a <a>ByteString</a>, <a>all</a> determines
--   if all elements of the <a>ByteString</a> satisfy the predicate.
all :: (Char -> Bool) -> ByteString -> Bool

-- | <a>maximum</a> returns the maximum value from a <a>ByteString</a>
maximum :: ByteString -> Char

-- | <a>minimum</a> returns the minimum value from a <a>ByteString</a>
minimum :: ByteString -> Char

-- | <a>scanl</a> is similar to <a>foldl</a>, but returns a list of
--   successive reduced values from the left:
--   
--   <pre>
--   scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
--   </pre>
--   
--   Note that
--   
--   <pre>
--   last (scanl f z xs) == foldl f z xs.
--   </pre>
scanl :: (Char -> Char -> Char) -> Char -> ByteString -> ByteString

-- | <a>scanl1</a> is a variant of <a>scanl</a> that has no starting value
--   argument:
--   
--   <pre>
--   scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
--   </pre>
scanl1 :: (Char -> Char -> Char) -> ByteString -> ByteString

-- | scanr is the right-to-left dual of scanl.
scanr :: (Char -> Char -> Char) -> Char -> ByteString -> ByteString

-- | <a>scanr1</a> is a variant of <a>scanr</a> that has no starting value
--   argument.
scanr1 :: (Char -> Char -> Char) -> ByteString -> ByteString

-- | The <a>mapAccumL</a> function behaves like a combination of <a>map</a>
--   and <a>foldl</a>; it applies a function to each element of a
--   ByteString, passing an accumulating parameter from left to right, and
--   returning a final value of this accumulator together with the new
--   list.
mapAccumL :: (acc -> Char -> (acc, Char)) -> acc -> ByteString -> (acc, ByteString)

-- | The <a>mapAccumR</a> function behaves like a combination of <a>map</a>
--   and <a>foldr</a>; it applies a function to each element of a
--   ByteString, passing an accumulating parameter from right to left, and
--   returning a final value of this accumulator together with the new
--   ByteString.
mapAccumR :: (acc -> Char -> (acc, Char)) -> acc -> ByteString -> (acc, ByteString)

-- | <i>O(n)</i> <a>replicate</a> <tt>n x</tt> is a ByteString of length
--   <tt>n</tt> with <tt>x</tt> the value of every element. The following
--   holds:
--   
--   <pre>
--   replicate w c = unfoldr w (\u -&gt; Just (u,u)) c
--   </pre>
--   
--   This implemenation uses <tt>memset(3)</tt>
replicate :: Int -> Char -> ByteString

-- | <i>O(n)</i>, where <i>n</i> is the length of the result. The
--   <a>unfoldr</a> function is analogous to the List 'unfoldr'.
--   <a>unfoldr</a> builds a ByteString from a seed value. The function
--   takes the element and returns <a>Nothing</a> if it is done producing
--   the ByteString or returns <a>Just</a> <tt>(a,b)</tt>, in which case,
--   <tt>a</tt> is the next character in the string, and <tt>b</tt> is the
--   seed value for further production.
--   
--   Examples:
--   
--   <pre>
--   unfoldr (\x -&gt; if x &lt;= '9' then Just (x, succ x) else Nothing) '0' == "0123456789"
--   </pre>
unfoldr :: (a -> Maybe (Char, a)) -> a -> ByteString

-- | <i>O(n)</i> Like <a>unfoldr</a>, <a>unfoldrN</a> builds a ByteString
--   from a seed value. However, the length of the result is limited by the
--   first argument to <a>unfoldrN</a>. This function is more efficient
--   than <a>unfoldr</a> when the maximum length of the result is known.
--   
--   The following equation relates <a>unfoldrN</a> and <a>unfoldr</a>:
--   
--   <pre>
--   unfoldrN n f s == take n (unfoldr f s)
--   </pre>
unfoldrN :: Int -> (a -> Maybe (Char, a)) -> a -> (ByteString, Maybe a)

-- | <i>O(1)</i> <a>take</a> <tt>n</tt>, applied to a ByteString
--   <tt>xs</tt>, returns the prefix of <tt>xs</tt> of length <tt>n</tt>,
--   or <tt>xs</tt> itself if <tt>n &gt; <a>length</a> xs</tt>.
take :: Int -> ByteString -> ByteString

-- | <i>O(1)</i> <a>drop</a> <tt>n xs</tt> returns the suffix of
--   <tt>xs</tt> after the first <tt>n</tt> elements, or <tt>[]</tt> if
--   <tt>n &gt; <a>length</a> xs</tt>.
drop :: Int -> ByteString -> ByteString

-- | <i>O(1)</i> <a>splitAt</a> <tt>n xs</tt> is equivalent to
--   <tt>(<a>take</a> n xs, <a>drop</a> n xs)</tt>.
splitAt :: Int -> ByteString -> (ByteString, ByteString)

-- | <a>takeWhile</a>, applied to a predicate <tt>p</tt> and a ByteString
--   <tt>xs</tt>, returns the longest prefix (possibly empty) of
--   <tt>xs</tt> of elements that satisfy <tt>p</tt>.
takeWhile :: (Char -> Bool) -> ByteString -> ByteString

-- | <a>dropWhile</a> <tt>p xs</tt> returns the suffix remaining after
--   <a>takeWhile</a> <tt>p xs</tt>.
dropWhile :: (Char -> Bool) -> ByteString -> ByteString

-- | <a>span</a> <tt>p xs</tt> breaks the ByteString into two segments. It
--   is equivalent to <tt>(<a>takeWhile</a> p xs, <a>dropWhile</a> p
--   xs)</tt>
span :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)

-- | <a>spanEnd</a> behaves like <a>span</a> but from the end of the
--   <a>ByteString</a>. We have
--   
--   <pre>
--   spanEnd (not.isSpace) "x y z" == ("x y ","z")
--   </pre>
--   
--   and
--   
--   <pre>
--   spanEnd (not . isSpace) ps
--      == 
--   let (x,y) = span (not.isSpace) (reverse ps) in (reverse y, reverse x) 
--   </pre>
spanEnd :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)

-- | <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (<a>not</a> .
--   p)</tt>.
break :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)

-- | <a>breakEnd</a> behaves like <a>break</a> but from the end of the
--   <a>ByteString</a>
--   
--   breakEnd p == spanEnd (not.p)
breakEnd :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)

-- | The <a>group</a> function takes a ByteString and returns a list of
--   ByteStrings such that the concatenation of the result is equal to the
--   argument. Moreover, each sublist in the result contains only equal
--   elements. For example,
--   
--   <pre>
--   group "Mississippi" = ["M","i","ss","i","ss","i","pp","i"]
--   </pre>
--   
--   It is a special case of <a>groupBy</a>, which allows the programmer to
--   supply their own equality test. It is about 40% faster than <i>groupBy
--   (==)</i>
group :: ByteString -> [ByteString]

-- | The <a>groupBy</a> function is the non-overloaded version of
--   <a>group</a>.
groupBy :: (Char -> Char -> Bool) -> ByteString -> [ByteString]

-- | <i>O(n)</i> Return all initial segments of the given
--   <a>ByteString</a>, shortest first.
inits :: ByteString -> [ByteString]

-- | <i>O(n)</i> Return all final segments of the given <a>ByteString</a>,
--   longest first.
tails :: ByteString -> [ByteString]

-- | <i>O(n)</i> Break a <a>ByteString</a> into pieces separated by the
--   byte argument, consuming the delimiter. I.e.
--   
--   <pre>
--   split '\n' "a\nb\nd\ne" == ["a","b","d","e"]
--   split 'a'  "aXaXaXa"    == ["","X","X","X",""]
--   split 'x'  "x"          == ["",""]
--   </pre>
--   
--   and
--   
--   <pre>
--   intercalate [c] . split c == id
--   split == splitWith . (==)
--   </pre>
--   
--   As for all splitting functions in this library, this function does not
--   copy the substrings, it just constructs new <tt>ByteStrings</tt> that
--   are slices of the original.
split :: Char -> ByteString -> [ByteString]

-- | <i>O(n)</i> Splits a <a>ByteString</a> into components delimited by
--   separators, where the predicate returns True for a separator element.
--   The resulting components do not contain the separators. Two adjacent
--   separators result in an empty component in the output. eg.
--   
--   <pre>
--   splitWith (=='a') "aabbaca" == ["","","bb","c",""]
--   </pre>
splitWith :: (Char -> Bool) -> ByteString -> [ByteString]

-- | <a>lines</a> breaks a ByteString up into a list of ByteStrings at
--   newline Chars. The resulting strings do not contain newlines.
lines :: ByteString -> [ByteString]

-- | <a>words</a> breaks a ByteString up into a list of words, which were
--   delimited by Chars representing white space.
words :: ByteString -> [ByteString]

-- | <a>unlines</a> is an inverse operation to <a>lines</a>. It joins
--   lines, after appending a terminating newline to each.
unlines :: [ByteString] -> ByteString

-- | The <a>unwords</a> function is analogous to the <a>unlines</a>
--   function, on words.
unwords :: [ByteString] -> ByteString

-- | <i>O(n)</i> The <a>isPrefixOf</a> function takes two ByteStrings and
--   returns <a>True</a> iff the first is a prefix of the second.
isPrefixOf :: ByteString -> ByteString -> Bool

-- | <i>O(n)</i> The <a>isSuffixOf</a> function takes two ByteStrings and
--   returns <a>True</a> iff the first is a suffix of the second.
--   
--   The following holds:
--   
--   <pre>
--   isSuffixOf x y == reverse x `isPrefixOf` reverse y
--   </pre>
--   
--   However, the real implemenation uses memcmp to compare the end of the
--   string only, with no reverse required..
isSuffixOf :: ByteString -> ByteString -> Bool

-- | Check whether one string is a substring of another. <tt>isInfixOf p
--   s</tt> is equivalent to <tt>not (null (findSubstrings p s))</tt>.
isInfixOf :: ByteString -> ByteString -> Bool

-- | Break a string on a substring, returning a pair of the part of the
--   string prior to the match, and the rest of the string.
--   
--   The following relationships hold:
--   
--   <pre>
--   break (== c) l == breakSubstring (singleton c) l
--   </pre>
--   
--   and:
--   
--   <pre>
--   findSubstring s l ==
--      if null s then Just 0
--                else case breakSubstring s l of
--                         (x,y) | null y    -&gt; Nothing
--                               | otherwise -&gt; Just (length x)
--   </pre>
--   
--   For example, to tokenise a string, dropping delimiters:
--   
--   <pre>
--   tokenise x y = h : if null t then [] else tokenise x (drop (length x) t)
--       where (h,t) = breakSubstring x y
--   </pre>
--   
--   To skip to the first occurence of a string:
--   
--   <pre>
--   snd (breakSubstring x y) 
--   </pre>
--   
--   To take the parts of a string before a delimiter:
--   
--   <pre>
--   fst (breakSubstring x y) 
--   </pre>
breakSubstring :: ByteString -> ByteString -> (ByteString, ByteString)

-- | Get the first index of a substring in another string, or
--   <a>Nothing</a> if the string is not found. <tt>findSubstring p s</tt>
--   is equivalent to <tt>listToMaybe (findSubstrings p s)</tt>.

-- | <i>Deprecated: findSubstring is deprecated in favour of
--   breakSubstring. </i>
findSubstring :: ByteString -> ByteString -> Maybe Int

-- | Find the indexes of all (possibly overlapping) occurances of a
--   substring in a string.

-- | <i>Deprecated: findSubstrings is deprecated in favour of
--   breakSubstring. </i>
findSubstrings :: ByteString -> ByteString -> [Int]

-- | <i>O(n)</i> <a>elem</a> is the <a>ByteString</a> membership predicate.
--   This implementation uses <tt>memchr(3)</tt>.
elem :: Char -> ByteString -> Bool

-- | <i>O(n)</i> <a>notElem</a> is the inverse of <a>elem</a>
notElem :: Char -> ByteString -> Bool

-- | <i>O(n)</i> The <a>find</a> function takes a predicate and a
--   ByteString, and returns the first element in matching the predicate,
--   or <a>Nothing</a> if there is no such element.
find :: (Char -> Bool) -> ByteString -> Maybe Char

-- | <i>O(n)</i> <a>filter</a>, applied to a predicate and a ByteString,
--   returns a ByteString containing those characters that satisfy the
--   predicate.
filter :: (Char -> Bool) -> ByteString -> ByteString

-- | <i>O(1)</i> <a>ByteString</a> index (subscript) operator, starting
--   from 0.
index :: ByteString -> Int -> Char

-- | <i>O(n)</i> The <a>elemIndex</a> function returns the index of the
--   first element in the given <a>ByteString</a> which is equal (by
--   memchr) to the query element, or <a>Nothing</a> if there is no such
--   element.
elemIndex :: Char -> ByteString -> Maybe Int

-- | <i>O(n)</i> The <a>elemIndices</a> function extends <a>elemIndex</a>,
--   by returning the indices of all elements equal to the query element,
--   in ascending order.
elemIndices :: Char -> ByteString -> [Int]

-- | <i>O(n)</i> The <a>elemIndexEnd</a> function returns the last index of
--   the element in the given <a>ByteString</a> which is equal to the query
--   element, or <a>Nothing</a> if there is no such element. The following
--   holds:
--   
--   <pre>
--   elemIndexEnd c xs == 
--   (-) (length xs - 1) `fmap` elemIndex c (reverse xs)
--   </pre>
elemIndexEnd :: Char -> ByteString -> Maybe Int

-- | The <a>findIndex</a> function takes a predicate and a
--   <a>ByteString</a> and returns the index of the first element in the
--   ByteString satisfying the predicate.
findIndex :: (Char -> Bool) -> ByteString -> Maybe Int

-- | The <a>findIndices</a> function extends <a>findIndex</a>, by returning
--   the indices of all elements satisfying the predicate, in ascending
--   order.
findIndices :: (Char -> Bool) -> ByteString -> [Int]

-- | count returns the number of times its argument appears in the
--   ByteString
--   
--   <pre>
--   count = length . elemIndices
--   </pre>
--   
--   Also
--   
--   <pre>
--   count '\n' == length . lines
--   </pre>
--   
--   But more efficiently than using length on the intermediate list.
count :: Char -> ByteString -> Int

-- | <i>O(n)</i> <a>zip</a> takes two ByteStrings and returns a list of
--   corresponding pairs of Chars. If one input ByteString is short, excess
--   elements of the longer ByteString are discarded. This is equivalent to
--   a pair of <a>unpack</a> operations, and so space usage may be large
--   for multi-megabyte ByteStrings
zip :: ByteString -> ByteString -> [(Char, Char)]

-- | <a>zipWith</a> generalises <a>zip</a> by zipping with the function
--   given as the first argument, instead of a tupling function. For
--   example, <tt><a>zipWith</a> (+)</tt> is applied to two ByteStrings to
--   produce the list of corresponding sums.
zipWith :: (Char -> Char -> a) -> ByteString -> ByteString -> [a]

-- | <a>unzip</a> transforms a list of pairs of Chars into a pair of
--   ByteStrings. Note that this performs two <a>pack</a> operations.
unzip :: [(Char, Char)] -> (ByteString, ByteString)

-- | <i>O(n)</i> Sort a ByteString efficiently, using counting sort.
sort :: ByteString -> ByteString

-- | readInt reads an Int from the beginning of the ByteString. If there is
--   no integer at the beginning of the string, it returns Nothing,
--   otherwise it just returns the int read, and the rest of the string.
readInt :: ByteString -> Maybe (Int, ByteString)

-- | readInteger reads an Integer from the beginning of the ByteString. If
--   there is no integer at the beginning of the string, it returns
--   Nothing, otherwise it just returns the int read, and the rest of the
--   string.
readInteger :: ByteString -> Maybe (Integer, ByteString)

-- | <i>O(n)</i> Make a copy of the <a>ByteString</a> with its own storage.
--   This is mainly useful to allow the rest of the data pointed to by the
--   <a>ByteString</a> to be garbage collected, for example if a large
--   string has been read in, and only a small part of it is needed in the
--   rest of the program.
copy :: ByteString -> ByteString

-- | <i>O(n).</i> Construct a new <tt>ByteString</tt> from a
--   <tt>CString</tt>. The resulting <tt>ByteString</tt> is an immutable
--   copy of the original <tt>CString</tt>, and is managed on the Haskell
--   heap. The original <tt>CString</tt> must be null terminated.
packCString :: CString -> IO ByteString

-- | <i>O(n).</i> Construct a new <tt>ByteString</tt> from a
--   <tt>CStringLen</tt>. The resulting <tt>ByteString</tt> is an immutable
--   copy of the original <tt>CStringLen</tt>. The <tt>ByteString</tt> is a
--   normal Haskell value and will be managed on the Haskell heap.
packCStringLen :: CStringLen -> IO ByteString

-- | <i>O(n) construction</i> Use a <tt>ByteString</tt> with a function
--   requiring a null-terminated <tt>CString</tt>. The <tt>CString</tt>
--   will be freed automatically. This is a memcpy(3).
useAsCString :: ByteString -> (CString -> IO a) -> IO a

-- | <i>O(n) construction</i> Use a <tt>ByteString</tt> with a function
--   requiring a <tt>CStringLen</tt>. As for <tt>useAsCString</tt> this
--   function makes a copy of the original <tt>ByteString</tt>.
useAsCStringLen :: ByteString -> (CStringLen -> IO a) -> IO a

-- | Read a line from stdin.
getLine :: IO ByteString

-- | getContents. Read stdin strictly. Equivalent to hGetContents stdin The
--   <a>Handle</a> is closed after the contents have been read.
getContents :: IO ByteString

-- | Write a ByteString to stdout
putStr :: ByteString -> IO ()

-- | Write a ByteString to stdout, appending a newline byte
putStrLn :: ByteString -> IO ()

-- | The interact function takes a function of type <tt>ByteString -&gt;
--   ByteString</tt> as its argument. The entire input from the standard
--   input device is passed to this function as its argument, and the
--   resulting string is output on the standard output device.
interact :: (ByteString -> ByteString) -> IO ()

-- | Read an entire file strictly into a <a>ByteString</a>. This is far
--   more efficient than reading the characters into a <a>String</a> and
--   then using <a>pack</a>. It also may be more efficient than opening the
--   file and reading it using hGet.
readFile :: FilePath -> IO ByteString

-- | Write a <a>ByteString</a> to a file.
writeFile :: FilePath -> ByteString -> IO ()

-- | Append a <a>ByteString</a> to a file.
appendFile :: FilePath -> ByteString -> IO ()

-- | Read a line from a handle
hGetLine :: Handle -> IO ByteString

-- | Read entire handle contents strictly into a <a>ByteString</a>.
--   
--   This function reads chunks at a time, doubling the chunksize on each
--   read. The final buffer is then realloced to the appropriate size. For
--   files &gt; half of available memory, this may lead to memory
--   exhaustion. Consider using <a>readFile</a> in this case.
--   
--   As with <a>hGet</a>, the string representation in the file is assumed
--   to be ISO-8859-1.
--   
--   The Handle is closed once the contents have been read, or if an
--   exception is thrown.
hGetContents :: Handle -> IO ByteString

-- | Read a <a>ByteString</a> directly from the specified <a>Handle</a>.
--   This is far more efficient than reading the characters into a
--   <a>String</a> and then using <a>pack</a>. First argument is the Handle
--   to read from, and the second is the number of bytes to read. It
--   returns the bytes read, up to n, or <a>null</a> if EOF has been
--   reached.
--   
--   <a>hGet</a> is implemented in terms of <a>hGetBuf</a>.
--   
--   If the handle is a pipe or socket, and the writing end is closed,
--   <a>hGet</a> will behave as if EOF was reached.
hGet :: Handle -> Int -> IO ByteString

-- | hGetNonBlocking is similar to <a>hGet</a>, except that it will never
--   block waiting for data to become available, instead it returns only
--   whatever data is available. If there is no data available to be read,
--   <a>hGetNonBlocking</a> returns <a>empty</a>.
--   
--   Note: on Windows and with Haskell implementation other than GHC, this
--   function does not work correctly; it behaves identically to
--   <a>hGet</a>.
hGetNonBlocking :: Handle -> Int -> IO ByteString

-- | Outputs a <a>ByteString</a> to the specified <a>Handle</a>.
hPut :: Handle -> ByteString -> IO ()

-- | Similar to <a>hPut</a> except that it will never block. Instead it
--   returns any tail that did not get written. This tail may be
--   <a>empty</a> in the case that the whole string was written, or the
--   whole original string if nothing was written. Partial writes are also
--   possible.
--   
--   Note: on Windows and with Haskell implementation other than GHC, this
--   function does not work correctly; it behaves identically to
--   <a>hPut</a>.
hPutNonBlocking :: Handle -> ByteString -> IO ByteString

-- | A synonym for <tt>hPut</tt>, for compatibility
hPutStr :: Handle -> ByteString -> IO ()

-- | Write a ByteString to a handle, appending a newline byte
hPutStrLn :: Handle -> ByteString -> IO ()


-- | A time and space-efficient implementation of lazy byte vectors using
--   lists of packed <a>Word8</a> arrays, suitable for high performance
--   use, both in terms of large data quantities, or high speed
--   requirements. Lazy ByteStrings are encoded as lazy lists of strict
--   chunks of bytes.
--   
--   A key feature of lazy ByteStrings is the means to manipulate large or
--   unbounded streams of data without requiring the entire sequence to be
--   resident in memory. To take advantage of this you have to write your
--   functions in a lazy streaming style, e.g. classic pipeline
--   composition. The default I/O chunk size is 32k, which should be good
--   in most circumstances.
--   
--   Some operations, such as <a>concat</a>, <a>append</a>, <a>reverse</a>
--   and <a>cons</a>, have better complexity than their
--   <a>Data.ByteString</a> equivalents, due to optimisations resulting
--   from the list spine structure. For other operations lazy ByteStrings
--   are usually within a few percent of strict ones.
--   
--   The recomended way to assemble lazy ByteStrings from smaller parts is
--   to use the builder monoid from <a>Data.ByteString.Lazy.Builder</a>.
--   
--   This module is intended to be imported <tt>qualified</tt>, to avoid
--   name clashes with <a>Prelude</a> functions. eg.
--   
--   <pre>
--   import qualified Data.ByteString.Lazy as B
--   </pre>
--   
--   Original GHC implementation by Bryan O'Sullivan. Rewritten to use
--   <a>UArray</a> by Simon Marlow. Rewritten to support slices and use
--   <a>ForeignPtr</a> by David Roundy. Rewritten again and extended by Don
--   Stewart and Duncan Coutts. Lazy variant by Duncan Coutts and Don
--   Stewart.
module Data.ByteString.Lazy

-- | A space-efficient representation of a Word8 vector, supporting many
--   efficient operations. A <a>ByteString</a> contains 8-bit characters
--   only.
--   
--   Instances of Eq, Ord, Read, Show, Data, Typeable
data ByteString

-- | <i>O(1)</i> The empty <a>ByteString</a>
empty :: ByteString

-- | <i>O(1)</i> Convert a <a>Word8</a> into a <a>ByteString</a>
singleton :: Word8 -> ByteString

-- | <i>O(n)</i> Convert a '[Word8]' into a <a>ByteString</a>.
pack :: [Word8] -> ByteString

-- | <i>O(n)</i> Converts a <a>ByteString</a> to a '[Word8]'.
unpack :: ByteString -> [Word8]

-- | <i>O(1)</i> Convert a strict <a>ByteString</a> into a lazy
--   <a>ByteString</a>.
fromStrict :: ByteString -> ByteString

-- | <i>O(n)</i> Convert a lazy <a>ByteString</a> into a strict
--   <a>ByteString</a>.
--   
--   Note that this is an <i>expensive</i> operation that forces the whole
--   lazy ByteString into memory and then copies all the data. If possible,
--   try to avoid converting back and forth between strict and lazy
--   bytestrings.
toStrict :: ByteString -> ByteString

-- | <i>O(c)</i> Convert a list of strict <a>ByteString</a> into a lazy
--   <a>ByteString</a>
fromChunks :: [ByteString] -> ByteString

-- | <i>O(c)</i> Convert a lazy <a>ByteString</a> into a list of strict
--   <a>ByteString</a>
toChunks :: ByteString -> [ByteString]

-- | Consume the chunks of a lazy ByteString with a natural right fold.
foldrChunks :: (ByteString -> a -> a) -> a -> ByteString -> a

-- | Consume the chunks of a lazy ByteString with a strict, tail-recursive,
--   accumulating left fold.
foldlChunks :: (a -> ByteString -> a) -> a -> ByteString -> a

-- | <i>O(1)</i> <a>cons</a> is analogous to '(:)' for lists.
cons :: Word8 -> ByteString -> ByteString

-- | <i>O(1)</i> Unlike <a>cons</a>, 'cons\'' is strict in the ByteString
--   that we are consing onto. More precisely, it forces the head and the
--   first chunk. It does this because, for space efficiency, it may
--   coalesce the new byte onto the first 'chunk' rather than starting a
--   new 'chunk'.
--   
--   So that means you can't use a lazy recursive contruction like this:
--   
--   <pre>
--   let xs = cons\' c xs in xs
--   </pre>
--   
--   You can however use <a>cons</a>, as well as <a>repeat</a> and
--   <a>cycle</a>, to build infinite lazy ByteStrings.
cons' :: Word8 -> ByteString -> ByteString

-- | <i>O(n\</i>c)/ Append a byte to the end of a <a>ByteString</a>
snoc :: ByteString -> Word8 -> ByteString

-- | <i>O(n\</i>c)/ Append two ByteStrings
append :: ByteString -> ByteString -> ByteString

-- | <i>O(1)</i> Extract the first element of a ByteString, which must be
--   non-empty.
head :: ByteString -> Word8

-- | <i>O(1)</i> Extract the head and tail of a ByteString, returning
--   Nothing if it is empty.
uncons :: ByteString -> Maybe (Word8, ByteString)

-- | <i>O(n\</i>c)/ Extract the last element of a ByteString, which must be
--   finite and non-empty.
last :: ByteString -> Word8

-- | <i>O(1)</i> Extract the elements after the head of a ByteString, which
--   must be non-empty.
tail :: ByteString -> ByteString

-- | <i>O(n\</i>c)/ Return all the elements of a <a>ByteString</a> except
--   the last one.
init :: ByteString -> ByteString

-- | <i>O(1)</i> Test whether a ByteString is empty.
null :: ByteString -> Bool

-- | <i>O(n\</i>c)/ <a>length</a> returns the length of a ByteString as an
--   <a>Int64</a>
length :: ByteString -> Int64

-- | <i>O(n)</i> <a>map</a> <tt>f xs</tt> is the ByteString obtained by
--   applying <tt>f</tt> to each element of <tt>xs</tt>.
map :: (Word8 -> Word8) -> ByteString -> ByteString

-- | <i>O(n)</i> <a>reverse</a> <tt>xs</tt> returns the elements of
--   <tt>xs</tt> in reverse order.
reverse :: ByteString -> ByteString

-- | The <a>intersperse</a> function takes a <a>Word8</a> and a
--   <a>ByteString</a> and `intersperses' that byte between the elements of
--   the <a>ByteString</a>. It is analogous to the intersperse function on
--   Lists.
intersperse :: Word8 -> ByteString -> ByteString

-- | <i>O(n)</i> The <a>intercalate</a> function takes a <a>ByteString</a>
--   and a list of <a>ByteString</a>s and concatenates the list after
--   interspersing the first argument between each element of the list.
intercalate :: ByteString -> [ByteString] -> ByteString

-- | The <a>transpose</a> function transposes the rows and columns of its
--   <a>ByteString</a> argument.
transpose :: [ByteString] -> [ByteString]

-- | <a>foldl</a>, applied to a binary operator, a starting value
--   (typically the left-identity of the operator), and a ByteString,
--   reduces the ByteString using the binary operator, from left to right.
foldl :: (a -> Word8 -> a) -> a -> ByteString -> a

-- | 'foldl\'' is like <a>foldl</a>, but strict in the accumulator.
foldl' :: (a -> Word8 -> a) -> a -> ByteString -> a

-- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value
--   argument, and thus must be applied to non-empty <tt>ByteStrings</tt>.
foldl1 :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8

-- | 'foldl1\'' is like <a>foldl1</a>, but strict in the accumulator.
foldl1' :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8

-- | <a>foldr</a>, applied to a binary operator, a starting value
--   (typically the right-identity of the operator), and a ByteString,
--   reduces the ByteString using the binary operator, from right to left.
foldr :: (Word8 -> a -> a) -> a -> ByteString -> a

-- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value
--   argument, and thus must be applied to non-empty <a>ByteString</a>s
foldr1 :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8

-- | <i>O(n)</i> Concatenate a list of ByteStrings.
concat :: [ByteString] -> ByteString

-- | Map a function over a <a>ByteString</a> and concatenate the results
concatMap :: (Word8 -> ByteString) -> ByteString -> ByteString

-- | <i>O(n)</i> Applied to a predicate and a ByteString, <a>any</a>
--   determines if any element of the <a>ByteString</a> satisfies the
--   predicate.
any :: (Word8 -> Bool) -> ByteString -> Bool

-- | <i>O(n)</i> Applied to a predicate and a <a>ByteString</a>, <a>all</a>
--   determines if all elements of the <a>ByteString</a> satisfy the
--   predicate.
all :: (Word8 -> Bool) -> ByteString -> Bool

-- | <i>O(n)</i> <a>maximum</a> returns the maximum value from a
--   <a>ByteString</a>
maximum :: ByteString -> Word8

-- | <i>O(n)</i> <a>minimum</a> returns the minimum value from a
--   <a>ByteString</a>
minimum :: ByteString -> Word8

-- | <a>scanl</a> is similar to <a>foldl</a>, but returns a list of
--   successive reduced values from the left. This function will fuse.
--   
--   <pre>
--   scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
--   </pre>
--   
--   Note that
--   
--   <pre>
--   last (scanl f z xs) == foldl f z xs.
--   </pre>
scanl :: (Word8 -> Word8 -> Word8) -> Word8 -> ByteString -> ByteString

-- | The <a>mapAccumL</a> function behaves like a combination of <a>map</a>
--   and <a>foldl</a>; it applies a function to each element of a
--   ByteString, passing an accumulating parameter from left to right, and
--   returning a final value of this accumulator together with the new
--   ByteString.
mapAccumL :: (acc -> Word8 -> (acc, Word8)) -> acc -> ByteString -> (acc, ByteString)

-- | The <a>mapAccumR</a> function behaves like a combination of <a>map</a>
--   and <a>foldr</a>; it applies a function to each element of a
--   ByteString, passing an accumulating parameter from right to left, and
--   returning a final value of this accumulator together with the new
--   ByteString.
mapAccumR :: (acc -> Word8 -> (acc, Word8)) -> acc -> ByteString -> (acc, ByteString)

-- | <tt><a>repeat</a> x</tt> is an infinite ByteString, with <tt>x</tt>
--   the value of every element.
repeat :: Word8 -> ByteString

-- | <i>O(n)</i> <tt><a>replicate</a> n x</tt> is a ByteString of length
--   <tt>n</tt> with <tt>x</tt> the value of every element.
replicate :: Int64 -> Word8 -> ByteString

-- | <a>cycle</a> ties a finite ByteString into a circular one, or
--   equivalently, the infinite repetition of the original ByteString.
cycle :: ByteString -> ByteString

-- | <tt><a>iterate</a> f x</tt> returns an infinite ByteString of repeated
--   applications of <tt>f</tt> to <tt>x</tt>:
--   
--   <pre>
--   iterate f x == [x, f x, f (f x), ...]
--   </pre>
iterate :: (Word8 -> Word8) -> Word8 -> ByteString

-- | <i>O(n)</i> The <a>unfoldr</a> function is analogous to the List
--   'unfoldr'. <a>unfoldr</a> builds a ByteString from a seed value. The
--   function takes the element and returns <a>Nothing</a> if it is done
--   producing the ByteString or returns <a>Just</a> <tt>(a,b)</tt>, in
--   which case, <tt>a</tt> is a prepending to the ByteString and
--   <tt>b</tt> is used as the next element in a recursive call.
unfoldr :: (a -> Maybe (Word8, a)) -> a -> ByteString

-- | <i>O(n\</i>c)/ <a>take</a> <tt>n</tt>, applied to a ByteString
--   <tt>xs</tt>, returns the prefix of <tt>xs</tt> of length <tt>n</tt>,
--   or <tt>xs</tt> itself if <tt>n &gt; <a>length</a> xs</tt>.
take :: Int64 -> ByteString -> ByteString

-- | <i>O(n\</i>c)/ <a>drop</a> <tt>n xs</tt> returns the suffix of
--   <tt>xs</tt> after the first <tt>n</tt> elements, or <tt>[]</tt> if
--   <tt>n &gt; <a>length</a> xs</tt>.
drop :: Int64 -> ByteString -> ByteString

-- | <i>O(n\</i>c)/ <a>splitAt</a> <tt>n xs</tt> is equivalent to
--   <tt>(<a>take</a> n xs, <a>drop</a> n xs)</tt>.
splitAt :: Int64 -> ByteString -> (ByteString, ByteString)

-- | <a>takeWhile</a>, applied to a predicate <tt>p</tt> and a ByteString
--   <tt>xs</tt>, returns the longest prefix (possibly empty) of
--   <tt>xs</tt> of elements that satisfy <tt>p</tt>.
takeWhile :: (Word8 -> Bool) -> ByteString -> ByteString

-- | <a>dropWhile</a> <tt>p xs</tt> returns the suffix remaining after
--   <a>takeWhile</a> <tt>p xs</tt>.
dropWhile :: (Word8 -> Bool) -> ByteString -> ByteString

-- | <a>span</a> <tt>p xs</tt> breaks the ByteString into two segments. It
--   is equivalent to <tt>(<a>takeWhile</a> p xs, <a>dropWhile</a> p
--   xs)</tt>
span :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (<a>not</a> .
--   p)</tt>.
break :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | The <a>group</a> function takes a ByteString and returns a list of
--   ByteStrings such that the concatenation of the result is equal to the
--   argument. Moreover, each sublist in the result contains only equal
--   elements. For example,
--   
--   <pre>
--   group "Mississippi" = ["M","i","ss","i","ss","i","pp","i"]
--   </pre>
--   
--   It is a special case of <a>groupBy</a>, which allows the programmer to
--   supply their own equality test.
group :: ByteString -> [ByteString]

-- | The <a>groupBy</a> function is the non-overloaded version of
--   <a>group</a>.
groupBy :: (Word8 -> Word8 -> Bool) -> ByteString -> [ByteString]

-- | <i>O(n)</i> Return all initial segments of the given
--   <a>ByteString</a>, shortest first.
inits :: ByteString -> [ByteString]

-- | <i>O(n)</i> Return all final segments of the given <a>ByteString</a>,
--   longest first.
tails :: ByteString -> [ByteString]

-- | <i>O(n)</i> Break a <a>ByteString</a> into pieces separated by the
--   byte argument, consuming the delimiter. I.e.
--   
--   <pre>
--   split '\n' "a\nb\nd\ne" == ["a","b","d","e"]
--   split 'a'  "aXaXaXa"    == ["","X","X","X",""]
--   split 'x'  "x"          == ["",""]
--   </pre>
--   
--   and
--   
--   <pre>
--   intercalate [c] . split c == id
--   split == splitWith . (==)
--   </pre>
--   
--   As for all splitting functions in this library, this function does not
--   copy the substrings, it just constructs new <tt>ByteStrings</tt> that
--   are slices of the original.
split :: Word8 -> ByteString -> [ByteString]

-- | <i>O(n)</i> Splits a <a>ByteString</a> into components delimited by
--   separators, where the predicate returns True for a separator element.
--   The resulting components do not contain the separators. Two adjacent
--   separators result in an empty component in the output. eg.
--   
--   <pre>
--   splitWith (=='a') "aabbaca" == ["","","bb","c",""]
--   splitWith (=='a') []        == []
--   </pre>
splitWith :: (Word8 -> Bool) -> ByteString -> [ByteString]

-- | <i>O(n)</i> The <a>isPrefixOf</a> function takes two ByteStrings and
--   returns <a>True</a> iff the first is a prefix of the second.
isPrefixOf :: ByteString -> ByteString -> Bool

-- | <i>O(n)</i> The <a>isSuffixOf</a> function takes two ByteStrings and
--   returns <a>True</a> iff the first is a suffix of the second.
--   
--   The following holds:
--   
--   <pre>
--   isSuffixOf x y == reverse x `isPrefixOf` reverse y
--   </pre>
isSuffixOf :: ByteString -> ByteString -> Bool

-- | <i>O(n)</i> <a>elem</a> is the <a>ByteString</a> membership predicate.
elem :: Word8 -> ByteString -> Bool

-- | <i>O(n)</i> <a>notElem</a> is the inverse of <a>elem</a>
notElem :: Word8 -> ByteString -> Bool

-- | <i>O(n)</i> The <a>find</a> function takes a predicate and a
--   ByteString, and returns the first element in matching the predicate,
--   or <a>Nothing</a> if there is no such element.
--   
--   <pre>
--   find f p = case findIndex f p of Just n -&gt; Just (p ! n) ; _ -&gt; Nothing
--   </pre>
find :: (Word8 -> Bool) -> ByteString -> Maybe Word8

-- | <i>O(n)</i> <a>filter</a>, applied to a predicate and a ByteString,
--   returns a ByteString containing those characters that satisfy the
--   predicate.
filter :: (Word8 -> Bool) -> ByteString -> ByteString

-- | <i>O(n)</i> The <a>partition</a> function takes a predicate a
--   ByteString and returns the pair of ByteStrings with elements which do
--   and do not satisfy the predicate, respectively; i.e.,
--   
--   <pre>
--   partition p bs == (filter p xs, filter (not . p) xs)
--   </pre>
partition :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | <i>O(c)</i> <a>ByteString</a> index (subscript) operator, starting
--   from 0.
index :: ByteString -> Int64 -> Word8

-- | <i>O(n)</i> The <a>elemIndex</a> function returns the index of the
--   first element in the given <a>ByteString</a> which is equal to the
--   query element, or <a>Nothing</a> if there is no such element. This
--   implementation uses memchr(3).
elemIndex :: Word8 -> ByteString -> Maybe Int64

-- | <i>O(n)</i> The <a>elemIndices</a> function extends <a>elemIndex</a>,
--   by returning the indices of all elements equal to the query element,
--   in ascending order. This implementation uses memchr(3).
elemIndices :: Word8 -> ByteString -> [Int64]

-- | The <a>findIndex</a> function takes a predicate and a
--   <a>ByteString</a> and returns the index of the first element in the
--   ByteString satisfying the predicate.
findIndex :: (Word8 -> Bool) -> ByteString -> Maybe Int64

-- | The <a>findIndices</a> function extends <a>findIndex</a>, by returning
--   the indices of all elements satisfying the predicate, in ascending
--   order.
findIndices :: (Word8 -> Bool) -> ByteString -> [Int64]

-- | count returns the number of times its argument appears in the
--   ByteString
--   
--   <pre>
--   count = length . elemIndices
--   </pre>
--   
--   But more efficiently than using length on the intermediate list.
count :: Word8 -> ByteString -> Int64

-- | <i>O(n)</i> <a>zip</a> takes two ByteStrings and returns a list of
--   corresponding pairs of bytes. If one input ByteString is short, excess
--   elements of the longer ByteString are discarded. This is equivalent to
--   a pair of <a>unpack</a> operations.
zip :: ByteString -> ByteString -> [(Word8, Word8)]

-- | <a>zipWith</a> generalises <a>zip</a> by zipping with the function
--   given as the first argument, instead of a tupling function. For
--   example, <tt><a>zipWith</a> (+)</tt> is applied to two ByteStrings to
--   produce the list of corresponding sums.
zipWith :: (Word8 -> Word8 -> a) -> ByteString -> ByteString -> [a]

-- | <i>O(n)</i> <a>unzip</a> transforms a list of pairs of bytes into a
--   pair of ByteStrings. Note that this performs two <a>pack</a>
--   operations.
unzip :: [(Word8, Word8)] -> (ByteString, ByteString)

-- | <i>O(n)</i> Make a copy of the <a>ByteString</a> with its own storage.
--   This is mainly useful to allow the rest of the data pointed to by the
--   <a>ByteString</a> to be garbage collected, for example if a large
--   string has been read in, and only a small part of it is needed in the
--   rest of the program.
copy :: ByteString -> ByteString

-- | getContents. Equivalent to hGetContents stdin. Will read <i>lazily</i>
getContents :: IO ByteString

-- | Write a ByteString to stdout
putStr :: ByteString -> IO ()

-- | Write a ByteString to stdout, appending a newline byte

-- | <i>Deprecated: Use Data.ByteString.Lazy.Char8.putStrLn instead.
--   (Functions that rely on ASCII encodings belong in
--   Data.ByteString.Lazy.Char8) </i>
putStrLn :: ByteString -> IO ()

-- | The interact function takes a function of type <tt>ByteString -&gt;
--   ByteString</tt> as its argument. The entire input from the standard
--   input device is passed to this function as its argument, and the
--   resulting string is output on the standard output device.
interact :: (ByteString -> ByteString) -> IO ()

-- | Read an entire file <i>lazily</i> into a <a>ByteString</a>. The Handle
--   will be held open until EOF is encountered.
readFile :: FilePath -> IO ByteString

-- | Write a <a>ByteString</a> to a file.
writeFile :: FilePath -> ByteString -> IO ()

-- | Append a <a>ByteString</a> to a file.
appendFile :: FilePath -> ByteString -> IO ()

-- | Read entire handle contents <i>lazily</i> into a <a>ByteString</a>.
--   Chunks are read on demand, using the default chunk size.
--   
--   Once EOF is encountered, the Handle is closed.
--   
--   Note: the <a>Handle</a> should be placed in binary mode with
--   <a>hSetBinaryMode</a> for <a>hGetContents</a> to work correctly.
hGetContents :: Handle -> IO ByteString

-- | Read <tt>n</tt> bytes into a <a>ByteString</a>, directly from the
--   specified <a>Handle</a>.
hGet :: Handle -> Int -> IO ByteString

-- | hGetNonBlocking is similar to <a>hGet</a>, except that it will never
--   block waiting for data to become available, instead it returns only
--   whatever data is available. If there is no data available to be read,
--   <a>hGetNonBlocking</a> returns <a>empty</a>.
--   
--   Note: on Windows and with Haskell implementation other than GHC, this
--   function does not work correctly; it behaves identically to
--   <a>hGet</a>.
hGetNonBlocking :: Handle -> Int -> IO ByteString

-- | Outputs a <a>ByteString</a> to the specified <a>Handle</a>.
hPut :: Handle -> ByteString -> IO ()

-- | Similar to <a>hPut</a> except that it will never block. Instead it
--   returns any tail that did not get written. This tail may be
--   <a>empty</a> in the case that the whole string was written, or the
--   whole original string if nothing was written. Partial writes are also
--   possible.
--   
--   Note: on Windows and with Haskell implementation other than GHC, this
--   function does not work correctly; it behaves identically to
--   <a>hPut</a>.
hPutNonBlocking :: Handle -> ByteString -> IO ByteString

-- | A synonym for <tt>hPut</tt>, for compatibility
hPutStr :: Handle -> ByteString -> IO ()


-- | Manipulate <i>lazy</i> <a>ByteString</a>s using <a>Char</a>
--   operations. All Chars will be truncated to 8 bits. It can be expected
--   that these functions will run at identical speeds to their
--   <a>Word8</a> equivalents in <a>Data.ByteString.Lazy</a>.
--   
--   This module is intended to be imported <tt>qualified</tt>, to avoid
--   name clashes with <a>Prelude</a> functions. eg.
--   
--   <pre>
--   import qualified Data.ByteString.Lazy.Char8 as C
--   </pre>
--   
--   The Char8 interface to bytestrings provides an instance of IsString
--   for the ByteString type, enabling you to use string literals, and have
--   them implicitly packed to ByteStrings. Use <tt>{-# LANGUAGE
--   OverloadedStrings #-}</tt> to enable this.
module Data.ByteString.Lazy.Char8

-- | A space-efficient representation of a Word8 vector, supporting many
--   efficient operations. A <a>ByteString</a> contains 8-bit characters
--   only.
--   
--   Instances of Eq, Ord, Read, Show, Data, Typeable
data ByteString

-- | <i>O(1)</i> The empty <a>ByteString</a>
empty :: ByteString

-- | <i>O(1)</i> Convert a <a>Char</a> into a <a>ByteString</a>
singleton :: Char -> ByteString

-- | <i>O(n)</i> Convert a <a>String</a> into a <a>ByteString</a>.
pack :: [Char] -> ByteString

-- | <i>O(n)</i> Converts a <a>ByteString</a> to a <a>String</a>.
unpack :: ByteString -> [Char]

-- | <i>O(c)</i> Convert a list of strict <a>ByteString</a> into a lazy
--   <a>ByteString</a>
fromChunks :: [ByteString] -> ByteString

-- | <i>O(c)</i> Convert a lazy <a>ByteString</a> into a list of strict
--   <a>ByteString</a>
toChunks :: ByteString -> [ByteString]

-- | <i>O(1)</i> Convert a strict <a>ByteString</a> into a lazy
--   <a>ByteString</a>.
fromStrict :: ByteString -> ByteString

-- | <i>O(n)</i> Convert a lazy <a>ByteString</a> into a strict
--   <a>ByteString</a>.
--   
--   Note that this is an <i>expensive</i> operation that forces the whole
--   lazy ByteString into memory and then copies all the data. If possible,
--   try to avoid converting back and forth between strict and lazy
--   bytestrings.
toStrict :: ByteString -> ByteString

-- | <i>O(1)</i> <a>cons</a> is analogous to '(:)' for lists.
cons :: Char -> ByteString -> ByteString

-- | <i>O(1)</i> Unlike <a>cons</a>, 'cons\'' is strict in the ByteString
--   that we are consing onto. More precisely, it forces the head and the
--   first chunk. It does this because, for space efficiency, it may
--   coalesce the new byte onto the first 'chunk' rather than starting a
--   new 'chunk'.
--   
--   So that means you can't use a lazy recursive contruction like this:
--   
--   <pre>
--   let xs = cons\' c xs in xs
--   </pre>
--   
--   You can however use <a>cons</a>, as well as <a>repeat</a> and
--   <a>cycle</a>, to build infinite lazy ByteStrings.
cons' :: Char -> ByteString -> ByteString

-- | <i>O(n)</i> Append a Char to the end of a <a>ByteString</a>. Similar
--   to <a>cons</a>, this function performs a memcpy.
snoc :: ByteString -> Char -> ByteString

-- | <i>O(n\</i>c)/ Append two ByteStrings
append :: ByteString -> ByteString -> ByteString

-- | <i>O(1)</i> Extract the first element of a ByteString, which must be
--   non-empty.
head :: ByteString -> Char

-- | <i>O(1)</i> Extract the head and tail of a ByteString, returning
--   Nothing if it is empty.
uncons :: ByteString -> Maybe (Char, ByteString)

-- | <i>O(1)</i> Extract the last element of a packed string, which must be
--   non-empty.
last :: ByteString -> Char

-- | <i>O(1)</i> Extract the elements after the head of a ByteString, which
--   must be non-empty.
tail :: ByteString -> ByteString

-- | <i>O(n\</i>c)/ Return all the elements of a <a>ByteString</a> except
--   the last one.
init :: ByteString -> ByteString

-- | <i>O(1)</i> Test whether a ByteString is empty.
null :: ByteString -> Bool

-- | <i>O(n\</i>c)/ <a>length</a> returns the length of a ByteString as an
--   <a>Int64</a>
length :: ByteString -> Int64

-- | <i>O(n)</i> <a>map</a> <tt>f xs</tt> is the ByteString obtained by
--   applying <tt>f</tt> to each element of <tt>xs</tt>
map :: (Char -> Char) -> ByteString -> ByteString

-- | <i>O(n)</i> <a>reverse</a> <tt>xs</tt> returns the elements of
--   <tt>xs</tt> in reverse order.
reverse :: ByteString -> ByteString

-- | <i>O(n)</i> The <a>intersperse</a> function takes a Char and a
--   <a>ByteString</a> and `intersperses' that Char between the elements of
--   the <a>ByteString</a>. It is analogous to the intersperse function on
--   Lists.
intersperse :: Char -> ByteString -> ByteString

-- | <i>O(n)</i> The <a>intercalate</a> function takes a <a>ByteString</a>
--   and a list of <a>ByteString</a>s and concatenates the list after
--   interspersing the first argument between each element of the list.
intercalate :: ByteString -> [ByteString] -> ByteString

-- | The <a>transpose</a> function transposes the rows and columns of its
--   <a>ByteString</a> argument.
transpose :: [ByteString] -> [ByteString]

-- | <a>foldl</a>, applied to a binary operator, a starting value
--   (typically the left-identity of the operator), and a ByteString,
--   reduces the ByteString using the binary operator, from left to right.
foldl :: (a -> Char -> a) -> a -> ByteString -> a

-- | 'foldl\'' is like foldl, but strict in the accumulator.
foldl' :: (a -> Char -> a) -> a -> ByteString -> a

-- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value
--   argument, and thus must be applied to non-empty <tt>ByteStrings</tt>.
foldl1 :: (Char -> Char -> Char) -> ByteString -> Char

-- | 'foldl1\'' is like <a>foldl1</a>, but strict in the accumulator.
foldl1' :: (Char -> Char -> Char) -> ByteString -> Char

-- | <a>foldr</a>, applied to a binary operator, a starting value
--   (typically the right-identity of the operator), and a packed string,
--   reduces the packed string using the binary operator, from right to
--   left.
foldr :: (Char -> a -> a) -> a -> ByteString -> a

-- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value
--   argument, and thus must be applied to non-empty <a>ByteString</a>s
foldr1 :: (Char -> Char -> Char) -> ByteString -> Char

-- | <i>O(n)</i> Concatenate a list of ByteStrings.
concat :: [ByteString] -> ByteString

-- | Map a function over a <a>ByteString</a> and concatenate the results
concatMap :: (Char -> ByteString) -> ByteString -> ByteString

-- | Applied to a predicate and a ByteString, <a>any</a> determines if any
--   element of the <a>ByteString</a> satisfies the predicate.
any :: (Char -> Bool) -> ByteString -> Bool

-- | Applied to a predicate and a <a>ByteString</a>, <a>all</a> determines
--   if all elements of the <a>ByteString</a> satisfy the predicate.
all :: (Char -> Bool) -> ByteString -> Bool

-- | <a>maximum</a> returns the maximum value from a <a>ByteString</a>
maximum :: ByteString -> Char

-- | <a>minimum</a> returns the minimum value from a <a>ByteString</a>
minimum :: ByteString -> Char

-- | <a>scanl</a> is similar to <a>foldl</a>, but returns a list of
--   successive reduced values from the left. This function will fuse.
--   
--   <pre>
--   scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
--   </pre>
--   
--   Note that
--   
--   <pre>
--   last (scanl f z xs) == foldl f z xs.
--   </pre>
scanl :: (Char -> Char -> Char) -> Char -> ByteString -> ByteString

-- | The <a>mapAccumL</a> function behaves like a combination of <a>map</a>
--   and <a>foldl</a>; it applies a function to each element of a
--   ByteString, passing an accumulating parameter from left to right, and
--   returning a final value of this accumulator together with the new
--   ByteString.
mapAccumL :: (acc -> Char -> (acc, Char)) -> acc -> ByteString -> (acc, ByteString)

-- | The <a>mapAccumR</a> function behaves like a combination of <a>map</a>
--   and <a>foldr</a>; it applies a function to each element of a
--   ByteString, passing an accumulating parameter from right to left, and
--   returning a final value of this accumulator together with the new
--   ByteString.
mapAccumR :: (acc -> Char -> (acc, Char)) -> acc -> ByteString -> (acc, ByteString)

-- | <tt><a>repeat</a> x</tt> is an infinite ByteString, with <tt>x</tt>
--   the value of every element.
repeat :: Char -> ByteString

-- | <i>O(n)</i> <tt><a>replicate</a> n x</tt> is a ByteString of length
--   <tt>n</tt> with <tt>x</tt> the value of every element.
replicate :: Int64 -> Char -> ByteString

-- | <a>cycle</a> ties a finite ByteString into a circular one, or
--   equivalently, the infinite repetition of the original ByteString.
cycle :: ByteString -> ByteString

-- | <tt><a>iterate</a> f x</tt> returns an infinite ByteString of repeated
--   applications of <tt>f</tt> to <tt>x</tt>:
--   
--   <pre>
--   iterate f x == [x, f x, f (f x), ...]
--   </pre>
iterate :: (Char -> Char) -> Char -> ByteString

-- | <i>O(n)</i> The <a>unfoldr</a> function is analogous to the List
--   'unfoldr'. <a>unfoldr</a> builds a ByteString from a seed value. The
--   function takes the element and returns <a>Nothing</a> if it is done
--   producing the ByteString or returns <a>Just</a> <tt>(a,b)</tt>, in
--   which case, <tt>a</tt> is a prepending to the ByteString and
--   <tt>b</tt> is used as the next element in a recursive call.
unfoldr :: (a -> Maybe (Char, a)) -> a -> ByteString

-- | <i>O(n\</i>c)/ <a>take</a> <tt>n</tt>, applied to a ByteString
--   <tt>xs</tt>, returns the prefix of <tt>xs</tt> of length <tt>n</tt>,
--   or <tt>xs</tt> itself if <tt>n &gt; <a>length</a> xs</tt>.
take :: Int64 -> ByteString -> ByteString

-- | <i>O(n\</i>c)/ <a>drop</a> <tt>n xs</tt> returns the suffix of
--   <tt>xs</tt> after the first <tt>n</tt> elements, or <tt>[]</tt> if
--   <tt>n &gt; <a>length</a> xs</tt>.
drop :: Int64 -> ByteString -> ByteString

-- | <i>O(n\</i>c)/ <a>splitAt</a> <tt>n xs</tt> is equivalent to
--   <tt>(<a>take</a> n xs, <a>drop</a> n xs)</tt>.
splitAt :: Int64 -> ByteString -> (ByteString, ByteString)

-- | <a>takeWhile</a>, applied to a predicate <tt>p</tt> and a ByteString
--   <tt>xs</tt>, returns the longest prefix (possibly empty) of
--   <tt>xs</tt> of elements that satisfy <tt>p</tt>.
takeWhile :: (Char -> Bool) -> ByteString -> ByteString

-- | <a>dropWhile</a> <tt>p xs</tt> returns the suffix remaining after
--   <a>takeWhile</a> <tt>p xs</tt>.
dropWhile :: (Char -> Bool) -> ByteString -> ByteString

-- | <a>span</a> <tt>p xs</tt> breaks the ByteString into two segments. It
--   is equivalent to <tt>(<a>takeWhile</a> p xs, <a>dropWhile</a> p
--   xs)</tt>
span :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)

-- | <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (<a>not</a> .
--   p)</tt>.
break :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)

-- | The <a>group</a> function takes a ByteString and returns a list of
--   ByteStrings such that the concatenation of the result is equal to the
--   argument. Moreover, each sublist in the result contains only equal
--   elements. For example,
--   
--   <pre>
--   group "Mississippi" = ["M","i","ss","i","ss","i","pp","i"]
--   </pre>
--   
--   It is a special case of <a>groupBy</a>, which allows the programmer to
--   supply their own equality test.
group :: ByteString -> [ByteString]

-- | The <a>groupBy</a> function is the non-overloaded version of
--   <a>group</a>.
groupBy :: (Char -> Char -> Bool) -> ByteString -> [ByteString]

-- | <i>O(n)</i> Return all initial segments of the given
--   <a>ByteString</a>, shortest first.
inits :: ByteString -> [ByteString]

-- | <i>O(n)</i> Return all final segments of the given <a>ByteString</a>,
--   longest first.
tails :: ByteString -> [ByteString]

-- | <i>O(n)</i> Break a <a>ByteString</a> into pieces separated by the
--   byte argument, consuming the delimiter. I.e.
--   
--   <pre>
--   split '\n' "a\nb\nd\ne" == ["a","b","d","e"]
--   split 'a'  "aXaXaXa"    == ["","X","X","X"]
--   split 'x'  "x"          == ["",""]
--   </pre>
--   
--   and
--   
--   <pre>
--   intercalate [c] . split c == id
--   split == splitWith . (==)
--   </pre>
--   
--   As for all splitting functions in this library, this function does not
--   copy the substrings, it just constructs new <tt>ByteStrings</tt> that
--   are slices of the original.
split :: Char -> ByteString -> [ByteString]

-- | <i>O(n)</i> Splits a <a>ByteString</a> into components delimited by
--   separators, where the predicate returns True for a separator element.
--   The resulting components do not contain the separators. Two adjacent
--   separators result in an empty component in the output. eg.
--   
--   <pre>
--   splitWith (=='a') "aabbaca" == ["","","bb","c",""]
--   </pre>
splitWith :: (Char -> Bool) -> ByteString -> [ByteString]

-- | <a>lines</a> breaks a ByteString up into a list of ByteStrings at
--   newline Chars. The resulting strings do not contain newlines.
--   
--   As of bytestring 0.9.0.3, this function is stricter than its list
--   cousin.
lines :: ByteString -> [ByteString]

-- | <a>words</a> breaks a ByteString up into a list of words, which were
--   delimited by Chars representing white space. And
--   
--   <pre>
--   tokens isSpace = words
--   </pre>
words :: ByteString -> [ByteString]

-- | <a>unlines</a> is an inverse operation to <a>lines</a>. It joins
--   lines, after appending a terminating newline to each.
unlines :: [ByteString] -> ByteString

-- | The <a>unwords</a> function is analogous to the <a>unlines</a>
--   function, on words.
unwords :: [ByteString] -> ByteString

-- | <i>O(n)</i> The <a>isPrefixOf</a> function takes two ByteStrings and
--   returns <a>True</a> iff the first is a prefix of the second.
isPrefixOf :: ByteString -> ByteString -> Bool

-- | <i>O(n)</i> <a>elem</a> is the <a>ByteString</a> membership predicate.
--   This implementation uses <tt>memchr(3)</tt>.
elem :: Char -> ByteString -> Bool

-- | <i>O(n)</i> <a>notElem</a> is the inverse of <a>elem</a>
notElem :: Char -> ByteString -> Bool

-- | <i>O(n)</i> The <a>find</a> function takes a predicate and a
--   ByteString, and returns the first element in matching the predicate,
--   or <a>Nothing</a> if there is no such element.
find :: (Char -> Bool) -> ByteString -> Maybe Char

-- | <i>O(n)</i> <a>filter</a>, applied to a predicate and a ByteString,
--   returns a ByteString containing those characters that satisfy the
--   predicate.
filter :: (Char -> Bool) -> ByteString -> ByteString

-- | <i>O(1)</i> <a>ByteString</a> index (subscript) operator, starting
--   from 0.
index :: ByteString -> Int64 -> Char

-- | <i>O(n)</i> The <a>elemIndex</a> function returns the index of the
--   first element in the given <a>ByteString</a> which is equal (by
--   memchr) to the query element, or <a>Nothing</a> if there is no such
--   element.
elemIndex :: Char -> ByteString -> Maybe Int64

-- | <i>O(n)</i> The <a>elemIndices</a> function extends <a>elemIndex</a>,
--   by returning the indices of all elements equal to the query element,
--   in ascending order.
elemIndices :: Char -> ByteString -> [Int64]

-- | The <a>findIndex</a> function takes a predicate and a
--   <a>ByteString</a> and returns the index of the first element in the
--   ByteString satisfying the predicate.
findIndex :: (Char -> Bool) -> ByteString -> Maybe Int64

-- | The <a>findIndices</a> function extends <a>findIndex</a>, by returning
--   the indices of all elements satisfying the predicate, in ascending
--   order.
findIndices :: (Char -> Bool) -> ByteString -> [Int64]

-- | count returns the number of times its argument appears in the
--   ByteString
--   
--   <pre>
--   count      == length . elemIndices
--   count '\n' == length . lines
--   </pre>
--   
--   But more efficiently than using length on the intermediate list.
count :: Char -> ByteString -> Int64

-- | <i>O(n)</i> <a>zip</a> takes two ByteStrings and returns a list of
--   corresponding pairs of Chars. If one input ByteString is short, excess
--   elements of the longer ByteString are discarded. This is equivalent to
--   a pair of <a>unpack</a> operations, and so space usage may be large
--   for multi-megabyte ByteStrings
zip :: ByteString -> ByteString -> [(Char, Char)]

-- | <a>zipWith</a> generalises <a>zip</a> by zipping with the function
--   given as the first argument, instead of a tupling function. For
--   example, <tt><a>zipWith</a> (+)</tt> is applied to two ByteStrings to
--   produce the list of corresponding sums.
zipWith :: (Char -> Char -> a) -> ByteString -> ByteString -> [a]

-- | <i>O(n)</i> Make a copy of the <a>ByteString</a> with its own storage.
--   This is mainly useful to allow the rest of the data pointed to by the
--   <a>ByteString</a> to be garbage collected, for example if a large
--   string has been read in, and only a small part of it is needed in the
--   rest of the program.
copy :: ByteString -> ByteString

-- | readInt reads an Int from the beginning of the ByteString. If there is
--   no integer at the beginning of the string, it returns Nothing,
--   otherwise it just returns the int read, and the rest of the string.
readInt :: ByteString -> Maybe (Int, ByteString)

-- | readInteger reads an Integer from the beginning of the ByteString. If
--   there is no integer at the beginning of the string, it returns
--   Nothing, otherwise it just returns the int read, and the rest of the
--   string.
readInteger :: ByteString -> Maybe (Integer, ByteString)

-- | getContents. Equivalent to hGetContents stdin. Will read <i>lazily</i>
getContents :: IO ByteString

-- | Write a ByteString to stdout
putStr :: ByteString -> IO ()

-- | Write a ByteString to stdout, appending a newline byte
putStrLn :: ByteString -> IO ()

-- | The interact function takes a function of type <tt>ByteString -&gt;
--   ByteString</tt> as its argument. The entire input from the standard
--   input device is passed to this function as its argument, and the
--   resulting string is output on the standard output device.
interact :: (ByteString -> ByteString) -> IO ()

-- | Read an entire file <i>lazily</i> into a <a>ByteString</a>.
readFile :: FilePath -> IO ByteString

-- | Write a <a>ByteString</a> to a file.
writeFile :: FilePath -> ByteString -> IO ()

-- | Append a <a>ByteString</a> to a file.
appendFile :: FilePath -> ByteString -> IO ()

-- | Read entire handle contents <i>lazily</i> into a <a>ByteString</a>.
--   Chunks are read on demand, using the default chunk size.
--   
--   Once EOF is encountered, the Handle is closed.
--   
--   Note: the <a>Handle</a> should be placed in binary mode with
--   <a>hSetBinaryMode</a> for <a>hGetContents</a> to work correctly.
hGetContents :: Handle -> IO ByteString

-- | Read <tt>n</tt> bytes into a <a>ByteString</a>, directly from the
--   specified <a>Handle</a>.
hGet :: Handle -> Int -> IO ByteString

-- | hGetNonBlocking is similar to <a>hGet</a>, except that it will never
--   block waiting for data to become available, instead it returns only
--   whatever data is available. If there is no data available to be read,
--   <a>hGetNonBlocking</a> returns <a>empty</a>.
--   
--   Note: on Windows and with Haskell implementation other than GHC, this
--   function does not work correctly; it behaves identically to
--   <a>hGet</a>.
hGetNonBlocking :: Handle -> Int -> IO ByteString

-- | Outputs a <a>ByteString</a> to the specified <a>Handle</a>.
hPut :: Handle -> ByteString -> IO ()

-- | Similar to <a>hPut</a> except that it will never block. Instead it
--   returns any tail that did not get written. This tail may be
--   <a>empty</a> in the case that the whole string was written, or the
--   whole original string if nothing was written. Partial writes are also
--   possible.
--   
--   Note: on Windows and with Haskell implementation other than GHC, this
--   function does not work correctly; it behaves identically to
--   <a>hPut</a>.
hPutNonBlocking :: Handle -> ByteString -> IO ByteString

-- | A synonym for <tt>hPut</tt>, for compatibility
hPutStr :: Handle -> ByteString -> IO ()

-- | Write a ByteString to a handle, appending a newline byte
hPutStrLn :: Handle -> ByteString -> IO ()


-- | Constructing <a>Builder</a>s using ASCII-based encodings.
module Data.ByteString.Lazy.Builder.ASCII

-- | Decimal encoding of an <a>Int8</a> using the ASCII digits.
--   
--   e.g.
--   
--   <pre>
--   toLazyByteString (int8Dec 42)   = "42"
--   toLazyByteString (int8Dec (-1)) = "-1"
--   </pre>
int8Dec :: Int8 -> Builder

-- | Decimal encoding of an <a>Int16</a> using the ASCII digits.
int16Dec :: Int16 -> Builder

-- | Decimal encoding of an <a>Int32</a> using the ASCII digits.
int32Dec :: Int32 -> Builder

-- | Decimal encoding of an <a>Int64</a> using the ASCII digits.
int64Dec :: Int64 -> Builder

-- | Decimal encoding of an <a>Int</a> using the ASCII digits.
intDec :: Int -> Builder

-- | <i>Currently slow.</i> Decimal encoding of an <a>Integer</a> using the
--   ASCII digits.
integerDec :: Integer -> Builder

-- | Decimal encoding of a <a>Word8</a> using the ASCII digits.
word8Dec :: Word8 -> Builder

-- | Decimal encoding of a <a>Word16</a> using the ASCII digits.
word16Dec :: Word16 -> Builder

-- | Decimal encoding of a <a>Word32</a> using the ASCII digits.
word32Dec :: Word32 -> Builder

-- | Decimal encoding of a <a>Word64</a> using the ASCII digits.
word64Dec :: Word64 -> Builder

-- | Decimal encoding of a <a>Word</a> using the ASCII digits.
wordDec :: Word -> Builder

-- | <i>Currently slow.</i> Decimal encoding of an IEEE <a>Float</a>.
floatDec :: Float -> Builder

-- | <i>Currently slow.</i> Decimal encoding of an IEEE <a>Double</a>.
doubleDec :: Double -> Builder

-- | Shortest hexadecimal encoding of a <a>Word8</a> using lower-case
--   characters.
word8Hex :: Word8 -> Builder

-- | Shortest hexadecimal encoding of a <a>Word16</a> using lower-case
--   characters.
word16Hex :: Word16 -> Builder

-- | Shortest hexadecimal encoding of a <a>Word32</a> using lower-case
--   characters.
word32Hex :: Word32 -> Builder

-- | Shortest hexadecimal encoding of a <a>Word64</a> using lower-case
--   characters.
word64Hex :: Word64 -> Builder

-- | Shortest hexadecimal encoding of a <a>Word</a> using lower-case
--   characters.
wordHex :: Word -> Builder

-- | Encode a <a>Int8</a> using 2 nibbles (hexadecimal digits).
int8HexFixed :: Int8 -> Builder

-- | Encode a <a>Int16</a> using 4 nibbles.
int16HexFixed :: Int16 -> Builder

-- | Encode a <a>Int32</a> using 8 nibbles.
int32HexFixed :: Int32 -> Builder

-- | Encode a <a>Int64</a> using 16 nibbles.
int64HexFixed :: Int64 -> Builder

-- | Encode a <a>Word8</a> using 2 nibbles (hexadecimal digits).
word8HexFixed :: Word8 -> Builder

-- | Encode a <a>Word16</a> using 4 nibbles.
word16HexFixed :: Word16 -> Builder

-- | Encode a <a>Word32</a> using 8 nibbles.
word32HexFixed :: Word32 -> Builder

-- | Encode a <a>Word64</a> using 16 nibbles.
word64HexFixed :: Word64 -> Builder

-- | Encode an IEEE <a>Float</a> using 8 nibbles.
floatHexFixed :: Float -> Builder

-- | Encode an IEEE <a>Double</a> using 16 nibbles.
doubleHexFixed :: Double -> Builder

-- | Encode each byte of a <a>ByteString</a> using its fixed-width hex
--   encoding.
byteStringHexFixed :: ByteString -> Builder

-- | Encode each byte of a lazy <a>ByteString</a> using its fixed-width hex
--   encoding.
lazyByteStringHexFixed :: ByteString -> Builder


-- | <a>Builder</a>s are used to efficiently construct sequences of bytes
--   from smaller parts. Typically, such a construction is part of the
--   implementation of an <i>encoding</i>, i.e., a function for converting
--   Haskell values to sequences of bytes. Examples of encodings are the
--   generation of the sequence of bytes representing a HTML document to be
--   sent in a HTTP response by a web application or the serialization of a
--   Haskell value using a fixed binary format.
--   
--   For an <i>efficient implementation of an encoding</i>, it is important
--   that (a) little time is spent on converting the Haskell values to the
--   resulting sequence of bytes <i>and</i> (b) that the representation of
--   the resulting sequence is such that it can be consumed efficiently.
--   <a>Builder</a>s support (a) by providing an <i>O(1)</i> concatentation
--   operation and efficient implementations of basic encodings for
--   <a>Char</a>s, <a>Int</a>s, and other standard Haskell values. They
--   support (b) by providing their result as a lazy <a>ByteString</a>,
--   which is internally just a linked list of pointers to <i>chunks</i> of
--   consecutive raw memory. Lazy <a>ByteString</a>s can be efficiently
--   consumed by functions that write them to a file or send them over a
--   network socket. Note that each chunk boundary incurs expensive extra
--   work (e.g., a system call) that must be amortized over the work spent
--   on consuming the chunk body. <a>Builder</a>s therefore take special
--   care to ensure that the average chunk size is large enough. The
--   precise meaning of large enough is application dependent. The current
--   implementation is tuned for an average chunk size between 4kb and
--   32kb, which should suit most applications.
--   
--   As a simple example of an encoding implementation, we show how to
--   efficiently convert the following representation of mixed-data tables
--   to an UTF-8 encoded Comma-Separated-Values (CSV) table.
--   
--   <pre>
--   data Cell = StringC String
--             | IntC Int
--             deriving( Eq, Ord, Show )
--   
--   type Row   = [Cell]
--   type Table = [Row]
--   </pre>
--   
--   We use the following imports and abbreviate <a>mappend</a> to simplify
--   reading.
--   
--   <pre>
--   import qualified <a>Data.ByteString.Lazy</a>               as L
--   import           <a>Data.ByteString.Lazy.Builder</a>
--   import           <a>Data.ByteString.Lazy.Builder.ASCII</a> (<a>intDec</a>)
--   import           Data.Monoid
--   import           Data.Foldable                        (<a>foldMap</a>)
--   import           Data.List                            (<a>intersperse</a>)
--   
--   infixr 4 &lt;&gt;
--   (&lt;&gt;) :: <a>Monoid</a> m =&gt; m -&gt; m -&gt; m
--   (&lt;&gt;) = <a>mappend</a>
--   </pre>
--   
--   CSV is a character-based representation of tables. For maximal
--   modularity, we could first render <tt>Table</tt>s as <a>String</a>s
--   and then encode this <a>String</a> using some Unicode character
--   encoding. However, this sacrifices performance due to the intermediate
--   <a>String</a> representation being built and thrown away right
--   afterwards. We get rid of this intermediate <a>String</a>
--   representation by fixing the character encoding to UTF-8 and using
--   <a>Builder</a>s to convert <tt>Table</tt>s directly to UTF-8 encoded
--   CSV tables represented as lazy <a>ByteString</a>s.
--   
--   <pre>
--   encodeUtf8CSV :: Table -&gt; L.ByteString
--   encodeUtf8CSV = <a>toLazyByteString</a> . renderTable
--   
--   renderTable :: Table -&gt; Builder
--   renderTable rs = <a>mconcat</a> [renderRow r &lt;&gt; <a>charUtf8</a> '\n' | r &lt;- rs]
--   
--   renderRow :: Row -&gt; Builder
--   renderRow []     = <a>mempty</a>
--   renderRow (c:cs) =
--       renderCell c &lt;&gt; mconcat [ charUtf8 ',' &lt;&gt; renderCell c' | c' &lt;- cs ]
--   
--   renderCell :: Cell -&gt; Builder
--   renderCell (StringC cs) = renderString cs
--   renderCell (IntC i)     = <a>intDec</a> i
--   
--   renderString :: String -&gt; Builder
--   renderString cs = charUtf8 '"' &lt;&gt; foldMap escape cs &lt;&gt; charUtf8 '"'
--     where
--       escape '\\' = charUtf8 '\\' &lt;&gt; charUtf8 '\\'
--       escape '\"' = charUtf8 '\\' &lt;&gt; charUtf8 '\"'
--       escape c    = charUtf8 c
--   </pre>
--   
--   Note that the ASCII encoding is a subset of the UTF-8 encoding, which
--   is why we can use the optimized function <a>intDec</a> to encode an
--   <a>Int</a> as a decimal number with UTF-8 encoded digits. Using
--   <a>intDec</a> is more efficient than <tt><a>stringUtf8</a> .
--   <a>show</a></tt>, as it avoids constructing an intermediate
--   <a>String</a>. Avoiding this intermediate data structure significantly
--   improves performance because encoding <tt>Cell</tt>s is the core
--   operation for rendering CSV-tables. See
--   <a>Data.ByteString.Lazy.Builder.BasicEncoding</a> for further
--   information on how to improve the performance of
--   <tt>renderString</tt>.
--   
--   We demonstrate our UTF-8 CSV encoding function on the following table.
--   
--   <pre>
--   strings :: [String]
--   strings =  ["hello", "\"1\"", "λ-wörld"]
--   
--   table :: Table
--   table = [map StringC strings, map IntC [-3..3]]
--   </pre>
--   
--   The expression <tt>encodeUtf8CSV table</tt> results in the following
--   lazy <a>ByteString</a>.
--   
--   <pre>
--   Chunk "\"hello\",\"\\\"1\\\"\",\"\206\187-w\195\182rld\"\n-3,-2,-1,0,1,2,3\n" Empty
--   </pre>
--   
--   We can clearly see that we are converting to a <i>binary</i> format.
--   The 'λ' and 'ö' characters, which have a Unicode codepoint above 127,
--   are expanded to their corresponding UTF-8 multi-byte representation.
--   
--   We use the <tt>criterion</tt> library
--   (<a>http://hackage.haskell.org/package/criterion</a>) to benchmark the
--   efficiency of our encoding function on the following table.
--   
--   <pre>
--   import Criterion.Main     -- add this import to the ones above
--   
--   maxiTable :: Table
--   maxiTable = take 1000 $ cycle table
--   
--   main :: IO ()
--   main = defaultMain
--     [ bench "encodeUtf8CSV maxiTable (original)" $
--         whnf (L.length . encodeUtf8CSV) maxiTable
--     ]
--   </pre>
--   
--   On a Core2 Duo 2.20GHz on a 32-bit Linux, the above code takes 1ms to
--   generate the 22'500 bytes long lazy <a>ByteString</a>. Looking again
--   at the definitions above, we see that we took care to avoid
--   intermediate data structures, as otherwise we would sacrifice
--   performance. For example, the following (arguably simpler) definition
--   of <tt>renderRow</tt> is about 20% slower.
--   
--   <pre>
--   renderRow :: Row -&gt; Builder
--   renderRow  = mconcat . intersperse (charUtf8 ',') . map renderCell
--   </pre>
--   
--   Similarly, using <i>O(n)</i> concatentations like <a>++</a> or the
--   equivalent <a>concat</a> operations on strict and lazy
--   <a>ByteString</a>s should be avoided. The following definition of
--   <tt>renderString</tt> is also about 20% slower.
--   
--   <pre>
--   renderString :: String -&gt; Builder
--   renderString cs = charUtf8 $ "\"" ++ concatMap escape cs ++ "\""
--     where
--       escape '\\' = "\\"
--       escape '\"' = "\\\""
--       escape c    = return c
--   </pre>
--   
--   Apart from removing intermediate data-structures, encodings can be
--   optimized further by fine-tuning their execution parameters using the
--   functions in <a>Data.ByteString.Lazy.Builder.Extras</a> and their
--   "inner loops" using the functions in
--   <a>Data.ByteString.Lazy.Builder.BasicEncoding</a>.
module Data.ByteString.Lazy.Builder

-- | <a>Builder</a>s denote sequences of bytes. They are <a>Monoid</a>s
--   where <a>mempty</a> is the zero-length sequence and <a>mappend</a> is
--   concatenation, which runs in <i>O(1)</i>.
data Builder

-- | Execute a <a>Builder</a> and return the generated chunks as a lazy
--   <a>ByteString</a>. The work is performed lazy, i.e., only when a chunk
--   of the lazy <a>ByteString</a> is forced.
toLazyByteString :: Builder -> ByteString

-- | Output a <a>Builder</a> to a <a>Handle</a>. The <a>Builder</a> is
--   executed directly on the buffer of the <a>Handle</a>. If the buffer is
--   too small (or not present), then it is replaced with a large enough
--   buffer.
--   
--   It is recommended that the <a>Handle</a> is set to binary and
--   <tt>BlockBuffering</tt> mode. See <tt>hSetBinaryMode</tt> and
--   <tt>hSetBuffering</tt>.
--   
--   This function is more efficient than <tt>hPut .
--   <a>toLazyByteString</a></tt> because in many cases no buffer
--   allocation has to be done. Moreover, the results of several executions
--   of short <a>Builder</a>s are concatenated in the <a>Handle</a>s
--   buffer, therefore avoiding unnecessary buffer flushes.
hPutBuilder :: Handle -> Builder -> IO ()

-- | Create a <a>Builder</a> denoting the same sequence of bytes as a
--   strict <a>ByteString</a>. The <a>Builder</a> inserts large
--   <a>ByteString</a>s directly, but copies small ones to ensure that the
--   generated chunks are large on average.
byteString :: ByteString -> Builder

-- | Create a <a>Builder</a> denoting the same sequence of bytes as a lazy
--   <a>ByteString</a>. The <a>Builder</a> inserts large chunks of the lazy
--   <a>ByteString</a> directly, but copies small ones to ensure that the
--   generated chunks are large on average.
lazyByteString :: ByteString -> Builder

-- | Encode a single signed byte as-is.
int8 :: Int8 -> Builder

-- | Encode a single unsigned byte as-is.
word8 :: Word8 -> Builder

-- | Encode an <a>Int16</a> in big endian format.
int16BE :: Int16 -> Builder

-- | Encode an <a>Int32</a> in big endian format.
int32BE :: Int32 -> Builder

-- | Encode an <a>Int64</a> in big endian format.
int64BE :: Int64 -> Builder

-- | Encode a <a>Word16</a> in big endian format.
word16BE :: Word16 -> Builder

-- | Encode a <a>Word32</a> in big endian format.
word32BE :: Word32 -> Builder

-- | Encode a <a>Word64</a> in big endian format.
word64BE :: Word64 -> Builder

-- | Encode a <a>Float</a> in big endian format.
floatBE :: Float -> Builder

-- | Encode a <a>Double</a> in big endian format.
doubleBE :: Double -> Builder

-- | Encode an <a>Int16</a> in little endian format.
int16LE :: Int16 -> Builder

-- | Encode an <a>Int32</a> in little endian format.
int32LE :: Int32 -> Builder

-- | Encode an <a>Int64</a> in little endian format.
int64LE :: Int64 -> Builder

-- | Encode a <a>Word16</a> in little endian format.
word16LE :: Word16 -> Builder

-- | Encode a <a>Word32</a> in little endian format.
word32LE :: Word32 -> Builder

-- | Encode a <a>Word64</a> in little endian format.
word64LE :: Word64 -> Builder

-- | Encode a <a>Float</a> in little endian format.
floatLE :: Float -> Builder

-- | Encode a <a>Double</a> in little endian format.
doubleLE :: Double -> Builder

-- | Char7 encode a <a>Char</a>.
char7 :: Char -> Builder

-- | Char7 encode a <a>String</a>.
string7 :: String -> Builder

-- | Char8 encode a <a>Char</a>.
char8 :: Char -> Builder

-- | Char8 encode a <a>String</a>.
string8 :: String -> Builder

-- | UTF-8 encode a <a>Char</a>.
charUtf8 :: Char -> Builder

-- | UTF-8 encode a <a>String</a>.
stringUtf8 :: String -> Builder


-- | Extra functions for creating and executing <a>Builder</a>s. They are
--   intended for application-specific fine-tuning the performance of
--   <a>Builder</a>s.
module Data.ByteString.Lazy.Builder.Extras

-- | Execute a <a>Builder</a> with custom execution parameters.
--   
--   This function is forced to be inlined to allow fusing with the
--   allocation strategy despite its rather heavy code-size. We therefore
--   recommend that you introduce a top-level function once you have fixed
--   your strategy. This avoids unnecessary code duplication. For example,
--   the default <a>Builder</a> execution function
--   <tt>toLazyByteString</tt> is defined as follows.
--   
--   <pre>
--   {--}
--   toLazyByteString =
--     toLazyByteStringWith (<a>safeStrategy</a> <a>smallChunkSize</a> <a>defaultChunkSize</a>) empty
--   </pre>
--   
--   where <tt>empty</tt> is the zero-length lazy <a>ByteString</a>.
--   
--   In most cases, the parameters used by <tt>toLazyByteString</tt> give
--   good performance. A sub-performing case of <tt>toLazyByteString</tt>
--   is executing short (&lt;128 bytes) <a>Builder</a>s. In this case, the
--   allocation overhead for the first 4kb buffer and the trimming cost
--   dominate the cost of executing the <a>Builder</a>. You can avoid this
--   problem using
--   
--   <pre>
--   toLazyByteStringWith (safeStrategy 128 smallChunkSize) empty
--   </pre>
--   
--   This reduces the allocation and trimming overhead, as all generated
--   <a>ByteString</a>s fit into the first buffer and there is no trimming
--   required, if more than 64 bytes are written.
toLazyByteStringWith :: AllocationStrategy -> ByteString -> Builder -> ByteString

-- | A buffer allocation strategy for executing <a>Builder</a>s.
data AllocationStrategy

-- | Use this strategy for generating lazy <a>ByteString</a>s whose chunks
--   are likely to survive one garbage collection. This strategy trims
--   buffers that are filled less than half in order to avoid spilling too
--   much memory.
safeStrategy :: Int -> Int -> AllocationStrategy

-- | Use this strategy for generating lazy <a>ByteString</a>s whose chunks
--   are discarded right after they are generated. For example, if you just
--   generate them to write them to a network socket.
untrimmedStrategy :: Int -> Int -> AllocationStrategy

-- | The recommended chunk size. Currently set to 4k, less the memory
--   management overhead
smallChunkSize :: Int

-- | The chunk size used for I/O. Currently set to 32k, less the memory
--   management overhead
defaultChunkSize :: Int

-- | Construct a <a>Builder</a> that copies the strict <a>ByteString</a>.
--   
--   Use this function to create <a>Builder</a>s from smallish (<tt>&lt;=
--   4kb</tt>) <a>ByteString</a>s or if you need to guarantee that the
--   <a>ByteString</a> is not shared with the chunks generated by the
--   <a>Builder</a>.
byteStringCopy :: ByteString -> Builder

-- | Construct a <a>Builder</a> that always inserts the strict
--   <a>ByteString</a> directly as a chunk.
--   
--   This implies flushing the output buffer, even if it contains just a
--   single byte. You should therefore use <a>byteStringInsert</a> only for
--   large (<tt>&gt; 8kb</tt>) <a>ByteString</a>s. Otherwise, the generated
--   chunks are too fragmented to be processed efficiently afterwards.
byteStringInsert :: ByteString -> Builder

-- | Construct a <a>Builder</a> that copies the strict <a>ByteString</a>s,
--   if it is smaller than the treshold, and inserts it directly otherwise.
--   
--   For example, <tt>byteStringThreshold 1024</tt> copies strict
--   <a>ByteString</a>s whose size is less or equal to 1kb, and inserts
--   them directly otherwise. This implies that the average chunk-size of
--   the generated lazy <a>ByteString</a> may be as low as 513 bytes, as
--   there could always be just a single byte between the directly inserted
--   1025 byte, strict <a>ByteString</a>s.
byteStringThreshold :: Int -> ByteString -> Builder

-- | Construct a <a>Builder</a> that copies the lazy <a>ByteString</a>.
lazyByteStringCopy :: ByteString -> Builder

-- | Construct a <a>Builder</a> that inserts all chunks of the lazy
--   <a>ByteString</a> directly.
lazyByteStringInsert :: ByteString -> Builder

-- | Construct a <a>Builder</a> that uses the thresholding strategy of
--   <a>byteStringThreshold</a> for each chunk of the lazy
--   <a>ByteString</a>.
lazyByteStringThreshold :: Int -> ByteString -> Builder

-- | Flush the current buffer. This introduces a chunk boundary.
flush :: Builder

-- | Encode a single native machine <a>Int</a>. The <a>Int</a> is encoded
--   in host order, host endian form, for the machine you're on. On a 64
--   bit machine the <a>Int</a> is an 8 byte value, on a 32 bit machine, 4
--   bytes. Values encoded this way are not portable to different endian or
--   int sized machines, without conversion.
intHost :: Int -> Builder

-- | Encode a <a>Int16</a> in native host order and host endianness.
int16Host :: Int16 -> Builder

-- | Encode a <a>Int32</a> in native host order and host endianness.
int32Host :: Int32 -> Builder

-- | Encode a <a>Int64</a> in native host order and host endianness.
int64Host :: Int64 -> Builder

-- | Encode a single native machine <a>Word</a>. The <a>Word</a> is encoded
--   in host order, host endian form, for the machine you're on. On a 64
--   bit machine the <a>Word</a> is an 8 byte value, on a 32 bit machine, 4
--   bytes. Values encoded this way are not portable to different endian or
--   word sized machines, without conversion.
wordHost :: Word -> Builder

-- | Encode a <a>Word16</a> in native host order and host endianness.
word16Host :: Word16 -> Builder

-- | Encode a <a>Word32</a> in native host order and host endianness.
word32Host :: Word32 -> Builder

-- | Encode a <a>Word64</a> in native host order and host endianness.
word64Host :: Word64 -> Builder

-- | Encode a <a>Float</a> in native host order. Values encoded this way
--   are not portable to different endian machines, without conversion.
floatHost :: Float -> Builder

-- | Encode a <a>Double</a> in native host order.
doubleHost :: Double -> Builder
