Add practical examples in alterF Haddocks (#1216)

Author: meooow25

containers/src/Data/IntMap/Internal.hs

@@ -1145,27 +1145,26 @@ alter f k Nil     = case f Nothing of
 -- or update a value in an 'IntMap'.  In short : @'lookup' k \<$\> 'alterF' f k m = f
 -- ('lookup' k m)@.
 --
--- Example:
---
--- @
--- interactiveAlter :: Int -> IntMap String -> IO (IntMap String)
--- interactiveAlter k m = alterF f k m where
---   f Nothing = do
---      putStrLn $ show k ++
---          " was not found in the map. Would you like to add it?"
---      getUserResponse1 :: IO (Maybe String)
---   f (Just old) = do
---      putStrLn $ "The key is currently bound to " ++ show old ++
---          ". Would you like to change or delete it?"
---      getUserResponse2 :: IO (Maybe String)
--- @
---
 -- 'alterF' is the most general operation for working with an individual
 -- key that may or may not be in a given map.
 --
 -- Note: 'alterF' is a flipped version of the @at@ combinator from
 -- @Control.Lens.At@.
 --
+-- === Examples
+--
+-- @
+-- -- Lookup the value at the key, and also remove the existing value or set a new value.
+-- lookupAndSet :: Key -> Maybe a -> IntMap a -> (Maybe a, IntMap a)
+-- lookupAndSet k new = alterF (\\old -> (old, new)) k
+-- @
+--
+-- @
+-- -- Delete the value at the key. If it is absent the result is Nothing.
+-- mustDelete :: Key -> IntMap a -> Maybe (IntMap a)
+-- mustDelete = alterF (Nothing <$)
+-- @
+--
 -- @since 0.5.8
 
 alterF :: Functor f

containers/src/Data/IntMap/Strict/Internal.hs

@@ -601,27 +601,26 @@ alter f !k t =
 -- or update a value in an 'IntMap'.  In short : @'lookup' k \<$\> 'alterF' f k m = f
 -- ('lookup' k m)@.
 --
--- Example:
---
--- @
--- interactiveAlter :: Int -> IntMap String -> IO (IntMap String)
--- interactiveAlter k m = alterF f k m where
---   f Nothing = do
---      putStrLn $ show k ++
---          " was not found in the map. Would you like to add it?"
---      getUserResponse1 :: IO (Maybe String)
---   f (Just old) = do
---      putStrLn $ "The key is currently bound to " ++ show old ++
---          ". Would you like to change or delete it?"
---      getUserResponse2 :: IO (Maybe String)
--- @
---
 -- 'alterF' is the most general operation for working with an individual
 -- key that may or may not be in a given map.
-
+--
 -- Note: 'alterF' is a flipped version of the 'at' combinator from
 -- 'Control.Lens.At'.
 --
+-- === Examples
+--
+-- @
+-- -- Lookup the value at the key, and also remove the existing value or set a new value.
+-- lookupAndSet :: Key -> Maybe a -> IntMap a -> (Maybe a, IntMap a)
+-- lookupAndSet k new = alterF (\\old -> (old, new)) k
+-- @
+--
+-- @
+-- -- Delete the value at the key. If it is absent the result is Nothing.
+-- mustDelete :: Key -> IntMap a -> Maybe (IntMap a)
+-- mustDelete = alterF (Nothing <$)
+-- @
+--
 -- @since 0.5.8
 
 alterF :: Functor f

containers/src/Data/IntSet/Internal.hs

@@ -608,6 +608,20 @@ pop x0 t0 = case go x0 t0 of
 --
 -- Note: 'alterF' is a variant of the @at@ combinator from "Control.Lens.At".
 --
+-- === Examples
+--
+-- @
+-- -- Get whether the element is a member, and also insert or remove it.
+-- getAndSet :: Key -> Bool -> IntSet -> (Bool, IntSet)
+-- getAndSet x new = alterF (\\old -> (old, new)) x
+-- @
+--
+-- @
+-- -- Delete the element. If it is absent the result is Nothing.
+-- mustDelete :: Key -> IntSet -> Maybe IntSet
+-- mustDelete = alterF (\\b -> if b then Just False else Nothing)
+-- @
+--
 -- @since 0.6.3.1
 alterF :: Functor f => (Bool -> f Bool) -> Key -> IntSet -> f IntSet
 alterF f k s = fmap choose (f member_)

containers/src/Data/Map/Internal.hs

@@ -1161,21 +1161,6 @@ data AreWeStrict = Strict | Lazy
 -- or update a value in a 'Map'.  In short: @'lookup' k \<$\> 'alterF' f k m = f
 -- ('lookup' k m)@.
 --
--- Example:
---
--- @
--- interactiveAlter :: Int -> Map Int String -> IO (Map Int String)
--- interactiveAlter k m = alterF f k m where
---   f Nothing = do
---      putStrLn $ show k ++
---          " was not found in the map. Would you like to add it?"
---      getUserResponse1 :: IO (Maybe String)
---   f (Just old) = do
---      putStrLn $ "The key is currently bound to " ++ show old ++
---          ". Would you like to change or delete it?"
---      getUserResponse2 :: IO (Maybe String)
--- @
---
 -- 'alterF' is the most general operation for working with an individual
 -- key that may or may not be in a given map. When used with trivial
 -- functors like 'Identity' and 'Const', it is often slightly slower than
@@ -1196,6 +1181,20 @@ data AreWeStrict = Strict | Lazy
 -- Note: 'alterF' is a flipped version of the @at@ combinator from
 -- @Control.Lens.At@.
 --
+-- === Examples
+--
+-- @
+-- -- Lookup the value at the key, and also remove the existing value or set a new value.
+-- lookupAndSet :: Ord k => k -> Maybe a -> Map k a -> (Maybe a, Map k a)
+-- lookupAndSet k new = alterF (\\old -> (old, new)) k
+-- @
+--
+-- @
+-- -- Delete the value at the key. If it is absent the result is Nothing.
+-- mustDelete :: Ord k => k -> Map k a -> Maybe (Map k a)
+-- mustDelete = alterF (Nothing <$)
+-- @
+--
 -- @since 0.5.8
 alterF :: (Functor f, Ord k)
        => (Maybe a -> f (Maybe a)) -> k -> Map k a -> f (Map k a)

containers/src/Data/Map/Strict/Internal.hs

@@ -745,21 +745,6 @@ alter = go
 -- 'alterF' can be used to inspect, insert, delete, or update a value in a 'Map'.
 -- In short: @'lookup' k \<$\> 'alterF' f k m = f ('lookup' k m)@.
 --
--- Example:
---
--- @
--- interactiveAlter :: Int -> Map Int String -> IO (Map Int String)
--- interactiveAlter k m = alterF f k m where
---   f Nothing = do
---      putStrLn $ show k ++
---          " was not found in the map. Would you like to add it?"
---      getUserResponse1 :: IO (Maybe String)
---   f (Just old) = do
---      putStrLn $ "The key is currently bound to " ++ show old ++
---          ". Would you like to change or delete it?"
---      getUserResponse2 :: IO (Maybe String)
--- @
---
 -- 'alterF' is the most general operation for working with an individual
 -- key that may or may not be in a given map. When used with trivial
 -- functors like 'Identity' and 'Const', it is often slightly slower than
@@ -780,6 +765,20 @@ alter = go
 -- Note: 'alterF' is a flipped version of the @at@ combinator from
 -- @Control.Lens.At@.
 --
+-- === Examples
+--
+-- @
+-- -- Lookup the value at the key, and also remove the existing value or set a new value.
+-- lookupAndSet :: Ord k => k -> Maybe a -> Map k a -> (Maybe a, Map k a)
+-- lookupAndSet k new = alterF (\\old -> (old, new)) k
+-- @
+--
+-- @
+-- -- Delete the value at the key. If it is absent the result is Nothing.
+-- mustDelete :: Ord k => k -> Map k a -> Maybe (Map k a)
+-- mustDelete = alterF (Nothing <$)
+-- @
+--
 -- @since 0.5.8
 alterF :: (Functor f, Ord k)
        => (Maybe a -> f (Maybe a)) -> k -> Map k a -> f (Map k a)

containers/src/Data/Set/Internal.hs

@@ -614,6 +614,20 @@ pop x0 t0 = case go x0 t0 of
 --
 -- Note: 'alterF' is a variant of the @at@ combinator from "Control.Lens.At".
 --
+-- === Examples
+--
+-- @
+-- -- Get whether the element is a member, and also insert or remove it.
+-- getAndSet :: Ord a => a -> Bool -> Set a -> (Bool, Set a)
+-- getAndSet x new = alterF (\\old -> (old, new)) x
+-- @
+--
+-- @
+-- -- Delete the element. If it is absent the result is Nothing.
+-- mustDelete :: Ord a => a -> Set a -> Maybe (Set a)
+-- mustDelete = alterF (\\b -> if b then Just False else Nothing)
+-- @
+--
 -- @since 0.6.3.1
 
 -- See Note [alterF implementation]