Data.Binary

binary-0.8.2.0: Binary serialisation for Haskell values using lazy ByteStrings

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

- The Binary class
  - Example
- Generic support
- The Get and Put monads
- Useful helpers for writing instances
- Binary serialisation
- IO functions for serialisation

Description

Binary serialisation of Haskell values to and from lazy `ByteString`s. 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.

Synopsis

- 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

class Binary t where Source

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

put :: t -> Put Source

Encode a value in the Put monad.

get :: Get t Source

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

Binary Bool |
Methods put :: Bool -> Put Source get :: Get Bool Source
Binary Char |
Methods put :: Char -> Put Source get :: Get Char Source
Binary Double |
Methods put :: Double -> Put Source get :: Get Double Source
Binary Float |
Methods put :: Float -> Put Source get :: Get Float Source
Binary Int |
Methods put :: Int -> Put Source get :: Get Int Source
Binary Int8 |
Methods put :: Int8 -> Put Source get :: Get Int8 Source
Binary Int16 |
Methods put :: Int16 -> Put Source get :: Get Int16 Source
Binary Int32 |
Methods put :: Int32 -> Put Source get :: Get Int32 Source
Binary Int64 |
Methods put :: Int64 -> Put Source get :: Get Int64 Source
Binary Integer |
Methods put :: Integer -> Put Source get :: Get Integer Source
Binary Ordering |
Methods put :: Ordering -> Put Source get :: Get Ordering Source
Binary Word |
Methods put :: Word -> Put Source get :: Get Word Source
Binary Word8 |
Methods put :: Word8 -> Put Source get :: Get Word8 Source
Binary Word16 |
Methods put :: Word16 -> Put Source get :: Get Word16 Source
Binary Word32 |
Methods put :: Word32 -> Put Source get :: Get Word32 Source
Binary Word64 |
Methods put :: Word64 -> Put Source get :: Get Word64 Source
Binary () |
Methods put :: () -> Put Source get :: Get () Source
Binary Void | Since: 0.8.0.0
Methods put :: Void -> Put Source get :: Get Void Source
Binary Natural | Since: 0.7.3.0
Methods put :: Natural -> Put Source get :: Get Natural Source
Binary Version | Since: 0.8.0.0
Methods put :: Version -> Put Source get :: Get Version Source
Binary Fingerprint | Since: 0.7.6.0
Methods put :: Fingerprint -> Put Source get :: Get Fingerprint Source
Binary ByteString |
Methods put :: ByteString -> Put Source get :: Get ByteString Source
Binary ShortByteString |
Methods put :: ShortByteString -> Put Source get :: Get ShortByteString Source
Binary ByteString |
Methods put :: ByteString -> Put Source get :: Get ByteString Source
Binary IntSet |
Methods put :: IntSet -> Put Source get :: Get IntSet Source
Binary a => Binary [a] |
Methods put :: [a] -> Put Source get :: Get [a] Source
Binary a => Binary (Maybe a) |
Methods put :: Maybe a -> Put Source get :: Get (Maybe a) Source
(Binary a, Integral a) => Binary (Ratio a) |
Methods put :: Ratio a -> Put Source get :: Get (Ratio a) Source
Binary (Fixed a) | Since: 0.8.0.0
Methods put :: Fixed a -> Put Source get :: Get (Fixed a) Source
Binary e => Binary (IntMap e) |
Methods put :: IntMap e -> Put Source get :: Get (IntMap e) Source
Binary a => Binary (Set a) |
Methods put :: Set a -> Put Source get :: Get (Set a) Source
Binary e => Binary (Tree e) |
Methods put :: Tree e -> Put Source get :: Get (Tree e) Source
Binary e => Binary (Seq e) |
Methods put :: Seq e -> Put Source get :: Get (Seq e) Source
(Binary a, Binary b) => Binary (Either a b) |
Methods put :: Either a b -> Put Source get :: Get (Either a b) Source
(Binary a, Binary b) => Binary (a, b) |
Methods put :: (a, b) -> Put Source get :: Get (a, b) Source
(Binary i, Ix i, Binary e, IArray UArray e) => Binary (UArray i e) |
Methods put :: UArray i e -> Put Source get :: Get (UArray i e) Source
(Binary i, Ix i, Binary e) => Binary (Array i e) |
Methods put :: Array i e -> Put Source get :: Get (Array i e) Source
(Binary k, Binary e) => Binary (Map k e) |
Methods put :: Map k e -> Put Source get :: Get (Map k e) Source
(Binary a, Binary b, Binary c) => Binary (a, b, c) |
Methods put :: (a, b, c) -> Put Source get :: Get (a, b, c) Source
(Binary a, Binary b, Binary c, Binary d) => Binary (a, b, c, d) |
Methods put :: (a, b, c, d) -> Put Source get :: Get (a, b, c, d) Source
(Binary a, Binary b, Binary c, Binary d, Binary e) => Binary (a, b, c, d, e) |
Methods put :: (a, b, c, d, e) -> Put Source get :: Get (a, b, c, d, e) Source
(Binary a, Binary b, Binary c, Binary d, Binary e, Binary f) => Binary (a, b, c, d, e, f) |
Methods put :: (a, b, c, d, e, f) -> Put Source get :: Get (a, b, c, d, e, f) Source
(Binary a, Binary b, Binary c, Binary d, Binary e, Binary f, Binary g) => Binary (a, b, c, d, e, f, g) |
Methods put :: (a, b, c, d, e, f, g) -> Put Source get :: Get (a, b, c, d, e, f, g) Source
(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) |
Methods put :: (a, b, c, d, e, f, g, h) -> Put Source get :: Get (a, b, c, d, e, f, g, h) Source
(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) |
Methods put :: (a, b, c, d, e, f, g, h, i) -> Put Source get :: Get (a, b, c, d, e, f, g, h, i) Source
(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) |
Methods put :: (a, b, c, d, e, f, g, h, i, j) -> Put Source get :: Get (a, b, c, d, e, f, g, h, i, j) Source

## Example

# Generic support

class GBinaryGet f where Source

Minimal complete definition

gget

Methods

gget :: Get (f t) Source

class GBinaryPut f where Source

Minimal complete definition

gput

Methods

gput :: f t -> Put Source

# The Get and Put monads

data Get a Source

Instances

Monad Get |
Methods (>>=) :: Get a -> (a -> Get b) -> Get b Source (>>) :: Get a -> Get b -> Get b Source return :: a -> Get a Source fail :: String -> Get a Source
Functor Get |
Methods fmap :: (a -> b) -> Get a -> Get b Source (<$) :: a -> Get b -> Get a Source
MonadFail Get |
Methods fail :: String -> Get a Source
Applicative Get |
Methods pure :: a -> Get a Source (<*>) :: Get (a -> b) -> Get a -> Get b Source (*>) :: Get a -> Get b -> Get b Source (<*) :: Get a -> Get b -> Get a Source
Alternative Get | Since: 0.7.0.0
Methods empty :: Get a Source (<|>) :: Get a -> Get a -> Get a Source some :: Get a -> Get [a] Source many :: Get a -> Get [a] Source
MonadPlus Get | Since: 0.7.1.0
Methods mzero :: Get a Source mplus :: Get a -> Get a -> Get a Source

type Put = PutM () Source

Put merely lifts Builder into a Writer monad, applied to ().

# Useful helpers for writing instances

putWord8 :: Word8 -> Put Source

Efficiently write a byte into the output buffer

getWord8 :: Get Word8 Source

Read a Word8 from the monad state

# 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

Decode a value from a lazy ByteString. Returning `Left` on failure and `Right` on success. In both cases the unconsumed input and the number of consumed bytes is returned. In case of failure, a human-readable error message will be returned as well.

Since: 0.7.0.0

# 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