A space-efficient representation of a succession of Word8 vectors, supporting many efficient operations.

An effectful ByteStream contains 8-bit bytes, or by using certain operations can be interpreted as containing 8-bit characters. It also contains an offset, which will be needed to track the virtual offsets in the BGZF decode.

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

O(1) Yield a Word8 as a minimal ByteStream

O(c) Transmute a pseudo-pure lazy bytestring to its representation as a monadic stream of chunks.

>>> Q.putStrLn $ Q.fromLazy "hi"
hi
>>> Q.fromLazy "hi"
Chunk "hi" (Empty (()))  -- note: a 'show' instance works in the identity monad
>>> Q.fromLazy $ BL.fromChunks ["here", "are", "some", "chunks"]
Chunk "here" (Chunk "are" (Chunk "some" (Chunk "chunks" (Empty (())))))

O(c) Converts a stream of strict bytestrings into a byte stream.

O(n) Convert an effectful byte stream into a single lazy ByteStream with the same internal chunk structure, retaining the original return value.

This is the canonical way of breaking streaming (toStrict 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, toLazy is a suitable argument for mapped

  B.mapped Q.toLazy :: Stream (ByteStream m) m r -> Stream (Of LazyBytes) m r

>>> Q.toLazy "hello"
"hello" :> ()
>>> B.toListM $ traverses Q.toLazy $ Q.lines "one\ntwo\nthree\nfour\nfive\n"
["one","two","three","four","five",""]  -- [LazyBytes]

O(n) Convert a monadic byte stream into a single strict ByteStream, retaining the return value of the original pair. This operation is for use with mapped.

mapped R.toStrict :: Monad m => Stream (ByteStream m) m r -> Stream (Of ByteStream) m r

It is subject to all the objections one makes to Data.ByteStream.Lazy toStrict; all of these are devastating.

Perform the effects contained in an effectful bytestring, ignoring the bytes.

Reconceive an effect that results in an effectful bytestring as an effectful bytestring. Compare Streaming.mwrap. The closes equivalent of

>>> Streaming.wrap :: f (Stream f m r) -> Stream f m r

is here consChunk. mwrap is the smart constructor for the internal Go constructor.

O(1) cons is analogous to '(:)' for lists.

O(1) Extract the head and tail of a ByteStream, or its return value if it is empty. This is the 'natural' uncons for an effectful byte stream.

break p is equivalent to span (not . p).

O(n/c) drop n xs returns the suffix of xs after the first n elements, or [] if n > length xs.

>>> Q.putStrLn $ Q.drop 6 "Wisconsin"
sin
>>> Q.putStrLn $ Q.drop 16 "Wisconsin"

>>> 

dropWhile p xs returns the suffix remaining after takeWhile p xs.

O(n/c) splitAt n xs is equivalent to (take n xs, drop n xs).

>>> rest <- Q.putStrLn $ Q.splitAt 3 "therapist is a danger to good hyphenation, as Knuth notes"
the
>>> Q.putStrLn $ Q.splitAt 19 rest
rapist is a danger

Strictly splits off a piece. This breaks streaming, so reserve its use for small strings or when conversion to strict Bytes is needed anyway.

Turns a ByteStream into a connected stream of ByteStreams that divide at newline characters. The resulting strings do not contain newlines. This is the genuinely streaming lines which only breaks chunks, and thus never increases the use of memory.

Because ByteStreams are usually read in binary mode, with no line ending conversion, this function recognizes both \n and \r\n endings (regardless of the current platform).

Turns a ByteStream into a stream of strict Bytes that divide at newline characters. The resulting strings do not contain newlines. This will cost memory if the lines are very long.

O(n) Concatenate a stream of byte streams.

Take a builder and convert it to a genuine streaming bytestring, using a specific allocation strategy.

Writes a ByteStream to a file. Actually writes to a temporary file and renames it on successful completion. The filename "-" causes it to write to stdout instead.

Read entire handle contents lazily into a ByteStream. Chunks are read on demand, using the default chunk size.

Note: the Handle should be placed in binary mode with hSetBinaryMode for hGetContents to work correctly.

Read entire handle contents lazily into a ByteStream. Chunks are read on demand, in at most k-sized chunks. It does not block waiting for a whole k-sized chunk, so if less than k bytes are available then they will be returned immediately as a smaller chunk.

The handle is closed on EOF.

Note: the Handle should be placed in binary mode with hSetBinaryMode for hGetContentsN to work correctly.

Outputs a ByteStream to the specified Handle.

Smart constructor for Chunk.

Yield-style smart constructor for Chunk.

Compresses a byte stream using GZip with default parameters.

Decompresses GZip if present. If any GZip stream is found, all such streams are decompressed and any remaining data is discarded. Else, the input is returned unchanged. If the input is BGZF, the result will contain meaningful virtual offsets. If the input contains exactly one GZip stream, the result will have meaningfull offsets into the uncompressed data. Else, the offsets will be bogus.

Checks if the input is GZip at all, and runs gunzip if it is. If it isn't, it runs k on the input.