bytes-0.15.2: Sharing code for serialization between binary and cereal

Copyright(c) Edward Kmett 2013-2015
LicenseBSD3
MaintainerEdward Kmett <ekmett@gmail.com>
Stabilityexperimental
Portabilitynon-portable
Safe HaskellTrustworthy
LanguageHaskell98

Data.Bytes.Serial

Contents

Description

This module contains two main classes, each providing methods to serialize and deserialize types. Serial is the primary class, to be used for the canonical way to serialize a specific type. SerialEndian is used to provide endian-specific methods for serializing a type.

Synopsis

Serialization

class Serial a where Source

Methods to serialize and deserialize type a to a binary representation

Instances provided here for fixed-with Integers and Words are big endian. Instances for strict and lazy bytestrings store also the length of bytestring big endian. Instances for Word and Int are host endian as they are machine-specific types.

Minimal complete definition

Nothing

Methods

serialize :: MonadPut m => a -> m () Source

deserialize :: MonadGet m => m a Source

Instances

Serial Bool Source 
Serial Char Source 
Serial Double Source 
Serial Float Source 
Serial Int Source 
Serial Int8 Source 
Serial Int16 Source 
Serial Int32 Source 
Serial Int64 Source 
Serial Integer Source
>>> (runGetL deserialize $ runPutL $ serialize (1822304234^100::Integer))::Integer
115368812579128172803867366576339947332796540054052185472042218522037227934707037623902492207671987696439966697503243972076991940820348847422930433939639982092916577692754723458548819441583937289395076910527534916776189405228720063994377687015476947534961767053653973945346259230972683338173842343243493433367681264359887291905132383269175086733345253389374961758293922003996035662362278340494093804835649459223465051596978792130073960666112508481814461273829244289795707398202762289955919352549768394583446336873179280924584333491364188425976869717125645749497258775598562132278030402205794994603544837805140410310712693778605743100915046769381631247123664460203591228745772887977959388457679427407639421147498028487544882346912935398848298806021505673449774474457435816552278997100556732447852816961683577731381792363312695347606768120122976105200574809419685234274705929886121600174028733812771637390342332436695318974693376
Serial Ordering Source
>>> runGetL deserialize $ runPutL $ serialize LT::Ordering
LT
>>> runGetL deserialize $ runPutL $ serialize EQ::Ordering
EQ
>>> runGetL deserialize $ runPutL $ serialize GT::Ordering
GT
Serial Word Source 
Serial Word8 Source 
Serial Word16 Source 
Serial Word32 Source 
Serial Word64 Source 
Serial () Source 
Serial Void Source 
Serial Natural Source
>>> runGetL deserialize (runPutL (serialize (10^10::Natural))) :: Natural
10000000000
Serial Version Source 
Serial All Source 
Serial Any Source 
Serial ByteString Source 
Serial ByteString Source 
Serial IntSet Source 
Serial Scientific Source 
Serial Text Source 
Serial Text Source 
Serial AbsoluteTime Source
>>> (runGetL deserialize $ runPutL $ serialize (addAbsoluteTime 18.2 taiEpoch))::AbsoluteTime
1858-11-17 00:00:18.2 TAI
Serial LocalTime Source 
Serial ZonedTime Source 
Serial TimeOfDay Source 
Serial TimeZone Source 
Serial UTCTime Source
>>> (runGetL deserialize $ runPutL $ serialize (read "2014-01-01 10:54:42.478031 UTC"::UTCTime))::UTCTime
2014-01-01 10:54:42.478031 UTC
Serial NominalDiffTime Source
>>> (runGetL deserialize $ runPutL $ serialize (1.82::DiffTime))::DiffTime
1.82s
Serial Day Source
>>> (runGetL deserialize $ runPutL $ serialize (ModifiedJulianDay 1))::Day
1858-11-18
Serial UniversalTime Source
>>> getModJulianDate $ (runGetL deserialize $ runPutL $ serialize (ModJulianDate $ 5 % 11)::UniversalTime)
5 % 11
Serial DiffTime Source
>>> (runGetL deserialize $ runPutL $ serialize (1.82::DiffTime))::DiffTime
1.82s
Serial a => Serial [a] Source 
(Serial a, Integral a) => Serial (Ratio a) Source
>>> (runGetL deserialize $ runPutL $ serialize (5 % 11::Ratio Int))::Ratio Int
5 % 11
Serial a => Serial (Identity a) Source 
HasResolution a => Serial (Fixed a) Source
>>> (runGetL deserialize $ runPutL $ serialize (1.82::Fixed E2))::Fixed E2
1.82
Serial a => Serial (ZipList a) Source 
Serial a => Serial (Dual a) Source 
Serial a => Serial (Sum a) Source 
Serial a => Serial (Product a) Source 
Serial a => Serial (First a) Source 
Serial a => Serial (Last a) Source 
Serial a => Serial (Down a) Source 
Serial a => Serial (Maybe a) Source 
Serial v => Serial (IntMap v) Source 
(Serial a, Ord a) => Serial (Set a) Source 
Serial a => Serial (Seq a) Source 
(Serial v, Hashable v, Eq v) => Serial (HashSet v) Source 
(Bits n, Integral n, Bits (Unsigned n), Integral (Unsigned n)) => Serial (VarInt n) Source

$setup >>> import Data.Word >>> import Data.Fixed >>> import Data.Bytes.Serial

Integer/Word types serialized to base-128 variable-width ints.

>>> import Data.Monoid (mconcat)
>>> import qualified Data.ByteString.Lazy as BSL
>>> mconcat $ BSL.toChunks $ runPutL $ serialize (97 :: Word64)
"\NUL\NUL\NUL\NUL\NUL\NUL\NULa"
>>> mconcat $ BSL.toChunks $ runPutL $ serialize (97 :: VarInt Word64)
"a"
(Serial a, Serial b) => Serial (Either a b) Source 
(Serial a, Serial b) => Serial (a, b) Source 
(Serial k, Serial v, Ord k) => Serial (Map k v) Source 
Serial (f a) => Serial (Reverse f a) Source 
Serial a => Serial (Constant a b) Source 
(Serial k, Serial v, Hashable k, Eq k) => Serial (HashMap k v) Source 
(Serial a, Serial b, Serial c) => Serial (a, b, c) Source 
(Serial (f a), Serial (g a)) => Serial (Product f g a) Source 
(Serial a, Serial b, Serial c, Serial d) => Serial (a, b, c, d) Source 
(Serial a, Serial b, Serial c, Serial d, Serial e) => Serial (a, b, c, d, e) Source 

Specifying endianness

class SerialEndian a where Source

Methods to serialize and deserialize type a to a big and little endian binary representations. Methods suffixed with "host" are automatically defined to use equal the methods corresponding to the current machine's native endianness, but they can be overridden.

Minimal complete definition

Nothing

Methods

serializeBE :: MonadPut m => a -> m () Source

deserializeBE :: MonadGet m => m a Source

serializeLE :: MonadPut m => a -> m () Source

deserializeLE :: MonadGet m => m a Source

serializeHost :: MonadPut m => a -> m () Source

deserializeHost :: MonadGet m => m a Source

Instances

Higher-order

These classes provide us with the ability to serialize containers that need polymorphic recursion.

class Serial1 f where Source

Minimal complete definition

Nothing

Methods

serializeWith :: MonadPut m => (a -> m ()) -> f a -> m () Source

deserializeWith :: MonadGet m => m a -> m (f a) Source

Instances

serialize1 :: (MonadPut m, Serial1 f, Serial a) => f a -> m () Source

deserialize1 :: (MonadGet m, Serial1 f, Serial a) => m (f a) Source

class Serial2 f where Source

Methods

serializeWith2 :: MonadPut m => (a -> m ()) -> (b -> m ()) -> f a b -> m () Source

deserializeWith2 :: MonadGet m => m a -> m b -> m (f a b) Source

Instances

serialize2 :: (MonadPut m, Serial2 f, Serial a, Serial b) => f a b -> m () Source

deserialize2 :: (MonadGet m, Serial2 f, Serial a, Serial b) => m (f a b) Source

Storable

store :: (MonadPut m, Storable a) => a -> m () Source

serialize any Storable in a host-specific format.

restore :: forall m a. (MonadGet m, Storable a) => m a Source

deserialize any Storable in a host-specific format.

Generics

You probably will never need to care that these exist except they provide us with default definitions for Serial and SerialEndian

class GSerial f where Source

Used internally to provide generic serialization

Methods

gserialize :: MonadPut m => f a -> m () Source

gdeserialize :: MonadGet m => m (f a) Source

Instances

class GSerialEndian f where Source

Used internally to provide generic big-endian serialization

Minimal complete definition

Nothing

Methods

gserializeBE :: MonadPut m => f a -> m () Source

gdeserializeBE :: MonadGet m => m (f a) Source

gserializeLE :: MonadPut m => f a -> m () Source

gdeserializeLE :: MonadGet m => m (f a) Source

Instances

class GSerial1 f where Source

Used internally to provide generic serialization

Methods

gserializeWith :: MonadPut m => (a -> m ()) -> f a -> m () Source

gdeserializeWith :: MonadGet m => m a -> m (f a) Source

Instances