Convert to cabal.project
[packages/containers.git] / containers / src / Data / Map / Merge / Strict.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.Strict
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 this module then the results will be forced before they are
37 -- inserted. If you use 'Data.Map.Merge.Lazy.mapMissing' from
38 -- "Data.Map.Merge.Lazy" then they will not.
39 --
40 -- == 'preserveMissing' inconsistency
41 --
42 -- For historical reasons, the preserved values are //not// forced. To force
43 -- them, use 'preserveMissing''.
44 --
45 -- == Efficiency note
46 --
47 -- The 'Control.Category.Category', 'Applicative', and 'Monad' instances for
48 -- 'WhenMissing' tactics are included because they are valid. However, they are
49 -- inefficient in many cases and should usually be avoided. The instances
50 -- for 'WhenMatched' tactics should not pose any major efficiency problems.
51 --
52 -- @since 0.5.9
53
54 module Data.Map.Merge.Strict (
55 -- ** Simple merge tactic types
56 SimpleWhenMissing
57 , SimpleWhenMatched
58
59 -- ** General combining function
60 , merge
61
62 -- *** @WhenMatched@ tactics
63 , zipWithMaybeMatched
64 , zipWithMatched
65
66 -- *** @WhenMissing@ tactics
67 , mapMaybeMissing
68 , dropMissing
69 , preserveMissing
70 , preserveMissing'
71 , mapMissing
72 , filterMissing
73
74 -- ** Applicative merge tactic types
75 , WhenMissing
76 , WhenMatched
77
78 -- ** Applicative general combining function
79 , mergeA
80
81 -- *** @WhenMatched@ tactics
82 -- | The tactics described for 'merge' work for
83 -- 'mergeA' as well. Furthermore, the following
84 -- are available.
85 , zipWithMaybeAMatched
86 , zipWithAMatched
87
88 -- *** @WhenMissing@ tactics
89 -- | The tactics described for 'merge' work for
90 -- 'mergeA' as well. Furthermore, the following
91 -- are available.
92 , traverseMaybeMissing
93 , traverseMissing
94 , filterAMissing
95
96 -- ** Covariant maps for tactics
97 , mapWhenMissing
98 , mapWhenMatched
99
100 -- ** Miscellaneous functions on tactics
101
102 , runWhenMatched
103 , runWhenMissing
104 ) where
105
106 import Data.Map.Strict.Internal