From e5661a7f8a7bc3e37a3dbdc1b0aba6b555bef9fe Mon Sep 17 00:00:00 2001
From: Andreas Abel <andreas.abel@ifi.lmu.de>
Date: Sat, 3 Aug 2024 19:56:18 +0200
Subject: [PATCH] Add `flattenSCC1 :: SCC a -> NonEmpty a` (#987)

This gives a more precise type compared to the existing
`flattenSCC :: SCC a -> [a]`.
---
 containers/changelog.md      | 18 ++++++++++++------
 containers/src/Data/Graph.hs | 16 ++++++++++++++--
 2 files changed, 26 insertions(+), 8 deletions(-)

diff --git a/containers/changelog.md b/containers/changelog.md
index 116d1ec4a..0c19cd717 100644
--- a/containers/changelog.md
+++ b/containers/changelog.md
@@ -9,6 +9,12 @@
   `Data.IntSet.splitMember` are now strict in the key. Previously, the key was
   ignored for an empty map or set. (Soumik Sarkar)
 
+## Unreleased with `@since` annotation for 0.7.1:
+
+### Additions
+
+* Add `Data.Graph.flattenSCC1`. (Andreas Abel)
+
 ## 0.7
 
 ### Breaking changes
@@ -327,13 +333,13 @@ modules.
 
 * Rewrite the `IsString` instance head for sequences, improving compatibility
   with the list instance and also improving type inference. We used to have
-  
+
   ```haskell
   instance IsString (Seq Char)
   ```
-  
+
   Now we commit more eagerly with
-  
+
   ```haskell
   instance a ~ Char => IsString (Seq a)
   ```
@@ -407,7 +413,7 @@ modules.
 * Fix completely incorrect implementations of `Data.IntMap.restrictKeys` and
   `Data.IntMap.withoutKeys`. Make the tests for these actually run. (Thanks
   to Tom Smalley for reporting this.)
-  
+
 * Fix a minor bug in the `Show1` instance of `Data.Tree`. This produced valid
   output, but with fewer parentheses than `Show`. (Thanks, Ryan Scott.)
 
@@ -462,7 +468,7 @@ performance improvements overall.
     before 7.0.
 
   * Integrate benchmarks with Cabal. (Thanks, Gabriel Gonzalez!)
-  
+
   * Make Cabal report required extensions properly, and stop using
     default extensions. Note that we do *not* report extensions conditionally enabled
     based on GHC version, as doing so would lead to a maintenance nightmare
@@ -512,7 +518,7 @@ performance improvements overall.
     it returned a lazy pair.
 
   * Fix completely erroneous definition of `length` for `Data.Sequence.ViewR`.
-  
+
   * Make `Data.Map.Strict.traverseWithKey` force result values before
     installing them in the new map.
 
diff --git a/containers/src/Data/Graph.hs b/containers/src/Data/Graph.hs
index 33983ffee..a0712811a 100644
--- a/containers/src/Data/Graph.hs
+++ b/containers/src/Data/Graph.hs
@@ -89,6 +89,7 @@ module Data.Graph (
 
     -- ** Conversion
     , flattenSCC
+    , flattenSCC1
     , flattenSCCs
 
     -- * Trees
@@ -246,9 +247,20 @@ flattenSCCs :: [SCC a] -> [a]
 flattenSCCs = concatMap flattenSCC
 
 -- | The vertices of a strongly connected component.
+--
+-- @flattenSCC = 'Data.List.NonEmpty.toList' . 'flattenSCC1'@.
+--
+-- This function is retained for backward compatibility,
+-- 'flattenSCC1' has the more precise type.
 flattenSCC :: SCC vertex -> [vertex]
-flattenSCC (AcyclicSCC v) = [v]
-flattenSCC (NECyclicSCC vs) = NE.toList vs
+flattenSCC = NE.toList . flattenSCC1
+
+-- | The vertices of a strongly connected component.
+--
+-- @since 0.7.1
+flattenSCC1 :: SCC vertex -> NonEmpty vertex
+flattenSCC1 (AcyclicSCC v) = v :| []
+flattenSCC1 (NECyclicSCC vs) = vs
 
 -- | \(O((V+E) \log V)\). The strongly connected components of a directed graph,
 -- reverse topologically sorted.