Add a topologicalSort function

CHANGELOG.md

@@ -1,3 +1,7 @@
+# 2.1.0
+
+* Add a `topologicalSort()` function.
+
 # 2.0.0
 
 - **Breaking**: `crawlAsync` will no longer ignore a node from the graph if the

lib/graphs.dart

@@ -3,6 +3,8 @@
 // BSD-style license that can be found in the LICENSE file.
 
 export 'src/crawl_async.dart' show crawlAsync;
+export 'src/cycle_exception.dart' show CycleException;
 export 'src/shortest_path.dart' show shortestPath, shortestPaths;
 export 'src/strongly_connected_components.dart'
     show stronglyConnectedComponents;
+export 'src/topological_sort.dart' show topologicalSort;

lib/src/cycle_exception.dart

@@ -0,0 +1,19 @@
+// Copyright (c) 2021, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+/// An exception indicating that a cycle was detected in a graph that was
+/// expected to be acyclic.
+class CycleException<T> implements Exception {
+  /// The list of nodes comprising the cycle.
+  ///
+  /// Each node in this list has an edge to the next node. The final node has an
+  /// edge to the first node.
+  final List<T> cycle;
+
+  CycleException(Iterable<T> cycle) : cycle = List.unmodifiable(cycle);
+
+  @override
+  String toString() => 'A cycle was detected in a graph that must be acyclic:\n'
+      '${cycle.map((node) => '* $node').join('\n')}';
+}

lib/src/topological_sort.dart

@@ -0,0 +1,56 @@
+// Copyright (c) 2021, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:collection';
+
+import 'package:collection/collection.dart';
+
+import 'cycle_exception.dart';
+
+/// Returns a topological sort of the nodes of the directed edges of a graph
+/// provided by [nodes] and [edges].
+///
+/// Each element of the returned iterable is guaranteed to appear after all
+/// nodes that have edges leading to that node. The result is not guaranteed to
+/// be unique, nor is it guaranteed to be stable across releases of this
+/// package; however, it will be stable for a given input within a given package
+/// version.
+///
+/// If [equals] is provided, it is used to compare nodes in the graph. If
+/// [equals] is omitted, the node's own [Object.==] is used instead.
+///
+/// Similarly, if [hashCode] is provided, it is used to produce a hash value
+/// for nodes to efficiently calculate the return value. If it is omitted, the
+/// key's own [Object.hashCode] is used.
+///
+/// If you supply one of [equals] or [hashCode], you should generally also to
+/// supply the other.
+///
+/// Throws a [CycleException<T>] if the graph is cyclical.
+List<T> topologicalSort<T>(Iterable<T> nodes, Iterable<T> Function(T) edges,
+    {bool Function(T, T)? equals, int Function(T)? hashCode}) {
+  // https://en.wikipedia.org/wiki/Topological_sorting#Depth-first_search
+  var result = QueueList<T>();
+  var permanentMark = HashSet<T>(equals: equals, hashCode: hashCode);
+  var temporaryMark = LinkedHashSet<T>(equals: equals, hashCode: hashCode);
+  void visit(T node) {
+    if (permanentMark.contains(node)) return;
+    if (temporaryMark.contains(node)) {
+      throw CycleException(temporaryMark);
+    }
+
+    temporaryMark.add(node);
+    for (var child in edges(node)) {
+      visit(child);
+    }
+    temporaryMark.remove(node);
+    permanentMark.add(node);
+    result.addFirst(node);
+  }
+
+  for (var node in nodes) {
+    visit(node);
+  }
+  return result;
+}

pubspec.yaml

@@ -1,11 +1,14 @@
 name: graphs
-version: 2.0.0
+version: 2.1.0
 description: Graph algorithms that operate on graphs in any representation
 repository: https://github.com/dart-lang/graphs
 
 environment:
   sdk: '>=2.12.0 <3.0.0'
 
+dependencies: 
+  collection: ^1.1.0
+
 dev_dependencies:
   pedantic: ^1.10.0
   test: ^1.16.0

test/topological_sort_test.dart

@@ -0,0 +1,128 @@
+// Copyright (c) 2018, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:collection';
+
+import 'package:graphs/graphs.dart';
+import 'package:test/test.dart';
+
+import 'utils/utils.dart';
+
+void main() {
+  group('sorts a graph', () {
+    test('with no nodes', () {
+      expect(_topologicalSort({}), isEmpty);
+    });
+
+    test('with only one node', () {
+      expect(_topologicalSort({1: []}), equals([1]));
+    });
+
+    test('with no edges', () {
+      expect(_topologicalSort({1: [], 2: [], 3: [], 4: []}),
+          unorderedEquals([1, 2, 3, 4]));
+    });
+
+    test('with single edges', () {
+      expect(
+          _topologicalSort({
+            1: [2],
+            2: [3],
+            3: [4],
+            4: []
+          }),
+          equals([1, 2, 3, 4]));
+    });
+
+    test('with many edges from one node', () {
+      var result = _topologicalSort({
+        1: [2, 3, 4],
+        2: [],
+        3: [],
+        4: []
+      });
+      expect(result.indexOf(1), lessThan(result.indexOf(2)));
+      expect(result.indexOf(1), lessThan(result.indexOf(3)));
+      expect(result.indexOf(1), lessThan(result.indexOf(4)));
+    });
+
+    test('with transitive edges', () {
+      var result = _topologicalSort({
+        1: [2, 4],
+        2: [],
+        3: [],
+        4: [3]
+      });
+      expect(result.indexOf(1), lessThan(result.indexOf(2)));
+      expect(result.indexOf(1), lessThan(result.indexOf(3)));
+      expect(result.indexOf(1), lessThan(result.indexOf(4)));
+      expect(result.indexOf(4), lessThan(result.indexOf(3)));
+    });
+
+    test('with diamond edges', () {
+      var result = _topologicalSort({
+        1: [2, 3],
+        2: [4],
+        3: [4],
+        4: []
+      });
+      expect(result.indexOf(1), lessThan(result.indexOf(2)));
+      expect(result.indexOf(1), lessThan(result.indexOf(3)));
+      expect(result.indexOf(1), lessThan(result.indexOf(4)));
+      expect(result.indexOf(2), lessThan(result.indexOf(4)));
+      expect(result.indexOf(3), lessThan(result.indexOf(4)));
+    });
+  });
+
+  test('respects custom equality and hash functions', () {
+    expect(
+        _topologicalSort<int>({
+          0: [2],
+          3: [4],
+          5: [6],
+          7: []
+        },
+            equals: (i, j) => (i ~/ 2) == (j ~/ 2),
+            hashCode: (i) => (i ~/ 2).hashCode),
+        equals([
+          0,
+          anyOf([2, 3]),
+          anyOf([4, 5]),
+          anyOf([6, 7])
+        ]));
+  });
+
+  group('throws a CycleException for a graph with', () {
+    test('a one-node cycle', () {
+      expect(
+          () => _topologicalSort({
+                1: [1]
+              }),
+          throwsCycleException([1]));
+    });
+
+    test('a multi-node cycle', () {
+      expect(
+          () => _topologicalSort({
+                1: [2],
+                2: [3],
+                3: [4],
+                4: [1]
+              }),
+          throwsCycleException([1, 2, 3, 4]));
+    });
+  });
+}
+
+/// Runs a topological sort on a graph represented a map from keys to edges.
+List<T> _topologicalSort<T>(Map<T, List<T>> graph,
+    {bool Function(T, T)? equals, int Function(T)? hashCode}) {
+  if (equals != null) {
+    graph = LinkedHashMap(equals: equals, hashCode: hashCode)..addAll(graph);
+  }
+  return topologicalSort(graph.keys, (node) {
+    expect(graph, contains(node));
+    return graph[node]!;
+  }, equals: equals, hashCode: hashCode);
+}

test/utils/utils.dart

@@ -2,10 +2,23 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
+import 'package:graphs/graphs.dart';
+import 'package:test/test.dart';
+
 bool xEquals(X a, X b) => a.value == b.value;
 
 int xHashCode(X a) => a.value.hashCode;
 
+/// Returns a matcher that verifies that a function throws a [CycleException<T>]
+/// with the given [cycle].
+Matcher throwsCycleException<T>(List<T> cycle) => throwsA(allOf([
+      isA<CycleException<T>>(),
+      predicate((exception) {
+        expect((exception as CycleException<T>).cycle, equals(cycle));
+        return true;
+      })
+    ]));
+
 class X {
   final String value;