Added WeightedDirectedGraph methods: updateEdgeWeight and weightedEdges.

Author: simphotonics

CHANGELOG.md

@@ -1,4 +1,8 @@
 
+## 0.5.3
+- Added `WeightedDirectedGraph` methods: `weightedEdges` and `updateEdgeWeight`.
+- Updated docs and examples. 
+
 ## 0.5.2
 - Fixed grammar in CHANGELOG entry below.
 - Moved [`GraphCrawler`][GraphCrawler] to a separate folder.
@@ -30,7 +34,7 @@
   `DirectedGraphBase` to
   [`GraphCrawler`][GraphCrawler]. It is now using a more efficient recursive
   algorithm.
-- Extended the definition of a quasi-topological ordering in section `Usage`. 
+- Extended the definition of a quasi-topological ordering in section `Usage`.
 - Lowered the required SDK version to ^3.5.0.
 
 ## 0.5.0

README.md

@@ -348,14 +348,10 @@ a [comparator] function is provided
 or if `T` implements [`Comparator`][Comparator].
 
 ```Dart
-
 import 'package:directed_graph/directed_graph.dart';
 
 void main(List<String> args) {
-  int comparator(
-    String s1,
-    String s2,
-  ) {
+  int comparator(String s1, String s2) {
     return s1.compareTo(s2);
   }
 
@@ -375,15 +371,15 @@ void main(List<String> args) {
 
   var graph = WeightedDirectedGraph<String, int>(
     {
-      a: {b: 1, h: 7, c: 2, e: 40, g:7},
+      a: {b: 1, h: 7, c: 2, e: 40, g: 7},
       b: {h: 6},
       c: {h: 5, g: 4},
       d: {e: 1, f: 2},
       e: {g: 2},
       f: {i: 3},
       i: {l: 3, k: 2},
       k: {g: 4, f: 5},
-      l: {l: 0}
+      l: {l: 0},
     },
     summation: sum,
     zero: 0,
@@ -407,6 +403,19 @@ void main(List<String> args) {
   final shortestPath = graph.shortestPath(a, g);
   print('\nShortest path a -> g');
   print('$shortestPath weight: ${graph.weightAlong(shortestPath)}');
+
+  print('\nTransitive Closure');
+  print(WeightedDirectedGraph.transitiveClosure(graph));
+
+  print('\nTransitive Weighted Edges:');
+  print(graph.transitiveWeightedEdges);
+
+  print('\nVertices reachable from d:');
+  print(graph.reachableVertices(d));
+
+  print('\nUpdate weight of edge (a,b) with value 101:');
+  graph.updateEdgeWeight(vertex: a, connectedVertex: b, weight: 101);
+  print('graph.weightedEdges(a): ${graph.weightedEdges(a)}');
 }
 ```
 
@@ -429,7 +438,7 @@ Weighted Graph:
  'l': {'l': 0},
 }
 
-Neighbouring vertices sorted by weight
+Neighbouring vertices sorted by weight:
 {
  'a': {'b': 1, 'c': 2, 'h': 7, 'g': 7, 'e': 40},
  'b': {'h': 6},
@@ -452,6 +461,30 @@ Heaviest path a -> g
 
 Shortest path a -> g
 [a, g] weight: 7
+
+Transitive Closure
+{
+ 'a': {'b': 1, 'c': 2, 'h': 7, 'g': 6, 'e': 40},
+ 'b': {'h': 6},
+ 'c': {'g': 4, 'h': 5},
+ 'd': {'e': 1, 'f': 2, 'g': 3, 'i': 5, 'k': 7, 'l': 8},
+ 'e': {'g': 2},
+ 'f': {'i': 3, 'k': 5, 'l': 6, 'g': 9, 'f': 10},
+ 'g': {},
+ 'h': {},
+ 'i': {'k': 2, 'l': 3, 'g': 6, 'f': 7, 'i': 10},
+ 'k': {'g': 4, 'f': 5, 'i': 8, 'k': 10, 'l': 11},
+ 'l': {'l': 0},
+}
+
+Transitive Weighted Edges:
+{a: {b: 1, c: 2, h: 7, g: 6, e: 40}, b: {h: 6}, c: {g: 4, h: 5}, d: {e: 1, f: 2, g: 3, i: 5, k: 7, l: 8}, e: {g: 2}, f: {i: 3, k: 5, l: 6, g: 9, f: 10}, g: {}, h: {}, i: {k: 2, l: 3, g: 6, f: 7, i: 10}, k: {g: 4, f: 5, i: 8, k: 10, l: 11}, l: {l: 0}}
+
+Vertices reachable from d:
+{e, g, f, i, k, l}
+
+Update weight of edge (a,b) with value 101:
+graph.weightedEdges(a): {b: 101, c: 2, h: 7, g: 7, e: 40}
 ```
 </details>
 

example/bin/weighted_graph_example.dart

@@ -62,4 +62,8 @@ void main(List<String> args) {
 
   print('\nVertices reachable from d:');
   print(graph.reachableVertices(d));
+
+  print('\nUpdate weight of edge (a,b) with value 101:');
+  graph.updateEdgeWeight(vertex: a, connectedVertex: b, weight: 101);
+  print('graph.weightedEdges(a): ${graph.weightedEdges(a)}');
 }

lib/src/graph/weighted_directed_graph.dart

@@ -84,8 +84,15 @@ class WeightedDirectedGraph<T extends Object, W extends Comparable>
   /// Note: Mathematically, an edge is an ordered pair
   /// (vertex, connected-vertex).
   @override
-  Set<T> edges(T vertex) =>
-      _edges[vertex] == null ? <T>{} : _edges[vertex]!.keys.toSet();
+  Set<T> edges(T vertex) => _edges[vertex]?.keys.toSet() ?? <T>{};
+
+
+  /// Returns a map containing the vertices connected to [vertex] as keys
+  /// and the weight associated with each edge as values.
+  /// ---
+  /// Returns and empty map if [vertex] is not connected to any other vertices
+  /// or if [vertex] is not a graph vertex. 
+  Map<T, W> weightedEdges(T vertex) => Map.of(_edges[vertex] ?? <T, W>{});
 
   /// Lazy variable representing the graph weight.
   late final _weight = Lazy<W>(() {
@@ -206,12 +213,12 @@ class WeightedDirectedGraph<T extends Object, W extends Comparable>
     updateCache();
   }
 
-  /// Returns the weight obtained by traversing `walk` and
+  /// Returns the weight obtained by traversing the iterable [walk] and
   /// summing all edge weights.
   /// * The vertices must be traversable in the specified order.
   /// * Vertices and edges may be repeated.
-  /// * Throws an error if the `walk` cannot be traversed.
-  /// * Returns zero if `walk` is empty.
+  /// * Throws an error if the [walk] cannot be traversed.
+  /// * Returns zero if the iterable [walk] is empty.
   W weightAlong(Iterable<T> walk) {
     final edge = walk.take(2);
     if (edge.length < 2) {
@@ -221,20 +228,41 @@ class WeightedDirectedGraph<T extends Object, W extends Comparable>
     final connectedVertex = edge.last;
 
     if (!_edges.containsKey(vertex)) {
-      throw ErrorOfType<UnkownVertex>();
+      throw ErrorOfType<UnkownVertex>(
+          message: 'Could not calculate weight of walk: $walk',
+          invalidState: '$vertex is not a graph vertex.');
     }
     if (!_edges[vertex]!.containsKey(connectedVertex)) {
       throw ErrorOfType<NotAnEdge>(
-        message: 'Could not calculate weight of walk: $walk.',
-        invalidState: 'Vertex $vertex not connected to $connectedVertex.}',
-      );
+          message: 'Could not calculate the weight of walk: $walk.',
+          invalidState: 'Vertex $vertex is not connected to $connectedVertex.}',
+          expectedState:
+              '$walk must be traversable using existing graph edges.');
     }
     return summation(
       _edges[vertex]![connectedVertex]!,
       weightAlong(walk.skip(1)),
     );
   }
 
+  /// Assigns [weight] to the `existing` edge connecting [vertex]
+  /// to [connectedVertex].
+  /// * Returns `true` on success.
+  /// * Return `false` if there is no graph edge connecting [vertex] to
+  /// [connectedVertex].
+  /// * Note: To create an new graph edge connecting [vertex] to
+  /// [connectedVertex] use the method [addEdge].
+  bool updateEdgeWeight(
+      {required T vertex, required T connectedVertex, required W weight}) {
+    if (!edgeExists(vertex, connectedVertex)) {
+      return false;
+    } else {
+      _edges[vertex]![connectedVertex] = weight;
+      _weight.updateCache();
+      return true;
+    }
+  }
+
   /// Sorts the neighbouring vertices of each vertex using [comparator].
   /// * By default the neighbouring vertices of a vertex are listed in
   ///   insertion order.

pubspec.yaml

@@ -3,7 +3,7 @@ name: directed_graph
 description: Generic directed graph and weighted directed graph with algorithms
   enabling sorting and topological ordering of vertices.
 
-version: 0.5.2
+version: 0.5.3
 
 homepage: https://github.com/simphotonics/directed_graph
 
@@ -25,6 +25,6 @@ dependencies:
   quote_buffer: ^0.2.7
 
 dev_dependencies:
-  benchmark_runner: ^2.0.1
-  lints: ^6.0.0
+  benchmark_runner: ^2.0.2
+  lints: ^6.1.0
   test: ^1.29.0

test/weighted_directed_graph_test.dart

@@ -278,6 +278,12 @@ void main() {
       final graph = WeightedDirectedGraph.of(graph0);
       expect(graph.weightAlong([a, c, g]), 6);
     });
+    test('updateEdgeWeight', () {
+      final graph = WeightedDirectedGraph.of(graph0);
+      graph.updateEdgeWeight(vertex: a, connectedVertex: c, weight: 1002);
+      expect(graph.weightAlong([a, c]), 1002);
+      expect(graph.weight, graph0.weight + 1000);
+    });
   });
 
   group('TransitiveClosure', () {