-- |
-- This module defines an API for writing functions that merge a map and a
-- set into a map. The key functions are 'Data.Map.Merge.Set.Lazy.merge' and
-- 'Data.Map.Merge.Set.Lazy.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 'Data.Map.Merge.Set.Strict.mapMissing' from "Data.Map.Merge.Set.Strict"
-- then the results will be forced before they are inserted. If you use
-- 'Data.Map.Merge.Set.Lazy.mapMissing' from this module then they will not.
--
-- @since 0.8.1
--
module Data.Map.Merge.Set.Lazy
  (
  -- ** Simple merge tactic types
    M.SimpleWhenMissing
  , Internal.SimpleWhenMissingSet
  , Internal.SimpleWhenMatched

  -- ** General combining function
  , Internal.merge

  -- *** @WhenMatched@ tactics
  , Internal.dropMatched
  , Internal.filterMatched
  , mapMatched
  , mapMaybeMatched

  -- *** @WhenMissing@ tactics
  , M.dropMissing
  , M.preserveMissing
  , M.mapMissing
  , M.filterMissing
  , M.mapMaybeMissing

  -- *** @WhenMissingSet@ tactics
  , Internal.dropMissingSet
  , generateMissingSet
  , generateMaybeMissingSet

  -- ** Applicative merge tactic types
  , M.WhenMissing
  , Internal.WhenMissingSet
  , Internal.WhenMatched

  -- ** General combining function
  , Internal.mergeA

  -- *** @WhenMatched@ tactics
  , Internal.filterAMatched
  , traverseMatched
  , traverseMaybeMatched

  -- *** @WhenMissing@ tactics
  , M.filterAMissing
  , M.traverseMissing
  , M.traverseMaybeMissing
  , M.whenMissing

  -- *** @WhenMissingSet@ tactics
  , generateAMissingSet
  , generateMaybeAMissingSet

  -- ** Miscellaneous
  , Internal.runWhenMatched
  , Internal.runWhenMissingSet
  ) where

import qualified Data.Map.Internal as M
import qualified Data.Map.Merge.Set.Internal as Internal
import Data.Map.Merge.Set.Internal (WhenMatched(..), WhenMissingSet(..))

-- | 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.
--
-- @since 0.8.1
mapMatched :: Applicative f => (k -> a -> b) -> WhenMatched f k a b
mapMatched :: forall (f :: * -> *) k a b.
Applicative f =>
(k -> a -> b) -> WhenMatched f k a b
mapMatched k -> a -> b
f = (k -> a -> f (Maybe b)) -> WhenMatched f k a b
forall (f :: * -> *) k a b.
(k -> a -> f (Maybe b)) -> WhenMatched f k a b
WhenMatched (\k
k a
x -> Maybe b -> f (Maybe b)
forall a. a -> f a
forall (f :: * -> *) a. Applicative f => a -> f a
pure (b -> Maybe b
forall a. a -> Maybe a
Just (k -> a -> b
f k
k a
x)))
{-# INLINE mapMatched #-}

-- | 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.
--
-- @since 0.8.1
mapMaybeMatched :: Applicative f => (k -> a -> Maybe b) -> WhenMatched f k a b
mapMaybeMatched :: forall (f :: * -> *) k a b.
Applicative f =>
(k -> a -> Maybe b) -> WhenMatched f k a b
mapMaybeMatched k -> a -> Maybe b
f = (k -> a -> f (Maybe b)) -> WhenMatched f k a b
forall (f :: * -> *) k a b.
(k -> a -> f (Maybe b)) -> WhenMatched f k a b
WhenMatched (\k
k a
x -> Maybe b -> f (Maybe b)
forall a. a -> f a
forall (f :: * -> *) a. Applicative f => a -> f a
pure (k -> a -> Maybe b
f k
k a
x))
{-# INLINE mapMaybeMatched #-}

-- | 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.
--
-- @since 0.8.1
traverseMatched :: Functor f => (k -> a -> f b) -> WhenMatched f k a b
traverseMatched :: forall (f :: * -> *) k a b.
Functor f =>
(k -> a -> f b) -> WhenMatched f k a b
traverseMatched k -> a -> f b
f = (k -> a -> f (Maybe b)) -> WhenMatched f k a b
forall (f :: * -> *) k a b.
(k -> a -> f (Maybe b)) -> WhenMatched f k a b
WhenMatched (\k
k a
x -> b -> Maybe b
forall a. a -> Maybe a
Just (b -> Maybe b) -> f b -> f (Maybe b)
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> k -> a -> f b
f k
k a
x)
{-# INLINE traverseMatched #-}

-- | 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.
--
-- @since 0.8.1
traverseMaybeMatched :: (k -> a -> f (Maybe b)) -> WhenMatched f k a b
traverseMaybeMatched :: forall k a (f :: * -> *) b.
(k -> a -> f (Maybe b)) -> WhenMatched f k a b
traverseMaybeMatched = (k -> a -> f (Maybe b)) -> WhenMatched f k a b
forall (f :: * -> *) k a b.
(k -> a -> f (Maybe b)) -> WhenMatched f k a b
WhenMatched

-- | 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.
--
-- @since 0.8.1
generateMissingSet :: Applicative f => (k -> a) -> WhenMissingSet f k a
generateMissingSet :: forall (f :: * -> *) k a.
Applicative f =>
(k -> a) -> WhenMissingSet f k a
generateMissingSet k -> a
f = WhenMissingSet
  { missingSubtree :: Set k -> f (Map k a)
missingSubtree = \Set k
s -> Map k a -> f (Map k a)
forall a. a -> f a
forall (f :: * -> *) a. Applicative f => a -> f a
pure ((k -> a) -> Set k -> Map k a
forall k a. (k -> a) -> Set k -> Map k a
M.fromSet k -> a
f Set k
s)
  , missingKey :: k -> f (Maybe a)
missingKey = \k
k -> Maybe a -> f (Maybe a)
forall a. a -> f a
forall (f :: * -> *) a. Applicative f => a -> f a
pure (a -> Maybe a
forall a. a -> Maybe a
Just (k -> a
f k
k))
  }
{-# INLINE generateMissingSet #-}

-- | 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.
--
-- @since 0.8.1
generateAMissingSet :: Applicative f => (k -> f a) -> WhenMissingSet f k a
generateAMissingSet :: forall (f :: * -> *) k a.
Applicative f =>
(k -> f a) -> WhenMissingSet f k a
generateAMissingSet k -> f a
f = WhenMissingSet
  { missingSubtree :: Set k -> f (Map k a)
missingSubtree = (k -> f a) -> Set k -> f (Map k a)
forall (f :: * -> *) k a.
Applicative f =>
(k -> f a) -> Set k -> f (Map k a)
M.fromSetA k -> f a
f
  , missingKey :: k -> f (Maybe a)
missingKey = \k
k -> a -> Maybe a
forall a. a -> Maybe a
Just (a -> Maybe a) -> f a -> f (Maybe a)
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> k -> f a
f k
k
  }
{-# INLINE generateAMissingSet #-}

-- | 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.
--
-- @since 0.8.1
generateMaybeMissingSet
  :: Applicative f => (k -> Maybe a) -> WhenMissingSet f k a
generateMaybeMissingSet :: forall (f :: * -> *) k a.
Applicative f =>
(k -> Maybe a) -> WhenMissingSet f k a
generateMaybeMissingSet k -> Maybe a
f = WhenMissingSet
  { missingSubtree :: Set k -> f (Map k a)
missingSubtree = \Set k
s -> Map k a -> f (Map k a)
forall a. a -> f a
forall (f :: * -> *) a. Applicative f => a -> f a
pure ((k -> Maybe a) -> Set k -> Map k a
forall k a. (k -> Maybe a) -> Set k -> Map k a
M.fromSetMaybe k -> Maybe a
f Set k
s)
  , missingKey :: k -> f (Maybe a)
missingKey = \k
k -> Maybe a -> f (Maybe a)
forall a. a -> f a
forall (f :: * -> *) a. Applicative f => a -> f a
pure (k -> Maybe a
f k
k)
  }
{-# INLINE generateMaybeMissingSet #-}

-- | 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.
--
-- @since 0.8.1
generateMaybeAMissingSet
  :: Applicative f => (k -> f (Maybe a)) -> WhenMissingSet f k a
generateMaybeAMissingSet :: forall (f :: * -> *) k a.
Applicative f =>
(k -> f (Maybe a)) -> WhenMissingSet f k a
generateMaybeAMissingSet k -> f (Maybe a)
f = WhenMissingSet
  { missingSubtree :: Set k -> f (Map k a)
missingSubtree = (k -> f (Maybe a)) -> Set k -> f (Map k a)
forall (f :: * -> *) k a.
Applicative f =>
(k -> f (Maybe a)) -> Set k -> f (Map k a)
M.fromSetMaybeA k -> f (Maybe a)
f
  , missingKey :: k -> f (Maybe a)
missingKey = k -> f (Maybe a)
f
  }
{-# INLINE generateMaybeAMissingSet #-}