Data.Map.Merge.Lazy

A tactic for dealing with keys present in one map but not the other in merge.

A tactic of type SimpleWhenMissing k x z is an abstract representation of a function of type k -> x -> Maybe z .

A tactic for dealing with keys present in both maps in merge.

A tactic of type SimpleWhenMatched k x y z is an abstract representation of a function of type k -> x -> y -> Maybe z .

Merge two maps.

merge takes two WhenMissing tactics, a WhenMatched tactic and two maps. It uses the tactics to merge the maps. Its behavior is best understood via its fundamental tactics, mapMaybeMissing and zipWithMaybeMatched.

Consider

merge (mapMaybeMissing g1)
             (mapMaybeMissing g2)
             (zipWithMaybeMatched f)
             m1 m2

Take, for example,

m1 = [(0, 'a'), (1, 'b'), (3, 'c'), (4, 'd')]
m2 = [(1, "one"), (2, "two"), (4, "three")]

merge will first "align" these maps by key:

m1 = [(0, 'a'), (1, 'b'),               (3, 'c'), (4, 'd')]
m2 =           [(1, "one"), (2, "two"),           (4, "three")]

It will then pass the individual entries and pairs of entries to g1, g2, or f as appropriate:

maybes = [g1 0 'a', f 1 'b' "one", g2 2 "two", g1 3 'c', f 4 'd' "three"]

This produces a Maybe for each key:

keys =     0        1          2           3        4
results = [Nothing, Just True, Just False, Nothing, Just True]

Finally, the Just results are collected into a map:

return value = [(1, True), (2, False), (4, True)]

The other tactics below are optimizations or simplifications of mapMaybeMissing for special cases. Most importantly,

• dropMissing drops all the keys.

• preserveMissing leaves all the entries alone.

When merge is given three arguments, it is inlined at the call site. To prevent excessive inlining, you should typically use merge to define your custom combining functions.

Examples:

prop> unionWithKey f = merge preserveMissing preserveMissing (zipWithMatched f)

prop> intersectionWithKey f = merge dropMissing dropMissing (zipWithMatched f)

prop> differenceWith f = merge preserveMissing dropMissing (zipWithMatched f)

prop> symmetricDifference = merge preserveMissing preserveMissing (zipWithMaybeMatched $ \ _ _ _ -> Nothing)

prop> mapEachPiece f g h = merge (mapMissing f) (mapMissing g) (zipWithMatched h)

A tactic for dealing with keys present in one map but not the other in merge or mergeA.

A tactic of type WhenMissing f k x z is an abstract representation of a function of type k -> x -> f (Maybe z) .

A tactic for dealing with keys present in both maps in merge or mergeA.

A tactic of type WhenMatched f k x y z is an abstract representation of a function of type k -> x -> y -> f (Maybe z) .

An applicative version of merge.

mergeA takes two WhenMissing tactics, a WhenMatched tactic and two maps. It uses the tactics to merge the maps. Its behavior is best understood via its fundamental tactics, traverseMaybeMissing and zipWithMaybeAMatched.

Consider

mergeA (traverseMaybeMissing g1)
              (traverseMaybeMissing g2)
              (zipWithMaybeAMatched f)
              m1 m2

Take, for example,

m1 = [(0, 'a'), (1, 'b'), (3, 'c'), (4, 'd')]
m2 = [(1, "one"), (2, "two"), (4, "three")]

mergeA will first "align" these maps by key:

m1 = [(0, 'a'), (1, 'b'),               (3, 'c'), (4, 'd')]
m2 =           [(1, "one"), (2, "two"),           (4, "three")]

It will then pass the individual entries and pairs of entries to g1, g2, or f as appropriate:

actions = [g1 0 'a', f 1 'b' "one", g2 2 "two", g1 3 'c', f 4 'd' "three"]

Next, it will perform the actions in the actions list in order from left to right.

keys =     0        1          2           3        4
results = [Nothing, Just True, Just False, Nothing, Just True]

Finally, the Just results are collected into a map:

return value = [(1, True), (2, False), (4, True)]

The other tactics below are optimizations or simplifications of traverseMaybeMissing for special cases. Most importantly,

• dropMissing drops all the keys.

• preserveMissing leaves all the entries alone.

• mapMaybeMissing does not use the Applicative context.

When mergeA is given three arguments, it is inlined at the call site. To prevent excessive inlining, you should generally only use mergeA to define custom combining functions.