Rename merge modules
authorDavid Feuer <David.Feuer@gmail.com>
Mon, 5 Sep 2016 18:43:29 +0000 (14:43 -0400)
committerDavid Feuer <David.Feuer@gmail.com>
Mon, 5 Sep 2016 18:43:29 +0000 (14:43 -0400)
I think it's more consistent with the rest of the API to name
them `Data.Map.Merge.Lazy` and `Data.Map.Merge.Strict`. This also
gives us the option to add further merge-related modules in the
`Merge` hierarchy. The original names still work for now, but they
are deprecated and hidden from Haddock.

Data/Map/Lazy/Merge.hs
Data/Map/Merge/Lazy.hs [new file with mode: 0644]
Data/Map/Merge/Strict.hs [new file with mode: 0644]
Data/Map/Strict/Merge.hs
containers.cabal
tests/map-properties.hs

index 4d54014..603697c 100644 (file)
@@ -1,23 +1,12 @@
 {-# LANGUAGE CPP #-}
-{-# LANGUAGE BangPatterns #-}
-#if __GLASGOW_HASKELL__
-{-# LANGUAGE DeriveDataTypeable, StandaloneDeriving #-}
-#endif
 #if !defined(TESTING) && __GLASGOW_HASKELL__ >= 703
 {-# LANGUAGE Safe #-}
 #endif
-#if __GLASGOW_HASKELL__ >= 708
-{-# LANGUAGE RoleAnnotations #-}
-{-# LANGUAGE TypeFamilies #-}
-#define USE_MAGIC_PROXY 1
-#endif
-
-#if USE_MAGIC_PROXY
-{-# LANGUAGE MagicHash #-}
-#endif
 
 #include "containers.h"
 
+{-# OPTIONS_HADDOCK hide #-}
+
 -----------------------------------------------------------------------------
 -- |
 -- Module      :  Data.Map.Lazy.Merge
 -- inefficient in many cases and should usually be avoided. The instances
 -- for 'WhenMatched' tactics should not pose any major efficiency problems.
 
-module Data.Map.Lazy.Merge (
-    -- ** Simple merge tactic types
-      SimpleWhenMissing
-    , SimpleWhenMatched
-
-    -- ** General combining function
-    , merge
-
-    -- *** @WhenMatched@ tactics
-    , zipWithMaybeMatched
-    , zipWithMatched
-
-    -- *** @WhenMissing@ tactics
-    , mapMaybeMissing
-    , dropMissing
-    , preserveMissing
-    , mapMissing
-    , filterMissing
-
-    -- ** Applicative merge tactic types
-    , WhenMissing
-    , WhenMatched
-
-    -- ** Applicative general combining function
-    , mergeA
-
-    -- *** @WhenMatched@ tactics
-    -- | The tactics described for 'merge' work for
-    -- 'mergeA' as well. Furthermore, the following
-    -- are available.
-    , zipWithMaybeAMatched
-    , zipWithAMatched
-
-    -- *** @WhenMissing@ tactics
-    -- | The tactics described for 'merge' work for
-    -- 'mergeA' as well. Furthermore, the following
-    -- are available.
-    , traverseMaybeMissing
-    , traverseMissing
-    , filterAMissing
-
-    -- *** Covariant maps for tactics
-    , mapWhenMissing
-    , mapWhenMatched
-
-    -- *** Contravariant maps for tactics
-    , lmapWhenMissing
-    , contramapFirstWhenMatched
-    , contramapSecondWhenMatched
-
-    -- *** Miscellaneous tactic functions
-    , runWhenMatched
-    , runWhenMissing
-    ) where
+module Data.Map.Lazy.Merge {-# DEPRECATED "Use \"Data.Map.Merge.Lazy\"." #-}
+    ( module Data.Map.Merge.Lazy ) where
 
-import Data.Map.Internal
+import Data.Map.Merge.Lazy
diff --git a/Data/Map/Merge/Lazy.hs b/Data/Map/Merge/Lazy.hs
new file mode 100644 (file)
index 0000000..ae4f139
--- /dev/null
@@ -0,0 +1,103 @@
+{-# LANGUAGE CPP #-}
+{-# LANGUAGE BangPatterns #-}
+#if __GLASGOW_HASKELL__
+{-# LANGUAGE DeriveDataTypeable, StandaloneDeriving #-}
+#endif
+#if !defined(TESTING) && __GLASGOW_HASKELL__ >= 703
+{-# LANGUAGE Safe #-}
+#endif
+#if __GLASGOW_HASKELL__ >= 708
+{-# LANGUAGE RoleAnnotations #-}
+{-# LANGUAGE TypeFamilies #-}
+#define USE_MAGIC_PROXY 1
+#endif
+
+#if USE_MAGIC_PROXY
+{-# LANGUAGE MagicHash #-}
+#endif
+
+#include "containers.h"
+
+-----------------------------------------------------------------------------
+-- |
+-- Module      :  Data.Map.Merge.Lazy
+-- Copyright   :  (c) David Feuer 2016
+-- License     :  BSD-style
+-- Maintainer  :  libraries@haskell.org
+-- Stability   :  provisional
+-- Portability :  portable
+--
+-- This module defines an API for writing functions that merge two
+-- maps. 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 'Data.Map.Strict.Merge.mapMissing'
+-- from "Data.Map.Strict.Merge" then the results will be forced before
+-- they are inserted. If you use 'Data.Map.Lazy.Merge.mapMissing' from
+-- this module then they will not.
+--
+-- == Efficiency note
+--
+-- The 'Category', 'Applicative', and 'Monad' instances for 'WhenMissing'
+-- tactics are included because they are valid. However, they are
+-- inefficient in many cases and should usually be avoided. The instances
+-- for 'WhenMatched' tactics should not pose any major efficiency problems.
+
+module Data.Map.Merge.Lazy (
+    -- ** Simple merge tactic types
+      SimpleWhenMissing
+    , SimpleWhenMatched
+
+    -- ** General combining function
+    , merge
+
+    -- *** @WhenMatched@ tactics
+    , zipWithMaybeMatched
+    , zipWithMatched
+
+    -- *** @WhenMissing@ tactics
+    , mapMaybeMissing
+    , dropMissing
+    , preserveMissing
+    , mapMissing
+    , filterMissing
+
+    -- ** Applicative merge tactic types
+    , WhenMissing
+    , WhenMatched
+
+    -- ** Applicative general combining function
+    , mergeA
+
+    -- *** @WhenMatched@ tactics
+    -- | The tactics described for 'merge' work for
+    -- 'mergeA' as well. Furthermore, the following
+    -- are available.
+    , zipWithMaybeAMatched
+    , zipWithAMatched
+
+    -- *** @WhenMissing@ tactics
+    -- | The tactics described for 'merge' work for
+    -- 'mergeA' as well. Furthermore, the following
+    -- are available.
+    , traverseMaybeMissing
+    , traverseMissing
+    , filterAMissing
+
+    -- *** Covariant maps for tactics
+    , mapWhenMissing
+    , mapWhenMatched
+
+    -- *** Contravariant maps for tactics
+    , lmapWhenMissing
+    , contramapFirstWhenMatched
+    , contramapSecondWhenMatched
+
+    -- *** Miscellaneous tactic functions
+    , runWhenMatched
+    , runWhenMissing
+    ) where
+
+import Data.Map.Internal
diff --git a/Data/Map/Merge/Strict.hs b/Data/Map/Merge/Strict.hs
new file mode 100644 (file)
index 0000000..6fcfaf8
--- /dev/null
@@ -0,0 +1,99 @@
+{-# LANGUAGE CPP #-}
+{-# LANGUAGE BangPatterns #-}
+#if __GLASGOW_HASKELL__
+{-# LANGUAGE DeriveDataTypeable, StandaloneDeriving #-}
+#endif
+#if !defined(TESTING) && __GLASGOW_HASKELL__ >= 703
+{-# LANGUAGE Safe #-}
+#endif
+#if __GLASGOW_HASKELL__ >= 708
+{-# LANGUAGE RoleAnnotations #-}
+{-# LANGUAGE TypeFamilies #-}
+#define USE_MAGIC_PROXY 1
+#endif
+
+#if USE_MAGIC_PROXY
+{-# LANGUAGE MagicHash #-}
+#endif
+
+#include "containers.h"
+
+-----------------------------------------------------------------------------
+-- |
+-- Module      :  Data.Map.Merge.Strict
+-- Copyright   :  (c) David Feuer 2016
+-- License     :  BSD-style
+-- Maintainer  :  libraries@haskell.org
+-- Stability   :  provisional
+-- Portability :  portable
+--
+-- This module defines an API for writing functions that merge two
+-- maps. 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 'Data.Map.Strict.Merge.mapMissing'
+-- from this module then the results will be forced before they are
+-- inserted. If you use 'Data.Map.Lazy.Merge.mapMissing' from
+-- "Data.Map.Lazy.Merge" then they will not.
+--
+-- == Efficiency note
+--
+-- The 'Category', 'Applicative', and 'Monad' instances for 'WhenMissing'
+-- tactics are included because they are valid. However, they are
+-- inefficient in many cases and should usually be avoided. The instances
+-- for 'WhenMatched' tactics should not pose any major efficiency problems.
+
+module Data.Map.Merge.Strict (
+    -- ** Simple merge tactic types
+      SimpleWhenMissing
+    , SimpleWhenMatched
+
+    -- ** General combining function
+    , merge
+
+    -- *** @WhenMatched@ tactics
+    , zipWithMaybeMatched
+    , zipWithMatched
+
+    -- *** @WhenMissing@ tactics
+    , mapMaybeMissing
+    , dropMissing
+    , preserveMissing
+    , mapMissing
+    , filterMissing
+
+    -- ** Applicative merge tactic types
+    , WhenMissing
+    , WhenMatched
+
+    -- ** Applicative general combining function
+    , mergeA
+
+    -- *** @WhenMatched@ tactics
+    -- | The tactics described for 'merge' work for
+    -- 'mergeA' as well. Furthermore, the following
+    -- are available.
+    , zipWithMaybeAMatched
+    , zipWithAMatched
+
+    -- *** @WhenMissing@ tactics
+    -- | The tactics described for 'merge' work for
+    -- 'mergeA' as well. Furthermore, the following
+    -- are available.
+    , traverseMaybeMissing
+    , traverseMissing
+    , filterAMissing
+
+    -- ** Covariant maps for tactics
+    , mapWhenMissing
+    , mapWhenMatched
+
+    -- ** Miscellaneous functions on tactics
+
+    , runWhenMatched
+    , runWhenMissing
+    ) where
+
+import Data.Map.Strict.Internal
index f71447e..73d4c5e 100644 (file)
@@ -1,23 +1,12 @@
 {-# LANGUAGE CPP #-}
-{-# LANGUAGE BangPatterns #-}
-#if __GLASGOW_HASKELL__
-{-# LANGUAGE DeriveDataTypeable, StandaloneDeriving #-}
-#endif
 #if !defined(TESTING) && __GLASGOW_HASKELL__ >= 703
 {-# LANGUAGE Safe #-}
 #endif
-#if __GLASGOW_HASKELL__ >= 708
-{-# LANGUAGE RoleAnnotations #-}
-{-# LANGUAGE TypeFamilies #-}
-#define USE_MAGIC_PROXY 1
-#endif
-
-#if USE_MAGIC_PROXY
-{-# LANGUAGE MagicHash #-}
-#endif
 
 #include "containers.h"
 
+{-# OPTIONS_HADDOCK hide #-}
+
 -----------------------------------------------------------------------------
 -- |
 -- Module      :  Data.Map.Strict.Merge
 -- inefficient in many cases and should usually be avoided. The instances
 -- for 'WhenMatched' tactics should not pose any major efficiency problems.
 
-module Data.Map.Strict.Merge (
-    -- ** Simple merge tactic types
-      SimpleWhenMissing
-    , SimpleWhenMatched
-
-    -- ** General combining function
-    , merge
-
-    -- *** @WhenMatched@ tactics
-    , zipWithMaybeMatched
-    , zipWithMatched
-
-    -- *** @WhenMissing@ tactics
-    , mapMaybeMissing
-    , dropMissing
-    , preserveMissing
-    , mapMissing
-    , filterMissing
-
-    -- ** Applicative merge tactic types
-    , WhenMissing
-    , WhenMatched
-
-    -- ** Applicative general combining function
-    , mergeA
-
-    -- *** @WhenMatched@ tactics
-    -- | The tactics described for 'merge' work for
-    -- 'mergeA' as well. Furthermore, the following
-    -- are available.
-    , zipWithMaybeAMatched
-    , zipWithAMatched
-
-    -- *** @WhenMissing@ tactics
-    -- | The tactics described for 'merge' work for
-    -- 'mergeA' as well. Furthermore, the following
-    -- are available.
-    , traverseMaybeMissing
-    , traverseMissing
-    , filterAMissing
-
-    -- ** Covariant maps for tactics
-    , mapWhenMissing
-    , mapWhenMatched
-
-    -- ** Miscellaneous functions on tactics
-
-    , runWhenMatched
-    , runWhenMissing
-    ) where
+module Data.Map.Strict.Merge {-# DEPRECATED "Use \"Data.Map.Merge.Strict\"." #-}
+  ( module Data.Map.Merge.Strict ) where
 
-import Data.Map.Strict.Internal
+import Data.Map.Merge.Strict
index b8ab295..6671ebf 100644 (file)
@@ -50,9 +50,11 @@ Library
         Data.Map
         Data.Map.Lazy
         Data.Map.Lazy.Merge
+        Data.Map.Merge.Lazy
         Data.Map.Strict.Internal
         Data.Map.Strict
         Data.Map.Strict.Merge
+        Data.Map.Merge.Strict
         Data.Map.Internal
         Data.Map.Internal.Debug
         Data.Set.Internal
index 5647292..703f88f 100644 (file)
@@ -2,10 +2,10 @@
 
 #ifdef STRICT
 import Data.Map.Strict as Data.Map hiding (showTree, showTreeWith)
-import Data.Map.Strict.Merge
+import Data.Map.Merge.Strict
 #else
 import Data.Map.Lazy as Data.Map hiding (showTree, showTreeWith)
-import Data.Map.Lazy.Merge
+import Data.Map.Merge.Lazy
 #endif
 import Data.Map.Internal (Map (..), link2, link, bin)
 import Data.Map.Internal.Debug (showTree, showTreeWith, balanced)