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


-- | Binary serialisation for Haskell values using lazy ByteStrings
--   
--   Efficient, pure binary serialisation using lazy ByteStrings. Haskell
--   values may be encoded to and from binary formats, written to disk as
--   binary, or sent over the network. Serialisation speeds of over 1 G/sec
--   have been observed, so this library should be suitable for high
--   performance scenarios.
@package binary
@version 0.6.1.0


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

-- | Ensure that <tt>n</tt> bytes are available, and then use <tt>f</tt> to
--   write exactly <tt>n</tt> bytes into memory.
writeN :: Int -> (Ptr Word8 -> IO ()) -> Builder

-- | Ensure that <tt>n</tt> bytes are available, and then use <tt>f</tt> to
--   write at most <tt>n</tt> bytes into memory. <tt>f</tt> must return the
--   actual number of bytes written.
writeAtMost :: Int -> (Ptr Word8 -> IO Int) -> Builder

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

-- | 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
--   was not provided enough input.
Fail :: !ByteString -> String -> Decoder a

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

-- | The decoder needs to know the current position in the input. Given the
--   number of bytes remaning in the decoder, the outer decoder runner
--   needs 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
--   providing 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
--   available the computation will escape with <a>Partial</a>.
readN :: Int -> (ByteString -> a) -> Get a
readNWith :: Int -> (Ptr a -> IO a) -> Get a

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

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

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

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

-- | Demand more input. If none available, fail.
demandInput :: Get ()

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

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

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

-- | An efficient get method for strict ByteStrings. Fails if fewer than
--   <tt>n</tt> bytes are left in the input. If <tt>n &lt;= 0</tt> then the
--   empty string is returned.
getByteString :: Int -> Get ByteString
instance Alternative Get
instance Show a => Show (Decoder a)
instance Functor Decoder
instance Functor Get
instance Applicative Get
instance Monad Get


-- | Efficient construction of lazy bytestrings.
module Data.Binary.Builder

-- | A <a>Builder</a> is an efficient way to build lazy <a>ByteString</a>s.
--   There are several functions for constructing <a>Builder</a>s, but only
--   one to inspect them: to extract any data, you have to turn them into
--   lazy <a>ByteString</a>s using <a>toLazyByteString</a>.
--   
--   Internally, a <a>Builder</a> constructs a lazy <a>Bytestring</a> by
--   filling byte arrays piece by piece. As each buffer is filled, it is
--   'popped' off, to become a new chunk of the resulting lazy
--   <a>ByteString</a>. All this is hidden from the user of the
--   <a>Builder</a>.
data Builder

-- | <i>O(n).</i> Extract a lazy <a>ByteString</a> from a <a>Builder</a>.
--   The construction work takes place if and when the relevant part of the
--   lazy <a>ByteString</a> is demanded.
toLazyByteString :: Builder -> ByteString

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

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

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

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

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

-- | <i>O(1).</i> Pop the <a>ByteString</a> we have constructed so far, if
--   any, yielding a new chunk in the result lazy <a>ByteString</a>.
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 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

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

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

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

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

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


-- | The Get monad. A monad for efficiently building structures from
--   encoded lazy ByteStrings.
module Data.Binary.Get
data Get a

-- | The simplest interface to run a <a>Get</a> decoder. If the decoder
--   runs into an error, calling <a>fail</a> or running out of input, it
--   will call <a>error</a>.
runGet :: Get a -> ByteString -> a

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

-- | <i>Deprecated: Use runGetPartial instead. This function will be
--   removed.</i>
runGetState :: Get a -> ByteString -> Int64 -> (a, ByteString, 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
--   was not provided enough input.
Fail :: !ByteString -> {-# UNPACK #-} !Int64 -> String -> Decoder a

-- | The decoder has consumed the available input and needs more to
--   continue. Provide <a>Just</a> if more input is available and
--   <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
--   also get the unused input as well as the count of used bytes.
Done :: !ByteString -> {-# UNPACK #-} !Int64 -> a -> Decoder a

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

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

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

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

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

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

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

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

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

-- | Get the remaining bytes as a lazy ByteString. Note that this can be an
--   expensive function to use as it forces reading all input and keeping
--   the 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
--   host order, host endian form, for the machine you're on. On a 64 bit
--   machine 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
--   endianness.
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

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

-- | DEPRECATED. Same as <a>getByteString</a>.
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
--   chunk in the result ByteString.
flush :: Put

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

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

-- | Write a lazy ByteString efficiently, simply appending the lazy
--   ByteString chunks to the output buffer
putLazyByteString :: ByteString -> 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 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

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

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

-- | <i>O(1).</i> Write a Word32 in native host order and host endianness.
--   For 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
--   we write two host order Word32s, in big endian form. For portability
--   issues see <tt>putWordhost</tt>.
putWord64host :: Word64 -> Put
instance Monad PutM
instance Applicative PutM
instance Functor PutM


-- | Binary serialisation of Haskell values to and from lazy ByteStrings.
--   The Binary library provides methods for encoding Haskell values as
--   streams of bytes directly in memory. The resulting <tt>ByteString</tt>
--   can then be written to disk, sent over the network, or futher
--   processed (for example, compressed with gzip).
--   
--   The <a>Binary</a> package is notable in that it provides both pure,
--   and high performance serialisation.
--   
--   Values are always encoded in network order (big endian) form, and
--   encoded data should be portable across machine endianess, word size,
--   or compiler version. For example, data encoded using the Binary class
--   could be written from GHC, and read back in Hugs.
module Data.Binary

-- | The <tt>Binary</tt> class provides <a>put</a> and <a>get</a>, methods
--   to encode and decode a Haskell value to a lazy ByteString. It mirrors
--   the Read and Show classes for textual representation of Haskell types,
--   and is suitable for serialising Haskell values to disk, over the
--   network.
--   
--   For decoding and generating simple external binary formats (e.g. C
--   structures), Binary may be used, but in general is not suitable for
--   complex protocols. Instead use the Put and Get primitives directly.
--   
--   Instances of Binary should satisfy the following property:
--   
--   <pre>
--   decode . encode == id
--   </pre>
--   
--   That is, the <a>get</a> and <a>put</a> methods should be the inverse
--   of each other. A range of instances are provided for basic Haskell
--   types.
class Binary t
put :: Binary t => t -> Put
get :: Binary t => Get t
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
--   structure.
decode :: Binary a => ByteString -> a

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

-- | Lazily reconstruct a value previously written to a file.
--   
--   This is just a convenience function, it's defined simply as:
--   
--   <pre>
--   decodeFile f = return . decode =&lt;&lt; B.readFile f
--   </pre>
--   
--   So for example if you wanted to decompress as well, you could use:
--   
--   <pre>
--   return . decode . decompress =&lt;&lt; B.readFile f
--   </pre>
--   
--   After contructing the data from the input file, <a>decodeFile</a>
--   checks if the file is empty, and in doing so will force the associated
--   file handle closed, if it is indeed empty. If the file is not empty,
--   it is up to the decoding instance to consume the rest of the data, or
--   otherwise finalise the resource.
decodeFile :: Binary a => FilePath -> IO a
instance (Binary i, Ix i, Binary e, IArray UArray e) => Binary (UArray i e)
instance (Binary i, Ix i, Binary e) => Binary (Array i e)
instance Binary e => Binary (Tree e)
instance Binary Float
instance Binary Double
instance Binary e => Binary (Seq e)
instance Binary e => Binary (IntMap e)
instance Binary IntSet
instance (Ord k, Binary k, Binary e) => Binary (Map k e)
instance (Ord a, Binary a) => Binary (Set a)
instance Binary ByteString
instance Binary ByteString
instance (Binary a, Binary b) => Binary (Either a b)
instance Binary a => Binary (Maybe a)
instance Binary a => Binary [a]
instance (Binary a, Binary b, Binary c, Binary d, Binary e, Binary f, Binary g, Binary h, Binary i, Binary j) => Binary (a, b, c, d, e, f, g, h, i, j)
instance (Binary a, Binary b, Binary c, Binary d, Binary e, Binary f, Binary g, Binary h, Binary i) => Binary (a, b, c, d, e, f, g, h, i)
instance (Binary a, Binary b, Binary c, Binary d, Binary e, Binary f, Binary g, Binary h) => Binary (a, b, c, d, e, f, g, h)
instance (Binary a, Binary b, Binary c, Binary d, Binary e, Binary f, Binary g) => Binary (a, b, c, d, e, f, g)
instance (Binary a, Binary b, Binary c, Binary d, Binary e, Binary f) => Binary (a, b, c, d, e, f)
instance (Binary a, Binary b, Binary c, Binary d, Binary e) => Binary (a, b, c, d, e)
instance (Binary a, Binary b, Binary c, Binary d) => Binary (a, b, c, d)
instance (Binary a, Binary b, Binary c) => Binary (a, b, c)
instance (Binary a, Binary b) => Binary (a, b)
instance Binary Char
instance (Binary a, Integral a) => Binary (Ratio a)
instance Binary Integer
instance Binary Int
instance Binary Word
instance Binary Int64
instance Binary Int32
instance Binary Int16
instance Binary Int8
instance Binary Word64
instance Binary Word32
instance Binary Word16
instance Binary Word8
instance Binary Ordering
instance Binary Bool
instance Binary ()