[Git][ghc/ghc][master] Document differences between Data.{Monoid,Semigroup}.{First,Last}

[Marge Bot (@marge-bot)]

Marge Bot pushed to branch master at Glasgow Haskell Compiler / GHC


Commits:
c9ad8852 by Bodigrim at 2023-01-28T03:00:33-05:00
Document differences between Data.{Monoid,Semigroup}.{First,Last}

- - - - -


2 changed files:

- libraries/base/Data/Monoid.hs
- libraries/base/Data/Semigroup.hs


Changes:

=====================================
libraries/base/Data/Monoid.hs
=====================================
@@ -122,13 +122,19 @@ import Data.Semigroup.Internal
 -- @
 
 
--- | Maybe monoid returning the leftmost non-Nothing value.
+-- | Maybe monoid returning the leftmost non-'Nothing' value.
 --
 -- @'First' a@ is isomorphic to @'Alt' 'Maybe' a@, but precedes it
 -- historically.
 --
 -- >>> getFirst (First (Just "hello") <> First Nothing <> First (Just "world"))
 -- Just "hello"
+--
+-- Beware that @Data.Monoid.@'First' is different from
+-- @Data.Semigroup.@'Data.Semigroup.First'. The former returns the first non-'Nothing',
+-- so @Data.Monoid.First Nothing <> x = x at . The latter simply returns the first value,
+-- thus @Data.Semigroup.First Nothing <> x = Data.Semigroup.First Nothing at .
+--
 newtype First a = First { getFirst :: Maybe a }
         deriving ( Eq          -- ^ @since 2.01
                  , Ord         -- ^ @since 2.01
@@ -151,13 +157,19 @@ instance Semigroup (First a) where
 instance Monoid (First a) where
         mempty = First Nothing
 
--- | Maybe monoid returning the rightmost non-Nothing value.
+-- | Maybe monoid returning the rightmost non-'Nothing' value.
 --
 -- @'Last' a@ is isomorphic to @'Dual' ('First' a)@, and thus to
 -- @'Dual' ('Alt' 'Maybe' a)@
 --
 -- >>> getLast (Last (Just "hello") <> Last Nothing <> Last (Just "world"))
 -- Just "world"
+--
+-- Beware that @Data.Monoid.@'Last' is different from
+-- @Data.Semigroup.@'Data.Semigroup.Last'. The former returns the last non-'Nothing',
+-- so @x <> Data.Monoid.Last Nothing = x at . The latter simply returns the last value,
+-- thus @x <> Data.Semigroup.Last Nothing = Data.Semigroup.Last Nothing at .
+--
 newtype Last a = Last { getLast :: Maybe a }
         deriving ( Eq          -- ^ @since 2.01
                  , Ord         -- ^ @since 2.01


=====================================
libraries/base/Data/Semigroup.hs
=====================================
@@ -357,6 +357,13 @@ instance Bifoldable Arg where
 instance Bitraversable Arg where
   bitraverse f g (Arg a b) = Arg <$> f a <*> g b
 
+-- |
+-- Beware that @Data.Semigroup.@'First' is different from
+-- @Data.Monoid.@'Data.Monoid.First'. The former simply returns the first value,
+-- so @Data.Semigroup.First Nothing <> x = Data.Semigroup.First Nothing at .
+-- The latter returns the first non-'Nothing',
+-- thus @Data.Monoid.First Nothing <> x = x at .
+--
 newtype First a = First { getFirst :: a }
   deriving ( Bounded  -- ^ @since 4.9.0.0
            , Eq       -- ^ @since 4.9.0.0
@@ -413,6 +420,13 @@ instance Monad First where
 instance MonadFix First where
   mfix f = fix (f . getFirst)
 
+-- |
+-- Beware that @Data.Semigroup.@'Last' is different from
+-- @Data.Monoid.@'Data.Monoid.Last'. The former simply returns the last value,
+-- so @x <> Data.Semigroup.Last Nothing = Data.Semigroup.Last Nothing at .
+-- The latter returns the last non-'Nothing',
+-- thus @x <> Data.Monoid.Last Nothing = x at .
+--
 newtype Last a = Last { getLast :: a }
   deriving ( Bounded  -- ^ @since 4.9.0.0
            , Eq       -- ^ @since 4.9.0.0



View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/c9ad8852bdd083f8692361134bc247a1eb2bbd77

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/c9ad8852bdd083f8692361134bc247a1eb2bbd77
You're receiving this email because of your account on gitlab.haskell.org.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-commits/attachments/20230128/f73f2a7b/attachment-0001.html>