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


-- | Fast, compact, strict and lazy byte strings with a list interface
--   
--   An efficient compact, immutable byte string type (both strict and
--   lazy) suitable for binary or 8-bit character data.
--   
--   The <a>ByteString</a> type represents sequences of bytes or 8-bit
--   characters. It is suitable for high performance use, both in terms of
--   large data quantities, or high speed requirements. The
--   <a>ByteString</a> functions follow the same style as Haskell's
--   ordinary lists, so it is easy to convert code from using <a>String</a>
--   to <a>ByteString</a>.
--   
--   Two <a>ByteString</a> variants are provided:
--   
--   <ul>
--   <li>Strict <a>ByteString</a>s keep the string as a single large array.
--   This makes them convenient for passing data between C and
--   Haskell.</li>
--   <li>Lazy <a>ByteString</a>s use a lazy list of strict chunks which
--   makes it suitable for I/O streaming tasks.</li>
--   </ul>
--   
--   The <tt>Char8</tt> modules provide a character-based view of the same
--   underlying <a>ByteString</a> types. This makes it convenient to handle
--   mixed binary and 8-bit character content (which is common in many file
--   formats and network protocols).
--   
--   The <a>Builder</a> module provides an efficient way to build up
--   <a>ByteString</a>s in an ad-hoc way by repeated concatenation. This is
--   ideal for fast serialisation or pretty printing.
--   
--   There is also a <a>ShortByteString</a> type which has a lower memory
--   overhead and can be converted to or from a <a>ByteString</a>. It is
--   suitable for keeping many short strings in memory.
--   
--   <a>ByteString</a>s are not designed for Unicode. For Unicode strings
--   you should use the <a>Text</a> type from the <tt>text</tt> package.
--   
--   These modules are intended to be imported qualified, to avoid name
--   clashes with <a>Prelude</a> functions, e.g.
--   
--   <pre>
--   import qualified Data.ByteString as BS
--   </pre>
@package bytestring
@version 0.11.3.1


-- | <ul>
--   <li>Warning:* this module is internal. If you find that you need it
--   please contact the maintainers and explain what you are trying to do
--   and discuss what you would need in the public API. It is important
--   that you do this as the module may not be exposed at all in future
--   releases.</li>
--   </ul>
--   
--   The maintainers are glad to accept patches for further standard
--   encodings of standard Haskell values.
--   
--   If you need to write your own builder primitives, then be aware that
--   you are writing code with <i>all safety belts off</i>; i.e., *this is
--   the code that might make your application vulnerable to
--   buffer-overflow attacks!* The
--   <a>Data.ByteString.Builder.Prim.Tests</a> module provides you with
--   utilities for testing your encodings thoroughly.
module Data.ByteString.Builder.Prim.Internal

-- | The type used for sizes and sizeBounds of sizes.
type Size = Int

-- | A builder primitive that always results in a sequence of bytes of a
--   pre-determined, fixed size.
data FixedPrim a
fixedPrim :: Int -> (a -> Ptr Word8 -> IO ()) -> FixedPrim a

-- | The size of the sequences of bytes generated by this <a>FixedPrim</a>.
size :: FixedPrim a -> Int
runF :: FixedPrim a -> a -> Ptr Word8 -> IO ()

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

-- | Change a primitives such that it first applies a function to the value
--   to be encoded.
--   
--   Note that primitives are <a>Contravariant</a>
--   <a>http://hackage.haskell.org/package/contravariant</a>. Hence, the
--   following laws hold.
--   
--   <pre>
--   contramapF id = id
--   contramapF f . contramapF g = contramapF (g . f)
--   </pre>
contramapF :: (b -> a) -> FixedPrim a -> FixedPrim b

-- | Encode a pair by encoding its first component and then its second
--   component.
pairF :: FixedPrim a -> FixedPrim b -> FixedPrim (a, b)
storableToF :: forall a. Storable a => FixedPrim a

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

boundedPrim :: Int -> (a -> Ptr Word8 -> IO (Ptr Word8)) -> BoundedPrim a

-- | The bound on the size of sequences of bytes generated by this
--   <a>BoundedPrim</a>.
sizeBound :: BoundedPrim a -> Int
runB :: BoundedPrim a -> a -> Ptr Word8 -> IO (Ptr Word8)

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

-- | Change a <a>BoundedPrim</a> such that it first applies a function to
--   the value to be encoded.
--   
--   Note that <a>BoundedPrim</a>s are <a>Contravariant</a>
--   <a>http://hackage.haskell.org/package/contravariant</a>. Hence, the
--   following laws hold.
--   
--   <pre>
--   contramapB id = id
--   contramapB f . contramapB g = contramapB (g . f)
--   </pre>
contramapB :: (b -> a) -> BoundedPrim a -> BoundedPrim b

-- | Encode a pair by encoding its first component and then its second
--   component.
pairB :: BoundedPrim a -> BoundedPrim b -> BoundedPrim (a, b)

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

-- | Conditionally select a <a>BoundedPrim</a>. For example, we can
--   implement the ASCII primitive that drops characters with Unicode
--   codepoints above 127 as follows.
--   
--   <pre>
--   charASCIIDrop = <a>condB</a> (&lt; '\128') (<a>liftFixedToBounded</a> <a>char7</a>) <a>emptyB</a>
--    
--   </pre>
condB :: (a -> Bool) -> BoundedPrim a -> BoundedPrim a -> BoundedPrim a

-- | Convert a <a>FixedPrim</a> to a <a>BoundedPrim</a>.
toB :: FixedPrim a -> BoundedPrim a

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

-- | A fmap-like operator for builder primitives, both bounded and fixed
--   size.
--   
--   Builder primitives are contravariant so it's like the normal fmap, but
--   backwards (look at the type). (If it helps to remember, the operator
--   symbol is like (<a>$</a>) but backwards.)
--   
--   We can use it for example to prepend and/or append fixed values to an
--   primitive.
--   
--   <pre>
--    import Data.ByteString.Builder.Prim as P
--   showEncoding ((\x -&gt; ('\'', (x, '\''))) &gt;$&lt; fixed3) 'x' = "'x'"
--     where
--       fixed3 = P.char7 &gt;*&lt; P.char7 &gt;*&lt; P.char7
--   </pre>
--   
--   Note that the rather verbose syntax for composition stems from the
--   requirement to be able to compute the size / size bound at compile
--   time.
(>$<) :: Contravariant f => (b -> a) -> f a -> f b
infixl 4 >$<

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

-- | Select an implementation depending on bitness. Throw a compile time
--   error if bitness is neither 32 nor 64.
caseWordSize_32_64 :: a -> a -> a

-- | <i>Deprecated: Use <a>boundedPrim</a> instead</i>
boudedPrim :: Int -> (a -> Ptr Word8 -> IO (Ptr Word8)) -> BoundedPrim a
instance Data.ByteString.Builder.Prim.Internal.Contravariant Data.ByteString.Builder.Prim.Internal.BoundedPrim
instance Data.ByteString.Builder.Prim.Internal.Monoidal Data.ByteString.Builder.Prim.Internal.BoundedPrim
instance Data.ByteString.Builder.Prim.Internal.Contravariant Data.ByteString.Builder.Prim.Internal.FixedPrim
instance Data.ByteString.Builder.Prim.Internal.Monoidal Data.ByteString.Builder.Prim.Internal.FixedPrim


-- | A module containing semi-public <a>ByteString</a> internals. This
--   exposes the <a>ByteString</a> representation and low level
--   construction functions. As such all the functions in this module are
--   unsafe. The API is also not stable.
--   
--   Where possible application should instead use the functions from the
--   normal public interface modules, such as
--   <a>Data.ByteString.Unsafe</a>. Packages that extend the ByteString
--   system at a low level will need to use this module.
module Data.ByteString.Internal

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

BS :: {-# UNPACK #-} !ForeignPtr Word8 -> {-# UNPACK #-} !Int -> ByteString

-- | <tt><a>PS</a> foreignPtr offset length</tt> represents a
--   <a>ByteString</a> with data backed by a given <tt>foreignPtr</tt>,
--   starting at a given <tt>offset</tt> in bytes and of a specified
--   <tt>length</tt>.
--   
--   This pattern is used to emulate the legacy <a>ByteString</a> data
--   constructor, so that pre-existing code generally doesn't need to
--   change to benefit from the simplified <a>BS</a> constructor and can
--   continue to function unchanged.
--   
--   <i>Note:</i> Matching with this constructor will always be given a 0
--   offset, as the base will be manipulated by <a>plusForeignPtr</a>
--   instead.
pattern PS :: ForeignPtr Word8 -> Int -> Int -> ByteString

-- | Type synonym for the strict flavour of <a>ByteString</a>.
type StrictByteString = ByteString

-- | <a>findIndexOrLength</a> is a variant of findIndex, that returns the
--   length of the string if no element is found, rather than Nothing.
findIndexOrLength :: (Word8 -> Bool) -> ByteString -> Int
packBytes :: [Word8] -> ByteString
packUptoLenBytes :: Int -> [Word8] -> (ByteString, [Word8])
unsafePackLenBytes :: Int -> [Word8] -> ByteString
packChars :: [Char] -> ByteString
packUptoLenChars :: Int -> [Char] -> (ByteString, [Char])
unsafePackLenChars :: Int -> [Char] -> ByteString
unpackBytes :: ByteString -> [Word8]
unpackAppendBytesLazy :: ByteString -> [Word8] -> [Word8]
unpackAppendBytesStrict :: ByteString -> [Word8] -> [Word8]
unpackChars :: ByteString -> [Char]
unpackAppendCharsLazy :: ByteString -> [Char] -> [Char]
unpackAppendCharsStrict :: ByteString -> [Char] -> [Char]

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

-- | See <a>unsafePackAddress</a>. This function is similar, but takes an
--   additional length argument rather then computing it with
--   <tt>strlen</tt>. Therefore embedding <tt>'\0'</tt> characters is
--   possible.
unsafePackLenAddress :: Int -> Addr# -> IO ByteString

-- | See <a>unsafePackAddress</a>. This function has similar behavior.
--   Prefer this function when the address in known to be an <tt>Addr#</tt>
--   literal. In that context, there is no need for the sequencing
--   guarantees that <a>IO</a> provides. On GHC 9.0 and up, this function
--   uses the <tt>FinalPtr</tt> data constructor for
--   <tt>ForeignPtrContents</tt>.
unsafePackLiteral :: Addr# -> ByteString

-- | See <a>unsafePackLiteral</a>. This function is similar, but takes an
--   additional length argument rather then computing it with
--   <tt>strlen</tt>. Therefore embedding <tt>'\0'</tt> characters is
--   possible.
unsafePackLenLiteral :: Int -> Addr# -> ByteString

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

-- | Create ByteString of size <tt>l</tt> and use action <tt>f</tt> to fill
--   its contents.
create :: Int -> (Ptr Word8 -> IO ()) -> IO ByteString

-- | Given a maximum size <tt>l</tt> and an action <tt>f</tt> that fills
--   the <a>ByteString</a> starting at the given <a>Ptr</a> and returns the
--   actual utilized length, <tt><a>createUptoN</a>` l f</tt> returns the
--   filled <a>ByteString</a>.
createUptoN :: Int -> (Ptr Word8 -> IO Int) -> IO ByteString

-- | Like <a>createUptoN</a>, but also returns an additional value created
--   by the action.
createUptoN' :: Int -> (Ptr Word8 -> IO (Int, a)) -> IO (ByteString, a)

-- | Given the maximum size needed and a function to make the contents of a
--   ByteString, createAndTrim makes the <a>ByteString</a>. The generating
--   function is required to return the actual final size (&lt;= the
--   maximum size), and the resulting byte array is reallocated to this
--   size.
--   
--   createAndTrim is the main mechanism for creating custom, efficient
--   ByteString functions, using Haskell or C functions to fill the space.
createAndTrim :: Int -> (Ptr Word8 -> IO Int) -> IO ByteString
createAndTrim' :: Int -> (Ptr Word8 -> IO (Int, Int, a)) -> IO (ByteString, a)

-- | A way of creating ByteStrings outside the IO monad. The <tt>Int</tt>
--   argument gives the final size of the ByteString.
unsafeCreate :: Int -> (Ptr Word8 -> IO ()) -> ByteString

-- | Like <a>unsafeCreate</a> but instead of giving the final size of the
--   ByteString, it is just an upper bound. The inner action returns the
--   actual size. Unlike <a>createAndTrim</a> the ByteString is not
--   reallocated if the final size is less than the estimated size.
unsafeCreateUptoN :: Int -> (Ptr Word8 -> IO Int) -> ByteString

unsafeCreateUptoN' :: Int -> (Ptr Word8 -> IO (Int, a)) -> (ByteString, a)

-- | Wrapper of <a>mallocForeignPtrBytes</a> with faster implementation for
--   GHC
mallocByteString :: Int -> IO (ForeignPtr a)

-- | <i>O(1)</i> Build a ByteString from a ForeignPtr.
--   
--   If you do not need the offset parameter then you should be using
--   <a>unsafePackCStringLen</a> or <a>unsafePackCStringFinalizer</a>
--   instead.
fromForeignPtr :: ForeignPtr Word8 -> Int -> Int -> ByteString

-- | <i>O(1)</i> Deconstruct a ForeignPtr from a ByteString
toForeignPtr :: ByteString -> (ForeignPtr Word8, Int, Int)

fromForeignPtr0 :: ForeignPtr Word8 -> Int -> ByteString

-- | <i>O(1)</i> Deconstruct a ForeignPtr from a ByteString
toForeignPtr0 :: ByteString -> (ForeignPtr Word8, Int)

-- | The 0 pointer. Used to indicate the empty Bytestring.
nullForeignPtr :: ForeignPtr Word8

-- | Add two non-negative numbers. Errors out on overflow.
checkedAdd :: String -> Int -> Int -> Int
c_strlen :: CString -> IO CSize
c_free_finalizer :: FunPtr (Ptr Word8 -> IO ())
memchr :: Ptr Word8 -> Word8 -> CSize -> IO (Ptr Word8)
memcmp :: Ptr Word8 -> Ptr Word8 -> Int -> IO CInt
memcpy :: Ptr Word8 -> Ptr Word8 -> Int -> IO ()
memset :: Ptr Word8 -> Word8 -> CSize -> IO (Ptr Word8)
c_reverse :: Ptr Word8 -> Ptr Word8 -> CSize -> IO ()
c_intersperse :: Ptr Word8 -> Ptr Word8 -> CSize -> Word8 -> IO ()
c_maximum :: Ptr Word8 -> CSize -> IO Word8
c_minimum :: Ptr Word8 -> CSize -> IO Word8
c_count :: Ptr Word8 -> CSize -> Word8 -> IO CSize
c_sort :: Ptr Word8 -> CSize -> IO ()

-- | Conversion between <a>Word8</a> and <a>Char</a>. Should compile to a
--   no-op.
w2c :: Word8 -> Char

-- | Unsafe conversion between <a>Char</a> and <a>Word8</a>. This is a
--   no-op and silently truncates to 8 bits Chars &gt; '255'. It is
--   provided as convenience for ByteString construction.
c2w :: Char -> Word8

-- | Selects words corresponding to white-space characters in the Latin-1
--   range
isSpaceWord8 :: Word8 -> Bool

-- | Selects white-space characters in the Latin-1 range
isSpaceChar8 :: Char -> Bool

-- | This "function" has a superficial similarity to <a>unsafePerformIO</a>
--   but it is in fact a malevolent agent of chaos. It unpicks the seams of
--   reality (and the <a>IO</a> monad) so that the normal rules no longer
--   apply. It lulls you into thinking it is reasonable, but when you are
--   not looking it stabs you in the back and aliases all of your mutable
--   buffers. The carcass of many a seasoned Haskell programmer lie strewn
--   at its feet.
--   
--   Witness the trail of destruction:
--   
--   <ul>
--   
--   <li><a>https://github.com/haskell/bytestring/commit/71c4b438c675aa360c79d79acc9a491e7bbc26e7</a></li>
--   
--   <li><a>https://github.com/haskell/bytestring/commit/210c656390ae617d9ee3b8bcff5c88dd17cef8da</a></li>
--   <li><a>https://ghc.haskell.org/trac/ghc/ticket/3486</a></li>
--   <li><a>https://ghc.haskell.org/trac/ghc/ticket/3487</a></li>
--   <li><a>https://ghc.haskell.org/trac/ghc/ticket/7270</a></li>
--   </ul>
--   
--   Do not talk about "safe"! You do not know what is safe!
--   
--   Yield not to its blasphemous call! Flee traveller! Flee or you will be
--   corrupted and devoured!
accursedUnutterablePerformIO :: IO a -> a

-- | Advances the given address by the given offset in bytes.
--   
--   The new <a>ForeignPtr</a> shares the finalizer of the original,
--   equivalent from a finalization standpoint to just creating another
--   reference to the original. That is, the finalizer will not be called
--   before the new <a>ForeignPtr</a> is unreachable, nor will it be called
--   an additional time due to this call, and the finalizer will be called
--   with the same address that it would have had this call not happened,
--   *not* the new address.
plusForeignPtr :: ForeignPtr a -> Int -> ForeignPtr b

-- | This is similar to <a>withForeignPtr</a> but comes with an important
--   caveat: the user must guarantee that the continuation does not diverge
--   (e.g. loop or throw an exception). In exchange for this loss of
--   generality, this function offers the ability of GHC to optimise more
--   aggressively.
--   
--   Specifically, applications of the form: <tt> unsafeWithForeignPtr fptr
--   (<a>forever</a> something) </tt>
--   
--   See GHC issue #17760 for more information about the unsoundness
--   behavior that this function can result in.
unsafeWithForeignPtr :: ForeignPtr a -> (Ptr a -> IO b) -> IO b
instance GHC.Classes.Eq Data.ByteString.Internal.ByteString
instance GHC.Classes.Ord Data.ByteString.Internal.ByteString
instance GHC.Base.Semigroup Data.ByteString.Internal.ByteString
instance GHC.Base.Monoid Data.ByteString.Internal.ByteString
instance Control.DeepSeq.NFData Data.ByteString.Internal.ByteString
instance GHC.Show.Show Data.ByteString.Internal.ByteString
instance GHC.Read.Read Data.ByteString.Internal.ByteString
instance GHC.Exts.IsList Data.ByteString.Internal.ByteString
instance Data.String.IsString Data.ByteString.Internal.ByteString
instance Data.Data.Data Data.ByteString.Internal.ByteString
instance Language.Haskell.TH.Syntax.Lift Data.ByteString.Internal.ByteString


-- | A module containing semi-public <a>ByteString</a> internals. This
--   exposes the <a>ByteString</a> representation and low level
--   construction functions. Modules which extend the <a>ByteString</a>
--   system will need to use this module while ideally most users will be
--   able to make do with the public interface modules.
module Data.ByteString.Lazy.Internal

-- | A space-efficient representation of a <a>Word8</a> vector, supporting
--   many efficient operations.
--   
--   A lazy <a>ByteString</a> contains 8-bit bytes, or by using the
--   operations from <a>Data.ByteString.Lazy.Char8</a> it can be
--   interpreted as containing 8-bit characters.
data ByteString
Empty :: ByteString
Chunk :: {-# UNPACK #-} !ByteString -> ByteString -> ByteString

-- | Type synonym for the lazy flavour of <a>ByteString</a>.
type LazyByteString = ByteString

-- | Smart constructor for <a>Chunk</a>. Guarantees the data type
--   invariant.
chunk :: ByteString -> 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,
--   accumulating left fold.
foldlChunks :: (a -> ByteString -> a) -> a -> ByteString -> a

-- | The data type invariant: Every ByteString is either <a>Empty</a> or
--   consists of non-null <a>ByteString</a>s. All functions must preserve
--   this, and the QC properties must check this.
invariant :: ByteString -> Bool

-- | In a form that checks the invariant lazily.
checkInvariant :: ByteString -> ByteString

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

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

-- | The memory management overhead. Currently this is tuned for GHC only.
chunkOverhead :: Int
packBytes :: [Word8] -> ByteString
packChars :: [Char] -> ByteString
unpackBytes :: ByteString -> [Word8]
unpackChars :: ByteString -> [Char]

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

-- | <i>O(n)</i> Convert a lazy <a>ByteString</a> into a strict
--   <a>ByteString</a>.
--   
--   Note that this is an <i>expensive</i> operation that forces the whole
--   lazy ByteString into memory and then copies all the data. If possible,
--   try to avoid converting back and forth between strict and lazy
--   bytestrings.
toStrict :: ByteString -> ByteString
instance Language.Haskell.TH.Syntax.Lift Data.ByteString.Lazy.Internal.ByteString
instance GHC.Classes.Eq Data.ByteString.Lazy.Internal.ByteString
instance GHC.Classes.Ord Data.ByteString.Lazy.Internal.ByteString
instance GHC.Base.Semigroup Data.ByteString.Lazy.Internal.ByteString
instance GHC.Base.Monoid Data.ByteString.Lazy.Internal.ByteString
instance Control.DeepSeq.NFData Data.ByteString.Lazy.Internal.ByteString
instance GHC.Show.Show Data.ByteString.Lazy.Internal.ByteString
instance GHC.Read.Read Data.ByteString.Lazy.Internal.ByteString
instance GHC.Exts.IsList Data.ByteString.Lazy.Internal.ByteString
instance Data.String.IsString Data.ByteString.Lazy.Internal.ByteString
instance Data.Data.Data Data.ByteString.Lazy.Internal.ByteString


-- | Internal representation of ShortByteString
module Data.ByteString.Short.Internal

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

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

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

-- | <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(n)</i>. Convert a <a>ShortByteString</a> into a
--   <a>ByteString</a>.
fromShort :: ShortByteString -> ByteString

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

-- | <i>O(n)</i> Append a byte to the end of a <a>ShortByteString</a>
--   
--   Note: copies the entire byte array
snoc :: ShortByteString -> Word8 -> ShortByteString
infixl 5 `snoc`

-- | <i>O(n)</i> <a>cons</a> is analogous to (:) for lists.
--   
--   Note: copies the entire byte array
cons :: Word8 -> ShortByteString -> ShortByteString
infixr 5 `cons`
append :: ShortByteString -> ShortByteString -> ShortByteString

-- | <i>O(1)</i> Extract the last element of a ShortByteString, which must
--   be finite and non-empty. An exception will be thrown in the case of an
--   empty ShortByteString.
--   
--   This is a partial function, consider using <a>unsnoc</a> instead.
last :: HasCallStack => ShortByteString -> Word8

-- | <i>O(n)</i> Extract the elements after the head of a ShortByteString,
--   which must be non-empty. An exception will be thrown in the case of an
--   empty ShortByteString.
--   
--   This is a partial function, consider using <a>uncons</a> instead.
--   
--   Note: copies the entire byte array
tail :: HasCallStack => ShortByteString -> ShortByteString

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

-- | <i>O(1)</i> Extract the first element of a ShortByteString, which must
--   be non-empty. An exception will be thrown in the case of an empty
--   ShortByteString.
--   
--   This is a partial function, consider using <a>uncons</a> instead.
head :: HasCallStack => ShortByteString -> Word8

-- | <i>O(n)</i> Return all the elements of a <a>ShortByteString</a> except
--   the last one. An exception will be thrown in the case of an empty
--   ShortByteString.
--   
--   This is a partial function, consider using <a>unsnoc</a> instead.
--   
--   Note: copies the entire byte array
init :: HasCallStack => ShortByteString -> ShortByteString

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

-- | <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(n)</i> <a>map</a> <tt>f xs</tt> is the ShortByteString obtained
--   by applying <tt>f</tt> to each element of <tt>xs</tt>.
map :: (Word8 -> Word8) -> ShortByteString -> ShortByteString

-- | <i>O(n)</i> <a>reverse</a> <tt>xs</tt> efficiently returns the
--   elements of <tt>xs</tt> in reverse order.
reverse :: ShortByteString -> ShortByteString

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

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

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

-- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value
--   argument, and thus must be applied to non-empty
--   <a>ShortByteString</a>s. An exception will be thrown in the case of an
--   empty ShortByteString.
foldl1 :: HasCallStack => (Word8 -> Word8 -> Word8) -> ShortByteString -> Word8

-- | <a>foldl1'</a> is like <a>foldl1</a>, but strict in the accumulator.
--   An exception will be thrown in the case of an empty ShortByteString.
foldl1' :: HasCallStack => (Word8 -> Word8 -> Word8) -> ShortByteString -> Word8

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

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

-- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value
--   argument, and thus must be applied to non-empty
--   <a>ShortByteString</a>s An exception will be thrown in the case of an
--   empty ShortByteString.
foldr1 :: HasCallStack => (Word8 -> Word8 -> Word8) -> ShortByteString -> Word8

-- | <a>foldr1'</a> is a variant of <a>foldr1</a>, but is strict in the
--   accumulator.
foldr1' :: HasCallStack => (Word8 -> Word8 -> Word8) -> ShortByteString -> Word8

-- | <i>O(n)</i> Applied to a predicate and a <a>ShortByteString</a>,
--   <a>all</a> determines if all elements of the <a>ShortByteString</a>
--   satisfy the predicate.
all :: (Word8 -> Bool) -> ShortByteString -> Bool

-- | <i>O(n)</i> Applied to a predicate and a ByteString, <a>any</a>
--   determines if any element of the <a>ByteString</a> satisfies the
--   predicate.
any :: (Word8 -> Bool) -> ShortByteString -> Bool
concat :: [ShortByteString] -> ShortByteString

-- | <i>O(n)</i> <a>replicate</a> <tt>n x</tt> is a ByteString of length
--   <tt>n</tt> with <tt>x</tt> the value of every element. The following
--   holds:
--   
--   <pre>
--   replicate w c = unfoldr w (\u -&gt; Just (u,u)) c
--   </pre>
replicate :: Int -> Word8 -> ShortByteString

-- | <i>O(n)</i>, where <i>n</i> is the length of the result. The
--   <a>unfoldr</a> function is analogous to the List 'unfoldr'.
--   <a>unfoldr</a> builds a ShortByteString from a seed value. The
--   function takes the element and returns <a>Nothing</a> if it is done
--   producing the ShortByteString or returns <a>Just</a> <tt>(a,b)</tt>,
--   in which case, <tt>a</tt> is the next byte in the string, and
--   <tt>b</tt> is the seed value for further production.
--   
--   This function is not efficient/safe. It will build a list of
--   <tt>[Word8]</tt> and run the generator until it returns
--   <a>Nothing</a>, otherwise recurse infinitely, then finally create a
--   <a>ShortByteString</a>.
--   
--   If you know the maximum length, consider using <a>unfoldrN</a>.
--   
--   Examples:
--   
--   <pre>
--      unfoldr (\x -&gt; if x &lt;= 5 then Just (x, x + 1) else Nothing) 0
--   == pack [0, 1, 2, 3, 4, 5]
--   </pre>
unfoldr :: (a -> Maybe (Word8, a)) -> a -> ShortByteString

-- | <i>O(n)</i> Like <a>unfoldr</a>, <a>unfoldrN</a> builds a
--   ShortByteString from a seed value. However, the length of the result
--   is limited by the first argument to <a>unfoldrN</a>. This function is
--   more efficient than <a>unfoldr</a> when the maximum length of the
--   result is known.
--   
--   The following equation relates <a>unfoldrN</a> and <a>unfoldr</a>:
--   
--   <pre>
--   fst (unfoldrN n f s) == take n (unfoldr f s)
--   </pre>
unfoldrN :: forall a. Int -> (a -> Maybe (Word8, a)) -> a -> (ShortByteString, Maybe a)

-- | <i>O(n)</i> <a>take</a> <tt>n</tt>, applied to a ShortByteString
--   <tt>xs</tt>, returns the prefix of <tt>xs</tt> of length <tt>n</tt>,
--   or <tt>xs</tt> itself if <tt>n &gt; <a>length</a> xs</tt>.
--   
--   Note: copies the entire byte array
take :: Int -> ShortByteString -> ShortByteString

-- | <i>O(n)</i> <tt><a>takeEnd</a> n xs</tt> is equivalent to
--   <tt><a>drop</a> (<a>length</a> xs - n) xs</tt>. Takes <tt>n</tt>
--   elements from end of bytestring.
--   
--   <pre>
--   &gt;&gt;&gt; takeEnd 3 "abcdefg"
--   "efg"
--   
--   &gt;&gt;&gt; takeEnd 0 "abcdefg"
--   ""
--   
--   &gt;&gt;&gt; takeEnd 4 "abc"
--   "abc"
--   </pre>
takeEnd :: Int -> ShortByteString -> ShortByteString

-- | Returns the longest (possibly empty) suffix of elements satisfying the
--   predicate.
--   
--   <tt><a>takeWhileEnd</a> p</tt> is equivalent to <tt><a>reverse</a> .
--   <a>takeWhile</a> p . <a>reverse</a></tt>.
takeWhileEnd :: (Word8 -> Bool) -> ShortByteString -> ShortByteString

-- | Similar to <a>takeWhile</a>, returns the longest (possibly empty)
--   prefix of elements satisfying the predicate.
takeWhile :: (Word8 -> Bool) -> ShortByteString -> ShortByteString

-- | <i>O(n)</i> <a>drop</a> <tt>n</tt> <tt>xs</tt> returns the suffix of
--   <tt>xs</tt> after the first n elements, or <a>empty</a> if <tt>n &gt;
--   <a>length</a> xs</tt>.
--   
--   Note: copies the entire byte array
drop :: Int -> ShortByteString -> ShortByteString

-- | <i>O(n)</i> <tt><a>dropEnd</a> n xs</tt> is equivalent to
--   <tt><a>take</a> (<a>length</a> xs - n) xs</tt>. Drops <tt>n</tt>
--   elements from end of bytestring.
--   
--   <pre>
--   &gt;&gt;&gt; dropEnd 3 "abcdefg"
--   "abcd"
--   
--   &gt;&gt;&gt; dropEnd 0 "abcdefg"
--   "abcdefg"
--   
--   &gt;&gt;&gt; dropEnd 4 "abc"
--   ""
--   </pre>
dropEnd :: Int -> ShortByteString -> ShortByteString

-- | Similar to <a>dropWhile</a>, drops the longest (possibly empty) prefix
--   of elements satisfying the predicate and returns the remainder.
--   
--   Note: copies the entire byte array
dropWhile :: (Word8 -> Bool) -> ShortByteString -> ShortByteString

-- | Similar to <a>dropWhileEnd</a>, drops the longest (possibly empty)
--   suffix of elements satisfying the predicate and returns the remainder.
--   
--   <tt><a>dropWhileEnd</a> p</tt> is equivalent to <tt><a>reverse</a> .
--   <a>dropWhile</a> p . <a>reverse</a></tt>.
dropWhileEnd :: (Word8 -> Bool) -> ShortByteString -> ShortByteString

-- | Returns the longest (possibly empty) suffix of elements which <b>do
--   not</b> satisfy the predicate and the remainder of the string.
--   
--   <a>breakEnd</a> <tt>p</tt> is equivalent to <tt><a>spanEnd</a> (not .
--   p)</tt> and to <tt>(<a>takeWhileEnd</a> (not . p) &amp;&amp;&amp;
--   <a>dropWhileEnd</a> (not . p))</tt>.
breakEnd :: (Word8 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)

-- | Similar to <a>break</a>, returns the longest (possibly empty) prefix
--   of elements which <b>do not</b> satisfy the predicate and the
--   remainder of the string.
--   
--   <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (not .
--   p)</tt> and to <tt>(<a>takeWhile</a> (not . p) &amp;&amp;&amp;
--   <a>dropWhile</a> (not . p))</tt>.
break :: (Word8 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)

-- | Similar to <a>span</a>, returns the longest (possibly empty) prefix of
--   elements satisfying the predicate and the remainder of the string.
--   
--   <a>span</a> <tt>p</tt> is equivalent to <tt><a>break</a> (not .
--   p)</tt> and to <tt>(<a>takeWhile</a> p &amp;&amp;&amp;
--   <a>dropWhile</a> p)</tt>.
span :: (Word8 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)

-- | Returns the longest (possibly empty) suffix of elements satisfying the
--   predicate and the remainder of the string.
--   
--   <a>spanEnd</a> <tt>p</tt> is equivalent to <tt><a>breakEnd</a> (not .
--   p)</tt> and to <tt>(<a>takeWhileEnd</a> p &amp;&amp;&amp;
--   <a>dropWhileEnd</a> p)</tt>.
--   
--   We have
--   
--   <pre>
--   spanEnd (not . isSpace) "x y z" == ("x y ", "z")
--   </pre>
--   
--   and
--   
--   <pre>
--   spanEnd (not . isSpace) sbs
--      ==
--   let (x, y) = span (not . isSpace) (reverse sbs) in (reverse y, reverse x)
--   </pre>
spanEnd :: (Word8 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)

-- | <i>O(n)</i> <a>splitAt</a> <tt>n sbs</tt> is equivalent to
--   <tt>(<a>take</a> n sbs, <a>drop</a> n sbs)</tt>.
--   
--   Note: copies the substrings
splitAt :: Int -> ShortByteString -> (ShortByteString, ShortByteString)

-- | <i>O(n)</i> Break a <a>ShortByteString</a> into pieces separated by
--   the byte argument, consuming the delimiter. I.e.
--   
--   <pre>
--   split 10  "a\nb\nd\ne" == ["a","b","d","e"]   -- fromEnum '\n' == 10
--   split 97  "aXaXaXa"    == ["","X","X","X",""] -- fromEnum 'a' == 97
--   split 120 "x"          == ["",""]             -- fromEnum 'x' == 120
--   split undefined ""     == []                  -- and not [""]
--   </pre>
--   
--   and
--   
--   <pre>
--   intercalate [c] . split c == id
--   split == splitWith . (==)
--   </pre>
--   
--   Note: copies the substrings
split :: Word8 -> ShortByteString -> [ShortByteString]

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

-- | <i>O(n)</i> The <a>stripSuffix</a> function takes two ShortByteStrings
--   and returns <a>Just</a> the remainder of the second iff the first is
--   its suffix, and otherwise <a>Nothing</a>.
stripSuffix :: ShortByteString -> ShortByteString -> Maybe ShortByteString

-- | <i>O(n)</i> The <a>stripPrefix</a> function takes two ShortByteStrings
--   and returns <a>Just</a> the remainder of the second iff the first is
--   its prefix, and otherwise <a>Nothing</a>.
stripPrefix :: ShortByteString -> ShortByteString -> Maybe ShortByteString

-- | Check whether one string is a substring of another.
isInfixOf :: ShortByteString -> ShortByteString -> Bool

-- | <i>O(n)</i> The <a>isPrefixOf</a> function takes two ShortByteStrings
--   and returns <a>True</a>
isPrefixOf :: ShortByteString -> ShortByteString -> Bool

-- | <i>O(n)</i> The <a>isSuffixOf</a> function takes two ShortByteStrings
--   and returns <a>True</a> iff the first is a suffix of the second.
--   
--   The following holds:
--   
--   <pre>
--   isSuffixOf x y == reverse x `isPrefixOf` reverse y
--   </pre>
isSuffixOf :: ShortByteString -> ShortByteString -> Bool

-- | Break a string on a substring, returning a pair of the part of the
--   string prior to the match, and the rest of the string.
--   
--   The following relationships hold:
--   
--   <pre>
--   break (== c) l == breakSubstring (singleton c) l
--   </pre>
--   
--   For example, to tokenise a string, dropping delimiters:
--   
--   <pre>
--   tokenise x y = h : if null t then [] else tokenise x (drop (length x) t)
--       where (h,t) = breakSubstring x y
--   </pre>
--   
--   To skip to the first occurrence of a string:
--   
--   <pre>
--   snd (breakSubstring x y)
--   </pre>
--   
--   To take the parts of a string before a delimiter:
--   
--   <pre>
--   fst (breakSubstring x y)
--   </pre>
--   
--   Note that calling `breakSubstring x` does some preprocessing work, so
--   you should avoid unnecessarily duplicating breakSubstring calls with
--   the same pattern.
breakSubstring :: ShortByteString -> ShortByteString -> (ShortByteString, ShortByteString)

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

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

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

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

-- | <i>O(1)</i> <a>ShortByteString</a> index (subscript) operator,
--   starting from 0.
index :: HasCallStack => ShortByteString -> Int -> Word8

-- | <i>O(1)</i> <a>ShortByteString</a> index, starting from 0, that
--   returns <a>Just</a> if:
--   
--   <pre>
--   0 &lt;= n &lt; length bs
--   </pre>
indexMaybe :: ShortByteString -> Int -> Maybe Word8

-- | <i>O(1)</i> <a>ShortByteString</a> index, starting from 0, that
--   returns <a>Just</a> if:
--   
--   <pre>
--   0 &lt;= n &lt; length bs
--   </pre>
(!?) :: ShortByteString -> Int -> Maybe Word8

-- | <i>O(n)</i> The <a>elemIndex</a> function returns the index of the
--   first element in the given <a>ShortByteString</a> which is equal to
--   the query element, or <a>Nothing</a> if there is no such element.
elemIndex :: Word8 -> ShortByteString -> Maybe Int

-- | <i>O(n)</i> The <a>elemIndices</a> function extends <a>elemIndex</a>,
--   by returning the indices of all elements equal to the query element,
--   in ascending order.
elemIndices :: Word8 -> ShortByteString -> [Int]

-- | count returns the number of times its argument appears in the
--   ShortByteString
count :: Word8 -> ShortByteString -> Int

-- | <i>O(n)</i> The <a>findIndex</a> function takes a predicate and a
--   <a>ShortByteString</a> and returns the index of the first element in
--   the ByteString satisfying the predicate.
findIndex :: (Word8 -> Bool) -> ShortByteString -> Maybe Int

-- | <i>O(n)</i> The <a>findIndices</a> function extends <a>findIndex</a>,
--   by returning the indices of all elements satisfying the predicate, in
--   ascending order.
findIndices :: (Word8 -> Bool) -> ShortByteString -> [Int]
createFromPtr :: Ptr a -> Int -> IO ShortByteString
copyToPtr :: ShortByteString -> Int -> Ptr a -> Int -> IO ()

-- | <i>O(n)</i> Check whether a <a>ShortByteString</a> represents valid
--   UTF-8.
isValidUtf8 :: ShortByteString -> Bool

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

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

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

-- | <i>O(n) construction.</i> Use a <tt>ShortByteString</tt> with a
--   function requiring a <tt>CStringLen</tt>. As for <tt>useAsCString</tt>
--   this function makes a copy of the original <tt>ShortByteString</tt>.
--   It must not be stored or used after the subcomputation finishes.
useAsCStringLen :: ShortByteString -> (CStringLen -> IO a) -> IO a
instance Language.Haskell.TH.Syntax.Lift Data.ByteString.Short.Internal.ShortByteString
instance GHC.Classes.Eq Data.ByteString.Short.Internal.ShortByteString
instance GHC.Classes.Ord Data.ByteString.Short.Internal.ShortByteString
instance GHC.Base.Semigroup Data.ByteString.Short.Internal.ShortByteString
instance GHC.Base.Monoid Data.ByteString.Short.Internal.ShortByteString
instance Control.DeepSeq.NFData Data.ByteString.Short.Internal.ShortByteString
instance GHC.Show.Show Data.ByteString.Short.Internal.ShortByteString
instance GHC.Read.Read Data.ByteString.Short.Internal.ShortByteString
instance GHC.Exts.IsList Data.ByteString.Short.Internal.ShortByteString
instance Data.String.IsString Data.ByteString.Short.Internal.ShortByteString
instance Data.Data.Data Data.ByteString.Short.Internal.ShortByteString


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

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

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

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

-- | <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(n)</i>. Convert a <a>ShortByteString</a> into a
--   <a>ByteString</a>.
fromShort :: ShortByteString -> ByteString

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

-- | <i>O(n)</i> Append a byte to the end of a <a>ShortByteString</a>
--   
--   Note: copies the entire byte array
snoc :: ShortByteString -> Word8 -> ShortByteString
infixl 5 `snoc`

-- | <i>O(n)</i> <a>cons</a> is analogous to (:) for lists.
--   
--   Note: copies the entire byte array
cons :: Word8 -> ShortByteString -> ShortByteString
infixr 5 `cons`
append :: ShortByteString -> ShortByteString -> ShortByteString

-- | <i>O(1)</i> Extract the last element of a ShortByteString, which must
--   be finite and non-empty. An exception will be thrown in the case of an
--   empty ShortByteString.
--   
--   This is a partial function, consider using <a>unsnoc</a> instead.
last :: HasCallStack => ShortByteString -> Word8

-- | <i>O(n)</i> Extract the elements after the head of a ShortByteString,
--   which must be non-empty. An exception will be thrown in the case of an
--   empty ShortByteString.
--   
--   This is a partial function, consider using <a>uncons</a> instead.
--   
--   Note: copies the entire byte array
tail :: HasCallStack => ShortByteString -> ShortByteString

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

-- | <i>O(1)</i> Extract the first element of a ShortByteString, which must
--   be non-empty. An exception will be thrown in the case of an empty
--   ShortByteString.
--   
--   This is a partial function, consider using <a>uncons</a> instead.
head :: HasCallStack => ShortByteString -> Word8

-- | <i>O(n)</i> Return all the elements of a <a>ShortByteString</a> except
--   the last one. An exception will be thrown in the case of an empty
--   ShortByteString.
--   
--   This is a partial function, consider using <a>unsnoc</a> instead.
--   
--   Note: copies the entire byte array
init :: HasCallStack => ShortByteString -> ShortByteString

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

-- | <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(n)</i> Check whether a <a>ShortByteString</a> represents valid
--   UTF-8.
isValidUtf8 :: ShortByteString -> Bool

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

-- | <i>O(n)</i> <a>reverse</a> <tt>xs</tt> efficiently returns the
--   elements of <tt>xs</tt> in reverse order.
reverse :: ShortByteString -> ShortByteString

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

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

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

-- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value
--   argument, and thus must be applied to non-empty
--   <a>ShortByteString</a>s. An exception will be thrown in the case of an
--   empty ShortByteString.
foldl1 :: HasCallStack => (Word8 -> Word8 -> Word8) -> ShortByteString -> Word8

-- | <a>foldl1'</a> is like <a>foldl1</a>, but strict in the accumulator.
--   An exception will be thrown in the case of an empty ShortByteString.
foldl1' :: HasCallStack => (Word8 -> Word8 -> Word8) -> ShortByteString -> Word8

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

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

-- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value
--   argument, and thus must be applied to non-empty
--   <a>ShortByteString</a>s An exception will be thrown in the case of an
--   empty ShortByteString.
foldr1 :: HasCallStack => (Word8 -> Word8 -> Word8) -> ShortByteString -> Word8

-- | <a>foldr1'</a> is a variant of <a>foldr1</a>, but is strict in the
--   accumulator.
foldr1' :: HasCallStack => (Word8 -> Word8 -> Word8) -> ShortByteString -> Word8

-- | <i>O(n)</i> Applied to a predicate and a <a>ShortByteString</a>,
--   <a>all</a> determines if all elements of the <a>ShortByteString</a>
--   satisfy the predicate.
all :: (Word8 -> Bool) -> ShortByteString -> Bool

-- | <i>O(n)</i> Applied to a predicate and a ByteString, <a>any</a>
--   determines if any element of the <a>ByteString</a> satisfies the
--   predicate.
any :: (Word8 -> Bool) -> ShortByteString -> Bool
concat :: [ShortByteString] -> ShortByteString

-- | <i>O(n)</i> <a>replicate</a> <tt>n x</tt> is a ByteString of length
--   <tt>n</tt> with <tt>x</tt> the value of every element. The following
--   holds:
--   
--   <pre>
--   replicate w c = unfoldr w (\u -&gt; Just (u,u)) c
--   </pre>
replicate :: Int -> Word8 -> ShortByteString

-- | <i>O(n)</i>, where <i>n</i> is the length of the result. The
--   <a>unfoldr</a> function is analogous to the List 'unfoldr'.
--   <a>unfoldr</a> builds a ShortByteString from a seed value. The
--   function takes the element and returns <a>Nothing</a> if it is done
--   producing the ShortByteString or returns <a>Just</a> <tt>(a,b)</tt>,
--   in which case, <tt>a</tt> is the next byte in the string, and
--   <tt>b</tt> is the seed value for further production.
--   
--   This function is not efficient/safe. It will build a list of
--   <tt>[Word8]</tt> and run the generator until it returns
--   <a>Nothing</a>, otherwise recurse infinitely, then finally create a
--   <a>ShortByteString</a>.
--   
--   If you know the maximum length, consider using <a>unfoldrN</a>.
--   
--   Examples:
--   
--   <pre>
--      unfoldr (\x -&gt; if x &lt;= 5 then Just (x, x + 1) else Nothing) 0
--   == pack [0, 1, 2, 3, 4, 5]
--   </pre>
unfoldr :: (a -> Maybe (Word8, a)) -> a -> ShortByteString

-- | <i>O(n)</i> Like <a>unfoldr</a>, <a>unfoldrN</a> builds a
--   ShortByteString from a seed value. However, the length of the result
--   is limited by the first argument to <a>unfoldrN</a>. This function is
--   more efficient than <a>unfoldr</a> when the maximum length of the
--   result is known.
--   
--   The following equation relates <a>unfoldrN</a> and <a>unfoldr</a>:
--   
--   <pre>
--   fst (unfoldrN n f s) == take n (unfoldr f s)
--   </pre>
unfoldrN :: forall a. Int -> (a -> Maybe (Word8, a)) -> a -> (ShortByteString, Maybe a)

-- | <i>O(n)</i> <a>take</a> <tt>n</tt>, applied to a ShortByteString
--   <tt>xs</tt>, returns the prefix of <tt>xs</tt> of length <tt>n</tt>,
--   or <tt>xs</tt> itself if <tt>n &gt; <a>length</a> xs</tt>.
--   
--   Note: copies the entire byte array
take :: Int -> ShortByteString -> ShortByteString

-- | <i>O(n)</i> <tt><a>takeEnd</a> n xs</tt> is equivalent to
--   <tt><a>drop</a> (<a>length</a> xs - n) xs</tt>. Takes <tt>n</tt>
--   elements from end of bytestring.
--   
--   <pre>
--   &gt;&gt;&gt; takeEnd 3 "abcdefg"
--   "efg"
--   
--   &gt;&gt;&gt; takeEnd 0 "abcdefg"
--   ""
--   
--   &gt;&gt;&gt; takeEnd 4 "abc"
--   "abc"
--   </pre>
takeEnd :: Int -> ShortByteString -> ShortByteString

-- | Returns the longest (possibly empty) suffix of elements satisfying the
--   predicate.
--   
--   <tt><a>takeWhileEnd</a> p</tt> is equivalent to <tt><a>reverse</a> .
--   <a>takeWhile</a> p . <a>reverse</a></tt>.
takeWhileEnd :: (Word8 -> Bool) -> ShortByteString -> ShortByteString

-- | Similar to <a>takeWhile</a>, returns the longest (possibly empty)
--   prefix of elements satisfying the predicate.
takeWhile :: (Word8 -> Bool) -> ShortByteString -> ShortByteString

-- | <i>O(n)</i> <a>drop</a> <tt>n</tt> <tt>xs</tt> returns the suffix of
--   <tt>xs</tt> after the first n elements, or <a>empty</a> if <tt>n &gt;
--   <a>length</a> xs</tt>.
--   
--   Note: copies the entire byte array
drop :: Int -> ShortByteString -> ShortByteString

-- | <i>O(n)</i> <tt><a>dropEnd</a> n xs</tt> is equivalent to
--   <tt><a>take</a> (<a>length</a> xs - n) xs</tt>. Drops <tt>n</tt>
--   elements from end of bytestring.
--   
--   <pre>
--   &gt;&gt;&gt; dropEnd 3 "abcdefg"
--   "abcd"
--   
--   &gt;&gt;&gt; dropEnd 0 "abcdefg"
--   "abcdefg"
--   
--   &gt;&gt;&gt; dropEnd 4 "abc"
--   ""
--   </pre>
dropEnd :: Int -> ShortByteString -> ShortByteString

-- | Similar to <a>dropWhile</a>, drops the longest (possibly empty) prefix
--   of elements satisfying the predicate and returns the remainder.
--   
--   Note: copies the entire byte array
dropWhile :: (Word8 -> Bool) -> ShortByteString -> ShortByteString

-- | Similar to <a>dropWhileEnd</a>, drops the longest (possibly empty)
--   suffix of elements satisfying the predicate and returns the remainder.
--   
--   <tt><a>dropWhileEnd</a> p</tt> is equivalent to <tt><a>reverse</a> .
--   <a>dropWhile</a> p . <a>reverse</a></tt>.
dropWhileEnd :: (Word8 -> Bool) -> ShortByteString -> ShortByteString

-- | Returns the longest (possibly empty) suffix of elements which <b>do
--   not</b> satisfy the predicate and the remainder of the string.
--   
--   <a>breakEnd</a> <tt>p</tt> is equivalent to <tt><a>spanEnd</a> (not .
--   p)</tt> and to <tt>(<a>takeWhileEnd</a> (not . p) &amp;&amp;&amp;
--   <a>dropWhileEnd</a> (not . p))</tt>.
breakEnd :: (Word8 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)

-- | Similar to <a>break</a>, returns the longest (possibly empty) prefix
--   of elements which <b>do not</b> satisfy the predicate and the
--   remainder of the string.
--   
--   <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (not .
--   p)</tt> and to <tt>(<a>takeWhile</a> (not . p) &amp;&amp;&amp;
--   <a>dropWhile</a> (not . p))</tt>.
break :: (Word8 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)

-- | Similar to <a>span</a>, returns the longest (possibly empty) prefix of
--   elements satisfying the predicate and the remainder of the string.
--   
--   <a>span</a> <tt>p</tt> is equivalent to <tt><a>break</a> (not .
--   p)</tt> and to <tt>(<a>takeWhile</a> p &amp;&amp;&amp;
--   <a>dropWhile</a> p)</tt>.
span :: (Word8 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)

-- | Returns the longest (possibly empty) suffix of elements satisfying the
--   predicate and the remainder of the string.
--   
--   <a>spanEnd</a> <tt>p</tt> is equivalent to <tt><a>breakEnd</a> (not .
--   p)</tt> and to <tt>(<a>takeWhileEnd</a> p &amp;&amp;&amp;
--   <a>dropWhileEnd</a> p)</tt>.
--   
--   We have
--   
--   <pre>
--   spanEnd (not . isSpace) "x y z" == ("x y ", "z")
--   </pre>
--   
--   and
--   
--   <pre>
--   spanEnd (not . isSpace) sbs
--      ==
--   let (x, y) = span (not . isSpace) (reverse sbs) in (reverse y, reverse x)
--   </pre>
spanEnd :: (Word8 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)

-- | <i>O(n)</i> <a>splitAt</a> <tt>n sbs</tt> is equivalent to
--   <tt>(<a>take</a> n sbs, <a>drop</a> n sbs)</tt>.
--   
--   Note: copies the substrings
splitAt :: Int -> ShortByteString -> (ShortByteString, ShortByteString)

-- | <i>O(n)</i> Break a <a>ShortByteString</a> into pieces separated by
--   the byte argument, consuming the delimiter. I.e.
--   
--   <pre>
--   split 10  "a\nb\nd\ne" == ["a","b","d","e"]   -- fromEnum '\n' == 10
--   split 97  "aXaXaXa"    == ["","X","X","X",""] -- fromEnum 'a' == 97
--   split 120 "x"          == ["",""]             -- fromEnum 'x' == 120
--   split undefined ""     == []                  -- and not [""]
--   </pre>
--   
--   and
--   
--   <pre>
--   intercalate [c] . split c == id
--   split == splitWith . (==)
--   </pre>
--   
--   Note: copies the substrings
split :: Word8 -> ShortByteString -> [ShortByteString]

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

-- | <i>O(n)</i> The <a>stripSuffix</a> function takes two ShortByteStrings
--   and returns <a>Just</a> the remainder of the second iff the first is
--   its suffix, and otherwise <a>Nothing</a>.
stripSuffix :: ShortByteString -> ShortByteString -> Maybe ShortByteString

-- | <i>O(n)</i> The <a>stripPrefix</a> function takes two ShortByteStrings
--   and returns <a>Just</a> the remainder of the second iff the first is
--   its prefix, and otherwise <a>Nothing</a>.
stripPrefix :: ShortByteString -> ShortByteString -> Maybe ShortByteString

-- | Check whether one string is a substring of another.
isInfixOf :: ShortByteString -> ShortByteString -> Bool

-- | <i>O(n)</i> The <a>isPrefixOf</a> function takes two ShortByteStrings
--   and returns <a>True</a>
isPrefixOf :: ShortByteString -> ShortByteString -> Bool

-- | <i>O(n)</i> The <a>isSuffixOf</a> function takes two ShortByteStrings
--   and returns <a>True</a> iff the first is a suffix of the second.
--   
--   The following holds:
--   
--   <pre>
--   isSuffixOf x y == reverse x `isPrefixOf` reverse y
--   </pre>
isSuffixOf :: ShortByteString -> ShortByteString -> Bool

-- | Break a string on a substring, returning a pair of the part of the
--   string prior to the match, and the rest of the string.
--   
--   The following relationships hold:
--   
--   <pre>
--   break (== c) l == breakSubstring (singleton c) l
--   </pre>
--   
--   For example, to tokenise a string, dropping delimiters:
--   
--   <pre>
--   tokenise x y = h : if null t then [] else tokenise x (drop (length x) t)
--       where (h,t) = breakSubstring x y
--   </pre>
--   
--   To skip to the first occurrence of a string:
--   
--   <pre>
--   snd (breakSubstring x y)
--   </pre>
--   
--   To take the parts of a string before a delimiter:
--   
--   <pre>
--   fst (breakSubstring x y)
--   </pre>
--   
--   Note that calling `breakSubstring x` does some preprocessing work, so
--   you should avoid unnecessarily duplicating breakSubstring calls with
--   the same pattern.
breakSubstring :: ShortByteString -> ShortByteString -> (ShortByteString, ShortByteString)

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

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

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

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

-- | <i>O(1)</i> <a>ShortByteString</a> index (subscript) operator,
--   starting from 0.
index :: HasCallStack => ShortByteString -> Int -> Word8

-- | <i>O(1)</i> <a>ShortByteString</a> index, starting from 0, that
--   returns <a>Just</a> if:
--   
--   <pre>
--   0 &lt;= n &lt; length bs
--   </pre>
indexMaybe :: ShortByteString -> Int -> Maybe Word8

-- | <i>O(1)</i> <a>ShortByteString</a> index, starting from 0, that
--   returns <a>Just</a> if:
--   
--   <pre>
--   0 &lt;= n &lt; length bs
--   </pre>
(!?) :: ShortByteString -> Int -> Maybe Word8

-- | <i>O(n)</i> The <a>elemIndex</a> function returns the index of the
--   first element in the given <a>ShortByteString</a> which is equal to
--   the query element, or <a>Nothing</a> if there is no such element.
elemIndex :: Word8 -> ShortByteString -> Maybe Int

-- | <i>O(n)</i> The <a>elemIndices</a> function extends <a>elemIndex</a>,
--   by returning the indices of all elements equal to the query element,
--   in ascending order.
elemIndices :: Word8 -> ShortByteString -> [Int]

-- | count returns the number of times its argument appears in the
--   ShortByteString
count :: Word8 -> ShortByteString -> Int

-- | <i>O(n)</i> The <a>findIndex</a> function takes a predicate and a
--   <a>ShortByteString</a> and returns the index of the first element in
--   the ByteString satisfying the predicate.
findIndex :: (Word8 -> Bool) -> ShortByteString -> Maybe Int

-- | <i>O(n)</i> The <a>findIndices</a> function extends <a>findIndex</a>,
--   by returning the indices of all elements satisfying the predicate, in
--   ascending order.
findIndices :: (Word8 -> Bool) -> ShortByteString -> [Int]

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

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

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

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


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

-- | A variety of <a>head</a> for non-empty ByteStrings. <a>unsafeHead</a>
--   omits the check for the empty case, so there is an obligation on the
--   programmer 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>
--   omits the check for the empty case. As with <a>unsafeHead</a>, the
--   programmer must provide a separate proof that the ByteString is
--   non-empty.
unsafeTail :: ByteString -> ByteString

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

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

-- | Unsafe <a>ByteString</a> index (subscript) operator, starting from 0,
--   returning a <a>Word8</a> This omits the bounds check, which means
--   there is an accompanying obligation on the programmer to ensure the
--   bounds 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
--   is an obligation on the programmer to provide a proof that <tt>0 &lt;=
--   n &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
--   is an obligation on the programmer to provide a proof that <tt>0 &lt;=
--   n &lt;= <a>length</a> xs</tt>.
unsafeDrop :: Int -> ByteString -> ByteString

-- | <i>O(1) construction</i> Use a <a>ByteString</a> with a function
--   requiring a <a>CString</a>.
--   
--   This function does zero copying, and merely unwraps a
--   <a>ByteString</a> to appear as a <a>CString</a>. It is <i>unsafe</i>
--   in two ways:
--   
--   <ul>
--   <li>After calling this function the <a>CString</a> shares the
--   underlying byte buffer with the original <a>ByteString</a>. Thus
--   modifying the <a>CString</a>, either in C, or using poke, will cause
--   the contents of the <a>ByteString</a> to change, breaking referential
--   transparency. Other <a>ByteString</a>s created by sharing (such as
--   those produced via <a>take</a> or <a>drop</a>) will also reflect these
--   changes. Modifying the <a>CString</a> will break referential
--   transparency. To avoid this, use <a>useAsCString</a>, which makes a
--   copy of the original <a>ByteString</a>.</li>
--   <li><a>CString</a>s are often passed to functions that require them to
--   be null-terminated. If the original <a>ByteString</a> wasn't null
--   terminated, neither will the <a>CString</a> be. It is the programmers
--   responsibility to guarantee that the <a>ByteString</a> is indeed null
--   terminated. If in doubt, use <a>useAsCString</a>.</li>
--   <li>The memory may freed at any point after the subcomputation
--   terminates, so the pointer to the storage must *not* be used after
--   this.</li>
--   </ul>
unsafeUseAsCString :: ByteString -> (CString -> IO a) -> IO a

-- | <i>O(1) construction</i> Use a <a>ByteString</a> with a function
--   requiring a <a>CStringLen</a>.
--   
--   This function does zero copying, and merely unwraps a
--   <a>ByteString</a> to appear as a <a>CStringLen</a>. It is
--   <i>unsafe</i>:
--   
--   <ul>
--   <li>After calling this function the <a>CStringLen</a> shares the
--   underlying byte buffer with the original <a>ByteString</a>. Thus
--   modifying the <a>CStringLen</a>, either in C, or using poke, will
--   cause the contents of the <a>ByteString</a> to change, breaking
--   referential transparency. Other <a>ByteString</a>s created by sharing
--   (such as those produced via <a>take</a> or <a>drop</a>) will also
--   reflect these changes. Modifying the <a>CStringLen</a> will break
--   referential transparency. To avoid this, use <a>useAsCStringLen</a>,
--   which makes a copy of the original <a>ByteString</a>.</li>
--   </ul>
--   
--   If <a>empty</a> is given, it will pass <tt>(<a>nullPtr</a>, 0)</tt>.
unsafeUseAsCStringLen :: ByteString -> (CStringLen -> IO a) -> IO a

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

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

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

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

-- | <i>O(n)</i> Pack a null-terminated sequence of bytes, pointed to by an
--   Addr# (an arbitrary machine address assumed to point outside the
--   garbage-collected heap) into a <tt>ByteString</tt>. A much faster way
--   to create an <a>Addr#</a> is with an unboxed string literal, than to
--   pack a boxed string. A unboxed string literal is compiled to a static
--   <tt>char []</tt> by GHC. Establishing the length of the string
--   requires a call to <tt>strlen(3)</tt>, so the <a>Addr#</a> must point
--   to a null-terminated buffer (as is the case with <tt>"string"#</tt>
--   literals in GHC). Use <a>unsafePackAddressLen</a> if you know the
--   length of the string statically.
--   
--   An example:
--   
--   <pre>
--   literalFS = unsafePackAddress "literal"#
--   </pre>
--   
--   This function is <i>unsafe</i>. If you modify the buffer pointed to by
--   the original <a>Addr#</a> this modification will be reflected in the
--   resulting <tt>ByteString</tt>, breaking referential transparency.
--   
--   Note this also won't work if your <a>Addr#</a> has embedded
--   <tt>'\0'</tt> characters in 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
--   construction of <a>ByteString</a>s, which is ideal for string
--   literals. It packs a sequence of bytes into a <a>ByteString</a>, given
--   a raw <a>Addr#</a> to the string, and the length of the string.
--   
--   This function is <i>unsafe</i> in two ways:
--   
--   <ul>
--   <li>the length argument is assumed to be correct. If the length
--   argument is incorrect, it is possible to overstep the end of the byte
--   array.</li>
--   <li>if the underlying <a>Addr#</a> is later modified, this change will
--   be reflected in the resulting <a>ByteString</a>, breaking referential
--   transparency.</li>
--   </ul>
--   
--   If 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
--   buffer, a length, and an IO action representing a finalizer. This
--   function is not available on Hugs.
--   
--   This function is <i>unsafe</i>, it is possible to break referential
--   transparency by modifying the underlying buffer pointed to by the
--   first argument. Any changes to the original buffer will be reflected
--   in the resulting <a>ByteString</a>.
unsafePackCStringFinalizer :: Ptr Word8 -> Int -> IO () -> IO ByteString

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


-- | A time- and space-efficient implementation of byte vectors using
--   packed Word8 arrays, suitable for high performance use, both in terms
--   of large data quantities and high speed requirements. Byte vectors are
--   encoded as strict <a>Word8</a> arrays of bytes, held in a
--   <a>ForeignPtr</a>, and can be passed between C and Haskell with little
--   effort.
--   
--   The recomended way to assemble ByteStrings from smaller parts is to
--   use the builder monoid from <a>Data.ByteString.Builder</a>.
--   
--   This module is intended to be imported <tt>qualified</tt>, to avoid
--   name clashes with <a>Prelude</a> functions. eg.
--   
--   <pre>
--   import qualified Data.ByteString as B
--   </pre>
--   
--   Original GHC implementation by Bryan O'Sullivan. Rewritten to use
--   <a>UArray</a> by Simon Marlow. Rewritten to support slices and use
--   <a>ForeignPtr</a> by David Roundy. Rewritten again and extended by Don
--   Stewart and Duncan Coutts.
module Data.ByteString

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

-- | Type synonym for the strict flavour of <a>ByteString</a>.
type StrictByteString = 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
--   <a>ByteString</a>.
--   
--   For applications with large numbers of string literals, <a>pack</a>
--   can be a bottleneck. In such cases, consider using
--   <a>unsafePackAddress</a> (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(1)</i> Convert a strict <a>ByteString</a> into a lazy
--   <a>ByteString</a>.
fromStrict :: ByteString -> ByteString

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

-- | Convert a <a>FilePath</a> to a <a>ByteString</a>.
--   
--   The <a>FilePath</a> type is expected to use the file system encoding
--   as reported by <a>getFileSystemEncoding</a>. This encoding allows for
--   round-tripping of arbitrary data on platforms that allow arbitrary
--   bytes in their paths. This conversion function does the same thing
--   that <a>openFile</a> would do when decoding the <a>FilePath</a>.
--   
--   This function is in <a>IO</a> because the file system encoding can be
--   changed. If the encoding can be assumed to be constant in your use
--   case, you may invoke this function via <a>unsafePerformIO</a>.
fromFilePath :: FilePath -> IO ByteString

-- | Convert a <a>ByteString</a> to a <a>FilePath</a>.
--   
--   This function uses the file system encoding, and resulting
--   <a>FilePath</a>s can be safely used with standard IO functions and
--   will reference the correct path in the presence of arbitrary non-UTF-8
--   encoded paths.
--   
--   This function is in <a>IO</a> because the file system encoding can be
--   changed. If the encoding can be assumed to be constant in your use
--   case, you may invoke this function via <a>unsafePerformIO</a>.
toFilePath :: ByteString -> IO FilePath

-- | <i>O(n)</i> <a>cons</a> is analogous to (:) for lists, but of
--   different 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
--   non-empty. An exception will be thrown in the case of an empty
--   ByteString.
head :: HasCallStack => ByteString -> Word8

-- | <i>O(1)</i> Extract the head and tail of a ByteString, returning
--   Nothing 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,
--   returning Nothing if it is empty.
unsnoc :: ByteString -> Maybe (ByteString, Word8)

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

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

-- | <i>O(1)</i> Return all the elements of a <a>ByteString</a> except the
--   last one. An exception will be thrown in the case of an empty
--   ByteString.
init :: HasCallStack => 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
--   <a>Int</a>.
length :: ByteString -> Int

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

-- | <i>O(n)</i> <a>reverse</a> <tt>xs</tt> efficiently returns the
--   elements 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
--   <a>ByteString</a> and `intersperses' that byte between the elements of
--   the <a>ByteString</a>. It is analogous to the intersperse function on
--   Lists.
intersperse :: Word8 -> ByteString -> ByteString

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

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

-- | <a>foldl</a>, applied to a binary operator, a starting value
--   (typically the left-identity of the operator), and a ByteString,
--   reduces the ByteString using the binary operator, from left to right.
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
--   argument, and thus must be applied to non-empty <a>ByteString</a>s. An
--   exception will be thrown in the case of an empty ByteString.
foldl1 :: HasCallStack => (Word8 -> Word8 -> Word8) -> ByteString -> Word8

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

-- | <a>foldr</a>, applied to a binary operator, a starting value
--   (typically the right-identity of the operator), and a ByteString,
--   reduces the ByteString using the binary operator, from right to left.
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
--   argument, and thus must be applied to non-empty <a>ByteString</a>s An
--   exception will be thrown in the case of an empty ByteString.
foldr1 :: HasCallStack => (Word8 -> Word8 -> Word8) -> ByteString -> Word8

-- | <a>foldr1'</a> is a variant of <a>foldr1</a>, but is strict in the
--   accumulator.
foldr1' :: HasCallStack => (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>
--   determines if any element of the <a>ByteString</a> satisfies the
--   predicate.
any :: (Word8 -> Bool) -> ByteString -> Bool

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

-- | <i>O(n)</i> <a>maximum</a> returns the maximum value from a
--   <a>ByteString</a> An exception will be thrown in the case of an empty
--   ByteString.
maximum :: HasCallStack => ByteString -> Word8

-- | <i>O(n)</i> <a>minimum</a> returns the minimum value from a
--   <a>ByteString</a> An exception will be thrown in the case of an empty
--   ByteString.
minimum :: HasCallStack => ByteString -> Word8

-- | <a>scanl</a> is similar to <a>foldl</a>, but returns a list of
--   successive reduced values from the left.
--   
--   <pre>
--   scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
--   </pre>
--   
--   Note that
--   
--   <pre>
--   head (scanl f z xs) == z
--   last (scanl f z xs) == foldl f z xs
--   </pre>
scanl :: (Word8 -> Word8 -> Word8) -> Word8 -> ByteString -> ByteString

-- | <a>scanl1</a> is a variant of <a>scanl</a> that has no starting value
--   argument.
--   
--   <pre>
--   scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
--   </pre>
scanl1 :: (Word8 -> Word8 -> Word8) -> ByteString -> ByteString

-- | <a>scanr</a> is similar to <a>foldr</a>, but returns a list of
--   successive reduced values from the right.
--   
--   <pre>
--   scanr f z [..., x{n-1}, xn] == [..., x{n-1} `f` (xn `f` z), xn `f` z, z]
--   </pre>
--   
--   Note that
--   
--   <pre>
--   head (scanr f z xs) == foldr f z xs
--   last (scanr f z xs) == z
--   </pre>
scanr :: (Word8 -> Word8 -> Word8) -> Word8 -> ByteString -> ByteString

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

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

-- | The <a>mapAccumR</a> function behaves like a combination of <a>map</a>
--   and <a>foldr</a>; it applies a function to each element of a
--   ByteString, passing an accumulating parameter from right to left, and
--   returning a final value of this accumulator together with the new
--   ByteString.
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
--   <tt>n</tt> with <tt>x</tt> the value of every element. The following
--   holds:
--   
--   <pre>
--   replicate w c = unfoldr w (\u -&gt; Just (u,u)) c
--   </pre>
--   
--   This implementation uses <tt>memset(3)</tt>
replicate :: Int -> Word8 -> ByteString

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

-- | <i>O(n)</i> Like <a>unfoldr</a>, <a>unfoldrN</a> builds a ByteString
--   from a seed value. However, the length of the result is limited by the
--   first argument to <a>unfoldrN</a>. This function is more efficient
--   than <a>unfoldr</a> when the maximum length of the result is known.
--   
--   The following equation relates <a>unfoldrN</a> and <a>unfoldr</a>:
--   
--   <pre>
--   fst (unfoldrN n f s) == take n (unfoldr f s)
--   </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
--   <tt>xs</tt>, returns the prefix of <tt>xs</tt> of length <tt>n</tt>,
--   or <tt>xs</tt> itself if <tt>n &gt; <a>length</a> xs</tt>.
take :: Int -> ByteString -> ByteString

-- | <i>O(1)</i> <tt><a>takeEnd</a> n xs</tt> is equivalent to
--   <tt><a>drop</a> (<a>length</a> xs - n) xs</tt>. Takes <tt>n</tt>
--   elements from end of bytestring.
--   
--   <pre>
--   &gt;&gt;&gt; takeEnd 3 "abcdefg"
--   "efg"
--   
--   &gt;&gt;&gt; takeEnd 0 "abcdefg"
--   ""
--   
--   &gt;&gt;&gt; takeEnd 4 "abc"
--   "abc"
--   </pre>
takeEnd :: Int -> ByteString -> ByteString

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

-- | <i>O(1)</i> <tt><a>dropEnd</a> n xs</tt> is equivalent to
--   <tt><a>take</a> (<a>length</a> xs - n) xs</tt>. Drops <tt>n</tt>
--   elements from end of bytestring.
--   
--   <pre>
--   &gt;&gt;&gt; dropEnd 3 "abcdefg"
--   "abcd"
--   
--   &gt;&gt;&gt; dropEnd 0 "abcdefg"
--   "abcdefg"
--   
--   &gt;&gt;&gt; dropEnd 4 "abc"
--   ""
--   </pre>
dropEnd :: Int -> ByteString -> ByteString

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

-- | Similar to <a>takeWhile</a>, returns the longest (possibly empty)
--   prefix of elements satisfying the predicate.
takeWhile :: (Word8 -> Bool) -> ByteString -> ByteString

-- | Returns the longest (possibly empty) suffix of elements satisfying the
--   predicate.
--   
--   <tt><a>takeWhileEnd</a> p</tt> is equivalent to <tt><a>reverse</a> .
--   <a>takeWhile</a> p . <a>reverse</a></tt>.
takeWhileEnd :: (Word8 -> Bool) -> ByteString -> ByteString

-- | Similar to <a>dropWhile</a>, drops the longest (possibly empty) prefix
--   of elements satisfying the predicate and returns the remainder.
dropWhile :: (Word8 -> Bool) -> ByteString -> ByteString

-- | Similar to <a>dropWhileEnd</a>, drops the longest (possibly empty)
--   suffix of elements satisfying the predicate and returns the remainder.
--   
--   <tt><a>dropWhileEnd</a> p</tt> is equivalent to <tt><a>reverse</a> .
--   <a>dropWhile</a> p . <a>reverse</a></tt>.
dropWhileEnd :: (Word8 -> Bool) -> ByteString -> ByteString

-- | Similar to <a>span</a>, returns the longest (possibly empty) prefix of
--   elements satisfying the predicate and the remainder of the string.
--   
--   <a>span</a> <tt>p</tt> is equivalent to <tt><a>break</a> (not .
--   p)</tt> and to <tt>(<a>takeWhile</a> p &amp;&amp;&amp;
--   <a>dropWhile</a> p)</tt>.
span :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | Returns the longest (possibly empty) suffix of elements satisfying the
--   predicate and the remainder of the string.
--   
--   <a>spanEnd</a> <tt>p</tt> is equivalent to <tt><a>breakEnd</a> (not .
--   p)</tt> and to <tt>(<a>takeWhileEnd</a> p &amp;&amp;&amp;
--   <a>dropWhileEnd</a> p)</tt>.
--   
--   We have
--   
--   <pre>
--   spanEnd (not . isSpace) "x y z" == ("x y ", "z")
--   </pre>
--   
--   and
--   
--   <pre>
--   spanEnd (not . isSpace) ps
--      ==
--   let (x, y) = span (not . isSpace) (reverse ps) in (reverse y, reverse x)
--   </pre>
spanEnd :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | Similar to <a>break</a>, returns the longest (possibly empty) prefix
--   of elements which <b>do not</b> satisfy the predicate and the
--   remainder of the string.
--   
--   <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (not .
--   p)</tt> and to <tt>(<a>takeWhile</a> (not . p) &amp;&amp;&amp;
--   <a>dropWhile</a> (not . p))</tt>.
--   
--   Under GHC, a rewrite rule will transform break (==) into a call to the
--   specialised breakByte:
--   
--   <pre>
--   break ((==) x) = breakByte x
--   break (==x) = breakByte x
--   </pre>
break :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | Returns the longest (possibly empty) suffix of elements which <b>do
--   not</b> satisfy the predicate and the remainder of the string.
--   
--   <a>breakEnd</a> <tt>p</tt> is equivalent to <tt><a>spanEnd</a> (not .
--   p)</tt> and to <tt>(<a>takeWhileEnd</a> (not . p) &amp;&amp;&amp;
--   <a>dropWhileEnd</a> (not . p))</tt>.
breakEnd :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

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

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

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

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

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

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

-- | <i>O(n)</i> Break a <a>ByteString</a> into pieces separated by the
--   byte argument, consuming the delimiter. I.e.
--   
--   <pre>
--   split 10  "a\nb\nd\ne" == ["a","b","d","e"]   -- fromEnum '\n' == 10
--   split 97  "aXaXaXa"    == ["","X","X","X",""] -- fromEnum 'a' == 97
--   split 120 "x"          == ["",""]             -- fromEnum 'x' == 120
--   split undefined ""     == []                  -- and not [""]
--   </pre>
--   
--   and
--   
--   <pre>
--   intercalate [c] . split c == id
--   split == splitWith . (==)
--   </pre>
--   
--   As for all splitting functions in this library, this function does not
--   copy the substrings, it just constructs new <a>ByteString</a>s that
--   are slices of the original.
split :: Word8 -> ByteString -> [ByteString]

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

-- | <i>O(n)</i> The <a>isPrefixOf</a> function takes two ByteStrings and
--   returns <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
--   returns <a>True</a> iff the first is a suffix of the second.
--   
--   The following holds:
--   
--   <pre>
--   isSuffixOf x y == reverse x `isPrefixOf` reverse y
--   </pre>
--   
--   However, the real implementation uses memcmp to compare the end of the
--   string only, with no reverse required..
isSuffixOf :: ByteString -> ByteString -> Bool

-- | Check whether one string is a substring of another.
isInfixOf :: ByteString -> ByteString -> Bool

-- | <i>O(n)</i> Check whether a <a>ByteString</a> represents valid UTF-8.
isValidUtf8 :: ByteString -> Bool

-- | Break a string on a substring, returning a pair of the part of the
--   string prior to the match, and the rest of the string.
--   
--   The following relationships hold:
--   
--   <pre>
--   break (== c) l == breakSubstring (singleton c) l
--   </pre>
--   
--   For example, to tokenise a string, dropping delimiters:
--   
--   <pre>
--   tokenise x y = h : if null t then [] else tokenise x (drop (length x) t)
--       where (h,t) = breakSubstring x y
--   </pre>
--   
--   To skip to the first occurrence of a string:
--   
--   <pre>
--   snd (breakSubstring x y)
--   </pre>
--   
--   To take the parts of a string before a delimiter:
--   
--   <pre>
--   fst (breakSubstring x y)
--   </pre>
--   
--   Note that calling `breakSubstring x` does some preprocessing work, so
--   you should avoid unnecessarily duplicating breakSubstring calls with
--   the same pattern.
breakSubstring :: ByteString -> ByteString -> (ByteString, ByteString)

-- | <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
--   ByteString, and returns the first element in matching the predicate,
--   or <a>Nothing</a> if there is no such element.
--   
--   <pre>
--   find f p = case findIndex f p of Just n -&gt; Just (p ! n) ; _ -&gt; Nothing
--   </pre>
find :: (Word8 -> Bool) -> ByteString -> Maybe Word8

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

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

-- | <i>O(1)</i> <a>ByteString</a> index (subscript) operator, starting
--   from 0.
index :: HasCallStack => ByteString -> Int -> Word8

-- | <i>O(1)</i> <a>ByteString</a> index, starting from 0, that returns
--   <a>Just</a> if:
--   
--   <pre>
--   0 &lt;= n &lt; length bs
--   </pre>
indexMaybe :: ByteString -> Int -> Maybe Word8

-- | <i>O(1)</i> <a>ByteString</a> index, starting from 0, that returns
--   <a>Just</a> if:
--   
--   <pre>
--   0 &lt;= n &lt; length bs
--   </pre>
(!?) :: ByteString -> Int -> Maybe Word8

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

-- | <i>O(n)</i> The <a>elemIndices</a> function extends <a>elemIndex</a>,
--   by returning the indices of all elements equal to the query element,
--   in 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
--   the element in the given <a>ByteString</a> which is equal to the query
--   element, or <a>Nothing</a> if there is no such element. The following
--   holds:
--   
--   <pre>
--   elemIndexEnd c xs = case elemIndex c (reverse xs) of
--     Nothing -&gt; Nothing
--     Just i  -&gt; Just (length xs - 1 - i)
--   </pre>
elemIndexEnd :: Word8 -> ByteString -> Maybe Int

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

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

-- | <i>O(n)</i> The <a>findIndexEnd</a> function takes a predicate and a
--   <a>ByteString</a> and returns the index of the last element in the
--   ByteString satisfying the predicate.
findIndexEnd :: (Word8 -> Bool) -> ByteString -> Maybe Int

-- | count returns the number of times its argument appears in the
--   ByteString
--   
--   <pre>
--   count = length . elemIndices
--   </pre>
--   
--   But 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
--   corresponding pairs of bytes. If one input ByteString is short, excess
--   elements of the longer ByteString are discarded. This is equivalent to
--   a pair of <a>unpack</a> operations.
zip :: ByteString -> ByteString -> [(Word8, Word8)]

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

-- | A specialised version of <a>zipWith</a> for the common case of a
--   simultaneous map over two ByteStrings, to build a 3rd.
packZipWith :: (Word8 -> Word8 -> Word8) -> ByteString -> ByteString -> ByteString

-- | <i>O(n)</i> <a>unzip</a> transforms a list of pairs of bytes into a
--   pair of ByteStrings. Note that this performs two <a>pack</a>
--   operations.
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.
--   This is mainly useful to allow the rest of the data pointed to by the
--   <a>ByteString</a> to be garbage collected, for example if a large
--   string has been read in, and only a small part of it is needed in the
--   rest of the program.
copy :: ByteString -> ByteString

-- | <i>O(n).</i> Construct a new <tt>ByteString</tt> from a
--   <tt>CString</tt>. The resulting <tt>ByteString</tt> is an immutable
--   copy of the original <tt>CString</tt>, and is managed on the Haskell
--   heap. 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
--   <tt>CStringLen</tt>. The resulting <tt>ByteString</tt> is an immutable
--   copy of the original <tt>CStringLen</tt>. The <tt>ByteString</tt> is a
--   normal 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
--   requiring a null-terminated <tt>CString</tt>. The <tt>CString</tt> is
--   a copy and will be freed automatically; it must not be stored or used
--   after the subcomputation finishes.
useAsCString :: ByteString -> (CString -> IO a) -> IO a

-- | <i>O(n) construction</i> Use a <tt>ByteString</tt> with a function
--   requiring a <tt>CStringLen</tt>. As for <tt>useAsCString</tt> this
--   function makes a copy of the original <tt>ByteString</tt>. It must not
--   be 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
--   <a>Handle</a> is closed after the contents have been read.
getContents :: IO ByteString

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

-- | The interact function takes a function of type <tt>ByteString -&gt;
--   ByteString</tt> as its argument. The entire input from the standard
--   input device is passed to this function as its argument, and the
--   resulting string is output on the standard output device.
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>.
--   
--   This function reads chunks at a time, increasing the chunk size on
--   each read. The final string is then reallocated to the appropriate
--   size. For files &gt; half of available memory, this may lead to memory
--   exhaustion. Consider using <a>readFile</a> in this case.
--   
--   The Handle is closed once the contents have been read, or if an
--   exception is thrown.
hGetContents :: Handle -> IO ByteString

-- | Read a <a>ByteString</a> directly from the specified <a>Handle</a>.
--   This is far more efficient than reading the characters into a
--   <a>String</a> and then using <a>pack</a>. First argument is the Handle
--   to read from, and the second is the number of bytes to read. It
--   returns the bytes read, up to n, or <a>empty</a> if EOF has been
--   reached.
--   
--   <a>hGet</a> is implemented in terms of <a>hGetBuf</a>.
--   
--   If the handle is a pipe or socket, and the writing end is closed,
--   <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
--   returned if there are not enough bytes immediately available to
--   satisfy the whole request. <a>hGetSome</a> only blocks if there is no
--   data 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
--   block waiting for data to become available, instead it returns only
--   whatever data is available. If there is no data available to be read,
--   <a>hGetNonBlocking</a> returns <a>empty</a>.
--   
--   Note: on Windows and with Haskell implementation other than GHC, this
--   function does not work correctly; it behaves identically to
--   <a>hGet</a>.
hGetNonBlocking :: 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
--   returns any tail that did not get written. This tail may be
--   <a>empty</a> in the case that the whole string was written, or the
--   whole original string if nothing was written. Partial writes are also
--   possible.
--   
--   Note: on Windows and with Haskell implementation other than GHC, this
--   function does not work correctly; it behaves identically to
--   <a>hPut</a>.
hPutNonBlocking :: Handle -> ByteString -> IO ByteString

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


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

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

-- | Type synonym for the lazy flavour of <a>ByteString</a>.
type LazyByteString = 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
--   <a>ByteString</a>.
fromStrict :: ByteString -> ByteString

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

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

-- | <i>O(c)</i> Convert a lazy <a>ByteString</a> into a list of strict
--   <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,
--   accumulating left fold.
foldlChunks :: (a -> ByteString -> a) -> a -> ByteString -> a

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

-- | <i>O(1)</i> Unlike <a>cons</a>, <a>cons'</a> is strict in the
--   ByteString that we are consing onto. More precisely, it forces the
--   head and the first chunk. It does this because, for space efficiency,
--   it may coalesce the new byte onto the first 'chunk' rather than
--   starting a new 'chunk'.
--   
--   So that means you can't use a lazy recursive contruction like this:
--   
--   <pre>
--   let xs = cons' c xs in xs
--   </pre>
--   
--   You can however use <a>cons</a>, as well as <a>repeat</a> and
--   <a>cycle</a>, to build infinite lazy ByteStrings.
cons' :: 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
--   non-empty.
head :: HasCallStack => ByteString -> Word8

-- | <i>O(1)</i> Extract the head and tail of a ByteString, returning
--   Nothing 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,
--   returning Nothing if it is empty.
--   
--   <ul>
--   <li>It is no faster than using <a>init</a> and <a>last</a></li>
--   </ul>
unsnoc :: ByteString -> Maybe (ByteString, Word8)

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

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

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

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

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

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

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

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

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

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

-- | <a>foldl</a>, applied to a binary operator, a starting value
--   (typically the left-identity of the operator), and a ByteString,
--   reduces the ByteString using the binary operator, from left to right.
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
--   argument, and thus must be applied to non-empty <a>ByteString</a>s.
foldl1 :: HasCallStack => (Word8 -> Word8 -> Word8) -> ByteString -> Word8

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

-- | <a>foldr</a>, applied to a binary operator, a starting value
--   (typically the right-identity of the operator), and a ByteString,
--   reduces the ByteString using the binary operator, from right to left.
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
--   argument, and thus must be applied to non-empty <a>ByteString</a>s
foldr1 :: HasCallStack => (Word8 -> Word8 -> Word8) -> ByteString -> Word8

-- | <a>foldr1'</a> is like <a>foldr1</a>, but strict in the accumulator.
foldr1' :: HasCallStack => (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>
--   determines if any element of the <a>ByteString</a> satisfies the
--   predicate.
any :: (Word8 -> Bool) -> ByteString -> Bool

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

-- | <i>O(n)</i> <a>maximum</a> returns the maximum value from a
--   <a>ByteString</a>
maximum :: HasCallStack => ByteString -> Word8

-- | <i>O(n)</i> <a>minimum</a> returns the minimum value from a
--   <a>ByteString</a>
minimum :: HasCallStack => ByteString -> Word8

-- | <i>O(c)</i> <a>compareLength</a> compares the length of a
--   <a>ByteString</a> to an <a>Int64</a>
compareLength :: ByteString -> Int64 -> Ordering

-- | <a>scanl</a> is similar to <a>foldl</a>, but returns a list of
--   successive reduced values from the left.
--   
--   <pre>
--   scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
--   </pre>
--   
--   Note that
--   
--   <pre>
--   head (scanl f z xs) == z
--   last (scanl f z xs) == foldl f z xs
--   </pre>
scanl :: (Word8 -> Word8 -> Word8) -> Word8 -> ByteString -> ByteString

-- | <a>scanl1</a> is a variant of <a>scanl</a> that has no starting value
--   argument.
--   
--   <pre>
--   scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
--   </pre>
scanl1 :: (Word8 -> Word8 -> Word8) -> ByteString -> ByteString

-- | <a>scanr</a> is similar to <a>foldr</a>, but returns a list of
--   successive reduced values from the right.
--   
--   <pre>
--   scanr f z [..., x{n-1}, xn] == [..., x{n-1} `f` (xn `f` z), xn `f` z, z]
--   </pre>
--   
--   Note that
--   
--   <pre>
--   head (scanr f z xs) == foldr f z xs
--   last (scanr f z xs) == z
--   </pre>
scanr :: (Word8 -> Word8 -> Word8) -> Word8 -> ByteString -> ByteString

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

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

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

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

-- | <i>O(n)</i> <tt><a>replicate</a> n x</tt> is a ByteString of length
--   <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
--   equivalently, the infinite repetition of the original ByteString.
cycle :: HasCallStack => ByteString -> ByteString

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

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

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

-- | <i>O(c)</i> <tt><a>takeEnd</a> n xs</tt> is equivalent to
--   <tt><a>drop</a> (<a>length</a> xs - n) xs</tt>. Takes <tt>n</tt>
--   elements from end of bytestring.
--   
--   <pre>
--   &gt;&gt;&gt; takeEnd 3 "abcdefg"
--   "efg"
--   
--   &gt;&gt;&gt; takeEnd 0 "abcdefg"
--   ""
--   
--   &gt;&gt;&gt; takeEnd 4 "abc"
--   "abc"
--   </pre>
takeEnd :: Int64 -> ByteString -> ByteString

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

-- | <i>O(n)</i> <tt><a>dropEnd</a> n xs</tt> is equivalent to
--   <tt><a>take</a> (<a>length</a> xs - n) xs</tt>. Drops <tt>n</tt>
--   elements from end of bytestring.
--   
--   <pre>
--   &gt;&gt;&gt; dropEnd 3 "abcdefg"
--   "abcd"
--   
--   &gt;&gt;&gt; dropEnd 0 "abcdefg"
--   "abcdefg"
--   
--   &gt;&gt;&gt; dropEnd 4 "abc"
--   ""
--   </pre>
dropEnd :: Int64 -> ByteString -> ByteString

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

-- | Similar to <a>takeWhile</a>, returns the longest (possibly empty)
--   prefix of elements satisfying the predicate.
takeWhile :: (Word8 -> Bool) -> ByteString -> ByteString

-- | Returns the longest (possibly empty) suffix of elements satisfying the
--   predicate.
--   
--   <tt><a>takeWhileEnd</a> p</tt> is equivalent to <tt><a>reverse</a> .
--   <a>takeWhile</a> p . <a>reverse</a></tt>.
--   
--   <pre>
--   &gt;&gt;&gt; {-# LANGUAGE OverloadedLists #-)
--   
--   &gt;&gt;&gt; takeWhileEnd even [1,2,3,4,6]
--   [4,6]
--   </pre>
takeWhileEnd :: (Word8 -> Bool) -> ByteString -> ByteString

-- | Similar to <a>dropWhile</a>, drops the longest (possibly empty) prefix
--   of elements satisfying the predicate and returns the remainder.
dropWhile :: (Word8 -> Bool) -> ByteString -> ByteString

-- | Similar to <a>dropWhileEnd</a>, drops the longest (possibly empty)
--   suffix of elements satisfying the predicate and returns the remainder.
--   
--   <tt><a>dropWhileEnd</a> p</tt> is equivalent to <tt><a>reverse</a> .
--   <a>dropWhile</a> p . <a>reverse</a></tt>.
--   
--   <pre>
--   &gt;&gt;&gt; {-# LANGUAGE OverloadedLists #-)
--   
--   &gt;&gt;&gt; dropWhileEnd even [1,2,3,4,6]
--   [1,2,3]
--   </pre>
dropWhileEnd :: (Word8 -> Bool) -> ByteString -> ByteString

-- | Similar to <a>span</a>, returns the longest (possibly empty) prefix of
--   elements satisfying the predicate and the remainder of the string.
--   
--   <a>span</a> <tt>p</tt> is equivalent to <tt><a>break</a> (not .
--   p)</tt> and to <tt>(<a>takeWhile</a> p &amp;&amp;&amp;
--   <a>dropWhile</a> p)</tt>.
span :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | Returns the longest (possibly empty) suffix of elements satisfying the
--   predicate and the remainder of the string.
--   
--   <a>spanEnd</a> <tt>p</tt> is equivalent to <tt><a>breakEnd</a> (not .
--   p)</tt> and to <tt>(<a>takeWhileEnd</a> p &amp;&amp;&amp;
--   <a>dropWhileEnd</a> p)</tt>.
--   
--   We have
--   
--   <pre>
--   spanEnd (not . isSpace) "x y z" == ("x y ", "z")
--   </pre>
--   
--   and
--   
--   <pre>
--   spanEnd (not . isSpace) ps
--      ==
--   let (x, y) = span (not . isSpace) (reverse ps) in (reverse y, reverse x)
--   </pre>
spanEnd :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | Similar to <a>break</a>, returns the longest (possibly empty) prefix
--   of elements which <b>do not</b> satisfy the predicate and the
--   remainder of the string.
--   
--   <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (not .
--   p)</tt> and to <tt>(<a>takeWhile</a> (not . p) &amp;&amp;&amp;
--   <a>dropWhile</a> (not . p))</tt>.
break :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | Returns the longest (possibly empty) suffix of elements which <b>do
--   not</b> satisfy the predicate and the remainder of the string.
--   
--   <a>breakEnd</a> <tt>p</tt> is equivalent to <tt><a>spanEnd</a> (not .
--   p)</tt> and to <tt>(<a>takeWhileEnd</a> (not . p) &amp;&amp;&amp;
--   <a>dropWhileEnd</a> (not . p))</tt>.
breakEnd :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

-- | The <a>group</a> function takes a ByteString and returns a list of
--   ByteStrings such that the concatenation of the result is equal to the
--   argument. Moreover, each string in the result contains only equal
--   elements. For example,
--   
--   <pre>
--   group "Mississippi" = ["M","i","ss","i","ss","i","pp","i"]
--   </pre>
--   
--   It is a special case of <a>groupBy</a>, which allows the programmer to
--   supply their own equality test.
group :: ByteString -> [ByteString]

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

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

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

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

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

-- | <i>O(n)</i> Break a <a>ByteString</a> into pieces separated by the
--   byte argument, consuming the delimiter. I.e.
--   
--   <pre>
--   split 10  "a\nb\nd\ne" == ["a","b","d","e"]   -- fromEnum '\n' == 10
--   split 97  "aXaXaXa"    == ["","X","X","X",""] -- fromEnum 'a' == 97
--   split 120 "x"          == ["",""]             -- fromEnum 'x' == 120
--   split undefined ""     == []                  -- and not [""]
--   </pre>
--   
--   and
--   
--   <pre>
--   intercalate [c] . split c == id
--   split == splitWith . (==)
--   </pre>
--   
--   As for all splitting functions in this library, this function does not
--   copy the substrings, it just constructs new <a>ByteString</a>s that
--   are slices of the original.
split :: Word8 -> ByteString -> [ByteString]

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

-- | <i>O(n)</i> The <a>isPrefixOf</a> function takes two ByteStrings and
--   returns <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
--   returns <a>True</a> iff the first is a suffix of the second.
--   
--   The following holds:
--   
--   <pre>
--   isSuffixOf x y == reverse x `isPrefixOf` reverse y
--   </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
--   ByteString, and returns the first element in matching the predicate,
--   or <a>Nothing</a> if there is no such element.
--   
--   <pre>
--   find f p = case findIndex f p of Just n -&gt; Just (p ! n) ; _ -&gt; Nothing
--   </pre>
find :: (Word8 -> Bool) -> ByteString -> Maybe Word8

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

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

-- | <i>O(c)</i> <a>ByteString</a> index (subscript) operator, starting
--   from 0.
index :: HasCallStack => ByteString -> Int64 -> Word8

-- | <i>O(c)</i> <a>ByteString</a> index, starting from 0, that returns
--   <a>Just</a> if:
--   
--   <pre>
--   0 &lt;= n &lt; length bs
--   </pre>
indexMaybe :: ByteString -> Int64 -> Maybe Word8

-- | <i>O(1)</i> <a>ByteString</a> index, starting from 0, that returns
--   <a>Just</a> if:
--   
--   <pre>
--   0 &lt;= n &lt; length bs
--   </pre>
(!?) :: ByteString -> Int64 -> Maybe Word8

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

-- | <i>O(n)</i> The <a>elemIndexEnd</a> function returns the last index of
--   the element in the given <a>ByteString</a> which is equal to the query
--   element, or <a>Nothing</a> if there is no such element. The following
--   holds:
--   
--   <pre>
--   elemIndexEnd c xs = case elemIndex c (reverse xs) of
--     Nothing -&gt; Nothing
--     Just i  -&gt; Just (length xs - 1 - i)
--   </pre>
elemIndexEnd :: Word8 -> ByteString -> Maybe Int64

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

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

-- | The <a>findIndexEnd</a> function takes a predicate and a
--   <a>ByteString</a> and returns the index of the last element in the
--   ByteString satisfying the predicate.
findIndexEnd :: (Word8 -> Bool) -> ByteString -> Maybe Int64

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

-- | count returns the number of times its argument appears in the
--   ByteString
--   
--   <pre>
--   count = length . elemIndices
--   </pre>
--   
--   But 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
--   corresponding pairs of bytes. If one input ByteString is short, excess
--   elements of the longer ByteString are discarded. This is equivalent to
--   a pair of <a>unpack</a> operations.
zip :: ByteString -> ByteString -> [(Word8, Word8)]

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

-- | A specialised version of <a>zipWith</a> for the common case of a
--   simultaneous map over two ByteStrings, to build a 3rd.
packZipWith :: (Word8 -> Word8 -> Word8) -> ByteString -> ByteString -> ByteString

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

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

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

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

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

-- | Read an entire file <i>lazily</i> into a <a>ByteString</a>.
--   
--   The <a>Handle</a> will be held open until EOF is encountered.
--   
--   Note that this function's implementation relies on
--   <a>hGetContents</a>. The reader is advised to read its documentation.
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>.
--   Chunks are read on demand, using the default chunk size.
--   
--   File handles are closed on EOF if all the file is read, or through
--   garbage collection otherwise.
hGetContents :: Handle -> IO ByteString

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

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

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

-- | Similar to <a>hPut</a> except that it will never block. Instead it
--   returns any tail that did not get written. This tail may be
--   <a>empty</a> in the case that the whole string was written, or the
--   whole original string if nothing was written. Partial writes are also
--   possible.
--   
--   Note: on Windows and with Haskell implementation other than GHC, this
--   function does not work correctly; it behaves identically to
--   <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>
--   operations. All Chars will be truncated to 8 bits. It can be expected
--   that these functions will run at identical speeds to their
--   <a>Word8</a> equivalents in <a>Data.ByteString.Lazy</a>.
--   
--   This module is intended to be imported <tt>qualified</tt>, to avoid
--   name clashes with <a>Prelude</a> functions. eg.
--   
--   <pre>
--   import qualified Data.ByteString.Lazy.Char8 as C
--   </pre>
--   
--   The Char8 interface to bytestrings provides an instance of IsString
--   for the ByteString type, enabling you to use string literals, and have
--   them implicitly packed to ByteStrings. Use <tt>{-# LANGUAGE
--   OverloadedStrings #-}</tt> to enable this.
module Data.ByteString.Lazy.Char8

-- | A space-efficient representation of a <a>Word8</a> vector, supporting
--   many efficient operations.
--   
--   A lazy <a>ByteString</a> contains 8-bit bytes, or by using the
--   operations from <a>Data.ByteString.Lazy.Char8</a> it can be
--   interpreted 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
--   <a>ByteString</a>
fromChunks :: [ByteString] -> ByteString

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

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

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

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

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

-- | <i>O(n)</i> Append a Char to the end of a <a>ByteString</a>. Similar
--   to <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
--   non-empty.
head :: ByteString -> Char

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

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

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

-- | <i>O(n/c)</i> Extract the <a>init</a> and <a>last</a> of a ByteString,
--   returning 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
--   the last one.
init :: HasCallStack => ByteString -> ByteString

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

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

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

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

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

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

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

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

-- | <a>foldl'</a> 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
--   argument, and thus must be applied to non-empty <a>ByteString</a>s.
foldl1 :: (Char -> Char -> Char) -> ByteString -> Char

-- | <a>foldl1'</a> 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
--   (typically the right-identity of the operator), and a packed string,
--   reduces the packed string using the binary operator, from right to
--   left.
foldr :: (Char -> a -> a) -> a -> ByteString -> a

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

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

-- | <a>foldr1'</a> is like <a>foldr1</a>, but strict in the accumulator.
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
--   element 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
--   if 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

-- | <i>O(c)</i> <a>compareLength</a> compares the length of a
--   <a>ByteString</a> to an <a>Int64</a>
compareLength :: ByteString -> Int64 -> Ordering

-- | <a>scanl</a> is similar to <a>foldl</a>, but returns a list of
--   successive reduced values from the left.
--   
--   <pre>
--   scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
--   </pre>
--   
--   Note that
--   
--   <pre>
--   last (scanl f z xs) == foldl f z xs.
--   </pre>
scanl :: (Char -> Char -> Char) -> Char -> ByteString -> ByteString

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

-- | <a>scanr</a> is similar to <a>foldr</a>, but returns a list of
--   successive reduced values from the right.
--   
--   <pre>
--   scanr f z [..., x{n-1}, xn] == [..., x{n-1} `f` (xn `f` z), xn `f` z, z]
--   </pre>
--   
--   Note that
--   
--   <pre>
--   head (scanr f z xs) == foldr f z xs
--   last (scanr f z xs) == z
--   </pre>
scanr :: (Char -> Char -> Char) -> Char -> ByteString -> ByteString

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

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

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

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

-- | <i>O(n)</i> <tt><a>replicate</a> n x</tt> is a ByteString of length
--   <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
--   equivalently, the infinite repetition of the original ByteString.
cycle :: HasCallStack => ByteString -> ByteString

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

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

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

-- | <i>O(c)</i> <tt><a>takeEnd</a> n xs</tt> is equivalent to
--   <tt><a>drop</a> (<a>length</a> xs - n) xs</tt>. Takes <tt>n</tt>
--   elements from end of bytestring.
--   
--   <pre>
--   &gt;&gt;&gt; takeEnd 3 "abcdefg"
--   "efg"
--   
--   &gt;&gt;&gt; takeEnd 0 "abcdefg"
--   ""
--   
--   &gt;&gt;&gt; takeEnd 4 "abc"
--   "abc"
--   </pre>
takeEnd :: Int64 -> ByteString -> ByteString

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

-- | <i>O(n)</i> <tt><a>dropEnd</a> n xs</tt> is equivalent to
--   <tt><a>take</a> (<a>length</a> xs - n) xs</tt>. Drops <tt>n</tt>
--   elements from end of bytestring.
--   
--   <pre>
--   &gt;&gt;&gt; dropEnd 3 "abcdefg"
--   "abcd"
--   
--   &gt;&gt;&gt; dropEnd 0 "abcdefg"
--   "abcdefg"
--   
--   &gt;&gt;&gt; dropEnd 4 "abc"
--   ""
--   </pre>
dropEnd :: Int64 -> ByteString -> ByteString

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

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

-- | Returns the longest (possibly empty) suffix of elements satisfying the
--   predicate.
--   
--   <tt><a>takeWhileEnd</a> p</tt> is equivalent to <tt><a>reverse</a> .
--   <a>takeWhile</a> p . <a>reverse</a></tt>.
takeWhileEnd :: (Char -> Bool) -> ByteString -> ByteString

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

-- | Similar to <a>dropWhileEnd</a>, drops the longest (possibly empty)
--   suffix of elements satisfying the predicate and returns the remainder.
--   
--   <tt><a>dropWhileEnd</a> p</tt> is equivalent to <tt><a>reverse</a> .
--   <a>dropWhile</a> p . <a>reverse</a></tt>.
dropWhileEnd :: (Char -> Bool) -> ByteString -> ByteString

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

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

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

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

-- | The <a>group</a> function takes a ByteString and returns a list of
--   ByteStrings such that the concatenation of the result is equal to the
--   argument. Moreover, each string in the result contains only equal
--   elements. For example,
--   
--   <pre>
--   group "Mississippi" = ["M","i","ss","i","ss","i","pp","i"]
--   </pre>
--   
--   It is a special case of <a>groupBy</a>, which allows the programmer to
--   supply their own equality test.
group :: ByteString -> [ByteString]

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

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

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

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

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

-- | <i>O(n)</i> Break a <a>ByteString</a> into pieces separated by the
--   byte argument, consuming the delimiter. I.e.
--   
--   <pre>
--   split '\n' "a\nb\nd\ne" == ["a","b","d","e"]
--   split 'a'  "aXaXaXa"    == ["","X","X","X"]
--   split 'x'  "x"          == ["",""]
--   split undefined ""      == []  -- and not [""]
--   </pre>
--   
--   and
--   
--   <pre>
--   intercalate [c] . split c == id
--   split == splitWith . (==)
--   </pre>
--   
--   As for all splitting functions in this library, this function does not
--   copy the substrings, it just constructs new <a>ByteString</a>s that
--   are slices of the original.
split :: Char -> ByteString -> [ByteString]

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

-- | <a>lines</a> breaks a ByteString up into a list of ByteStrings at
--   newline Chars (<tt>'\n'</tt>). The resulting strings do not contain
--   newlines.
--   
--   As of bytestring 0.9.0.3, this function is stricter than its list
--   cousin.
--   
--   Note that it <b>does not</b> regard CR (<tt>'\r'</tt>) as a newline
--   character.
lines :: ByteString -> [ByteString]

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

-- | <a>unlines</a> joins lines, appending a terminating newline after
--   each.
--   
--   Equivalent to <tt><a>concat</a> . Data.List.concatMap (\x -&gt; [x,
--   <a>singleton</a> '\n'])</tt>.
unlines :: [ByteString] -> ByteString

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

-- | <i>O(n)</i> The <a>isPrefixOf</a> function takes two ByteStrings and
--   returns <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
--   returns <a>True</a> iff the first is a suffix of the second.
--   
--   The following holds:
--   
--   <pre>
--   isSuffixOf x y == reverse x `isPrefixOf` reverse y
--   </pre>
isSuffixOf :: ByteString -> ByteString -> Bool

-- | <i>O(n)</i> <a>elem</a> is the <a>ByteString</a> membership predicate.
--   This 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
--   ByteString, and returns the first element in matching the predicate,
--   or <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,
--   returns a ByteString containing those characters that satisfy the
--   predicate.
filter :: (Char -> Bool) -> ByteString -> ByteString

partition :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)

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

-- | <i>O(1)</i> <a>ByteString</a> index, starting from 0, that returns
--   <a>Just</a> if:
--   
--   <pre>
--   0 &lt;= n &lt; length bs
--   </pre>
indexMaybe :: ByteString -> Int64 -> Maybe Char

-- | <i>O(1)</i> <a>ByteString</a> index, starting from 0, that returns
--   <a>Just</a> if:
--   
--   <pre>
--   0 &lt;= n &lt; length bs
--   </pre>
(!?) :: ByteString -> Int64 -> Maybe Char

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

-- | <i>O(n)</i> The <a>elemIndexEnd</a> function returns the last index of
--   the element in the given <a>ByteString</a> which is equal to the query
--   element, or <a>Nothing</a> if there is no such element. The following
--   holds:
--   
--   <pre>
--   elemIndexEnd c xs = case elemIndex c (reverse xs) of
--     Nothing -&gt; Nothing
--     Just i  -&gt; Just (length xs - 1 - i)
--   </pre>
elemIndexEnd :: Char -> ByteString -> Maybe Int64

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

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

-- | The <a>findIndexEnd</a> function takes a predicate and a
--   <a>ByteString</a> and returns the index of the last element in the
--   ByteString satisfying the predicate.
findIndexEnd :: (Char -> Bool) -> ByteString -> Maybe Int64

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

-- | count returns the number of times its argument appears in the
--   ByteString
--   
--   <pre>
--   count      == length . elemIndices
--   count '\n' == length . lines
--   </pre>
--   
--   But 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
--   corresponding pairs of Chars. If one input ByteString is short, excess
--   elements of the longer ByteString are discarded. This is equivalent to
--   a pair of <a>unpack</a> operations, and so space usage may be large
--   for multi-megabyte ByteStrings
zip :: ByteString -> ByteString -> [(Char, Char)]

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

-- | A specialised version of <a>zipWith</a> for the common case of a
--   simultaneous map over two ByteStrings, to build a 3rd.
packZipWith :: (Char -> Char -> Char) -> ByteString -> ByteString -> ByteString

-- | <i>O(n)</i> <a>unzip</a> transforms a list of pairs of chars into a
--   pair of ByteStrings. Note that this performs two <a>pack</a>
--   operations.
unzip :: [(Char, Char)] -> (ByteString, ByteString)

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

-- | readInt reads an Int from the beginning of the ByteString. If there is
--   no integer at the beginning of the string, it returns Nothing,
--   otherwise it just returns the int read, and the rest of the string.
--   
--   Note: This function will overflow the Int for large integers.
readInt :: ByteString -> Maybe (Int, ByteString)

-- | readInteger reads an Integer from the beginning of the ByteString. If
--   there is no integer at the beginning of the string, it returns
--   Nothing, otherwise it just returns the int read, and the rest of the
--   string.
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;
--   ByteString</tt> as its argument. The entire input from the standard
--   input device is passed to this function as its argument, and the
--   resulting string is output on the standard output device.
interact :: (ByteString -> ByteString) -> IO ()

-- | Read an entire file <i>lazily</i> into a <a>ByteString</a>.
--   
--   The <a>Handle</a> will be held open until EOF is encountered.
--   
--   Note that this function's implementation relies on
--   <a>hGetContents</a>. The reader is advised to read its documentation.
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>.
--   Chunks are read on demand, using the default chunk size.
--   
--   File handles are closed on EOF if all the file is read, or through
--   garbage collection otherwise.
hGetContents :: Handle -> IO ByteString

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

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

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

-- | Similar to <a>hPut</a> except that it will never block. Instead it
--   returns any tail that did not get written. This tail may be
--   <a>empty</a> in the case that the whole string was written, or the
--   whole original string if nothing was written. Partial writes are also
--   possible.
--   
--   Note: on Windows and with Haskell implementation other than GHC, this
--   function does not work correctly; it behaves identically to
--   <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
--   will be truncated to 8 bits. It can be expected that these functions
--   will run at identical speeds to their <a>Word8</a> equivalents in
--   <a>Data.ByteString</a>.
--   
--   More specifically these byte strings are taken to be in the subset of
--   Unicode covered by code points 0-255. This covers Unicode Basic Latin,
--   Latin-1 Supplement and C0+C1 Controls.
--   
--   See:
--   
--   <ul>
--   <li><a>http://www.unicode.org/charts/</a></li>
--   <li><a>http://www.unicode.org/charts/PDF/U0000.pdf</a></li>
--   <li><a>http://www.unicode.org/charts/PDF/U0080.pdf</a></li>
--   </ul>
--   
--   This module is intended to be imported <tt>qualified</tt>, to avoid
--   name clashes with <a>Prelude</a> functions. eg.
--   
--   <pre>
--   import qualified Data.ByteString.Char8 as C
--   </pre>
--   
--   The Char8 interface to bytestrings provides an instance of IsString
--   for the ByteString type, enabling you to use string literals, and have
--   them implicitly packed to ByteStrings. Use <tt>{-# LANGUAGE
--   OverloadedStrings #-}</tt> to enable this.
module Data.ByteString.Char8

-- | A space-efficient representation of a <a>Word8</a> vector, supporting
--   many efficient operations.
--   
--   A <a>ByteString</a> contains 8-bit bytes, or by using the operations
--   from <a>Data.ByteString.Char8</a> it can be interpreted 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>
--   
--   For applications with large numbers of string literals, pack can be a
--   bottleneck.
pack :: String -> ByteString

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

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

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

-- | <i>O(n)</i> <a>cons</a> is analogous to (:) for lists, but of
--   different 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
--   to <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
--   non-empty.
head :: ByteString -> Char

-- | <i>O(1)</i> Extract the head and tail of a ByteString, returning
--   Nothing 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,
--   returning 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
--   non-empty.
last :: ByteString -> Char

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

-- | <i>O(1)</i> Return all the elements of a <a>ByteString</a> except the
--   last one. An exception will be thrown in the case of an empty
--   ByteString.
init :: HasCallStack => 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
--   <a>Int</a>.
length :: ByteString -> Int

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

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

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

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

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

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

-- | <a>foldl'</a> 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
--   argument, and thus must be applied to non-empty <a>ByteString</a>s.
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
--   (typically the right-identity of the operator), and a packed string,
--   reduces the packed string using the binary operator, from right to
--   left.
foldr :: (Char -> a -> a) -> a -> ByteString -> a

-- | <a>foldr'</a> 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
--   argument, 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
--   element 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
--   if 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
--   successive reduced values from the left:
--   
--   <pre>
--   scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
--   </pre>
--   
--   Note that
--   
--   <pre>
--   last (scanl f z xs) == foldl f z xs.
--   </pre>
scanl :: (Char -> Char -> Char) -> Char -> ByteString -> ByteString

-- | <a>scanl1</a> is a variant of <a>scanl</a> that has no starting value
--   argument:
--   
--   <pre>
--   scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
--   </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
--   argument.
scanr1 :: (Char -> Char -> Char) -> ByteString -> ByteString

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

-- | The <a>mapAccumR</a> function behaves like a combination of <a>map</a>
--   and <a>foldr</a>; it applies a function to each element of a
--   ByteString, passing an accumulating parameter from right to left, and
--   returning a final value of this accumulator together with the new
--   ByteString.
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
--   <tt>n</tt> with <tt>x</tt> the value of every element. The following
--   holds:
--   
--   <pre>
--   replicate w c = unfoldr w (\u -&gt; Just (u,u)) c
--   </pre>
--   
--   This implementation uses <tt>memset(3)</tt>
replicate :: Int -> Char -> ByteString

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

-- | <i>O(n)</i> Like <a>unfoldr</a>, <a>unfoldrN</a> builds a ByteString
--   from a seed value. However, the length of the result is limited by the
--   first argument to <a>unfoldrN</a>. This function is more efficient
--   than <a>unfoldr</a> when the maximum length of the result is known.
--   
--   The following equation relates <a>unfoldrN</a> and <a>unfoldr</a>:
--   
--   <pre>
--   unfoldrN n f s == take n (unfoldr f s)
--   </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
--   <tt>xs</tt>, returns the prefix of <tt>xs</tt> of length <tt>n</tt>,
--   or <tt>xs</tt> itself if <tt>n &gt; <a>length</a> xs</tt>.
take :: Int -> ByteString -> ByteString

-- | <i>O(1)</i> <tt><a>takeEnd</a> n xs</tt> is equivalent to
--   <tt><a>drop</a> (<a>length</a> xs - n) xs</tt>. Takes <tt>n</tt>
--   elements from end of bytestring.
--   
--   <pre>
--   &gt;&gt;&gt; takeEnd 3 "abcdefg"
--   "efg"
--   
--   &gt;&gt;&gt; takeEnd 0 "abcdefg"
--   ""
--   
--   &gt;&gt;&gt; takeEnd 4 "abc"
--   "abc"
--   </pre>
takeEnd :: Int -> ByteString -> ByteString

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

-- | <i>O(1)</i> <tt><a>dropEnd</a> n xs</tt> is equivalent to
--   <tt><a>take</a> (<a>length</a> xs - n) xs</tt>. Drops <tt>n</tt>
--   elements from end of bytestring.
--   
--   <pre>
--   &gt;&gt;&gt; dropEnd 3 "abcdefg"
--   "abcd"
--   
--   &gt;&gt;&gt; dropEnd 0 "abcdefg"
--   "abcdefg"
--   
--   &gt;&gt;&gt; dropEnd 4 "abc"
--   ""
--   </pre>
dropEnd :: Int -> ByteString -> ByteString

-- | <i>O(1)</i> <a>splitAt</a> <tt>n xs</tt> is equivalent to
--   <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
--   <tt>xs</tt>, returns the longest prefix (possibly empty) of
--   <tt>xs</tt> of elements that satisfy <tt>p</tt>.
takeWhile :: (Char -> Bool) -> ByteString -> ByteString

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

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

-- | <a>dropWhileEnd</a> <tt>p xs</tt> returns the prefix remaining after
--   <a>takeWhileEnd</a> <tt>p xs</tt>.
dropWhileEnd :: (Char -> Bool) -> ByteString -> ByteString

-- | <a>dropSpace</a> efficiently returns the <a>ByteString</a> argument
--   with white space Chars removed from the front. It is more efficient
--   than calling dropWhile for removing whitespace. I.e.
--   
--   <pre>
--   dropWhile isSpace == dropSpace
--   </pre>
dropSpace :: ByteString -> ByteString

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

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

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

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

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

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

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

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

-- | Remove leading and trailing white space from a <a>ByteString</a>.
strip :: ByteString -> ByteString

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

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

-- | <i>O(n)</i> Break a <a>ByteString</a> into pieces separated by the
--   byte argument, consuming the delimiter. I.e.
--   
--   <pre>
--   split '\n' "a\nb\nd\ne" == ["a","b","d","e"]
--   split 'a'  "aXaXaXa"    == ["","X","X","X",""]
--   split 'x'  "x"          == ["",""]
--   split undefined ""      == []  -- and not [""]
--   </pre>
--   
--   and
--   
--   <pre>
--   intercalate [c] . split c == id
--   split == splitWith . (==)
--   </pre>
--   
--   As for all splitting functions in this library, this function does not
--   copy the substrings, it just constructs new <a>ByteString</a>s that
--   are slices of the original.
split :: Char -> ByteString -> [ByteString]

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

-- | <a>lines</a> breaks a ByteString up into a list of ByteStrings at
--   newline Chars (<tt>'\n'</tt>). The resulting strings do not contain
--   newlines.
--   
--   Note that it <b>does not</b> regard CR (<tt>'\r'</tt>) as a newline
--   character.
lines :: ByteString -> [ByteString]

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

-- | <a>unlines</a> joins lines, appending a terminating newline after
--   each.
--   
--   Equivalent to <tt><a>concat</a> . Data.List.concatMap (\x -&gt; [x,
--   <a>singleton</a> '\n'])</tt>.
unlines :: [ByteString] -> ByteString

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

-- | <i>O(n)</i> The <a>isPrefixOf</a> function takes two ByteStrings and
--   returns <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
--   returns <a>True</a> iff the first is a suffix of the second.
--   
--   The following holds:
--   
--   <pre>
--   isSuffixOf x y == reverse x `isPrefixOf` reverse y
--   </pre>
--   
--   However, the real implementation uses memcmp to compare the end of the
--   string only, with no reverse required..
isSuffixOf :: ByteString -> ByteString -> Bool

-- | Check whether one string is a substring of another.
isInfixOf :: ByteString -> ByteString -> Bool

-- | Break a string on a substring, returning a pair of the part of the
--   string prior to the match, and the rest of the string.
--   
--   The following relationships hold:
--   
--   <pre>
--   break (== c) l == breakSubstring (singleton c) l
--   </pre>
--   
--   For example, to tokenise a string, dropping delimiters:
--   
--   <pre>
--   tokenise x y = h : if null t then [] else tokenise x (drop (length x) t)
--       where (h,t) = breakSubstring x y
--   </pre>
--   
--   To skip to the first occurrence of a string:
--   
--   <pre>
--   snd (breakSubstring x y)
--   </pre>
--   
--   To take the parts of a string before a delimiter:
--   
--   <pre>
--   fst (breakSubstring x y)
--   </pre>
--   
--   Note that calling `breakSubstring x` does some preprocessing work, so
--   you should avoid unnecessarily duplicating breakSubstring calls with
--   the same pattern.
breakSubstring :: ByteString -> ByteString -> (ByteString, ByteString)

-- | <i>O(n)</i> <a>elem</a> is the <a>ByteString</a> membership predicate.
--   This 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
--   ByteString, and returns the first element in matching the predicate,
--   or <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,
--   returns a ByteString containing those characters that satisfy the
--   predicate.
filter :: (Char -> Bool) -> ByteString -> ByteString

partition :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)

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

-- | <i>O(1)</i> <a>ByteString</a> index, starting from 0, that returns
--   <a>Just</a> if:
--   
--   <pre>
--   0 &lt;= n &lt; length bs
--   </pre>
indexMaybe :: ByteString -> Int -> Maybe Char

-- | <i>O(1)</i> <a>ByteString</a> index, starting from 0, that returns
--   <a>Just</a> if:
--   
--   <pre>
--   0 &lt;= n &lt; length bs
--   </pre>
(!?) :: ByteString -> Int -> Maybe Char

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

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

-- | <i>O(n)</i> The <a>elemIndexEnd</a> function returns the last index of
--   the element in the given <a>ByteString</a> which is equal to the query
--   element, or <a>Nothing</a> if there is no such element. The following
--   holds:
--   
--   <pre>
--   elemIndexEnd c xs = case elemIndex c (reverse xs) of
--     Nothing -&gt; Nothing
--     Just i  -&gt; Just (length xs - 1 - i)
--   </pre>
elemIndexEnd :: Char -> ByteString -> Maybe Int

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

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

-- | <i>O(n)</i> The <a>findIndexEnd</a> function takes a predicate and a
--   <a>ByteString</a> and returns the index of the last element in the
--   ByteString satisfying the predicate.
findIndexEnd :: (Char -> Bool) -> ByteString -> Maybe Int

-- | count returns the number of times its argument appears in the
--   ByteString
--   
--   <pre>
--   count = length . elemIndices
--   </pre>
--   
--   Also
--   
--   <pre>
--   count '\n' == length . lines
--   </pre>
--   
--   But 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
--   corresponding pairs of Chars. If one input ByteString is short, excess
--   elements of the longer ByteString are discarded. This is equivalent to
--   a pair of <a>unpack</a> operations, and so space usage may be large
--   for multi-megabyte ByteStrings
zip :: ByteString -> ByteString -> [(Char, Char)]

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

-- | A specialised version of <a>zipWith</a> for the common case of a
--   simultaneous map over two ByteStrings, to build a 3rd.
packZipWith :: (Char -> Char -> Char) -> ByteString -> ByteString -> ByteString

-- | <a>unzip</a> transforms a list of pairs of Chars into a pair of
--   ByteStrings. 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
--   no integer at the beginning of the string, it returns Nothing,
--   otherwise it just returns the int read, and the rest of the string.
--   
--   Note: This function will overflow the Int for large integers.
readInt :: ByteString -> Maybe (Int, ByteString)

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

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

-- | <i>O(n).</i> Construct a new <tt>ByteString</tt> from a
--   <tt>CString</tt>. The resulting <tt>ByteString</tt> is an immutable
--   copy of the original <tt>CString</tt>, and is managed on the Haskell
--   heap. 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
--   <tt>CStringLen</tt>. The resulting <tt>ByteString</tt> is an immutable
--   copy of the original <tt>CStringLen</tt>. The <tt>ByteString</tt> is a
--   normal 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
--   requiring a null-terminated <tt>CString</tt>. The <tt>CString</tt> is
--   a copy and will be freed automatically; it must not be stored or used
--   after the subcomputation finishes.
useAsCString :: ByteString -> (CString -> IO a) -> IO a

-- | <i>O(n) construction</i> Use a <tt>ByteString</tt> with a function
--   requiring a <tt>CStringLen</tt>. As for <tt>useAsCString</tt> this
--   function makes a copy of the original <tt>ByteString</tt>. It must not
--   be 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
--   <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;
--   ByteString</tt> as its argument. The entire input from the standard
--   input device is passed to this function as its argument, and the
--   resulting string is output on the standard output device.
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>.
--   
--   This function reads chunks at a time, increasing the chunk size on
--   each read. The final string is then reallocated to the appropriate
--   size. For files &gt; half of available memory, this may lead to memory
--   exhaustion. Consider using <a>readFile</a> in this case.
--   
--   The Handle is closed once the contents have been read, or if an
--   exception is thrown.
hGetContents :: Handle -> IO ByteString

-- | Read a <a>ByteString</a> directly from the specified <a>Handle</a>.
--   This is far more efficient than reading the characters into a
--   <a>String</a> and then using <a>pack</a>. First argument is the Handle
--   to read from, and the second is the number of bytes to read. It
--   returns the bytes read, up to n, or <a>empty</a> if EOF has been
--   reached.
--   
--   <a>hGet</a> is implemented in terms of <a>hGetBuf</a>.
--   
--   If the handle is a pipe or socket, and the writing end is closed,
--   <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
--   returned if there are not enough bytes immediately available to
--   satisfy the whole request. <a>hGetSome</a> only blocks if there is no
--   data 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
--   block waiting for data to become available, instead it returns only
--   whatever data is available. If there is no data available to be read,
--   <a>hGetNonBlocking</a> returns <a>empty</a>.
--   
--   Note: on Windows and with Haskell implementation other than GHC, this
--   function does not work correctly; it behaves identically to
--   <a>hGet</a>.
hGetNonBlocking :: 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
--   returns any tail that did not get written. This tail may be
--   <a>empty</a> in the case that the whole string was written, or the
--   whole original string if nothing was written. Partial writes are also
--   possible.
--   
--   Note: on Windows and with Haskell implementation other than GHC, this
--   function does not work correctly; it behaves identically to
--   <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 ()


-- | <ul>
--   <li>Warning:* this module is internal. If you find that you need it
--   then please contact the maintainers and explain what you are trying to
--   do and discuss what you would need in the public API. It is important
--   that you do this as the module may not be exposed at all in future
--   releases.</li>
--   </ul>
--   
--   Core types and functions for the <a>Builder</a> monoid and its
--   generalization, the <a>Put</a> monad.
--   
--   The design of the <a>Builder</a> monoid is optimized such that
--   
--   <ol>
--   <li>buffers of arbitrary size can be filled as efficiently as possible
--   and</li>
--   <li>sequencing of <a>Builder</a>s is as cheap as possible.</li>
--   </ol>
--   
--   We achieve (1) by completely handing over control over writing to the
--   buffer to the <a>BuildStep</a> implementing the <a>Builder</a>. This
--   <a>BuildStep</a> is just told the start and the end of the buffer
--   (represented as a <a>BufferRange</a>). Then, the <a>BuildStep</a> can
--   write to as big a prefix of this <a>BufferRange</a> in any way it
--   desires. If the <a>BuildStep</a> is done, the <a>BufferRange</a> is
--   full, or a long sequence of bytes should be inserted directly, then
--   the <a>BuildStep</a> signals this to its caller using a
--   <a>BuildSignal</a>.
--   
--   We achieve (2) by requiring that every <a>Builder</a> is implemented
--   by a <a>BuildStep</a> that takes a continuation <a>BuildStep</a>,
--   which it calls with the updated <a>BufferRange</a> after it is done.
--   Therefore, only two pointers have to be passed in a function call to
--   implement concatenation of <a>Builder</a>s. Moreover, many
--   <a>Builder</a>s are completely inlined, which enables the compiler to
--   sequence them without a function call and with no boxing at all.
--   
--   This design gives the implementation of a <a>Builder</a> full access
--   to the <a>IO</a> monad. Therefore, utmost care has to be taken to not
--   overwrite anything outside the given <a>BufferRange</a>s. Moreover,
--   further care has to be taken to ensure that <a>Builder</a>s and
--   <a>Put</a>s are referentially transparent. See the comments of the
--   <a>builder</a> and <a>put</a> functions for further information. Note
--   that there are <i>no safety belts</i> at all, when implementing a
--   <a>Builder</a> using an <a>IO</a> action: you are writing code that
--   might enable the next buffer-overflow attack on a Haskell server!
module Data.ByteString.Builder.Internal

-- | A <a>Buffer</a> together with the <a>BufferRange</a> of free bytes.
--   The filled space starts at offset 0 and ends at the first free byte.
data Buffer
Buffer :: {-# UNPACK #-} !ForeignPtr Word8 -> {-# UNPACK #-} !BufferRange -> Buffer

-- | A range of bytes in a buffer represented by the pointer to the first
--   byte of the range and the pointer to the first byte <i>after</i> the
--   range.
data BufferRange
BufferRange :: {-# UNPACK #-} !Ptr Word8 -> {-# UNPACK #-} !Ptr Word8 -> BufferRange

-- | Allocate a new buffer of the given size.
newBuffer :: Int -> IO Buffer

-- | Combined size of the filled and free space in the buffer.
bufferSize :: Buffer -> Int

-- | Convert the filled part of a <a>Buffer</a> to a strict
--   <a>ByteString</a>.
byteStringFromBuffer :: Buffer -> ByteString

-- | A stream of chunks that are constructed in the <a>IO</a> monad.
--   
--   This datatype serves as the common interface for the buffer-by-buffer
--   execution of a <a>BuildStep</a> by <a>buildStepToCIOS</a>. Typical
--   users of this interface are <a>ciosToLazyByteString</a> or
--   iteratee-style libraries like <tt>enumerator</tt>.
data ChunkIOStream a

-- | The partially filled last buffer together with the result.
Finished :: Buffer -> a -> ChunkIOStream a

-- | Yield a <i>non-empty</i> strict <a>ByteString</a>.
Yield1 :: ByteString -> IO (ChunkIOStream a) -> ChunkIOStream a

-- | Convert a <a>BuildStep</a> to a <a>ChunkIOStream</a> stream by
--   executing it on <a>Buffer</a>s allocated according to the given
--   <a>AllocationStrategy</a>.
buildStepToCIOS :: AllocationStrategy -> BuildStep a -> IO (ChunkIOStream a)

-- | Convert a <tt><a>ChunkIOStream</a> ()</tt> to a lazy <a>ByteString</a>
--   using <a>unsafeDupablePerformIO</a>.
ciosUnitToLazyByteString :: AllocationStrategy -> ByteString -> ChunkIOStream () -> ByteString

-- | Convert a <a>ChunkIOStream</a> to a lazy tuple of the result and the
--   written <a>ByteString</a> using <a>unsafeDupablePerformIO</a>.
ciosToLazyByteString :: AllocationStrategy -> (a -> (b, ByteString)) -> ChunkIOStream a -> (b, ByteString)

-- | <a>BuildSignal</a>s abstract signals to the caller of a
--   <a>BuildStep</a>. There are three signals: <a>done</a>,
--   <a>bufferFull</a>, or 'insertChunks signals
data BuildSignal a

-- | <a>BuildStep</a>s may be called *multiple times* and they must not
--   rise an async. exception.
type BuildStep a = BufferRange -> IO (BuildSignal a)

-- | The final build step that returns the <a>done</a> signal.
finalBuildStep :: BuildStep ()

-- | Signal that the current <a>BuildStep</a> is done and has computed a
--   value.
done :: Ptr Word8 -> a -> BuildSignal a

-- | Signal that the current buffer is full.
bufferFull :: Int -> Ptr Word8 -> BuildStep a -> BuildSignal a

-- | Signal that a <a>ByteString</a> chunk should be inserted directly.
insertChunk :: Ptr Word8 -> ByteString -> BuildStep a -> BuildSignal a

-- | Fill a <a>BufferRange</a> using a <a>BuildStep</a>.
fillWithBuildStep :: BuildStep a -> (Ptr Word8 -> a -> IO b) -> (Ptr Word8 -> Int -> BuildStep a -> IO b) -> (Ptr Word8 -> ByteString -> BuildStep a -> IO b) -> BufferRange -> IO b

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

-- | Construct a <a>Builder</a>. In contrast to <a>BuildStep</a>s,
--   <a>Builder</a>s are referentially transparent.
builder :: (forall r. BuildStep r -> BuildStep r) -> Builder

-- | Run a <a>Builder</a> with the <a>finalBuildStep</a>.
runBuilder :: Builder -> BuildStep ()

-- | Run a <a>Builder</a>.
runBuilderWith :: Builder -> BuildStep a -> BuildStep a

-- | The <a>Builder</a> denoting a zero-length sequence of bytes. This
--   function is only exported for use in rewriting rules. Use
--   <a>mempty</a> otherwise.
empty :: Builder

-- | Concatenate two <a>Builder</a>s. This function is only exported for
--   use in rewriting rules. Use <a>mappend</a> otherwise.
append :: Builder -> Builder -> Builder

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

-- | <tt><a>ensureFree</a> n</tt> ensures that there are at least
--   <tt>n</tt> free bytes for the following <a>Builder</a>.
ensureFree :: Int -> Builder

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

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

-- | Construct a <a>Builder</a> that copies the strict <a>ByteString</a>s,
--   if it is smaller than the treshold, and inserts it directly otherwise.
--   
--   For example, <tt>byteStringThreshold 1024</tt> copies strict
--   <a>ByteString</a>s whose size is less or equal to 1kb, and inserts
--   them directly otherwise. This implies that the average chunk-size of
--   the generated lazy <a>ByteString</a> may be as low as 513 bytes, as
--   there could always be just a single byte between the directly inserted
--   1025 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
--   <a>ByteString</a> directly.
lazyByteStringInsert :: ByteString -> Builder

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

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

-- | The maximal size of a <a>ByteString</a> that is copied. <tt>2 *
--   <a>smallChunkSize</a></tt> to guarantee that on average a chunk is of
--   <a>smallChunkSize</a>.
maximalCopySize :: Int

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

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

-- | <i>Heavy inlining.</i> Execute a <a>Builder</a> with custom execution
--   parameters.
--   
--   This function is inlined despite its heavy code-size to allow fusing
--   with the allocation strategy. For example, the default <a>Builder</a>
--   execution function <a>toLazyByteString</a> is defined as follows.
--   
--   <pre>
--   {-# NOINLINE toLazyByteString #-}
--   toLazyByteString =
--     toLazyByteStringWith (<a>safeStrategy</a> <a>smallChunkSize</a> <a>defaultChunkSize</a>) L.empty
--   </pre>
--   
--   where <tt>L.empty</tt> is the zero-length lazy <a>ByteString</a>.
--   
--   In most cases, the parameters used by <a>toLazyByteString</a> give
--   good performance. A sub-performing case of <a>toLazyByteString</a> is
--   executing short (&lt;128 bytes) <a>Builder</a>s. In this case, the
--   allocation overhead for the first 4kb buffer and the trimming cost
--   dominate the cost of executing the <a>Builder</a>. You can avoid this
--   problem using
--   
--   <pre>
--   toLazyByteStringWith (safeStrategy 128 smallChunkSize) L.empty
--   </pre>
--   
--   This reduces the allocation and trimming overhead, as all generated
--   <a>ByteString</a>s fit into the first buffer and there is no trimming
--   required, 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
--   are likely to survive one garbage collection. This strategy trims
--   buffers that are filled less than half in order to avoid spilling too
--   much memory.
safeStrategy :: Int -> Int -> AllocationStrategy

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

-- | Create a custom allocation strategy. See the code for
--   <a>safeStrategy</a> and <a>untrimmedStrategy</a> for examples.
customStrategy :: (Maybe (Buffer, Int) -> IO Buffer) -> Int -> (Int -> Int -> Bool) -> AllocationStrategy

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

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

-- | The memory management overhead. Currently this is tuned for GHC only.
chunkOverhead :: Int

-- | A <a>Put</a> action denotes a computation of a value that writes a
--   stream of bytes as a side-effect. <a>Put</a>s are strict in their
--   side-effect; i.e., the stream of bytes will always be written before
--   the computed value is returned.
--   
--   <a>Put</a>s are a generalization of <a>Builder</a>s. The typical use
--   case is the implementation of an encoding that might fail (e.g., an
--   interface to the <a>zlib</a> compression library or the conversion
--   from Base64 encoded data to 8-bit data). For a <a>Builder</a>, the
--   only way to handle and report such a failure is ignore it or call
--   <a>error</a>. In contrast, <a>Put</a> actions are expressive enough to
--   allow reporting and handling such a failure in a pure fashion.
--   
--   <tt><a>Put</a> ()</tt> actions are isomorphic to <a>Builder</a>s. The
--   functions <a>putBuilder</a> and <a>fromPut</a> convert between these
--   two types. Where possible, you should use <a>Builder</a>s, as
--   sequencing them is slightly cheaper than sequencing <a>Put</a>s
--   because they do not carry around a computed value.
data Put a

-- | Construct a <a>Put</a> action. In contrast to <a>BuildStep</a>s,
--   <a>Put</a>s are referentially transparent in the sense that sequencing
--   the same <a>Put</a> multiple times yields every time the same value
--   with the same side-effect.
put :: (forall r. (a -> BuildStep r) -> BuildStep r) -> Put a

-- | Run a <a>Put</a>.
runPut :: Put a -> BuildStep a

-- | Execute a <a>Put</a> and return the computed result and the bytes
--   written during the computation as a lazy <a>ByteString</a>.
--   
--   This function is strict in the computed result and lazy in the writing
--   of the bytes. For example, given
--   
--   <pre>
--   infinitePut = sequence_ (repeat (putBuilder (word8 1))) &gt;&gt; return 0
--    
--   </pre>
--   
--   evaluating the expression
--   
--   <pre>
--   fst $ putToLazyByteString infinitePut
--    
--   </pre>
--   
--   does not terminate, while evaluating the expression
--   
--   <pre>
--   L.head $ snd $ putToLazyByteString infinitePut
--    
--   </pre>
--   
--   does terminate and yields the value <tt>1 :: Word8</tt>.
--   
--   An illustrative example for these strictness properties is the
--   implementation of Base64 decoding
--   (<a>http://en.wikipedia.org/wiki/Base64</a>).
--   
--   <pre>
--   type DecodingState = ...
--   
--   decodeBase64 :: <a>ByteString</a> -&gt; DecodingState -&gt; <a>Put</a> (Maybe DecodingState)
--   decodeBase64 = ...
--    
--   </pre>
--   
--   The above function takes a strict <a>ByteString</a> supposed to
--   represent Base64 encoded data and the current decoding state. It
--   writes the decoded bytes as the side-effect of the <a>Put</a> and
--   returns the new decoding state, if the decoding of all data in the
--   <a>ByteString</a> was successful. The checking if the strict
--   <a>ByteString</a> represents Base64 encoded data and the actual
--   decoding are fused. This makes the common case, where all data
--   represents Base64 encoded data, more efficient. It also implies that
--   all data must be decoded before the final decoding state can be
--   returned. <a>Put</a>s are intended for implementing such fused
--   checking and decoding/encoding, which is reflected in their strictness
--   properties.
putToLazyByteString :: Put a -> (a, ByteString)

-- | Execute a <a>Put</a> with a buffer-allocation strategy and a
--   continuation. For example, <a>putToLazyByteString</a> is implemented
--   as follows.
--   
--   <pre>
--   putToLazyByteString = <a>putToLazyByteStringWith</a>
--       (<a>safeStrategy</a> <a>smallChunkSize</a> <a>defaultChunkSize</a>) (x -&gt; (x, L.empty))
--    
--   </pre>
putToLazyByteStringWith :: AllocationStrategy -> (a -> (b, ByteString)) -> Put a -> (b, ByteString)

-- | Run a <a>Put</a> action redirecting the produced output to a
--   <a>Handle</a>.
--   
--   The output is buffered using the <a>Handle</a>s associated buffer. If
--   this buffer is too small to execute one step of the <a>Put</a> action,
--   then it is replaced with a large enough buffer.
hPut :: forall a. Handle -> Put a -> IO a

-- | Run a <a>Builder</a> as a side-effect of a <tt><a>Put</a> ()</tt>
--   action.
putBuilder :: Builder -> Put ()

-- | Convert a <tt><a>Put</a> ()</tt> action to a <a>Builder</a>.
fromPut :: Put () -> Builder
instance GHC.Base.Functor Data.ByteString.Builder.Internal.Put
instance GHC.Base.Applicative Data.ByteString.Builder.Internal.Put
instance GHC.Base.Monad Data.ByteString.Builder.Internal.Put
instance GHC.Base.Semigroup Data.ByteString.Builder.Internal.Builder
instance GHC.Base.Monoid Data.ByteString.Builder.Internal.Builder


-- | This module provides <a>Builder</a> <i>primitives</i>, which are lower
--   level building blocks for constructing <a>Builder</a>s. You don't need
--   to go down to this level but it can be slightly faster.
--   
--   Morally, builder primitives are like functions <tt>a -&gt;
--   Builder</tt>, that is they take a value and encode it as a sequence of
--   bytes, represented as a <a>Builder</a>. Of course their implementation
--   is a bit more specialised.
--   
--   Builder primitives come in two forms: fixed-size and bounded-size.
--   
--   <ul>
--   <li><i>Fixed(-size) primitives</i> are builder primitives that always
--   result in a sequence of bytes of a fixed length. That is, the length
--   is independent of the value that is encoded. An example of a fixed
--   size primitive is the big-endian encoding of a <a>Word64</a>, which
--   always results in exactly 8 bytes.</li>
--   <li><i>Bounded(-size) primitives</i> are builder primitives that
--   always result in a sequence of bytes that is no larger than a
--   predetermined bound. That is, the bound is independent of the value
--   that is encoded but the actual length will depend on the value. An
--   example for a bounded primitive is the UTF-8 encoding of a
--   <a>Char</a>, which can be 1,2,3 or 4 bytes long, so the bound is 4
--   bytes.</li>
--   </ul>
--   
--   Note that fixed primitives can be considered as a special case of
--   bounded primitives, and we can lift from fixed to bounded.
--   
--   Because bounded primitives are the more general case, in this
--   documentation we only refer to fixed size primitives where it matters
--   that the resulting sequence of bytes is of a fixed length. Otherwise,
--   we just refer to bounded size primitives.
--   
--   The purpose of using builder primitives is to improve the performance
--   of <a>Builder</a>s. These improvements stem from making the two most
--   common steps performed by a <a>Builder</a> more efficient. We explain
--   these two steps in turn.
--   
--   The first most common step is the concatenation of two
--   <a>Builder</a>s. Internally, concatenation corresponds to function
--   composition. (Note that <a>Builder</a>s can be seen as
--   difference-lists of buffer-filling functions; cf.
--   <a>http://hackage.haskell.org/cgi-bin/hackage-scripts/package/dlist</a>.
--   ) Function composition is a fast <i>O(1)</i> operation. However, we
--   can use bounded primitives to remove some of these function
--   compositions altogether, which is more efficient.
--   
--   The second most common step performed by a <a>Builder</a> is to fill a
--   buffer using a bounded primitives, which works as follows. The
--   <a>Builder</a> checks whether there is enough space left to execute
--   the bounded primitive. If there is, then the <a>Builder</a> executes
--   the bounded primitive and calls the next <a>Builder</a> with the
--   updated buffer. Otherwise, the <a>Builder</a> signals its driver that
--   it requires a new buffer. This buffer must be at least as large as the
--   bound of the primitive. We can use bounded primitives to reduce the
--   number of buffer-free checks by fusing the buffer-free checks of
--   consecutive <a>Builder</a>s. We can also use bounded primitives to
--   simplify the control flow for signalling that a buffer is full by
--   ensuring that we check first that there is enough space left and only
--   then decide on how to encode a given value.
--   
--   Let us illustrate these improvements on the CSV-table rendering
--   example from <a>Data.ByteString.Builder</a>. Its "hot code" is the
--   rendering of a table's cells, which we implement as follows using only
--   the functions from the <a>Builder</a> API.
--   
--   <pre>
--   import <a>Data.ByteString.Builder</a> as B
--   
--   renderCell :: Cell -&gt; Builder
--   renderCell (StringC cs) = renderString cs
--   renderCell (IntC i)     = B.intDec i
--   
--   renderString :: String -&gt; Builder
--   renderString cs = B.charUtf8 '"' &lt;&gt; foldMap escape cs &lt;&gt; B.charUtf8 '"'
--     where
--       escape '\\' = B.charUtf8 '\\' &lt;&gt; B.charUtf8 '\\'
--       escape '\"' = B.charUtf8 '\\' &lt;&gt; B.charUtf8 '\"'
--       escape c    = B.charUtf8 c
--   </pre>
--   
--   Efficient encoding of <a>Int</a>s as decimal numbers is performed by
--   <tt>intDec</tt>. Optimization potential exists for the escaping of
--   <a>String</a>s. The above implementation has two optimization
--   opportunities. First, the buffer-free checks of the <a>Builder</a>s
--   for escaping double quotes and backslashes can be fused. Second, the
--   concatenations performed by <a>foldMap</a> can be eliminated. The
--   following implementation exploits these optimizations.
--   
--   <pre>
--   import qualified Data.ByteString.Builder.Prim  as P
--   import           Data.ByteString.Builder.Prim
--                    ( <a>condB</a>, <a>liftFixedToBounded</a>, (<a>&gt;*&lt;</a>), (<a>&gt;$&lt;</a>) )
--   
--   renderString :: String -&gt; Builder
--   renderString cs =
--       B.charUtf8 '"' &lt;&gt; <a>primMapListBounded</a> escape cs &lt;&gt; B.charUtf8 '"'
--     where
--       escape :: <a>BoundedPrim</a> Char
--       escape =
--         <a>condB</a> (== '\\') (fixed2 ('\\', '\\')) $
--         <a>condB</a> (== '\"') (fixed2 ('\\', '\"')) $
--         <a>charUtf8</a>
--        
--       {-# INLINE fixed2 #-}
--       fixed2 x = <a>liftFixedToBounded</a> $ const x <a>&gt;$&lt;</a> <a>char7</a> <a>&gt;*&lt;</a> <a>char7</a>
--   </pre>
--   
--   The code should be mostly self-explanatory. The slightly awkward
--   syntax is because the combinators are written such that the size-bound
--   of the resulting <a>BoundedPrim</a> can be computed at compile time.
--   We also explicitly inline the <tt>fixed2</tt> primitive, which encodes
--   a fixed tuple of characters, to ensure that the bound computation
--   happens at compile time. When encoding the following list of
--   <a>String</a>s, the optimized implementation of <tt>renderString</tt>
--   is two times faster.
--   
--   <pre>
--   maxiStrings :: [String]
--   maxiStrings = take 1000 $ cycle ["hello", "\"1\"", "λ-wörld"]
--   </pre>
--   
--   Most of the performance gain stems from using
--   <a>primMapListBounded</a>, which encodes a list of values from
--   left-to-right with a <a>BoundedPrim</a>. It exploits the
--   <a>Builder</a> internals to avoid unnecessary function compositions
--   (i.e., concatenations). In the future, we might expect the compiler to
--   perform the optimizations implemented in <a>primMapListBounded</a>.
--   However, it seems that the code is currently to complicated for the
--   compiler to see through. Therefore, we provide the <a>BoundedPrim</a>
--   escape hatch, which allows data structures to provide very efficient
--   encoding traversals, like <a>primMapListBounded</a> for lists.
--   
--   Note that <a>BoundedPrim</a>s are a bit verbose, but quite versatile.
--   Here is an example of a <a>BoundedPrim</a> for combined HTML escaping
--   and UTF-8 encoding. It exploits that the escaped character with the
--   maximal Unicode codepoint is '&gt;'.
--   
--   <pre>
--   {-# INLINE charUtf8HtmlEscaped #-}
--   charUtf8HtmlEscaped :: <a>BoundedPrim</a> Char
--   charUtf8HtmlEscaped =
--       <a>condB</a> (&gt;  '&gt;' ) <a>charUtf8</a> $
--       <a>condB</a> (== '&lt;' ) (fixed4 ('&amp;',('l',('t',';')))) $        -- &amp;lt;
--       <a>condB</a> (== '&gt;' ) (fixed4 ('&amp;',('g',('t',';')))) $        -- &amp;gt;
--       <a>condB</a> (== '&amp;' ) (fixed5 ('&amp;',('a',('m',('p',';'))))) $  -- &amp;amp;
--       <a>condB</a> (== '"' ) (fixed5 ('&amp;',('#',('3',('4',';'))))) $  -- &amp;#34;
--       <a>condB</a> (== '\'') (fixed5 ('&amp;',('#',('3',('9',';'))))) $  -- &amp;#39;
--       (<a>liftFixedToBounded</a> <a>char7</a>)         -- fallback for <a>Char</a>s smaller than '&gt;'
--     where
--       {-# INLINE fixed4 #-}
--       fixed4 x = <a>liftFixedToBounded</a> $ const x <a>&gt;$&lt;</a>
--         char7 <a>&gt;*&lt;</a> char7 <a>&gt;*&lt;</a> char7 <a>&gt;*&lt;</a> char7
--        
--       {-# INLINE fixed5 #-}
--       fixed5 x = <a>liftFixedToBounded</a> $ const x <a>&gt;$&lt;</a>
--         char7 <a>&gt;*&lt;</a> char7 <a>&gt;*&lt;</a> char7 <a>&gt;*&lt;</a> char7 <a>&gt;*&lt;</a> char7
--   </pre>
--   
--   This module currently does not expose functions that require the
--   special properties of fixed-size primitives. They are useful for
--   prefixing <a>Builder</a>s with their size or for implementing chunked
--   encodings. We will expose the corresponding functions in future
--   releases of this library.
module Data.ByteString.Builder.Prim

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

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

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

-- | A fmap-like operator for builder primitives, both bounded and fixed
--   size.
--   
--   Builder primitives are contravariant so it's like the normal fmap, but
--   backwards (look at the type). (If it helps to remember, the operator
--   symbol is like (<a>$</a>) but backwards.)
--   
--   We can use it for example to prepend and/or append fixed values to an
--   primitive.
--   
--   <pre>
--    import Data.ByteString.Builder.Prim as P
--   showEncoding ((\x -&gt; ('\'', (x, '\''))) &gt;$&lt; fixed3) 'x' = "'x'"
--     where
--       fixed3 = P.char7 &gt;*&lt; P.char7 &gt;*&lt; P.char7
--   </pre>
--   
--   Note that the rather verbose syntax for composition stems from the
--   requirement to be able to compute the size / size bound at compile
--   time.
(>$<) :: Contravariant f => (b -> a) -> f a -> f b
infixl 4 >$<

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

-- | Conditionally select a <a>BoundedPrim</a>. For example, we can
--   implement the ASCII primitive that drops characters with Unicode
--   codepoints above 127 as follows.
--   
--   <pre>
--   charASCIIDrop = <a>condB</a> (&lt; '\128') (<a>liftFixedToBounded</a> <a>char7</a>) <a>emptyB</a>
--    
--   </pre>
condB :: (a -> Bool) -> BoundedPrim a -> BoundedPrim a -> BoundedPrim a

-- | Create a <a>Builder</a> that encodes values with the given
--   <a>BoundedPrim</a>.
--   
--   We rewrite consecutive uses of <a>primBounded</a> such that the
--   bound-checks are fused. For example,
--   
--   <pre>
--   primBounded (word32 c1) `mappend` primBounded (word32 c2)
--   </pre>
--   
--   is rewritten such that the resulting <a>Builder</a> checks only once,
--   if ther are at 8 free bytes, instead of checking twice, if there are 4
--   free bytes. This optimization is not observationally equivalent in a
--   strict sense, as it influences the boundaries of the generated chunks.
--   However, for a user of this library it is observationally equivalent,
--   as chunk boundaries of a lazy <a>ByteString</a> can only be observed
--   through the internal interface. Moreover, we expect that all
--   primitives write much fewer than 4kb (the default short buffer size).
--   Hence, it is safe to ignore the additional memory spilled due to the
--   more aggressive buffer wrapping introduced by this optimization.
primBounded :: BoundedPrim a -> a -> Builder

-- | Create a <a>Builder</a> that encodes a list of values consecutively
--   using a <a>BoundedPrim</a> for each element. This function is more
--   efficient than
--   
--   <pre>
--   mconcat . map (primBounded w)
--   </pre>
--   
--   or
--   
--   <pre>
--   foldMap (primBounded w)
--   </pre>
--   
--   because 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
--   value 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
--   <a>ByteString</a> using a <a>BoundedPrim</a>. For example, we can
--   write a <a>Builder</a> that filters a strict <a>ByteString</a> as
--   follows.
--   
--   <pre>
--   import qualified Data.ByteString.Builder.Prim as P
--   </pre>
--   
--   <pre>
--   filterBS p = P.condB p (P.liftFixedToBounded P.word8) P.emptyB
--   </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
--   pre-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
--   <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>
--   from left-to-right with a <a>FixedPrim</a>. This function is quite
--   versatile. For example, we can use it to construct a <a>Builder</a>
--   that maps every byte before copying it to the buffer to be filled.
--   
--   <pre>
--   mapToBuilder :: (Word8 -&gt; Word8) -&gt; S.ByteString -&gt; Builder
--   mapToBuilder f = primMapByteStringFixed (contramapF f word8)
--   </pre>
--   
--   We can also use it to hex-encode a strict <a>ByteString</a> as shown
--   by the <a>byteStringHex</a> example above.
primMapByteStringFixed :: FixedPrim Word8 -> ByteString -> Builder

-- | <i>Heavy inlining.</i> Encode all bytes of a lazy <a>ByteString</a>
--   from 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
--   in host order, host endian form, for the machine you are on. On a 64
--   bit machine the <a>Int</a> is an 8 byte value, on a 32 bit machine, 4
--   bytes. Values encoded this way are not portable to different endian or
--   integer 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
--   encoded in host order, host endian form, for the machine you are on.
--   On a 64 bit machine the <a>Word</a> is an 8 byte value, on a 32 bit
--   machine, 4 bytes. Values encoded this way are not portable to
--   different 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
--   written this way are not portable to different endian machines,
--   without 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

-- | A null-terminated ASCII encoded <a>CString</a>. Null characters are
--   not representable.
cstring :: Addr# -> Builder

-- | A null-terminated UTF-8 encoded <a>CString</a>. Null characters can be
--   encoded as <tt>0xc0 0x80</tt>.
cstringUtf8 :: Addr# -> Builder


-- | Floating point formatting for <tt>Bytestring.Builder</tt>
--   
--   This module primarily exposes <a>floatDec</a> and <a>doubleDec</a>
--   which do the equivalent of converting through <tt><a>string7</a> .
--   <a>show</a></tt>.
--   
--   It also exposes <a>formatFloat</a> and <a>formatDouble</a> with a
--   similar API as <a>formatRealFloat</a>.
--   
--   NB: The float-to-string conversions exposed by this module match
--   <a>show</a>'s output (specifically with respect to default rounding
--   and length). In particular, there are boundary cases where the closest
--   and 'shortest' string representations are not used. Mentions of
--   'shortest' in the docs below are with this caveat.
--   
--   For example, for fidelity, we match <a>show</a> on the output below.
--   
--   <pre>
--   &gt;&gt;&gt; show (1.0e23 :: Float)
--   "1.0e23"
--   
--   &gt;&gt;&gt; show (1.0e23 :: Double)
--   "9.999999999999999e22"
--   
--   &gt;&gt;&gt; floatDec 1.0e23
--   "1.0e23"
--   
--   &gt;&gt;&gt; doubleDec 1.0e23
--   "9.999999999999999e22"
--   </pre>
--   
--   Simplifying, we can build a shorter, lossless representation by just
--   using <tt>"1.0e23"</tt> since the floating point values that are 1 ULP
--   away are
--   
--   <pre>
--   &gt;&gt;&gt; showHex (castDoubleToWord64 1.0e23) []
--   "44b52d02c7e14af6"
--   
--   &gt;&gt;&gt; castWord64ToDouble 0x44b52d02c7e14af5
--   9.999999999999997e22
--   
--   &gt;&gt;&gt; castWord64ToDouble 0x44b52d02c7e14af6
--   9.999999999999999e22
--   
--   &gt;&gt;&gt; castWord64ToDouble 0x44b52d02c7e14af7
--   1.0000000000000001e23
--   </pre>
--   
--   In particular, we could use the exact boundary if it is the shortest
--   representation and the original floating number is even. To experiment
--   with the shorter rounding, refer to <a>acceptBounds</a>. This will
--   give us
--   
--   <pre>
--   &gt;&gt;&gt; floatDec 1.0e23
--   "1.0e23"
--   
--   &gt;&gt;&gt; doubleDec 1.0e23
--   "1.0e23"
--   </pre>
--   
--   For more details, please refer to the <a>Ryu paper</a>.
module Data.ByteString.Builder.RealFloat

-- | Returns a rendered Float. Matches <a>show</a> in displaying in
--   standard or scientific notation
--   
--   <pre>
--   floatDec = <a>formatFloat</a> <a>generic</a>
--   </pre>
floatDec :: Float -> Builder

-- | Returns a rendered Double. Matches <a>show</a> in displaying in
--   standard or scientific notation
--   
--   <pre>
--   doubleDec = <a>formatDouble</a> <a>generic</a>
--   </pre>
doubleDec :: Double -> Builder

-- | Returns a rendered Float. Returns the 'shortest' representation in
--   scientific notation and takes an optional precision argument in
--   standard notation. Also see <a>floatDec</a>.
--   
--   With standard notation, the precision argument is used to truncate (or
--   extend with 0s) the 'shortest' rendered Float. The 'default precision'
--   does no such modifications and will return as many decimal places as
--   the representation demands.
--   
--   e.g
--   
--   <pre>
--   &gt;&gt;&gt; formatFloat (standard 1) 1.2345e-2
--   "0.0"
--   
--   &gt;&gt;&gt; formatFloat (standard 10) 1.2345e-2
--   "0.0123450000"
--   
--   &gt;&gt;&gt; formatFloat standardDefaultPrecision 1.2345e-2
--   "0.01234"
--   
--   &gt;&gt;&gt; formatFloat scientific 12.345
--   "1.2345e1"
--   
--   &gt;&gt;&gt; formatFloat generic 12.345
--   "12.345"
--   </pre>
formatFloat :: FloatFormat -> Float -> Builder

-- | Returns a rendered Double. Returns the 'shortest' representation in
--   scientific notation and takes an optional precision argument in
--   standard notation. Also see <a>doubleDec</a>.
--   
--   With standard notation, the precision argument is used to truncate (or
--   extend with 0s) the 'shortest' rendered Float. The 'default precision'
--   does no such modifications and will return as many decimal places as
--   the representation demands.
--   
--   e.g
--   
--   <pre>
--   &gt;&gt;&gt; formatDouble (standard 1) 1.2345e-2
--   "0.0"
--   
--   &gt;&gt;&gt; formatDouble (standard 10) 1.2345e-2
--   "0.0123450000"
--   
--   &gt;&gt;&gt; formatDouble standardDefaultPrecision 1.2345e-2
--   "0.01234"
--   
--   &gt;&gt;&gt; formatDouble scientific 12.345
--   "1.2345e1"
--   
--   &gt;&gt;&gt; formatDouble generic 12.345
--   "12.345"
--   </pre>
formatDouble :: FloatFormat -> Double -> Builder

-- | Format type for use with <a>formatFloat</a> and <a>formatDouble</a>.
data FloatFormat

-- | Standard notation with <tt>n</tt> decimal places
standard :: Int -> FloatFormat

-- | Standard notation with the 'default precision' (decimal places
--   matching <a>show</a>)
standardDefaultPrecision :: FloatFormat

-- | Scientific notation with 'default precision' (decimal places matching
--   <a>show</a>)
scientific :: FloatFormat

-- | Standard or scientific notation depending on the exponent. Matches
--   <a>show</a>
generic :: FloatFormat
instance GHC.Show.Show Data.ByteString.Builder.RealFloat.FormatMode


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

-- | <i>Heavy inlining.</i> Execute a <a>Builder</a> with custom execution
--   parameters.
--   
--   This function is inlined despite its heavy code-size to allow fusing
--   with the allocation strategy. For example, the default <a>Builder</a>
--   execution function <a>toLazyByteString</a> is defined as follows.
--   
--   <pre>
--   {-# NOINLINE toLazyByteString #-}
--   toLazyByteString =
--     toLazyByteStringWith (<a>safeStrategy</a> <a>smallChunkSize</a> <a>defaultChunkSize</a>) L.empty
--   </pre>
--   
--   where <tt>L.empty</tt> is the zero-length lazy <a>ByteString</a>.
--   
--   In most cases, the parameters used by <a>toLazyByteString</a> give
--   good performance. A sub-performing case of <a>toLazyByteString</a> is
--   executing short (&lt;128 bytes) <a>Builder</a>s. In this case, the
--   allocation overhead for the first 4kb buffer and the trimming cost
--   dominate the cost of executing the <a>Builder</a>. You can avoid this
--   problem using
--   
--   <pre>
--   toLazyByteStringWith (safeStrategy 128 smallChunkSize) L.empty
--   </pre>
--   
--   This reduces the allocation and trimming overhead, as all generated
--   <a>ByteString</a>s fit into the first buffer and there is no trimming
--   required, 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
--   are likely to survive one garbage collection. This strategy trims
--   buffers that are filled less than half in order to avoid spilling too
--   much memory.
safeStrategy :: Int -> Int -> AllocationStrategy

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

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

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

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

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

-- | Construct a <a>Builder</a> that copies the strict <a>ByteString</a>s,
--   if it is smaller than the treshold, and inserts it directly otherwise.
--   
--   For example, <tt>byteStringThreshold 1024</tt> copies strict
--   <a>ByteString</a>s whose size is less or equal to 1kb, and inserts
--   them directly otherwise. This implies that the average chunk-size of
--   the generated lazy <a>ByteString</a> may be as low as 513 bytes, as
--   there could always be just a single byte between the directly inserted
--   1025 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
--   <a>ByteString</a> directly.
lazyByteStringInsert :: ByteString -> Builder

-- | Construct a <a>Builder</a> that uses the thresholding strategy of
--   <a>byteStringThreshold</a> for each chunk of the lazy
--   <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
--   <a>Builder</a>. It unfolds as a sequence of chunks of data. These
--   chunks come in two forms:
--   
--   <ul>
--   <li>an IO action for writing the Builder's data into a user-supplied
--   memory buffer.</li>
--   <li>a pre-existing chunks of data represented by a strict
--   <a>ByteString</a></li>
--   </ul>
--   
--   While this is rather low level, it provides you with full flexibility
--   in how the data is written out.
--   
--   The <a>BufferWriter</a> itself is an IO action: you supply it with a
--   buffer (as a pointer and length) and it will write data into the
--   buffer. It returns a number indicating how many bytes were actually
--   written (which can be <tt>0</tt>). It also returns a <a>Next</a> which
--   describes what comes next.
type BufferWriter = Ptr Word8 -> Int -> IO (Int, Next)

-- | After running a <a>BufferWriter</a> action there are three
--   possibilities 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
--   next <a>BufferWriter</a> action. You should call that action with an
--   appropriate buffer. The int indicates the <i>minimum</i> buffer size
--   required by the next <a>BufferWriter</a> action. That is, if you call
--   the next action you <i>must</i> supply it with a buffer length of at
--   least this size.
More :: !Int -> BufferWriter -> Next

-- | In addition to the data that has just been written into your buffer by
--   the <a>BufferWriter</a> action, it gives you a pre-existing chunk of
--   data as a <a>ByteString</a>. It also gives you the following
--   <a>BufferWriter</a> action. It is safe to run this following action
--   using a buffer with as much free space as was left by the previous run
--   action.
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
--   in host order, host endian form, for the machine you're on. On a 64
--   bit machine the <a>Int</a> is an 8 byte value, on a 32 bit machine, 4
--   bytes. Values encoded this way are not portable to different endian or
--   int 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
--   in host order, host endian form, for the machine you're on. On a 64
--   bit machine the <a>Word</a> is an 8 byte value, on a 32 bit machine, 4
--   bytes. Values encoded this way are not portable to different endian or
--   word 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
--   are not portable to different endian machines, without conversion.
floatHost :: Float -> Builder

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


-- | <a>Builder</a>s are used to efficiently construct sequences of bytes
--   from smaller parts. Typically, such a construction is part of the
--   implementation of an <i>encoding</i>, i.e., a function for converting
--   Haskell values to sequences of bytes. Examples of encodings are the
--   generation of the sequence of bytes representing a HTML document to be
--   sent in a HTTP response by a web application or the serialization of a
--   Haskell value using a fixed binary format.
--   
--   For an <i>efficient implementation of an encoding</i>, it is important
--   that (a) little time is spent on converting the Haskell values to the
--   resulting sequence of bytes <i>and</i> (b) that the representation of
--   the resulting sequence is such that it can be consumed efficiently.
--   <a>Builder</a>s support (a) by providing an <i>O(1)</i> concatentation
--   operation and efficient implementations of basic encodings for
--   <a>Char</a>s, <a>Int</a>s, and other standard Haskell values. They
--   support (b) by providing their result as a lazy <a>ByteString</a>,
--   which is internally just a linked list of pointers to <i>chunks</i> of
--   consecutive raw memory. Lazy <a>ByteString</a>s can be efficiently
--   consumed by functions that write them to a file or send them over a
--   network socket. Note that each chunk boundary incurs expensive extra
--   work (e.g., a system call) that must be amortized over the work spent
--   on consuming the chunk body. <a>Builder</a>s therefore take special
--   care to ensure that the average chunk size is large enough. The
--   precise meaning of large enough is application dependent. The current
--   implementation is tuned for an average chunk size between 4kb and
--   32kb, which should suit most applications.
--   
--   As a simple example of an encoding implementation, we show how to
--   efficiently convert the following representation of mixed-data tables
--   to an UTF-8 encoded Comma-Separated-Values (CSV) table.
--   
--   <pre>
--   data Cell = StringC String
--             | IntC Int
--             deriving( Eq, Ord, Show )
--   
--   type Row   = [Cell]
--   type Table = [Row]
--   </pre>
--   
--   We use the following imports and abbreviate <a>mappend</a> to simplify
--   reading.
--   
--   <pre>
--   import qualified <a>Data.ByteString.Lazy</a>               as L
--   import           <a>Data.ByteString.Builder</a>
--   import           Data.Monoid
--   import           Data.Foldable                        (<a>foldMap</a>)
--   import           Data.List                            (<a>intersperse</a>)
--   
--   infixr 4 &lt;&gt;
--   (&lt;&gt;) :: <a>Monoid</a> m =&gt; m -&gt; m -&gt; m
--   (&lt;&gt;) = <a>mappend</a>
--   </pre>
--   
--   CSV is a character-based representation of tables. For maximal
--   modularity, we could first render <tt>Table</tt>s as <a>String</a>s
--   and then encode this <a>String</a> using some Unicode character
--   encoding. However, this sacrifices performance due to the intermediate
--   <a>String</a> representation being built and thrown away right
--   afterwards. We get rid of this intermediate <a>String</a>
--   representation by fixing the character encoding to UTF-8 and using
--   <a>Builder</a>s to convert <tt>Table</tt>s directly to UTF-8 encoded
--   CSV tables represented as lazy <a>ByteString</a>s.
--   
--   <pre>
--   encodeUtf8CSV :: Table -&gt; L.ByteString
--   encodeUtf8CSV = <a>toLazyByteString</a> . renderTable
--   
--   renderTable :: Table -&gt; Builder
--   renderTable rs = <a>mconcat</a> [renderRow r &lt;&gt; <a>charUtf8</a> '\n' | r &lt;- rs]
--   
--   renderRow :: Row -&gt; Builder
--   renderRow []     = <a>mempty</a>
--   renderRow (c:cs) =
--       renderCell c &lt;&gt; mconcat [ charUtf8 ',' &lt;&gt; renderCell c' | c' &lt;- cs ]
--   
--   renderCell :: Cell -&gt; Builder
--   renderCell (StringC cs) = renderString cs
--   renderCell (IntC i)     = <a>intDec</a> i
--   
--   renderString :: String -&gt; Builder
--   renderString cs = charUtf8 '"' &lt;&gt; foldMap escape cs &lt;&gt; charUtf8 '"'
--     where
--       escape '\\' = charUtf8 '\\' &lt;&gt; charUtf8 '\\'
--       escape '\"' = charUtf8 '\\' &lt;&gt; charUtf8 '\"'
--       escape c    = charUtf8 c
--   </pre>
--   
--   Note that the ASCII encoding is a subset of the UTF-8 encoding, which
--   is why we can use the optimized function <a>intDec</a> to encode an
--   <a>Int</a> as a decimal number with UTF-8 encoded digits. Using
--   <a>intDec</a> is more efficient than <tt><a>stringUtf8</a> .
--   <a>show</a></tt>, as it avoids constructing an intermediate
--   <a>String</a>. Avoiding this intermediate data structure significantly
--   improves performance because encoding <tt>Cell</tt>s is the core
--   operation for rendering CSV-tables. See
--   <a>Data.ByteString.Builder.Prim</a> for further information on how to
--   improve the performance of <tt>renderString</tt>.
--   
--   We demonstrate our UTF-8 CSV encoding function on the following table.
--   
--   <pre>
--   strings :: [String]
--   strings =  ["hello", "\"1\"", "λ-wörld"]
--   
--   table :: Table
--   table = [map StringC strings, map IntC [-3..3]]
--   </pre>
--   
--   The expression <tt>encodeUtf8CSV table</tt> results in the following
--   lazy <a>ByteString</a>.
--   
--   <pre>
--   Chunk "\"hello\",\"\\\"1\\\"\",\"\206\187-w\195\182rld\"\n-3,-2,-1,0,1,2,3\n" Empty
--   </pre>
--   
--   We can clearly see that we are converting to a <i>binary</i> format.
--   The 'λ' and 'ö' characters, which have a Unicode codepoint above 127,
--   are expanded to their corresponding UTF-8 multi-byte representation.
--   
--   We use the <tt>criterion</tt> library
--   (<a>http://hackage.haskell.org/package/criterion</a>) to benchmark the
--   efficiency of our encoding function on the following table.
--   
--   <pre>
--   import Criterion.Main     -- add this import to the ones above
--   
--   maxiTable :: Table
--   maxiTable = take 1000 $ cycle table
--   
--   main :: IO ()
--   main = defaultMain
--     [ bench "encodeUtf8CSV maxiTable (original)" $
--         whnf (L.length . encodeUtf8CSV) maxiTable
--     ]
--   </pre>
--   
--   On a Core2 Duo 2.20GHz on a 32-bit Linux, the above code takes 1ms to
--   generate the 22'500 bytes long lazy <a>ByteString</a>. Looking again
--   at the definitions above, we see that we took care to avoid
--   intermediate data structures, as otherwise we would sacrifice
--   performance. For example, the following (arguably simpler) definition
--   of <tt>renderRow</tt> is about 20% slower.
--   
--   <pre>
--   renderRow :: Row -&gt; Builder
--   renderRow  = mconcat . intersperse (charUtf8 ',') . map renderCell
--   </pre>
--   
--   Similarly, using <i>O(n)</i> concatentations like <a>++</a> or the
--   equivalent <a>concat</a> operations on strict and lazy
--   <a>ByteString</a>s should be avoided. The following definition of
--   <tt>renderString</tt> is also about 20% slower.
--   
--   <pre>
--   renderString :: String -&gt; Builder
--   renderString cs = charUtf8 $ "\"" ++ concatMap escape cs ++ "\""
--     where
--       escape '\\' = "\\"
--       escape '\"' = "\\\""
--       escape c    = return c
--   </pre>
--   
--   Apart from removing intermediate data-structures, encodings can be
--   optimized further by fine-tuning their execution parameters using the
--   functions in <a>Data.ByteString.Builder.Extra</a> and their "inner
--   loops" 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
--   where <a>mempty</a> is the zero-length sequence and <a>mappend</a> is
--   concatenation, which runs in <i>O(1)</i>.
data Builder

-- | Execute a <a>Builder</a> and return the generated chunks as a lazy
--   <a>ByteString</a>. The work is performed lazy, i.e., only when a chunk
--   of 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
--   executed directly on the buffer of the <a>Handle</a>. If the buffer is
--   too small (or not present), then it is replaced with a large enough
--   buffer.
--   
--   It is recommended that the <a>Handle</a> is set to binary and
--   <a>BlockBuffering</a> mode. See <a>hSetBinaryMode</a> and
--   <a>hSetBuffering</a>.
--   
--   This function is more efficient than <tt>hPut .
--   <a>toLazyByteString</a></tt> because in many cases no buffer
--   allocation has to be done. Moreover, the results of several executions
--   of short <a>Builder</a>s are concatenated in the <a>Handle</a>s
--   buffer, therefore avoiding unnecessary buffer flushes.
hPutBuilder :: Handle -> Builder -> IO ()

-- | Write a <a>Builder</a> to a file.
--   
--   Similarly to <a>hPutBuilder</a>, this function is more efficient than
--   using <a>hPut</a> . <a>toLazyByteString</a> with a file handle.
writeFile :: FilePath -> Builder -> IO ()

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

-- | Create a <a>Builder</a> denoting the same sequence of bytes as a lazy
--   <a>ByteString</a>. The <a>Builder</a> inserts large chunks of the lazy
--   <a>ByteString</a> directly, but copies small ones to ensure that the
--   generated 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>.
--   
--   Note that <a>stringUtf8</a> performs no codepoint validation and
--   consequently may emit invalid UTF-8 if asked (e.g. single surrogates).
stringUtf8 :: String -> Builder

-- | Decimal encoding of an <a>Int8</a> using the ASCII digits.
--   
--   e.g.
--   
--   <pre>
--   toLazyByteString (int8Dec 42)   = "42"
--   toLazyByteString (int8Dec (-1)) = "-1"
--   </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

-- | Returns a rendered Float. Matches <a>show</a> in displaying in
--   standard or scientific notation
--   
--   <pre>
--   floatDec = <a>formatFloat</a> <a>generic</a>
--   </pre>
floatDec :: Float -> Builder

-- | Returns a rendered Double. Matches <a>show</a> in displaying in
--   standard or scientific notation
--   
--   <pre>
--   doubleDec = <a>formatDouble</a> <a>generic</a>
--   </pre>
doubleDec :: Double -> Builder

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

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

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

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

-- | Shortest hexadecimal encoding of a <a>Word</a> using lower-case
--   characters.
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
--   encoding.
byteStringHex :: ByteString -> Builder

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