A time and space-efficient implementation of lazy byte vectors
using lists of packed Word8 arrays, suitable for high performance
use, both in terms of large data quantities, or high speed
requirements. Byte vectors are encoded as lazy lists of strict Word8
arrays of bytes. They provide a means to manipulate large byte vectors
without requiring the entire vector be resident in memory.

Some operations, such as concat, append, reverse and cons, have
better complexity than their Data.ByteString equivalents, due to
optimisations resulting from the list spine structure. And for other
operations lazy ByteStrings are usually within a few percent of
strict ones, but with better heap usage. For data larger than the
available memory, or if you have tight memory constraints, this
module will be the only option. The default chunk size is 64k, which
should be good in most circumstances. For people with large L2
caches, you may want to increase this to fit your cache.

This module is intended to be imported qualified, to avoid name
clashes with Prelude functions. eg.

import qualified Data.ByteString.Lazy as B

Original GHC implementation by Bryan O'Sullivan.
Rewritten to use Data.Array.Unboxed.UArray by Simon Marlow.
Rewritten to support slices and use Foreign.ForeignPtr.ForeignPtr
by David Roundy.
Polished and extended by Don Stewart.
Lazy variant by Duncan Coutts and Don Stewart.

Basic interface

O(1) Unlike cons, '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:

let xs = cons\' c xs in xs

You can however use cons, as well as repeat and cycle, to build
infinite lazy ByteStrings.

Accumulating maps

The mapAccumL function behaves like a combination of map and
foldl; it applies a function to each element of a ByteString,
passing an accumulating parameter from left to right, and returning a
final value of this accumulator together with the new ByteString.

The mapAccumR function behaves like a combination of map and
foldr; it applies a function to each element of a ByteString,
passing an accumulating parameter from right to left, and returning a
final value of this accumulator together with the new ByteString.

Unfolding ByteStrings

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

The group 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,

group "Mississippi" = ["M","i","ss","i","ss","i","pp","i"]

It is a special case of groupBy, which allows the programmer to
supply their own equality test.

O(n) Splits a ByteString 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.

Indexing ByteStrings

O(n) The elemIndex function returns the index of the first
element in the given ByteString which is equal to the query
element, or Nothing if there is no such element.
This implementation uses memchr(3).

Zipping and unzipping ByteStrings

O(n)zip takes two ByteStrings and returns a list of
corresponding pairs of bytes. If one input ByteString is short,
excess elements of the longer ByteString are discarded. This is
equivalent to a pair of unpack operations.

zipWith generalises zip by zipping with the function given as
the first argument, instead of a tupling function. For example,
zipWith (+) is applied to two ByteStrings to produce the list of
corresponding sums.

Ordered ByteStrings

Low level conversions

Copying ByteStrings

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

The interact function takes a function of type ByteString -> ByteString
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.