diff options
| author | Bodigrim <andrew.lelechenko@gmail.com> | 2023-01-26 22:57:32 +0000 |
|---|---|---|
| committer | Marge Bot <ben+marge-bot@smart-cactus.org> | 2023-01-28 03:00:33 -0500 |
| commit | c9ad8852bdd083f8692361134bc247a1eb2bbd77 (patch) | |
| tree | 6678b132b7d085524a7124e5f5f5506da9003851 | |
| parent | 3330b819afa1235d870b9373bd5c39a772a20ff8 (diff) | |
| download | haskell-c9ad8852bdd083f8692361134bc247a1eb2bbd77.tar.gz | |
Document differences between Data.{Monoid,Semigroup}.{First,Last}
| -rw-r--r-- | libraries/base/Data/Monoid.hs | 16 | ||||
| -rw-r--r-- | libraries/base/Data/Semigroup.hs | 14 |
2 files changed, 28 insertions, 2 deletions
diff --git a/libraries/base/Data/Monoid.hs b/libraries/base/Data/Monoid.hs index beb5917e59..ac4e6b8523 100644 --- a/libraries/base/Data/Monoid.hs +++ b/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@. The latter simply returns the first value, +-- thus @Data.Semigroup.First Nothing <> x = Data.Semigroup.First Nothing@. +-- 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@. The latter simply returns the last value, +-- thus @x <> Data.Semigroup.Last Nothing = Data.Semigroup.Last Nothing@. +-- newtype Last a = Last { getLast :: Maybe a } deriving ( Eq -- ^ @since 2.01 , Ord -- ^ @since 2.01 diff --git a/libraries/base/Data/Semigroup.hs b/libraries/base/Data/Semigroup.hs index 256f2761fd..f318b76bb8 100644 --- a/libraries/base/Data/Semigroup.hs +++ b/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@. +-- The latter returns the first non-'Nothing', +-- thus @Data.Monoid.First Nothing <> x = x@. +-- 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@. +-- The latter returns the last non-'Nothing', +-- thus @x <> Data.Monoid.Last Nothing = x@. +-- newtype Last a = Last { getLast :: a } deriving ( Bounded -- ^ @since 4.9.0.0 , Eq -- ^ @since 4.9.0.0 |