binary
Binary serialisation for Haskell values using lazy ByteStrings
https://github.com/kolmodin/binary
Version on this page: | 0.8.5.1 |
LTS Haskell 22.18: | 0.8.9.1 |
Stackage Nightly 2024-04-25: | 0.8.9.1 |
Latest on Hackage: | 0.10.0.0@rev:1 |
binary-0.8.5.1@sha256:e4e0c71916cc1112c63b498ad12b26ff361af1e8c6d42c5e3f7e3a598871d407,5924
Module documentation for 0.8.5.1
binary package
Efficient, pure binary serialisation using lazy ByteStrings.
The binary
package provides Data.Binary, containing the Binary class,
and associated methods, for serialising values to and from lazy
ByteStrings.
A key feature of binary
is that the interface is both pure, and efficient.
The binary
package is portable to GHC and Hugs.
Installing binary from Hackage
binary
is part of The Glasgow Haskell Compiler (GHC) and therefore if you
have either GHC or The Haskell Platform
installed, you already have binary
.
More recent versions of binary
than you might have installed may be
available. You can use cabal-install
to install a later version from
Hackage.
$ cabal update
$ cabal install binary
Building binary
binary
comes with both a test suite and a set of benchmarks.
While developing, you probably want to enable both.
Here’s how to get the latest version of the repository, configure and build.
$ git clone [email protected]:kolmodin/binary.git
$ cd binary
$ cabal update
$ cabal configure --enable-tests --enable-benchmarks
$ cabal build
Run the test suite.
$ cabal test
Using binary
First:
import Data.Binary
and then write an instance of Binary for the type you wish to serialise.
An example doing exactly this can be found in the Data.Binary module.
You can also use the Data.Binary.Builder module to efficiently build
lazy bytestrings using the Builder
monoid. Or, alternatively, the
Data.Binary.Get and Data.Binary.Put to serialize/deserialize using
the Get
and Put
monads.
More information in the haddock documentation.
Deriving binary instances using GHC’s Generic
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
Contributors
- Lennart Kolmodin
- Duncan Coutts
- Don Stewart
- Spencer Janssen
- David Himmelstrup
- Björn Bringert
- Ross Paterson
- Einar Karttunen
- John Meacham
- Ulf Norell
- Tomasz Zielonka
- Stefan Karrmann
- Bryan O’Sullivan
- Bas van Dijk
- Florian Weimer
For a full list of contributors, see here.
Changes
binary
binary-0.9.0.0
0.8.5.0
was first released as version0.9.0.0
. It didn’t have any breaking changes though, so it was again released as version0.8.5.0
according to PVP. Next breaking release ofbinary
will be version0.10.0.0
.
binary-0.8.5.0
- Add Binary instances for Typeable TypeReps, #131.
binary-0.8.4.1
- Fix compilation with bytestring < 0.10.4.
binary-0.8.4.0
binary
supports GHC >= 7.4.2- Performance improvements for
Alternative
functions. - put/get functions for IEEE-754 floats and doubles, #119.
- Fix performance bugs, #115.
- Binary instances for datatypes in
Data.Monoid
andData.Semigroup
, #114.
binary-0.8.3.0
- Replace binary’s home grown
Builder
withData.ByteString.Builder
.Data.Binary.Builder
now exportsData.ByteString.Builder.Builder
. - Add
putList :: [a] -> Put
to theBinary
class. This is used to be able to use the list writing primitives of the new Builder. This brought a number of speedups; Encoding a String is now 70% faster. [Word8] is 76% faster, which also makes Integer 34% faster. Similar numbers for all [IntXX] and [WordXX]. - Fail gracefully within
Get
when decodingBool
andOrdering
. Previously when decoding invalid data these instances would fail witherror
. - Add Binary instance for
Complex a
. - Add Monoid and Semigroup instance for
Put
.
binary-0.8.2.1
- Fix compilation error when using older GHC versions and clang. clang barfs on some of its CPP input (#105).
binary-0.8.2.0
- When using GHC >= 8,
Data.Binary.Get.Get
implements MonadFail and delegates itsfail
toMonadFail.fail
.
binary-0.8.1.0
- Add binary instance for
Data.ByteString.Short
. - Add get/put functions for all Int sizes to
Data.Binary.Builder
,Data.Binary.Get
andData.Binary.Put
.
binary-0.8.0.1
- Address compiler warnings.
binary-0.8.0.0
- Added binary instance for
Version
fromData.Version
. - Added binary instance for
Void
from GHC 7.10.1. - Added binary instance for
(Data.Fixed a)
from GHC 7.8.1. - Added semigroup instance for
Data.Binary.Builder
from GHC 8.0.
binary-0.7.6.1
- Fix compilation for GHC == 7.2.*.
binary-0.7.6.0
- Added binary instance for GHC.Fingerprint (from GHC >= 7.4).
binary-0.7.5.0
- Fix performance bug that was noticable when you get a big strict ByteString and the input to the decoder consists of many small chunks.
- Fix memory leak when decoding Double and Float.
- Commit 497a181c083fa9faf7fa3aa64d1d8deb9ac76ecb
- We now require QuickCheck >= 2.8. Remove our version of arbitrarySizedNatural.
binary-0.7.4.0
- Some invalid UTF-8 strings caused an exception when decoded. Those errors will now now fail in the Get monad instead. See #70. Patch contributed by @ttuegel.
binary-0.7.3.0
- Add Binary instance for Natural (only with base > 4.8).
binary-0.7.2.3
- Remove INLINEs from GBinary/GSum methods. These interact very badly with the GHC 7.9.x simplifier. See also;
binary-0.7.2.2
- Make import of GHC.Base future-proof (https://github.com/kolmodin/binary/pull/59).
binary-0.7.2.1
- Fix to compile on GHC 6.10.4 and older (https://github.com/kolmodin/binary/issues/55).
binary-0.7.2.0
- Add
isolate :: Int -> Get a -> Get a
. - Add
label :: String -> Get a -> Get a
.
binary-0.7.1.0
- Add
lookAheadE :: Get (Either a b) -> Get (Either a b)
. - Add MonadPlus instance for Get.
binary-0.7.0.1
- Updates to documentation.
binary-0.7.0.0
- Add
lookAhead :: Get a -> Get a
. - Add
lookAheadM :: Get (Maybe a) -> Get (Maybe a)
. - Add Alternative instance for Get (provides
<|>
). - Add
decodeOrFail :: Binary a => L.ByteString -> Either (L.ByteString, ByteOffset, String) (L.ByteString, ByteOffset, a)
- Add
decodeFileOrFail :: Binary a => FilePath -> IO (Either (ByteOffset, String) a)
. - Remove
Ord
class constraint fromSet
andMap
Binary instances.
binary-0.6.4
- Add
runGetOrFail :: Get a -> L.ByteString -> Either (L.ByteString, ByteOffset, String) (L.ByteString, ByteOffset, a)
.
binary-0.6.3
- Documentation tweeks, internal restructuring, more tests.
binary-0.6.2
some
andmany
more efficient.- Fix bug where
bytesRead
returned the wrong value. - Documentation improvements.
binary-0.6.1
- Fix bug where a decoder could return with
Partial
after the previous reply wasNothing
.