[Git][ghc/ghc][master] feat: Add sortOn to Data.List.NonEmpty

Marge Bot (@marge-bot) gitlab at gitlab.haskell.org
Thu Feb 15 14:41:33 UTC 2024 


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


Commits:
264a4fa9 by Owen Shepherd at 2024-02-15T09:41:06-05:00
feat: Add sortOn to Data.List.NonEmpty

Adds `sortOn` to `Data.List.NonEmpty`, and adds
comments describing when to use it, compared to
`sortWith` or `sortBy . comparing`.

The aim is to smooth out the API between
`Data.List`, and `Data.List.NonEmpty`.

This change has been discussed in the
[clc issue](https://github.com/haskell/core-libraries-committee/issues/227).

- - - - -


7 changed files:

- libraries/base/changelog.md
- libraries/base/src/Data/List/NonEmpty.hs
- libraries/ghc-internal/src/Data/OldList.hs
- testsuite/tests/interface-stability/base-exports.stdout
- testsuite/tests/interface-stability/base-exports.stdout-javascript-unknown-ghcjs
- testsuite/tests/interface-stability/base-exports.stdout-mingw32
- testsuite/tests/interface-stability/base-exports.stdout-ws-32


Changes:

=====================================
libraries/base/changelog.md
=====================================
@@ -33,6 +33,8 @@
     then the constraint `DataToTag t` can always be solved.
 
     ([CLC proposal #104](https://github.com/haskell/core-libraries-committee/issues/104))
+  * Add `sortOn` to `Data.List.NonEmpty`
+    ([CLC proposal #227](https://github.com/haskell/core-libraries-committee/issues/227))
 
   * Add more instances for `Compose`: `Fractional`, `RealFrac`, `Floating`, `RealFloat` ([CLC proposal #226](https://github.com/haskell/core-libraries-committee/issues/226))
 


=====================================
libraries/base/src/Data/List/NonEmpty.hs
=====================================
@@ -45,6 +45,7 @@ module Data.List.NonEmpty (
    , uncons      -- :: NonEmpty a -> (a, Maybe (NonEmpty a))
    , unfoldr     -- :: (a -> (b, Maybe a)) -> a -> NonEmpty b
    , sort        -- :: Ord a => NonEmpty a -> NonEmpty a
+   , sortOn      -- :: Ord b => (a -> b) -> NonEmpty a -> NonEmpty a
    , reverse     -- :: NonEmpty a -> NonEmpty a
    , inits       -- :: Foldable f => f a -> NonEmpty [a]
    , inits1      -- :: NonEmpty a -> NonEmpty (NonEmpty a)
@@ -196,6 +197,39 @@ cons = (<|)
 sort :: Ord a => NonEmpty a -> NonEmpty a
 sort = lift List.sort
 
+-- | Sort a 'NonEmpty' on a user-supplied projection of its elements.
+-- See 'List.sortOn' for more detailed information.
+--
+-- ==== __Examples__
+--
+-- >>> sortOn fst $ (2, "world") :| [(4, "!"), (1, "Hello")]
+-- (1,"Hello") :| [(2,"world"),(4,"!")]
+--
+-- >>> sortOn length $ "jim" :| ["creed", "pam", "michael", "dwight", "kevin"]
+-- "jim" :| ["pam","creed","kevin","dwight","michael"]
+--
+-- ==== __Performance notes__
+--
+-- This function minimises the projections performed, by materialising
+-- the projections in an intermediate list.
+--
+-- For trivial projections, you should prefer using 'sortBy' with
+-- 'comparing', for example:
+--
+-- >>> sortBy (comparing fst) $ (3, 1) :| [(2, 2), (1, 3)]
+-- (1,3) :| [(2,2),(3,1)]
+--
+-- Or, for the exact same API as 'sortOn', you can use `sortBy . comparing`:
+--
+-- >>> (sortBy . comparing) fst $ (3, 1) :| [(2, 2), (1, 3)]
+-- (1,3) :| [(2,2),(3,1)]
+--
+-- 'sortWith' is an alias for `sortBy . comparing`.
+--
+-- @since 4.20.0.0
+sortOn :: Ord b => (a -> b) -> NonEmpty a -> NonEmpty a
+sortOn f = lift (List.sortOn f)
+
 -- | Converts a normal list to a 'NonEmpty' stream.
 --
 -- Raises an error if given an empty list.


=====================================
libraries/ghc-internal/src/Data/OldList.hs
=====================================
@@ -1798,6 +1798,22 @@ rqpart cmp x (y:ys) rle rgt r =
 -- >>> sortOn length ["jim", "creed", "pam", "michael", "dwight", "kevin"]
 -- ["jim","pam","creed","kevin","dwight","michael"]
 --
+-- ==== __Performance notes__
+--
+-- This function minimises the projections performed, by materialising
+-- the projections in an intermediate list.
+--
+-- For trivial projections, you should prefer using 'sortBy' with
+-- 'comparing', for example:
+--
+-- >>> sortBy (comparing fst) [(3, 1), (2, 2), (1, 3)]
+-- [(1,3),(2,2),(3,1)]
+--
+-- Or, for the exact same API as 'sortOn', you can use `sortBy . comparing`:
+--
+-- >>> (sortBy . comparing) fst [(3, 1), (2, 2), (1, 3)]
+-- [(1,3),(2,2),(3,1)]
+--
 -- @since 4.8.0.0
 sortOn :: Ord b => (a -> b) -> [a] -> [a]
 sortOn f =


=====================================
testsuite/tests/interface-stability/base-exports.stdout
=====================================
@@ -1423,6 +1423,7 @@ module Data.List.NonEmpty where
   some1 :: forall (f :: * -> *) a. GHC.Base.Alternative f => f a -> f (NonEmpty a)
   sort :: forall a. GHC.Classes.Ord a => NonEmpty a -> NonEmpty a
   sortBy :: forall a. (a -> a -> GHC.Types.Ordering) -> NonEmpty a -> NonEmpty a
+  sortOn :: forall b a. GHC.Classes.Ord b => (a -> b) -> NonEmpty a -> NonEmpty a
   sortWith :: forall o a. GHC.Classes.Ord o => (a -> o) -> NonEmpty a -> NonEmpty a
   span :: forall a. (a -> GHC.Types.Bool) -> NonEmpty a -> ([a], [a])
   splitAt :: forall a. GHC.Types.Int -> NonEmpty a -> ([a], [a])


=====================================
testsuite/tests/interface-stability/base-exports.stdout-javascript-unknown-ghcjs
=====================================
@@ -1423,6 +1423,7 @@ module Data.List.NonEmpty where
   some1 :: forall (f :: * -> *) a. GHC.Base.Alternative f => f a -> f (NonEmpty a)
   sort :: forall a. GHC.Classes.Ord a => NonEmpty a -> NonEmpty a
   sortBy :: forall a. (a -> a -> GHC.Types.Ordering) -> NonEmpty a -> NonEmpty a
+  sortOn :: forall b a. GHC.Classes.Ord b => (a -> b) -> NonEmpty a -> NonEmpty a
   sortWith :: forall o a. GHC.Classes.Ord o => (a -> o) -> NonEmpty a -> NonEmpty a
   span :: forall a. (a -> GHC.Types.Bool) -> NonEmpty a -> ([a], [a])
   splitAt :: forall a. GHC.Types.Int -> NonEmpty a -> ([a], [a])


=====================================
testsuite/tests/interface-stability/base-exports.stdout-mingw32
=====================================
@@ -1423,6 +1423,7 @@ module Data.List.NonEmpty where
   some1 :: forall (f :: * -> *) a. GHC.Base.Alternative f => f a -> f (NonEmpty a)
   sort :: forall a. GHC.Classes.Ord a => NonEmpty a -> NonEmpty a
   sortBy :: forall a. (a -> a -> GHC.Types.Ordering) -> NonEmpty a -> NonEmpty a
+  sortOn :: forall b a. GHC.Classes.Ord b => (a -> b) -> NonEmpty a -> NonEmpty a
   sortWith :: forall o a. GHC.Classes.Ord o => (a -> o) -> NonEmpty a -> NonEmpty a
   span :: forall a. (a -> GHC.Types.Bool) -> NonEmpty a -> ([a], [a])
   splitAt :: forall a. GHC.Types.Int -> NonEmpty a -> ([a], [a])


=====================================
testsuite/tests/interface-stability/base-exports.stdout-ws-32
=====================================
@@ -1423,6 +1423,7 @@ module Data.List.NonEmpty where
   some1 :: forall (f :: * -> *) a. GHC.Base.Alternative f => f a -> f (NonEmpty a)
   sort :: forall a. GHC.Classes.Ord a => NonEmpty a -> NonEmpty a
   sortBy :: forall a. (a -> a -> GHC.Types.Ordering) -> NonEmpty a -> NonEmpty a
+  sortOn :: forall b a. GHC.Classes.Ord b => (a -> b) -> NonEmpty a -> NonEmpty a
   sortWith :: forall o a. GHC.Classes.Ord o => (a -> o) -> NonEmpty a -> NonEmpty a
   span :: forall a. (a -> GHC.Types.Bool) -> NonEmpty a -> ([a], [a])
   splitAt :: forall a. GHC.Types.Int -> NonEmpty a -> ([a], [a])



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

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/264a4fa91cc2f8f104f9c4af5ef4ed37cd615193
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/20240215/c9453e62/attachment-0001.html>

More information about the ghc-commits mailing list