| Copyright | Lennart Kolmodin |
|---|---|
| License | BSD3-style (see LICENSE) |
| Maintainer | Lennart Kolmodin <kolmodin@gmail.com> |
| Stability | unstable |
| Portability | portable to Hugs and GHC. Requires the FFI and some flexible instances. |
| Safe Haskell | Trustworthy |
| Language | Haskell98 |
Data.Binary
Contents
Description
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 ByteString can
then be written to disk, sent over the network, or further processed
(for example, compressed with gzip).
The binary package is notable in that it provides both pure, and
high performance serialisation.
Values encoded using the Binary class are always encoded in network order
(big endian) form, and encoded data should be portable across
machine endianness, word size, or compiler version. For example,
data encoded using the Binary class could be written on any machine,
and read back on any another.
If the specifics of the data format is not important to you, for example,
you are more interested in serializing and deserializing values than
in which format will be used, it is possible to derive Binary
instances using the generic support. See GBinaryGet and
GBinaryPut.
If you have specific requirements about the encoding format, you can use the encoding and decoding primitives directly, see the modules Data.Binary.Get and Data.Binary.Put.
- class Binary t where
- class GBinaryGet f where
- class GBinaryPut f where
- data Get a
- type Put = PutM ()
- putWord8 :: Word8 -> Put
- getWord8 :: Get Word8
- encode :: Binary a => a -> ByteString
- decode :: Binary a => ByteString -> a
- decodeOrFail :: Binary a => ByteString -> Either (ByteString, ByteOffset, String) (ByteString, ByteOffset, a)
- encodeFile :: Binary a => FilePath -> a -> IO ()
- decodeFile :: Binary a => FilePath -> IO a
- decodeFileOrFail :: Binary a => FilePath -> IO (Either (ByteOffset, String) a)
- module Data.Word
The Binary class
The Binary class provides put and get, 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:
decode . encode == id
That is, the get and put methods should be the inverse of each
other. A range of instances are provided for basic Haskell types.
Methods
Encode a value in the Put monad.
Decode a value in the Get monad
put :: (Generic t, GBinaryPut (Rep t)) => t -> Put Source
Encode a value in the Put monad.
get :: (Generic t, GBinaryGet (Rep t)) => Get t Source
Decode a value in the Get monad
Instances
Example
Generic support
The Get and Put monads
Useful helpers for writing instances
Binary serialisation
encode :: Binary a => a -> ByteString Source
Encode a value using binary serialisation to a lazy ByteString.
decode :: Binary a => ByteString -> a Source
Decode a value from a lazy ByteString, reconstructing the original structure.
decodeOrFail :: Binary a => ByteString -> Either (ByteString, ByteOffset, String) (ByteString, ByteOffset, a) Source
IO functions for serialisation
encodeFile :: Binary a => FilePath -> a -> IO () Source
Lazily serialise a value to a file.
This is just a convenience function, it's defined simply as:
encodeFile f = B.writeFile f . encode
So for example if you wanted to compress as well, you could use:
B.writeFile f . compress . encode
decodeFile :: Binary a => FilePath -> IO a Source
Decode a value from a file. In case of errors, error will
be called with the error message.
Since: 0.7.0.0
decodeFileOrFail :: Binary a => FilePath -> IO (Either (ByteOffset, String) a) Source
Decode a value from a file. In case of success, the value will be returned
in Right. In case of decoder errors, the error message together with
the byte offset will be returned.
module Data.Word