Add shortestPath(s) functions

Fixes #27

Author: kevmoo

Diff for: CHANGELOG.md

@@ -1,5 +1,7 @@
 # 0.1.3
 
+- Added `shortestPath` and `shortestPaths` functions.
+
 - Use `HashMap` and `HashSet` from `dart:collection` for 
   `stronglyConnectedComponents`. Improves runtime performance.
 

Diff for: benchmark/shortest_path_benchmark.dart

@@ -0,0 +1,44 @@
+// 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 'dart:math' show Random;
+
+import 'package:graphs/graphs.dart';
+
+void main() {
+  final _rnd = Random(1);
+  final size = 1000;
+  final graph = HashMap<int, List<int>>();
+
+  for (var i = 0; i < size * 5; i++) {
+    final toList = graph.putIfAbsent(_rnd.nextInt(size), () => List<int>());
+
+    final toValue = _rnd.nextInt(size);
+    if (!toList.contains(toValue)) {
+      toList.add(toValue);
+    }
+  }
+
+  var counts = <int>[];
+
+  final testOutput =
+      shortestPath(0, size - 1, (e) => graph[e] ?? []).toString();
+  print(testOutput);
+  assert(testOutput == '[258, 252, 819, 999]');
+
+  for (var i = 0; i < 50; i++) {
+    var count = 0;
+    final watch = Stopwatch()..start();
+    while (watch.elapsed < const Duration(milliseconds: 100)) {
+      count++;
+      final length = shortestPath(0, size - 1, (e) => graph[e] ?? []).length;
+      assert(length == 4, '$length');
+    }
+    print(count);
+    counts.add(count);
+  }
+
+  print('max iterations in 1s: ${(counts..sort()).last}');
+}

Diff for: lib/graphs.dart

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

Diff for: lib/src/shortest_path.dart

@@ -0,0 +1,88 @@
+// 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';
+
+/// Returns the shortest path from [start] to [target] given the directed
+/// edges of a graph provided by [edges].
+///
+/// If [start] `==` [target], an empty [List] is returned and [edges] is never
+/// called.
+///
+/// [start], [target] and all values returned by [edges] must not be `null`.
+/// If asserts are enabled, an [AssertionError] is raised if these conditions
+/// are not met. If asserts are not enabled, violations result in undefined
+/// behavior.
+///
+/// This function assumes [T] implements correct and efficient `==` and
+/// `hashCode`.
+List<T> shortestPath<T>(T start, T target, Iterable<T> Function(T) edges) =>
+    _shortestPaths(start, edges, target)[target];
+
+/// Returns a [Map] of the shortest paths from [start] to all of the nodes in
+/// the directed graph defined by [edges].
+///
+/// All return values will contain the key [start] with an empty [List] value.
+///
+/// [start] and all values returned by [edges] must not be `null`.
+/// If asserts are enabled, an [AssertionError] is raised if these conditions
+/// are not met. If asserts are not enabled, violations result in undefined
+/// behavior.
+///
+/// This function assumes [T] implements correct and efficient `==` and
+/// `hashCode`.
+Map<T, List<T>> shortestPaths<T>(T start, Iterable<T> Function(T) edges) =>
+    _shortestPaths(start, edges);
+
+Map<T, List<T>> _shortestPaths<T>(T start, Iterable<T> Function(T) edges,
+    [T target]) {
+  assert(start != null, '`start` cannot be null');
+  assert(edges != null, '`edges` cannot be null');
+
+  final distances = HashMap<T, List<T>>();
+  distances[start] = [];
+
+  if (start == target) {
+    return distances;
+  }
+
+  final toVisit = ListQueue<T>()..add(start);
+
+  List<T> bestOption;
+
+  while (toVisit.isNotEmpty) {
+    final current = toVisit.removeFirst();
+    final distanceToCurrent = distances[current];
+
+    if (bestOption != null && distanceToCurrent.length >= bestOption.length) {
+      // Skip any existing `toVisit` items that have no chance of being
+      // better than bestOption (if it exists)
+      continue;
+    }
+
+    for (var edge in edges(current)) {
+      assert(edge != null, '`edges` cannot return null values.');
+      final existingPath = distances[edge];
+
+      if (existingPath == null ||
+          existingPath.length > (distanceToCurrent.length + 1)) {
+        final newOption = distanceToCurrent.followedBy(<T>[edge]).toList();
+
+        if (edge == target) {
+          assert(bestOption == null || bestOption.length > newOption.length);
+          bestOption = newOption;
+        }
+
+        distances[edge] = newOption;
+        if (bestOption == null || bestOption.length > newOption.length) {
+          // Only add a node to visit if it might be a better path to the
+          // target node
+          toVisit.add(edge);
+        }
+      }
+    }
+  }
+
+  return distances;
+}

Diff for: test/shortest_path_test.dart

@@ -0,0 +1,98 @@
+// 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 'package:graphs/graphs.dart';
+import 'package:test/test.dart';
+
+Matcher _throwsAssertionError(messageMatcher) =>
+    throwsA(const TypeMatcher<AssertionError>()
+        .having((ae) => ae.message, 'message', messageMatcher));
+
+void main() {
+  const graph = <String, List<String>>{
+    'a': ['b', 'e'],
+    'b': ['c'],
+    'c': ['d', 'e'],
+    'd': ['a'],
+    'e': ['h'],
+    'f': ['g'],
+  };
+
+  test('null `start` throws AssertionError', () {
+    expect(() => shortestPath(null, 'a', (input) => graph[input] ?? []),
+        _throwsAssertionError('`start` cannot be null'));
+    expect(() => shortestPaths(null, (input) => graph[input] ?? []),
+        _throwsAssertionError('`start` cannot be null'));
+  });
+
+  test('null `edges` throws AssertionError', () {
+    expect(() => shortestPath('a', 'a', null),
+        _throwsAssertionError('`edges` cannot be null'));
+    expect(() => shortestPaths('a', null),
+        _throwsAssertionError('`edges` cannot be null'));
+  });
+
+  test('null return value from `edges` throws', () {
+    expect(shortestPath('a', 'a', (input) => null), [],
+        reason: 'self target short-circuits');
+    expect(shortestPath('a', 'a', (input) => [null]), [],
+        reason: 'self target short-circuits');
+
+    expect(
+        () => shortestPath('a', 'b', (input) => null), throwsNoSuchMethodError);
+
+    expect(() => shortestPaths('a', (input) => null), throwsNoSuchMethodError);
+
+    expect(() => shortestPath('a', 'b', (input) => [null]),
+        _throwsAssertionError('`edges` cannot return null values.'));
+    expect(() => shortestPaths('a', (input) => [null]),
+        _throwsAssertionError('`edges` cannot return null values.'));
+  });
+
+  void _singlePathTest(String from, String to, List<String> expected) {
+    test('$from -> $to should be $expected', () {
+      expect(shortestPath(from, to, (input) => graph[input] ?? []), expected);
+    });
+  }
+
+  void _pathsTest(
+      String from, Map<String, List<String>> expected, List<String> nullPaths) {
+    test('paths from $from', () {
+      final result = shortestPaths(from, (input) => graph[input] ?? []);
+      expect(result, expected);
+    });
+
+    for (var entry in expected.entries) {
+      _singlePathTest(from, entry.key, entry.value);
+    }
+
+    for (var entry in nullPaths) {
+      _singlePathTest(from, entry, null);
+    }
+  }
+
+  _pathsTest('a', {
+    'e': ['e'],
+    'c': ['b', 'c'],
+    'h': ['e', 'h'],
+    'a': [],
+    'b': ['b'],
+    'd': ['b', 'c', 'd'],
+  }, [
+    'f',
+    'g',
+  ]);
+
+  _pathsTest('f', {
+    'g': ['g'],
+    'f': [],
+  }, [
+    'a',
+  ]);
+  _pathsTest('g', {'g': []}, ['a', 'f']);
+
+  _pathsTest('not_defined', {'not_defined': []}, ['a', 'f']);
+
+  _singlePathTest('a', null, null);
+}