Community
Modules 31

Data.Map.Merge.Set.Lazy

This module defines an API for writing functions that merge a map and a set into a map. The key functions are merge and mergeA. Each of these can be used with several different "merge tactics".

The merge and mergeA functions are shared by the lazy and strict modules. Only the choice of merge tactics determines strictness. If you use mapMissing from Data.Map.Merge.Set.Strict then the results will be forced before they are inserted. If you use mapMissing from this module then they will not.

Simple merge tactic types

type SimpleWhenMissing = WhenMissing Identity

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 .

type SimpleWhenMissingSet = WhenMissingSet Identity

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

A tactic of type SimpleWhenMissingSet k a is an abstract representation of a function of type k -> Maybe a.

type SimpleWhenMatched = WhenMatched Identity

A tactic for dealing with keys present in both the set and the map in merge.

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

General combining function

merge :: Ord k => M.SimpleWhenMissing k a b -> SimpleWhenMissingSet k b -> SimpleWhenMatched k a b -> Map k a -> Set k -> Map k b

Merge a map and a set into a map.

merge takes a SimpleWhenMissing tactic, a SimpleWhenMissingSet tactic, a SimpleWhenMatched tactic, a map and a set. It uses the tactics to merge the map and the set into a map.

Its behavior is best understood via the tactics mapMaybeMissing, generateMaybeMissingSet, and mapMaybeMatched. Consider

merge (mapMaybeMissing g1) (generateMaybeMissingSet g2) (mapMaybeMatched f) m1 s2
g1 k x = if k == 2 then Just ("1" ++ x) else Nothing
g2 k = if k == 3 then Just "2" else Nothing
f k x = if k == 6 then Just ("3" ++ x) else Nothing
m1 = fromList [(2,"a"), (4,"b"), (6,"c"), (8,"d"), (10,"e"), (12,"f")]
s2 = fromList [3, 6, 9, 12]

merge will pass the keys and values to g1, g2, or f as appropriate, producing a Maybe for each element.

m1:      [ (2, "a"),           (4, "b"),  (6, "c"), (8, "d"),          (10, "e"), (12, "f")]
s2:      [                  3,                   6,                 9,                   12]
result:  [ g1 2 "a",     g2 3, g1 4 "b",   f 6 "c", g1 8 "d",    g2 9, g1 10 "e",  f 12 "f"]
       = [Just "1a", Just "2",  Nothing, Just "3c",  Nothing, Nothing,   Nothing,   Nothing]

The result map contains the Just values.

>>> merge (mapMaybeMissing g1) (generateMaybeMissingSet g2) (mapMaybeMatched f) m1 s2
fromList [(2,"1a"), (3,"2g"), (6,"3c")]

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.

What to do with keys in m1 but not s2

What to do with keys in s2 but not m1

What to do with keys in both m1 and s2

Map m1

Set s2

WhenMatched tactics

dropMatched :: Applicative f => WhenMatched f k a b

When a key is found in both the map and the set, drop the key and value.

filterMatched :: Applicative f => (k -> a -> Bool) -> WhenMatched f k a a

When a key is found in both the map and the set, apply a function to the key and the value in the map and keep the value in the merged map if the result is True.

mapMatched :: Applicative f => (k -> a -> b) -> WhenMatched f k a b

When a key is found in both the map and the set, apply a function to the key and the value in the map and use the result as the value for the merged map.

mapMaybeMatched :: Applicative f => (k -> a -> Maybe b) -> WhenMatched f k a b

When a key is found in both the map and the set, apply a function to the key and the value in the map and maybe use the result as the value for the merged map.

WhenMissing tactics

dropMissing :: Applicative f => WhenMissing f k x y

Drop all the entries whose keys are missing from the other map.

dropMissing :: SimpleWhenMissing k x y
dropMissing = mapMaybeMissing (\_ _ -> Nothing)

but dropMissing is much faster.

preserveMissing :: Applicative f => WhenMissing f k x x

Preserve, unchanged, the entries whose keys are missing from the other map.

preserveMissing :: SimpleWhenMissing k x x
preserveMissing = Merge.Lazy.mapMaybeMissing (\_ x -> Just x)

but preserveMissing is much faster.

mapMissing :: Applicative f => (k -> x -> y) -> WhenMissing f k x y

Map over the entries whose keys are missing from the other map.

mapMissing :: (k -> x -> y) -> SimpleWhenMissing k x y
mapMissing f = mapMaybeMissing (\k x -> Just $ f k x)

but mapMissing is somewhat faster.

filterMissing :: Applicative f => (k -> x -> Bool) -> WhenMissing f k x x

Filter the entries whose keys are missing from the other map.

filterMissing :: (k -> x -> Bool) -> SimpleWhenMissing k x x
filterMissing f = Merge.Lazy.mapMaybeMissing $ \k x -> guard (f k x) *> Just x

but this should be a little faster.

mapMaybeMissing :: Applicative f => (k -> x -> Maybe y) -> WhenMissing f k x y

Map over the entries whose keys are missing from the other map, optionally removing some. This is the most powerful SimpleWhenMissing tactic, but others are usually more efficient.

mapMaybeMissing :: (k -> x -> Maybe y) -> SimpleWhenMissing k x y
mapMaybeMissing f = traverseMaybeMissing (\k x -> pure (f k x))

but mapMaybeMissing uses fewer unnecessary Applicative operations.

WhenMissingSet tactics

dropMissingSet :: Applicative f => WhenMissingSet f k a

Drop keys that are present in the set but missing from the map.

generateMissingSet :: Applicative f => (k -> a) -> WhenMissingSet f k a

For keys that are present in the set but missing from the map, apply a function and use the result as the value for the merged map.

generateMaybeMissingSet :: Applicative f => (k -> Maybe a) -> WhenMissingSet f k a

For keys that are present in the set but missing from the map, apply a function and maybe use the result as the value for the merged map.

Applicative merge tactic types

data WhenMissing f k x y

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) .

data WhenMissingSet f k a

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

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

newtype WhenMatched f k a b

A tactic for dealing with keys present in both the set and the map in merge or mergeA.

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

General combining function

mergeA :: (Applicative f, Ord k) => M.WhenMissing f k a b -> WhenMissingSet f k b -> WhenMatched f k a b -> Map k a -> Set k -> f (Map k b)

Merge a map and a set into a map. Applicative version of merge.

mergeA takes a WhenMissing tactic, a WhenMissingSet tactic, a WhenMatched tactic, a map and a set. It uses the tactics to merge the map and the set into a map.

Behaves just like merge while allowing Applicative effects. Effects are performed in increasing order of keys.

Consider

mergeA (traverseMaybeMissing g1)
       (generateMaybeAMissingSet g2)
       (traverseMaybeMatched f)
       m1
       s2
g1 k x = let z = if k == 2 then Just ("1" ++ x) else Nothing
         in z <$ putStrLn ("g1 " ++ show (k, x))
g2 k = let z = if k == 3 then Just "2" else Nothing
       in z <$ putStrLn ("g2 " ++ show k)
f k x = let z = if k == 6 then Just ("3" ++ x) else Nothing
        in z <$ putStrLn ("f " ++ show (k, x))
m1 = fromList [(2,"a"), (4,"b"), (6,"c"), (8,"d"), (10,"e"), (12,"f")]
m2 = fromList [3, 6, 9, 12]

As with merge, the result map is [(2,"1a"), (3,"2"), (6,"3c")]. Additionally, g1, g2, and f perform IO effects, printing in increasing order of key.

>>> mergeA (traverseMaybeMissing g1) (generateMaybeAMissingSet g2) (traverseMaybeMatched f) m1 s2
g1 (2,"a")
g2 3
g1 (4,"b")
f (6,"c")
g1 (8,"d")
g2 9
g1 (10,"e")
f (12,"f")
fromList [(2,"1a"),(3,"2"),(6,"3c")]

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.

Examples

data Pair a = Pair !a !a deriving Functor

instance Applicative Pair where
   pure x = Pair x x
   liftA2 f (Pair x1 y1) (Pair x2 y2) = Pair (f x1 x2) (f y1 y2)

-- | Partition the map according to whether the keys appear in the set.
partitionKeys :: Ord k => Map k a -> Set k -> (Map k a, Map k a)
partitionKeys m s =
  case mergeA dropAndPreserveMissing dropMissingSet preserveAndDropMatched m s of
    Pair m1 m2 -> (m1, m2)
  where
    dropAndPreserveMissing = whenMissing (\\_k x -> Pair Nothing (Just x)) (\\m -> Pair empty m)
    preserveAndDropMatched = traverseMaybeMatched (\\_k x -> Pair (Just x) Nothing)
import Data.Functor.Const (Const(..))
import Data.Monoid (All(..))

-- | Whether the keys of the map are a subset of the keys of the set.
keysAreSubsetOf :: Ord k => Map k a -> Set k -> Bool
keysAreSubsetOf m s =
  getAll (getConst (mergeA isEmpty dropMissing 'dropMatched' m1 m2))
  where
    isEmpty = whenMissing (\\_k _x -> Const (All False)) (\\m -> Const (All (null m)))

What to do with keys in m1 but not s2

What to do with keys in s2 but not m1

What to do with keys in both m1 and s2

Map m1

Set s2

WhenMatched tactics

filterAMatched :: Functor f => (k -> a -> f Bool) -> WhenMatched f k a a

When a key is found in both the map and the set, apply a function to the key and the value in the map and keep the value in the merged map if the result of the action is True.

traverseMatched :: Functor f => (k -> a -> f b) -> WhenMatched f k a b

When a key is found in both the map and the set, apply a function to the key and the value in the map, and use the result of the action as the value for the merged map.

traverseMaybeMatched :: (k -> a -> f (Maybe b)) -> WhenMatched f k a b

When a key is found in both the map and the set, apply a function to the key and the value in the map, and maybe use the result of the action as the value for the merged map.

WhenMissing tactics

filterAMissing :: Applicative f => (k -> x -> f Bool) -> WhenMissing f k x x

Filter the entries whose keys are missing from the other map using some Applicative action.

filterAMissing f = Merge.Lazy.traverseMaybeMissing $
  \k x -> (\b -> guard b *> Just x) <$> f k x

but this should be a little faster.

traverseMissing :: Applicative f => (k -> x -> f y) -> WhenMissing f k x y

Traverse over the entries whose keys are missing from the other map.

traverseMaybeMissing :: Applicative f => (k -> x -> f (Maybe y)) -> WhenMissing f k x y

Traverse over the entries whose keys are missing from the other map, optionally producing values to put in the result. This is the most powerful WhenMissing tactic, but others are usually more efficient.

whenMissing :: (k -> x -> f (Maybe y)) -> (Map k x -> f (Map k y)) -> WhenMissing f k x y

Create a WhenMissing from two functions.

whenMissing must be called with two functions f and g such that g = traverseMaybeWithKey f. g may be a more efficient way of applying f to all key-value pairs in a Map.

Warning: It is the caller's responsibility to ensure the above property.

Examples

preserveMissing :: Applicative f => WhenMissing f k x x
preserveMissing = whenMissing f g
  where
    f _k x = pure (Just x)
    g m = pure m
    -- Note that this satisfies g = traverseMaybeWithKey f
import Data.Functor.Const (Const(..))
import Data.Monoid (All(..))

-- For a usage of this, see examples on mergeA
isEmpty :: WhenMissing (Const All) k x y
isEmpty = whenMissing f g
  where
    f _k _x = Const (All False)
    g m = Const (All (null m))
    -- Note that this satisfies g = traverseMaybeWithKey f

WhenMissingSet tactics

generateAMissingSet :: Applicative f => (k -> f a) -> WhenMissingSet f k a

For keys that are present in the set but missing from the map, apply a function, and use the result of the action as the value for the merged map.

generateMaybeAMissingSet :: Applicative f => (k -> f (Maybe a)) -> WhenMissingSet f k a

For keys that are present in the set but missing from the map, apply a function, and maybe use the result of the action as the value for the merged map.

Miscellaneous

runWhenMatched :: WhenMatched f k a b -> k -> a -> f (Maybe b)

Run WhenMatched.

Build record and source files

Community contribution. The service has not verified this documentation. The generator reported 15 diagnostics.

Target: Linux on x86-64. Some inferred types and resolved links are not available.

Generator: aihc-haddock-aa6debbd-web-3

Metadata snapshot: 634f718c0d8cd970c4e2c511d2345d8fd36c6dc32b06343c2b4e914ffccbce7f

Open the dependency plan · Download the documentation model

Import a package

Enter a package name and an exact version from Hackage. The site contains imported versions only.