-- 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)
