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


-- | Binary serialisation for Haskell values using lazy ByteStrings
°5u
°5uEfficient, pure binary serialisation using lazy ByteStrings. Haskell
°5uvalues may be encoded to and from binary formats, written to disk as
°5ubinary, or sent over the network. The format used can be automatically
°5ugenerated, or you can choose to implement a custom format if needed.
°5uSerialisation speeds of over 1 G/sec have been observed, so this
°5ulibrary should be suitable for high performance scenarios.
@package binary
@version 0.8.5.1


-- | Efficient constructions of lazy bytestrings.
°5u
°5uThis now re-exports <a>Builder</a>.
module Data.Binary.Builder

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

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

-- | <i>O(1).</i> The empty Builder, satisfying
°5u
°5u<ul>
°5u<li><pre><a>toLazyByteString</a> <a>empty</a> =
°5u<a>empty</a></pre></li>
°5u</ul>
empty :: Builder

-- | <i>O(1).</i> A Builder taking a single byte, satisfying
°5u
°5u<ul>
°5u<li><pre><a>toLazyByteString</a> (<a>singleton</a> b) =
°5u<a>singleton</a> b</pre></li>
°5u</ul>
singleton :: Word8 -> Builder

-- | <i>O(1).</i> The concatenation of two Builders, an associative
°5uoperation with identity <a>empty</a>, satisfying
°5u
°5u<ul>
°5u<li><pre><a>toLazyByteString</a> (<a>append</a> x y) = <a>append</a>
°5u(<a>toLazyByteString</a> x) (<a>toLazyByteString</a> y)</pre></li>
°5u</ul>
append :: Builder -> Builder -> Builder

-- | <i>O(1).</i> A Builder taking a <a>ByteString</a>, satisfying
°5u
°5u<ul>
°5u<li><pre><a>toLazyByteString</a> (<a>fromByteString</a> bs) =
°5u<a>fromChunks</a> [bs]</pre></li>
°5u</ul>
fromByteString :: ByteString -> Builder

-- | <i>O(1).</i> A Builder taking a lazy <a>ByteString</a>, satisfying
°5u
°5u<ul>
°5u<li><pre><a>toLazyByteString</a> (<a>fromLazyByteString</a> bs) =
°5ubs</pre></li>
°5u</ul>
fromLazyByteString :: ByteString -> Builder

-- | <i>O(n).</i> A builder taking <a>ShortByteString</a> and copy it to a
°5uBuilder, satisfying
°5u
°5u<ul>
°5u<li>@<a>toLazyByteString</a> (<a>fromShortByteString</a> bs) =
°5u<a>fromChunks</a> [<a>fromShort</a> bs]</li>
°5u</ul>
fromShortByteString :: ShortByteString -> Builder

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

-- | Write a Word16 in big endian format
putWord16be :: Word16 -> Builder

-- | Write a Word32 in big endian format
putWord32be :: Word32 -> Builder

-- | Write a Word64 in big endian format
putWord64be :: Word64 -> Builder

-- | Write a Int16 in big endian format
putInt16be :: Int16 -> Builder

-- | Write a Int32 in big endian format
putInt32be :: Int32 -> Builder

-- | Write a Int64 in big endian format
putInt64be :: Int64 -> Builder

-- | Write a Word16 in little endian format
putWord16le :: Word16 -> Builder

-- | Write a Word32 in little endian format
putWord32le :: Word32 -> Builder

-- | Write a Word64 in little endian format
putWord64le :: Word64 -> Builder

-- | Write a Int16 in little endian format
putInt16le :: Int16 -> Builder

-- | Write a Int32 in little endian format
putInt32le :: Int32 -> Builder

-- | Write a Int64 in little endian format
putInt64le :: Int64 -> Builder

-- | <i>O(1).</i> A Builder taking a single native machine word. The word
°5uis written in host order, host endian form, for the machine you're on.
°5uOn a 64 bit machine the Word is an 8 byte value, on a 32 bit machine,
°5u4 bytes. Values written this way are not portable to different endian
°5uor word sized machines, without conversion.
putWordhost :: Word -> Builder

-- | Write a Word16 in native host order and host endianness. 2 bytes will
°5ube written, unaligned.
putWord16host :: Word16 -> Builder

-- | Write a Word32 in native host order and host endianness. 4 bytes will
°5ube written, unaligned.
putWord32host :: Word32 -> Builder

-- | Write a Word64 in native host order. On a 32 bit machine we write two
°5uhost order Word32s, in big endian form. 8 bytes will be written,
°5uunaligned.
putWord64host :: Word64 -> Builder

-- | <i>O(1).</i> A Builder taking a single native machine word. The word
°5uis written in host order, host endian form, for the machine you're on.
°5uOn a 64 bit machine the Int is an 8 byte value, on a 32 bit machine, 4
°5ubytes. Values written this way are not portable to different endian or
°5uword sized machines, without conversion.
putInthost :: Int -> Builder

-- | Write a Int16 in native host order and host endianness. 2 bytes will
°5ube written, unaligned.
putInt16host :: Int16 -> Builder

-- | Write a Int32 in native host order and host endianness. 4 bytes will
°5ube written, unaligned.
putInt32host :: Int32 -> Builder

-- | Write a Int64 in native host order. On a 32 bit machine we write two
°5uhost order Int32s, in big endian form. 8 bytes will be written,
°5uunaligned.
putInt64host :: Int64 -> Builder

-- | Write a character using UTF-8 encoding.
putCharUtf8 :: Char -> Builder

-- | Write a String using UTF-8 encoding.
putStringUtf8 :: String -> Builder

module Data.Binary.Get.Internal
data Get a
runCont :: Get a -> forall r. ByteString -> Success a r -> Decoder r

-- | A decoder produced by running a <a>Get</a> monad.
data Decoder a

-- | The decoder ran into an error. The decoder either used <a>fail</a> or
°5uwas not provided enough input.
Fail :: !ByteString -> String -> Decoder a

-- | The decoder has consumed the available input and needs more to
°5ucontinue. Provide <a>Just</a> if more input is available and
°5u<a>Nothing</a> otherwise, and you will get a new <a>Decoder</a>.
Partial :: (Maybe ByteString -> Decoder a) -> Decoder a

-- | The decoder has successfully finished. Except for the output value you
°5ualso get the unused input.
Done :: !ByteString -> a -> Decoder a

-- | The decoder needs to know the current position in the input. Given the
°5unumber of bytes remaning in the decoder, the outer decoder runner
°5uneeds to calculate the position and resume the decoding.
BytesRead :: {-# UNPACK #-} !Int64 -> (Int64 -> Decoder a) -> Decoder a

-- | Run a <a>Get</a> monad. See <a>Decoder</a> for what to do next, like
°5uproviding input, handling decoding errors and to get the output value.
runGetIncremental :: Get a -> Decoder a

-- | Return at least <tt>n</tt> bytes, maybe more. If not enough data is
°5uavailable the computation will escape with <a>Partial</a>.
readN :: Int -> (ByteString -> a) -> Get a

-- | <tt>readNWith n f</tt> where <tt>f</tt> must be deterministic and not
°5uhave side effects.
readNWith :: Int -> (Ptr a -> IO a) -> Get a

-- | Get the total number of bytes read to this point.
bytesRead :: Get Int64

-- | Isolate a decoder to operate with a fixed number of bytes, and fail if
°5ufewer bytes were consumed, or more bytes were attempted to be
°5uconsumed. If the given decoder fails, <a>isolate</a> will also fail.
°5uOffset from <a>bytesRead</a> will be relative to the start of
°5u<a>isolate</a>, not the absolute of the input.
°5u
°5u<i>Since: 0.7.2.0</i>
isolate :: Int -> Get a -> Get a
withInputChunks :: s -> Consume s -> ([ByteString] -> b) -> ([ByteString] -> Get b) -> Get b
type Consume s = s -> ByteString -> Either s (ByteString, ByteString)
failOnEOF :: [ByteString] -> Get a

-- | Get the current chunk.
get :: Get ByteString

-- | Replace the current chunk.
put :: ByteString -> Get ()

-- | Ensure that there are at least <tt>n</tt> bytes available. If not, the
°5ucomputation will escape with <a>Partial</a>.
ensureN :: Int -> Get ()

-- | DEPRECATED. Get the number of bytes of remaining input. Note that this
°5uis an expensive function to use as in order to calculate how much
°5uinput remains, all input has to be read and kept in-memory. The
°5udecoder keeps the input as a strict bytestring, so you are likely
°5ubetter off by calculating the remaining input in another way.

-- | <i>Deprecated: This will force all remaining input, don't use it.</i>
remaining :: Get Int64

-- | DEPRECATED. Same as <a>getByteString</a>.

-- | <i>Deprecated: Use <a>getByteString</a> instead of
°5u<a>getBytes</a>.</i>
getBytes :: Int -> Get ByteString

-- | Test whether all input has been consumed, i.e. there are no remaining
°5uundecoded bytes.
isEmpty :: Get Bool

-- | Run the given decoder, but without consuming its input. If the given
°5udecoder fails, then so will this function.
°5u
°5u<i>Since: 0.7.0.0</i>
lookAhead :: Get a -> Get a

-- | Run the given decoder, and only consume its input if it returns
°5u<a>Just</a>. If <a>Nothing</a> is returned, the input will be
°5uunconsumed. If the given decoder fails, then so will this function.
°5u
°5u<i>Since: 0.7.0.0</i>
lookAheadM :: Get (Maybe a) -> Get (Maybe a)

-- | Run the given decoder, and only consume its input if it returns
°5u<a>Right</a>. If <a>Left</a> is returned, the input will be
°5uunconsumed. If the given decoder fails, then so will this function.
°5u
°5u<i>Since: 0.7.1.0</i>
lookAheadE :: Get (Either a b) -> Get (Either a b)

-- | Label a decoder. If the decoder fails, the label will be appended on a
°5unew line to the error message string.
°5u
°5u<i>Since: 0.7.2.0</i>
label :: String -> Get a -> Get a

-- | An efficient get method for strict ByteStrings. Fails if fewer than
°5u<tt>n</tt> bytes are left in the input. If <tt>n &lt;= 0</tt> then the
°5uempty string is returned.
getByteString :: Int -> Get ByteString
instance GHC.Base.Monad Data.Binary.Get.Internal.Get
instance Control.Monad.Fail.MonadFail Data.Binary.Get.Internal.Get
instance GHC.Base.Applicative Data.Binary.Get.Internal.Get
instance GHC.Base.MonadPlus Data.Binary.Get.Internal.Get
instance GHC.Base.Functor Data.Binary.Get.Internal.Get
instance GHC.Base.Alternative Data.Binary.Get.Internal.Get
instance GHC.Base.Functor Data.Binary.Get.Internal.Decoder
instance GHC.Show.Show a => GHC.Show.Show (Data.Binary.Get.Internal.Decoder a)


-- | The <a>Get</a> monad. A monad for efficiently building structures from
°5uencoded lazy ByteStrings.
°5u
°5uPrimitives are available to decode words of various sizes, both big
°5uand little endian.
°5u
°5uLet's decode binary data representing illustrated here. In this
°5uexample the values are in little endian.
°5u
°5u<pre>
°5u+------------------+--------------+-----------------+
°5u| 32 bit timestamp | 32 bit price | 16 bit quantity |
°5u+------------------+--------------+-----------------+
°5u</pre>
°5u
°5uA corresponding Haskell value looks like this:
°5u
°5u<pre>
°5udata Trade = Trade
°5u  { timestamp :: !<a>Word32</a>
°5u  , price     :: !<a>Word32</a>
°5u  , qty       :: !<a>Word16</a>
°5u  } deriving (<a>Show</a>)
°5u 
°5u</pre>
°5u
°5uThe fields in <tt>Trade</tt> are marked as strict (using <tt>!</tt>)
°5usince we don't need laziness here. In practise, you would probably
°5uconsider using the UNPACK pragma as well.
°5u<a>https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/glasgow_exts.html#unpack-pragma</a>
°5u
°5uNow, let's have a look at a decoder for this format.
°5u
°5u<pre>
°5ugetTrade :: <a>Get</a> Trade
°5ugetTrade = do
°5u  timestamp &lt;- <a>getWord32le</a>
°5u  price     &lt;- <a>getWord32le</a>
°5u  quantity  &lt;- <a>getWord16le</a>
°5u  return <a>$!</a> Trade timestamp price quantity
°5u 
°5u</pre>
°5u
°5uOr even simpler using applicative style:
°5u
°5u<pre>
°5ugetTrade' :: <a>Get</a> Trade
°5ugetTrade' = Trade <a>&lt;$&gt;</a> <a>getWord32le</a> <a>&lt;*&gt;</a> <a>getWord32le</a> <a>&lt;*&gt;</a> <a>getWord16le</a>
°5u 
°5u</pre>
°5u
°5uThere are two kinds of ways to execute this decoder, the lazy input
°5umethod and the incremental input method. Here we will use the lazy
°5uinput method.
°5u
°5uLet's first define a function that decodes many <tt>Trade</tt>s.
°5u
°5u<pre>
°5ugetTrades :: Get [Trade]
°5ugetTrades = do
°5u  empty &lt;- <a>isEmpty</a>
°5u  if empty
°5u    then return []
°5u    else do trade &lt;- getTrade
°5u            trades &lt;- getTrades
°5u            return (trade:trades)
°5u 
°5u</pre>
°5u
°5uFinally, we run the decoder:
°5u
°5u<pre>
°5ulazyIOExample :: IO [Trade]
°5ulazyIOExample = do
°5u  input &lt;- BL.readFile "trades.bin"
°5u  return (<a>runGet</a> getTrades input)
°5u 
°5u</pre>
°5u
°5uThis decoder has the downside that it will need to read all the input
°5ubefore it can return. On the other hand, it will not return anything
°5uuntil it knows it could decode without any decoder errors.
°5u
°5uYou could also refactor to a left-fold, to decode in a more streaming
°5ufashion, and get the following decoder. It will start to return data
°5uwithout knowing that it can decode all input.
°5u
°5u<pre>
°5uincrementalExample :: BL.ByteString -&gt; [Trade]
°5uincrementalExample input0 = go decoder input0
°5u  where
°5u    decoder = <a>runGetIncremental</a> getTrade
°5u    go :: <a>Decoder</a> Trade -&gt; BL.ByteString -&gt; [Trade]
°5u    go (<a>Done</a> leftover _consumed trade) input =
°5u      trade : go decoder (BL.chunk leftover input)
°5u    go (<a>Partial</a> k) input                     =
°5u      go (k . takeHeadChunk $ input) (dropHeadChunk input)
°5u    go (<a>Fail</a> _leftover _consumed msg) _input =
°5u      error msg
°5u
°5utakeHeadChunk :: BL.ByteString -&gt; Maybe BS.ByteString
°5utakeHeadChunk lbs =
°5u  case lbs of
°5u    (BL.Chunk bs _) -&gt; Just bs
°5u    _ -&gt; Nothing
°5u
°5udropHeadChunk :: BL.ByteString -&gt; BL.ByteString
°5udropHeadChunk lbs =
°5u  case lbs of
°5u    (BL.Chunk _ lbs') -&gt; lbs'
°5u    _ -&gt; BL.Empty
°5u 
°5u</pre>
°5u
°5uThe <tt>lazyIOExample</tt> uses lazy I/O to read the file from the
°5udisk, which is not suitable in all applications, and certainly not if
°5uyou need to read from a socket which has higher likelihood to fail. To
°5uaddress these needs, use the incremental input method like in
°5u<tt>incrementalExample</tt>. For an example of how to read
°5uincrementally from a Handle, see the implementation of
°5u<tt>decodeFileOrFail</tt> in <a>Data.Binary</a>.
module Data.Binary.Get
data Get a

-- | The simplest interface to run a <a>Get</a> decoder. If the decoder
°5uruns into an error, calls <a>fail</a>, or runs out of input, it will
°5ucall <a>error</a>.
runGet :: Get a -> ByteString -> a

-- | Run a <a>Get</a> monad and return <a>Left</a> on failure and
°5u<a>Right</a> on success. In both cases any unconsumed input and the
°5unumber of bytes consumed is returned. In the case of failure, a
°5uhuman-readable error message is included as well.
°5u
°5u<i>Since: 0.6.4.0</i>
runGetOrFail :: Get a -> ByteString -> Either (ByteString, ByteOffset, String) (ByteString, ByteOffset, a)

-- | An offset, counted in bytes.
type ByteOffset = Int64

-- | A decoder procuced by running a <a>Get</a> monad.
data Decoder a

-- | The decoder ran into an error. The decoder either used <a>fail</a> or
°5uwas not provided enough input. Contains any unconsumed input and the
°5unumber of bytes consumed.
Fail :: !ByteString -> {-# UNPACK #-} !ByteOffset -> String -> Decoder a

-- | The decoder has consumed the available input and needs more to
°5ucontinue. Provide <a>Just</a> if more input is available and
°5u<a>Nothing</a> otherwise, and you will get a new <a>Decoder</a>.
Partial :: (Maybe ByteString -> Decoder a) -> Decoder a

-- | The decoder has successfully finished. Except for the output value you
°5ualso get any unused input as well as the number of bytes consumed.
Done :: !ByteString -> {-# UNPACK #-} !ByteOffset -> a -> Decoder a

-- | Run a <a>Get</a> monad. See <a>Decoder</a> for what to do next, like
°5uproviding input, handling decoder errors and to get the output value.
°5uHint: Use the helper functions <a>pushChunk</a>, <a>pushChunks</a> and
°5u<a>pushEndOfInput</a>.
runGetIncremental :: Get a -> Decoder a

-- | Feed a <a>Decoder</a> with more input. If the <a>Decoder</a> is
°5u<a>Done</a> or <a>Fail</a> it will add the input to <a>ByteString</a>
°5uof unconsumed input.
°5u
°5u<pre>
°5u<a>runGetIncremental</a> myParser `pushChunk` myInput1 `pushChunk` myInput2
°5u</pre>
pushChunk :: Decoder a -> ByteString -> Decoder a

-- | Feed a <a>Decoder</a> with more input. If the <a>Decoder</a> is
°5u<a>Done</a> or <a>Fail</a> it will add the input to
°5u<tt>ByteString</tt> of unconsumed input.
°5u
°5u<pre>
°5u<a>runGetIncremental</a> myParser `pushChunks` myLazyByteString
°5u</pre>
pushChunks :: Decoder a -> ByteString -> Decoder a

-- | Tell a <a>Decoder</a> that there is no more input. This passes
°5u<a>Nothing</a> to a <a>Partial</a> decoder, otherwise returns the
°5udecoder unchanged.
pushEndOfInput :: Decoder a -> Decoder a

-- | Skip ahead <tt>n</tt> bytes. Fails if fewer than <tt>n</tt> bytes are
°5uavailable.
skip :: Int -> Get ()

-- | Test whether all input has been consumed, i.e. there are no remaining
°5uundecoded bytes.
isEmpty :: Get Bool

-- | Get the total number of bytes read to this point.
bytesRead :: Get Int64

-- | Isolate a decoder to operate with a fixed number of bytes, and fail if
°5ufewer bytes were consumed, or more bytes were attempted to be
°5uconsumed. If the given decoder fails, <a>isolate</a> will also fail.
°5uOffset from <a>bytesRead</a> will be relative to the start of
°5u<a>isolate</a>, not the absolute of the input.
°5u
°5u<i>Since: 0.7.2.0</i>
isolate :: Int -> Get a -> Get a

-- | Run the given decoder, but without consuming its input. If the given
°5udecoder fails, then so will this function.
°5u
°5u<i>Since: 0.7.0.0</i>
lookAhead :: Get a -> Get a

-- | Run the given decoder, and only consume its input if it returns
°5u<a>Just</a>. If <a>Nothing</a> is returned, the input will be
°5uunconsumed. If the given decoder fails, then so will this function.
°5u
°5u<i>Since: 0.7.0.0</i>
lookAheadM :: Get (Maybe a) -> Get (Maybe a)

-- | Run the given decoder, and only consume its input if it returns
°5u<a>Right</a>. If <a>Left</a> is returned, the input will be
°5uunconsumed. If the given decoder fails, then so will this function.
°5u
°5u<i>Since: 0.7.1.0</i>
lookAheadE :: Get (Either a b) -> Get (Either a b)

-- | Label a decoder. If the decoder fails, the label will be appended on a
°5unew line to the error message string.
°5u
°5u<i>Since: 0.7.2.0</i>
label :: String -> Get a -> Get a

-- | An efficient get method for strict ByteStrings. Fails if fewer than
°5u<tt>n</tt> bytes are left in the input. If <tt>n &lt;= 0</tt> then the
°5uempty string is returned.
getByteString :: Int -> Get ByteString

-- | An efficient get method for lazy ByteStrings. Fails if fewer than
°5u<tt>n</tt> bytes are left in the input.
getLazyByteString :: Int64 -> Get ByteString

-- | Get a lazy ByteString that is terminated with a NUL byte. The returned
°5ustring does not contain the NUL byte. Fails if it reaches the end of
°5uinput without finding a NUL.
getLazyByteStringNul :: Get ByteString

-- | Get the remaining bytes as a lazy ByteString. Note that this can be an
°5uexpensive function to use as it forces reading all input and keeping
°5uthe string in-memory.
getRemainingLazyByteString :: Get ByteString

-- | Read a Word8 from the monad state
getWord8 :: Get Word8

-- | Read a Word16 in big endian format
getWord16be :: Get Word16

-- | Read a Word32 in big endian format
getWord32be :: Get Word32

-- | Read a Word64 in big endian format
getWord64be :: Get Word64

-- | Read a Word16 in little endian format
getWord16le :: Get Word16

-- | Read a Word32 in little endian format
getWord32le :: Get Word32

-- | Read a Word64 in little endian format
getWord64le :: Get Word64

-- | <i>O(1).</i> Read a single native machine word. The word is read in
°5uhost order, host endian form, for the machine you're on. On a 64 bit
°5umachine the Word is an 8 byte value, on a 32 bit machine, 4 bytes.
getWordhost :: Get Word

-- | <i>O(1).</i> Read a 2 byte Word16 in native host order and host
°5uendianness.
getWord16host :: Get Word16

-- | <i>O(1).</i> Read a Word32 in native host order and host endianness.
getWord32host :: Get Word32

-- | <i>O(1).</i> Read a Word64 in native host order and host endianess.
getWord64host :: Get Word64

-- | Read an Int8 from the monad state
getInt8 :: Get Int8

-- | Read an Int16 in big endian format.
getInt16be :: Get Int16

-- | Read an Int32 in big endian format.
getInt32be :: Get Int32

-- | Read an Int64 in big endian format.
getInt64be :: Get Int64

-- | Read an Int16 in little endian format.
getInt16le :: Get Int16

-- | Read an Int32 in little endian format.
getInt32le :: Get Int32

-- | Read an Int64 in little endian format.
getInt64le :: Get Int64

-- | <i>O(1).</i> Read a single native machine word in native host order.
°5uIt works in the same way as <a>getWordhost</a>.
getInthost :: Get Int

-- | <i>O(1).</i> Read a 2 byte Int16 in native host order and host
°5uendianness.
getInt16host :: Get Int16

-- | <i>O(1).</i> Read an Int32 in native host order and host endianness.
getInt32host :: Get Int32

-- | <i>O(1).</i> Read an Int64 in native host order and host endianess.
getInt64host :: Get Int64

-- | Read a <a>Float</a> in big endian IEEE-754 format.
getFloatbe :: Get Float

-- | Read a <a>Float</a> in little endian IEEE-754 format.
getFloatle :: Get Float

-- | Read a <a>Float</a> in IEEE-754 format and host endian.
getFloathost :: Get Float

-- | Read a <a>Double</a> in big endian IEEE-754 format.
getDoublebe :: Get Double

-- | Read a <a>Double</a> in little endian IEEE-754 format.
getDoublele :: Get Double

-- | Read a <a>Double</a> in IEEE-754 format and host endian.
getDoublehost :: Get Double

-- | DEPRECATED. Provides compatibility with previous versions of this
°5ulibrary. Run a <a>Get</a> monad and return a tuple with three values.
°5uThe first value is the result of the decoder. The second and third are
°5uthe unused input, and the number of consumed bytes.

-- | <i>Deprecated: Use runGetIncremental instead. This function will be
°5uremoved.</i>
runGetState :: Get a -> ByteString -> ByteOffset -> (a, ByteString, ByteOffset)

-- | DEPRECATED. Get the number of bytes of remaining input. Note that this
°5uis an expensive function to use as in order to calculate how much
°5uinput remains, all input has to be read and kept in-memory. The
°5udecoder keeps the input as a strict bytestring, so you are likely
°5ubetter off by calculating the remaining input in another way.

-- | <i>Deprecated: This will force all remaining input, don't use it.</i>
remaining :: Get Int64

-- | DEPRECATED. Same as <a>getByteString</a>.

-- | <i>Deprecated: Use <a>getByteString</a> instead of
°5u<a>getBytes</a>.</i>
getBytes :: Int -> Get ByteString


-- | The Put monad. A monad for efficiently constructing lazy bytestrings.
module Data.Binary.Put

-- | Put merely lifts Builder into a Writer monad, applied to ().
type Put = PutM ()

-- | The PutM type. A Writer monad over the efficient Builder monoid.
newtype PutM a
Put :: PairS a -> PutM a
[unPut] :: PutM a -> PairS a

-- | Run the <a>Put</a> monad with a serialiser
runPut :: Put -> ByteString

-- | Run the <a>Put</a> monad with a serialiser and get its result
runPutM :: PutM a -> (a, ByteString)
putBuilder :: Builder -> Put

-- | Run the <a>Put</a> monad
execPut :: PutM a -> Builder

-- | Pop the ByteString we have constructed so far, if any, yielding a new
°5uchunk in the result ByteString.
flush :: Put

-- | Efficiently write a byte into the output buffer
putWord8 :: Word8 -> Put

-- | Efficiently write a signed byte into the output buffer
putInt8 :: Int8 -> Put

-- | An efficient primitive to write a strict ByteString into the output
°5ubuffer. It flushes the current buffer, and writes the argument into a
°5unew chunk.
putByteString :: ByteString -> Put

-- | Write a lazy ByteString efficiently, simply appending the lazy
°5uByteString chunks to the output buffer
putLazyByteString :: ByteString -> Put

-- | Write <a>ShortByteString</a> to the buffer
putShortByteString :: ShortByteString -> Put

-- | Write a Word16 in big endian format
putWord16be :: Word16 -> Put

-- | Write a Word32 in big endian format
putWord32be :: Word32 -> Put

-- | Write a Word64 in big endian format
putWord64be :: Word64 -> Put

-- | Write an Int16 in big endian format
putInt16be :: Int16 -> Put

-- | Write an Int32 in big endian format
putInt32be :: Int32 -> Put

-- | Write an Int64 in big endian format
putInt64be :: Int64 -> Put

-- | Write a <a>Float</a> in big endian IEEE-754 format.
putFloatbe :: Float -> Put

-- | Write a <a>Double</a> in big endian IEEE-754 format.
putDoublebe :: Double -> Put

-- | Write a Word16 in little endian format
putWord16le :: Word16 -> Put

-- | Write a Word32 in little endian format
putWord32le :: Word32 -> Put

-- | Write a Word64 in little endian format
putWord64le :: Word64 -> Put

-- | Write an Int16 in little endian format
putInt16le :: Int16 -> Put

-- | Write an Int32 in little endian format
putInt32le :: Int32 -> Put

-- | Write an Int64 in little endian format
putInt64le :: Int64 -> Put

-- | Write a <a>Float</a> in little endian IEEE-754 format.
putFloatle :: Float -> Put

-- | Write a <a>Double</a> in little endian IEEE-754 format.
putDoublele :: Double -> Put

-- | <i>O(1).</i> Write a single native machine word. The word is written
°5uin host order, host endian form, for the machine you're on. On a 64
°5ubit machine the Word is an 8 byte value, on a 32 bit machine, 4 bytes.
°5uValues written this way are not portable to different endian or word
°5usized machines, without conversion.
putWordhost :: Word -> Put

-- | <i>O(1).</i> Write a Word16 in native host order and host endianness.
°5uFor portability issues see <tt>putWordhost</tt>.
putWord16host :: Word16 -> Put

-- | <i>O(1).</i> Write a Word32 in native host order and host endianness.
°5uFor portability issues see <tt>putWordhost</tt>.
putWord32host :: Word32 -> Put

-- | <i>O(1).</i> Write a Word64 in native host order On a 32 bit machine
°5uwe write two host order Word32s, in big endian form. For portability
°5uissues see <tt>putWordhost</tt>.
putWord64host :: Word64 -> Put

-- | <i>O(1).</i> Write a single native machine word. The word is written
°5uin host order, host endian form, for the machine you're on. On a 64
°5ubit machine the Int is an 8 byte value, on a 32 bit machine, 4 bytes.
°5uValues written this way are not portable to different endian or word
°5usized machines, without conversion.
putInthost :: Int -> Put

-- | <i>O(1).</i> Write an Int16 in native host order and host endianness.
°5uFor portability issues see <tt>putInthost</tt>.
putInt16host :: Int16 -> Put

-- | <i>O(1).</i> Write an Int32 in native host order and host endianness.
°5uFor portability issues see <tt>putInthost</tt>.
putInt32host :: Int32 -> Put

-- | <i>O(1).</i> Write an Int64 in native host order On a 32 bit machine
°5uwe write two host order Int32s, in big endian form. For portability
°5uissues see <tt>putInthost</tt>.
putInt64host :: Int64 -> Put

-- | Write a <a>Float</a> in native in IEEE-754 format and host endian.
putFloathost :: Float -> Put

-- | Write a <a>Double</a> in native in IEEE-754 format and host endian.
putDoublehost :: Double -> Put

-- | Write a character using UTF-8 encoding.
putCharUtf8 :: Char -> Put

-- | Write a String using UTF-8 encoding.
putStringUtf8 :: String -> Put
instance GHC.Base.Functor Data.Binary.Put.PutM
instance GHC.Base.Applicative Data.Binary.Put.PutM
instance GHC.Base.Monad Data.Binary.Put.PutM
instance GHC.Base.Monoid (Data.Binary.Put.PutM ())
instance GHC.Base.Semigroup (Data.Binary.Put.PutM ())


-- | Binary serialisation of Haskell values to and from lazy
°5u<a>ByteString</a>s. The Binary library provides methods for encoding
°5uHaskell values as streams of bytes directly in memory. The resulting
°5u<a>ByteString</a> can then be written to disk, sent over the network,
°5uor further processed (for example, compressed with gzip).
°5u
°5uThe <tt>binary</tt> package is notable in that it provides both pure,
°5uand high performance serialisation.
°5u
°5uValues encoded using the <a>Binary</a> class are always encoded in
°5unetwork order (big endian) form, and encoded data should be portable
°5uacross machine endianness, word size, or compiler version. For
°5uexample, data encoded using the <a>Binary</a> class could be written
°5uon any machine, and read back on any another.
°5u
°5uIf the specifics of the data format is not important to you, for
°5uexample, you are more interested in serializing and deserializing
°5uvalues than in which format will be used, it is possible to derive
°5u<a>Binary</a> instances using the generic support. See
°5u<a>GBinaryGet</a> and <a>GBinaryPut</a>.
°5u
°5uIf you have specific requirements about the encoding format, you can
°5uuse the encoding and decoding primitives directly, see the modules
°5u<a>Data.Binary.Get</a> and <a>Data.Binary.Put</a>.
module Data.Binary

-- | The <a>Binary</a> class provides <a>put</a> and <a>get</a>, methods to
°5uencode and decode a Haskell value to a lazy <a>ByteString</a>. It
°5umirrors the <a>Read</a> and <a>Show</a> classes for textual
°5urepresentation of Haskell types, and is suitable for serialising
°5uHaskell values to disk, over the network.
°5u
°5uFor decoding and generating simple external binary formats (e.g. C
°5ustructures), Binary may be used, but in general is not suitable for
°5ucomplex protocols. Instead use the <a>Put</a> and <a>Get</a>
°5uprimitives directly.
°5u
°5uInstances of Binary should satisfy the following property:
°5u
°5u<pre>
°5udecode . encode == id
°5u</pre>
°5u
°5uThat is, the <a>get</a> and <a>put</a> methods should be the inverse
°5uof each other. A range of instances are provided for basic Haskell
°5utypes.
class Binary t

-- | Encode a value in the Put monad.
put :: Binary t => t -> Put

-- | Decode a value in the Get monad
get :: Binary t => Get t

-- | Encode a list of values in the Put monad. The default implementation
°5umay be overridden to be more efficient but must still have the same
°5uencoding format.
putList :: Binary t => [t] -> Put

-- | Encode a value in the Put monad.
put :: (Binary t, Generic t, GBinaryPut (Rep t)) => t -> Put

-- | Decode a value in the Get monad
get :: (Binary t, Generic t, GBinaryGet (Rep t)) => Get t
class GBinaryGet f
gget :: GBinaryGet f => Get (f t)
class GBinaryPut f
gput :: GBinaryPut f => f t -> Put
data Get a

-- | Put merely lifts Builder into a Writer monad, applied to ().
type Put = PutM ()

-- | Efficiently write a byte into the output buffer
putWord8 :: Word8 -> Put

-- | Read a Word8 from the monad state
getWord8 :: Get Word8

-- | Encode a value using binary serialisation to a lazy ByteString.
encode :: Binary a => a -> ByteString

-- | Decode a value from a lazy ByteString, reconstructing the original
°5ustructure.
decode :: Binary a => ByteString -> a

-- | Decode a value from a lazy ByteString. Returning <a>Left</a> on
°5ufailure and <a>Right</a> on success. In both cases the unconsumed
°5uinput and the number of consumed bytes is returned. In case of
°5ufailure, a human-readable error message will be returned as well.
°5u
°5u<i>Since: 0.7.0.0</i>
decodeOrFail :: Binary a => ByteString -> Either (ByteString, ByteOffset, String) (ByteString, ByteOffset, a)

-- | Lazily serialise a value to a file.
°5u
°5uThis is just a convenience function, it's defined simply as:
°5u
°5u<pre>
°5uencodeFile f = B.writeFile f . encode
°5u</pre>
°5u
°5uSo for example if you wanted to compress as well, you could use:
°5u
°5u<pre>
°5uB.writeFile f . compress . encode
°5u</pre>
encodeFile :: Binary a => FilePath -> a -> IO ()

-- | Decode a value from a file. In case of errors, <a>error</a> will be
°5ucalled with the error message.
°5u
°5u<i>Since: 0.7.0.0</i>
decodeFile :: Binary a => FilePath -> IO a

-- | Decode a value from a file. In case of success, the value will be
°5ureturned in <a>Right</a>. In case of decoder errors, the error message
°5utogether with the byte offset will be returned.
decodeFileOrFail :: Binary a => FilePath -> IO (Either (ByteOffset, String) a)
