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


-- | Fast, compact, strict and lazy byte strings with a list interface
°5u
°5uAn efficient compact, immutable byte string type (both strict and
°5ulazy) suitable for binary or 8-bit character data.
°5u
°5uThe <a>ByteString</a> type represents sequences of bytes or 8-bit
°5ucharacters. It is suitable for high performance use, both in terms of
°5ularge data quantities, or high speed requirements. The
°5u<a>ByteString</a> functions follow the same style as Haskell's
°5uordinary lists, so it is easy to convert code from using <a>String</a>
°5uto <a>ByteString</a>.
°5u
°5uTwo <a>ByteString</a> variants are provided:
°5u
°5u<ul>
°5u<li>Strict <a>ByteString</a>s keep the string as a single large array.
°5uThis makes them convenient for passing data between C and
°5uHaskell.</li>
°5u<li>Lazy <a>ByteString</a>s use a lazy list of strict chunks which
°5umakes it suitable for I/O streaming tasks.</li>
°5u</ul>
°5u
°5uThe <tt>Char8</tt> modules provide a character-based view of the same
°5uunderlying <a>ByteString</a> types. This makes it convenient to handle
°5umixed binary and 8-bit character content (which is common in many file
°5uformats and network protocols).
°5u
°5uThe <a>Builder</a> module provides an efficient way to build up
°5u<a>ByteString</a>s in an ad-hoc way by repeated concatenation. This is
°5uideal for fast serialisation or pretty printing.
°5u
°5uThere is also a <a>ShortByteString</a> type which has a lower memory
°5uoverhead and can can be converted to or from a <a>ByteString</a>, but
°5usupports very few other operations. It is suitable for keeping many
°5ushort strings in memory.
°5u
°5u<a>ByteString</a>s are not designed for Unicode. For Unicode strings
°5uyou should use the <a>Text</a> type from the <tt>text</tt> package.
°5u
°5uThese modules are intended to be imported qualified, to avoid name
°5uclashes with <a>Prelude</a> functions, e.g.
°5u
°5u<pre>
°5uimport qualified Data.ByteString as BS
°5u</pre>
@package bytestring
@version 0.10.8.2


-- | A compact representation suitable for storing short byte strings in
°5umemory.
°5u
°5uIn typical use cases it can be imported alongside
°5u<a>Data.ByteString</a>, e.g.
°5u
°5u<pre>
°5uimport qualified Data.ByteString       as B
°5uimport qualified Data.ByteString.Short as B
°5u         (ShortByteString, toShort, fromShort)
°5u</pre>
°5u
°5uOther <a>ShortByteString</a> operations clash with
°5u<a>Data.ByteString</a> or <a>Prelude</a> functions however, so they
°5ushould be imported <tt>qualified</tt> with a different alias e.g.
°5u
°5u<pre>
°5uimport qualified Data.ByteString.Short as B.Short
°5u</pre>
module Data.ByteString.Short

-- | A compact representation of a <a>Word8</a> vector.
°5u
°5uIt has a lower memory overhead than a <a>ByteString</a> and and does
°5unot contribute to heap fragmentation. It can be converted to or from a
°5u<a>ByteString</a> (at the cost of copying the string data). It
°5usupports very few other operations.
°5u
°5uIt is suitable for use as an internal representation for code that
°5uneeds to keep many short strings in memory, but it <i>should not</i>
°5ube used as an interchange type. That is, it should not generally be
°5uused in public APIs. The <a>ByteString</a> type is usually more
°5usuitable for use in interfaces; it is more flexible and it supports a
°5uwide range of operations.
data ShortByteString

-- | <i>O(n)</i>. Convert a <a>ByteString</a> into a
°5u<a>ShortByteString</a>.
°5u
°5uThis makes a copy, so does not retain the input string.
toShort :: ByteString -> ShortByteString

-- | <i>O(n)</i>. Convert a <a>ShortByteString</a> into a
°5u<a>ByteString</a>.
fromShort :: ShortByteString -> ByteString

-- | <i>O(n)</i>. Convert a list into a <a>ShortByteString</a>
pack :: [Word8] -> ShortByteString

-- | <i>O(n)</i>. Convert a <a>ShortByteString</a> into a list.
unpack :: ShortByteString -> [Word8]

-- | <i>O(1)</i>. The empty <a>ShortByteString</a>.
empty :: ShortByteString

-- | <i>O(1)</i> Test whether a <a>ShortByteString</a> is empty.
null :: ShortByteString -> Bool

-- | <i>O(1)</i> The length of a <a>ShortByteString</a>.
length :: ShortByteString -> Int

-- | <i>O(1)</i> <a>ShortByteString</a> index (subscript) operator,
°5ustarting from 0.
index :: ShortByteString -> Int -> Word8


-- | A module containing unsafe <a>ByteString</a> operations.
°5u
°5uWhile these functions have a stable API and you may use these
°5ufunctions in applications, do carefully consider the documented
°5upre-conditions; incorrect use can break referential transparency or
°5uworse.
module Data.ByteString.Unsafe

-- | A variety of <a>head</a> for non-empty ByteStrings. <a>unsafeHead</a>
°5uomits the check for the empty case, so there is an obligation on the
°5uprogrammer to provide a proof that the ByteString is non-empty.
unsafeHead :: ByteString -> Word8

-- | A variety of <a>tail</a> for non-empty ByteStrings. <a>unsafeTail</a>
°5uomits the check for the empty case. As with <a>unsafeHead</a>, the
°5uprogrammer must provide a separate proof that the ByteString is
°5unon-empty.
unsafeTail :: ByteString -> ByteString

-- | A variety of <a>init</a> for non-empty ByteStrings. <a>unsafeInit</a>
°5uomits the check for the empty case. As with <a>unsafeHead</a>, the
°5uprogrammer must provide a separate proof that the ByteString is
°5unon-empty.
unsafeInit :: ByteString -> ByteString

-- | A variety of <a>last</a> for non-empty ByteStrings. <a>unsafeLast</a>
°5uomits the check for the empty case. As with <a>unsafeHead</a>, the
°5uprogrammer must provide a separate proof that the ByteString is
°5unon-empty.
unsafeLast :: ByteString -> Word8

-- | Unsafe <a>ByteString</a> index (subscript) operator, starting from 0,
°5ureturning a <a>Word8</a> This omits the bounds check, which means
°5uthere is an accompanying obligation on the programmer to ensure the
°5ubounds are checked in some other way.
unsafeIndex :: ByteString -> Int -> Word8

-- | A variety of <a>take</a> which omits the checks on <tt>n</tt> so there
°5uis an obligation on the programmer to provide a proof that <tt>0 &lt;=
°5un &lt;= <a>length</a> xs</tt>.
unsafeTake :: Int -> ByteString -> ByteString

-- | A variety of <a>drop</a> which omits the checks on <tt>n</tt> so there
°5uis an obligation on the programmer to provide a proof that <tt>0 &lt;=
°5un &lt;= <a>length</a> xs</tt>.
unsafeDrop :: Int -> ByteString -> ByteString

-- | <i>O(1) construction</i> Use a <tt>ByteString</tt> with a function
°5urequiring a <tt>CString</tt>.
°5u
°5uThis function does zero copying, and merely unwraps a
°5u<tt>ByteString</tt> to appear as a <tt>CString</tt>. It is
°5u<i>unsafe</i> in two ways:
°5u
°5u<ul>
°5u<li>After calling this function the <tt>CString</tt> shares the
°5uunderlying byte buffer with the original <tt>ByteString</tt>. Thus
°5umodifying the <tt>CString</tt>, either in C, or using poke, will cause
°5uthe contents of the <tt>ByteString</tt> to change, breaking
°5ureferential transparency. Other <tt>ByteStrings</tt> created by
°5usharing (such as those produced via <a>take</a> or <a>drop</a>) will
°5ualso reflect these changes. Modifying the <tt>CString</tt> will break
°5ureferential transparency. To avoid this, use <tt>useAsCString</tt>,
°5uwhich makes a copy of the original <tt>ByteString</tt>.</li>
°5u<li><tt>CStrings</tt> are often passed to functions that require them
°5uto be null-terminated. If the original <tt>ByteString</tt> wasn't null
°5uterminated, neither will the <tt>CString</tt> be. It is the
°5uprogrammers responsibility to guarantee that the <tt>ByteString</tt>
°5uis indeed null terminated. If in doubt, use
°5u<tt>useAsCString</tt>.</li>
°5u<li>The memory may freed at any point after the subcomputation
°5uterminates, so the pointer to the storage must *not* be used after
°5uthis.</li>
°5u</ul>
unsafeUseAsCString :: ByteString -> (CString -> IO a) -> IO a

-- | <i>O(1) construction</i> Use a <tt>ByteString</tt> with a function
°5urequiring a <tt>CStringLen</tt>.
°5u
°5uThis function does zero copying, and merely unwraps a
°5u<tt>ByteString</tt> to appear as a <tt>CStringLen</tt>. It is
°5u<i>unsafe</i>:
°5u
°5u<ul>
°5u<li>After calling this function the <tt>CStringLen</tt> shares the
°5uunderlying byte buffer with the original <tt>ByteString</tt>. Thus
°5umodifying the <tt>CStringLen</tt>, either in C, or using poke, will
°5ucause the contents of the <tt>ByteString</tt> to change, breaking
°5ureferential transparency. Other <tt>ByteStrings</tt> created by
°5usharing (such as those produced via <a>take</a> or <a>drop</a>) will
°5ualso reflect these changes. Modifying the <tt>CStringLen</tt> will
°5ubreak referential transparency. To avoid this, use
°5u<tt>useAsCStringLen</tt>, which makes a copy of the original
°5u<tt>ByteString</tt>.</li>
°5u</ul>
unsafeUseAsCStringLen :: ByteString -> (CStringLen -> IO a) -> IO a

-- | <i>O(n)</i> Build a <tt>ByteString</tt> from a <tt>CString</tt>. This
°5uvalue will have <i>no</i> finalizer associated to it, and will not be
°5ugarbage collected by Haskell. The ByteString length is calculated
°5uusing <i>strlen(3)</i>, and thus the complexity is a <i>O(n)</i>.
°5u
°5uThis function is <i>unsafe</i>. If the <tt>CString</tt> is later
°5umodified, this change will be reflected in the resulting
°5u<tt>ByteString</tt>, breaking referential transparency.
unsafePackCString :: CString -> IO ByteString

-- | <i>O(1)</i> Build a <tt>ByteString</tt> from a <tt>CStringLen</tt>.
°5uThis value will have <i>no</i> finalizer associated with it, and will
°5unot be garbage collected by Haskell. This operation has <i>O(1)</i>
°5ucomplexity as we already know the final size, so no <i>strlen(3)</i>
°5uis required.
°5u
°5uThis function is <i>unsafe</i>. If the original <tt>CStringLen</tt> is
°5ulater modified, this change will be reflected in the resulting
°5u<tt>ByteString</tt>, breaking referential transparency.
unsafePackCStringLen :: CStringLen -> IO ByteString

-- | <i>O(n)</i> Build a <tt>ByteString</tt> from a malloced
°5u<tt>CString</tt>. This value will have a <tt>free(3)</tt> finalizer
°5uassociated to it.
°5u
°5uThis function is <i>unsafe</i>. If the original <tt>CString</tt> is
°5ulater modified, this change will be reflected in the resulting
°5u<tt>ByteString</tt>, breaking referential transparency.
°5u
°5uThis function is also unsafe if you call its finalizer twice, which
°5uwill result in a <i>double free</i> error, or if you pass it a CString
°5unot allocated with <tt>malloc</tt>.
unsafePackMallocCString :: CString -> IO ByteString

-- | <i>O(1)</i> Build a <tt>ByteString</tt> from a malloced
°5u<tt>CStringLen</tt>. This value will have a <tt>free(3)</tt> finalizer
°5uassociated to it.
°5u
°5uThis function is <i>unsafe</i>. If the original <tt>CString</tt> is
°5ulater modified, this change will be reflected in the resulting
°5u<tt>ByteString</tt>, breaking referential transparency.
°5u
°5uThis function is also unsafe if you call its finalizer twice, which
°5uwill result in a <i>double free</i> error, or if you pass it a CString
°5unot allocated with <tt>malloc</tt>.
unsafePackMallocCStringLen :: CStringLen -> IO ByteString

-- | <i>O(n)</i> Pack a null-terminated sequence of bytes, pointed to by an
°5uAddr# (an arbitrary machine address assumed to point outside the
°5ugarbage-collected heap) into a <tt>ByteString</tt>. A much faster way
°5uto create an Addr# is with an unboxed string literal, than to pack a
°5uboxed string. A unboxed string literal is compiled to a static
°5u<tt>char []</tt> by GHC. Establishing the length of the string
°5urequires a call to <tt>strlen(3)</tt>, so the Addr# must point to a
°5unull-terminated buffer (as is the case with "string"# literals in
°5uGHC). Use <tt>unsafePackAddressLen</tt> if you know the length of the
°5ustring statically.
°5u
°5uAn example:
°5u
°5u<pre>
°5uliteralFS = unsafePackAddress "literal"#
°5u</pre>
°5u
°5uThis function is <i>unsafe</i>. If you modify the buffer pointed to by
°5uthe original Addr# this modification will be reflected in the
°5uresulting <tt>ByteString</tt>, breaking referential transparency.
°5u
°5uNote this also won't work if your Addr# has embedded '\0' characters
°5uin the string, as <tt>strlen</tt> will return too short a length.
unsafePackAddress :: Addr# -> IO ByteString

-- | <i>O(1)</i> <a>unsafePackAddressLen</a> provides constant-time
°5uconstruction of <a>ByteString</a>s, which is ideal for string
°5uliterals. It packs a sequence of bytes into a <tt>ByteString</tt>,
°5ugiven a raw <a>Addr#</a> to the string, and the length of the string.
°5u
°5uThis function is <i>unsafe</i> in two ways:
°5u
°5u<ul>
°5u<li>the length argument is assumed to be correct. If the length
°5uargument is incorrect, it is possible to overstep the end of the byte
°5uarray.</li>
°5u<li>if the underying Addr# is later modified, this change will be
°5ureflected in resulting <tt>ByteString</tt>, breaking referential
°5utransparency.</li>
°5u</ul>
°5u
°5uIf in doubt, don't use this function.
unsafePackAddressLen :: Int -> Addr# -> IO ByteString

-- | <i>O(1)</i> Construct a <a>ByteString</a> given a Ptr Word8 to a
°5ubuffer, a length, and an IO action representing a finalizer. This
°5ufunction is not available on Hugs.
°5u
°5uThis function is <i>unsafe</i>, it is possible to break referential
°5utransparency by modifying the underlying buffer pointed to by the
°5ufirst argument. Any changes to the original buffer will be reflected
°5uin the resulting <tt>ByteString</tt>.
unsafePackCStringFinalizer :: Ptr Word8 -> Int -> IO () -> IO ByteString

-- | Explicitly run the finaliser associated with a <a>ByteString</a>.
°5uReferences to this value after finalisation may generate invalid
°5umemory references.
°5u
°5uThis function is <i>unsafe</i>, as there may be other
°5u<tt>ByteStrings</tt> referring to the same underlying pages. If you
°5uuse this, you need to have a proof of some kind that all
°5u<a>ByteString</a>s ever generated from the underlying byte array are
°5uno longer live.
unsafeFinalize :: ByteString -> IO ()


-- | A time and space-efficient implementation of byte vectors using packed
°5uWord8 arrays, suitable for high performance use, both in terms of
°5ularge data quantities, or high speed requirements. Byte vectors are
°5uencoded as strict <a>Word8</a> arrays of bytes, held in a
°5u<a>ForeignPtr</a>, and can be passed between C and Haskell with little
°5ueffort.
°5u
°5uThe recomended way to assemble ByteStrings from smaller parts is to
°5uuse the builder monoid from <a>Data.ByteString.Builder</a>.
°5u
°5uThis module is intended to be imported <tt>qualified</tt>, to avoid
°5uname clashes with <a>Prelude</a> functions. eg.
°5u
°5u<pre>
°5uimport qualified Data.ByteString as B
°5u</pre>
°5u
°5uOriginal GHC implementation by Bryan O'Sullivan. Rewritten to use
°5u<a>UArray</a> by Simon Marlow. Rewritten to support slices and use
°5u<a>ForeignPtr</a> by David Roundy. Rewritten again and extended by Don
°5uStewart and Duncan Coutts.
module Data.ByteString

-- | A space-efficient representation of a <a>Word8</a> vector, supporting
°5umany efficient operations.
°5u
°5uA <a>ByteString</a> contains 8-bit bytes, or by using the operations
°5ufrom <a>Data.ByteString.Char8</a> it can be interpreted as containing
°5u8-bit characters.
data ByteString

-- | <i>O(1)</i> The empty <a>ByteString</a>
empty :: ByteString

-- | <i>O(1)</i> Convert a <a>Word8</a> into a <a>ByteString</a>
singleton :: Word8 -> ByteString

-- | <i>O(n)</i> Convert a <tt>[<a>Word8</a>]</tt> into a
°5u<a>ByteString</a>.
°5u
°5uFor applications with large numbers of string literals, pack can be a
°5ubottleneck. In such cases, consider using packAddress (GHC only).
pack :: [Word8] -> ByteString

-- | <i>O(n)</i> Converts a <a>ByteString</a> to a <tt>[<a>Word8</a>]</tt>.
unpack :: ByteString -> [Word8]

-- | <i>O(n)</i> <a>cons</a> is analogous to (:) for lists, but of
°5udifferent complexity, as it requires making a copy.
cons :: Word8 -> ByteString -> ByteString
infixr 5 `cons`

-- | <i>O(n)</i> Append a byte to the end of a <a>ByteString</a>
snoc :: ByteString -> Word8 -> ByteString
infixl 5 `snoc`

-- | <i>O(n)</i> Append two ByteStrings
append :: ByteString -> ByteString -> ByteString

-- | <i>O(1)</i> Extract the first element of a ByteString, which must be
°5unon-empty. An exception will be thrown in the case of an empty
°5uByteString.
head :: ByteString -> Word8

-- | <i>O(1)</i> Extract the head and tail of a ByteString, returning
°5uNothing if it is empty.
uncons :: ByteString -> Maybe (Word8, ByteString)

-- | <i>O(1)</i> Extract the <a>init</a> and <a>last</a> of a ByteString,
°5ureturning Nothing if it is empty.
unsnoc :: ByteString -> Maybe (ByteString, Word8)

-- | <i>O(1)</i> Extract the last element of a ByteString, which must be
°5ufinite and non-empty. An exception will be thrown in the case of an
°5uempty ByteString.
last :: ByteString -> Word8

-- | <i>O(1)</i> Extract the elements after the head of a ByteString, which
°5umust be non-empty. An exception will be thrown in the case of an empty
°5uByteString.
tail :: ByteString -> ByteString

-- | <i>O(1)</i> Return all the elements of a <a>ByteString</a> except the
°5ulast one. An exception will be thrown in the case of an empty
°5uByteString.
init :: ByteString -> ByteString

-- | <i>O(1)</i> Test whether a ByteString is empty.
null :: ByteString -> Bool

-- | <i>O(1)</i> <a>length</a> returns the length of a ByteString as an
°5u<a>Int</a>.
length :: ByteString -> Int

-- | <i>O(n)</i> <a>map</a> <tt>f xs</tt> is the ByteString obtained by
°5uapplying <tt>f</tt> to each element of <tt>xs</tt>.
map :: (Word8 -> Word8) -> ByteString -> ByteString

-- | <i>O(n)</i> <a>reverse</a> <tt>xs</tt> efficiently returns the
°5uelements of <tt>xs</tt> in reverse order.
reverse :: ByteString -> ByteString

-- | <i>O(n)</i> The <a>intersperse</a> function takes a <a>Word8</a> and a
°5u<a>ByteString</a> and `intersperses' that byte between the elements of
°5uthe <a>ByteString</a>. It is analogous to the intersperse function on
°5uLists.
intersperse :: Word8 -> ByteString -> ByteString

-- | <i>O(n)</i> The <a>intercalate</a> function takes a <a>ByteString</a>
°5uand a list of <a>ByteString</a>s and concatenates the list after
°5uinterspersing the first argument between each element of the list.
intercalate :: ByteString -> [ByteString] -> ByteString

-- | The <a>transpose</a> function transposes the rows and columns of its
°5u<a>ByteString</a> argument.
transpose :: [ByteString] -> [ByteString]

-- | <a>foldl</a>, applied to a binary operator, a starting value
°5u(typically the left-identity of the operator), and a ByteString,
°5ureduces the ByteString using the binary operator, from left to right.
foldl :: (a -> Word8 -> a) -> a -> ByteString -> a

-- | <a>foldl'</a> is like <a>foldl</a>, but strict in the accumulator.
foldl' :: (a -> Word8 -> a) -> a -> ByteString -> a

-- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value
°5uargument, and thus must be applied to non-empty <tt>ByteStrings</tt>.
°5uAn exception will be thrown in the case of an empty ByteString.
foldl1 :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8

-- | 'foldl1\'' is like <a>foldl1</a>, but strict in the accumulator. An
°5uexception will be thrown in the case of an empty ByteString.
foldl1' :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8

-- | <a>foldr</a>, applied to a binary operator, a starting value
°5u(typically the right-identity of the operator), and a ByteString,
°5ureduces the ByteString using the binary operator, from right to left.
foldr :: (Word8 -> a -> a) -> a -> ByteString -> a

-- | <a>foldr'</a> is like <a>foldr</a>, but strict in the accumulator.
foldr' :: (Word8 -> a -> a) -> a -> ByteString -> a

-- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value
°5uargument, and thus must be applied to non-empty <a>ByteString</a>s An
°5uexception will be thrown in the case of an empty ByteString.
foldr1 :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8

-- | 'foldr1\'' is a variant of <a>foldr1</a>, but is strict in the
°5uaccumulator.
foldr1' :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8

-- | <i>O(n)</i> Concatenate a list of ByteStrings.
concat :: [ByteString] -> ByteString

-- | Map a function over a <a>ByteString</a> and concatenate the results
concatMap :: (Word8 -> ByteString) -> ByteString -> ByteString

-- | <i>O(n)</i> Applied to a predicate and a ByteString, <a>any</a>
°5udetermines if any element of the <a>ByteString</a> satisfies the
°5upredicate.
any :: (Word8 -> Bool) -> ByteString -> Bool

-- | <i>O(n)</i> Applied to a predicate and a <a>ByteString</a>, <a>all</a>
°5udetermines if all elements of the <a>ByteString</a> satisfy the
°5upredicate.
all :: (Word8 -> Bool) -> ByteString -> Bool

-- | <i>O(n)</i> <a>maximum</a> returns the maximum value from a
°5u<a>ByteString</a> This function will fuse. An exception will be thrown
°5uin the case of an empty ByteString.
maximum :: ByteString -> Word8

-- | <i>O(n)</i> <a>minimum</a> returns the minimum value from a
°5u<a>ByteString</a> This function will fuse. An exception will be thrown
°5uin the case of an empty ByteString.
minimum :: ByteString -> Word8

-- | <a>scanl</a> is similar to <a>foldl</a>, but returns a list of
°5usuccessive reduced values from the left. This function will fuse.
°5u
°5u<pre>
°5uscanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
°5u</pre>
°5u
°5uNote that
°5u
°5u<pre>
°5ulast (scanl f z xs) == foldl f z xs.
°5u</pre>
scanl :: (Word8 -> Word8 -> Word8) -> Word8 -> ByteString -> ByteString

-- | <a>scanl1</a> is a variant of <a>scanl</a> that has no starting value
°5uargument. This function will fuse.
°5u
°5u<pre>
°5uscanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
°5u</pre>
scanl1 :: (Word8 -> Word8 -> Word8) -> ByteString -> ByteString

-- | scanr is the right-to-left dual of scanl.
scanr :: (Word8 -> Word8 -> Word8) -> Word8 -> ByteString -> ByteString

-- | <a>scanr1</a> is a variant of <a>scanr</a> that has no starting value
°5uargument.
scanr1 :: (Word8 -> Word8 -> Word8) -> ByteString -> ByteString

-- | The <a>mapAccumL</a> function behaves like a combination of <a>map</a>
°5uand <a>foldl</a>; it applies a function to each element of a
°5uByteString, passing an accumulating parameter from left to right, and
°5ureturning a final value of this accumulator together with the new
°5ulist.
mapAccumL :: (acc -> Word8 -> (acc, Word8)) -> acc -> ByteString -> (acc, ByteString)

-- | The <a>mapAccumR</a> function behaves like a combination of <a>map</a>
°5uand <a>foldr</a>; it applies a function to each element of a
°5uByteString, passing an accumulating parameter from right to left, and
°5ureturning a final value of this accumulator together with the new
°5uByteString.
mapAccumR :: (acc -> Word8 -> (acc, Word8)) -> acc -> ByteString -> (acc, ByteString)

-- | <i>O(n)</i> <a>replicate</a> <tt>n x</tt> is a ByteString of length
°5u<tt>n</tt> with <tt>x</tt> the value of every element. The following
°5uholds:
°5u
°5u<pre>
°5ureplicate w c = unfoldr w (\u -&gt; Just (u,u)) c
°5u</pre>
°5u
°5uThis implemenation uses <tt>memset(3)</tt>
replicate :: Int -> Word8 -> ByteString

-- | <i>O(n)</i>, where <i>n</i> is the length of the result. The
°5u<a>unfoldr</a> function is analogous to the List 'unfoldr'.
°5u<a>unfoldr</a> builds a ByteString from a seed value. The function
°5utakes the element and returns <a>Nothing</a> if it is done producing
°5uthe ByteString or returns <a>Just</a> <tt>(a,b)</tt>, in which case,
°5u<tt>a</tt> is the next byte in the string, and <tt>b</tt> is the seed
°5uvalue for further production.
°5u
°5uExamples:
°5u
°5u<pre>
°5u   unfoldr (\x -&gt; if x &lt;= 5 then Just (x, x + 1) else Nothing) 0
°5u== pack [0, 1, 2, 3, 4, 5]
°5u</pre>
unfoldr :: (a -> Maybe (Word8, a)) -> a -> ByteString

-- | <i>O(n)</i> Like <a>unfoldr</a>, <a>unfoldrN</a> builds a ByteString
°5ufrom a seed value. However, the length of the result is limited by the
°5ufirst argument to <a>unfoldrN</a>. This function is more efficient
°5uthan <a>unfoldr</a> when the maximum length of the result is known.
°5u
°5uThe following equation relates <a>unfoldrN</a> and <a>unfoldr</a>:
°5u
°5u<pre>
°5ufst (unfoldrN n f s) == take n (unfoldr f s)
°5u</pre>
unfoldrN :: Int -> (a -> Maybe (Word8, a)) -> a -> (ByteString, Maybe a)

-- | <i>O(1)</i> <a>take</a> <tt>n</tt>, applied to a ByteString
°5u<tt>xs</tt>, returns the prefix of <tt>xs</tt> of length <tt>n</tt>,
°5uor <tt>xs</tt> itself if <tt>n &gt; <a>length</a> xs</tt>.
take :: Int -> ByteString -> ByteString

-- | <i>O(1)</i> <a>drop</a> <tt>n xs</tt> returns the suffix of
°5u<tt>xs</tt> after the first <tt>n</tt> elements, or <tt>[]</tt> if
°5u<tt>n &gt; <a>length</a> xs</tt>.
drop :: Int -> ByteString -> ByteString

-- | <i>O(1)</i> <a>splitAt</a> <tt>n xs</tt> is equivalent to
°5u<tt>(<a>take</a> n xs, <a>drop</a> n xs)</tt>.
splitAt :: Int -> ByteString -> (ByteString, ByteString)

-- | <a>takeWhile</a>, applied to a predicate <tt>p</tt> and a ByteString
°5u<tt>xs</tt>, returns the longest prefix (possibly empty) of
°5u<tt>xs</tt> of elements that satisfy <tt>p</tt>.
takeWhile :: (Word8 -> Bool) -> ByteString -> ByteString

-- | <a>dropWhile</a> <tt>p xs</tt> returns the suffix remaining after
°5u<a>takeWhile</a> <tt>p xs</tt>.
dropWhile :: (Word8 -> Bool) -> ByteString -> ByteString

-- | <a>span</a> <tt>p xs</tt> breaks the ByteString into two segments. It
°5uis equivalent to <tt>(<a>takeWhile</a> p xs, <a>dropWhile</a> p
°5uxs)</tt>
span :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | <a>spanEnd</a> behaves like <a>span</a> but from the end of the
°5u<a>ByteString</a>. We have
°5u
°5u<pre>
°5uspanEnd (not.isSpace) "x y z" == ("x y ","z")
°5u</pre>
°5u
°5uand
°5u
°5u<pre>
°5uspanEnd (not . isSpace) ps
°5u   ==
°5ulet (x,y) = span (not.isSpace) (reverse ps) in (reverse y, reverse x)
°5u</pre>
spanEnd :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (<a>not</a> .
°5up)</tt>.
°5u
°5uUnder GHC, a rewrite rule will transform break (==) into a call to the
°5uspecialised breakByte:
°5u
°5u<pre>
°5ubreak ((==) x) = breakByte x
°5ubreak (==x) = breakByte x
°5u</pre>
break :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | <a>breakEnd</a> behaves like <a>break</a> but from the end of the
°5u<a>ByteString</a>
°5u
°5ubreakEnd p == spanEnd (not.p)
breakEnd :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | The <a>group</a> function takes a ByteString and returns a list of
°5uByteStrings such that the concatenation of the result is equal to the
°5uargument. Moreover, each sublist in the result contains only equal
°5uelements. For example,
°5u
°5u<pre>
°5ugroup "Mississippi" = ["M","i","ss","i","ss","i","pp","i"]
°5u</pre>
°5u
°5uIt is a special case of <a>groupBy</a>, which allows the programmer to
°5usupply their own equality test. It is about 40% faster than <i>groupBy
°5u(==)</i>
group :: ByteString -> [ByteString]

-- | The <a>groupBy</a> function is the non-overloaded version of
°5u<a>group</a>.
groupBy :: (Word8 -> Word8 -> Bool) -> ByteString -> [ByteString]

-- | <i>O(n)</i> Return all initial segments of the given
°5u<a>ByteString</a>, shortest first.
inits :: ByteString -> [ByteString]

-- | <i>O(n)</i> Return all final segments of the given <a>ByteString</a>,
°5ulongest first.
tails :: ByteString -> [ByteString]

-- | <i>O(n)</i> The <a>stripPrefix</a> function takes two ByteStrings and
°5ureturns <a>Just</a> the remainder of the second iff the first is its
°5uprefix, and otherwise <a>Nothing</a>.
stripPrefix :: ByteString -> ByteString -> Maybe ByteString

-- | <i>O(n)</i> The <a>stripSuffix</a> function takes two ByteStrings and
°5ureturns <a>Just</a> the remainder of the second iff the first is its
°5usuffix, and otherwise <a>Nothing</a>.
stripSuffix :: ByteString -> ByteString -> Maybe ByteString

-- | <i>O(n)</i> Break a <a>ByteString</a> into pieces separated by the
°5ubyte argument, consuming the delimiter. I.e.
°5u
°5u<pre>
°5usplit '\n' "a\nb\nd\ne" == ["a","b","d","e"]
°5usplit 'a'  "aXaXaXa"    == ["","X","X","X",""]
°5usplit 'x'  "x"          == ["",""]
°5u</pre>
°5u
°5uand
°5u
°5u<pre>
°5uintercalate [c] . split c == id
°5usplit == splitWith . (==)
°5u</pre>
°5u
°5uAs for all splitting functions in this library, this function does not
°5ucopy the substrings, it just constructs new <tt>ByteStrings</tt> that
°5uare slices of the original.
split :: Word8 -> ByteString -> [ByteString]

-- | <i>O(n)</i> Splits a <a>ByteString</a> into components delimited by
°5useparators, where the predicate returns True for a separator element.
°5uThe resulting components do not contain the separators. Two adjacent
°5useparators result in an empty component in the output. eg.
°5u
°5u<pre>
°5usplitWith (=='a') "aabbaca" == ["","","bb","c",""]
°5usplitWith (=='a') []        == []
°5u</pre>
splitWith :: (Word8 -> Bool) -> ByteString -> [ByteString]

-- | <i>O(n)</i> The <a>isPrefixOf</a> function takes two ByteStrings and
°5ureturns <a>True</a> if the first is a prefix of the second.
isPrefixOf :: ByteString -> ByteString -> Bool

-- | <i>O(n)</i> The <a>isSuffixOf</a> function takes two ByteStrings and
°5ureturns <a>True</a> iff the first is a suffix of the second.
°5u
°5uThe following holds:
°5u
°5u<pre>
°5uisSuffixOf x y == reverse x `isPrefixOf` reverse y
°5u</pre>
°5u
°5uHowever, the real implemenation uses memcmp to compare the end of the
°5ustring only, with no reverse required..
isSuffixOf :: ByteString -> ByteString -> Bool

-- | Check whether one string is a substring of another. <tt>isInfixOf p
°5us</tt> is equivalent to <tt>not (null (findSubstrings p s))</tt>.
isInfixOf :: ByteString -> ByteString -> Bool

-- | Break a string on a substring, returning a pair of the part of the
°5ustring prior to the match, and the rest of the string.
°5u
°5uThe following relationships hold:
°5u
°5u<pre>
°5ubreak (== c) l == breakSubstring (singleton c) l
°5u</pre>
°5u
°5uand:
°5u
°5u<pre>
°5ufindSubstring s l ==
°5u   if null s then Just 0
°5u             else case breakSubstring s l of
°5u                      (x,y) | null y    -&gt; Nothing
°5u                            | otherwise -&gt; Just (length x)
°5u</pre>
°5u
°5uFor example, to tokenise a string, dropping delimiters:
°5u
°5u<pre>
°5utokenise x y = h : if null t then [] else tokenise x (drop (length x) t)
°5u    where (h,t) = breakSubstring x y
°5u</pre>
°5u
°5uTo skip to the first occurence of a string:
°5u
°5u<pre>
°5usnd (breakSubstring x y)
°5u</pre>
°5u
°5uTo take the parts of a string before a delimiter:
°5u
°5u<pre>
°5ufst (breakSubstring x y)
°5u</pre>
°5u
°5uNote that calling `breakSubstring x` does some preprocessing work, so
°5uyou should avoid unnecessarily duplicating breakSubstring calls with
°5uthe same pattern.
breakSubstring :: ByteString -> ByteString -> (ByteString, ByteString)

-- | Get the first index of a substring in another string, or
°5u<a>Nothing</a> if the string is not found. <tt>findSubstring p s</tt>
°5uis equivalent to <tt>listToMaybe (findSubstrings p s)</tt>.

-- | <i>Deprecated: findSubstring is deprecated in favour of
°5ubreakSubstring.</i>
findSubstring :: ByteString -> ByteString -> Maybe Int

-- | Find the indexes of all (possibly overlapping) occurances of a
°5usubstring in a string.

-- | <i>Deprecated: findSubstrings is deprecated in favour of
°5ubreakSubstring.</i>
findSubstrings :: ByteString -> ByteString -> [Int]

-- | <i>O(n)</i> <a>elem</a> is the <a>ByteString</a> membership predicate.
elem :: Word8 -> ByteString -> Bool

-- | <i>O(n)</i> <a>notElem</a> is the inverse of <a>elem</a>
notElem :: Word8 -> ByteString -> Bool

-- | <i>O(n)</i> The <a>find</a> function takes a predicate and a
°5uByteString, and returns the first element in matching the predicate,
°5uor <a>Nothing</a> if there is no such element.
°5u
°5u<pre>
°5ufind f p = case findIndex f p of Just n -&gt; Just (p ! n) ; _ -&gt; Nothing
°5u</pre>
find :: (Word8 -> Bool) -> ByteString -> Maybe Word8

-- | <i>O(n)</i> <a>filter</a>, applied to a predicate and a ByteString,
°5ureturns a ByteString containing those characters that satisfy the
°5upredicate.
filter :: (Word8 -> Bool) -> ByteString -> ByteString

-- | <i>O(n)</i> The <a>partition</a> function takes a predicate a
°5uByteString and returns the pair of ByteStrings with elements which do
°5uand do not satisfy the predicate, respectively; i.e.,
°5u
°5u<pre>
°5upartition p bs == (filter p xs, filter (not . p) xs)
°5u</pre>
partition :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | <i>O(1)</i> <a>ByteString</a> index (subscript) operator, starting
°5ufrom 0.
index :: ByteString -> Int -> Word8

-- | <i>O(n)</i> The <a>elemIndex</a> function returns the index of the
°5ufirst element in the given <a>ByteString</a> which is equal to the
°5uquery element, or <a>Nothing</a> if there is no such element. This
°5uimplementation uses memchr(3).
elemIndex :: Word8 -> ByteString -> Maybe Int

-- | <i>O(n)</i> The <a>elemIndices</a> function extends <a>elemIndex</a>,
°5uby returning the indices of all elements equal to the query element,
°5uin ascending order. This implementation uses memchr(3).
elemIndices :: Word8 -> ByteString -> [Int]

-- | <i>O(n)</i> The <a>elemIndexEnd</a> function returns the last index of
°5uthe element in the given <a>ByteString</a> which is equal to the query
°5uelement, or <a>Nothing</a> if there is no such element. The following
°5uholds:
°5u
°5u<pre>
°5uelemIndexEnd c xs ==
°5u(-) (length xs - 1) `fmap` elemIndex c (reverse xs)
°5u</pre>
elemIndexEnd :: Word8 -> ByteString -> Maybe Int

-- | The <a>findIndex</a> function takes a predicate and a
°5u<a>ByteString</a> and returns the index of the first element in the
°5uByteString satisfying the predicate.
findIndex :: (Word8 -> Bool) -> ByteString -> Maybe Int

-- | The <a>findIndices</a> function extends <a>findIndex</a>, by returning
°5uthe indices of all elements satisfying the predicate, in ascending
°5uorder.
findIndices :: (Word8 -> Bool) -> ByteString -> [Int]

-- | count returns the number of times its argument appears in the
°5uByteString
°5u
°5u<pre>
°5ucount = length . elemIndices
°5u</pre>
°5u
°5uBut more efficiently than using length on the intermediate list.
count :: Word8 -> ByteString -> Int

-- | <i>O(n)</i> <a>zip</a> takes two ByteStrings and returns a list of
°5ucorresponding pairs of bytes. If one input ByteString is short, excess
°5uelements of the longer ByteString are discarded. This is equivalent to
°5ua pair of <a>unpack</a> operations.
zip :: ByteString -> ByteString -> [(Word8, Word8)]

-- | <a>zipWith</a> generalises <a>zip</a> by zipping with the function
°5ugiven as the first argument, instead of a tupling function. For
°5uexample, <tt><a>zipWith</a> (+)</tt> is applied to two ByteStrings to
°5uproduce the list of corresponding sums.
zipWith :: (Word8 -> Word8 -> a) -> ByteString -> ByteString -> [a]

-- | <i>O(n)</i> <a>unzip</a> transforms a list of pairs of bytes into a
°5upair of ByteStrings. Note that this performs two <a>pack</a>
°5uoperations.
unzip :: [(Word8, Word8)] -> (ByteString, ByteString)

-- | <i>O(n)</i> Sort a ByteString efficiently, using counting sort.
sort :: ByteString -> ByteString

-- | <i>O(n)</i> Make a copy of the <a>ByteString</a> with its own storage.
°5uThis is mainly useful to allow the rest of the data pointed to by the
°5u<a>ByteString</a> to be garbage collected, for example if a large
°5ustring has been read in, and only a small part of it is needed in the
°5urest of the program.
copy :: ByteString -> ByteString

-- | <i>O(n).</i> Construct a new <tt>ByteString</tt> from a
°5u<tt>CString</tt>. The resulting <tt>ByteString</tt> is an immutable
°5ucopy of the original <tt>CString</tt>, and is managed on the Haskell
°5uheap. The original <tt>CString</tt> must be null terminated.
packCString :: CString -> IO ByteString

-- | <i>O(n).</i> Construct a new <tt>ByteString</tt> from a
°5u<tt>CStringLen</tt>. The resulting <tt>ByteString</tt> is an immutable
°5ucopy of the original <tt>CStringLen</tt>. The <tt>ByteString</tt> is a
°5unormal Haskell value and will be managed on the Haskell heap.
packCStringLen :: CStringLen -> IO ByteString

-- | <i>O(n) construction</i> Use a <tt>ByteString</tt> with a function
°5urequiring a null-terminated <tt>CString</tt>. The <tt>CString</tt> is
°5ua copy and will be freed automatically; it must not be stored or used
°5uafter the subcomputation finishes.
useAsCString :: ByteString -> (CString -> IO a) -> IO a

-- | <i>O(n) construction</i> Use a <tt>ByteString</tt> with a function
°5urequiring a <tt>CStringLen</tt>. As for <tt>useAsCString</tt> this
°5ufunction makes a copy of the original <tt>ByteString</tt>. It must not
°5ube stored or used after the subcomputation finishes.
useAsCStringLen :: ByteString -> (CStringLen -> IO a) -> IO a

-- | Read a line from stdin.
getLine :: IO ByteString

-- | getContents. Read stdin strictly. Equivalent to hGetContents stdin The
°5u<a>Handle</a> is closed after the contents have been read.
getContents :: IO ByteString

-- | Write a ByteString to stdout
putStr :: ByteString -> IO ()

-- | Write a ByteString to stdout, appending a newline byte

-- | <i>Deprecated: Use Data.ByteString.Char8.putStrLn instead. (Functions
°5uthat rely on ASCII encodings belong in Data.ByteString.Char8)</i>
putStrLn :: ByteString -> IO ()

-- | The interact function takes a function of type <tt>ByteString -&gt;
°5uByteString</tt> as its argument. The entire input from the standard
°5uinput device is passed to this function as its argument, and the
°5uresulting string is output on the standard output device.
interact :: (ByteString -> ByteString) -> IO ()

-- | Read an entire file strictly into a <a>ByteString</a>.
readFile :: FilePath -> IO ByteString

-- | Write a <a>ByteString</a> to a file.
writeFile :: FilePath -> ByteString -> IO ()

-- | Append a <a>ByteString</a> to a file.
appendFile :: FilePath -> ByteString -> IO ()

-- | Read a line from a handle
hGetLine :: Handle -> IO ByteString

-- | Read a handle's entire contents strictly into a <a>ByteString</a>.
°5u
°5uThis function reads chunks at a time, increasing the chunk size on
°5ueach read. The final string is then realloced to the appropriate size.
°5uFor files &gt; half of available memory, this may lead to memory
°5uexhaustion. Consider using <a>readFile</a> in this case.
°5u
°5uThe Handle is closed once the contents have been read, or if an
°5uexception is thrown.
hGetContents :: Handle -> IO ByteString

-- | Read a <a>ByteString</a> directly from the specified <a>Handle</a>.
°5uThis is far more efficient than reading the characters into a
°5u<a>String</a> and then using <a>pack</a>. First argument is the Handle
°5uto read from, and the second is the number of bytes to read. It
°5ureturns the bytes read, up to n, or <a>empty</a> if EOF has been
°5ureached.
°5u
°5u<a>hGet</a> is implemented in terms of <a>hGetBuf</a>.
°5u
°5uIf the handle is a pipe or socket, and the writing end is closed,
°5u<a>hGet</a> will behave as if EOF was reached.
hGet :: Handle -> Int -> IO ByteString

-- | Like <a>hGet</a>, except that a shorter <a>ByteString</a> may be
°5ureturned if there are not enough bytes immediately available to
°5usatisfy the whole request. <a>hGetSome</a> only blocks if there is no
°5udata available, and EOF has not yet been reached.
hGetSome :: Handle -> Int -> IO ByteString

-- | hGetNonBlocking is similar to <a>hGet</a>, except that it will never
°5ublock waiting for data to become available, instead it returns only
°5uwhatever data is available. If there is no data available to be read,
°5u<a>hGetNonBlocking</a> returns <a>empty</a>.
°5u
°5uNote: on Windows and with Haskell implementation other than GHC, this
°5ufunction does not work correctly; it behaves identically to
°5u<a>hGet</a>.
hGetNonBlocking :: Handle -> Int -> IO ByteString

-- | Outputs a <a>ByteString</a> to the specified <a>Handle</a>.
hPut :: Handle -> ByteString -> IO ()

-- | Similar to <a>hPut</a> except that it will never block. Instead it
°5ureturns any tail that did not get written. This tail may be
°5u<a>empty</a> in the case that the whole string was written, or the
°5uwhole original string if nothing was written. Partial writes are also
°5upossible.
°5u
°5uNote: on Windows and with Haskell implementation other than GHC, this
°5ufunction does not work correctly; it behaves identically to
°5u<a>hPut</a>.
hPutNonBlocking :: Handle -> ByteString -> IO ByteString

-- | A synonym for <tt>hPut</tt>, for compatibility
hPutStr :: Handle -> ByteString -> IO ()

-- | Write a ByteString to a handle, appending a newline byte

-- | <i>Deprecated: Use Data.ByteString.Char8.hPutStrLn instead. (Functions
°5uthat rely on ASCII encodings belong in Data.ByteString.Char8)</i>
hPutStrLn :: Handle -> ByteString -> IO ()

-- | <a>breakByte</a> breaks its ByteString argument at the first occurence
°5uof the specified byte. It is more efficient than <a>break</a> as it is
°5uimplemented with <tt>memchr(3)</tt>. I.e.
°5u
°5u<pre>
°5ubreak (=='c') "abcd" == breakByte 'c' "abcd"
°5u</pre>

-- | <i>Deprecated: It is an internal function and should never have been
°5uexported. Use 'break (== x)' instead. (There are rewrite rules that
°5uhandle this special case of <a>break</a>.)</i>
breakByte :: Word8 -> ByteString -> (ByteString, ByteString)


-- | A time and space-efficient implementation of lazy byte vectors using
°5ulists of packed <a>Word8</a> arrays, suitable for high performance
°5uuse, both in terms of large data quantities, or high speed
°5urequirements. Lazy ByteStrings are encoded as lazy lists of strict
°5uchunks of bytes.
°5u
°5uA key feature of lazy ByteStrings is the means to manipulate large or
°5uunbounded streams of data without requiring the entire sequence to be
°5uresident in memory. To take advantage of this you have to write your
°5ufunctions in a lazy streaming style, e.g. classic pipeline
°5ucomposition. The default I/O chunk size is 32k, which should be good
°5uin most circumstances.
°5u
°5uSome operations, such as <a>concat</a>, <a>append</a>, <a>reverse</a>
°5uand <a>cons</a>, have better complexity than their
°5u<a>Data.ByteString</a> equivalents, due to optimisations resulting
°5ufrom the list spine structure. For other operations lazy ByteStrings
°5uare usually within a few percent of strict ones.
°5u
°5uThe recomended way to assemble lazy ByteStrings from smaller parts is
°5uto use the builder monoid from <a>Data.ByteString.Builder</a>.
°5u
°5uThis module is intended to be imported <tt>qualified</tt>, to avoid
°5uname clashes with <a>Prelude</a> functions. eg.
°5u
°5u<pre>
°5uimport qualified Data.ByteString.Lazy as B
°5u</pre>
°5u
°5uOriginal GHC implementation by Bryan O'Sullivan. Rewritten to use
°5u<a>UArray</a> by Simon Marlow. Rewritten to support slices and use
°5u<a>ForeignPtr</a> by David Roundy. Rewritten again and extended by Don
°5uStewart and Duncan Coutts. Lazy variant by Duncan Coutts and Don
°5uStewart.
module Data.ByteString.Lazy

-- | A space-efficient representation of a <a>Word8</a> vector, supporting
°5umany efficient operations.
°5u
°5uA lazy <a>ByteString</a> contains 8-bit bytes, or by using the
°5uoperations from <a>Data.ByteString.Lazy.Char8</a> it can be
°5uinterpreted as containing 8-bit characters.
data ByteString

-- | <i>O(1)</i> The empty <a>ByteString</a>
empty :: ByteString

-- | <i>O(1)</i> Convert a <a>Word8</a> into a <a>ByteString</a>
singleton :: Word8 -> ByteString

-- | <i>O(n)</i> Convert a '[Word8]' into a <a>ByteString</a>.
pack :: [Word8] -> ByteString

-- | <i>O(n)</i> Converts a <a>ByteString</a> to a '[Word8]'.
unpack :: ByteString -> [Word8]

-- | <i>O(1)</i> Convert a strict <a>ByteString</a> into a lazy
°5u<a>ByteString</a>.
fromStrict :: ByteString -> ByteString

-- | <i>O(n)</i> Convert a lazy <a>ByteString</a> into a strict
°5u<a>ByteString</a>.
°5u
°5uNote that this is an <i>expensive</i> operation that forces the whole
°5ulazy ByteString into memory and then copies all the data. If possible,
°5utry to avoid converting back and forth between strict and lazy
°5ubytestrings.
toStrict :: ByteString -> ByteString

-- | <i>O(c)</i> Convert a list of strict <a>ByteString</a> into a lazy
°5u<a>ByteString</a>
fromChunks :: [ByteString] -> ByteString

-- | <i>O(c)</i> Convert a lazy <a>ByteString</a> into a list of strict
°5u<a>ByteString</a>
toChunks :: ByteString -> [ByteString]

-- | Consume the chunks of a lazy ByteString with a natural right fold.
foldrChunks :: (ByteString -> a -> a) -> a -> ByteString -> a

-- | Consume the chunks of a lazy ByteString with a strict, tail-recursive,
°5uaccumulating left fold.
foldlChunks :: (a -> ByteString -> a) -> a -> ByteString -> a

-- | <i>O(1)</i> <a>cons</a> is analogous to '(:)' for lists.
cons :: Word8 -> ByteString -> ByteString
infixr 5 `cons`

-- | <i>O(1)</i> Unlike <a>cons</a>, 'cons\'' is strict in the ByteString
°5uthat we are consing onto. More precisely, it forces the head and the
°5ufirst chunk. It does this because, for space efficiency, it may
°5ucoalesce the new byte onto the first 'chunk' rather than starting a
°5unew 'chunk'.
°5u
°5uSo that means you can't use a lazy recursive contruction like this:
°5u
°5u<pre>
°5ulet xs = cons\' c xs in xs
°5u</pre>
°5u
°5uYou can however use <a>cons</a>, as well as <a>repeat</a> and
°5u<a>cycle</a>, to build infinite lazy ByteStrings.
cons' :: Word8 -> ByteString -> ByteString
infixr 5 `cons'`

-- | <i>O(n/c)</i> Append a byte to the end of a <a>ByteString</a>
snoc :: ByteString -> Word8 -> ByteString
infixl 5 `snoc`

-- | <i>O(n/c)</i> Append two ByteStrings
append :: ByteString -> ByteString -> ByteString

-- | <i>O(1)</i> Extract the first element of a ByteString, which must be
°5unon-empty.
head :: ByteString -> Word8

-- | <i>O(1)</i> Extract the head and tail of a ByteString, returning
°5uNothing if it is empty.
uncons :: ByteString -> Maybe (Word8, ByteString)

-- | <i>O(n/c)</i> Extract the <a>init</a> and <a>last</a> of a ByteString,
°5ureturning Nothing if it is empty.
°5u
°5u<ul>
°5u<li>It is no faster than using <a>init</a> and <a>last</a></li>
°5u</ul>
unsnoc :: ByteString -> Maybe (ByteString, Word8)

-- | <i>O(n/c)</i> Extract the last element of a ByteString, which must be
°5ufinite and non-empty.
last :: ByteString -> Word8

-- | <i>O(1)</i> Extract the elements after the head of a ByteString, which
°5umust be non-empty.
tail :: ByteString -> ByteString

-- | <i>O(n/c)</i> Return all the elements of a <a>ByteString</a> except
°5uthe last one.
init :: ByteString -> ByteString

-- | <i>O(1)</i> Test whether a ByteString is empty.
null :: ByteString -> Bool

-- | <i>O(n/c)</i> <a>length</a> returns the length of a ByteString as an
°5u<a>Int64</a>
length :: ByteString -> Int64

-- | <i>O(n)</i> <a>map</a> <tt>f xs</tt> is the ByteString obtained by
°5uapplying <tt>f</tt> to each element of <tt>xs</tt>.
map :: (Word8 -> Word8) -> ByteString -> ByteString

-- | <i>O(n)</i> <a>reverse</a> <tt>xs</tt> returns the elements of
°5u<tt>xs</tt> in reverse order.
reverse :: ByteString -> ByteString

-- | The <a>intersperse</a> function takes a <a>Word8</a> and a
°5u<a>ByteString</a> and `intersperses' that byte between the elements of
°5uthe <a>ByteString</a>. It is analogous to the intersperse function on
°5uLists.
intersperse :: Word8 -> ByteString -> ByteString

-- | <i>O(n)</i> The <a>intercalate</a> function takes a <a>ByteString</a>
°5uand a list of <a>ByteString</a>s and concatenates the list after
°5uinterspersing the first argument between each element of the list.
intercalate :: ByteString -> [ByteString] -> ByteString

-- | The <a>transpose</a> function transposes the rows and columns of its
°5u<a>ByteString</a> argument.
transpose :: [ByteString] -> [ByteString]

-- | <a>foldl</a>, applied to a binary operator, a starting value
°5u(typically the left-identity of the operator), and a ByteString,
°5ureduces the ByteString using the binary operator, from left to right.
foldl :: (a -> Word8 -> a) -> a -> ByteString -> a

-- | 'foldl\'' is like <a>foldl</a>, but strict in the accumulator.
foldl' :: (a -> Word8 -> a) -> a -> ByteString -> a

-- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value
°5uargument, and thus must be applied to non-empty <tt>ByteStrings</tt>.
foldl1 :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8

-- | 'foldl1\'' is like <a>foldl1</a>, but strict in the accumulator.
foldl1' :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8

-- | <a>foldr</a>, applied to a binary operator, a starting value
°5u(typically the right-identity of the operator), and a ByteString,
°5ureduces the ByteString using the binary operator, from right to left.
foldr :: (Word8 -> a -> a) -> a -> ByteString -> a

-- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value
°5uargument, and thus must be applied to non-empty <a>ByteString</a>s
foldr1 :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8

-- | <i>O(n)</i> Concatenate a list of ByteStrings.
concat :: [ByteString] -> ByteString

-- | Map a function over a <a>ByteString</a> and concatenate the results
concatMap :: (Word8 -> ByteString) -> ByteString -> ByteString

-- | <i>O(n)</i> Applied to a predicate and a ByteString, <a>any</a>
°5udetermines if any element of the <a>ByteString</a> satisfies the
°5upredicate.
any :: (Word8 -> Bool) -> ByteString -> Bool

-- | <i>O(n)</i> Applied to a predicate and a <a>ByteString</a>, <a>all</a>
°5udetermines if all elements of the <a>ByteString</a> satisfy the
°5upredicate.
all :: (Word8 -> Bool) -> ByteString -> Bool

-- | <i>O(n)</i> <a>maximum</a> returns the maximum value from a
°5u<a>ByteString</a>
maximum :: ByteString -> Word8

-- | <i>O(n)</i> <a>minimum</a> returns the minimum value from a
°5u<a>ByteString</a>
minimum :: ByteString -> Word8

-- | <a>scanl</a> is similar to <a>foldl</a>, but returns a list of
°5usuccessive reduced values from the left. This function will fuse.
°5u
°5u<pre>
°5uscanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
°5u</pre>
°5u
°5uNote that
°5u
°5u<pre>
°5ulast (scanl f z xs) == foldl f z xs.
°5u</pre>
scanl :: (Word8 -> Word8 -> Word8) -> Word8 -> ByteString -> ByteString

-- | The <a>mapAccumL</a> function behaves like a combination of <a>map</a>
°5uand <a>foldl</a>; it applies a function to each element of a
°5uByteString, passing an accumulating parameter from left to right, and
°5ureturning a final value of this accumulator together with the new
°5uByteString.
mapAccumL :: (acc -> Word8 -> (acc, Word8)) -> acc -> ByteString -> (acc, ByteString)

-- | The <a>mapAccumR</a> function behaves like a combination of <a>map</a>
°5uand <a>foldr</a>; it applies a function to each element of a
°5uByteString, passing an accumulating parameter from right to left, and
°5ureturning a final value of this accumulator together with the new
°5uByteString.
mapAccumR :: (acc -> Word8 -> (acc, Word8)) -> acc -> ByteString -> (acc, ByteString)

-- | <tt><a>repeat</a> x</tt> is an infinite ByteString, with <tt>x</tt>
°5uthe value of every element.
repeat :: Word8 -> ByteString

-- | <i>O(n)</i> <tt><a>replicate</a> n x</tt> is a ByteString of length
°5u<tt>n</tt> with <tt>x</tt> the value of every element.
replicate :: Int64 -> Word8 -> ByteString

-- | <a>cycle</a> ties a finite ByteString into a circular one, or
°5uequivalently, the infinite repetition of the original ByteString.
cycle :: ByteString -> ByteString

-- | <tt><a>iterate</a> f x</tt> returns an infinite ByteString of repeated
°5uapplications of <tt>f</tt> to <tt>x</tt>:
°5u
°5u<pre>
°5uiterate f x == [x, f x, f (f x), ...]
°5u</pre>
iterate :: (Word8 -> Word8) -> Word8 -> ByteString

-- | <i>O(n)</i> The <a>unfoldr</a> function is analogous to the List
°5u'unfoldr'. <a>unfoldr</a> builds a ByteString from a seed value. The
°5ufunction takes the element and returns <a>Nothing</a> if it is done
°5uproducing the ByteString or returns <a>Just</a> <tt>(a,b)</tt>, in
°5uwhich case, <tt>a</tt> is a prepending to the ByteString and
°5u<tt>b</tt> is used as the next element in a recursive call.
unfoldr :: (a -> Maybe (Word8, a)) -> a -> ByteString

-- | <i>O(n/c)</i> <a>take</a> <tt>n</tt>, applied to a ByteString
°5u<tt>xs</tt>, returns the prefix of <tt>xs</tt> of length <tt>n</tt>,
°5uor <tt>xs</tt> itself if <tt>n &gt; <a>length</a> xs</tt>.
take :: Int64 -> ByteString -> ByteString

-- | <i>O(n/c)</i> <a>drop</a> <tt>n xs</tt> returns the suffix of
°5u<tt>xs</tt> after the first <tt>n</tt> elements, or <tt>[]</tt> if
°5u<tt>n &gt; <a>length</a> xs</tt>.
drop :: Int64 -> ByteString -> ByteString

-- | <i>O(n/c)</i> <a>splitAt</a> <tt>n xs</tt> is equivalent to
°5u<tt>(<a>take</a> n xs, <a>drop</a> n xs)</tt>.
splitAt :: Int64 -> ByteString -> (ByteString, ByteString)

-- | <a>takeWhile</a>, applied to a predicate <tt>p</tt> and a ByteString
°5u<tt>xs</tt>, returns the longest prefix (possibly empty) of
°5u<tt>xs</tt> of elements that satisfy <tt>p</tt>.
takeWhile :: (Word8 -> Bool) -> ByteString -> ByteString

-- | <a>dropWhile</a> <tt>p xs</tt> returns the suffix remaining after
°5u<a>takeWhile</a> <tt>p xs</tt>.
dropWhile :: (Word8 -> Bool) -> ByteString -> ByteString

-- | <a>span</a> <tt>p xs</tt> breaks the ByteString into two segments. It
°5uis equivalent to <tt>(<a>takeWhile</a> p xs, <a>dropWhile</a> p
°5uxs)</tt>
span :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (<a>not</a> .
°5up)</tt>.
break :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | The <a>group</a> function takes a ByteString and returns a list of
°5uByteStrings such that the concatenation of the result is equal to the
°5uargument. Moreover, each sublist in the result contains only equal
°5uelements. For example,
°5u
°5u<pre>
°5ugroup "Mississippi" = ["M","i","ss","i","ss","i","pp","i"]
°5u</pre>
°5u
°5uIt is a special case of <a>groupBy</a>, which allows the programmer to
°5usupply their own equality test.
group :: ByteString -> [ByteString]

-- | The <a>groupBy</a> function is the non-overloaded version of
°5u<a>group</a>.
groupBy :: (Word8 -> Word8 -> Bool) -> ByteString -> [ByteString]

-- | <i>O(n)</i> Return all initial segments of the given
°5u<a>ByteString</a>, shortest first.
inits :: ByteString -> [ByteString]

-- | <i>O(n)</i> Return all final segments of the given <a>ByteString</a>,
°5ulongest first.
tails :: ByteString -> [ByteString]

-- | <i>O(n)</i> The <a>stripPrefix</a> function takes two ByteStrings and
°5ureturns <a>Just</a> the remainder of the second iff the first is its
°5uprefix, and otherwise <a>Nothing</a>.
stripPrefix :: ByteString -> ByteString -> Maybe ByteString

-- | <i>O(n)</i> The <a>stripSuffix</a> function takes two ByteStrings and
°5ureturns <a>Just</a> the remainder of the second iff the first is its
°5usuffix, and otherwise <a>Nothing</a>.
stripSuffix :: ByteString -> ByteString -> Maybe ByteString

-- | <i>O(n)</i> Break a <a>ByteString</a> into pieces separated by the
°5ubyte argument, consuming the delimiter. I.e.
°5u
°5u<pre>
°5usplit '\n' "a\nb\nd\ne" == ["a","b","d","e"]
°5usplit 'a'  "aXaXaXa"    == ["","X","X","X",""]
°5usplit 'x'  "x"          == ["",""]
°5u</pre>
°5u
°5uand
°5u
°5u<pre>
°5uintercalate [c] . split c == id
°5usplit == splitWith . (==)
°5u</pre>
°5u
°5uAs for all splitting functions in this library, this function does not
°5ucopy the substrings, it just constructs new <tt>ByteStrings</tt> that
°5uare slices of the original.
split :: Word8 -> ByteString -> [ByteString]

-- | <i>O(n)</i> Splits a <a>ByteString</a> into components delimited by
°5useparators, where the predicate returns True for a separator element.
°5uThe resulting components do not contain the separators. Two adjacent
°5useparators result in an empty component in the output. eg.
°5u
°5u<pre>
°5usplitWith (=='a') "aabbaca" == ["","","bb","c",""]
°5usplitWith (=='a') []        == []
°5u</pre>
splitWith :: (Word8 -> Bool) -> ByteString -> [ByteString]

-- | <i>O(n)</i> The <a>isPrefixOf</a> function takes two ByteStrings and
°5ureturns <a>True</a> iff the first is a prefix of the second.
isPrefixOf :: ByteString -> ByteString -> Bool

-- | <i>O(n)</i> The <a>isSuffixOf</a> function takes two ByteStrings and
°5ureturns <a>True</a> iff the first is a suffix of the second.
°5u
°5uThe following holds:
°5u
°5u<pre>
°5uisSuffixOf x y == reverse x `isPrefixOf` reverse y
°5u</pre>
isSuffixOf :: ByteString -> ByteString -> Bool

-- | <i>O(n)</i> <a>elem</a> is the <a>ByteString</a> membership predicate.
elem :: Word8 -> ByteString -> Bool

-- | <i>O(n)</i> <a>notElem</a> is the inverse of <a>elem</a>
notElem :: Word8 -> ByteString -> Bool

-- | <i>O(n)</i> The <a>find</a> function takes a predicate and a
°5uByteString, and returns the first element in matching the predicate,
°5uor <a>Nothing</a> if there is no such element.
°5u
°5u<pre>
°5ufind f p = case findIndex f p of Just n -&gt; Just (p ! n) ; _ -&gt; Nothing
°5u</pre>
find :: (Word8 -> Bool) -> ByteString -> Maybe Word8

-- | <i>O(n)</i> <a>filter</a>, applied to a predicate and a ByteString,
°5ureturns a ByteString containing those characters that satisfy the
°5upredicate.
filter :: (Word8 -> Bool) -> ByteString -> ByteString

-- | <i>O(n)</i> The <a>partition</a> function takes a predicate a
°5uByteString and returns the pair of ByteStrings with elements which do
°5uand do not satisfy the predicate, respectively; i.e.,
°5u
°5u<pre>
°5upartition p bs == (filter p xs, filter (not . p) xs)
°5u</pre>
partition :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | <i>O(c)</i> <a>ByteString</a> index (subscript) operator, starting
°5ufrom 0.
index :: ByteString -> Int64 -> Word8

-- | <i>O(n)</i> The <a>elemIndex</a> function returns the index of the
°5ufirst element in the given <a>ByteString</a> which is equal to the
°5uquery element, or <a>Nothing</a> if there is no such element. This
°5uimplementation uses memchr(3).
elemIndex :: Word8 -> ByteString -> Maybe Int64

-- | <i>O(n)</i> The <a>elemIndexEnd</a> function returns the last index of
°5uthe element in the given <a>ByteString</a> which is equal to the query
°5uelement, or <a>Nothing</a> if there is no such element. The following
°5uholds:
°5u
°5u<pre>
°5uelemIndexEnd c xs ==
°5u(-) (length xs - 1) `fmap` elemIndex c (reverse xs)
°5u</pre>
elemIndexEnd :: Word8 -> ByteString -> Maybe Int64

-- | <i>O(n)</i> The <a>elemIndices</a> function extends <a>elemIndex</a>,
°5uby returning the indices of all elements equal to the query element,
°5uin ascending order. This implementation uses memchr(3).
elemIndices :: Word8 -> ByteString -> [Int64]

-- | The <a>findIndex</a> function takes a predicate and a
°5u<a>ByteString</a> and returns the index of the first element in the
°5uByteString satisfying the predicate.
findIndex :: (Word8 -> Bool) -> ByteString -> Maybe Int64

-- | The <a>findIndices</a> function extends <a>findIndex</a>, by returning
°5uthe indices of all elements satisfying the predicate, in ascending
°5uorder.
findIndices :: (Word8 -> Bool) -> ByteString -> [Int64]

-- | count returns the number of times its argument appears in the
°5uByteString
°5u
°5u<pre>
°5ucount = length . elemIndices
°5u</pre>
°5u
°5uBut more efficiently than using length on the intermediate list.
count :: Word8 -> ByteString -> Int64

-- | <i>O(n)</i> <a>zip</a> takes two ByteStrings and returns a list of
°5ucorresponding pairs of bytes. If one input ByteString is short, excess
°5uelements of the longer ByteString are discarded. This is equivalent to
°5ua pair of <a>unpack</a> operations.
zip :: ByteString -> ByteString -> [(Word8, Word8)]

-- | <a>zipWith</a> generalises <a>zip</a> by zipping with the function
°5ugiven as the first argument, instead of a tupling function. For
°5uexample, <tt><a>zipWith</a> (+)</tt> is applied to two ByteStrings to
°5uproduce the list of corresponding sums.
zipWith :: (Word8 -> Word8 -> a) -> ByteString -> ByteString -> [a]

-- | <i>O(n)</i> <a>unzip</a> transforms a list of pairs of bytes into a
°5upair of ByteStrings. Note that this performs two <a>pack</a>
°5uoperations.
unzip :: [(Word8, Word8)] -> (ByteString, ByteString)

-- | <i>O(n)</i> Make a copy of the <a>ByteString</a> with its own storage.
°5uThis is mainly useful to allow the rest of the data pointed to by the
°5u<a>ByteString</a> to be garbage collected, for example if a large
°5ustring has been read in, and only a small part of it is needed in the
°5urest of the program.
copy :: ByteString -> ByteString

-- | getContents. Equivalent to hGetContents stdin. Will read <i>lazily</i>
getContents :: IO ByteString

-- | Write a ByteString to stdout
putStr :: ByteString -> IO ()

-- | Write a ByteString to stdout, appending a newline byte

-- | <i>Deprecated: Use Data.ByteString.Lazy.Char8.putStrLn instead.
°5u(Functions that rely on ASCII encodings belong in
°5uData.ByteString.Lazy.Char8)</i>
putStrLn :: ByteString -> IO ()

-- | The interact function takes a function of type <tt>ByteString -&gt;
°5uByteString</tt> as its argument. The entire input from the standard
°5uinput device is passed to this function as its argument, and the
°5uresulting string is output on the standard output device.
interact :: (ByteString -> ByteString) -> IO ()

-- | Read an entire file <i>lazily</i> into a <a>ByteString</a>. The Handle
°5uwill be held open until EOF is encountered.
readFile :: FilePath -> IO ByteString

-- | Write a <a>ByteString</a> to a file.
writeFile :: FilePath -> ByteString -> IO ()

-- | Append a <a>ByteString</a> to a file.
appendFile :: FilePath -> ByteString -> IO ()

-- | Read entire handle contents <i>lazily</i> into a <a>ByteString</a>.
°5uChunks are read on demand, using the default chunk size.
°5u
°5uOnce EOF is encountered, the Handle is closed.
°5u
°5uNote: the <a>Handle</a> should be placed in binary mode with
°5u<a>hSetBinaryMode</a> for <a>hGetContents</a> to work correctly.
hGetContents :: Handle -> IO ByteString

-- | Read <tt>n</tt> bytes into a <a>ByteString</a>, directly from the
°5uspecified <a>Handle</a>.
hGet :: Handle -> Int -> IO ByteString

-- | hGetNonBlocking is similar to <a>hGet</a>, except that it will never
°5ublock waiting for data to become available, instead it returns only
°5uwhatever data is available. If there is no data available to be read,
°5u<a>hGetNonBlocking</a> returns <a>empty</a>.
°5u
°5uNote: on Windows and with Haskell implementation other than GHC, this
°5ufunction does not work correctly; it behaves identically to
°5u<a>hGet</a>.
hGetNonBlocking :: Handle -> Int -> IO ByteString

-- | Outputs a <a>ByteString</a> to the specified <a>Handle</a>. The chunks
°5uwill be written one at a time. Other threads might write to the
°5u<a>Handle</a> between the writes, and hence <a>hPut</a> alone might
°5unot be suitable for concurrent writes.
hPut :: Handle -> ByteString -> IO ()

-- | Similar to <a>hPut</a> except that it will never block. Instead it
°5ureturns any tail that did not get written. This tail may be
°5u<a>empty</a> in the case that the whole string was written, or the
°5uwhole original string if nothing was written. Partial writes are also
°5upossible.
°5u
°5uNote: on Windows and with Haskell implementation other than GHC, this
°5ufunction does not work correctly; it behaves identically to
°5u<a>hPut</a>.
hPutNonBlocking :: Handle -> ByteString -> IO ByteString

-- | A synonym for <tt>hPut</tt>, for compatibility
hPutStr :: Handle -> ByteString -> IO ()


-- | Manipulate <i>lazy</i> <a>ByteString</a>s using <a>Char</a>
°5uoperations. All Chars will be truncated to 8 bits. It can be expected
°5uthat these functions will run at identical speeds to their
°5u<a>Word8</a> equivalents in <a>Data.ByteString.Lazy</a>.
°5u
°5uThis module is intended to be imported <tt>qualified</tt>, to avoid
°5uname clashes with <a>Prelude</a> functions. eg.
°5u
°5u<pre>
°5uimport qualified Data.ByteString.Lazy.Char8 as C
°5u</pre>
°5u
°5uThe Char8 interface to bytestrings provides an instance of IsString
°5ufor the ByteString type, enabling you to use string literals, and have
°5uthem implicitly packed to ByteStrings. Use <tt>{-# LANGUAGE
°5uOverloadedStrings #-}</tt> to enable this.
module Data.ByteString.Lazy.Char8

-- | A space-efficient representation of a <a>Word8</a> vector, supporting
°5umany efficient operations.
°5u
°5uA lazy <a>ByteString</a> contains 8-bit bytes, or by using the
°5uoperations from <a>Data.ByteString.Lazy.Char8</a> it can be
°5uinterpreted as containing 8-bit characters.
data ByteString

-- | <i>O(1)</i> The empty <a>ByteString</a>
empty :: ByteString

-- | <i>O(1)</i> Convert a <a>Char</a> into a <a>ByteString</a>
singleton :: Char -> ByteString

-- | <i>O(n)</i> Convert a <a>String</a> into a <a>ByteString</a>.
pack :: [Char] -> ByteString

-- | <i>O(n)</i> Converts a <a>ByteString</a> to a <a>String</a>.
unpack :: ByteString -> [Char]

-- | <i>O(c)</i> Convert a list of strict <a>ByteString</a> into a lazy
°5u<a>ByteString</a>
fromChunks :: [ByteString] -> ByteString

-- | <i>O(c)</i> Convert a lazy <a>ByteString</a> into a list of strict
°5u<a>ByteString</a>
toChunks :: ByteString -> [ByteString]

-- | <i>O(1)</i> Convert a strict <a>ByteString</a> into a lazy
°5u<a>ByteString</a>.
fromStrict :: ByteString -> ByteString

-- | <i>O(n)</i> Convert a lazy <a>ByteString</a> into a strict
°5u<a>ByteString</a>.
°5u
°5uNote that this is an <i>expensive</i> operation that forces the whole
°5ulazy ByteString into memory and then copies all the data. If possible,
°5utry to avoid converting back and forth between strict and lazy
°5ubytestrings.
toStrict :: ByteString -> ByteString

-- | <i>O(1)</i> <a>cons</a> is analogous to '(:)' for lists.
cons :: Char -> ByteString -> ByteString
infixr 5 `cons`

-- | <i>O(1)</i> Unlike <a>cons</a>, 'cons\'' is strict in the ByteString
°5uthat we are consing onto. More precisely, it forces the head and the
°5ufirst chunk. It does this because, for space efficiency, it may
°5ucoalesce the new byte onto the first 'chunk' rather than starting a
°5unew 'chunk'.
°5u
°5uSo that means you can't use a lazy recursive contruction like this:
°5u
°5u<pre>
°5ulet xs = cons\' c xs in xs
°5u</pre>
°5u
°5uYou can however use <a>cons</a>, as well as <a>repeat</a> and
°5u<a>cycle</a>, to build infinite lazy ByteStrings.
cons' :: Char -> ByteString -> ByteString
infixr 5 `cons'`

-- | <i>O(n)</i> Append a Char to the end of a <a>ByteString</a>. Similar
°5uto <a>cons</a>, this function performs a memcpy.
snoc :: ByteString -> Char -> ByteString
infixl 5 `snoc`

-- | <i>O(n/c)</i> Append two ByteStrings
append :: ByteString -> ByteString -> ByteString

-- | <i>O(1)</i> Extract the first element of a ByteString, which must be
°5unon-empty.
head :: ByteString -> Char

-- | <i>O(1)</i> Extract the head and tail of a ByteString, returning
°5uNothing if it is empty.
uncons :: ByteString -> Maybe (Char, ByteString)

-- | <i>O(1)</i> Extract the last element of a packed string, which must be
°5unon-empty.
last :: ByteString -> Char

-- | <i>O(1)</i> Extract the elements after the head of a ByteString, which
°5umust be non-empty.
tail :: ByteString -> ByteString

-- | <i>O(n/c)</i> Extract the <a>init</a> and <a>last</a> of a ByteString,
°5ureturning Nothing if it is empty.
unsnoc :: ByteString -> Maybe (ByteString, Char)

-- | <i>O(n/c)</i> Return all the elements of a <a>ByteString</a> except
°5uthe last one.
init :: ByteString -> ByteString

-- | <i>O(1)</i> Test whether a ByteString is empty.
null :: ByteString -> Bool

-- | <i>O(n/c)</i> <a>length</a> returns the length of a ByteString as an
°5u<a>Int64</a>
length :: ByteString -> Int64

-- | <i>O(n)</i> <a>map</a> <tt>f xs</tt> is the ByteString obtained by
°5uapplying <tt>f</tt> to each element of <tt>xs</tt>
map :: (Char -> Char) -> ByteString -> ByteString

-- | <i>O(n)</i> <a>reverse</a> <tt>xs</tt> returns the elements of
°5u<tt>xs</tt> in reverse order.
reverse :: ByteString -> ByteString

-- | <i>O(n)</i> The <a>intersperse</a> function takes a Char and a
°5u<a>ByteString</a> and `intersperses' that Char between the elements of
°5uthe <a>ByteString</a>. It is analogous to the intersperse function on
°5uLists.
intersperse :: Char -> ByteString -> ByteString

-- | <i>O(n)</i> The <a>intercalate</a> function takes a <a>ByteString</a>
°5uand a list of <a>ByteString</a>s and concatenates the list after
°5uinterspersing the first argument between each element of the list.
intercalate :: ByteString -> [ByteString] -> ByteString

-- | The <a>transpose</a> function transposes the rows and columns of its
°5u<a>ByteString</a> argument.
transpose :: [ByteString] -> [ByteString]

-- | <a>foldl</a>, applied to a binary operator, a starting value
°5u(typically the left-identity of the operator), and a ByteString,
°5ureduces the ByteString using the binary operator, from left to right.
foldl :: (a -> Char -> a) -> a -> ByteString -> a

-- | 'foldl\'' is like foldl, but strict in the accumulator.
foldl' :: (a -> Char -> a) -> a -> ByteString -> a

-- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value
°5uargument, and thus must be applied to non-empty <tt>ByteStrings</tt>.
foldl1 :: (Char -> Char -> Char) -> ByteString -> Char

-- | 'foldl1\'' is like <a>foldl1</a>, but strict in the accumulator.
foldl1' :: (Char -> Char -> Char) -> ByteString -> Char

-- | <a>foldr</a>, applied to a binary operator, a starting value
°5u(typically the right-identity of the operator), and a packed string,
°5ureduces the packed string using the binary operator, from right to
°5uleft.
foldr :: (Char -> a -> a) -> a -> ByteString -> a

-- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value
°5uargument, and thus must be applied to non-empty <a>ByteString</a>s
foldr1 :: (Char -> Char -> Char) -> ByteString -> Char

-- | <i>O(n)</i> Concatenate a list of ByteStrings.
concat :: [ByteString] -> ByteString

-- | Map a function over a <a>ByteString</a> and concatenate the results
concatMap :: (Char -> ByteString) -> ByteString -> ByteString

-- | Applied to a predicate and a ByteString, <a>any</a> determines if any
°5uelement of the <a>ByteString</a> satisfies the predicate.
any :: (Char -> Bool) -> ByteString -> Bool

-- | Applied to a predicate and a <a>ByteString</a>, <a>all</a> determines
°5uif all elements of the <a>ByteString</a> satisfy the predicate.
all :: (Char -> Bool) -> ByteString -> Bool

-- | <a>maximum</a> returns the maximum value from a <a>ByteString</a>
maximum :: ByteString -> Char

-- | <a>minimum</a> returns the minimum value from a <a>ByteString</a>
minimum :: ByteString -> Char

-- | <a>scanl</a> is similar to <a>foldl</a>, but returns a list of
°5usuccessive reduced values from the left. This function will fuse.
°5u
°5u<pre>
°5uscanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
°5u</pre>
°5u
°5uNote that
°5u
°5u<pre>
°5ulast (scanl f z xs) == foldl f z xs.
°5u</pre>
scanl :: (Char -> Char -> Char) -> Char -> ByteString -> ByteString

-- | The <a>mapAccumL</a> function behaves like a combination of <a>map</a>
°5uand <a>foldl</a>; it applies a function to each element of a
°5uByteString, passing an accumulating parameter from left to right, and
°5ureturning a final value of this accumulator together with the new
°5uByteString.
mapAccumL :: (acc -> Char -> (acc, Char)) -> acc -> ByteString -> (acc, ByteString)

-- | The <a>mapAccumR</a> function behaves like a combination of <a>map</a>
°5uand <a>foldr</a>; it applies a function to each element of a
°5uByteString, passing an accumulating parameter from right to left, and
°5ureturning a final value of this accumulator together with the new
°5uByteString.
mapAccumR :: (acc -> Char -> (acc, Char)) -> acc -> ByteString -> (acc, ByteString)

-- | <tt><a>repeat</a> x</tt> is an infinite ByteString, with <tt>x</tt>
°5uthe value of every element.
repeat :: Char -> ByteString

-- | <i>O(n)</i> <tt><a>replicate</a> n x</tt> is a ByteString of length
°5u<tt>n</tt> with <tt>x</tt> the value of every element.
replicate :: Int64 -> Char -> ByteString

-- | <a>cycle</a> ties a finite ByteString into a circular one, or
°5uequivalently, the infinite repetition of the original ByteString.
cycle :: ByteString -> ByteString

-- | <tt><a>iterate</a> f x</tt> returns an infinite ByteString of repeated
°5uapplications of <tt>f</tt> to <tt>x</tt>:
°5u
°5u<pre>
°5uiterate f x == [x, f x, f (f x), ...]
°5u</pre>
iterate :: (Char -> Char) -> Char -> ByteString

-- | <i>O(n)</i> The <a>unfoldr</a> function is analogous to the List
°5u'unfoldr'. <a>unfoldr</a> builds a ByteString from a seed value. The
°5ufunction takes the element and returns <a>Nothing</a> if it is done
°5uproducing the ByteString or returns <a>Just</a> <tt>(a,b)</tt>, in
°5uwhich case, <tt>a</tt> is a prepending to the ByteString and
°5u<tt>b</tt> is used as the next element in a recursive call.
unfoldr :: (a -> Maybe (Char, a)) -> a -> ByteString

-- | <i>O(n/c)</i> <a>take</a> <tt>n</tt>, applied to a ByteString
°5u<tt>xs</tt>, returns the prefix of <tt>xs</tt> of length <tt>n</tt>,
°5uor <tt>xs</tt> itself if <tt>n &gt; <a>length</a> xs</tt>.
take :: Int64 -> ByteString -> ByteString

-- | <i>O(n/c)</i> <a>drop</a> <tt>n xs</tt> returns the suffix of
°5u<tt>xs</tt> after the first <tt>n</tt> elements, or <tt>[]</tt> if
°5u<tt>n &gt; <a>length</a> xs</tt>.
drop :: Int64 -> ByteString -> ByteString

-- | <i>O(n/c)</i> <a>splitAt</a> <tt>n xs</tt> is equivalent to
°5u<tt>(<a>take</a> n xs, <a>drop</a> n xs)</tt>.
splitAt :: Int64 -> ByteString -> (ByteString, ByteString)

-- | <a>takeWhile</a>, applied to a predicate <tt>p</tt> and a ByteString
°5u<tt>xs</tt>, returns the longest prefix (possibly empty) of
°5u<tt>xs</tt> of elements that satisfy <tt>p</tt>.
takeWhile :: (Char -> Bool) -> ByteString -> ByteString

-- | <a>dropWhile</a> <tt>p xs</tt> returns the suffix remaining after
°5u<a>takeWhile</a> <tt>p xs</tt>.
dropWhile :: (Char -> Bool) -> ByteString -> ByteString

-- | <a>span</a> <tt>p xs</tt> breaks the ByteString into two segments. It
°5uis equivalent to <tt>(<a>takeWhile</a> p xs, <a>dropWhile</a> p
°5uxs)</tt>
span :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)

-- | <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (<a>not</a> .
°5up)</tt>.
break :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)

-- | The <a>group</a> function takes a ByteString and returns a list of
°5uByteStrings such that the concatenation of the result is equal to the
°5uargument. Moreover, each sublist in the result contains only equal
°5uelements. For example,
°5u
°5u<pre>
°5ugroup "Mississippi" = ["M","i","ss","i","ss","i","pp","i"]
°5u</pre>
°5u
°5uIt is a special case of <a>groupBy</a>, which allows the programmer to
°5usupply their own equality test.
group :: ByteString -> [ByteString]

-- | The <a>groupBy</a> function is the non-overloaded version of
°5u<a>group</a>.
groupBy :: (Char -> Char -> Bool) -> ByteString -> [ByteString]

-- | <i>O(n)</i> Return all initial segments of the given
°5u<a>ByteString</a>, shortest first.
inits :: ByteString -> [ByteString]

-- | <i>O(n)</i> Return all final segments of the given <a>ByteString</a>,
°5ulongest first.
tails :: ByteString -> [ByteString]

-- | <i>O(n)</i> The <a>stripPrefix</a> function takes two ByteStrings and
°5ureturns <a>Just</a> the remainder of the second iff the first is its
°5uprefix, and otherwise <a>Nothing</a>.
stripPrefix :: ByteString -> ByteString -> Maybe ByteString

-- | <i>O(n)</i> The <a>stripSuffix</a> function takes two ByteStrings and
°5ureturns <a>Just</a> the remainder of the second iff the first is its
°5usuffix, and otherwise <a>Nothing</a>.
stripSuffix :: ByteString -> ByteString -> Maybe ByteString

-- | <i>O(n)</i> Break a <a>ByteString</a> into pieces separated by the
°5ubyte argument, consuming the delimiter. I.e.
°5u
°5u<pre>
°5usplit '\n' "a\nb\nd\ne" == ["a","b","d","e"]
°5usplit 'a'  "aXaXaXa"    == ["","X","X","X"]
°5usplit 'x'  "x"          == ["",""]
°5u</pre>
°5u
°5uand
°5u
°5u<pre>
°5uintercalate [c] . split c == id
°5usplit == splitWith . (==)
°5u</pre>
°5u
°5uAs for all splitting functions in this library, this function does not
°5ucopy the substrings, it just constructs new <tt>ByteStrings</tt> that
°5uare slices of the original.
split :: Char -> ByteString -> [ByteString]

-- | <i>O(n)</i> Splits a <a>ByteString</a> into components delimited by
°5useparators, where the predicate returns True for a separator element.
°5uThe resulting components do not contain the separators. Two adjacent
°5useparators result in an empty component in the output. eg.
°5u
°5u<pre>
°5usplitWith (=='a') "aabbaca" == ["","","bb","c",""]
°5u</pre>
splitWith :: (Char -> Bool) -> ByteString -> [ByteString]

-- | <a>lines</a> breaks a ByteString up into a list of ByteStrings at
°5unewline Chars. The resulting strings do not contain newlines.
°5u
°5uAs of bytestring 0.9.0.3, this function is stricter than its list
°5ucousin.
lines :: ByteString -> [ByteString]

-- | <a>words</a> breaks a ByteString up into a list of words, which were
°5udelimited by Chars representing white space. And
°5u
°5u<pre>
°5utokens isSpace = words
°5u</pre>
words :: ByteString -> [ByteString]

-- | <a>unlines</a> is an inverse operation to <a>lines</a>. It joins
°5ulines, after appending a terminating newline to each.
unlines :: [ByteString] -> ByteString

-- | The <a>unwords</a> function is analogous to the <a>unlines</a>
°5ufunction, on words.
unwords :: [ByteString] -> ByteString

-- | <i>O(n)</i> The <a>isPrefixOf</a> function takes two ByteStrings and
°5ureturns <a>True</a> iff the first is a prefix of the second.
isPrefixOf :: ByteString -> ByteString -> Bool

-- | <i>O(n)</i> The <a>isSuffixOf</a> function takes two ByteStrings and
°5ureturns <a>True</a> iff the first is a suffix of the second.
°5u
°5uThe following holds:
°5u
°5u<pre>
°5uisSuffixOf x y == reverse x `isPrefixOf` reverse y
°5u</pre>
isSuffixOf :: ByteString -> ByteString -> Bool

-- | <i>O(n)</i> <a>elem</a> is the <a>ByteString</a> membership predicate.
°5uThis implementation uses <tt>memchr(3)</tt>.
elem :: Char -> ByteString -> Bool

-- | <i>O(n)</i> <a>notElem</a> is the inverse of <a>elem</a>
notElem :: Char -> ByteString -> Bool

-- | <i>O(n)</i> The <a>find</a> function takes a predicate and a
°5uByteString, and returns the first element in matching the predicate,
°5uor <a>Nothing</a> if there is no such element.
find :: (Char -> Bool) -> ByteString -> Maybe Char

-- | <i>O(n)</i> <a>filter</a>, applied to a predicate and a ByteString,
°5ureturns a ByteString containing those characters that satisfy the
°5upredicate.
filter :: (Char -> Bool) -> ByteString -> ByteString

-- | <i>O(1)</i> <a>ByteString</a> index (subscript) operator, starting
°5ufrom 0.
index :: ByteString -> Int64 -> Char

-- | <i>O(n)</i> The <a>elemIndex</a> function returns the index of the
°5ufirst element in the given <a>ByteString</a> which is equal (by
°5umemchr) to the query element, or <a>Nothing</a> if there is no such
°5uelement.
elemIndex :: Char -> ByteString -> Maybe Int64

-- | <i>O(n)</i> The <a>elemIndices</a> function extends <a>elemIndex</a>,
°5uby returning the indices of all elements equal to the query element,
°5uin ascending order.
elemIndices :: Char -> ByteString -> [Int64]

-- | The <a>findIndex</a> function takes a predicate and a
°5u<a>ByteString</a> and returns the index of the first element in the
°5uByteString satisfying the predicate.
findIndex :: (Char -> Bool) -> ByteString -> Maybe Int64

-- | The <a>findIndices</a> function extends <a>findIndex</a>, by returning
°5uthe indices of all elements satisfying the predicate, in ascending
°5uorder.
findIndices :: (Char -> Bool) -> ByteString -> [Int64]

-- | count returns the number of times its argument appears in the
°5uByteString
°5u
°5u<pre>
°5ucount      == length . elemIndices
°5ucount '\n' == length . lines
°5u</pre>
°5u
°5uBut more efficiently than using length on the intermediate list.
count :: Char -> ByteString -> Int64

-- | <i>O(n)</i> <a>zip</a> takes two ByteStrings and returns a list of
°5ucorresponding pairs of Chars. If one input ByteString is short, excess
°5uelements of the longer ByteString are discarded. This is equivalent to
°5ua pair of <a>unpack</a> operations, and so space usage may be large
°5ufor multi-megabyte ByteStrings
zip :: ByteString -> ByteString -> [(Char, Char)]

-- | <a>zipWith</a> generalises <a>zip</a> by zipping with the function
°5ugiven as the first argument, instead of a tupling function. For
°5uexample, <tt><a>zipWith</a> (+)</tt> is applied to two ByteStrings to
°5uproduce the list of corresponding sums.
zipWith :: (Char -> Char -> a) -> ByteString -> ByteString -> [a]

-- | <i>O(n)</i> Make a copy of the <a>ByteString</a> with its own storage.
°5uThis is mainly useful to allow the rest of the data pointed to by the
°5u<a>ByteString</a> to be garbage collected, for example if a large
°5ustring has been read in, and only a small part of it is needed in the
°5urest of the program.
copy :: ByteString -> ByteString

-- | readInt reads an Int from the beginning of the ByteString. If there is
°5uno integer at the beginning of the string, it returns Nothing,
°5uotherwise it just returns the int read, and the rest of the string.
readInt :: ByteString -> Maybe (Int, ByteString)

-- | readInteger reads an Integer from the beginning of the ByteString. If
°5uthere is no integer at the beginning of the string, it returns
°5uNothing, otherwise it just returns the int read, and the rest of the
°5ustring.
readInteger :: ByteString -> Maybe (Integer, ByteString)

-- | getContents. Equivalent to hGetContents stdin. Will read <i>lazily</i>
getContents :: IO ByteString

-- | Write a ByteString to stdout
putStr :: ByteString -> IO ()

-- | Write a ByteString to stdout, appending a newline byte
putStrLn :: ByteString -> IO ()

-- | The interact function takes a function of type <tt>ByteString -&gt;
°5uByteString</tt> as its argument. The entire input from the standard
°5uinput device is passed to this function as its argument, and the
°5uresulting string is output on the standard output device.
interact :: (ByteString -> ByteString) -> IO ()

-- | Read an entire file <i>lazily</i> into a <a>ByteString</a>. The Handle
°5uwill be held open until EOF is encountered.
readFile :: FilePath -> IO ByteString

-- | Write a <a>ByteString</a> to a file.
writeFile :: FilePath -> ByteString -> IO ()

-- | Append a <a>ByteString</a> to a file.
appendFile :: FilePath -> ByteString -> IO ()

-- | Read entire handle contents <i>lazily</i> into a <a>ByteString</a>.
°5uChunks are read on demand, using the default chunk size.
°5u
°5uOnce EOF is encountered, the Handle is closed.
°5u
°5uNote: the <a>Handle</a> should be placed in binary mode with
°5u<a>hSetBinaryMode</a> for <a>hGetContents</a> to work correctly.
hGetContents :: Handle -> IO ByteString

-- | Read <tt>n</tt> bytes into a <a>ByteString</a>, directly from the
°5uspecified <a>Handle</a>.
hGet :: Handle -> Int -> IO ByteString

-- | hGetNonBlocking is similar to <a>hGet</a>, except that it will never
°5ublock waiting for data to become available, instead it returns only
°5uwhatever data is available. If there is no data available to be read,
°5u<a>hGetNonBlocking</a> returns <a>empty</a>.
°5u
°5uNote: on Windows and with Haskell implementation other than GHC, this
°5ufunction does not work correctly; it behaves identically to
°5u<a>hGet</a>.
hGetNonBlocking :: Handle -> Int -> IO ByteString

-- | Outputs a <a>ByteString</a> to the specified <a>Handle</a>. The chunks
°5uwill be written one at a time. Other threads might write to the
°5u<a>Handle</a> between the writes, and hence <a>hPut</a> alone might
°5unot be suitable for concurrent writes.
hPut :: Handle -> ByteString -> IO ()

-- | Similar to <a>hPut</a> except that it will never block. Instead it
°5ureturns any tail that did not get written. This tail may be
°5u<a>empty</a> in the case that the whole string was written, or the
°5uwhole original string if nothing was written. Partial writes are also
°5upossible.
°5u
°5uNote: on Windows and with Haskell implementation other than GHC, this
°5ufunction does not work correctly; it behaves identically to
°5u<a>hPut</a>.
hPutNonBlocking :: Handle -> ByteString -> IO ByteString

-- | A synonym for <tt>hPut</tt>, for compatibility
hPutStr :: Handle -> ByteString -> IO ()

-- | Write a ByteString to a handle, appending a newline byte
hPutStrLn :: Handle -> ByteString -> IO ()


-- | Manipulate <a>ByteString</a>s using <a>Char</a> operations. All Chars
°5uwill be truncated to 8 bits. It can be expected that these functions
°5uwill run at identical speeds to their <a>Word8</a> equivalents in
°5u<a>Data.ByteString</a>.
°5u
°5uMore specifically these byte strings are taken to be in the subset of
°5uUnicode covered by code points 0-255. This covers Unicode Basic Latin,
°5uLatin-1 Supplement and C0+C1 Controls.
°5u
°5uSee:
°5u
°5u<ul>
°5u<li><a>http://www.unicode.org/charts/</a></li>
°5u<li><a>http://www.unicode.org/charts/PDF/U0000.pdf</a></li>
°5u<li><a>http://www.unicode.org/charts/PDF/U0080.pdf</a></li>
°5u</ul>
°5u
°5uThis module is intended to be imported <tt>qualified</tt>, to avoid
°5uname clashes with <a>Prelude</a> functions. eg.
°5u
°5u<pre>
°5uimport qualified Data.ByteString.Char8 as C
°5u</pre>
°5u
°5uThe Char8 interface to bytestrings provides an instance of IsString
°5ufor the ByteString type, enabling you to use string literals, and have
°5uthem implicitly packed to ByteStrings. Use <tt>{-# LANGUAGE
°5uOverloadedStrings #-}</tt> to enable this.
module Data.ByteString.Char8

-- | A space-efficient representation of a <a>Word8</a> vector, supporting
°5umany efficient operations.
°5u
°5uA <a>ByteString</a> contains 8-bit bytes, or by using the operations
°5ufrom <a>Data.ByteString.Char8</a> it can be interpreted as containing
°5u8-bit characters.
data ByteString

-- | <i>O(1)</i> The empty <a>ByteString</a>
empty :: ByteString

-- | <i>O(1)</i> Convert a <a>Char</a> into a <a>ByteString</a>
singleton :: Char -> ByteString

-- | <i>O(n)</i> Convert a <a>String</a> into a <a>ByteString</a>
°5u
°5uFor applications with large numbers of string literals, pack can be a
°5ubottleneck.
pack :: String -> ByteString

-- | <i>O(n)</i> Converts a <a>ByteString</a> to a <a>String</a>.
unpack :: ByteString -> [Char]

-- | <i>O(n)</i> <a>cons</a> is analogous to (:) for lists, but of
°5udifferent complexity, as it requires a memcpy.
cons :: Char -> ByteString -> ByteString
infixr 5 `cons`

-- | <i>O(n)</i> Append a Char to the end of a <a>ByteString</a>. Similar
°5uto <a>cons</a>, this function performs a memcpy.
snoc :: ByteString -> Char -> ByteString
infixl 5 `snoc`

-- | <i>O(n)</i> Append two ByteStrings
append :: ByteString -> ByteString -> ByteString

-- | <i>O(1)</i> Extract the first element of a ByteString, which must be
°5unon-empty.
head :: ByteString -> Char

-- | <i>O(1)</i> Extract the head and tail of a ByteString, returning
°5uNothing if it is empty.
uncons :: ByteString -> Maybe (Char, ByteString)

-- | <i>O(1)</i> Extract the <a>init</a> and <a>last</a> of a ByteString,
°5ureturning Nothing if it is empty.
unsnoc :: ByteString -> Maybe (ByteString, Char)

-- | <i>O(1)</i> Extract the last element of a packed string, which must be
°5unon-empty.
last :: ByteString -> Char

-- | <i>O(1)</i> Extract the elements after the head of a ByteString, which
°5umust be non-empty. An exception will be thrown in the case of an empty
°5uByteString.
tail :: ByteString -> ByteString

-- | <i>O(1)</i> Return all the elements of a <a>ByteString</a> except the
°5ulast one. An exception will be thrown in the case of an empty
°5uByteString.
init :: ByteString -> ByteString

-- | <i>O(1)</i> Test whether a ByteString is empty.
null :: ByteString -> Bool

-- | <i>O(1)</i> <a>length</a> returns the length of a ByteString as an
°5u<a>Int</a>.
length :: ByteString -> Int

-- | <i>O(n)</i> <a>map</a> <tt>f xs</tt> is the ByteString obtained by
°5uapplying <tt>f</tt> to each element of <tt>xs</tt>
map :: (Char -> Char) -> ByteString -> ByteString

-- | <i>O(n)</i> <a>reverse</a> <tt>xs</tt> efficiently returns the
°5uelements of <tt>xs</tt> in reverse order.
reverse :: ByteString -> ByteString

-- | <i>O(n)</i> The <a>intersperse</a> function takes a Char and a
°5u<a>ByteString</a> and `intersperses' that Char between the elements of
°5uthe <a>ByteString</a>. It is analogous to the intersperse function on
°5uLists.
intersperse :: Char -> ByteString -> ByteString

-- | <i>O(n)</i> The <a>intercalate</a> function takes a <a>ByteString</a>
°5uand a list of <a>ByteString</a>s and concatenates the list after
°5uinterspersing the first argument between each element of the list.
intercalate :: ByteString -> [ByteString] -> ByteString

-- | The <a>transpose</a> function transposes the rows and columns of its
°5u<a>ByteString</a> argument.
transpose :: [ByteString] -> [ByteString]

-- | <a>foldl</a>, applied to a binary operator, a starting value
°5u(typically the left-identity of the operator), and a ByteString,
°5ureduces the ByteString using the binary operator, from left to right.
foldl :: (a -> Char -> a) -> a -> ByteString -> a

-- | 'foldl\'' is like foldl, but strict in the accumulator.
foldl' :: (a -> Char -> a) -> a -> ByteString -> a

-- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value
°5uargument, and thus must be applied to non-empty <tt>ByteStrings</tt>.
foldl1 :: (Char -> Char -> Char) -> ByteString -> Char

-- | A strict version of <a>foldl1</a>
foldl1' :: (Char -> Char -> Char) -> ByteString -> Char

-- | <a>foldr</a>, applied to a binary operator, a starting value
°5u(typically the right-identity of the operator), and a packed string,
°5ureduces the packed string using the binary operator, from right to
°5uleft.
foldr :: (Char -> a -> a) -> a -> ByteString -> a

-- | 'foldr\'' is a strict variant of foldr
foldr' :: (Char -> a -> a) -> a -> ByteString -> a

-- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value
°5uargument, and thus must be applied to non-empty <a>ByteString</a>s
foldr1 :: (Char -> Char -> Char) -> ByteString -> Char

-- | A strict variant of foldr1
foldr1' :: (Char -> Char -> Char) -> ByteString -> Char

-- | <i>O(n)</i> Concatenate a list of ByteStrings.
concat :: [ByteString] -> ByteString

-- | Map a function over a <a>ByteString</a> and concatenate the results
concatMap :: (Char -> ByteString) -> ByteString -> ByteString

-- | Applied to a predicate and a ByteString, <a>any</a> determines if any
°5uelement of the <a>ByteString</a> satisfies the predicate.
any :: (Char -> Bool) -> ByteString -> Bool

-- | Applied to a predicate and a <a>ByteString</a>, <a>all</a> determines
°5uif all elements of the <a>ByteString</a> satisfy the predicate.
all :: (Char -> Bool) -> ByteString -> Bool

-- | <a>maximum</a> returns the maximum value from a <a>ByteString</a>
maximum :: ByteString -> Char

-- | <a>minimum</a> returns the minimum value from a <a>ByteString</a>
minimum :: ByteString -> Char

-- | <a>scanl</a> is similar to <a>foldl</a>, but returns a list of
°5usuccessive reduced values from the left:
°5u
°5u<pre>
°5uscanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
°5u</pre>
°5u
°5uNote that
°5u
°5u<pre>
°5ulast (scanl f z xs) == foldl f z xs.
°5u</pre>
scanl :: (Char -> Char -> Char) -> Char -> ByteString -> ByteString

-- | <a>scanl1</a> is a variant of <a>scanl</a> that has no starting value
°5uargument:
°5u
°5u<pre>
°5uscanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
°5u</pre>
scanl1 :: (Char -> Char -> Char) -> ByteString -> ByteString

-- | scanr is the right-to-left dual of scanl.
scanr :: (Char -> Char -> Char) -> Char -> ByteString -> ByteString

-- | <a>scanr1</a> is a variant of <a>scanr</a> that has no starting value
°5uargument.
scanr1 :: (Char -> Char -> Char) -> ByteString -> ByteString

-- | The <a>mapAccumL</a> function behaves like a combination of <a>map</a>
°5uand <a>foldl</a>; it applies a function to each element of a
°5uByteString, passing an accumulating parameter from left to right, and
°5ureturning a final value of this accumulator together with the new
°5ulist.
mapAccumL :: (acc -> Char -> (acc, Char)) -> acc -> ByteString -> (acc, ByteString)

-- | The <a>mapAccumR</a> function behaves like a combination of <a>map</a>
°5uand <a>foldr</a>; it applies a function to each element of a
°5uByteString, passing an accumulating parameter from right to left, and
°5ureturning a final value of this accumulator together with the new
°5uByteString.
mapAccumR :: (acc -> Char -> (acc, Char)) -> acc -> ByteString -> (acc, ByteString)

-- | <i>O(n)</i> <a>replicate</a> <tt>n x</tt> is a ByteString of length
°5u<tt>n</tt> with <tt>x</tt> the value of every element. The following
°5uholds:
°5u
°5u<pre>
°5ureplicate w c = unfoldr w (\u -&gt; Just (u,u)) c
°5u</pre>
°5u
°5uThis implemenation uses <tt>memset(3)</tt>
replicate :: Int -> Char -> ByteString

-- | <i>O(n)</i>, where <i>n</i> is the length of the result. The
°5u<a>unfoldr</a> function is analogous to the List 'unfoldr'.
°5u<a>unfoldr</a> builds a ByteString from a seed value. The function
°5utakes the element and returns <a>Nothing</a> if it is done producing
°5uthe ByteString or returns <a>Just</a> <tt>(a,b)</tt>, in which case,
°5u<tt>a</tt> is the next character in the string, and <tt>b</tt> is the
°5useed value for further production.
°5u
°5uExamples:
°5u
°5u<pre>
°5uunfoldr (\x -&gt; if x &lt;= '9' then Just (x, succ x) else Nothing) '0' == "0123456789"
°5u</pre>
unfoldr :: (a -> Maybe (Char, a)) -> a -> ByteString

-- | <i>O(n)</i> Like <a>unfoldr</a>, <a>unfoldrN</a> builds a ByteString
°5ufrom a seed value. However, the length of the result is limited by the
°5ufirst argument to <a>unfoldrN</a>. This function is more efficient
°5uthan <a>unfoldr</a> when the maximum length of the result is known.
°5u
°5uThe following equation relates <a>unfoldrN</a> and <a>unfoldr</a>:
°5u
°5u<pre>
°5uunfoldrN n f s == take n (unfoldr f s)
°5u</pre>
unfoldrN :: Int -> (a -> Maybe (Char, a)) -> a -> (ByteString, Maybe a)

-- | <i>O(1)</i> <a>take</a> <tt>n</tt>, applied to a ByteString
°5u<tt>xs</tt>, returns the prefix of <tt>xs</tt> of length <tt>n</tt>,
°5uor <tt>xs</tt> itself if <tt>n &gt; <a>length</a> xs</tt>.
take :: Int -> ByteString -> ByteString

-- | <i>O(1)</i> <a>drop</a> <tt>n xs</tt> returns the suffix of
°5u<tt>xs</tt> after the first <tt>n</tt> elements, or <tt>[]</tt> if
°5u<tt>n &gt; <a>length</a> xs</tt>.
drop :: Int -> ByteString -> ByteString

-- | <i>O(1)</i> <a>splitAt</a> <tt>n xs</tt> is equivalent to
°5u<tt>(<a>take</a> n xs, <a>drop</a> n xs)</tt>.
splitAt :: Int -> ByteString -> (ByteString, ByteString)

-- | <a>takeWhile</a>, applied to a predicate <tt>p</tt> and a ByteString
°5u<tt>xs</tt>, returns the longest prefix (possibly empty) of
°5u<tt>xs</tt> of elements that satisfy <tt>p</tt>.
takeWhile :: (Char -> Bool) -> ByteString -> ByteString

-- | <a>dropWhile</a> <tt>p xs</tt> returns the suffix remaining after
°5u<a>takeWhile</a> <tt>p xs</tt>.
dropWhile :: (Char -> Bool) -> ByteString -> ByteString

-- | <a>span</a> <tt>p xs</tt> breaks the ByteString into two segments. It
°5uis equivalent to <tt>(<a>takeWhile</a> p xs, <a>dropWhile</a> p
°5uxs)</tt>
span :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)

-- | <a>spanEnd</a> behaves like <a>span</a> but from the end of the
°5u<a>ByteString</a>. We have
°5u
°5u<pre>
°5uspanEnd (not.isSpace) "x y z" == ("x y ","z")
°5u</pre>
°5u
°5uand
°5u
°5u<pre>
°5uspanEnd (not . isSpace) ps
°5u   ==
°5ulet (x,y) = span (not.isSpace) (reverse ps) in (reverse y, reverse x)
°5u</pre>
spanEnd :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)

-- | <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (<a>not</a> .
°5up)</tt>.
break :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)

-- | <a>breakEnd</a> behaves like <a>break</a> but from the end of the
°5u<a>ByteString</a>
°5u
°5ubreakEnd p == spanEnd (not.p)
breakEnd :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)

-- | The <a>group</a> function takes a ByteString and returns a list of
°5uByteStrings such that the concatenation of the result is equal to the
°5uargument. Moreover, each sublist in the result contains only equal
°5uelements. For example,
°5u
°5u<pre>
°5ugroup "Mississippi" = ["M","i","ss","i","ss","i","pp","i"]
°5u</pre>
°5u
°5uIt is a special case of <a>groupBy</a>, which allows the programmer to
°5usupply their own equality test. It is about 40% faster than <i>groupBy
°5u(==)</i>
group :: ByteString -> [ByteString]

-- | The <a>groupBy</a> function is the non-overloaded version of
°5u<a>group</a>.
groupBy :: (Char -> Char -> Bool) -> ByteString -> [ByteString]

-- | <i>O(n)</i> Return all initial segments of the given
°5u<a>ByteString</a>, shortest first.
inits :: ByteString -> [ByteString]

-- | <i>O(n)</i> Return all final segments of the given <a>ByteString</a>,
°5ulongest first.
tails :: ByteString -> [ByteString]

-- | <i>O(n)</i> The <a>stripPrefix</a> function takes two ByteStrings and
°5ureturns <a>Just</a> the remainder of the second iff the first is its
°5uprefix, and otherwise <a>Nothing</a>.
stripPrefix :: ByteString -> ByteString -> Maybe ByteString

-- | <i>O(n)</i> The <a>stripSuffix</a> function takes two ByteStrings and
°5ureturns <a>Just</a> the remainder of the second iff the first is its
°5usuffix, and otherwise <a>Nothing</a>.
stripSuffix :: ByteString -> ByteString -> Maybe ByteString

-- | <i>O(n)</i> Break a <a>ByteString</a> into pieces separated by the
°5ubyte argument, consuming the delimiter. I.e.
°5u
°5u<pre>
°5usplit '\n' "a\nb\nd\ne" == ["a","b","d","e"]
°5usplit 'a'  "aXaXaXa"    == ["","X","X","X",""]
°5usplit 'x'  "x"          == ["",""]
°5u</pre>
°5u
°5uand
°5u
°5u<pre>
°5uintercalate [c] . split c == id
°5usplit == splitWith . (==)
°5u</pre>
°5u
°5uAs for all splitting functions in this library, this function does not
°5ucopy the substrings, it just constructs new <tt>ByteStrings</tt> that
°5uare slices of the original.
split :: Char -> ByteString -> [ByteString]

-- | <i>O(n)</i> Splits a <a>ByteString</a> into components delimited by
°5useparators, where the predicate returns True for a separator element.
°5uThe resulting components do not contain the separators. Two adjacent
°5useparators result in an empty component in the output. eg.
°5u
°5u<pre>
°5usplitWith (=='a') "aabbaca" == ["","","bb","c",""]
°5u</pre>
splitWith :: (Char -> Bool) -> ByteString -> [ByteString]

-- | <a>lines</a> breaks a ByteString up into a list of ByteStrings at
°5unewline Chars. The resulting strings do not contain newlines.
lines :: ByteString -> [ByteString]

-- | <a>words</a> breaks a ByteString up into a list of words, which were
°5udelimited by Chars representing white space.
words :: ByteString -> [ByteString]

-- | <a>unlines</a> is an inverse operation to <a>lines</a>. It joins
°5ulines, after appending a terminating newline to each.
unlines :: [ByteString] -> ByteString

-- | The <a>unwords</a> function is analogous to the <a>unlines</a>
°5ufunction, on words.
unwords :: [ByteString] -> ByteString

-- | <i>O(n)</i> The <a>isPrefixOf</a> function takes two ByteStrings and
°5ureturns <a>True</a> if the first is a prefix of the second.
isPrefixOf :: ByteString -> ByteString -> Bool

-- | <i>O(n)</i> The <a>isSuffixOf</a> function takes two ByteStrings and
°5ureturns <a>True</a> iff the first is a suffix of the second.
°5u
°5uThe following holds:
°5u
°5u<pre>
°5uisSuffixOf x y == reverse x `isPrefixOf` reverse y
°5u</pre>
°5u
°5uHowever, the real implemenation uses memcmp to compare the end of the
°5ustring only, with no reverse required..
isSuffixOf :: ByteString -> ByteString -> Bool

-- | Check whether one string is a substring of another. <tt>isInfixOf p
°5us</tt> is equivalent to <tt>not (null (findSubstrings p s))</tt>.
isInfixOf :: ByteString -> ByteString -> Bool

-- | Break a string on a substring, returning a pair of the part of the
°5ustring prior to the match, and the rest of the string.
°5u
°5uThe following relationships hold:
°5u
°5u<pre>
°5ubreak (== c) l == breakSubstring (singleton c) l
°5u</pre>
°5u
°5uand:
°5u
°5u<pre>
°5ufindSubstring s l ==
°5u   if null s then Just 0
°5u             else case breakSubstring s l of
°5u                      (x,y) | null y    -&gt; Nothing
°5u                            | otherwise -&gt; Just (length x)
°5u</pre>
°5u
°5uFor example, to tokenise a string, dropping delimiters:
°5u
°5u<pre>
°5utokenise x y = h : if null t then [] else tokenise x (drop (length x) t)
°5u    where (h,t) = breakSubstring x y
°5u</pre>
°5u
°5uTo skip to the first occurence of a string:
°5u
°5u<pre>
°5usnd (breakSubstring x y)
°5u</pre>
°5u
°5uTo take the parts of a string before a delimiter:
°5u
°5u<pre>
°5ufst (breakSubstring x y)
°5u</pre>
°5u
°5uNote that calling `breakSubstring x` does some preprocessing work, so
°5uyou should avoid unnecessarily duplicating breakSubstring calls with
°5uthe same pattern.
breakSubstring :: ByteString -> ByteString -> (ByteString, ByteString)

-- | Get the first index of a substring in another string, or
°5u<a>Nothing</a> if the string is not found. <tt>findSubstring p s</tt>
°5uis equivalent to <tt>listToMaybe (findSubstrings p s)</tt>.

-- | <i>Deprecated: findSubstring is deprecated in favour of
°5ubreakSubstring.</i>
findSubstring :: ByteString -> ByteString -> Maybe Int

-- | Find the indexes of all (possibly overlapping) occurances of a
°5usubstring in a string.

-- | <i>Deprecated: findSubstrings is deprecated in favour of
°5ubreakSubstring.</i>
findSubstrings :: ByteString -> ByteString -> [Int]

-- | <i>O(n)</i> <a>elem</a> is the <a>ByteString</a> membership predicate.
°5uThis implementation uses <tt>memchr(3)</tt>.
elem :: Char -> ByteString -> Bool

-- | <i>O(n)</i> <a>notElem</a> is the inverse of <a>elem</a>
notElem :: Char -> ByteString -> Bool

-- | <i>O(n)</i> The <a>find</a> function takes a predicate and a
°5uByteString, and returns the first element in matching the predicate,
°5uor <a>Nothing</a> if there is no such element.
find :: (Char -> Bool) -> ByteString -> Maybe Char

-- | <i>O(n)</i> <a>filter</a>, applied to a predicate and a ByteString,
°5ureturns a ByteString containing those characters that satisfy the
°5upredicate.
filter :: (Char -> Bool) -> ByteString -> ByteString

-- | <i>O(1)</i> <a>ByteString</a> index (subscript) operator, starting
°5ufrom 0.
index :: ByteString -> Int -> Char

-- | <i>O(n)</i> The <a>elemIndex</a> function returns the index of the
°5ufirst element in the given <a>ByteString</a> which is equal (by
°5umemchr) to the query element, or <a>Nothing</a> if there is no such
°5uelement.
elemIndex :: Char -> ByteString -> Maybe Int

-- | <i>O(n)</i> The <a>elemIndices</a> function extends <a>elemIndex</a>,
°5uby returning the indices of all elements equal to the query element,
°5uin ascending order.
elemIndices :: Char -> ByteString -> [Int]

-- | <i>O(n)</i> The <a>elemIndexEnd</a> function returns the last index of
°5uthe element in the given <a>ByteString</a> which is equal to the query
°5uelement, or <a>Nothing</a> if there is no such element. The following
°5uholds:
°5u
°5u<pre>
°5uelemIndexEnd c xs ==
°5u(-) (length xs - 1) `fmap` elemIndex c (reverse xs)
°5u</pre>
elemIndexEnd :: Char -> ByteString -> Maybe Int

-- | The <a>findIndex</a> function takes a predicate and a
°5u<a>ByteString</a> and returns the index of the first element in the
°5uByteString satisfying the predicate.
findIndex :: (Char -> Bool) -> ByteString -> Maybe Int

-- | The <a>findIndices</a> function extends <a>findIndex</a>, by returning
°5uthe indices of all elements satisfying the predicate, in ascending
°5uorder.
findIndices :: (Char -> Bool) -> ByteString -> [Int]

-- | count returns the number of times its argument appears in the
°5uByteString
°5u
°5u<pre>
°5ucount = length . elemIndices
°5u</pre>
°5u
°5uAlso
°5u
°5u<pre>
°5ucount '\n' == length . lines
°5u</pre>
°5u
°5uBut more efficiently than using length on the intermediate list.
count :: Char -> ByteString -> Int

-- | <i>O(n)</i> <a>zip</a> takes two ByteStrings and returns a list of
°5ucorresponding pairs of Chars. If one input ByteString is short, excess
°5uelements of the longer ByteString are discarded. This is equivalent to
°5ua pair of <a>unpack</a> operations, and so space usage may be large
°5ufor multi-megabyte ByteStrings
zip :: ByteString -> ByteString -> [(Char, Char)]

-- | <a>zipWith</a> generalises <a>zip</a> by zipping with the function
°5ugiven as the first argument, instead of a tupling function. For
°5uexample, <tt><a>zipWith</a> (+)</tt> is applied to two ByteStrings to
°5uproduce the list of corresponding sums.
zipWith :: (Char -> Char -> a) -> ByteString -> ByteString -> [a]

-- | <a>unzip</a> transforms a list of pairs of Chars into a pair of
°5uByteStrings. Note that this performs two <a>pack</a> operations.
unzip :: [(Char, Char)] -> (ByteString, ByteString)

-- | <i>O(n)</i> Sort a ByteString efficiently, using counting sort.
sort :: ByteString -> ByteString

-- | readInt reads an Int from the beginning of the ByteString. If there is
°5uno integer at the beginning of the string, it returns Nothing,
°5uotherwise it just returns the int read, and the rest of the string.
readInt :: ByteString -> Maybe (Int, ByteString)

-- | readInteger reads an Integer from the beginning of the ByteString. If
°5uthere is no integer at the beginning of the string, it returns
°5uNothing, otherwise it just returns the int read, and the rest of the
°5ustring.
readInteger :: ByteString -> Maybe (Integer, ByteString)

-- | <i>O(n)</i> Make a copy of the <a>ByteString</a> with its own storage.
°5uThis is mainly useful to allow the rest of the data pointed to by the
°5u<a>ByteString</a> to be garbage collected, for example if a large
°5ustring has been read in, and only a small part of it is needed in the
°5urest of the program.
copy :: ByteString -> ByteString

-- | <i>O(n).</i> Construct a new <tt>ByteString</tt> from a
°5u<tt>CString</tt>. The resulting <tt>ByteString</tt> is an immutable
°5ucopy of the original <tt>CString</tt>, and is managed on the Haskell
°5uheap. The original <tt>CString</tt> must be null terminated.
packCString :: CString -> IO ByteString

-- | <i>O(n).</i> Construct a new <tt>ByteString</tt> from a
°5u<tt>CStringLen</tt>. The resulting <tt>ByteString</tt> is an immutable
°5ucopy of the original <tt>CStringLen</tt>. The <tt>ByteString</tt> is a
°5unormal Haskell value and will be managed on the Haskell heap.
packCStringLen :: CStringLen -> IO ByteString

-- | <i>O(n) construction</i> Use a <tt>ByteString</tt> with a function
°5urequiring a null-terminated <tt>CString</tt>. The <tt>CString</tt> is
°5ua copy and will be freed automatically; it must not be stored or used
°5uafter the subcomputation finishes.
useAsCString :: ByteString -> (CString -> IO a) -> IO a

-- | <i>O(n) construction</i> Use a <tt>ByteString</tt> with a function
°5urequiring a <tt>CStringLen</tt>. As for <tt>useAsCString</tt> this
°5ufunction makes a copy of the original <tt>ByteString</tt>. It must not
°5ube stored or used after the subcomputation finishes.
useAsCStringLen :: ByteString -> (CStringLen -> IO a) -> IO a

-- | Read a line from stdin.
getLine :: IO ByteString

-- | getContents. Read stdin strictly. Equivalent to hGetContents stdin The
°5u<a>Handle</a> is closed after the contents have been read.
getContents :: IO ByteString

-- | Write a ByteString to stdout
putStr :: ByteString -> IO ()

-- | Write a ByteString to stdout, appending a newline byte
putStrLn :: ByteString -> IO ()

-- | The interact function takes a function of type <tt>ByteString -&gt;
°5uByteString</tt> as its argument. The entire input from the standard
°5uinput device is passed to this function as its argument, and the
°5uresulting string is output on the standard output device.
interact :: (ByteString -> ByteString) -> IO ()

-- | Read an entire file strictly into a <a>ByteString</a>.
readFile :: FilePath -> IO ByteString

-- | Write a <a>ByteString</a> to a file.
writeFile :: FilePath -> ByteString -> IO ()

-- | Append a <a>ByteString</a> to a file.
appendFile :: FilePath -> ByteString -> IO ()

-- | Read a line from a handle
hGetLine :: Handle -> IO ByteString

-- | Read a handle's entire contents strictly into a <a>ByteString</a>.
°5u
°5uThis function reads chunks at a time, increasing the chunk size on
°5ueach read. The final string is then realloced to the appropriate size.
°5uFor files &gt; half of available memory, this may lead to memory
°5uexhaustion. Consider using <a>readFile</a> in this case.
°5u
°5uThe Handle is closed once the contents have been read, or if an
°5uexception is thrown.
hGetContents :: Handle -> IO ByteString

-- | Read a <a>ByteString</a> directly from the specified <a>Handle</a>.
°5uThis is far more efficient than reading the characters into a
°5u<a>String</a> and then using <a>pack</a>. First argument is the Handle
°5uto read from, and the second is the number of bytes to read. It
°5ureturns the bytes read, up to n, or <a>empty</a> if EOF has been
°5ureached.
°5u
°5u<a>hGet</a> is implemented in terms of <a>hGetBuf</a>.
°5u
°5uIf the handle is a pipe or socket, and the writing end is closed,
°5u<a>hGet</a> will behave as if EOF was reached.
hGet :: Handle -> Int -> IO ByteString

-- | Like <a>hGet</a>, except that a shorter <a>ByteString</a> may be
°5ureturned if there are not enough bytes immediately available to
°5usatisfy the whole request. <a>hGetSome</a> only blocks if there is no
°5udata available, and EOF has not yet been reached.
hGetSome :: Handle -> Int -> IO ByteString

-- | hGetNonBlocking is similar to <a>hGet</a>, except that it will never
°5ublock waiting for data to become available, instead it returns only
°5uwhatever data is available. If there is no data available to be read,
°5u<a>hGetNonBlocking</a> returns <a>empty</a>.
°5u
°5uNote: on Windows and with Haskell implementation other than GHC, this
°5ufunction does not work correctly; it behaves identically to
°5u<a>hGet</a>.
hGetNonBlocking :: Handle -> Int -> IO ByteString

-- | Outputs a <a>ByteString</a> to the specified <a>Handle</a>.
hPut :: Handle -> ByteString -> IO ()

-- | Similar to <a>hPut</a> except that it will never block. Instead it
°5ureturns any tail that did not get written. This tail may be
°5u<a>empty</a> in the case that the whole string was written, or the
°5uwhole original string if nothing was written. Partial writes are also
°5upossible.
°5u
°5uNote: on Windows and with Haskell implementation other than GHC, this
°5ufunction does not work correctly; it behaves identically to
°5u<a>hPut</a>.
hPutNonBlocking :: Handle -> ByteString -> IO ByteString

-- | A synonym for <tt>hPut</tt>, for compatibility
hPutStr :: Handle -> ByteString -> IO ()

-- | Write a ByteString to a handle, appending a newline byte
hPutStrLn :: Handle -> ByteString -> IO ()


-- | This module provides <a>Builder</a> <i>primitives</i>, which are lower
°5ulevel building blocks for constructing <a>Builder</a>s. You don't need
°5uto go down to this level but it can be slightly faster.
°5u
°5uMorally, builder primitives are like functions <tt>a -&gt;
°5uBuilder</tt>, that is they take a value and encode it as a sequence of
°5ubytes, represented as a <a>Builder</a>. Of course their implementation
°5uis a bit more specialised.
°5u
°5uBuilder primitives come in two forms: fixed-size and bounded-size.
°5u
°5u<ul>
°5u<li><i>Fixed(-size) primitives</i> are builder primitives that always
°5uresult in a sequence of bytes of a fixed length. That is, the length
°5uis independent of the value that is encoded. An example of a fixed
°5usize primitive is the big-endian encoding of a <a>Word64</a>, which
°5ualways results in exactly 8 bytes.</li>
°5u<li><i>Bounded(-size) primitives</i> are builder primitives that
°5ualways result in a sequence of bytes that is no larger than a
°5upredetermined bound. That is, the bound is independent of the value
°5uthat is encoded but the actual length will depend on the value. An
°5uexample for a bounded primitive is the UTF-8 encoding of a
°5u<a>Char</a>, which can be 1,2,3 or 4 bytes long, so the bound is 4
°5ubytes.</li>
°5u</ul>
°5u
°5uNote that fixed primitives can be considered as a special case of
°5ubounded primitives, and we can lift from fixed to bounded.
°5u
°5uBecause bounded primitives are the more general case, in this
°5udocumentation we only refer to fixed size primitives where it matters
°5uthat the resulting sequence of bytes is of a fixed length. Otherwise,
°5uwe just refer to bounded size primitives.
°5u
°5uThe purpose of using builder primitives is to improve the performance
°5uof <a>Builder</a>s. These improvements stem from making the two most
°5ucommon steps performed by a <a>Builder</a> more efficient. We explain
°5uthese two steps in turn.
°5u
°5uThe first most common step is the concatenation of two
°5u<a>Builder</a>s. Internally, concatenation corresponds to function
°5ucomposition. (Note that <a>Builder</a>s can be seen as
°5udifference-lists of buffer-filling functions; cf.
°5u<a>http://hackage.haskell.org/cgi-bin/hackage-scripts/package/dlist</a>.
°5u) Function composition is a fast <i>O(1)</i> operation. However, we
°5ucan use bounded primitives to remove some of these function
°5ucompositions altogether, which is more efficient.
°5u
°5uThe second most common step performed by a <a>Builder</a> is to fill a
°5ubuffer using a bounded primitives, which works as follows. The
°5u<a>Builder</a> checks whether there is enough space left to execute
°5uthe bounded primitive. If there is, then the <a>Builder</a> executes
°5uthe bounded primitive and calls the next <a>Builder</a> with the
°5uupdated buffer. Otherwise, the <a>Builder</a> signals its driver that
°5uit requires a new buffer. This buffer must be at least as large as the
°5ubound of the primitive. We can use bounded primitives to reduce the
°5unumber of buffer-free checks by fusing the buffer-free checks of
°5uconsecutive <a>Builder</a>s. We can also use bounded primitives to
°5usimplify the control flow for signalling that a buffer is full by
°5uensuring that we check first that there is enough space left and only
°5uthen decide on how to encode a given value.
°5u
°5uLet us illustrate these improvements on the CSV-table rendering
°5uexample from <a>Data.ByteString.Builder</a>. Its "hot code" is the
°5urendering of a table's cells, which we implement as follows using only
°5uthe functions from the <a>Builder</a> API.
°5u
°5u<pre>
°5uimport <a>Data.ByteString.Builder</a> as B
°5u
°5urenderCell :: Cell -&gt; Builder
°5urenderCell (StringC cs) = renderString cs
°5urenderCell (IntC i)     = B.intDec i
°5u
°5urenderString :: String -&gt; Builder
°5urenderString cs = B.charUtf8 '"' &lt;&gt; foldMap escape cs &lt;&gt; B.charUtf8 '"'
°5u  where
°5u    escape '\\' = B.charUtf8 '\\' &lt;&gt; B.charUtf8 '\\'
°5u    escape '\"' = B.charUtf8 '\\' &lt;&gt; B.charUtf8 '\"'
°5u    escape c    = B.charUtf8 c
°5u</pre>
°5u
°5uEfficient encoding of <a>Int</a>s as decimal numbers is performed by
°5u<tt>intDec</tt>. Optimization potential exists for the escaping of
°5u<a>String</a>s. The above implementation has two optimization
°5uopportunities. First, the buffer-free checks of the <a>Builder</a>s
°5ufor escaping double quotes and backslashes can be fused. Second, the
°5uconcatenations performed by <a>foldMap</a> can be eliminated. The
°5ufollowing implementation exploits these optimizations.
°5u
°5u<pre>
°5uimport qualified Data.ByteString.Builder.Prim  as P
°5uimport           Data.ByteString.Builder.Prim
°5u                 ( <a>condB</a>, <a>liftFixedToBounded</a>, (<a>&gt;*&lt;</a>), (<a>&gt;$&lt;</a>) )
°5u
°5urenderString :: String -&gt; Builder
°5urenderString cs =
°5u    B.charUtf8 '"' &lt;&gt; E.<tt>encodeListWithB</tt> escape cs &lt;&gt; B.charUtf8 '"'
°5u  where
°5u    escape :: E.<a>BoundedPrim</a> Char
°5u    escape =
°5u      <a>condB</a> (== '\\') (fixed2 ('\\', '\\')) $
°5u      <a>condB</a> (== '\"') (fixed2 ('\\', '\"')) $
°5u      E.<a>charUtf8</a>
°5u     
°5u    {-# INLINE fixed2 #-}
°5u    fixed2 x = <a>liftFixedToBounded</a> $ const x <a>&gt;$&lt;</a> E.<a>char7</a> <a>&gt;*&lt;</a> E.<a>char7</a>
°5u</pre>
°5u
°5uThe code should be mostly self-explanatory. The slightly awkward
°5usyntax is because the combinators are written such that the size-bound
°5uof the resulting <a>BoundedPrim</a> can be computed at compile time.
°5uWe also explicitly inline the <tt>fixed2</tt> primitive, which encodes
°5ua fixed tuple of characters, to ensure that the bound computation
°5uhappens at compile time. When encoding the following list of
°5u<a>String</a>s, the optimized implementation of <tt>renderString</tt>
°5uis two times faster.
°5u
°5u<pre>
°5umaxiStrings :: [String]
°5umaxiStrings = take 1000 $ cycle ["hello", "\"1\"", "λ-wörld"]
°5u</pre>
°5u
°5uMost of the performance gain stems from using
°5u<a>primMapListBounded</a>, which encodes a list of values from
°5uleft-to-right with a <a>BoundedPrim</a>. It exploits the
°5u<a>Builder</a> internals to avoid unnecessary function compositions
°5u(i.e., concatenations). In the future, we might expect the compiler to
°5uperform the optimizations implemented in <a>primMapListBounded</a>.
°5uHowever, it seems that the code is currently to complicated for the
°5ucompiler to see through. Therefore, we provide the <a>BoundedPrim</a>
°5uescape hatch, which allows data structures to provide very efficient
°5uencoding traversals, like <a>primMapListBounded</a> for lists.
°5u
°5uNote that <a>BoundedPrim</a>s are a bit verbose, but quite versatile.
°5uHere is an example of a <a>BoundedPrim</a> for combined HTML escaping
°5uand UTF-8 encoding. It exploits that the escaped character with the
°5umaximal Unicode codepoint is '&gt;'.
°5u
°5u<pre>
°5u{-# INLINE charUtf8HtmlEscaped #-}
°5ucharUtf8HtmlEscaped :: E.BoundedPrim Char
°5ucharUtf8HtmlEscaped =
°5u    <a>condB</a> (&gt;  '&gt;' ) E.<a>charUtf8</a> $
°5u    <a>condB</a> (== '&lt;' ) (fixed4 ('&amp;',('l',('t',';')))) $        -- &amp;lt;
°5u    <a>condB</a> (== '&gt;' ) (fixed4 ('&amp;',('g',('t',';')))) $        -- &amp;gt;
°5u    <a>condB</a> (== '&amp;' ) (fixed5 ('&amp;',('a',('m',('p',';'))))) $  -- &amp;amp;
°5u    <a>condB</a> (== '"' ) (fixed5 ('&amp;',('#',('3',('4',';'))))) $  -- &amp;#34;
°5u    <a>condB</a> (== '\'') (fixed5 ('&amp;',('#',('3',('9',';'))))) $  -- &amp;#39;
°5u    (<a>liftFixedToBounded</a> E.<a>char7</a>)         -- fallback for <a>Char</a>s smaller than '&gt;'
°5u  where
°5u    {-# INLINE fixed4 #-}
°5u    fixed4 x = <a>liftFixedToBounded</a> $ const x <a>&gt;$&lt;</a>
°5u      E.char7 <a>&gt;*&lt;</a> E.char7 <a>&gt;*&lt;</a> E.char7 <a>&gt;*&lt;</a> E.char7
°5u     
°5u    {-# INLINE fixed5 #-}
°5u    fixed5 x = <a>liftFixedToBounded</a> $ const x <a>&gt;$&lt;</a>
°5u      E.char7 <a>&gt;*&lt;</a> E.char7 <a>&gt;*&lt;</a> E.char7 <a>&gt;*&lt;</a> E.char7 <a>&gt;*&lt;</a> E.char7
°5u</pre>
°5u
°5uThis module currently does not expose functions that require the
°5uspecial properties of fixed-size primitives. They are useful for
°5uprefixing <a>Builder</a>s with their size or for implementing chunked
°5uencodings. We will expose the corresponding functions in future
°5ureleases of this library.
module Data.ByteString.Builder.Prim

-- | A builder primitive that always results in sequence of bytes that is
°5uno longer than a pre-determined bound.
data BoundedPrim a

-- | The <a>BoundedPrim</a> that always results in the zero-length
°5usequence.
emptyB :: BoundedPrim a

-- | A pairing/concatenation operator for builder primitives, both bounded
°5uand fixed size.
°5u
°5uFor example,
°5u
°5u<pre>
°5utoLazyByteString (primFixed (char7 &gt;*&lt; char7) ('x','y')) = "xy"
°5u</pre>
°5u
°5uWe can combine multiple primitives using <a>&gt;*&lt;</a> multiple
°5utimes.
°5u
°5u<pre>
°5utoLazyByteString (primFixed (char7 &gt;*&lt; char7 &gt;*&lt; char7) ('x',('y','z'))) = "xyz"
°5u</pre>
(>*<) :: Monoidal f => f a -> f b -> f (a, b)
infixr 5 >*<

-- | A fmap-like operator for builder primitives, both bounded and fixed
°5usize.
°5u
°5uBuilder primitives are contravariant so it's like the normal fmap, but
°5ubackwards (look at the type). (If it helps to remember, the operator
°5usymbol is like (<a>$</a>) but backwards.)
°5u
°5uWe can use it for example to prepend and/or append fixed values to an
°5uprimitive.
°5u
°5u<pre>
°5ushowEncoding ((\x -&gt; ('\'', (x, '\''))) &gt;$&lt; fixed3) 'x' = "'x'"
°5u  where
°5u    fixed3 = char7 &gt;*&lt; char7 &gt;*&lt; char7
°5u</pre>
°5u
°5uNote that the rather verbose syntax for composition stems from the
°5urequirement to be able to compute the size / size bound at compile
°5utime.
(>$<) :: Contravariant f => (b -> a) -> f a -> f b
infixl 4 >$<

-- | Encode an <a>Either</a> value using the first <a>BoundedPrim</a> for
°5u<a>Left</a> values and the second <a>BoundedPrim</a> for <a>Right</a>
°5uvalues.
°5u
°5uNote that the functions <a>eitherB</a>, <a>pairB</a>, and
°5u<a>contramapB</a> (written below using <a>&gt;$&lt;</a>) suffice to
°5uconstruct <a>BoundedPrim</a>s for all non-recursive algebraic
°5udatatypes. For example,
°5u
°5u<pre>
°5umaybeB :: BoundedPrim () -&gt; BoundedPrim a -&gt; BoundedPrim (Maybe a)
°5umaybeB nothing just = <a>maybe</a> (Left ()) Right <a>&gt;$&lt;</a> eitherB nothing just
°5u 
°5u</pre>
eitherB :: BoundedPrim a -> BoundedPrim b -> BoundedPrim (Either a b)

-- | Conditionally select a <a>BoundedPrim</a>. For example, we can
°5uimplement the ASCII primitive that drops characters with Unicode
°5ucodepoints above 127 as follows.
°5u
°5u<pre>
°5ucharASCIIDrop = <a>condB</a> (&lt; '\128') (<tt>fromF</tt> <tt>char7</tt>) <a>emptyB</a>
°5u 
°5u</pre>
condB :: (a -> Bool) -> BoundedPrim a -> BoundedPrim a -> BoundedPrim a

-- | Create a <a>Builder</a> that encodes values with the given
°5u<a>BoundedPrim</a>.
°5u
°5uWe rewrite consecutive uses of <a>primBounded</a> such that the
°5ubound-checks are fused. For example,
°5u
°5u<pre>
°5uprimBounded (word32 c1) `mappend` primBounded (word32 c2)
°5u</pre>
°5u
°5uis rewritten such that the resulting <a>Builder</a> checks only once,
°5uif ther are at 8 free bytes, instead of checking twice, if there are 4
°5ufree bytes. This optimization is not observationally equivalent in a
°5ustrict sense, as it influences the boundaries of the generated chunks.
°5uHowever, for a user of this library it is observationally equivalent,
°5uas chunk boundaries of a lazy <a>ByteString</a> can only be observed
°5uthrough the internal interface. Morevoer, we expect that all
°5uprimitives write much fewer than 4kb (the default short buffer size).
°5uHence, it is safe to ignore the additional memory spilled due to the
°5umore agressive buffer wrapping introduced by this optimization.
primBounded :: BoundedPrim a -> (a -> Builder)

-- | Create a <a>Builder</a> that encodes a list of values consecutively
°5uusing a <a>BoundedPrim</a> for each element. This function is more
°5uefficient than the canonical
°5u
°5u<pre>
°5ufilter p =
°5u B.toLazyByteString .
°5u E.encodeLazyByteStringWithF (E.ifF p E.word8) E.emptyF)
°5u</pre>
°5u
°5u<pre>
°5umconcat . map (primBounded w)
°5u</pre>
°5u
°5uor
°5u
°5u<pre>
°5ufoldMap (primBounded w)
°5u</pre>
°5u
°5ubecause it moves several variables out of the inner loop.
primMapListBounded :: BoundedPrim a -> [a] -> Builder

-- | Create a <a>Builder</a> that encodes a sequence generated from a seed
°5uvalue using a <a>BoundedPrim</a> for each sequence element.
primUnfoldrBounded :: BoundedPrim b -> (a -> Maybe (b, a)) -> a -> Builder

-- | Create a <a>Builder</a> that encodes each <a>Word8</a> of a strict
°5u<a>ByteString</a> using a <a>BoundedPrim</a>. For example, we can
°5uwrite a <a>Builder</a> that filters a strict <a>ByteString</a> as
°5ufollows.
°5u
°5u<pre>
°5uimport Data.ByteString.Builder.Primas P (word8, condB, emptyB)
°5u</pre>
°5u
°5u<pre>
°5ufilterBS p = P.condB p P.word8 P.emptyB
°5u</pre>
primMapByteStringBounded :: BoundedPrim Word8 -> ByteString -> Builder

-- | Chunk-wise application of <a>primMapByteStringBounded</a>.
primMapLazyByteStringBounded :: BoundedPrim Word8 -> ByteString -> Builder

-- | A builder primitive that always results in a sequence of bytes of a
°5upre-determined, fixed size.
data FixedPrim a

-- | The <a>FixedPrim</a> that always results in the zero-length sequence.
emptyF :: FixedPrim a

-- | Lift a <a>FixedPrim</a> to a <a>BoundedPrim</a>.
liftFixedToBounded :: FixedPrim a -> BoundedPrim a

-- | Encode a value with a <a>FixedPrim</a>.
primFixed :: FixedPrim a -> (a -> Builder)

-- | Encode a list of values from left-to-right with a <a>FixedPrim</a>.
primMapListFixed :: FixedPrim a -> ([a] -> Builder)

-- | Encode a list of values represented as an <a>unfoldr</a> with a
°5u<a>FixedPrim</a>.
primUnfoldrFixed :: FixedPrim b -> (a -> Maybe (b, a)) -> a -> Builder

-- | <i>Heavy inlining.</i> Encode all bytes of a strict <a>ByteString</a>
°5ufrom left-to-right with a <a>FixedPrim</a>. This function is quite
°5uversatile. For example, we can use it to construct a <a>Builder</a>
°5uthat maps every byte before copying it to the buffer to be filled.
°5u
°5u<pre>
°5umapToBuilder :: (Word8 -&gt; Word8) -&gt; S.ByteString -&gt; Builder
°5umapToBuilder f = encodeByteStringWithF (contramapF f word8)
°5u</pre>
°5u
°5uWe can also use it to hex-encode a strict <a>ByteString</a> as shown
°5uby the <tt>byteStringHex</tt> example above.
primMapByteStringFixed :: FixedPrim Word8 -> (ByteString -> Builder)

-- | <i>Heavy inlining.</i> Encode all bytes of a lazy <a>ByteString</a>
°5ufrom left-to-right with a <a>FixedPrim</a>.
primMapLazyByteStringFixed :: FixedPrim Word8 -> (ByteString -> Builder)

-- | Encoding single signed bytes as-is.
int8 :: FixedPrim Int8

-- | Encoding single unsigned bytes as-is.
word8 :: FixedPrim Word8

-- | Encoding <a>Int16</a>s in big endian format.
int16BE :: FixedPrim Int16

-- | Encoding <a>Int32</a>s in big endian format.
int32BE :: FixedPrim Int32

-- | Encoding <a>Int64</a>s in big endian format.
int64BE :: FixedPrim Int64

-- | Encoding <a>Word16</a>s in big endian format.
word16BE :: FixedPrim Word16

-- | Encoding <a>Word32</a>s in big endian format.
word32BE :: FixedPrim Word32

-- | Encoding <a>Word64</a>s in big endian format.
word64BE :: FixedPrim Word64

-- | Encode a <a>Float</a> in big endian format.
floatBE :: FixedPrim Float

-- | Encode a <a>Double</a> in big endian format.
doubleBE :: FixedPrim Double

-- | Encoding <a>Int16</a>s in little endian format.
int16LE :: FixedPrim Int16

-- | Encoding <a>Int32</a>s in little endian format.
int32LE :: FixedPrim Int32

-- | Encoding <a>Int64</a>s in little endian format.
int64LE :: FixedPrim Int64

-- | Encoding <a>Word16</a>s in little endian format.
word16LE :: FixedPrim Word16

-- | Encoding <a>Word32</a>s in little endian format.
word32LE :: FixedPrim Word32

-- | Encoding <a>Word64</a>s in little endian format.
word64LE :: FixedPrim Word64

-- | Encode a <a>Float</a> in little endian format.
floatLE :: FixedPrim Float

-- | Encode a <a>Double</a> in little endian format.
doubleLE :: FixedPrim Double

-- | Encode a single native machine <a>Int</a>. The <a>Int</a>s is encoded
°5uin host order, host endian form, for the machine you are on. On a 64
°5ubit machine the <a>Int</a> is an 8 byte value, on a 32 bit machine, 4
°5ubytes. Values encoded this way are not portable to different endian or
°5uinteger sized machines, without conversion.
intHost :: FixedPrim Int

-- | Encoding <a>Int16</a>s in native host order and host endianness.
int16Host :: FixedPrim Int16

-- | Encoding <a>Int32</a>s in native host order and host endianness.
int32Host :: FixedPrim Int32

-- | Encoding <a>Int64</a>s in native host order and host endianness.
int64Host :: FixedPrim Int64

-- | Encode a single native machine <a>Word</a>. The <a>Word</a>s is
°5uencoded in host order, host endian form, for the machine you are on.
°5uOn a 64 bit machine the <a>Word</a> is an 8 byte value, on a 32 bit
°5umachine, 4 bytes. Values encoded this way are not portable to
°5udifferent endian or word sized machines, without conversion.
wordHost :: FixedPrim Word

-- | Encoding <a>Word16</a>s in native host order and host endianness.
word16Host :: FixedPrim Word16

-- | Encoding <a>Word32</a>s in native host order and host endianness.
word32Host :: FixedPrim Word32

-- | Encoding <a>Word64</a>s in native host order and host endianness.
word64Host :: FixedPrim Word64

-- | Encode a <a>Float</a> in native host order and host endianness. Values
°5uwritten this way are not portable to different endian machines,
°5uwithout conversion.
floatHost :: FixedPrim Float

-- | Encode a <a>Double</a> in native host order and host endianness.
doubleHost :: FixedPrim Double

-- | Encode the least 7-bits of a <a>Char</a> using the ASCII encoding.
char7 :: FixedPrim Char

-- | Decimal encoding of an <a>Int8</a>.
int8Dec :: BoundedPrim Int8

-- | Decimal encoding of an <a>Int16</a>.
int16Dec :: BoundedPrim Int16

-- | Decimal encoding of an <a>Int32</a>.
int32Dec :: BoundedPrim Int32

-- | Decimal encoding of an <a>Int64</a>.
int64Dec :: BoundedPrim Int64

-- | Decimal encoding of an <a>Int</a>.
intDec :: BoundedPrim Int

-- | Decimal encoding of a <a>Word8</a>.
word8Dec :: BoundedPrim Word8

-- | Decimal encoding of a <a>Word16</a>.
word16Dec :: BoundedPrim Word16

-- | Decimal encoding of a <a>Word32</a>.
word32Dec :: BoundedPrim Word32

-- | Decimal encoding of a <a>Word64</a>.
word64Dec :: BoundedPrim Word64

-- | Decimal encoding of a <a>Word</a>.
wordDec :: BoundedPrim Word

-- | Hexadecimal encoding of a <a>Word8</a>.
word8Hex :: BoundedPrim Word8

-- | Hexadecimal encoding of a <a>Word16</a>.
word16Hex :: BoundedPrim Word16

-- | Hexadecimal encoding of a <a>Word32</a>.
word32Hex :: BoundedPrim Word32

-- | Hexadecimal encoding of a <a>Word64</a>.
word64Hex :: BoundedPrim Word64

-- | Hexadecimal encoding of a <a>Word</a>.
wordHex :: BoundedPrim Word

-- | Encode a <a>Int8</a> using 2 nibbles (hexadecimal digits).
int8HexFixed :: FixedPrim Int8

-- | Encode a <a>Int16</a> using 4 nibbles.
int16HexFixed :: FixedPrim Int16

-- | Encode a <a>Int32</a> using 8 nibbles.
int32HexFixed :: FixedPrim Int32

-- | Encode a <a>Int64</a> using 16 nibbles.
int64HexFixed :: FixedPrim Int64

-- | Encode a <a>Word8</a> using 2 nibbles (hexadecimal digits).
word8HexFixed :: FixedPrim Word8

-- | Encode a <a>Word16</a> using 4 nibbles.
word16HexFixed :: FixedPrim Word16

-- | Encode a <a>Word32</a> using 8 nibbles.
word32HexFixed :: FixedPrim Word32

-- | Encode a <a>Word64</a> using 16 nibbles.
word64HexFixed :: FixedPrim Word64

-- | Encode an IEEE <a>Float</a> using 8 nibbles.
floatHexFixed :: FixedPrim Float

-- | Encode an IEEE <a>Double</a> using 16 nibbles.
doubleHexFixed :: FixedPrim Double

-- | Char8 encode a <a>Char</a>.
char8 :: FixedPrim Char

-- | UTF-8 encode a <a>Char</a>.
charUtf8 :: BoundedPrim Char


-- | Extra functions for creating and executing <a>Builder</a>s. They are
°5uintended for application-specific fine-tuning the performance of
°5u<a>Builder</a>s.
module Data.ByteString.Builder.Extra

-- | <i>Heavy inlining.</i> Execute a <a>Builder</a> with custom execution
°5uparameters.
°5u
°5uThis function is inlined despite its heavy code-size to allow fusing
°5uwith the allocation strategy. For example, the default <a>Builder</a>
°5uexecution function <tt>toLazyByteString</tt> is defined as follows.
°5u
°5u<pre>
°5u{-# NOINLINE toLazyByteString #-}
°5utoLazyByteString =
°5u  toLazyByteStringWith (<a>safeStrategy</a> <a>smallChunkSize</a> <a>defaultChunkSize</a>) L.empty
°5u</pre>
°5u
°5uwhere <tt>L.empty</tt> is the zero-length lazy <a>ByteString</a>.
°5u
°5uIn most cases, the parameters used by <tt>toLazyByteString</tt> give
°5ugood performance. A sub-performing case of <tt>toLazyByteString</tt>
°5uis executing short (&lt;128 bytes) <a>Builder</a>s. In this case, the
°5uallocation overhead for the first 4kb buffer and the trimming cost
°5udominate the cost of executing the <a>Builder</a>. You can avoid this
°5uproblem using
°5u
°5u<pre>
°5utoLazyByteStringWith (safeStrategy 128 smallChunkSize) L.empty
°5u</pre>
°5u
°5uThis reduces the allocation and trimming overhead, as all generated
°5u<a>ByteString</a>s fit into the first buffer and there is no trimming
°5urequired, if more than 64 bytes and less than 128 bytes are written.
toLazyByteStringWith :: AllocationStrategy -> ByteString -> Builder -> ByteString

-- | A buffer allocation strategy for executing <a>Builder</a>s.
data AllocationStrategy

-- | Use this strategy for generating lazy <a>ByteString</a>s whose chunks
°5uare likely to survive one garbage collection. This strategy trims
°5ubuffers that are filled less than half in order to avoid spilling too
°5umuch memory.
safeStrategy :: Int -> Int -> AllocationStrategy

-- | Use this strategy for generating lazy <a>ByteString</a>s whose chunks
°5uare discarded right after they are generated. For example, if you just
°5ugenerate them to write them to a network socket.
untrimmedStrategy :: Int -> Int -> AllocationStrategy

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

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

-- | Construct a <a>Builder</a> that copies the strict <a>ByteString</a>.
°5u
°5uUse this function to create <a>Builder</a>s from smallish (<tt>&lt;=
°5u4kb</tt>) <a>ByteString</a>s or if you need to guarantee that the
°5u<a>ByteString</a> is not shared with the chunks generated by the
°5u<a>Builder</a>.
byteStringCopy :: ByteString -> Builder

-- | Construct a <a>Builder</a> that always inserts the strict
°5u<a>ByteString</a> directly as a chunk.
°5u
°5uThis implies flushing the output buffer, even if it contains just a
°5usingle byte. You should therefore use <a>byteStringInsert</a> only for
°5ularge (<tt>&gt; 8kb</tt>) <a>ByteString</a>s. Otherwise, the generated
°5uchunks are too fragmented to be processed efficiently afterwards.
byteStringInsert :: ByteString -> Builder

-- | Construct a <a>Builder</a> that copies the strict <a>ByteString</a>s,
°5uif it is smaller than the treshold, and inserts it directly otherwise.
°5u
°5uFor example, <tt>byteStringThreshold 1024</tt> copies strict
°5u<a>ByteString</a>s whose size is less or equal to 1kb, and inserts
°5uthem directly otherwise. This implies that the average chunk-size of
°5uthe generated lazy <a>ByteString</a> may be as low as 513 bytes, as
°5uthere could always be just a single byte between the directly inserted
°5u1025 byte, strict <a>ByteString</a>s.
byteStringThreshold :: Int -> ByteString -> Builder

-- | Construct a <a>Builder</a> that copies the lazy <a>ByteString</a>.
lazyByteStringCopy :: ByteString -> Builder

-- | Construct a <a>Builder</a> that inserts all chunks of the lazy
°5u<a>ByteString</a> directly.
lazyByteStringInsert :: ByteString -> Builder

-- | Construct a <a>Builder</a> that uses the thresholding strategy of
°5u<a>byteStringThreshold</a> for each chunk of the lazy
°5u<a>ByteString</a>.
lazyByteStringThreshold :: Int -> ByteString -> Builder

-- | Flush the current buffer. This introduces a chunk boundary.
flush :: Builder

-- | A <a>BufferWriter</a> represents the result of running a
°5u<a>Builder</a>. It unfolds as a sequence of chunks of data. These
°5uchunks come in two forms:
°5u
°5u<ul>
°5u<li>an IO action for writing the Builder's data into a user-supplied
°5umemory buffer.</li>
°5u<li>a pre-existing chunks of data represented by a strict
°5u<tt>ByteString</tt></li>
°5u</ul>
°5u
°5uWhile this is rather low level, it provides you with full flexibility
°5uin how the data is written out.
°5u
°5uThe <a>BufferWriter</a> itself is an IO action: you supply it with a
°5ubuffer (as a pointer and length) and it will write data into the
°5ubuffer. It returns a number indicating how many bytes were actually
°5uwritten (which can be <tt>0</tt>). It also returns a <a>Next</a> which
°5udescribes what comes next.
type BufferWriter = Ptr Word8 -> Int -> IO (Int, Next)

-- | After running a <a>BufferWriter</a> action there are three
°5upossibilities for what comes next:
data Next

-- | This means we're all done. All the builder data has now been written.
Done :: Next

-- | This indicates that there may be more data to write. It gives you the
°5unext <a>BufferWriter</a> action. You should call that action with an
°5uappropriate buffer. The int indicates the <i>minimum</i> buffer size
°5urequired by the next <a>BufferWriter</a> action. That is, if you call
°5uthe next action you <i>must</i> supply it with a buffer length of at
°5uleast this size.
More :: !Int -> BufferWriter -> Next

-- | In addition to the data that has just been written into your buffer by
°5uthe <a>BufferWriter</a> action, it gives you a pre-existing chunk of
°5udata as a <a>ByteString</a>. It also gives you the following
°5u<a>BufferWriter</a> action. It is safe to run this following action
°5uusing a buffer with as much free space as was left by the previous run
°5uaction.
Chunk :: !ByteString -> BufferWriter -> Next

-- | Turn a <a>Builder</a> into its initial <a>BufferWriter</a> action.
runBuilder :: Builder -> BufferWriter

-- | Encode a single native machine <a>Int</a>. The <a>Int</a> is encoded
°5uin host order, host endian form, for the machine you're on. On a 64
°5ubit machine the <a>Int</a> is an 8 byte value, on a 32 bit machine, 4
°5ubytes. Values encoded this way are not portable to different endian or
°5uint sized machines, without conversion.
intHost :: Int -> Builder

-- | Encode a <a>Int16</a> in native host order and host endianness.
int16Host :: Int16 -> Builder

-- | Encode a <a>Int32</a> in native host order and host endianness.
int32Host :: Int32 -> Builder

-- | Encode a <a>Int64</a> in native host order and host endianness.
int64Host :: Int64 -> Builder

-- | Encode a single native machine <a>Word</a>. The <a>Word</a> is encoded
°5uin host order, host endian form, for the machine you're on. On a 64
°5ubit machine the <a>Word</a> is an 8 byte value, on a 32 bit machine, 4
°5ubytes. Values encoded this way are not portable to different endian or
°5uword sized machines, without conversion.
wordHost :: Word -> Builder

-- | Encode a <a>Word16</a> in native host order and host endianness.
word16Host :: Word16 -> Builder

-- | Encode a <a>Word32</a> in native host order and host endianness.
word32Host :: Word32 -> Builder

-- | Encode a <a>Word64</a> in native host order and host endianness.
word64Host :: Word64 -> Builder

-- | Encode a <a>Float</a> in native host order. Values encoded this way
°5uare not portable to different endian machines, without conversion.
floatHost :: Float -> Builder

-- | Encode a <a>Double</a> in native host order.
doubleHost :: Double -> Builder


-- | We decided to rename the Builder modules. Sorry about that.
°5u
°5uThe old names will hang about for at least once release cycle before
°5uwe deprecate them and then later remove them.
module Data.ByteString.Lazy.Builder.Extras


-- | <a>Builder</a>s are used to efficiently construct sequences of bytes
°5ufrom smaller parts. Typically, such a construction is part of the
°5uimplementation of an <i>encoding</i>, i.e., a function for converting
°5uHaskell values to sequences of bytes. Examples of encodings are the
°5ugeneration of the sequence of bytes representing a HTML document to be
°5usent in a HTTP response by a web application or the serialization of a
°5uHaskell value using a fixed binary format.
°5u
°5uFor an <i>efficient implementation of an encoding</i>, it is important
°5uthat (a) little time is spent on converting the Haskell values to the
°5uresulting sequence of bytes <i>and</i> (b) that the representation of
°5uthe resulting sequence is such that it can be consumed efficiently.
°5u<a>Builder</a>s support (a) by providing an <i>O(1)</i> concatentation
°5uoperation and efficient implementations of basic encodings for
°5u<a>Char</a>s, <a>Int</a>s, and other standard Haskell values. They
°5usupport (b) by providing their result as a lazy <a>ByteString</a>,
°5uwhich is internally just a linked list of pointers to <i>chunks</i> of
°5uconsecutive raw memory. Lazy <a>ByteString</a>s can be efficiently
°5uconsumed by functions that write them to a file or send them over a
°5unetwork socket. Note that each chunk boundary incurs expensive extra
°5uwork (e.g., a system call) that must be amortized over the work spent
°5uon consuming the chunk body. <a>Builder</a>s therefore take special
°5ucare to ensure that the average chunk size is large enough. The
°5uprecise meaning of large enough is application dependent. The current
°5uimplementation is tuned for an average chunk size between 4kb and
°5u32kb, which should suit most applications.
°5u
°5uAs a simple example of an encoding implementation, we show how to
°5uefficiently convert the following representation of mixed-data tables
°5uto an UTF-8 encoded Comma-Separated-Values (CSV) table.
°5u
°5u<pre>
°5udata Cell = StringC String
°5u          | IntC Int
°5u          deriving( Eq, Ord, Show )
°5u
°5utype Row   = [Cell]
°5utype Table = [Row]
°5u</pre>
°5u
°5uWe use the following imports and abbreviate <a>mappend</a> to simplify
°5ureading.
°5u
°5u<pre>
°5uimport qualified <a>Data.ByteString.Lazy</a>               as L
°5uimport           <a>Data.ByteString.Builder</a>
°5uimport           Data.Monoid
°5uimport           Data.Foldable                        (<a>foldMap</a>)
°5uimport           Data.List                            (<a>intersperse</a>)
°5u
°5uinfixr 4 &lt;&gt;
°5u(&lt;&gt;) :: <a>Monoid</a> m =&gt; m -&gt; m -&gt; m
°5u(&lt;&gt;) = <a>mappend</a>
°5u</pre>
°5u
°5uCSV is a character-based representation of tables. For maximal
°5umodularity, we could first render <tt>Table</tt>s as <a>String</a>s
°5uand then encode this <a>String</a> using some Unicode character
°5uencoding. However, this sacrifices performance due to the intermediate
°5u<a>String</a> representation being built and thrown away right
°5uafterwards. We get rid of this intermediate <a>String</a>
°5urepresentation by fixing the character encoding to UTF-8 and using
°5u<a>Builder</a>s to convert <tt>Table</tt>s directly to UTF-8 encoded
°5uCSV tables represented as lazy <a>ByteString</a>s.
°5u
°5u<pre>
°5uencodeUtf8CSV :: Table -&gt; L.ByteString
°5uencodeUtf8CSV = <a>toLazyByteString</a> . renderTable
°5u
°5urenderTable :: Table -&gt; Builder
°5urenderTable rs = <a>mconcat</a> [renderRow r &lt;&gt; <a>charUtf8</a> '\n' | r &lt;- rs]
°5u
°5urenderRow :: Row -&gt; Builder
°5urenderRow []     = <a>mempty</a>
°5urenderRow (c:cs) =
°5u    renderCell c &lt;&gt; mconcat [ charUtf8 ',' &lt;&gt; renderCell c' | c' &lt;- cs ]
°5u
°5urenderCell :: Cell -&gt; Builder
°5urenderCell (StringC cs) = renderString cs
°5urenderCell (IntC i)     = <a>intDec</a> i
°5u
°5urenderString :: String -&gt; Builder
°5urenderString cs = charUtf8 '"' &lt;&gt; foldMap escape cs &lt;&gt; charUtf8 '"'
°5u  where
°5u    escape '\\' = charUtf8 '\\' &lt;&gt; charUtf8 '\\'
°5u    escape '\"' = charUtf8 '\\' &lt;&gt; charUtf8 '\"'
°5u    escape c    = charUtf8 c
°5u</pre>
°5u
°5uNote that the ASCII encoding is a subset of the UTF-8 encoding, which
°5uis why we can use the optimized function <a>intDec</a> to encode an
°5u<a>Int</a> as a decimal number with UTF-8 encoded digits. Using
°5u<a>intDec</a> is more efficient than <tt><a>stringUtf8</a> .
°5u<a>show</a></tt>, as it avoids constructing an intermediate
°5u<a>String</a>. Avoiding this intermediate data structure significantly
°5uimproves performance because encoding <tt>Cell</tt>s is the core
°5uoperation for rendering CSV-tables. See
°5u<a>Data.ByteString.Builder.Prim</a> for further information on how to
°5uimprove the performance of <tt>renderString</tt>.
°5u
°5uWe demonstrate our UTF-8 CSV encoding function on the following table.
°5u
°5u<pre>
°5ustrings :: [String]
°5ustrings =  ["hello", "\"1\"", "λ-wörld"]
°5u
°5utable :: Table
°5utable = [map StringC strings, map IntC [-3..3]]
°5u</pre>
°5u
°5uThe expression <tt>encodeUtf8CSV table</tt> results in the following
°5ulazy <a>ByteString</a>.
°5u
°5u<pre>
°5uChunk "\"hello\",\"\\\"1\\\"\",\"\206\187-w\195\182rld\"\n-3,-2,-1,0,1,2,3\n" Empty
°5u</pre>
°5u
°5uWe can clearly see that we are converting to a <i>binary</i> format.
°5uThe 'λ' and 'ö' characters, which have a Unicode codepoint above 127,
°5uare expanded to their corresponding UTF-8 multi-byte representation.
°5u
°5uWe use the <tt>criterion</tt> library
°5u(<a>http://hackage.haskell.org/package/criterion</a>) to benchmark the
°5uefficiency of our encoding function on the following table.
°5u
°5u<pre>
°5uimport Criterion.Main     -- add this import to the ones above
°5u
°5umaxiTable :: Table
°5umaxiTable = take 1000 $ cycle table
°5u
°5umain :: IO ()
°5umain = defaultMain
°5u  [ bench "encodeUtf8CSV maxiTable (original)" $
°5u      whnf (L.length . encodeUtf8CSV) maxiTable
°5u  ]
°5u</pre>
°5u
°5uOn a Core2 Duo 2.20GHz on a 32-bit Linux, the above code takes 1ms to
°5ugenerate the 22'500 bytes long lazy <a>ByteString</a>. Looking again
°5uat the definitions above, we see that we took care to avoid
°5uintermediate data structures, as otherwise we would sacrifice
°5uperformance. For example, the following (arguably simpler) definition
°5uof <tt>renderRow</tt> is about 20% slower.
°5u
°5u<pre>
°5urenderRow :: Row -&gt; Builder
°5urenderRow  = mconcat . intersperse (charUtf8 ',') . map renderCell
°5u</pre>
°5u
°5uSimilarly, using <i>O(n)</i> concatentations like <a>++</a> or the
°5uequivalent <a>concat</a> operations on strict and lazy
°5u<a>ByteString</a>s should be avoided. The following definition of
°5u<tt>renderString</tt> is also about 20% slower.
°5u
°5u<pre>
°5urenderString :: String -&gt; Builder
°5urenderString cs = charUtf8 $ "\"" ++ concatMap escape cs ++ "\""
°5u  where
°5u    escape '\\' = "\\"
°5u    escape '\"' = "\\\""
°5u    escape c    = return c
°5u</pre>
°5u
°5uApart from removing intermediate data-structures, encodings can be
°5uoptimized further by fine-tuning their execution parameters using the
°5ufunctions in <a>Data.ByteString.Builder.Extra</a> and their "inner
°5uloops" using the functions in <a>Data.ByteString.Builder.Prim</a>.
module Data.ByteString.Builder

-- | <a>Builder</a>s denote sequences of bytes. They are <a>Monoid</a>s
°5uwhere <a>mempty</a> is the zero-length sequence and <a>mappend</a> is
°5uconcatenation, which runs in <i>O(1)</i>.
data Builder

-- | Execute a <a>Builder</a> and return the generated chunks as a lazy
°5u<a>ByteString</a>. The work is performed lazy, i.e., only when a chunk
°5uof the lazy <a>ByteString</a> is forced.
toLazyByteString :: Builder -> ByteString

-- | Output a <a>Builder</a> to a <a>Handle</a>. The <a>Builder</a> is
°5uexecuted directly on the buffer of the <a>Handle</a>. If the buffer is
°5utoo small (or not present), then it is replaced with a large enough
°5ubuffer.
°5u
°5uIt is recommended that the <a>Handle</a> is set to binary and
°5u<tt>BlockBuffering</tt> mode. See <tt>hSetBinaryMode</tt> and
°5u<tt>hSetBuffering</tt>.
°5u
°5uThis function is more efficient than <tt>hPut .
°5u<a>toLazyByteString</a></tt> because in many cases no buffer
°5uallocation has to be done. Moreover, the results of several executions
°5uof short <a>Builder</a>s are concatenated in the <a>Handle</a>s
°5ubuffer, therefore avoiding unnecessary buffer flushes.
hPutBuilder :: Handle -> Builder -> IO ()

-- | Create a <a>Builder</a> denoting the same sequence of bytes as a
°5ustrict <a>ByteString</a>. The <a>Builder</a> inserts large
°5u<a>ByteString</a>s directly, but copies small ones to ensure that the
°5ugenerated chunks are large on average.
byteString :: ByteString -> Builder

-- | Create a <a>Builder</a> denoting the same sequence of bytes as a lazy
°5u<a>ByteString</a>. The <a>Builder</a> inserts large chunks of the lazy
°5u<a>ByteString</a> directly, but copies small ones to ensure that the
°5ugenerated chunks are large on average.
lazyByteString :: ByteString -> Builder

-- | Construct a <a>Builder</a> that copies the <a>ShortByteString</a>.
shortByteString :: ShortByteString -> Builder

-- | Encode a single signed byte as-is.
int8 :: Int8 -> Builder

-- | Encode a single unsigned byte as-is.
word8 :: Word8 -> Builder

-- | Encode an <a>Int16</a> in big endian format.
int16BE :: Int16 -> Builder

-- | Encode an <a>Int32</a> in big endian format.
int32BE :: Int32 -> Builder

-- | Encode an <a>Int64</a> in big endian format.
int64BE :: Int64 -> Builder

-- | Encode a <a>Word16</a> in big endian format.
word16BE :: Word16 -> Builder

-- | Encode a <a>Word32</a> in big endian format.
word32BE :: Word32 -> Builder

-- | Encode a <a>Word64</a> in big endian format.
word64BE :: Word64 -> Builder

-- | Encode a <a>Float</a> in big endian format.
floatBE :: Float -> Builder

-- | Encode a <a>Double</a> in big endian format.
doubleBE :: Double -> Builder

-- | Encode an <a>Int16</a> in little endian format.
int16LE :: Int16 -> Builder

-- | Encode an <a>Int32</a> in little endian format.
int32LE :: Int32 -> Builder

-- | Encode an <a>Int64</a> in little endian format.
int64LE :: Int64 -> Builder

-- | Encode a <a>Word16</a> in little endian format.
word16LE :: Word16 -> Builder

-- | Encode a <a>Word32</a> in little endian format.
word32LE :: Word32 -> Builder

-- | Encode a <a>Word64</a> in little endian format.
word64LE :: Word64 -> Builder

-- | Encode a <a>Float</a> in little endian format.
floatLE :: Float -> Builder

-- | Encode a <a>Double</a> in little endian format.
doubleLE :: Double -> Builder

-- | Char7 encode a <a>Char</a>.
char7 :: Char -> Builder

-- | Char7 encode a <a>String</a>.
string7 :: String -> Builder

-- | Char8 encode a <a>Char</a>.
char8 :: Char -> Builder

-- | Char8 encode a <a>String</a>.
string8 :: String -> Builder

-- | UTF-8 encode a <a>Char</a>.
charUtf8 :: Char -> Builder

-- | UTF-8 encode a <a>String</a>.
stringUtf8 :: String -> Builder

-- | Decimal encoding of an <a>Int8</a> using the ASCII digits.
°5u
°5ue.g.
°5u
°5u<pre>
°5utoLazyByteString (int8Dec 42)   = "42"
°5utoLazyByteString (int8Dec (-1)) = "-1"
°5u</pre>
int8Dec :: Int8 -> Builder

-- | Decimal encoding of an <a>Int16</a> using the ASCII digits.
int16Dec :: Int16 -> Builder

-- | Decimal encoding of an <a>Int32</a> using the ASCII digits.
int32Dec :: Int32 -> Builder

-- | Decimal encoding of an <a>Int64</a> using the ASCII digits.
int64Dec :: Int64 -> Builder

-- | Decimal encoding of an <a>Int</a> using the ASCII digits.
intDec :: Int -> Builder

-- | Decimal encoding of an <a>Integer</a> using the ASCII digits.
integerDec :: Integer -> Builder

-- | Decimal encoding of a <a>Word8</a> using the ASCII digits.
word8Dec :: Word8 -> Builder

-- | Decimal encoding of a <a>Word16</a> using the ASCII digits.
word16Dec :: Word16 -> Builder

-- | Decimal encoding of a <a>Word32</a> using the ASCII digits.
word32Dec :: Word32 -> Builder

-- | Decimal encoding of a <a>Word64</a> using the ASCII digits.
word64Dec :: Word64 -> Builder

-- | Decimal encoding of a <a>Word</a> using the ASCII digits.
wordDec :: Word -> Builder

-- | <i>Currently slow.</i> Decimal encoding of an IEEE <a>Float</a>.
floatDec :: Float -> Builder

-- | <i>Currently slow.</i> Decimal encoding of an IEEE <a>Double</a>.
doubleDec :: Double -> Builder

-- | Shortest hexadecimal encoding of a <a>Word8</a> using lower-case
°5ucharacters.
word8Hex :: Word8 -> Builder

-- | Shortest hexadecimal encoding of a <a>Word16</a> using lower-case
°5ucharacters.
word16Hex :: Word16 -> Builder

-- | Shortest hexadecimal encoding of a <a>Word32</a> using lower-case
°5ucharacters.
word32Hex :: Word32 -> Builder

-- | Shortest hexadecimal encoding of a <a>Word64</a> using lower-case
°5ucharacters.
word64Hex :: Word64 -> Builder

-- | Shortest hexadecimal encoding of a <a>Word</a> using lower-case
°5ucharacters.
wordHex :: Word -> Builder

-- | Encode a <a>Int8</a> using 2 nibbles (hexadecimal digits).
int8HexFixed :: Int8 -> Builder

-- | Encode a <a>Int16</a> using 4 nibbles.
int16HexFixed :: Int16 -> Builder

-- | Encode a <a>Int32</a> using 8 nibbles.
int32HexFixed :: Int32 -> Builder

-- | Encode a <a>Int64</a> using 16 nibbles.
int64HexFixed :: Int64 -> Builder

-- | Encode a <a>Word8</a> using 2 nibbles (hexadecimal digits).
word8HexFixed :: Word8 -> Builder

-- | Encode a <a>Word16</a> using 4 nibbles.
word16HexFixed :: Word16 -> Builder

-- | Encode a <a>Word32</a> using 8 nibbles.
word32HexFixed :: Word32 -> Builder

-- | Encode a <a>Word64</a> using 16 nibbles.
word64HexFixed :: Word64 -> Builder

-- | Encode an IEEE <a>Float</a> using 8 nibbles.
floatHexFixed :: Float -> Builder

-- | Encode an IEEE <a>Double</a> using 16 nibbles.
doubleHexFixed :: Double -> Builder

-- | Encode each byte of a <a>ByteString</a> using its fixed-width hex
°5uencoding.
byteStringHex :: ByteString -> Builder

-- | Encode each byte of a lazy <a>ByteString</a> using its fixed-width hex
°5uencoding.
lazyByteStringHex :: ByteString -> Builder
instance Data.String.IsString Data.ByteString.Builder.Internal.Builder


-- | We decided to rename the Builder modules. Sorry about that.
°5u
°5uIn additon, the ASCII module has been merged into the main
°5u<a>Data.ByteString.Builder</a> module.
°5u
°5uThe old names will hang about for at least once release cycle before
°5uwe deprecate them and then later remove them.
module Data.ByteString.Lazy.Builder.ASCII
byteStringHexFixed :: ByteString -> Builder
lazyByteStringHexFixed :: ByteString -> Builder


-- | We decided to rename the Builder modules. Sorry about that.
°5u
°5uThe old names will hang about for at least once release cycle before
°5uwe deprecate them and then later remove them.
module Data.ByteString.Lazy.Builder
