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