Update changelog and since annotations for Data.List.NonEmpty.permuta…

…tions

Approved by CLC in haskell/core-libraries-committee#68 (comment)

libraries/base/changelog.md

@@ -2,6 +2,7 @@
 
 ## 4.20.0.0 *TBA*
   * Export `foldl'` from `Prelude` ([CLC proposal #167](https://github.com/haskell/core-libraries-committee/issues/167))
+  * Add `permutations` and `permutations1` to `Data.List.NonEmpty` ([CLC proposal #68](https://github.com/haskell/core-libraries-committee/issues/68))
   * Add a `RULE` to `Prelude.lookup`, allowing it to participate in list fusion ([CLC proposal #174](https://github.com/haskell/core-libraries-committee/issues/175))
   * The `Enum Int64` and `Enum Word64` instances now use native operations on 32-bit platforms, increasing performance by up to 1.5x on i386 and up to 5.6x with the JavaScript backend. ([CLC proposal #187](https://github.com/haskell/core-libraries-committee/issues/187))
   * Update to [Unicode 15.1.0](https://www.unicode.org/versions/Unicode15.1.0/).

libraries/base/src/Data/List/NonEmpty.hs

@@ -444,6 +444,8 @@ groupAllWith1 :: (Ord b) => (a -> b) -> NonEmpty a -> NonEmpty (NonEmpty a)
 groupAllWith1 f = groupWith1 f . sortWith f
 
 -- | The 'permutations' function returns the list of all permutations of the argument.
+--
+-- @since 4.20.0.0
 permutations            :: [a] -> NonEmpty [a]
 permutations xs0        =  xs0 :| perms xs0 []
   where
@@ -453,9 +455,15 @@ permutations xs0        =  xs0 :| perms xs0 []
             interleave' _ []     r = (ts, r)
             interleave' f (y:ys) r = let (us,zs) = interleave' (f . (y:)) ys r
                                      in  (y:us, f (t:y:us) : zs)
+-- The implementation of 'permutations' is adopted from 'Data.List.permutations',
+-- see there for discussion and explanations.
 
 -- | 'permutations1' operates like 'permutations', but uses the knowledge that its input is
--- non-empty to produce output which every element is non-empty.
+-- non-empty to produce output where every element is non-empty.
+--
+-- > permutations1 = fmap fromList . permutations . toList
+--
+-- @since 4.20.0.0
 permutations1 :: NonEmpty a -> NonEmpty (NonEmpty a)
 permutations1 xs = fromList <$> permutations (toList xs)
 

testsuite/tests/interface-stability/base-exports.stdout

@@ -1410,6 +1410,8 @@ module Data.List.NonEmpty where
   nub :: forall a. GHC.Classes.Eq a => NonEmpty a -> NonEmpty a
   nubBy :: forall a. (a -> a -> GHC.Types.Bool) -> NonEmpty a -> NonEmpty a
   partition :: forall a. (a -> GHC.Types.Bool) -> NonEmpty a -> ([a], [a])
+  permutations :: forall a. [a] -> NonEmpty [a]
+  permutations1 :: forall a. NonEmpty a -> NonEmpty (NonEmpty a)
   prependList :: forall a. [a] -> NonEmpty a -> NonEmpty a
   repeat :: forall a. a -> NonEmpty a
   reverse :: forall a. NonEmpty a -> NonEmpty a

testsuite/tests/interface-stability/base-exports.stdout-javascript-unknown-ghcjs

@@ -1410,6 +1410,8 @@ module Data.List.NonEmpty where
   nub :: forall a. GHC.Classes.Eq a => NonEmpty a -> NonEmpty a
   nubBy :: forall a. (a -> a -> GHC.Types.Bool) -> NonEmpty a -> NonEmpty a
   partition :: forall a. (a -> GHC.Types.Bool) -> NonEmpty a -> ([a], [a])
+  permutations :: forall a. [a] -> NonEmpty [a]
+  permutations1 :: forall a. NonEmpty a -> NonEmpty (NonEmpty a)
   prependList :: forall a. [a] -> NonEmpty a -> NonEmpty a
   repeat :: forall a. a -> NonEmpty a
   reverse :: forall a. NonEmpty a -> NonEmpty a

testsuite/tests/interface-stability/base-exports.stdout-mingw32

@@ -1410,6 +1410,8 @@ module Data.List.NonEmpty where
   nub :: forall a. GHC.Classes.Eq a => NonEmpty a -> NonEmpty a
   nubBy :: forall a. (a -> a -> GHC.Types.Bool) -> NonEmpty a -> NonEmpty a
   partition :: forall a. (a -> GHC.Types.Bool) -> NonEmpty a -> ([a], [a])
+  permutations :: forall a. [a] -> NonEmpty [a]
+  permutations1 :: forall a. NonEmpty a -> NonEmpty (NonEmpty a)
   prependList :: forall a. [a] -> NonEmpty a -> NonEmpty a
   repeat :: forall a. a -> NonEmpty a
   reverse :: forall a. NonEmpty a -> NonEmpty a

testsuite/tests/interface-stability/base-exports.stdout-ws-32

@@ -1410,6 +1410,8 @@ module Data.List.NonEmpty where
   nub :: forall a. GHC.Classes.Eq a => NonEmpty a -> NonEmpty a
   nubBy :: forall a. (a -> a -> GHC.Types.Bool) -> NonEmpty a -> NonEmpty a
   partition :: forall a. (a -> GHC.Types.Bool) -> NonEmpty a -> ([a], [a])
+  permutations :: forall a. [a] -> NonEmpty [a]
+  permutations1 :: forall a. NonEmpty a -> NonEmpty (NonEmpty a)
   prependList :: forall a. [a] -> NonEmpty a -> NonEmpty a
   repeat :: forall a. a -> NonEmpty a
   reverse :: forall a. NonEmpty a -> NonEmpty a