Data.Increments

Calculate incremental changes of data structures.

The Incremental class provides a set of functions that work like the unix utilities diff and patch. changes generates an incremental diff between two data values. The incremental diff can then be applied by the applyChanges function.

The primary intention of this library is to support efficient serialization. As such, default Increment types are automatically provided with Beamable instances.

{-# LANGUAGE DeriveGenerics #-}
{-# LANGUAGE ConstraintKinds #-}
{-# LANGUAGE FlexibleContexts #-}
{-# LANGUAGE UndecidableInstances #-}

import GHC.Generics
import Data.Beamable
import Data.ByteString as B

data Foo a b = Foo Int (Maybe a) b deriving (Generic, Eq, Show)

-- If a 'Generic' instance is available, the default definition is
-- fine, after adding some constraints.
instance (IncrementalCnstr a, IncrementalCnstr b) => Incremental (Foo a b)

-- generate some test data
foo1 = Foo 1 Nothing "foo1"
foo2 = Foo 1 (Just "foo2") "foo1"

-- the 'changes' function calculates an incremental changeset from
-- 'foo1' to 'foo2'
diff = changes foo1 foo2

-- 'applyChanges' applies the changes in an incremental patch to some data
-- applyChanges foo1 diff == foo2
-- True

-- incremental changes can be smaller (sometimes significantly smaller)
-- than the data source
-- B.length $ encode diff
-- 8
-- B.length $ encode foo2
-- 12

Incremental changes are not in general commutative or optional, and it can be an error to apply a change to a data structure that doesn't match the originating structure. For example:

*Data.Increments> let diff = changes (Left 1) (Left 2 :: Either Int Char)
*Data.Increments> applyChanges (Right 'a') diff
*** Exception: Data.Increments: malformed Increment Rep

Documentation

class Incremental a where

Calculate differences between data structures.

Minimal complete definition

Nothing

Associated Types

type Increment a :: *

Methods

changes :: a -> a -> Increment a

generate the changes between the previous and current data

applyChanges :: a -> Increment a -> a

Apply a changes to a value

Instances

Incremental Bool

Incremental Char

Incremental Double

Incremental Float

Incremental Int

Incremental Int8

Incremental Int16

Incremental Int32

Incremental Int64

Incremental Integer

Incremental Ordering

Incremental Word

Incremental Word8

Incremental Word16

Incremental Word32

Incremental Word64

Incremental ()

Incremental ByteString

Incremental ByteString

Incremental IntSet

Eq x => Incremental [x]

(Incremental a, Changed (Increment a)) => Incremental (Maybe a)

IncrementalCnstr a => Incremental (IntMap a)

Ord a => Incremental (Set a)

(Incremental l, Incremental r, Changed (Increment l), Changed (Increment r)) => Incremental (Either l r)

(IncrementalCnstr l, IncrementalCnstr r) => Incremental (l, r)

(Ord k, IncrementalCnstr a) => Incremental (Map k a)

(IncrementalCnstr a, IncrementalCnstr b, IncrementalCnstr c) => Incremental (a, b, c)

(IncrementalCnstr a, IncrementalCnstr b, IncrementalCnstr c, IncrementalCnstr d) => Incremental (a, b, c, d)

(IncrementalCnstr a, IncrementalCnstr b, IncrementalCnstr c, IncrementalCnstr d, IncrementalCnstr e) => Incremental (a, b, c, d, e)

(IncrementalCnstr a, IncrementalCnstr b, IncrementalCnstr c, IncrementalCnstr d, IncrementalCnstr e, IncrementalCnstr f) => Incremental (a, b, c, d, e, f)

(IncrementalCnstr a, IncrementalCnstr b, IncrementalCnstr c, IncrementalCnstr d, IncrementalCnstr e, IncrementalCnstr f, IncrementalCnstr g) => Incremental (a, b, c, d, e, f, g)

class Changed a where

Determine if a Increment representation contains a real change. Unchanging changes may be omitted.

Methods

didChange :: a -> Bool

Instances

Changed ()

Changed (DPrim a)

type IncrementalCnstr a = (Incremental a, Changed (Increment a))

A useful type constraint synonym for writing instances