Deprecate some functions in Data.Map
authorDavid Feuer <David.Feuer@gmail.com>
Wed, 31 Aug 2016 03:13:18 +0000 (23:13 -0400)
committerDavid Feuer <David.Feuer@gmail.com>
Wed, 31 Aug 2016 03:21:58 +0000 (23:21 -0400)
* `Data.Map` has had several functions documented as deprecated,
but without actual `DEPRECATED` pragmas, for years. Add the
pragmas so we can move toward removal in a couple more major
versions.

* The `showTree` and `showTreeWith` functions don't seem like a
good fit for the public API. I'm deprecating them, but they will
remain available for the foreseeable future in `Data.Map.Base`
or some other internal module.

Data/Map.hs
Data/Map/Base.hs
changelog.md

index ec0326f..dfb0797 100644 (file)
@@ -72,16 +72,14 @@ import Prelude hiding (foldr)
 import Data.Map.Lazy
 import qualified Data.Map.Strict as Strict
 
--- | /Deprecated./ As of version 0.5, replaced by 'Data.Map.Strict.insertWith'.
---
--- /O(log n)/. Same as 'insertWith', but the value being inserted to the map is
+-- | /O(log n)/. Same as 'insertWith', but the value being inserted to the map is
 -- evaluated to WHNF beforehand.
 --
 -- For example, to update a counter:
 --
 -- > insertWith' (+) k 1 m
 --
-
+{-# DEPRECATED insertWith' "As of version 0.5, replaced by 'Data.Map.Strict.insertWith'." #-}
 insertWith' :: Ord k => (a -> a -> a) -> k -> a -> Map k a -> Map k a
 insertWith' = Strict.insertWith
 #if __GLASGOW_HASKELL__
@@ -90,12 +88,9 @@ insertWith' = Strict.insertWith
 {-# INLINE insertWith' #-}
 #endif
 
--- | /Deprecated./ As of version 0.5, replaced by
--- 'Data.Map.Strict.insertWithKey'.
---
--- /O(log n)/. Same as 'insertWithKey', but the value being inserted to the map is
+-- | /O(log n)/. Same as 'insertWithKey', but the value being inserted to the map is
 -- evaluated to WHNF beforehand.
-
+{-# DEPRECATED insertWithKey' "As of version 0.5, replaced by 'Data.Map.Strict.insertWithKey'." #-}
 insertWithKey' :: Ord k => (k -> a -> a -> a) -> k -> a -> Map k a -> Map k a
 -- We do not reuse Data.Map.Strict.insertWithKey, because it is stricter -- it
 -- forces evaluation of the given value.
@@ -106,12 +101,9 @@ insertWithKey' = Strict.insertWithKey
 {-# INLINE insertWithKey' #-}
 #endif
 
--- | /Deprecated./ As of version 0.5, replaced by
--- 'Data.Map.Strict.insertLookupWithKey'.
---
--- /O(log n)/. Same as 'insertLookupWithKey', but the value being inserted to
+-- | /O(log n)/. Same as 'insertLookupWithKey', but the value being inserted to
 -- the map is evaluated to WHNF beforehand.
-
+{-# DEPRECATED insertLookupWithKey' "As of version 0.5, replaced by 'Data.Map.Strict.insertLookupWithKey'." #-}
 insertLookupWithKey' :: Ord k => (k -> a -> a -> a) -> k -> a -> Map k a
                      -> (Maybe a, Map k a)
 -- We do not reuse Data.Map.Strict.insertLookupWithKey, because it is stricter -- it
@@ -123,20 +115,18 @@ insertLookupWithKey' = Strict.insertLookupWithKey
 {-# INLINE insertLookupWithKey' #-}
 #endif
 
--- | /Deprecated./ As of version 0.5, replaced by 'foldr'.
---
--- /O(n)/. Fold the values in the map using the given right-associative
+-- | /O(n)/. Fold the values in the map using the given right-associative
 -- binary operator. This function is an equivalent of 'foldr' and is present
 -- for compatibility only.
+{-# DEPRECATED fold "As of version 0.5, replaced by 'foldr'." #-}
 fold :: (a -> b -> b) -> b -> Map k a -> b
 fold = foldr
 {-# INLINE fold #-}
 
--- | /Deprecated./ As of version 0.4, replaced by 'foldrWithKey'.
---
--- /O(n)/. Fold the keys and values in the map using the given right-associative
+-- | /O(n)/. Fold the keys and values in the map using the given right-associative
 -- binary operator. This function is an equivalent of 'foldrWithKey' and is present
 -- for compatibility only.
+{-# DEPRECATED foldWithKey "As of version 0.4, replaced by 'foldrWithKey'." #-}
 foldWithKey :: (k -> a -> b -> b) -> b -> Map k a -> b
 foldWithKey = foldrWithKey
 {-# INLINE foldWithKey #-}
index 9ebae06..c31a576 100644 (file)
@@ -3965,6 +3965,7 @@ instance (Show k, Show a) => Show (Map k a) where
 
 -- | /O(n)/. Show the tree that implements the map. The tree is shown
 -- in a compressed, hanging format. See 'showTreeWith'.
+{-# DEPRECATED showTree "This function is being removed from the public API." #-}
 showTree :: (Show k,Show a) => Map k a -> String
 showTree m
   = showTreeWith showElem True False m
@@ -4008,6 +4009,7 @@ showTree m
 >     +--(1,())
 
 -}
+{-# DEPRECATED showTreeWith "This function is being removed from the public API." #-}
 showTreeWith :: (k -> a -> String) -> Bool -> Bool -> Map k a -> String
 showTreeWith showelem hang wide t
   | hang      = (showsTreeHang showelem wide [] t) ""
index 8abdb54..d180353 100644 (file)
 
   * Make `drawTree` handle newlines better. (Thanks, recursion-ninja!)
 
+### Deprecations
+
+  * All functions in `Data.Map` proper that have been documented as deprecated since
+    version 0.5 or before now have `DEPRECATED` pragmas and will actually be
+    removed after another cycle or two.
+
+  * Tree printing functions in `Data.Map` intended for library debugging are now
+    deprecated. They will continue to be available for the foreseeable future in
+    an internal module.
+
 ### Performance changes
 
   * Substantially speed up `splitAt`, `zipWith`, `take`, `drop`,