HORIZON HASKELLDocslts/ghc-9.10.xc74966e2026-09-27Search names, modules, packages, or :: a typeCtrl K

GHC 9.10.3 · lts/ghc-9.10.x · c74966e · 2026-09-27

Modulebinary-0.8.9.3Haskell2010

Data.Binary

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.

  • 7 types
  • 3 classes
  • 15 values
  • Packagebinary-0.8.9.3
  • Exports25
  • LanguageHaskell2010
  • LicenceBSD-3-Clause
  • SourceBinary.hs

The Binary class

1 declaration
classclass Binary t where
#

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

    Encode a value in the Put monad.

  • get :: Get t

    Decode a value in the Get monad

  • putList :: [t] -> Put

    Encode a list of values in the Put monad. The default implementation may be overridden to be more efficient but must still have the same encoding format.

Instances71Binary, …

Example

To serialise a custom type, an instance of Binary for that type is required. For example, suppose we have a data structure:

data Exp = IntE Int
         | OpE  String Exp Exp
   deriving Show

We can encode values of this type into bytestrings using the following instance, which proceeds by recursively breaking down the structure to serialise:

instance Binary Exp where
      put (IntE i)      = do put (0 :: Word8)
                             put i
      put (OpE s e1 e2) = do put (1 :: Word8)
                             put s
                             put e1
                             put e2

      get = do t <- get :: Get Word8
               case t of
                    0 -> do i <- get
                            return (IntE i)
                    1 -> do s  <- get
                            e1 <- get
                            e2 <- get
                            return (OpE s e1 e2)

Note how we write an initial tag byte to indicate each variant of the data type.

We can simplify the writing of get instances using monadic combinators:

      get = do tag <- getWord8
               case tag of
                   0 -> liftM  IntE get
                   1 -> liftM3 OpE  get get get

To serialise this to a bytestring, we use encode, which packs the data structure into a binary format, in a lazy bytestring

> let e = OpE "*" (IntE 7) (OpE "/" (IntE 4) (IntE 2))
> let v = encode e

Where v is a binary encoded data structure. To reconstruct the original data, we use decode

> decode v :: Exp
OpE "*" (IntE 7) (OpE "/" (IntE 4) (IntE 2))

The lazy ByteString that results from encode can be written to disk, and read from disk using Data.ByteString.Lazy IO functions, such as hPutStr or writeFile:

> writeFile "/tmp/exp.txt" (encode e)

And read back with:

> readFile "/tmp/exp.txt" >>= return . decode :: IO Exp
OpE "*" (IntE 7) (OpE "/" (IntE 4) (IntE 2))

We can also directly serialise a value to and from a Handle, or a file:

> v <- decodeFile  "/tmp/exp.txt" :: IO Exp
OpE "*" (IntE 7) (OpE "/" (IntE 4) (IntE 2))

And write a value to disk

> encodeFile "/tmp/a.txt" v

Generic support

2 declarations

Beginning with GHC 7.2, it is possible to use binary serialization without writing any instance boilerplate code.

{-# LANGUAGE DeriveGeneric #-}

import Data.Binary
import GHC.Generics (Generic)

data Foo = Foo
         deriving (Generic)

-- GHC will automatically fill out the instance
instance Binary Foo

This mechanism makes use of GHC's efficient built-in generics support.

classclass GBinaryGet (f :: k -> Type) where
#

Methods

Instances6GBinaryGet
  • GBinaryGet U1Defined in binary-0.8.9.3 · Data.Binary.Generic · orphan
  • GBinaryGet V1Defined in binary-0.8.9.3 · Data.Binary.Generic · orphan
  • Binary a => GBinaryGet (K1 i a)Defined in binary-0.8.9.3 · Data.Binary.Generic · orphan
  • (GBinaryGet a, GBinaryGet b) => GBinaryGet (a :*: b)Defined in binary-0.8.9.3 · Data.Binary.Generic · orphan
  • (GSumGet a, GSumGet b, SumSize a, SumSize b) => GBinaryGet (a :+: b)Defined in binary-0.8.9.3 · Data.Binary.Generic · orphan
  • GBinaryGet a => GBinaryGet (M1 i c a)Defined in binary-0.8.9.3 · Data.Binary.Generic · orphan
classclass GBinaryPut (f :: k -> Type) where
#

Methods

Instances6GBinaryPut
  • GBinaryPut U1Defined in binary-0.8.9.3 · Data.Binary.Generic · orphan
  • GBinaryPut V1Defined in binary-0.8.9.3 · Data.Binary.Generic · orphan
  • Binary a => GBinaryPut (K1 i a)Defined in binary-0.8.9.3 · Data.Binary.Generic · orphan
  • (GBinaryPut a, GBinaryPut b) => GBinaryPut (a :*: b)Defined in binary-0.8.9.3 · Data.Binary.Generic · orphan
  • (GSumPut a, GSumPut b, SumSize a, SumSize b) => GBinaryPut (a :+: b)Defined in binary-0.8.9.3 · Data.Binary.Generic · orphan
  • GBinaryPut a => GBinaryPut (M1 i c a)Defined in binary-0.8.9.3 · Data.Binary.Generic · orphan

The Get and Put monads

2 declarations
newtypenewtype Get a
#
Instances6Monad, Functor, MonadFail, Applicative, Alternative, MonadPlus
  • Monad GetDefined in binary-0.8.9.3 · Data.Binary.Get.Internal
  • Functor GetDefined in binary-0.8.9.3 · Data.Binary.Get.Internal
  • MonadFail GetDefined in binary-0.8.9.3 · Data.Binary.Get.Internal
  • Applicative GetDefined in binary-0.8.9.3 · Data.Binary.Get.Internal
  • Alternative GetDefined in binary-0.8.9.3 · Data.Binary.Get.Internal
  • MonadPlus GetDefined in binary-0.8.9.3 · Data.Binary.Get.Internal
typetype Put = PutM ()
#

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

Useful helpers for writing instances

2 declarations

Binary serialisation

3 declarations
valuedecode :: Binary a => ByteString -> a
#

Decode a value from a lazy ByteString, reconstructing the original structure.

IO functions for serialisation

15 declarations
valueencodeFile :: Binary a => FilePath -> a -> IO ()
#

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
datadata Word
#

A Word is an unsigned integral type, with the same size as Int.

Instances32Bounded, Enum, Integral, Data, Num, Read, …
datadata Word64
#

64-bit unsigned integer type

Instances22Bounded, Enum, Eq, Integral, Data, Num, …
  • Bounded Word64Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Enum Word64Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Eq Word64Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Integral Word64Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Data Word64Defined in ghc-internal-9.1003.0 · GHC.Internal.Data.Data
  • Num Word64Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Ord Word64Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Read Word64Defined in ghc-internal-9.1003.0 · GHC.Internal.Read
  • Real Word64Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Show Word64Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Ix Word64Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Bits Word64Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • FiniteBits Word64Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Storable Word64Defined in ghc-internal-9.1003.0 · GHC.Internal.Foreign.Storable
  • PrintfArg Word64Defined in base-4.20.2.0 · Text.Printf
  • NFData Word64Defined in deepseq-1.5.0.0 · Control.DeepSeq
  • Mantissa Word64Defined in bytestring-0.12.2.0 · Data.ByteString.Builder.RealFloat.Internal
  • Binary Word64Defined in binary-0.8.9.3 · Data.Binary.Class
  • Lift Word64Defined in template-haskell-2.22.0.0 · Language.Haskell.TH.Syntax
  • IArray UArray Word64Defined in array-0.5.8.0 · Data.Array.Base
  • MArray IOUArray Word64 IODefined in array-0.5.8.0 · Data.Array.IO.Internals
  • MArray (STUArray s) Word64 (ST s)Defined in array-0.5.8.0 · Data.Array.Base
datadata Word32
#

32-bit unsigned integer type

Instances22Bounded, Enum, Eq, Integral, Data, Num, …
  • Bounded Word32Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Enum Word32Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Eq Word32Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Integral Word32Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Data Word32Defined in ghc-internal-9.1003.0 · GHC.Internal.Data.Data
  • Num Word32Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Ord Word32Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Read Word32Defined in ghc-internal-9.1003.0 · GHC.Internal.Read
  • Real Word32Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Show Word32Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Ix Word32Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Bits Word32Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • FiniteBits Word32Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Storable Word32Defined in ghc-internal-9.1003.0 · GHC.Internal.Foreign.Storable
  • PrintfArg Word32Defined in base-4.20.2.0 · Text.Printf
  • NFData Word32Defined in deepseq-1.5.0.0 · Control.DeepSeq
  • Mantissa Word32Defined in bytestring-0.12.2.0 · Data.ByteString.Builder.RealFloat.Internal
  • Binary Word32Defined in binary-0.8.9.3 · Data.Binary.Class
  • Lift Word32Defined in template-haskell-2.22.0.0 · Language.Haskell.TH.Syntax
  • IArray UArray Word32Defined in array-0.5.8.0 · Data.Array.Base
  • MArray IOUArray Word32 IODefined in array-0.5.8.0 · Data.Array.IO.Internals
  • MArray (STUArray s) Word32 (ST s)Defined in array-0.5.8.0 · Data.Array.Base
datadata Word16
#

16-bit unsigned integer type

Instances21Bounded, Enum, Eq, Integral, Data, Num, …
  • Bounded Word16Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Enum Word16Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Eq Word16Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Integral Word16Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Data Word16Defined in ghc-internal-9.1003.0 · GHC.Internal.Data.Data
  • Num Word16Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Ord Word16Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Read Word16Defined in ghc-internal-9.1003.0 · GHC.Internal.Read
  • Real Word16Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Show Word16Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Ix Word16Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Bits Word16Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • FiniteBits Word16Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Storable Word16Defined in ghc-internal-9.1003.0 · GHC.Internal.Foreign.Storable
  • PrintfArg Word16Defined in base-4.20.2.0 · Text.Printf
  • NFData Word16Defined in deepseq-1.5.0.0 · Control.DeepSeq
  • Binary Word16Defined in binary-0.8.9.3 · Data.Binary.Class
  • Lift Word16Defined in template-haskell-2.22.0.0 · Language.Haskell.TH.Syntax
  • IArray UArray Word16Defined in array-0.5.8.0 · Data.Array.Base
  • MArray IOUArray Word16 IODefined in array-0.5.8.0 · Data.Array.IO.Internals
  • MArray (STUArray s) Word16 (ST s)Defined in array-0.5.8.0 · Data.Array.Base
datadata Word8
#

8-bit unsigned integer type

Instances21Bounded, Enum, Eq, Integral, Data, Num, …
  • Bounded Word8Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Enum Word8Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Eq Word8Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Integral Word8Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Data Word8Defined in ghc-internal-9.1003.0 · GHC.Internal.Data.Data
  • Num Word8Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Ord Word8Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Read Word8Defined in ghc-internal-9.1003.0 · GHC.Internal.Read
  • Real Word8Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Show Word8Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Ix Word8Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Bits Word8Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • FiniteBits Word8Defined in ghc-internal-9.1003.0 · GHC.Internal.Word
  • Storable Word8Defined in ghc-internal-9.1003.0 · GHC.Internal.Foreign.Storable
  • PrintfArg Word8Defined in base-4.20.2.0 · Text.Printf
  • NFData Word8Defined in deepseq-1.5.0.0 · Control.DeepSeq
  • Binary Word8Defined in binary-0.8.9.3 · Data.Binary.Class
  • Lift Word8Defined in template-haskell-2.22.0.0 · Language.Haskell.TH.Syntax
  • IArray UArray Word8Defined in array-0.5.8.0 · Data.Array.Base
  • MArray IOUArray Word8 IODefined in array-0.5.8.0 · Data.Array.IO.Internals
  • MArray (STUArray s) Word8 (ST s)Defined in array-0.5.8.0 · Data.Array.Base