# String -> ByteString +bytestring

*O(n)* Convert a String into a ByteString
For applications with large numbers of string literals, pack can be a bottleneck.
Read an entire file *lazily* into a ByteString. The Handle will be held open until EOF is encountered.
Read an entire file strictly into a ByteString. This is far more efficient than reading the characters into a String and then using pack. It also may be more efficient than opening the file and reading it using hGet.
Read an entire file strictly into a ByteString. This is far more efficient than reading the characters into a String and then using pack. It also may be more efficient than opening the file and reading it using hGet.
repeat x is an infinite ByteString, with x the value of every element.
iterate f x returns an infinite ByteString of repeated applications of f to x:
> iterate f x == [x, f x, f (f x), ...]
*O(n)* replicate n x is a ByteString of length n with x the value of every element.
*O(n)* replicate n x is a ByteString of length n with x the value of every element. The following holds:
> replicate w c = unfoldr w (\u -> Just (u,u)) c
This implemenation uses memset(3)
*O(1)* cons is analogous to '(:)' for lists.
*O(n)* cons is analogous to (:) for lists, but of different complexity, as it requires a memcpy.
*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.
*O(n)* The intersperse function takes a Char and a ByteString and `intersperses' that Char between the elements of the ByteString. It is analogous to the intersperse function on Lists.
*O(n)* Append a Char to the end of a ByteString. Similar to cons, this function performs a memcpy.
scanl is similar to foldl, but returns a list of successive reduced values from the left. This function will fuse.
> scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
Note that
> last (scanl f z xs) == foldl f z xs.
scanl is similar to foldl, but returns a list of successive reduced values from the left:
> scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
Note that
> last (scanl f z xs) == foldl f z xs.
scanr is the right-to-left dual of scanl.

*O(n)* Break a ByteString into pieces separated by the byte argument, consuming the delimiter. I.e.
> split '\n' "a\nb\nd\ne" == ["a","b","d","e"]
> split 'a' "aXaXaXa" == ["","X","X","X",""]
> split 'x' "x" == ["",""]
and
> intercalate [c] . split c == id
> split == splitWith . (==)
As for all splitting functions in this library, this function does not copy the substrings, it just constructs new ByteStrings that are slices of the original.
*O(n)* Break a ByteString into pieces separated by the byte argument, consuming the delimiter. I.e.
> split '\n' "a\nb\nd\ne" == ["a","b","d","e"]
> split 'a' "aXaXaXa" == ["","X","X","X"]
> split 'x' "x" == ["",""]
and
> intercalate [c] . split c == id
> split == splitWith . (==)
As for all splitting functions in this library, this function does not copy the substrings, it just constructs new ByteStrings that are slices of the original.
*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.
*O(n)*, 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 the next byte in the string, and b is the seed value for further production.
Examples:
> unfoldr (\x -> if x <= 5 then Just (x, x + 1) else Nothing) 0
> == pack [0, 1, 2, 3, 4, 5]
*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.
*O(n)*, 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 the next character in the string, and b is the seed value for further production.
Examples:
> unfoldr (\x -> if x <= '9' then Just (x, succ x) else Nothing) '0' == "0123456789"
A fmap-like operator for builder primitives, both bounded and fixed size.
Builder primitives are contravariant so it's like the normal fmap, but backwards (look at the type). (If it helps to remember, the operator symbol is like ($) but backwards.)
We can use it for example to prepend and/or append fixed values to an primitive.
> showEncoding ((\x -> ('\'', (x, '\''))) >$< fixed3) 'x' = "'x'"
>
> fixed3 = char7 >*< char7 >*< char7
Note that the rather verbose syntax for composition stems from the requirement to be able to compute the size / size bound at compile time.