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


-- | Fast, effectful byte streams.
--   
--   This library enables fast and safe streaming of byte data, in either
--   <tt>Word8</tt> or <tt>Char</tt> form. It is a core addition to the
--   <a>streaming ecosystem</a> and avoids the usual pitfalls of combinbing
--   lazy <tt>ByteString</tt>s with lazy <tt>IO</tt>.
--   
--   We follow the philosophy shared by <tt>streaming</tt> that "the best
--   API is the one you already know". Thus this library mirrors the API of
--   the <tt>bytestring</tt> library as closely as possible.
--   
--   See the module documentation and the README for more information.
@package streaming-bytestring
@version 0.2.1


module Streaming.ByteString.Internal

-- | A space-efficient representation of a succession of <a>Word8</a>
--   vectors, supporting many efficient operations.
--   
--   An effectful <a>ByteStream</a> contains 8-bit bytes, or by using the
--   operations from <a>Streaming.ByteString.Char8</a> it can be
--   interpreted as containing 8-bit characters.
data ByteStream m r
Empty :: r -> ByteStream m r
Chunk :: {-# UNPACK #-} !ByteString -> ByteStream m r -> ByteStream m r
Go :: m (ByteStream m r) -> ByteStream m r

-- | A type alias for back-compatibility.

-- | <i>Deprecated: Use ByteStream instead.</i>
type ByteString = ByteStream

-- | Smart constructor for <a>Chunk</a>.
consChunk :: ByteString -> ByteStream m r -> ByteStream m r

-- | The memory management overhead. Currently this is tuned for GHC only.
chunkOverhead :: Int

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

-- | Construct a succession of chunks from its Church encoding (compare
--   <tt>GHC.Exts.build</tt>)
materialize :: (forall x. (r -> x) -> (ByteString -> x -> x) -> (m x -> x) -> x) -> ByteStream m r

-- | Resolve a succession of chunks into its Church encoding; this is not a
--   safe operation; it is equivalent to exposing the constructors
dematerialize :: Monad m => ByteStream m r -> forall x. (r -> x) -> (ByteString -> x -> x) -> (m x -> x) -> x

-- | Consume the chunks of an effectful <a>ByteString</a> with a natural
--   right fold.
foldrChunks :: Monad m => (ByteString -> a -> a) -> a -> ByteStream m r -> m a

-- | Consume the chunks of an effectful <a>ByteString</a> with a left fold.
--   Suitable for use with <a>mapped</a>.
foldlChunks :: Monad m => (a -> ByteString -> a) -> a -> ByteStream m r -> m (Of a r)

-- | Consume the chunks of an effectful ByteString with a natural right
--   monadic fold.
foldrChunksM :: Monad m => (ByteString -> m a -> m a) -> m a -> ByteStream m r -> m a

-- | Like <a>foldlChunks</a>, but fold effectfully. Suitable for use with
--   <a>mapped</a>.
foldlChunksM :: Monad m => (a -> ByteString -> m a) -> m a -> ByteStream m r -> m (Of a r)

-- | <tt>chunkFold</tt> is preferable to <tt>foldlChunks</tt> since it is
--   an appropriate argument for <tt>Control.Foldl.purely</tt> which
--   permits many folds and sinks to be run simultaneously on one
--   bytestream.
chunkFold :: Monad m => (x -> ByteString -> x) -> x -> (x -> a) -> ByteStream m r -> m (Of a r)

-- | <a>chunkFoldM</a> is preferable to <a>foldlChunksM</a> since it is an
--   appropriate argument for <a>impurely</a> which permits many folds and
--   sinks to be run simultaneously on one bytestream.
chunkFoldM :: Monad m => (x -> ByteString -> m x) -> m x -> (x -> m a) -> ByteStream m r -> m (Of a r)

-- | Instead of mapping over each <a>Word8</a> or <a>Char</a>, map over
--   each strict <a>ByteString</a> chunk in the stream.
chunkMap :: Monad m => (ByteString -> ByteString) -> ByteStream m r -> ByteStream m r

-- | Like <a>chunkMap</a>, but map effectfully.
chunkMapM :: Monad m => (ByteString -> m ByteString) -> ByteStream m r -> ByteStream m r

-- | Like <a>chunkMapM</a>, but discard the result of each effectful
--   mapping.
chunkMapM_ :: Monad m => (ByteString -> m x) -> ByteStream m r -> m r

-- | Given some continual monadic action that produces strict
--   <a>ByteString</a> chunks, produce a stream of bytes.
unfoldMChunks :: Monad m => (s -> m (Maybe (ByteString, s))) -> s -> ByteStream m ()

-- | Like <a>unfoldMChunks</a>, but feed through a final <tt>r</tt> return
--   value.
unfoldrChunks :: Monad m => (s -> m (Either r (ByteString, s))) -> s -> ByteStream m r

-- | Convert a vanilla <a>Stream</a> of characters into a stream of bytes.
--   
--   <i>Note:</i> Each <a>Char</a> value is truncated to 8 bits.
packChars :: Monad m => Stream (Of Char) m r -> ByteStream m r

-- | Packing and unpacking from lists packBytes' :: Monad m =&gt; [Word8]
--   -&gt; ByteString m () packBytes' cs0 = packChunks 32 cs0 where
--   packChunks n cs = case B.packUptoLenBytes n cs of (bs, []) -&gt; Chunk
--   bs (Empty ()) (bs, cs') -&gt; Chunk bs (packChunks (min (n * 2)
--   BI.smallChunkSize) cs') -- packUptoLenBytes :: Int -&gt; [Word8] -&gt;
--   (ByteString, [Word8]) packUptoLenBytes len xs0 =
--   accursedUnutterablePerformIO (createUptoN' len $ p -&gt; go p len xs0)
--   where go !_ !n [] = return (len-n, []) go !_ !0 xs = return (len, xs)
--   go !p !n (x:xs) = poke p x &gt;&gt; go (p <a>plusPtr</a> 1) (n-1) xs
--   createUptoN' :: Int -&gt; (Ptr Word8 -&gt; IO (Int, a)) -&gt; IO
--   (B.ByteString, a) createUptoN' l f = do fp &lt;- B.mallocByteString l
--   (l', res) <a>withForeignPtr fp $ p -</a> f p assert (l' &lt;= l) $
--   return (B.PS fp 0 l', res) {-# INLINABLE packBytes' #-}
--   
--   Convert a <a>Stream</a> of pure <a>Word8</a> into a chunked
--   <a>ByteStream</a>.
packBytes :: Monad m => Stream (Of Word8) m r -> ByteStream m r

-- | The reverse of <a>packChars</a>. Given a stream of bytes, produce a
--   <a>Stream</a> individual bytes.
unpackBytes :: Monad m => ByteStream m r -> Stream (Of Word8) m r

-- | Yield-style smart constructor for <a>Chunk</a>.
chunk :: ByteString -> ByteStream m ()

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

-- | Reconceive an effect that results in an effectful bytestring as an
--   effectful bytestring. Compare Streaming.mwrap. The closest equivalent
--   of
--   
--   <pre>
--   &gt;&gt;&gt; Streaming.wrap :: f (Stream f m r) -&gt; Stream f m r
--   </pre>
--   
--   is here <tt>consChunk</tt>. <tt>mwrap</tt> is the smart constructor
--   for the internal <tt>Go</tt> constructor.
mwrap :: m (ByteStream m r) -> ByteStream m r

-- | Internal utility for <tt>unfoldr</tt>.
unfoldrNE :: Int -> (a -> Either r (Word8, a)) -> a -> (ByteString, Either r a)

-- | Stream chunks from something that contains <tt>m (Maybe
--   ByteString)</tt> until it returns <a>Nothing</a>. <a>reread</a> is of
--   particular use rendering <tt>io-streams</tt> input streams as byte
--   streams in the present sense.
--   
--   <pre>
--   import qualified Data.ByteString as B
--   import qualified System.IO.Streams as S
--   Q.reread S.read            :: S.InputStream B.ByteString -&gt; Q.ByteStream IO ()
--   Q.reread (liftIO . S.read) :: MonadIO m =&gt; S.InputStream B.ByteString -&gt; Q.ByteStream m ()
--   </pre>
--   
--   The other direction here is
--   
--   <pre>
--   S.unfoldM Q.unconsChunk    :: Q.ByteString IO r -&gt; IO (S.InputStream B.ByteString)
--   </pre>
reread :: Monad m => (s -> m (Maybe ByteString)) -> s -> ByteStream m ()

-- | Copied from Data.ByteString.Unsafe for compatibility with older
--   bytestring.
unsafeLast :: ByteString -> Word8

-- | Copied from Data.ByteString.Unsafe for compatibility with older
--   bytestring.
unsafeInit :: ByteString -> ByteString

-- | Make the information in a bytestring available to more than one
--   eliminating fold, e.g.
--   
--   <pre>
--   &gt;&gt;&gt; Q.count 'l' $ Q.count 'o' $ Q.copy $ "hello\nworld"
--   3 :&gt; (2 :&gt; ())
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Q.length $ Q.count 'l' $ Q.count 'o' $ Q.copy $ Q.copy "hello\nworld"
--   11 :&gt; (3 :&gt; (2 :&gt; ()))
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; runResourceT $ Q.writeFile "hello2.txt" $ Q.writeFile "hello1.txt" $ Q.copy $ "hello\nworld\n"
--   
--   &gt;&gt;&gt; :! cat hello2.txt
--   hello
--   world
--   
--   &gt;&gt;&gt; :! cat hello1.txt
--   hello
--   world
--   </pre>
--   
--   This sort of manipulation could as well be acheived by combining folds
--   - using <tt>Control.Foldl</tt> for example. But any sort of
--   manipulation can be involved in the fold. Here are a couple of trivial
--   complications involving splitting by lines:
--   
--   <pre>
--   &gt;&gt;&gt; let doubleLines = Q.unlines . maps (&lt;* Q.chunk "\n" ) . Q.lines
--   
--   &gt;&gt;&gt; let emphasize = Q.unlines . maps (&lt;* Q.chunk "!" ) . Q.lines
--   
--   &gt;&gt;&gt; runResourceT $ Q.writeFile "hello2.txt" $ emphasize $ Q.writeFile "hello1.txt" $ doubleLines $ Q.copy $ "hello\nworld"
--   
--   &gt;&gt;&gt; :! cat hello2.txt
--   hello!
--   world!
--   
--   &gt;&gt;&gt; :! cat hello1.txt
--   hello
--   
--   world
--   </pre>
--   
--   As with the parallel operations in <tt>Streaming.Prelude</tt>, we have
--   
--   <pre>
--   Q.effects . Q.copy       = id
--   hoist Q.effects . Q.copy = id
--   </pre>
--   
--   The duplication does not by itself involve the copying of bytestring
--   chunks; it just makes two references to each chunk as it arises. This
--   does, however double the number of constructors associated with each
--   chunk.
copy :: Monad m => ByteStream m r -> ByteStream (ByteStream m) r

-- | <a>findIndexOrEnd</a> is a variant of findIndex, that returns the
--   length of the string if no element is found, rather than Nothing.
findIndexOrEnd :: (Word8 -> Bool) -> ByteString -> Int

-- | Like <tt>bracket</tt>, but specialized for <a>ByteString</a>.
bracketByteString :: MonadResource m => IO a -> (a -> IO ()) -> (a -> ByteStream m b) -> ByteStream m b

-- | Synonym of <a>withForeignPtr</a> for GHC prior to 9.0.
unsafeWithForeignPtr :: ForeignPtr a -> (Ptr a -> IO b) -> IO b
instance GHC.Base.Monad m => GHC.Base.Functor (Streaming.ByteString.Internal.ByteStream m)
instance GHC.Base.Monad m => GHC.Base.Applicative (Streaming.ByteString.Internal.ByteStream m)
instance GHC.Base.Monad m => GHC.Base.Monad (Streaming.ByteString.Internal.ByteStream m)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Streaming.ByteString.Internal.ByteStream m)
instance Control.Monad.Trans.Class.MonadTrans Streaming.ByteString.Internal.ByteStream
instance Control.Monad.Morph.MFunctor Streaming.ByteString.Internal.ByteStream
instance (r GHC.Types.~ ()) => Data.String.IsString (Streaming.ByteString.Internal.ByteStream m r)
instance (m GHC.Types.~ Data.Functor.Identity.Identity, GHC.Show.Show r) => GHC.Show.Show (Streaming.ByteString.Internal.ByteStream m r)
instance (GHC.Base.Semigroup r, GHC.Base.Monad m) => GHC.Base.Semigroup (Streaming.ByteString.Internal.ByteStream m r)
instance (GHC.Base.Monoid r, GHC.Base.Monad m) => GHC.Base.Monoid (Streaming.ByteString.Internal.ByteStream m r)
instance Control.Monad.Base.MonadBase b m => Control.Monad.Base.MonadBase b (Streaming.ByteString.Internal.ByteStream m)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Streaming.ByteString.Internal.ByteStream m)
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Streaming.ByteString.Internal.ByteStream m)
instance Control.Monad.Trans.Resource.Internal.MonadResource m => Control.Monad.Trans.Resource.Internal.MonadResource (Streaming.ByteString.Internal.ByteStream m)


-- | See the simple examples of use <a>here</a> and the <tt>ghci</tt>
--   examples especially in <a>Streaming.ByteString.Char8</a>. We begin
--   with a slight modification of the documentation to
--   <a>Data.ByteString.Lazy</a>:
--   
--   A time and space-efficient implementation of effectful byte streams
--   using a stream of packed <a>Word8</a> arrays, suitable for high
--   performance use, both in terms of large data quantities, or high speed
--   requirements. Streaming ByteStrings are encoded as streams of strict
--   chunks of bytes.
--   
--   A key feature of streaming 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 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>, 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 streaming, like lazy, ByteStrings are
--   usually within a few percent of strict ones.
--   
--   This module is intended to be imported <tt>qualified</tt>, to avoid
--   name clashes with <a>Prelude</a> functions. eg.
--   
--   <pre>
--   import qualified Streaming.ByteString as Q
--   </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. Streaming variant by Michael Thompson, following the ideas of
--   Gabriel Gonzales' pipes-bytestring.
module Streaming.ByteString

-- | A space-efficient representation of a succession of <a>Word8</a>
--   vectors, supporting many efficient operations.
--   
--   An effectful <a>ByteStream</a> contains 8-bit bytes, or by using the
--   operations from <a>Streaming.ByteString.Char8</a> it can be
--   interpreted as containing 8-bit characters.
data ByteStream m r

-- | A type alias for back-compatibility.

-- | <i>Deprecated: Use ByteStream instead.</i>
type ByteString = ByteStream

-- | <i>O(1)</i> The empty <a>ByteStream</a> -- i.e. <tt>return ()</tt>
--   Note that <tt>ByteStream m w</tt> is generally a monoid for monoidal
--   values of <tt>w</tt>, like <tt>()</tt>.
empty :: ByteStream m ()

-- | <i>O(1)</i> Yield a <a>Word8</a> as a minimal <a>ByteStream</a>.
singleton :: Monad m => Word8 -> ByteStream m ()

-- | <i>O(n)</i> Convert a monadic stream of individual <a>Word8</a>s into
--   a packed byte stream.
pack :: Monad m => Stream (Of Word8) m r -> ByteStream m r

-- | <i>O(n)</i> Converts a packed byte stream into a stream of individual
--   bytes.
unpack :: Monad m => ByteStream m r -> Stream (Of Word8) m r

-- | <i>O(c)</i> Transmute a pseudo-pure lazy bytestring to its
--   representation as a monadic stream of chunks.
--   
--   <pre>
--   &gt;&gt;&gt; Q.putStrLn $ Q.fromLazy "hi"
--   hi
--   
--   &gt;&gt;&gt; Q.fromLazy "hi"
--   Chunk "hi" (Empty (()))  -- note: a 'show' instance works in the identity monad
--   
--   &gt;&gt;&gt; Q.fromLazy $ BL.fromChunks ["here", "are", "some", "chunks"]
--   Chunk "here" (Chunk "are" (Chunk "some" (Chunk "chunks" (Empty (())))))
--   </pre>
fromLazy :: Monad m => ByteString -> ByteStream m ()

-- | <i>O(n)</i> Convert an effectful byte stream into a single lazy
--   <a>ByteString</a> with the same internal chunk structure, retaining
--   the original return value.
--   
--   This is the canonical way of breaking streaming (<a>toStrict</a> and
--   the like are far more demonic). Essentially one is dividing the
--   interleaved layers of effects and bytes into one immense layer of
--   effects, followed by the memory of the succession of bytes.
--   
--   Because one preserves the return value, <a>toLazy</a> is a suitable
--   argument for <a>mapped</a>:
--   
--   <pre>
--   S.mapped Q.toLazy :: Stream (ByteStream m) m r -&gt; Stream (Of L.ByteString) m r
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Q.toLazy "hello"
--   "hello" :&gt; ()
--   
--   &gt;&gt;&gt; S.toListM $ traverses Q.toLazy $ Q.lines "one\ntwo\nthree\nfour\nfive\n"
--   ["one","two","three","four","five",""]  -- [L.ByteString]
--   </pre>
toLazy :: Monad m => ByteStream m r -> m (Of ByteString r)

-- | <i>O(n)</i> Convert an effectful byte stream into a single lazy
--   <a>ByteStream</a> with the same internal chunk structure. See
--   <a>toLazy</a> which preserve connectedness by keeping the return value
--   of the effectful bytestring.
toLazy_ :: Monad m => ByteStream m r -> m ByteString

-- | <i>O(c)</i> Convert a monadic stream of individual strict
--   <a>ByteString</a> chunks into a byte stream.
fromChunks :: Monad m => Stream (Of ByteString) m r -> ByteStream m r

-- | <i>O(c)</i> Convert a byte stream into a stream of individual strict
--   bytestrings. This of course exposes the internal chunk structure.
toChunks :: Monad m => ByteStream m r -> Stream (Of ByteString) m r

-- | <i>O(1)</i> Yield a strict <a>ByteString</a> chunk.
fromStrict :: ByteString -> ByteStream m ()

-- | <i>O(n)</i> Convert a monadic byte stream into a single strict
--   <a>ByteString</a>, retaining the return value of the original pair.
--   This operation is for use with <a>mapped</a>.
--   
--   <pre>
--   mapped R.toStrict :: Monad m =&gt; Stream (ByteStream m) m r -&gt; Stream (Of ByteString) m r
--   </pre>
--   
--   It is subject to all the objections one makes to Data.ByteString.Lazy
--   <a>toStrict</a>; all of these are devastating.
toStrict :: Monad m => ByteStream m r -> m (Of ByteString r)

-- | <i>O(n)</i> Convert a byte stream into a single strict
--   <a>ByteString</a>.
--   
--   Note that this is an <i>expensive</i> operation that forces the whole
--   monadic ByteString into memory and then copies all the data. If
--   possible, try to avoid converting back and forth between streaming and
--   strict bytestrings.
toStrict_ :: Monad m => ByteStream m r -> m ByteString

-- | Perform the effects contained in an effectful bytestring, ignoring the
--   bytes.
effects :: Monad m => ByteStream m r -> m r

-- | Make the information in a bytestring available to more than one
--   eliminating fold, e.g.
--   
--   <pre>
--   &gt;&gt;&gt; Q.count 'l' $ Q.count 'o' $ Q.copy $ "hello\nworld"
--   3 :&gt; (2 :&gt; ())
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Q.length $ Q.count 'l' $ Q.count 'o' $ Q.copy $ Q.copy "hello\nworld"
--   11 :&gt; (3 :&gt; (2 :&gt; ()))
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; runResourceT $ Q.writeFile "hello2.txt" $ Q.writeFile "hello1.txt" $ Q.copy $ "hello\nworld\n"
--   
--   &gt;&gt;&gt; :! cat hello2.txt
--   hello
--   world
--   
--   &gt;&gt;&gt; :! cat hello1.txt
--   hello
--   world
--   </pre>
--   
--   This sort of manipulation could as well be acheived by combining folds
--   - using <tt>Control.Foldl</tt> for example. But any sort of
--   manipulation can be involved in the fold. Here are a couple of trivial
--   complications involving splitting by lines:
--   
--   <pre>
--   &gt;&gt;&gt; let doubleLines = Q.unlines . maps (&lt;* Q.chunk "\n" ) . Q.lines
--   
--   &gt;&gt;&gt; let emphasize = Q.unlines . maps (&lt;* Q.chunk "!" ) . Q.lines
--   
--   &gt;&gt;&gt; runResourceT $ Q.writeFile "hello2.txt" $ emphasize $ Q.writeFile "hello1.txt" $ doubleLines $ Q.copy $ "hello\nworld"
--   
--   &gt;&gt;&gt; :! cat hello2.txt
--   hello!
--   world!
--   
--   &gt;&gt;&gt; :! cat hello1.txt
--   hello
--   
--   world
--   </pre>
--   
--   As with the parallel operations in <tt>Streaming.Prelude</tt>, we have
--   
--   <pre>
--   Q.effects . Q.copy       = id
--   hoist Q.effects . Q.copy = id
--   </pre>
--   
--   The duplication does not by itself involve the copying of bytestring
--   chunks; it just makes two references to each chunk as it arises. This
--   does, however double the number of constructors associated with each
--   chunk.
copy :: Monad m => ByteStream m r -> ByteStream (ByteStream m) r

-- | Perform the effects contained in the second in an effectful pair of
--   bytestrings, ignoring the bytes. It would typically be used at the
--   type
--   
--   <pre>
--   ByteStream m (ByteStream m r) -&gt; ByteStream m r
--   </pre>
drained :: (Monad m, MonadTrans t, Monad (t m)) => t m (ByteStream m r) -> t m r

-- | Reconceive an effect that results in an effectful bytestring as an
--   effectful bytestring. Compare Streaming.mwrap. The closest equivalent
--   of
--   
--   <pre>
--   &gt;&gt;&gt; Streaming.wrap :: f (Stream f m r) -&gt; Stream f m r
--   </pre>
--   
--   is here <tt>consChunk</tt>. <tt>mwrap</tt> is the smart constructor
--   for the internal <tt>Go</tt> constructor.
mwrap :: m (ByteStream m r) -> ByteStream m r

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

-- | <i>O(n)</i> The <a>intercalate</a> function takes a <a>ByteStream</a>
--   and a list of <a>ByteStream</a>s and concatenates the list after
--   interspersing the first argument between each element of the list.
intercalate :: Monad m => ByteStream m () -> Stream (ByteStream m) m r -> ByteStream m r

-- | The <a>intersperse</a> function takes a <a>Word8</a> and a
--   <a>ByteStream</a> and `intersperses' that byte between the elements of
--   the <a>ByteStream</a>. It is analogous to the intersperse function on
--   Streams.
intersperse :: Monad m => Word8 -> ByteStream m r -> ByteStream m r

-- | <i>O(1)</i> <a>cons</a> is analogous to <tt>(:)</tt> for lists.
cons :: Monad m => Word8 -> ByteStream m r -> ByteStream m r

-- | <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 byte streams.
cons' :: Word8 -> ByteStream m r -> ByteStream m r

-- | <i>O(n/c)</i> Append a byte to the end of a <a>ByteStream</a>.
snoc :: Monad m => ByteStream m r -> Word8 -> ByteStream m r

-- | <i>O(n/c)</i> Append two <a>ByteString</a>s together.
append :: Monad m => ByteStream m r -> ByteStream m s -> ByteStream m s

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

-- | <i>O(1)</i> Extract the head and tail of a <a>ByteStream</a>, or its
--   return value if it is empty. This is the 'natural' uncons for an
--   effectful byte stream.
uncons :: Monad m => ByteStream m r -> m (Either r (Word8, ByteStream m r))

-- | The same as <a>uncons</a>, will be removed in the next version.

-- | <i>Deprecated: Use uncons instead.</i>
nextByte :: Monad m => ByteStream m r -> m (Either r (Word8, ByteStream m r))

-- | <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (<a>not</a> .
--   p)</tt>.
break :: Monad m => (Word8 -> Bool) -> ByteStream m r -> ByteStream m (ByteStream m r)

-- | <i>O(n/c)</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>.
--   
--   <pre>
--   &gt;&gt;&gt; Q.putStrLn $ Q.drop 6 "Wisconsin"
--   sin
--   
--   &gt;&gt;&gt; Q.putStrLn $ Q.drop 16 "Wisconsin"
--   </pre>
drop :: Monad m => Int64 -> ByteStream m r -> ByteStream m r

-- | <a>dropWhile</a> <tt>p xs</tt> returns the suffix remaining after
--   <a>takeWhile</a> <tt>p xs</tt>.
dropWhile :: Monad m => (Word8 -> Bool) -> ByteStream m r -> ByteStream m r

-- | The <a>group</a> function takes a ByteStream and returns a list of
--   ByteStreams 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 :: Monad m => ByteStream m r -> Stream (ByteStream m) m r

-- | The <a>groupBy</a> function is a generalized version of <a>group</a>.
groupBy :: Monad m => (Word8 -> Word8 -> Bool) -> ByteStream m r -> Stream (ByteStream m) m r

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

-- | <i>O(n/c)</i> <a>splitAt</a> <tt>n xs</tt> is equivalent to
--   <tt>(<a>take</a> n xs, <a>drop</a> n xs)</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; rest &lt;- Q.putStrLn $ Q.splitAt 3 "therapist is a danger to good hyphenation, as Knuth notes"
--   the
--   
--   &gt;&gt;&gt; Q.putStrLn $ Q.splitAt 19 rest
--   rapist is a danger
--   </pre>
splitAt :: Monad m => Int64 -> ByteStream m r -> ByteStream m (ByteStream m r)

-- | <i>O(n)</i> Splits a <a>ByteStream</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 :: Monad m => (Word8 -> Bool) -> ByteStream m r -> Stream (ByteStream m) m r

-- | <i>O(n/c)</i> <a>take</a> <tt>n</tt>, applied to a ByteStream
--   <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>.
--   
--   Note that in the streaming context this drops the final return value;
--   <a>splitAt</a> preserves this information, and is sometimes to be
--   preferred.
--   
--   <pre>
--   &gt;&gt;&gt; Q.putStrLn $ Q.take 8 $ "Is there a God?" &gt;&gt; return True
--   Is there
--   
--   &gt;&gt;&gt; Q.putStrLn $ "Is there a God?" &gt;&gt; return True
--   Is there a God?
--   True
--   
--   &gt;&gt;&gt; rest &lt;- Q.putStrLn $ Q.splitAt 8 $ "Is there a God?" &gt;&gt; return True
--   Is there
--   
--   &gt;&gt;&gt; Q.effects  rest
--   True
--   </pre>
take :: Monad m => Int64 -> ByteStream m r -> ByteStream m ()

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

-- | <i>O(n)</i> Break a <a>ByteStream</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 <a>ByteStream</a>s that
--   are slices of the original.
split :: Monad m => Word8 -> ByteStream m r -> Stream (ByteStream m) m r

-- | <i>O(n)</i> Concatenate a stream of byte streams.
concat :: Monad m => Stream (ByteStream m) m r -> ByteStream m r

-- | Remove empty ByteStrings from a stream of bytestrings.
denull :: Monad m => Stream (ByteStream m) m r -> Stream (ByteStream m) m r

-- | Take a builder constructed otherwise and convert it to a genuine
--   streaming bytestring.
--   
--   <pre>
--   &gt;&gt;&gt; Q.putStrLn $ Q.toStreamingByteString $ stringUtf8 "哈斯克尔" &lt;&gt; stringUtf8 " " &lt;&gt; integerDec 98
--   哈斯克尔 98
--   </pre>
--   
--   <a>This benchmark</a> shows its performance is indistinguishable from
--   <tt>toLazyByteString</tt>
toStreamingByteString :: MonadIO m => Builder -> ByteStream m ()

-- | Take a builder and convert it to a genuine streaming bytestring, using
--   a specific allocation strategy.
toStreamingByteStringWith :: MonadIO m => AllocationStrategy -> Builder -> ByteStream m ()

-- | A simple construction of a builder from a <a>ByteString</a>.
--   
--   <pre>
--   &gt;&gt;&gt; let aaa = "10000 is a number\n" :: Q.ByteString IO ()
--   
--   &gt;&gt;&gt; hPutBuilder  IO.stdout $ toBuilder  aaa
--   10000 is a number
--   </pre>
toBuilder :: ByteStream IO () -> Builder

-- | Concatenate a stream of builders (not a streaming bytestring!) into a
--   single builder.
--   
--   <pre>
--   &gt;&gt;&gt; let aa = yield (integerDec 10000) &gt;&gt; yield (string8 " is a number.") &gt;&gt; yield (char8 '\n')
--   
--   &gt;&gt;&gt; hPutBuilder IO.stdout $ concatBuilders aa
--   10000 is a number.
--   </pre>
concatBuilders :: Stream (Of Builder) IO () -> Builder

-- | <tt><a>repeat</a> x</tt> is an infinite ByteStream, with <tt>x</tt>
--   the value of every element.
--   
--   <pre>
--   &gt;&gt;&gt; R.stdout $ R.take 50 $ R.repeat 60
--   &lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;
--   
--   &gt;&gt;&gt; Q.putStrLn $ Q.take 50 $ Q.repeat 'z'
--   zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
--   </pre>
repeat :: Word8 -> ByteStream m r

-- | <tt><a>iterate</a> f x</tt> returns an infinite ByteStream of repeated
--   applications -- of <tt>f</tt> to <tt>x</tt>:
--   
--   <pre>
--   iterate f x == [x, f x, f (f x), ...]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; R.stdout $ R.take 50 $ R.iterate succ 39
--   ()*+,-./0123456789:;&lt;=&gt;?@ABCDEFGHIJKLMNOPQRSTUVWXY
--   
--   &gt;&gt;&gt; Q.putStrLn $ Q.take 50 $ Q.iterate succ '\''
--   ()*+,-./0123456789:;&lt;=&gt;?@ABCDEFGHIJKLMNOPQRSTUVWXY
--   </pre>
iterate :: (Word8 -> Word8) -> Word8 -> ByteStream m r

-- | <a>cycle</a> ties a finite ByteStream into a circular one, or
--   equivalently, the infinite repetition of the original ByteStream. For
--   an empty bytestring (like <tt>return 17</tt>) it of course makes an
--   unproductive loop
--   
--   <pre>
--   &gt;&gt;&gt; Q.putStrLn $ Q.take 7 $ Q.cycle  "y\n"
--   y
--   y
--   y
--   y
--   </pre>
cycle :: Monad m => ByteStream m r -> ByteStream m s

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

-- | Like <a>unfoldM</a>, but yields a final <tt>r</tt> when the
--   <a>Word8</a> generation is complete.
unfoldr :: (a -> Either r (Word8, a)) -> a -> ByteStream m r

-- | Stream chunks from something that contains <tt>m (Maybe
--   ByteString)</tt> until it returns <a>Nothing</a>. <a>reread</a> is of
--   particular use rendering <tt>io-streams</tt> input streams as byte
--   streams in the present sense.
--   
--   <pre>
--   import qualified Data.ByteString as B
--   import qualified System.IO.Streams as S
--   Q.reread S.read            :: S.InputStream B.ByteString -&gt; Q.ByteStream IO ()
--   Q.reread (liftIO . S.read) :: MonadIO m =&gt; S.InputStream B.ByteString -&gt; Q.ByteStream m ()
--   </pre>
--   
--   The other direction here is
--   
--   <pre>
--   S.unfoldM Q.unconsChunk    :: Q.ByteString IO r -&gt; IO (S.InputStream B.ByteString)
--   </pre>
reread :: Monad m => (s -> m (Maybe ByteString)) -> s -> ByteStream m ()

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

-- | <a>fold</a> keeps the return value of the left-folded bytestring.
--   Useful for simultaneous folds over a segmented bytestream.
fold :: Monad m => (x -> Word8 -> x) -> x -> (x -> b) -> ByteStream m r -> m (Of b r)

-- | <a>fold_</a>, applied to a binary operator, a starting value
--   (typically the left-identity of the operator), and a ByteStream,
--   reduces the ByteStream using the binary operator, from left to right.
--   We use the style of the foldl library for left folds
fold_ :: Monad m => (x -> Word8 -> x) -> x -> (x -> b) -> ByteStream m () -> m b

-- | <i>O(c)</i> Extract the first element of a <a>ByteStream</a>, if there
--   is one. Suitable for use with <a>mapped</a>:
--   
--   <pre>
--   S.mapped Q.head :: Stream (Q.ByteStream m) m r -&gt; Stream (Of (Maybe Word8)) m r
--   </pre>
head :: Monad m => ByteStream m r -> m (Of (Maybe Word8) r)

-- | <i>O(1)</i> Extract the first element of a <a>ByteStream</a>, which
--   must be non-empty.
head_ :: Monad m => ByteStream m r -> m Word8

-- | Extract the last element of a <a>ByteStream</a>, if possible. Suitable
--   for use with <a>mapped</a>:
--   
--   <pre>
--   S.mapped Q.last :: Streaming (ByteStream m) m r -&gt; Stream (Of (Maybe Word8)) m r
--   </pre>
last :: Monad m => ByteStream m r -> m (Of (Maybe Word8) r)

-- | <i>O(n/c)</i> Extract the last element of a <a>ByteStream</a>, which
--   must be finite and non-empty.
last_ :: Monad m => ByteStream m r -> m Word8

-- | <i>O(n/c)</i> <a>length</a> returns the length of a byte stream as an
--   <a>Int</a> together with the return value. This makes various maps
--   possible.
--   
--   <pre>
--   &gt;&gt;&gt; Q.length "one\ntwo\three\nfour\nfive\n"
--   23 :&gt; ()
--   
--   &gt;&gt;&gt; S.print $ S.take 3 $ mapped Q.length $ Q.lines "one\ntwo\three\nfour\nfive\n"
--   3
--   8
--   4
--   </pre>
length :: Monad m => ByteStream m r -> m (Of Int r)

-- | Like <a>length</a>, report the length in bytes of the
--   <a>ByteStream</a> by running through its contents. Since the return
--   value is in the effect <tt>m</tt>, this is one way to "get out" of the
--   stream.
length_ :: Monad m => ByteStream m r -> m Int

-- | Test whether a <a>ByteStream</a> is empty, collecting its return
--   value; to reach the return value, this operation must check the whole
--   length of the string.
--   
--   <pre>
--   &gt;&gt;&gt; Q.null "one\ntwo\three\nfour\nfive\n"
--   False :&gt; ()
--   
--   &gt;&gt;&gt; Q.null ""
--   True :&gt; ()
--   
--   &gt;&gt;&gt; S.print $ mapped R.null $ Q.lines "yours,\nMeredith"
--   False
--   False
--   </pre>
--   
--   Suitable for use with <a>mapped</a>:
--   
--   <pre>
--   S.mapped Q.null :: Streaming (ByteStream m) m r -&gt; Stream (Of Bool) m r
--   </pre>
null :: Monad m => ByteStream m r -> m (Of Bool r)

-- | <i>O(1)</i> Test whether a <a>ByteStream</a> is empty. The value is of
--   course in the monad of the effects.
--   
--   <pre>
--   &gt;&gt;&gt; Q.null "one\ntwo\three\nfour\nfive\n"
--   False
--   
--   &gt;&gt;&gt; Q.null $ Q.take 0 Q.stdin
--   True
--   
--   &gt;&gt;&gt; :t Q.null $ Q.take 0 Q.stdin
--   Q.null $ Q.take 0 Q.stdin :: MonadIO m =&gt; m Bool
--   </pre>
null_ :: Monad m => ByteStream m r -> m Bool

-- | <i>O1</i> Distinguish empty from non-empty lines, while maintaining
--   streaming; the empty ByteStrings are on the right
--   
--   <pre>
--   &gt;&gt;&gt; nulls  ::  ByteStream m r -&gt; m (Sum (ByteStream m) (ByteStream m) r)
--   </pre>
--   
--   There are many (generally slower) ways to remove null bytestrings from
--   a <tt>Stream (ByteStream m) m r</tt> (besides using <tt>denull</tt>).
--   If we pass next to
--   
--   <pre>
--   &gt;&gt;&gt; mapped nulls bs :: Stream (Sum (ByteStream m) (ByteStream m)) m r
--   </pre>
--   
--   then can then apply <tt>Streaming.separate</tt> to get
--   
--   <pre>
--   &gt;&gt;&gt; separate (mapped nulls bs) :: Stream (ByteStream m) (Stream (ByteStream m) m) r
--   </pre>
--   
--   The inner monad is now made of the empty bytestrings; we act on this
--   with <tt>hoist</tt> , considering that
--   
--   <pre>
--   &gt;&gt;&gt; :t Q.effects . Q.concat
--   Q.effects . Q.concat
--     :: Monad m =&gt; Stream (Q.ByteStream m) m r -&gt; m r
--   </pre>
--   
--   we have
--   
--   <pre>
--   &gt;&gt;&gt; hoist (Q.effects . Q.concat) . separate . mapped Q.nulls
--     :: Monad n =&gt;  Stream (Q.ByteStream n) n b -&gt; Stream (Q.ByteStream n) n b
--   </pre>
nulls :: Monad m => ByteStream m r -> m (Sum (ByteStream m) (ByteStream m) r)

-- | Similar to <a>null</a>, but yields the remainder of the
--   <a>ByteStream</a> stream when an answer has been determined.
testNull :: Monad m => ByteStream m r -> m (Of Bool (ByteStream m r))

-- | Returns the number of times its argument appears in the
--   <a>ByteStream</a>. Suitable for use with <a>mapped</a>:
--   
--   <pre>
--   S.mapped (Q.count 37) :: Stream (Q.ByteStream m) m r -&gt; Stream (Of Int) m r
--   </pre>
count :: Monad m => Word8 -> ByteStream m r -> m (Of Int r)

-- | Returns the number of times its argument appears in the
--   <a>ByteStream</a>.
--   
--   <pre>
--   count = length . elemIndices
--   </pre>
count_ :: Monad m => Word8 -> ByteStream m r -> m Int

-- | Equivalent to <tt>hGetContents stdin</tt>. Will read <i>lazily</i>.
getContents :: MonadIO m => ByteStream m ()

-- | Pipes-style nomenclature for <a>getContents</a>.
stdin :: MonadIO m => ByteStream m ()

-- | Pipes-style nomenclature for <tt>putStr</tt>.
stdout :: MonadIO m => ByteStream m r -> m r

-- | A synonym for <tt>hPut</tt>, for compatibility
--   
--   hPutStr :: Handle -&gt; ByteStream IO r -&gt; IO r hPutStr = hPut
--   
--   <ul>
--   <li>- | Write a ByteStream to stdout putStr :: ByteStream IO r -&gt;
--   IO r putStr = hPut IO.stdout</li>
--   </ul>
--   
--   The interact function takes a function of type <tt>ByteStream -&gt;
--   ByteStream</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.
--   
--   <pre>
--   interact morph = stdout (morph stdin)
--   </pre>
interact :: (ByteStream IO () -> ByteStream IO r) -> IO r

-- | Read an entire file into a chunked <tt><a>ByteStream</a> IO ()</tt>.
--   The handle will be held open until EOF is encountered. The block
--   governed by <a>runResourceT</a> will end with the closing of any
--   handles opened.
--   
--   <pre>
--   &gt;&gt;&gt; :! cat hello.txt
--   Hello world.
--   Goodbye world.
--   
--   &gt;&gt;&gt; runResourceT $ Q.stdout $ Q.readFile "hello.txt"
--   Hello world.
--   Goodbye world.
--   </pre>
readFile :: MonadResource m => FilePath -> ByteStream m ()

-- | Write a <a>ByteStream</a> to a file. Use <a>runResourceT</a> to ensure
--   that the handle is closed.
--   
--   <pre>
--   &gt;&gt;&gt; :set -XOverloadedStrings
--   
--   &gt;&gt;&gt; runResourceT $ Q.writeFile "hello.txt" "Hello world.\nGoodbye world.\n"
--   
--   &gt;&gt;&gt; :! cat "hello.txt"
--   Hello world.
--   Goodbye world.
--   
--   &gt;&gt;&gt; runResourceT $ Q.writeFile "hello2.txt" $ Q.readFile "hello.txt"
--   
--   &gt;&gt;&gt; :! cat hello2.txt
--   Hello world.
--   Goodbye world.
--   </pre>
writeFile :: MonadResource m => FilePath -> ByteStream m r -> m r

-- | Append a <a>ByteStream</a> to a file. Use <a>runResourceT</a> to
--   ensure that the handle is closed.
--   
--   <pre>
--   &gt;&gt;&gt; runResourceT $ Q.writeFile "hello.txt" "Hello world.\nGoodbye world.\n"
--   
--   &gt;&gt;&gt; runResourceT $ Q.stdout $ Q.readFile "hello.txt"
--   Hello world.
--   Goodbye world.
--   
--   &gt;&gt;&gt; runResourceT $ Q.appendFile "hello.txt" "sincerely yours,\nArthur\n"
--   
--   &gt;&gt;&gt; runResourceT $ Q.stdout $  Q.readFile "hello.txt"
--   Hello world.
--   Goodbye world.
--   sincerely yours,
--   Arthur
--   </pre>
appendFile :: MonadResource m => FilePath -> ByteStream m r -> m r

-- | Pipes-style nomenclature for <a>hGetContents</a>.
fromHandle :: MonadIO m => Handle -> ByteStream m ()

-- | Pipes nomenclature for <a>hPut</a>.
toHandle :: MonadIO m => Handle -> ByteStream m r -> m r

-- | Read <tt>n</tt> bytes into a <a>ByteStream</a>, directly from the
--   specified <a>Handle</a>.
hGet :: MonadIO m => Handle -> Int -> ByteStream m ()

-- | Read entire handle contents <i>lazily</i> into a <a>ByteStream</a>.
--   Chunks are read on demand, using the default chunk size.
--   
--   Note: the <a>Handle</a> should be placed in binary mode with
--   <a>hSetBinaryMode</a> for <a>hGetContents</a> to work correctly.
hGetContents :: MonadIO m => Handle -> ByteStream m ()

-- | Read entire handle contents <i>lazily</i> into a <a>ByteStream</a>.
--   Chunks are read on demand, in at most <tt>k</tt>-sized chunks. It does
--   not block waiting for a whole <tt>k</tt>-sized chunk, so if less than
--   <tt>k</tt> bytes are available then they will be returned immediately
--   as a smaller chunk.
--   
--   Note: the <a>Handle</a> should be placed in binary mode with
--   <a>hSetBinaryMode</a> for <a>hGetContentsN</a> to work correctly.
hGetContentsN :: MonadIO m => Int -> Handle -> ByteStream m ()

-- | Read <tt>n</tt> bytes into a <a>ByteStream</a>, directly from the
--   specified <a>Handle</a>, in chunks of size <tt>k</tt>.
hGetN :: MonadIO m => Int -> Handle -> Int -> ByteStream m ()

-- | 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 :: MonadIO m => Handle -> Int -> ByteStream m ()

-- | hGetNonBlockingN is similar to <a>hGetContentsN</a>, except that it
--   will never block waiting for data to become available, instead it
--   returns only whatever data is available. Chunks are read on demand, in
--   <tt>k</tt>-sized chunks.
hGetNonBlockingN :: MonadIO m => Int -> Handle -> Int -> ByteStream m ()

-- | Outputs a <a>ByteStream</a> to the specified <a>Handle</a>.
hPut :: MonadIO m => Handle -> ByteStream m r -> m r

-- | Like <a>uncons</a>, but yields the entire first <a>ByteString</a>
--   chunk that the stream is holding onto. If there wasn't one, it tries
--   to fetch it. Yields the final <tt>r</tt> return value when the
--   <a>ByteStream</a> is empty.
unconsChunk :: Monad m => ByteStream m r -> m (Either r (ByteString, ByteStream m r))

-- | The same as <a>unconsChunk</a>, will be removed in the next version.

-- | <i>Deprecated: Use unconsChunk instead.</i>
nextChunk :: Monad m => ByteStream m r -> m (Either r (ByteString, ByteStream m r))

-- | Yield-style smart constructor for <a>Chunk</a>.
chunk :: ByteString -> ByteStream m ()

-- | Consume the chunks of an effectful <a>ByteString</a> with a natural
--   right fold.
foldrChunks :: Monad m => (ByteString -> a -> a) -> a -> ByteStream m r -> m a

-- | Consume the chunks of an effectful <a>ByteString</a> with a left fold.
--   Suitable for use with <a>mapped</a>.
foldlChunks :: Monad m => (a -> ByteString -> a) -> a -> ByteStream m r -> m (Of a r)

-- | <tt>chunkFold</tt> is preferable to <tt>foldlChunks</tt> since it is
--   an appropriate argument for <tt>Control.Foldl.purely</tt> which
--   permits many folds and sinks to be run simultaneously on one
--   bytestream.
chunkFold :: Monad m => (x -> ByteString -> x) -> x -> (x -> a) -> ByteStream m r -> m (Of a r)

-- | <a>chunkFoldM</a> is preferable to <a>foldlChunksM</a> since it is an
--   appropriate argument for <a>impurely</a> which permits many folds and
--   sinks to be run simultaneously on one bytestream.
chunkFoldM :: Monad m => (x -> ByteString -> m x) -> m x -> (x -> m a) -> ByteStream m r -> m (Of a r)

-- | Instead of mapping over each <a>Word8</a> or <a>Char</a>, map over
--   each strict <a>ByteString</a> chunk in the stream.
chunkMap :: Monad m => (ByteString -> ByteString) -> ByteStream m r -> ByteStream m r

-- | Like <a>chunkMap</a>, but map effectfully.
chunkMapM :: Monad m => (ByteString -> m ByteString) -> ByteStream m r -> ByteStream m r

-- | Like <a>chunkMapM</a>, but discard the result of each effectful
--   mapping.
chunkMapM_ :: Monad m => (ByteString -> m x) -> ByteStream m r -> m r

-- | Resolve a succession of chunks into its Church encoding; this is not a
--   safe operation; it is equivalent to exposing the constructors
dematerialize :: Monad m => ByteStream m r -> forall x. (r -> x) -> (ByteString -> x -> x) -> (m x -> x) -> x

-- | Construct a succession of chunks from its Church encoding (compare
--   <tt>GHC.Exts.build</tt>)
materialize :: (forall x. (r -> x) -> (ByteString -> x -> x) -> (m x -> x) -> x) -> ByteStream m r

-- | Given a byte stream on a transformed monad, make it possible to 'run'
--   transformer.
distribute :: (Monad m, MonadTrans t, MFunctor t, Monad (t m), Monad (t (ByteStream m))) => ByteStream (t m) a -> t (ByteStream m) a

-- | Zip a list and a stream-of-byte-streams together.
zipWithStream :: Monad m => (forall x. a -> ByteStream m x -> ByteStream m x) -> [a] -> Stream (ByteStream m) m r -> Stream (ByteStream m) m r


-- | This library emulates <a>Data.ByteString.Lazy.Char8</a> but includes a
--   monadic element and thus at certain points uses a
--   <a>Stream</a>/<tt>FreeT</tt> type in place of lists. See the
--   documentation for <a>Streaming.ByteString</a> and the examples of of
--   use to implement simple shell operations <a>here</a>. Examples of use
--   with <tt>http-client</tt>, <tt>attoparsec</tt>, <tt>aeson</tt>,
--   <tt>zlib</tt> etc. can be found in the 'streaming-utils' library.
module Streaming.ByteString.Char8

-- | A space-efficient representation of a succession of <a>Word8</a>
--   vectors, supporting many efficient operations.
--   
--   An effectful <a>ByteStream</a> contains 8-bit bytes, or by using the
--   operations from <a>Streaming.ByteString.Char8</a> it can be
--   interpreted as containing 8-bit characters.
data ByteStream m r

-- | A type alias for back-compatibility.

-- | <i>Deprecated: Use ByteStream instead.</i>
type ByteString = ByteStream

-- | <i>O(1)</i> The empty <a>ByteStream</a> -- i.e. <tt>return ()</tt>
--   Note that <tt>ByteStream m w</tt> is generally a monoid for monoidal
--   values of <tt>w</tt>, like <tt>()</tt>.
empty :: ByteStream m ()

-- | <i>O(n)</i> Convert a stream of separate characters into a packed byte
--   stream.
pack :: Monad m => Stream (Of Char) m r -> ByteStream m r

-- | Given a stream of bytes, produce a vanilla <a>Stream</a> of
--   characters.
unpack :: Monad m => ByteStream m r -> Stream (Of Char) m r

-- | Promote a vanilla <a>String</a> into a stream.
--   
--   <i>Note:</i> Each <a>Char</a> is truncated to 8 bits.
string :: String -> ByteStream m ()

-- | The <a>unlines</a> function restores line breaks between layers.
--   
--   Note that this is not a perfect inverse of <a>lines</a>:
--   
--   <ul>
--   <li><tt><a>lines</a> . <a>unlines</a></tt> can produce more strings
--   than there were if some of the "lines" had embedded newlines.</li>
--   <li><tt><a>unlines</a> . <a>lines</a></tt> will replace <tt>\r\n</tt>
--   with <tt>\n</tt>.</li>
--   </ul>
unlines :: Monad m => Stream (ByteStream m) m r -> ByteStream m r

-- | The <a>unwords</a> function is analogous to the <a>unlines</a>
--   function, on words.
unwords :: Monad m => Stream (ByteStream m) m r -> ByteStream m r

-- | <i>O(1)</i> Yield a <a>Char</a> as a minimal <a>ByteStream</a>
singleton :: Monad m => Char -> ByteStream m ()

-- | <i>O(c)</i> Convert a monadic stream of individual strict
--   <a>ByteString</a> chunks into a byte stream.
fromChunks :: Monad m => Stream (Of ByteString) m r -> ByteStream m r

-- | <i>O(c)</i> Transmute a pseudo-pure lazy bytestring to its
--   representation as a monadic stream of chunks.
--   
--   <pre>
--   &gt;&gt;&gt; Q.putStrLn $ Q.fromLazy "hi"
--   hi
--   
--   &gt;&gt;&gt; Q.fromLazy "hi"
--   Chunk "hi" (Empty (()))  -- note: a 'show' instance works in the identity monad
--   
--   &gt;&gt;&gt; Q.fromLazy $ BL.fromChunks ["here", "are", "some", "chunks"]
--   Chunk "here" (Chunk "are" (Chunk "some" (Chunk "chunks" (Empty (())))))
--   </pre>
fromLazy :: Monad m => ByteString -> ByteStream m ()

-- | <i>O(1)</i> Yield a strict <a>ByteString</a> chunk.
fromStrict :: ByteString -> ByteStream m ()

-- | <i>O(c)</i> Convert a byte stream into a stream of individual strict
--   bytestrings. This of course exposes the internal chunk structure.
toChunks :: Monad m => ByteStream m r -> Stream (Of ByteString) m r

-- | <i>O(n)</i> Convert an effectful byte stream into a single lazy
--   <a>ByteString</a> with the same internal chunk structure, retaining
--   the original return value.
--   
--   This is the canonical way of breaking streaming (<a>toStrict</a> and
--   the like are far more demonic). Essentially one is dividing the
--   interleaved layers of effects and bytes into one immense layer of
--   effects, followed by the memory of the succession of bytes.
--   
--   Because one preserves the return value, <a>toLazy</a> is a suitable
--   argument for <a>mapped</a>:
--   
--   <pre>
--   S.mapped Q.toLazy :: Stream (ByteStream m) m r -&gt; Stream (Of L.ByteString) m r
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Q.toLazy "hello"
--   "hello" :&gt; ()
--   
--   &gt;&gt;&gt; S.toListM $ traverses Q.toLazy $ Q.lines "one\ntwo\nthree\nfour\nfive\n"
--   ["one","two","three","four","five",""]  -- [L.ByteString]
--   </pre>
toLazy :: Monad m => ByteStream m r -> m (Of ByteString r)

-- | <i>O(n)</i> Convert an effectful byte stream into a single lazy
--   <a>ByteStream</a> with the same internal chunk structure. See
--   <a>toLazy</a> which preserve connectedness by keeping the return value
--   of the effectful bytestring.
toLazy_ :: Monad m => ByteStream m r -> m ByteString

-- | <i>O(n)</i> Convert a monadic byte stream into a single strict
--   <a>ByteString</a>, retaining the return value of the original pair.
--   This operation is for use with <a>mapped</a>.
--   
--   <pre>
--   mapped R.toStrict :: Monad m =&gt; Stream (ByteStream m) m r -&gt; Stream (Of ByteString) m r
--   </pre>
--   
--   It is subject to all the objections one makes to Data.ByteString.Lazy
--   <a>toStrict</a>; all of these are devastating.
toStrict :: Monad m => ByteStream m r -> m (Of ByteString r)

-- | <i>O(n)</i> Convert a byte stream into a single strict
--   <a>ByteString</a>.
--   
--   Note that this is an <i>expensive</i> operation that forces the whole
--   monadic ByteString into memory and then copies all the data. If
--   possible, try to avoid converting back and forth between streaming and
--   strict bytestrings.
toStrict_ :: Monad m => ByteStream m r -> m ByteString

-- | Perform the effects contained in an effectful bytestring, ignoring the
--   bytes.
effects :: Monad m => ByteStream m r -> m r

-- | Make the information in a bytestring available to more than one
--   eliminating fold, e.g.
--   
--   <pre>
--   &gt;&gt;&gt; Q.count 'l' $ Q.count 'o' $ Q.copy $ "hello\nworld"
--   3 :&gt; (2 :&gt; ())
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Q.length $ Q.count 'l' $ Q.count 'o' $ Q.copy $ Q.copy "hello\nworld"
--   11 :&gt; (3 :&gt; (2 :&gt; ()))
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; runResourceT $ Q.writeFile "hello2.txt" $ Q.writeFile "hello1.txt" $ Q.copy $ "hello\nworld\n"
--   
--   &gt;&gt;&gt; :! cat hello2.txt
--   hello
--   world
--   
--   &gt;&gt;&gt; :! cat hello1.txt
--   hello
--   world
--   </pre>
--   
--   This sort of manipulation could as well be acheived by combining folds
--   - using <tt>Control.Foldl</tt> for example. But any sort of
--   manipulation can be involved in the fold. Here are a couple of trivial
--   complications involving splitting by lines:
--   
--   <pre>
--   &gt;&gt;&gt; let doubleLines = Q.unlines . maps (&lt;* Q.chunk "\n" ) . Q.lines
--   
--   &gt;&gt;&gt; let emphasize = Q.unlines . maps (&lt;* Q.chunk "!" ) . Q.lines
--   
--   &gt;&gt;&gt; runResourceT $ Q.writeFile "hello2.txt" $ emphasize $ Q.writeFile "hello1.txt" $ doubleLines $ Q.copy $ "hello\nworld"
--   
--   &gt;&gt;&gt; :! cat hello2.txt
--   hello!
--   world!
--   
--   &gt;&gt;&gt; :! cat hello1.txt
--   hello
--   
--   world
--   </pre>
--   
--   As with the parallel operations in <tt>Streaming.Prelude</tt>, we have
--   
--   <pre>
--   Q.effects . Q.copy       = id
--   hoist Q.effects . Q.copy = id
--   </pre>
--   
--   The duplication does not by itself involve the copying of bytestring
--   chunks; it just makes two references to each chunk as it arises. This
--   does, however double the number of constructors associated with each
--   chunk.
copy :: Monad m => ByteStream m r -> ByteStream (ByteStream m) r

-- | Perform the effects contained in the second in an effectful pair of
--   bytestrings, ignoring the bytes. It would typically be used at the
--   type
--   
--   <pre>
--   ByteStream m (ByteStream m r) -&gt; ByteStream m r
--   </pre>
drained :: (Monad m, MonadTrans t, Monad (t m)) => t m (ByteStream m r) -> t m r

-- | Reconceive an effect that results in an effectful bytestring as an
--   effectful bytestring. Compare Streaming.mwrap. The closest equivalent
--   of
--   
--   <pre>
--   &gt;&gt;&gt; Streaming.wrap :: f (Stream f m r) -&gt; Stream f m r
--   </pre>
--   
--   is here <tt>consChunk</tt>. <tt>mwrap</tt> is the smart constructor
--   for the internal <tt>Go</tt> constructor.
mwrap :: m (ByteStream m r) -> ByteStream m r

-- | <i>O(n)</i> <a>map</a> <tt>f xs</tt> is the ByteStream obtained by
--   applying <tt>f</tt> to each element of <tt>xs</tt>.
map :: Monad m => (Char -> Char) -> ByteStream m r -> ByteStream m r

-- | <i>O(n)</i> The <a>intercalate</a> function takes a <a>ByteStream</a>
--   and a list of <a>ByteStream</a>s and concatenates the list after
--   interspersing the first argument between each element of the list.
intercalate :: Monad m => ByteStream m () -> Stream (ByteStream m) m r -> ByteStream m r

-- | The <a>intersperse</a> function takes a <a>Char</a> and a
--   <a>ByteStream</a> and `intersperses' that byte between the elements of
--   the <a>ByteStream</a>. It is analogous to the intersperse function on
--   Streams.
intersperse :: Monad m => Char -> ByteStream m r -> ByteStream m r

-- | <i>O(1)</i> Cons a <a>Char</a> onto a byte stream.
cons :: Monad m => Char -> ByteStream m r -> ByteStream m r

-- | <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 ByteStreams.
cons' :: Char -> ByteStream m r -> ByteStream m r

-- | <i>O(n/c)</i> Append a byte to the end of a <a>ByteStream</a>
snoc :: Monad m => ByteStream m r -> Char -> ByteStream m r

-- | <i>O(n/c)</i> Append two <a>ByteString</a>s together.
append :: Monad m => ByteStream m r -> ByteStream m s -> ByteStream m s

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

-- | <i>O(1)</i> Extract the first element of a ByteStream, if possible.
--   Suitable for use with <a>mapped</a>:
--   
--   <pre>
--   S.mapped Q.head :: Stream (Q.ByteStream m) m r -&gt; Stream (Of (Maybe Char)) m r
--   </pre>
head :: Monad m => ByteStream m r -> m (Of (Maybe Char) r)

-- | <i>O(1)</i> Extract the first element of a ByteStream, which must be
--   non-empty.
head_ :: Monad m => ByteStream m r -> m Char

-- | Extract the last element of a <a>ByteStream</a>, if possible. Suitable
--   for use with <a>mapped</a>:
--   
--   <pre>
--   S.mapped Q.last :: Streaming (ByteStream m) m r -&gt; Stream (Of (Maybe Char)) m r
--   </pre>
last :: Monad m => ByteStream m r -> m (Of (Maybe Char) r)

-- | <i>O(n/c)</i> Extract the last element of a ByteStream, which must be
--   finite and non-empty.
last_ :: Monad m => ByteStream m r -> m Char

-- | Test whether a <a>ByteStream</a> is empty, collecting its return
--   value; to reach the return value, this operation must check the whole
--   length of the string.
--   
--   <pre>
--   &gt;&gt;&gt; Q.null "one\ntwo\three\nfour\nfive\n"
--   False :&gt; ()
--   
--   &gt;&gt;&gt; Q.null ""
--   True :&gt; ()
--   
--   &gt;&gt;&gt; S.print $ mapped R.null $ Q.lines "yours,\nMeredith"
--   False
--   False
--   </pre>
--   
--   Suitable for use with <a>mapped</a>:
--   
--   <pre>
--   S.mapped Q.null :: Streaming (ByteStream m) m r -&gt; Stream (Of Bool) m r
--   </pre>
null :: Monad m => ByteStream m r -> m (Of Bool r)

-- | <i>O(1)</i> Test whether a <a>ByteStream</a> is empty. The value is of
--   course in the monad of the effects.
--   
--   <pre>
--   &gt;&gt;&gt; Q.null "one\ntwo\three\nfour\nfive\n"
--   False
--   
--   &gt;&gt;&gt; Q.null $ Q.take 0 Q.stdin
--   True
--   
--   &gt;&gt;&gt; :t Q.null $ Q.take 0 Q.stdin
--   Q.null $ Q.take 0 Q.stdin :: MonadIO m =&gt; m Bool
--   </pre>
null_ :: Monad m => ByteStream m r -> m Bool

-- | <i>O1</i> Distinguish empty from non-empty lines, while maintaining
--   streaming; the empty ByteStrings are on the right
--   
--   <pre>
--   &gt;&gt;&gt; nulls  ::  ByteStream m r -&gt; m (Sum (ByteStream m) (ByteStream m) r)
--   </pre>
--   
--   There are many (generally slower) ways to remove null bytestrings from
--   a <tt>Stream (ByteStream m) m r</tt> (besides using <tt>denull</tt>).
--   If we pass next to
--   
--   <pre>
--   &gt;&gt;&gt; mapped nulls bs :: Stream (Sum (ByteStream m) (ByteStream m)) m r
--   </pre>
--   
--   then can then apply <tt>Streaming.separate</tt> to get
--   
--   <pre>
--   &gt;&gt;&gt; separate (mapped nulls bs) :: Stream (ByteStream m) (Stream (ByteStream m) m) r
--   </pre>
--   
--   The inner monad is now made of the empty bytestrings; we act on this
--   with <tt>hoist</tt> , considering that
--   
--   <pre>
--   &gt;&gt;&gt; :t Q.effects . Q.concat
--   Q.effects . Q.concat
--     :: Monad m =&gt; Stream (Q.ByteStream m) m r -&gt; m r
--   </pre>
--   
--   we have
--   
--   <pre>
--   &gt;&gt;&gt; hoist (Q.effects . Q.concat) . separate . mapped Q.nulls
--     :: Monad n =&gt;  Stream (Q.ByteStream n) n b -&gt; Stream (Q.ByteStream n) n b
--   </pre>
nulls :: Monad m => ByteStream m r -> m (Sum (ByteStream m) (ByteStream m) r)

-- | Similar to <a>null</a>, but yields the remainder of the
--   <a>ByteStream</a> stream when an answer has been determined.
testNull :: Monad m => ByteStream m r -> m (Of Bool (ByteStream m r))

-- | <i>O(1)</i> Extract the head and tail of a <a>ByteStream</a>, or its
--   return value if it is empty. This is the 'natural' uncons for an
--   effectful byte stream.
uncons :: Monad m => ByteStream m r -> m (Either r (Char, ByteStream m r))

-- | The same as <a>uncons</a>, will be removed in the next version.

-- | <i>Deprecated: Use uncons instead.</i>
nextChar :: Monad m => ByteStream m r -> m (Either r (Char, ByteStream m r))

-- | Try to position the stream at the next non-whitespace input, by
--   skipping leading whitespace. Only a <i>reasonable</i> quantity of
--   whitespace will be skipped before giving up and returning the rest of
--   the stream with any remaining whitespace. Limiting the amount of
--   whitespace consumed is a safety mechanism to avoid looping forever on
--   a never-ending stream of whitespace from an untrusted source. For
--   unconditional dropping of all leading whitespace, use <a>dropWhile</a>
--   with a suitable predicate.
skipSomeWS :: Monad m => ByteStream m r -> ByteStream m r

-- | <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (<a>not</a> .
--   p)</tt>.
break :: Monad m => (Char -> Bool) -> ByteStream m r -> ByteStream m (ByteStream m r)

-- | <i>O(n/c)</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>.
--   
--   <pre>
--   &gt;&gt;&gt; Q.putStrLn $ Q.drop 6 "Wisconsin"
--   sin
--   
--   &gt;&gt;&gt; Q.putStrLn $ Q.drop 16 "Wisconsin"
--   </pre>
drop :: Monad m => Int64 -> ByteStream m r -> ByteStream m r

-- | <a>dropWhile</a> <tt>p xs</tt> returns the suffix remaining after
--   <a>takeWhile</a> <tt>p xs</tt>.
dropWhile :: Monad m => (Char -> Bool) -> ByteStream m r -> ByteStream m r

-- | The <a>group</a> function takes a ByteStream and returns a list of
--   ByteStreams 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 :: Monad m => ByteStream m r -> Stream (ByteStream m) m r

-- | The <a>groupBy</a> function is a generalized version of <a>group</a>.
groupBy :: Monad m => (Char -> Char -> Bool) -> ByteStream m r -> Stream (ByteStream m) m r

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

-- | <i>O(n/c)</i> <a>splitAt</a> <tt>n xs</tt> is equivalent to
--   <tt>(<a>take</a> n xs, <a>drop</a> n xs)</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; rest &lt;- Q.putStrLn $ Q.splitAt 3 "therapist is a danger to good hyphenation, as Knuth notes"
--   the
--   
--   &gt;&gt;&gt; Q.putStrLn $ Q.splitAt 19 rest
--   rapist is a danger
--   </pre>
splitAt :: Monad m => Int64 -> ByteStream m r -> ByteStream m (ByteStream m r)

-- | Like <a>split</a>, but you can supply your own splitting predicate.
splitWith :: Monad m => (Char -> Bool) -> ByteStream m r -> Stream (ByteStream m) m r

-- | <i>O(n/c)</i> <a>take</a> <tt>n</tt>, applied to a ByteStream
--   <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>.
--   
--   Note that in the streaming context this drops the final return value;
--   <a>splitAt</a> preserves this information, and is sometimes to be
--   preferred.
--   
--   <pre>
--   &gt;&gt;&gt; Q.putStrLn $ Q.take 8 $ "Is there a God?" &gt;&gt; return True
--   Is there
--   
--   &gt;&gt;&gt; Q.putStrLn $ "Is there a God?" &gt;&gt; return True
--   Is there a God?
--   True
--   
--   &gt;&gt;&gt; rest &lt;- Q.putStrLn $ Q.splitAt 8 $ "Is there a God?" &gt;&gt; return True
--   Is there
--   
--   &gt;&gt;&gt; Q.effects  rest
--   True
--   </pre>
take :: Monad m => Int64 -> ByteStream m r -> ByteStream m ()

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

-- | <i>O(n)</i> Break a <a>ByteStream</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 <a>ByteStream</a>s that
--   are slices of the original.
--   
--   <pre>
--   &gt;&gt;&gt; Q.stdout $ Q.unlines $ Q.split 'n' "banana peel"
--   ba
--   a
--   a peel
--   </pre>
split :: Monad m => Char -> ByteStream m r -> Stream (ByteStream m) m r

-- | <a>lines</a> turns a ByteStream into a connected stream of ByteStreams
--   at divide at newline characters. The resulting strings do not contain
--   newlines. This is the genuinely streaming <a>lines</a> which only
--   breaks chunks, and thus never increases the use of memory.
--   
--   Because <a>ByteStream</a>s are usually read in binary mode, with no
--   line ending conversion, this function recognizes both <tt>\n</tt> and
--   <tt>\r\n</tt> endings (regardless of the current platform).
lines :: forall m r. Monad m => ByteStream m r -> Stream (ByteStream m) m r

-- | <a>lineSplit</a> turns a ByteStream into a connected stream of
--   ByteStreams at divide after a fixed number of newline characters.
--   Unlike most of the string splitting functions in this library, this
--   function preserves newlines characters.
--   
--   Like <a>lines</a>, this function properly handles both <tt>\n</tt> and
--   <tt>\r\n</tt> endings regardless of the current platform. It does not
--   support <tt>\r</tt> or <tt>\n\r</tt> line endings.
--   
--   <pre>
--   &gt;&gt;&gt; let planets = ["Mercury","Venus","Earth","Mars","Saturn","Jupiter","Neptune","Uranus"]
--   
--   &gt;&gt;&gt; S.mapsM_ (\x -&gt; putStrLn "Chunk" &gt;&gt; Q.putStrLn x) $ Q.lineSplit 3 $ Q.string $ L.unlines planets
--   Chunk
--   Mercury
--   Venus
--   Earth
--   </pre>
--   
--   Chunk Mars Saturn Jupiter
--   
--   Chunk Neptune Uranus
--   
--   Since all characters originally present in the stream are preserved,
--   this function satisfies the following law:
--   
--   <pre>
--   Ɐ n bs. concat (lineSplit n bs) ≅ bs
--   </pre>
lineSplit :: forall m r. Monad m => Int -> ByteStream m r -> Stream (ByteStream m) m r

-- | <a>words</a> breaks a byte stream up into a succession of byte streams
--   corresponding to words, breaking on <a>Char</a>s representing white
--   space. This is the genuinely streaming <a>words</a>. A function that
--   returns individual strict bytestrings would concatenate even
--   infinitely long words like <tt>cycle "y"</tt> in memory. When the
--   stream is known to not contain unreasonably long words, you can write
--   <tt>mapped toStrict . words</tt> or the like, if strict bytestrings
--   are needed.
words :: Monad m => ByteStream m r -> Stream (ByteStream m) m r

-- | <i>O(n)</i> Concatenate a stream of byte streams.
concat :: Monad m => Stream (ByteStream m) m r -> ByteStream m r

-- | Remove empty ByteStrings from a stream of bytestrings.
denull :: Monad m => Stream (ByteStream m) m r -> Stream (ByteStream m) m r

-- | Take a builder constructed otherwise and convert it to a genuine
--   streaming bytestring.
--   
--   <pre>
--   &gt;&gt;&gt; Q.putStrLn $ Q.toStreamingByteString $ stringUtf8 "哈斯克尔" &lt;&gt; stringUtf8 " " &lt;&gt; integerDec 98
--   哈斯克尔 98
--   </pre>
--   
--   <a>This benchmark</a> shows its performance is indistinguishable from
--   <tt>toLazyByteString</tt>
toStreamingByteString :: MonadIO m => Builder -> ByteStream m ()

-- | Take a builder and convert it to a genuine streaming bytestring, using
--   a specific allocation strategy.
toStreamingByteStringWith :: MonadIO m => AllocationStrategy -> Builder -> ByteStream m ()

-- | A simple construction of a builder from a <a>ByteString</a>.
--   
--   <pre>
--   &gt;&gt;&gt; let aaa = "10000 is a number\n" :: Q.ByteString IO ()
--   
--   &gt;&gt;&gt; hPutBuilder  IO.stdout $ toBuilder  aaa
--   10000 is a number
--   </pre>
toBuilder :: ByteStream IO () -> Builder

-- | Concatenate a stream of builders (not a streaming bytestring!) into a
--   single builder.
--   
--   <pre>
--   &gt;&gt;&gt; let aa = yield (integerDec 10000) &gt;&gt; yield (string8 " is a number.") &gt;&gt; yield (char8 '\n')
--   
--   &gt;&gt;&gt; hPutBuilder IO.stdout $ concatBuilders aa
--   10000 is a number.
--   </pre>
concatBuilders :: Stream (Of Builder) IO () -> Builder

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

-- | <tt><a>iterate</a> f x</tt> returns an infinite ByteStream 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 -> ByteStream m r

-- | <a>cycle</a> ties a finite ByteStream into a circular one, or
--   equivalently, the infinite repetition of the original ByteStream. For
--   an empty bytestring (like <tt>return 17</tt>) it of course makes an
--   unproductive loop
--   
--   <pre>
--   &gt;&gt;&gt; Q.putStrLn $ Q.take 7 $ Q.cycle  "y\n"
--   y
--   y
--   y
--   y
--   </pre>
cycle :: Monad m => ByteStream m r -> ByteStream m s

-- | Given some pure process that produces characters, generate a stream of
--   bytes. The <tt>r</tt> produced by the final <a>Left</a> will be the
--   return value at the end of the stream. Note also that the <a>Char</a>
--   values will be truncated to 8-bits.
unfoldr :: (a -> Either r (Char, a)) -> a -> ByteStream m r

-- | <a>cycle</a> ties a finite ByteStream into a circular one, or
--   equivalently, the infinite repetition of the original ByteStream.
--   
--   | <i>O(n)</i> The <a>unfoldM</a> function is analogous to the Stream
--   'unfoldr'. <a>unfoldM</a> builds a ByteStream from a seed value. The
--   function takes the element and returns <a>Nothing</a> if it is done
--   producing the ByteStream or returns <a>Just</a> <tt>(a,b)</tt>, in
--   which case, <tt>a</tt> is a prepending to the ByteStream and
--   <tt>b</tt> is used as the next element in a recursive call.
unfoldM :: Monad m => (a -> Maybe (Char, a)) -> a -> ByteStream m ()

-- | Stream chunks from something that contains <tt>m (Maybe
--   ByteString)</tt> until it returns <a>Nothing</a>. <a>reread</a> is of
--   particular use rendering <tt>io-streams</tt> input streams as byte
--   streams in the present sense.
--   
--   <pre>
--   import qualified Data.ByteString as B
--   import qualified System.IO.Streams as S
--   Q.reread S.read            :: S.InputStream B.ByteString -&gt; Q.ByteStream IO ()
--   Q.reread (liftIO . S.read) :: MonadIO m =&gt; S.InputStream B.ByteString -&gt; Q.ByteStream m ()
--   </pre>
--   
--   The other direction here is
--   
--   <pre>
--   S.unfoldM Q.unconsChunk    :: Q.ByteString IO r -&gt; IO (S.InputStream B.ByteString)
--   </pre>
reread :: Monad m => (s -> m (Maybe ByteString)) -> s -> ByteStream m ()

-- | Like <a>fold_</a>, but suitable for use with <a>mapped</a>.
fold :: Monad m => (x -> Char -> x) -> x -> (x -> b) -> ByteStream m r -> m (Of b r)

-- | <a>fold_</a> keeps the return value of the left-folded bytestring.
--   Useful for simultaneous folds over a segmented bytestream.
fold_ :: Monad m => (x -> Char -> x) -> x -> (x -> b) -> ByteStream m () -> m b

-- | <i>O(n/c)</i> <a>length</a> returns the length of a byte stream as an
--   <a>Int</a> together with the return value. This makes various maps
--   possible.
--   
--   <pre>
--   &gt;&gt;&gt; Q.length "one\ntwo\three\nfour\nfive\n"
--   23 :&gt; ()
--   
--   &gt;&gt;&gt; S.print $ S.take 3 $ mapped Q.length $ Q.lines "one\ntwo\three\nfour\nfive\n"
--   3
--   8
--   4
--   </pre>
length :: Monad m => ByteStream m r -> m (Of Int r)

-- | Like <a>length</a>, report the length in bytes of the
--   <a>ByteStream</a> by running through its contents. Since the return
--   value is in the effect <tt>m</tt>, this is one way to "get out" of the
--   stream.
length_ :: Monad m => ByteStream m r -> m Int

-- | Returns the number of times its argument appears in the
--   <a>ByteStream</a>. Suitable for use with <a>mapped</a>:
--   
--   <pre>
--   S.mapped (Q.count 'a') :: Stream (Q.ByteStream m) m r -&gt; Stream (Of Int) m r
--   </pre>
count :: Monad m => Char -> ByteStream m r -> m (Of Int r)

-- | Returns the number of times its argument appears in the
--   <a>ByteStream</a>.
count_ :: Monad m => Char -> ByteStream m r -> m Int

-- | Try to read an <a>Int</a> value from the <a>ByteString</a>, returning
--   <tt>m (Compose (Just val :&gt; str))</tt> on success, where
--   <tt>val</tt> is the value read and <tt>str</tt> is the rest of the
--   input stream. If the stream of digits decodes to a value larger than
--   can be represented by an <a>Int</a>, the returned value will be <tt>m
--   (Compose (Nothing :&gt; str))</tt>, where the content of <tt>str</tt>
--   is the same as the original stream, but some of the monadic effects
--   may already have taken place, so the original stream MUST NOT be used.
--   To read the remaining data, you MUST use the returned <tt>str</tt>.
--   
--   This function will not read an <i>unreasonably</i> long stream of
--   leading zero digits when trying to decode a number. When reading the
--   first non-zero digit would require requesting a new chunk and ~32KB of
--   leading zeros have already been read, the conversion is aborted and
--   <a>Nothing</a> is returned, along with the overly long run of leading
--   zeros (and any initial explicit plus or minus sign).
--   
--   <a>readInt</a> does not ignore leading whitespace, the value must
--   start immediately at the beginning of the input stream. Use
--   <a>skipSomeWS</a> if you want to skip a <i>reasonable</i> quantity of
--   leading whitespace.
--   
--   <h4><b>Example</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; getCompose &lt;$&gt; (readInt . skipSomeWS) stream &gt;&gt;= \case
--   
--   &gt;&gt;&gt; Just n  :&gt; rest -&gt; print n &gt;&gt; gladly rest
--   
--   &gt;&gt;&gt; Nothing :&gt; rest -&gt; sadly rest
--   </pre>
readInt :: Monad m => ByteStream m r -> m (Compose (Of (Maybe Int)) (ByteStream m) r)

-- | Equivalent to <tt>hGetContents stdin</tt>. Will read <i>lazily</i>.
getContents :: MonadIO m => ByteStream m ()

-- | Pipes-style nomenclature for <a>getContents</a>.
stdin :: MonadIO m => ByteStream m ()

-- | Pipes-style nomenclature for <tt>putStr</tt>.
stdout :: MonadIO m => ByteStream m r -> m r

-- | A synonym for <tt>hPut</tt>, for compatibility
--   
--   hPutStr :: Handle -&gt; ByteStream IO r -&gt; IO r hPutStr = hPut
--   
--   <ul>
--   <li>- | Write a ByteStream to stdout putStr :: ByteStream IO r -&gt;
--   IO r putStr = hPut IO.stdout</li>
--   </ul>
--   
--   The interact function takes a function of type <tt>ByteStream -&gt;
--   ByteStream</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.
--   
--   <pre>
--   interact morph = stdout (morph stdin)
--   </pre>
interact :: (ByteStream IO () -> ByteStream IO r) -> IO r

-- | Print a stream of bytes to STDOUT.
putStr :: MonadIO m => ByteStream m r -> m r

-- | Print a stream of bytes to STDOUT, ending with a final <tt>n</tt>.
--   
--   <i>Note:</i> The final <tt>n</tt> is not added atomically, and in
--   certain multi-threaded scenarios might not appear where expected.
putStrLn :: MonadIO m => ByteStream m r -> m r

-- | Read an entire file into a chunked <tt><a>ByteStream</a> IO ()</tt>.
--   The handle will be held open until EOF is encountered. The block
--   governed by <a>runResourceT</a> will end with the closing of any
--   handles opened.
--   
--   <pre>
--   &gt;&gt;&gt; :! cat hello.txt
--   Hello world.
--   Goodbye world.
--   
--   &gt;&gt;&gt; runResourceT $ Q.stdout $ Q.readFile "hello.txt"
--   Hello world.
--   Goodbye world.
--   </pre>
readFile :: MonadResource m => FilePath -> ByteStream m ()

-- | Write a <a>ByteStream</a> to a file. Use <a>runResourceT</a> to ensure
--   that the handle is closed.
--   
--   <pre>
--   &gt;&gt;&gt; :set -XOverloadedStrings
--   
--   &gt;&gt;&gt; runResourceT $ Q.writeFile "hello.txt" "Hello world.\nGoodbye world.\n"
--   
--   &gt;&gt;&gt; :! cat "hello.txt"
--   Hello world.
--   Goodbye world.
--   
--   &gt;&gt;&gt; runResourceT $ Q.writeFile "hello2.txt" $ Q.readFile "hello.txt"
--   
--   &gt;&gt;&gt; :! cat hello2.txt
--   Hello world.
--   Goodbye world.
--   </pre>
writeFile :: MonadResource m => FilePath -> ByteStream m r -> m r

-- | Append a <a>ByteStream</a> to a file. Use <a>runResourceT</a> to
--   ensure that the handle is closed.
--   
--   <pre>
--   &gt;&gt;&gt; runResourceT $ Q.writeFile "hello.txt" "Hello world.\nGoodbye world.\n"
--   
--   &gt;&gt;&gt; runResourceT $ Q.stdout $ Q.readFile "hello.txt"
--   Hello world.
--   Goodbye world.
--   
--   &gt;&gt;&gt; runResourceT $ Q.appendFile "hello.txt" "sincerely yours,\nArthur\n"
--   
--   &gt;&gt;&gt; runResourceT $ Q.stdout $  Q.readFile "hello.txt"
--   Hello world.
--   Goodbye world.
--   sincerely yours,
--   Arthur
--   </pre>
appendFile :: MonadResource m => FilePath -> ByteStream m r -> m r

-- | Pipes-style nomenclature for <a>hGetContents</a>.
fromHandle :: MonadIO m => Handle -> ByteStream m ()

-- | Pipes nomenclature for <a>hPut</a>.
toHandle :: MonadIO m => Handle -> ByteStream m r -> m r

-- | Read <tt>n</tt> bytes into a <a>ByteStream</a>, directly from the
--   specified <a>Handle</a>.
hGet :: MonadIO m => Handle -> Int -> ByteStream m ()

-- | Read entire handle contents <i>lazily</i> into a <a>ByteStream</a>.
--   Chunks are read on demand, using the default chunk size.
--   
--   Note: the <a>Handle</a> should be placed in binary mode with
--   <a>hSetBinaryMode</a> for <a>hGetContents</a> to work correctly.
hGetContents :: MonadIO m => Handle -> ByteStream m ()

-- | Read entire handle contents <i>lazily</i> into a <a>ByteStream</a>.
--   Chunks are read on demand, in at most <tt>k</tt>-sized chunks. It does
--   not block waiting for a whole <tt>k</tt>-sized chunk, so if less than
--   <tt>k</tt> bytes are available then they will be returned immediately
--   as a smaller chunk.
--   
--   Note: the <a>Handle</a> should be placed in binary mode with
--   <a>hSetBinaryMode</a> for <a>hGetContentsN</a> to work correctly.
hGetContentsN :: MonadIO m => Int -> Handle -> ByteStream m ()

-- | Read <tt>n</tt> bytes into a <a>ByteStream</a>, directly from the
--   specified <a>Handle</a>, in chunks of size <tt>k</tt>.
hGetN :: MonadIO m => Int -> Handle -> Int -> ByteStream m ()

-- | 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 :: MonadIO m => Handle -> Int -> ByteStream m ()

-- | hGetNonBlockingN is similar to <a>hGetContentsN</a>, except that it
--   will never block waiting for data to become available, instead it
--   returns only whatever data is available. Chunks are read on demand, in
--   <tt>k</tt>-sized chunks.
hGetNonBlockingN :: MonadIO m => Int -> Handle -> Int -> ByteStream m ()

-- | Outputs a <a>ByteStream</a> to the specified <a>Handle</a>.
hPut :: MonadIO m => Handle -> ByteStream m r -> m r

-- | Like <a>uncons</a>, but yields the entire first <a>ByteString</a>
--   chunk that the stream is holding onto. If there wasn't one, it tries
--   to fetch it. Yields the final <tt>r</tt> return value when the
--   <a>ByteStream</a> is empty.
unconsChunk :: Monad m => ByteStream m r -> m (Either r (ByteString, ByteStream m r))

-- | The same as <a>unconsChunk</a>, will be removed in the next version.

-- | <i>Deprecated: Use unconsChunk instead.</i>
nextChunk :: Monad m => ByteStream m r -> m (Either r (ByteString, ByteStream m r))

-- | Yield-style smart constructor for <a>Chunk</a>.
chunk :: ByteString -> ByteStream m ()

-- | Consume the chunks of an effectful <a>ByteString</a> with a natural
--   right fold.
foldrChunks :: Monad m => (ByteString -> a -> a) -> a -> ByteStream m r -> m a

-- | Consume the chunks of an effectful <a>ByteString</a> with a left fold.
--   Suitable for use with <a>mapped</a>.
foldlChunks :: Monad m => (a -> ByteString -> a) -> a -> ByteStream m r -> m (Of a r)

-- | <tt>chunkFold</tt> is preferable to <tt>foldlChunks</tt> since it is
--   an appropriate argument for <tt>Control.Foldl.purely</tt> which
--   permits many folds and sinks to be run simultaneously on one
--   bytestream.
chunkFold :: Monad m => (x -> ByteString -> x) -> x -> (x -> a) -> ByteStream m r -> m (Of a r)

-- | <a>chunkFoldM</a> is preferable to <a>foldlChunksM</a> since it is an
--   appropriate argument for <a>impurely</a> which permits many folds and
--   sinks to be run simultaneously on one bytestream.
chunkFoldM :: Monad m => (x -> ByteString -> m x) -> m x -> (x -> m a) -> ByteStream m r -> m (Of a r)

-- | Instead of mapping over each <a>Word8</a> or <a>Char</a>, map over
--   each strict <a>ByteString</a> chunk in the stream.
chunkMap :: Monad m => (ByteString -> ByteString) -> ByteStream m r -> ByteStream m r

-- | Like <a>chunkMap</a>, but map effectfully.
chunkMapM :: Monad m => (ByteString -> m ByteString) -> ByteStream m r -> ByteStream m r

-- | Like <a>chunkMapM</a>, but discard the result of each effectful
--   mapping.
chunkMapM_ :: Monad m => (ByteString -> m x) -> ByteStream m r -> m r

-- | Resolve a succession of chunks into its Church encoding; this is not a
--   safe operation; it is equivalent to exposing the constructors
dematerialize :: Monad m => ByteStream m r -> forall x. (r -> x) -> (ByteString -> x -> x) -> (m x -> x) -> x

-- | Construct a succession of chunks from its Church encoding (compare
--   <tt>GHC.Exts.build</tt>)
materialize :: (forall x. (r -> x) -> (ByteString -> x -> x) -> (m x -> x) -> x) -> ByteStream m r

-- | Given a byte stream on a transformed monad, make it possible to 'run'
--   transformer.
distribute :: (Monad m, MonadTrans t, MFunctor t, Monad (t m), Monad (t (ByteStream m))) => ByteStream (t m) a -> t (ByteStream m) a

-- | Zip a list and a stream-of-byte-streams together.
zipWithStream :: Monad m => (forall x. a -> ByteStream m x -> ByteStream m x) -> [a] -> Stream (ByteStream m) m r -> Stream (ByteStream m) m r


-- | A simple module reexport to aid back-compatibility. Please use the new
--   module.

-- | <i>Deprecated: Use Streaming.ByteString.Char8 instead.</i>
module Data.ByteString.Streaming.Char8


-- | A simple module reexport to aid back-compatibility. Please use the new
--   module.

-- | <i>Deprecated: Use Streaming.ByteString instead.</i>
module Data.ByteString.Streaming


-- | A simple module reexport to aid back-compatibility. Please use the new
--   module.

-- | <i>Deprecated: Use Streaming.ByteString.Internal instead.</i>
module Data.ByteString.Streaming.Internal
