-- 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.5.0.1


-- | 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 <tt>L.Bytestring</tt>
--   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
instance Monoid Builder


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

-- | The Get monad is just a State monad carrying around the input
--   ByteString We treat it as a strict state monad.
data Get a

-- | Run the Get monad applies a <a>get</a>-based parser on the input
--   ByteString
runGet :: Get a -> ByteString -> a

-- | Run the Get monad applies a <a>get</a>-based parser on the input
--   ByteString. Additional to the result of get it returns the number of
--   consumed bytes and the rest of the input.
runGetState :: Get a -> ByteString -> Int64 -> (a, ByteString, Int64)

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

-- | Skip ahead <tt>n</tt> bytes. No error if there isn't enough bytes.
uncheckedSkip :: Int64 -> Get ()

-- | Run <tt>ga</tt>, but return without consuming its input. Fails if
--   <tt>ga</tt> fails.
lookAhead :: Get a -> Get a

-- | Like <a>lookAhead</a>, but consume the input if <tt>gma</tt> returns
--   'Just _'. Fails if <tt>gma</tt> fails.
lookAheadM :: Get (Maybe a) -> Get (Maybe a)

-- | Like <a>lookAhead</a>, but consume the input if <tt>gea</tt> returns
--   'Right _'. Fails if <tt>gea</tt> fails.
lookAheadE :: Get (Either a b) -> Get (Either a b)

-- | Get the next up to <tt>n</tt> bytes as a lazy ByteString, without
--   consuming them.
uncheckedLookAhead :: Int64 -> Get ByteString

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

-- | Pull <tt>n</tt> bytes from the input, as a strict ByteString.
--   
--   important
getBytes :: Int -> Get ByteString

-- | Get the number of remaining unparsed bytes. Useful for checking
--   whether all input has been consumed. Note that this forces the rest of
--   the input.
remaining :: Get Int64

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

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

-- | An efficient <a>get</a> method for strict ByteStrings. Fails if fewer
--   than <tt>n</tt> bytes are left in the input.
getByteString :: Int -> Get ByteString

-- | An efficient <a>get</a> method for lazy ByteStrings. Does not fail 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. Fails if it
--   reaches the end of input without hitting a NUL.
getLazyByteStringNul :: Get ByteString

-- | Get the remaining bytes as a lazy ByteString
getRemainingLazyByteString :: Get ByteString

-- | 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
instance MonadFix Get
instance Monad Get
instance Applicative Get
instance Functor Get


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

-- | The Get monad is just a State monad carrying around the input
--   ByteString We treat it as a strict state monad.
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 ()