Convert to cabal.project
[packages/containers.git] / containers / src / Data / Map / Merge / Lazy.hs
1 {-# LANGUAGE CPP #-}
2 {-# LANGUAGE BangPatterns #-}
3 #if __GLASGOW_HASKELL__
4 {-# LANGUAGE DeriveDataTypeable, StandaloneDeriving #-}
5 #endif
6 #if !defined(TESTING) && defined(__GLASGOW_HASKELL__)
7 {-# LANGUAGE Safe #-}
8 #endif
9 #if __GLASGOW_HASKELL__ >= 708
10 {-# LANGUAGE RoleAnnotations #-}
11 {-# LANGUAGE TypeFamilies #-}
12 #define USE_MAGIC_PROXY 1
13 #endif
14
15 #if USE_MAGIC_PROXY
16 {-# LANGUAGE MagicHash #-}
17 #endif
18
19 #include "containers.h"
20
21 -----------------------------------------------------------------------------
22 -- |
23 -- Module : Data.Map.Merge.Lazy
24 -- Copyright : (c) David Feuer 2016
25 -- License : BSD-style
26 -- Maintainer : libraries@haskell.org
27 -- Portability : portable
28 --
29 -- This module defines an API for writing functions that merge two
30 -- maps. The key functions are 'merge' and 'mergeA'.
31 -- Each of these can be used with several different \"merge tactics\".
32 --
33 -- The 'merge' and 'mergeA' functions are shared by
34 -- the lazy and strict modules. Only the choice of merge tactics
35 -- determines strictness. If you use 'Data.Map.Merge.Strict.mapMissing'
36 -- from "Data.Map.Merge.Strict" then the results will be forced before
37 -- they are inserted. If you use 'Data.Map.Merge.Lazy.mapMissing' from
38 -- this module then they will not.
39 --
40 -- == Efficiency note
41 --
42 -- The 'Control.Category.Category', 'Applicative', and 'Monad' instances for
43 -- 'WhenMissing' tactics are included because they are valid. However, they are
44 -- inefficient in many cases and should usually be avoided. The instances
45 -- for 'WhenMatched' tactics should not pose any major efficiency problems.
46 --
47 -- @since 0.5.9
48
49 module Data.Map.Merge.Lazy (
50 -- ** Simple merge tactic types
51 SimpleWhenMissing
52 , SimpleWhenMatched
53
54 -- ** General combining function
55 , merge
56
57 -- *** @WhenMatched@ tactics
58 , zipWithMaybeMatched
59 , zipWithMatched
60
61 -- *** @WhenMissing@ tactics
62 , mapMaybeMissing
63 , dropMissing
64 , preserveMissing
65 , mapMissing
66 , filterMissing
67
68 -- ** Applicative merge tactic types
69 , WhenMissing
70 , WhenMatched
71
72 -- ** Applicative general combining function
73 , mergeA
74
75 -- *** @WhenMatched@ tactics
76 -- | The tactics described for 'merge' work for
77 -- 'mergeA' as well. Furthermore, the following
78 -- are available.
79 , zipWithMaybeAMatched
80 , zipWithAMatched
81
82 -- *** @WhenMissing@ tactics
83 -- | The tactics described for 'merge' work for
84 -- 'mergeA' as well. Furthermore, the following
85 -- are available.
86 , traverseMaybeMissing
87 , traverseMissing
88 , filterAMissing
89
90 -- *** Covariant maps for tactics
91 , mapWhenMissing
92 , mapWhenMatched
93
94 -- *** Contravariant maps for tactics
95 , lmapWhenMissing
96 , contramapFirstWhenMatched
97 , contramapSecondWhenMatched
98
99 -- *** Miscellaneous tactic functions
100 , runWhenMatched
101 , runWhenMissing
102 ) where
103
104 import Data.Map.Internal