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


-- | effectful byte steams, or: bytestring io done right.
--   
--   This is an implementation of effectful, memory-constrained bytestrings
--   (byte streams) and functions for streaming bytestring manipulation,
--   adequate for non-lazy-io. Some examples of the use of byte streams to
--   implement simple shell progams can be found <a>here</a>. See also the
--   illustrations of use with e.g. <tt>attoparsec</tt>, <tt>aeson</tt>,
--   <tt>http-client</tt>, <tt>zlib</tt> etc. in the <a>streaming-utils</a>
--   library. Usage is as close as possible to that of <tt>ByteString</tt>
--   and lazy <tt>ByteString</tt>.
--   
--   A <tt>ByteString IO ()</tt> is the most natural representation of an
--   effectful stream of bytes arising chunkwise from a handle. Indeed, the
--   implementation follows the details of <tt>Data.ByteString.Lazy</tt>
--   and <tt>Data.ByteString.Lazy.Char8</tt> in unrelenting detail,
--   omitting only transparently non-streaming operations like
--   <tt>reverse</tt>. It is just a question of replacing the lazy
--   bytestring type:
--   
--   <pre>
--   data ByteString     = Empty   | Chunk Strict.ByteString ByteString
--   </pre>
--   
--   with the <i>minimal</i> effectful variant:
--   
--   <pre>
--   data ByteString m r = Empty r | Chunk Strict.ByteString (ByteString m r) | Go (m (ByteString m r))
--   </pre>
--   
--   (Constructors are necessarily hidden in internal modules in both the
--   <tt>Lazy</tt> and the <tt>Streaming</tt>.)
--   
--   That's it. As a lazy bytestring is implemented internally by a sort of
--   list of strict bytestring chunks, a streaming bytestring is simply
--   implemented as a <i>producer</i> or <i>generator</i> of strict
--   bytestring chunks. Most operations are defined by simply adding a line
--   to what we find in <tt>Data.ByteString.Lazy</tt>. The only possible
--   simplification would involve specializing to <tt>IO</tt>, throughout -
--   but this would e.g. block the use of <tt>ResourceT</tt> to manage
--   handles and the like, and a number of other convenient operations like
--   <tt>copy</tt>, which permits one to apply two operations
--   simultaneously over the length of the byte stream.
--   
--   Something like this alteration of type is of course obvious and
--   mechanical, once the idea of an effectful bytestring type is
--   contemplated and lazy io is rejected. Indeed it seems that this is the
--   proper expression of what was intended by lazy bytestrings to begin
--   with. The documentation, after all, reads
--   
--   <ul>
--   <li>"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."</li>
--   </ul>
--   
--   ... which is very much the idea of this library: the default chunk
--   size for <a>hGetContents</a> and the like follows
--   <tt>Data.ByteString.Lazy</tt>; operations like <tt>lines</tt> and
--   <tt>append</tt> and so on are tailored not to increase chunk size.
--   
--   The present library is thus if you like nothing but <i>lazy bytestring
--   done right</i>. The authors of <tt>Data.ByteString.Lazy</tt> must have
--   supposed that the directly monadic formulation of such their type
--   would necessarily make things slower. This appears to be a prejudice.
--   For example, passing a large file of short lines through this
--   benchmark transformation
--   
--   <pre>
--   Lazy.unlines      . map    (\bs -&gt; "!"       &lt;&gt; Lazy.drop 5 bs)       . Lazy.lines
--   Streaming.unlines . S.maps (\bs -&gt; chunk "!" &gt;&gt; Streaming.drop 5 bs)  . Streaming.lines
--   </pre>
--   
--   gives pleasing results like these
--   
--   <pre>
--   $  time ./benchlines lazy &gt;&gt; /dev/null
--   real	0m2.097s
--   ...
--   $  time ./benchlines streaming &gt;&gt; /dev/null
--   real	0m1.930s
--   </pre>
--   
--   For a more sophisticated operation like
--   
--   <pre>
--   Lazy.intercalate "!\n"      . Lazy.lines
--   Streaming.intercalate "!\n" . Streaming.lines
--   </pre>
--   
--   we get results like these:
--   
--   <pre>
--   time ./benchlines lazy &gt;&gt; /dev/null
--   real	0m1.250s
--   ...
--   time ./benchlines streaming &gt;&gt; /dev/null
--   real	0m1.531s
--   </pre>
--   
--   The pipes environment would express the latter as
--   
--   <pre>
--   Pipes.intercalates (Pipes.yield "!\n") . view Pipes.lines
--   </pre>
--   
--   meaning almost exactly what we mean above, but with results like this
--   
--   <pre>
--   time ./benchlines pipes &gt;&gt; /dev/null
--   real	0m6.353s
--   </pre>
--   
--   The difference, however, <i>is emphatically not intrinsic to
--   pipes</i>; it is just that this library depends the <tt>streaming</tt>
--   library, which is used in place of <tt>free</tt> to express the
--   <a>"perfectly streaming"</a> splitting and iterated division or
--   "chunking" of byte streams.
--   
--   These concepts belong to the ABCs of streaming; <tt>lines</tt> is just
--   a textbook example, and it is of course handled correctly in
--   <tt>Data.ByteString.Lazy</tt>. But the concepts are
--   <i>catastrophically mishandled</i> in <i>all</i> streaming io
--   libraries other than pipes. Already the <tt>enumerator</tt> and
--   <tt>iteratee</tt> libraries were completely defeated by
--   <tt>lines</tt>: see e.g. the <tt>enumerator</tt> implementation of
--   <a>splitWhen and lines</a>. This will concatenate strict text forever,
--   if that's what is coming in. The rot spreads from there. It is just a
--   fact that in all of the general streaming io frameworks other than
--   pipes,it becomes torture to express elementary distinctions that are
--   transparently and immediately contained in any idea of streaming
--   whatsoever.
--   
--   Though, as was said above, we barely alter signatures in
--   <tt>Data.ByteString.Lazy</tt> more than is required by the types, the
--   point of view that emerges is very much that of
--   <tt>pipes-bytestring</tt> and <tt>pipes-group</tt>. In particular we
--   have these correspondences:
--   
--   <pre>
--   Lazy.splitAt      :: Int -&gt; ByteString              -&gt; (ByteString, ByteString)
--   Streaming.splitAt :: Int -&gt; ByteString m r          -&gt; ByteString m (ByteString m r)
--   Pipes.splitAt     :: Int -&gt; Producer ByteString m r -&gt; Producer ByteString m (Producer ByteString m r)
--   </pre>
--   
--   and
--   
--   <pre>
--   Lazy.lines      :: ByteString -&gt; [ByteString]
--   Streaming.lines :: ByteString m r -&gt; Stream (ByteString m) m r
--   Pipes.lines     :: Producer ByteString m r -&gt; FreeT (Producer ByteString m) m r
--   </pre>
--   
--   where the <tt>Stream</tt> type expresses the sequencing of
--   <tt>ByteString m _</tt> layers with the usual 'free monad' sequencing.
--   
--   Interoperation with <tt>pipes-bytestring</tt> uses this isomorphism:
--   
--   <pre>
--   Streaming.ByteString.unfoldrChunks Pipes.next :: Monad m =&gt; Producer ByteString m r -&gt; ByteString m r
--   Pipes.unfoldr Streaming.ByteString.nextChunk  :: Monad m =&gt; ByteString m r -&gt; Producer ByteString m r
--   </pre>
--   
--   Interoperation with <tt>io-streams</tt> is thus:
--   
--   <pre>
--   IOStreams.unfoldM Streaming.ByteString.unconsChunk :: ByteString IO () -&gt; IO (InputStream ByteString)
--   Streaming.ByteString.reread IOStreams.read         :: InputStream ByteString -&gt; ByteString IO ()
--   </pre>
--   
--   and similarly for other rational streaming io libraries.
--   
--   Problems and questions about the library can be put as issues on the
--   github page, or mailed to the <a>pipes list</a>.
--   
--   A tutorial module is in the works; <a>here</a>, for the moment, is a
--   sequence of simplified implementations of familiar shell utilities.
--   The same programs are implemented at the end of the excellent
--   <a>io-streams tutorial</a>. It is generally much simpler; in some case
--   simpler than what you would write with lazy bytestrings. <a>Here</a>
--   is a simple GET request that returns a byte stream.
@package streaming-bytestring
@version 0.1.6

module Data.ByteString.Streaming.Internal

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

-- | Smart constructor for <a>Chunk</a>.
consChunk :: ByteString -> ByteString m r -> ByteString 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) -> ByteString 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 => ByteString m r -> (forall x. (r -> x) -> (ByteString -> x -> x) -> (m x -> x) -> x)

-- | Consume the chunks of an effectful ByteString with a natural right
--   fold.
foldrChunks :: Monad m => (ByteString -> a -> a) -> a -> ByteString m r -> m a
foldlChunks :: Monad m => (a -> ByteString -> a) -> a -> ByteString 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 -> ByteString m r -> m a
foldlChunksM :: Monad m => (a -> ByteString -> m a) -> m a -> ByteString 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 simulaneously on one
--   bytestream.
chunkFold :: Monad m => (x -> ByteString -> x) -> x -> (x -> a) -> ByteString m r -> m (Of a r)

-- | <tt>chunkFoldM</tt> is preferable to <tt>foldlChunksM</tt> since it is
--   an appropriate argument for <tt>Control.Foldl.impurely</tt> which
--   permits many folds and sinks to be run simulaneously on one
--   bytestream.
chunkFoldM :: Monad m => (x -> ByteString -> m x) -> m x -> (x -> m a) -> ByteString m r -> m (Of a r)
chunkMap :: Monad m => (ByteString -> ByteString) -> ByteString m r -> ByteString m r
chunkMapM :: Monad m => (ByteString -> m ByteString) -> ByteString m r -> ByteString m r
chunkMapM_ :: Monad m => (ByteString -> m x) -> ByteString m r -> m r
unfoldMChunks :: Monad m => (s -> m (Maybe (ByteString, s))) -> s -> ByteString m ()
unfoldrChunks :: Monad m => (s -> m (Either r (ByteString, s))) -> s -> ByteString m r
packChars :: Monad m => Stream (Of Char) m r -> ByteString m r

-- | The recommended chunk size. Currently set to 4k, less the memory
--   management overhead
smallChunkSize :: Int
unpackBytes :: Monad m => ByteString m r -> Stream (Of Word8) 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 S.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 =
--   unsafeDupablePerformIO (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
--   (S.ByteString, a) createUptoN' l f = do fp &lt;- S.mallocByteString l
--   (l', res) <a>withForeignPtr fp $ p -</a> f p assert (l' &lt;= l) $
--   return (S.PS fp 0 l', res) {--}
packBytes :: Monad m => Stream (Of Word8) m r -> ByteString m r

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

-- | Reconceive an effect that results in an effectful bytestring as an
--   effectful bytestring. Compare Streaming.mwrap. The closes 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 (ByteString m r) -> ByteString m r
unfoldrNE :: Int -> (a -> Either r (Word8, a)) -> a -> (ByteString, Either r a)

-- | Stream chunks from something that contains <tt>IO (Maybe
--   ByteString)</tt> until it returns <tt>Nothing</tt>. <tt>reread</tt> is
--   of particular use rendering <tt>io-streams</tt> input streams as byte
--   streams in the present sense
--   
--   <pre>
--   Q.reread Streams.read             :: InputStream S.ByteString -&gt; Q.ByteString IO ()
--   Q.reread (liftIO . Streams.read)  :: MonadIO m =&gt; InputStream S.ByteString -&gt; Q.ByteString m ()
--   </pre>
--   
--   The other direction here is
--   
--   <pre>
--   Streams.unfoldM Q.unconsChunk     :: Q.ByteString IO r -&gt; IO (InputStream S.ByteString)
--   </pre>
reread :: Monad m => (s -> m (Maybe ByteString)) -> s -> ByteString m ()
inlinePerformIO :: IO a -> a
unsafeLast :: ByteString -> Word8
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
--   </pre>
--   
--   world
--   
--   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 => ByteString m r -> ByteString (ByteString m) r
bracketByteString :: (MonadResource m) => IO a -> (a -> IO ()) -> (a -> ByteString m b) -> ByteString m b
instance GHC.Base.Monad m => GHC.Base.Monad (Data.ByteString.Streaming.Internal.ByteString m)
instance GHC.Base.Monad m => GHC.Base.Functor (Data.ByteString.Streaming.Internal.ByteString m)
instance GHC.Base.Monad m => GHC.Base.Applicative (Data.ByteString.Streaming.Internal.ByteString m)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Data.ByteString.Streaming.Internal.ByteString m)
instance Control.Monad.Trans.Class.MonadTrans Data.ByteString.Streaming.Internal.ByteString
instance Control.Monad.Morph.MFunctor Data.ByteString.Streaming.Internal.ByteString
instance r ~ () => Data.String.IsString (Data.ByteString.Streaming.Internal.ByteString m r)
instance (m ~ Data.Functor.Identity.Identity, GHC.Show.Show r) => GHC.Show.Show (Data.ByteString.Streaming.Internal.ByteString m r)
instance (Data.Semigroup.Semigroup r, GHC.Base.Monad m) => Data.Semigroup.Semigroup (Data.ByteString.Streaming.Internal.ByteString m r)
instance (GHC.Base.Monoid r, GHC.Base.Monad m) => GHC.Base.Monoid (Data.ByteString.Streaming.Internal.ByteString m r)
instance Control.Monad.Base.MonadBase b m => Control.Monad.Base.MonadBase b (Data.ByteString.Streaming.Internal.ByteString m)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Data.ByteString.Streaming.Internal.ByteString m)
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Data.ByteString.Streaming.Internal.ByteString m)
instance Control.Monad.Trans.Resource.Internal.MonadResource m => Control.Monad.Trans.Resource.Internal.MonadResource (Data.ByteString.Streaming.Internal.ByteString m)


-- | See the simple examples of use <a>here</a> and the <tt>ghci</tt>
--   examples especially in <a>Data.ByteString.Streaming.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>,
--   <tt>reverse</tt> 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 Data.ByteString.Streaming 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. Streaming variant by Michael Thompson, following the ideas of
--   Gabriel Gonzales' pipes-bytestring
module Data.ByteString.Streaming

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

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

-- | <i>O(1)</i> Yield a <a>Word8</a> as a minimal <a>ByteString</a>
singleton :: Monad m => Word8 -> ByteString 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 -> ByteString m r

-- | <i>O(n)</i> Converts a packed byte stream into a stream of individual
--   bytes.
unpack :: Monad m => ByteString 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 -> ByteString 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 (<tt>toStrict</tt> 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, <tt>toLazy</tt> is a suitable
--   argument for <a>mapped</a>
--   
--   <pre>
--   S.mapped Q.toLazy :: Stream (ByteString 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 => ByteString m r -> m (Of ByteString r)

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

-- | <i>O(1)</i> yield a strict <a>ByteString</a> chunk.
fromStrict :: ByteString -> ByteString 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 (ByteString 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 => ByteString 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 => ByteString m () -> m (ByteString)

-- | Perform the effects contained in an effectful bytestring, ignoring the
--   bytes.
effects :: Monad m => ByteString 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
--   </pre>
--   
--   world
--   
--   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 => ByteString m r -> ByteString (ByteString 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>
--   ByteString m (ByteString m r) -&gt; ByteString m r
--   </pre>
drained :: (Monad m, MonadTrans t, Monad (t m)) => t m (ByteString m r) -> t m r

-- | Reconceive an effect that results in an effectful bytestring as an
--   effectful bytestring. Compare Streaming.mwrap. The closes 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 (ByteString m r) -> ByteString 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 (ByteString m))) => ByteString (t m) a -> t (ByteString m) a

-- | <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 :: Monad m => (Word8 -> Word8) -> ByteString m r -> ByteString m r

-- | <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 :: Monad m => ByteString m () -> Stream (ByteString m) m r -> ByteString m r
intersperse :: Monad m => Word8 -> ByteString m r -> ByteString m r

-- | <i>O(1)</i> <a>cons</a> is analogous to '(:)' for lists.
cons :: Monad m => Word8 -> ByteString m r -> ByteString 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 -> ByteString m r -> ByteString m r

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

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

-- | <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 :: Monad m => (Word8 -> Bool) -> ByteString m r -> ByteString m r

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

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

-- | Remove empty ByteStrings from a stream of bytestrings.
denull :: Monad m => Stream (ByteString m) m r -> Stream (ByteString m) 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) -> ByteString m r -> ByteString m (ByteString 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>
--   
--   <pre>
--   &gt;&gt;&gt; 
--   </pre>
drop :: Monad m => Int64 -> ByteString m r -> ByteString 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) -> ByteString m r -> ByteString m r

-- | 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 :: Monad m => ByteString m r -> Stream (ByteString m) m r

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

-- | <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 :: Monad m => (Word8 -> Bool) -> ByteString m r -> ByteString m (ByteString 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 -> ByteString m r -> ByteString m (ByteString m r)

-- | <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 :: Monad m => (Word8 -> Bool) -> ByteString m r -> Stream (ByteString m) m r

-- | <i>O(n/c)</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>.
--   
--   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 -> ByteString m r -> ByteString m ()

-- | <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 :: Monad m => (Word8 -> Bool) -> ByteString m r -> ByteString m ()

-- | <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 :: Monad m => Word8 -> ByteString m r -> Stream (ByteString m) m r

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

-- | Take a builder and convert it to a genuine streaming bytestring, using
--   a specific allocation strategy.
toStreamingByteStringWith :: MonadIO m => AllocationStrategy -> Builder -> ByteString m ()
toStreamingByteString :: MonadIO m => Builder -> ByteString 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 :: ByteString IO () -> Builder
concatBuilders :: Stream (Of Builder) IO () -> Builder

-- | <tt><a>repeat</a> x</tt> is an infinite ByteString, 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 -> ByteString m r

-- | <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>
--   
--   <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 -> ByteString m r

-- | <a>cycle</a> ties a finite ByteString into a circular one, or
--   equivalently, the infinite repetition of the original ByteString. 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 => ByteString m r -> ByteString m s

-- | <i>O(n)</i> The <a>unfoldr</a> function is analogous to the Stream
--   <tt>unfoldr</tt>. <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 <tt><a>Just</a>
--   (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.
unfoldM :: Monad m => (a -> Maybe (Word8, a)) -> a -> ByteString m ()

-- | <tt>unfold</tt> is like <a>unfoldr</a> but stops when the co-algebra
--   returns <a>Left</a>; the result is the return value of the
--   <tt>ByteString m r</tt> <tt>unfoldr uncons = id</tt>
unfoldr :: (a -> Either r (Word8, a)) -> a -> ByteString m r

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

-- | <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.
--   
--   <pre>
--   foldr cons = id
--   </pre>
foldr :: Monad m => (Word8 -> a -> a) -> a -> ByteString m () -> m a

-- | <a>fold</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. We use the
--   style of the foldl libarary for left folds
fold :: Monad m => (x -> Word8 -> x) -> x -> (x -> b) -> ByteString m () -> m b

-- | <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) -> ByteString m r -> m (Of b r)

-- | <i>O(c)</i> Extract the first element of a <a>ByteString</a>, which
--   must be non-empty.
head :: Monad m => ByteString m r -> m (Of (Maybe Word8) r)

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

-- | <i>O(n/c)</i> Extract the last element of a <a>ByteString</a>, which
--   must be finite and non-empty.
last_ :: Monad m => ByteString 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 => ByteString m r -> m (Of Int r)
length_ :: Monad m => ByteString m r -> m Int

-- | Test whether a ByteString 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>
null :: Monad m => ByteString m r -> m (Of Bool r)

-- | <i>O(1)</i> Test whether an ByteString 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 => ByteString 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  ::  ByteString m r -&gt; m (Sum (ByteString m) (ByteString m) r)
--   </pre>
--   
--   There are many ways to remove null bytestrings from a <tt>Stream
--   (ByteString m) m r</tt> (besides using <tt>denull</tt>). If we pass
--   next to
--   
--   <pre>
--   &gt;&gt;&gt; mapped nulls bs :: Stream (Sum (ByteString m) (ByteString m)) m r
--   </pre>
--   
--   then can then apply <tt>Streaming.separate</tt> to get
--   
--   <pre>
--   &gt;&gt;&gt; separate (mapped nulls bs) :: Stream (ByteString m) (Stream (ByteString 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.ByteString 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.ByteString n) n b -&gt; Stream (Q.ByteString n) n b
--   </pre>
nulls :: Monad m => ByteString m r -> m (Sum (ByteString m) (ByteString m) r)
testNull :: Monad m => ByteString m r -> m (Of Bool (ByteString m r))
count :: Monad m => Word8 -> ByteString m r -> m (Of Int r)

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

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

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

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

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

-- | Read an entire file into a chunked <tt><a>ByteString</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 -> ByteString m ()

-- | Write a <a>ByteString</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 -> ByteString m r -> m r

-- | Append a <a>ByteString</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 -> ByteString m r -> m r

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

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

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

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

-- | Read entire handle contents <i>lazily</i> into a <a>ByteString</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.
--   
--   The handle is closed on EOF.
--   
--   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 -> ByteString m ()

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

-- | Outputs a <a>ByteString</a> to the specified <a>Handle</a>.
hPut :: MonadIO m => Handle -> ByteString m r -> m r
zipWithStream :: (Monad m) => (forall x. a -> ByteString m x -> ByteString m x) -> [a] -> Stream (ByteString m) m r -> Stream (ByteString m) m r
unconsChunk :: Monad m => ByteString m r -> m (Maybe (ByteString, ByteString m r))
nextChunk :: Monad m => ByteString m r -> m (Either r (ByteString, ByteString m r))

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

-- | Consume the chunks of an effectful ByteString with a natural right
--   fold.
foldrChunks :: Monad m => (ByteString -> a -> a) -> a -> ByteString m r -> m a
foldlChunks :: Monad m => (a -> ByteString -> a) -> a -> ByteString 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 simulaneously on one
--   bytestream.
chunkFold :: Monad m => (x -> ByteString -> x) -> x -> (x -> a) -> ByteString m r -> m (Of a r)

-- | <tt>chunkFoldM</tt> is preferable to <tt>foldlChunksM</tt> since it is
--   an appropriate argument for <tt>Control.Foldl.impurely</tt> which
--   permits many folds and sinks to be run simulaneously on one
--   bytestream.
chunkFoldM :: Monad m => (x -> ByteString -> m x) -> m x -> (x -> m a) -> ByteString m r -> m (Of a r)
chunkMap :: Monad m => (ByteString -> ByteString) -> ByteString m r -> ByteString m r
chunkMapM :: Monad m => (ByteString -> m ByteString) -> ByteString m r -> ByteString m r
chunkMapM_ :: Monad m => (ByteString -> m x) -> ByteString m r -> 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 <tt>Data.ByteString.Streaming</tt> 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 Data.ByteString.Streaming.Char8

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

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

-- | <i>O(n)</i> Convert a stream of separate characters into a packed byte
--   stream.
pack :: Monad m => Stream (Of Char) m r -> ByteString m r
unpack :: Monad m => ByteString m r -> Stream (Of Char) m r
string :: String -> ByteString 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 (ByteString m) m r -> ByteString m r

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

-- | <i>O(1)</i> Yield a <a>Char</a> as a minimal <a>ByteString</a>
singleton :: Monad m => Char -> ByteString 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 -> ByteString 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 -> ByteString m ()

-- | <i>O(1)</i> yield a strict <a>ByteString</a> chunk.
fromStrict :: ByteString -> ByteString 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 => ByteString 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 (<tt>toStrict</tt> 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, <tt>toLazy</tt> is a suitable
--   argument for <a>mapped</a>
--   
--   <pre>
--   S.mapped Q.toLazy :: Stream (ByteString 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 => ByteString m r -> m (Of ByteString r)

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

-- | Perform the effects contained in an effectful bytestring, ignoring the
--   bytes.
effects :: Monad m => ByteString 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
--   </pre>
--   
--   world
--   
--   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 => ByteString m r -> ByteString (ByteString 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>
--   ByteString m (ByteString m r) -&gt; ByteString m r
--   </pre>
drained :: (Monad m, MonadTrans t, Monad (t m)) => t m (ByteString m r) -> t m r

-- | Reconceive an effect that results in an effectful bytestring as an
--   effectful bytestring. Compare Streaming.mwrap. The closes 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 (ByteString m r) -> ByteString m r

-- | <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 :: Monad m => (Char -> Char) -> ByteString m r -> ByteString m r

-- | <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 :: Monad m => ByteString m () -> Stream (ByteString m) m r -> ByteString m r
intersperse :: Monad m => Char -> ByteString m r -> ByteString m r

-- | <i>O(1)</i> Cons a <a>Char</a> onto a byte stream.
cons :: Monad m => Char -> ByteString m r -> ByteString 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 ByteStrings.
cons' :: Char -> ByteString m r -> ByteString m r

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

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

-- | <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 :: Monad m => (Char -> Bool) -> ByteString m r -> ByteString m r

-- | <i>O(1)</i> Extract the first element of a ByteString, which may be
--   non-empty
head :: Monad m => ByteString m r -> m (Of (Maybe Char) r)

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

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

-- | Test whether a ByteString 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>
null :: Monad m => ByteString m r -> m (Of Bool r)

-- | <i>O(1)</i> Test whether an ByteString 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 => ByteString m r -> m Bool
testNull :: Monad m => ByteString m r -> m (Of Bool (ByteString m r))

-- | <i>O1</i> Distinguish empty from non-empty lines, while maintaining
--   streaming; the empty ByteStrings are on the right
--   
--   <pre>
--   &gt;&gt;&gt; nulls  ::  ByteString m r -&gt; m (Sum (ByteString m) (ByteString m) r)
--   </pre>
--   
--   There are many ways to remove null bytestrings from a <tt>Stream
--   (ByteString m) m r</tt> (besides using <tt>denull</tt>). If we pass
--   next to
--   
--   <pre>
--   &gt;&gt;&gt; mapped nulls bs :: Stream (Sum (ByteString m) (ByteString m)) m r
--   </pre>
--   
--   then can then apply <tt>Streaming.separate</tt> to get
--   
--   <pre>
--   &gt;&gt;&gt; separate (mapped nulls bs) :: Stream (ByteString m) (Stream (ByteString 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.ByteString 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.ByteString n) n b -&gt; Stream (Q.ByteString n) n b
--   </pre>
nulls :: Monad m => ByteString m r -> m (Sum (ByteString m) (ByteString m) r)

-- | <i>O(1)</i> Extract the head and tail of a ByteString, returning
--   Nothing if it is empty.
uncons :: Monad m => ByteString m r -> m (Either r (Char, ByteString m r))
nextChar :: Monad m => ByteString m r -> m (Either r (Char, ByteString 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) -> ByteString m r -> ByteString m (ByteString 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>
--   
--   <pre>
--   &gt;&gt;&gt; 
--   </pre>
drop :: Monad m => Int64 -> ByteString m r -> ByteString 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) -> ByteString m r -> ByteString m r

-- | 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 :: Monad m => ByteString m r -> Stream (ByteString m) m r
groupBy :: Monad m => (Char -> Char -> Bool) -> ByteString m r -> Stream (ByteString m) m r

-- | <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 :: Monad m => (Char -> Bool) -> ByteString m r -> ByteString m (ByteString 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 -> ByteString m r -> ByteString m (ByteString m r)
splitWith :: Monad m => (Char -> Bool) -> ByteString m r -> Stream (ByteString m) m r

-- | <i>O(n/c)</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>.
--   
--   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 -> ByteString m r -> ByteString m ()

-- | <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 :: Monad m => (Char -> Bool) -> ByteString m r -> ByteString m ()

-- | <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.
--   
--   <pre>
--   &gt;&gt;&gt; Q.stdout $ Q.unlines $ Q.split 'n' "banana peel"
--   ba
--   a
--   a peel
--   </pre>
split :: Monad m => Char -> ByteString m r -> Stream (ByteString m) m r

-- | <a>lines</a> turns a ByteString into a connected stream of ByteStrings
--   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>ByteString</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 => ByteString m r -> Stream (ByteString m) m r

-- | <a>words</a> breaks a byte stream up into a succession of byte streams
--   corresponding to words, breaking Chars 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. It is best for the user who
--   has reflected on her materials to write `mapped toStrict . words` or
--   the like, if strict bytestrings are needed.
words :: Monad m => ByteString m r -> Stream (ByteString m) m r

-- | <a>lineSplit</a> turns a ByteString into a connected stream of
--   ByteStrings 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 -> ByteString m r -> Stream (ByteString m) m r

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

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

-- | Take a builder and convert it to a genuine streaming bytestring, using
--   a specific allocation strategy.
toStreamingByteStringWith :: MonadIO m => AllocationStrategy -> Builder -> ByteString 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 :: ByteString IO () -> Builder
concatBuilders :: Stream (Of Builder) IO () -> Builder

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

-- | <tt><a>iterate</a> f x</tt> returns an infinite ByteString of repeated
--   applications of <tt>f</tt> to <tt>x</tt>:
iterate :: (Char -> Char) -> Char -> ByteString m r

-- | <a>cycle</a> ties a finite ByteString into a circular one, or
--   equivalently, the infinite repetition of the original ByteString. 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 => ByteString m r -> ByteString m s
unfoldr :: (a -> Either r (Char, a)) -> a -> ByteString m r

-- | <a>cycle</a> ties a finite ByteString into a circular one, or
--   equivalently, the infinite repetition of the original ByteString.
--   
--   | <i>O(n)</i> The <a>unfoldr</a> function is analogous to the Stream
--   '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.
unfoldM :: Monad m => (a -> Maybe (Char, a)) -> a -> ByteString m ()

-- | Stream chunks from something that contains <tt>IO (Maybe
--   ByteString)</tt> until it returns <tt>Nothing</tt>. <tt>reread</tt> is
--   of particular use rendering <tt>io-streams</tt> input streams as byte
--   streams in the present sense
--   
--   <pre>
--   Q.reread Streams.read             :: InputStream S.ByteString -&gt; Q.ByteString IO ()
--   Q.reread (liftIO . Streams.read)  :: MonadIO m =&gt; InputStream S.ByteString -&gt; Q.ByteString m ()
--   </pre>
--   
--   The other direction here is
--   
--   <pre>
--   Streams.unfoldM Q.unconsChunk     :: Q.ByteString IO r -&gt; IO (InputStream S.ByteString)
--   </pre>
reread :: Monad m => (s -> m (Maybe ByteString)) -> s -> ByteString m ()
fold :: Monad m => (x -> Char -> x) -> x -> (x -> b) -> ByteString m r -> m (Of b r)
fold_ :: Monad m => (x -> Char -> x) -> x -> (x -> b) -> ByteString 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 => ByteString m r -> m (Of Int r)
length_ :: Monad m => ByteString m r -> m Int
count :: Monad m => Char -> ByteString m r -> m (Of Int r)
count_ :: Monad m => Char -> ByteString m r -> m Int

-- | This will read positive or negative Ints that require 18 or fewer
--   characters.
readInt :: Monad m => ByteString m r -> m (Compose (Of (Maybe Int)) (ByteString m) r)

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

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

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

-- | A synonym for <tt>hPut</tt>, for compatibility
--   
--   hPutStr :: Handle -&gt; ByteString IO r -&gt; IO r hPutStr = hPut
--   
--   <ul>
--   <li>- | Write a ByteString to stdout putStr :: ByteString IO r -&gt;
--   IO r putStr = hPut IO.stdout</li>
--   </ul>
--   
--   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.
--   
--   <pre>
--   interact morph = stdout (morph stdin)
--   </pre>
interact :: (ByteString IO () -> ByteString IO r) -> IO r
putStr :: MonadIO m => ByteString m r -> m r
putStrLn :: MonadIO m => ByteString m r -> m r

-- | Read an entire file into a chunked <tt><a>ByteString</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 -> ByteString m ()

-- | Write a <a>ByteString</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 -> ByteString m r -> m r

-- | Append a <a>ByteString</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 -> ByteString m r -> m r

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

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

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

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

-- | Read entire handle contents <i>lazily</i> into a <a>ByteString</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.
--   
--   The handle is closed on EOF.
--   
--   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 -> ByteString m ()

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

-- | Outputs a <a>ByteString</a> to the specified <a>Handle</a>.
hPut :: MonadIO m => Handle -> ByteString m r -> m r
unconsChunk :: Monad m => ByteString m r -> m (Maybe (ByteString, ByteString m r))
nextChunk :: Monad m => ByteString m r -> m (Either r (ByteString, ByteString m r))

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

-- | Consume the chunks of an effectful ByteString with a natural right
--   fold.
foldrChunks :: Monad m => (ByteString -> a -> a) -> a -> ByteString m r -> m a
foldlChunks :: Monad m => (a -> ByteString -> a) -> a -> ByteString 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 simulaneously on one
--   bytestream.
chunkFold :: Monad m => (x -> ByteString -> x) -> x -> (x -> a) -> ByteString m r -> m (Of a r)

-- | <tt>chunkFoldM</tt> is preferable to <tt>foldlChunksM</tt> since it is
--   an appropriate argument for <tt>Control.Foldl.impurely</tt> which
--   permits many folds and sinks to be run simulaneously on one
--   bytestream.
chunkFoldM :: Monad m => (x -> ByteString -> m x) -> m x -> (x -> m a) -> ByteString m r -> m (Of a r)
chunkMap :: Monad m => (ByteString -> ByteString) -> ByteString m r -> ByteString m r
chunkMapM :: Monad m => (ByteString -> m ByteString) -> ByteString m r -> ByteString m r
chunkMapM_ :: Monad m => (ByteString -> m x) -> ByteString m r -> 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 (ByteString m))) => ByteString (t m) a -> t (ByteString m) a

-- | 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) -> ByteString 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 => ByteString m r -> (forall x. (r -> x) -> (ByteString -> x -> x) -> (m x -> x) -> x)
