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


-- | Binary serialisation for Haskell values using lazy ByteStrings
gr
grEfficient, pure binary serialisation using lazy ByteStrings. Haskell
grvalues may be encoded to and from binary formats, written to disk as
grbinary, or sent over the network. The format used can be automatically
grgenerated, or you can choose to implement a custom format if needed.
grSerialisation speeds of over 1 G/sec have been observed, so this
grlibrary should be suitable for high performance scenarios.
@package binary
@version 0.8.5.1


-- | Efficient constructions of lazy bytestrings.
gr
grThis now re-exports <a>Builder</a>.
module Data.Binary.Builder

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

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

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

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

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

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

-- | <i>O(1).</i> A Builder taking a lazy <a>ByteString</a>, satisfying
gr
gr<ul>
gr<li><pre><a>toLazyByteString</a> (<a>fromLazyByteString</a> bs) =
grbs</pre></li>
gr</ul>
fromLazyByteString :: ByteString -> Builder

-- | <i>O(n).</i> A builder taking <a>ShortByteString</a> and copy it to a
grBuilder, satisfying
gr
gr<ul>
gr<li>@<a>toLazyByteString</a> (<a>fromShortByteString</a> bs) =
gr<a>fromChunks</a> [<a>fromShort</a> bs]</li>
gr</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
gris written in host order, host endian form, for the machine you're on.
grOn a 64 bit machine the Word is an 8 byte value, on a 32 bit machine,
gr4 bytes. Values written this way are not portable to different endian
gror word sized machines, without conversion.
putWordhost :: Word -> Builder

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

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

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

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

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

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

-- | Write a Int64 in native host order. On a 32 bit machine we write two
grhost order Int32s, in big endian form. 8 bytes will be written,
grunaligned.
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
grwas not provided enough input.
Fail :: !ByteString -> String -> Decoder a

-- | The decoder has consumed the available input and needs more to
grcontinue. Provide <a>Just</a> if more input is available and
gr<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
gralso get the unused input.
Done :: !ByteString -> a -> Decoder a

-- | The decoder needs to know the current position in the input. Given the
grnumber of bytes remaning in the decoder, the outer decoder runner
grneeds 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
grproviding 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
gravailable 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
grhave 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
grfewer bytes were consumed, or more bytes were attempted to be
grconsumed. If the given decoder fails, <a>isolate</a> will also fail.
grOffset from <a>bytesRead</a> will be relative to the start of
gr<a>isolate</a>, not the absolute of the input.
gr
gr<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
grcomputation will escape with <a>Partial</a>.
ensureN :: Int -> Get ()

-- | DEPRECATED. Get the number of bytes of remaining input. Note that this
gris an expensive function to use as in order to calculate how much
grinput remains, all input has to be read and kept in-memory. The
grdecoder keeps the input as a strict bytestring, so you are likely
grbetter 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
gr<a>getBytes</a>.</i>
getBytes :: Int -> Get ByteString

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

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

-- | Run the given decoder, and only consume its input if it returns
gr<a>Just</a>. If <a>Nothing</a> is returned, the input will be
grunconsumed. If the given decoder fails, then so will this function.
gr
gr<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
gr<a>Right</a>. If <a>Left</a> is returned, the input will be
grunconsumed. If the given decoder fails, then so will this function.
gr
gr<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
grnew line to the error message string.
gr
gr<i>Since: 0.7.2.0</i>
label :: String -> Get a -> Get a

-- | An efficient get method for strict ByteStrings. Fails if fewer than
gr<tt>n</tt> bytes are left in the input. If <tt>n &lt;= 0</tt> then the
grempty 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
grencoded lazy ByteStrings.
gr
grPrimitives are available to decode words of various sizes, both big
grand little endian.
gr
grLet's decode binary data representing illustrated here. In this
grexample the values are in little endian.
gr
gr<pre>
gr+------------------+--------------+-----------------+
gr| 32 bit timestamp | 32 bit price | 16 bit quantity |
gr+------------------+--------------+-----------------+
gr</pre>
gr
grA corresponding Haskell value looks like this:
gr
gr<pre>
grdata Trade = Trade
gr  { timestamp :: !<a>Word32</a>
gr  , price     :: !<a>Word32</a>
gr  , qty       :: !<a>Word16</a>
gr  } deriving (<a>Show</a>)
gr 
gr</pre>
gr
grThe fields in <tt>Trade</tt> are marked as strict (using <tt>!</tt>)
grsince we don't need laziness here. In practise, you would probably
grconsider using the UNPACK pragma as well.
gr<a>https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/glasgow_exts.html#unpack-pragma</a>
gr
grNow, let's have a look at a decoder for this format.
gr
gr<pre>
grgetTrade :: <a>Get</a> Trade
grgetTrade = do
gr  timestamp &lt;- <a>getWord32le</a>
gr  price     &lt;- <a>getWord32le</a>
gr  quantity  &lt;- <a>getWord16le</a>
gr  return <a>$!</a> Trade timestamp price quantity
gr 
gr</pre>
gr
grOr even simpler using applicative style:
gr
gr<pre>
grgetTrade' :: <a>Get</a> Trade
grgetTrade' = Trade <a>&lt;$&gt;</a> <a>getWord32le</a> <a>&lt;*&gt;</a> <a>getWord32le</a> <a>&lt;*&gt;</a> <a>getWord16le</a>
gr 
gr</pre>
gr
grThere are two kinds of ways to execute this decoder, the lazy input
grmethod and the incremental input method. Here we will use the lazy
grinput method.
gr
grLet's first define a function that decodes many <tt>Trade</tt>s.
gr
gr<pre>
grgetTrades :: Get [Trade]
grgetTrades = do
gr  empty &lt;- <a>isEmpty</a>
gr  if empty
gr    then return []
gr    else do trade &lt;- getTrade
gr            trades &lt;- getTrades
gr            return (trade:trades)
gr 
gr</pre>
gr
grFinally, we run the decoder:
gr
gr<pre>
grlazyIOExample :: IO [Trade]
grlazyIOExample = do
gr  input &lt;- BL.readFile "trades.bin"
gr  return (<a>runGet</a> getTrades input)
gr 
gr</pre>
gr
grThis decoder has the downside that it will need to read all the input
grbefore it can return. On the other hand, it will not return anything
gruntil it knows it could decode without any decoder errors.
gr
grYou could also refactor to a left-fold, to decode in a more streaming
grfashion, and get the following decoder. It will start to return data
grwithout knowing that it can decode all input.
gr
gr<pre>
grincrementalExample :: BL.ByteString -&gt; [Trade]
grincrementalExample input0 = go decoder input0
gr  where
gr    decoder = <a>runGetIncremental</a> getTrade
gr    go :: <a>Decoder</a> Trade -&gt; BL.ByteString -&gt; [Trade]
gr    go (<a>Done</a> leftover _consumed trade) input =
gr      trade : go decoder (BL.chunk leftover input)
gr    go (<a>Partial</a> k) input                     =
gr      go (k . takeHeadChunk $ input) (dropHeadChunk input)
gr    go (<a>Fail</a> _leftover _consumed msg) _input =
gr      error msg
gr
grtakeHeadChunk :: BL.ByteString -&gt; Maybe BS.ByteString
grtakeHeadChunk lbs =
gr  case lbs of
gr    (BL.Chunk bs _) -&gt; Just bs
gr    _ -&gt; Nothing
gr
grdropHeadChunk :: BL.ByteString -&gt; BL.ByteString
grdropHeadChunk lbs =
gr  case lbs of
gr    (BL.Chunk _ lbs') -&gt; lbs'
gr    _ -&gt; BL.Empty
gr 
gr</pre>
gr
grThe <tt>lazyIOExample</tt> uses lazy I/O to read the file from the
grdisk, which is not suitable in all applications, and certainly not if
gryou need to read from a socket which has higher likelihood to fail. To
graddress these needs, use the incremental input method like in
gr<tt>incrementalExample</tt>. For an example of how to read
grincrementally from a Handle, see the implementation of
gr<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
grruns into an error, calls <a>fail</a>, or runs out of input, it will
grcall <a>error</a>.
runGet :: Get a -> ByteString -> a

-- | Run a <a>Get</a> monad and return <a>Left</a> on failure and
gr<a>Right</a> on success. In both cases any unconsumed input and the
grnumber of bytes consumed is returned. In the case of failure, a
grhuman-readable error message is included as well.
gr
gr<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
grwas not provided enough input. Contains any unconsumed input and the
grnumber of bytes consumed.
Fail :: !ByteString -> {-# UNPACK #-} !ByteOffset -> String -> Decoder a

-- | The decoder has consumed the available input and needs more to
grcontinue. Provide <a>Just</a> if more input is available and
gr<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
gralso 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
grproviding input, handling decoder errors and to get the output value.
grHint: Use the helper functions <a>pushChunk</a>, <a>pushChunks</a> and
gr<a>pushEndOfInput</a>.
runGetIncremental :: Get a -> Decoder a

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

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

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

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

-- | Test whether all input has been consumed, i.e. there are no remaining
grundecoded 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
grfewer bytes were consumed, or more bytes were attempted to be
grconsumed. If the given decoder fails, <a>isolate</a> will also fail.
grOffset from <a>bytesRead</a> will be relative to the start of
gr<a>isolate</a>, not the absolute of the input.
gr
gr<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
grdecoder fails, then so will this function.
gr
gr<i>Since: 0.7.0.0</i>
lookAhead :: Get a -> Get a

-- | Run the given decoder, and only consume its input if it returns
gr<a>Just</a>. If <a>Nothing</a> is returned, the input will be
grunconsumed. If the given decoder fails, then so will this function.
gr
gr<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
gr<a>Right</a>. If <a>Left</a> is returned, the input will be
grunconsumed. If the given decoder fails, then so will this function.
gr
gr<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
grnew line to the error message string.
gr
gr<i>Since: 0.7.2.0</i>
label :: String -> Get a -> Get a

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

-- | An efficient get method for lazy ByteStrings. Fails if fewer than
gr<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
grstring does not contain the NUL byte. Fails if it reaches the end of
grinput without finding a NUL.
getLazyByteStringNul :: Get ByteString

-- | Get the remaining bytes as a lazy ByteString. Note that this can be an
grexpensive function to use as it forces reading all input and keeping
grthe 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
grhost order, host endian form, for the machine you're on. On a 64 bit
grmachine 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
grendianness.
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.
grIt 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
grendianness.
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
grlibrary. Run a <a>Get</a> monad and return a tuple with three values.
grThe first value is the result of the decoder. The second and third are
grthe unused input, and the number of consumed bytes.

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

-- | DEPRECATED. Get the number of bytes of remaining input. Note that this
gris an expensive function to use as in order to calculate how much
grinput remains, all input has to be read and kept in-memory. The
grdecoder keeps the input as a strict bytestring, so you are likely
grbetter 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
gr<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
grchunk 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
grbuffer. It flushes the current buffer, and writes the argument into a
grnew chunk.
putByteString :: ByteString -> Put

-- | Write a lazy ByteString efficiently, simply appending the lazy
grByteString 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
grin host order, host endian form, for the machine you're on. On a 64
grbit machine the Word is an 8 byte value, on a 32 bit machine, 4 bytes.
grValues written this way are not portable to different endian or word
grsized machines, without conversion.
putWordhost :: Word -> Put

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

-- | <i>O(1).</i> Write a Word32 in native host order and host endianness.
grFor 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
grwe write two host order Word32s, in big endian form. For portability
grissues see <tt>putWordhost</tt>.
putWord64host :: Word64 -> Put

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

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

-- | <i>O(1).</i> Write an Int32 in native host order and host endianness.
grFor 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
grwe write two host order Int32s, in big endian form. For portability
grissues 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
gr<a>ByteString</a>s. The Binary library provides methods for encoding
grHaskell values as streams of bytes directly in memory. The resulting
gr<a>ByteString</a> can then be written to disk, sent over the network,
gror further processed (for example, compressed with gzip).
gr
grThe <tt>binary</tt> package is notable in that it provides both pure,
grand high performance serialisation.
gr
grValues encoded using the <a>Binary</a> class are always encoded in
grnetwork order (big endian) form, and encoded data should be portable
gracross machine endianness, word size, or compiler version. For
grexample, data encoded using the <a>Binary</a> class could be written
gron any machine, and read back on any another.
gr
grIf the specifics of the data format is not important to you, for
grexample, you are more interested in serializing and deserializing
grvalues than in which format will be used, it is possible to derive
gr<a>Binary</a> instances using the generic support. See
gr<a>GBinaryGet</a> and <a>GBinaryPut</a>.
gr
grIf you have specific requirements about the encoding format, you can
gruse the encoding and decoding primitives directly, see the modules
gr<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
grencode and decode a Haskell value to a lazy <a>ByteString</a>. It
grmirrors the <a>Read</a> and <a>Show</a> classes for textual
grrepresentation of Haskell types, and is suitable for serialising
grHaskell values to disk, over the network.
gr
grFor decoding and generating simple external binary formats (e.g. C
grstructures), Binary may be used, but in general is not suitable for
grcomplex protocols. Instead use the <a>Put</a> and <a>Get</a>
grprimitives directly.
gr
grInstances of Binary should satisfy the following property:
gr
gr<pre>
grdecode . encode == id
gr</pre>
gr
grThat is, the <a>get</a> and <a>put</a> methods should be the inverse
grof each other. A range of instances are provided for basic Haskell
grtypes.
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
grmay be overridden to be more efficient but must still have the same
grencoding 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
grstructure.
decode :: Binary a => ByteString -> a

-- | Decode a value from a lazy ByteString. Returning <a>Left</a> on
grfailure and <a>Right</a> on success. In both cases the unconsumed
grinput and the number of consumed bytes is returned. In case of
grfailure, a human-readable error message will be returned as well.
gr
gr<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.
gr
grThis is just a convenience function, it's defined simply as:
gr
gr<pre>
grencodeFile f = B.writeFile f . encode
gr</pre>
gr
grSo for example if you wanted to compress as well, you could use:
gr
gr<pre>
grB.writeFile f . compress . encode
gr</pre>
encodeFile :: Binary a => FilePath -> a -> IO ()

-- | Decode a value from a file. In case of errors, <a>error</a> will be
grcalled with the error message.
gr
gr<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
grreturned in <a>Right</a>. In case of decoder errors, the error message
grtogether with the byte offset will be returned.
decodeFileOrFail :: Binary a => FilePath -> IO (Either (ByteOffset, String) a)
