Rename the GraphBuilder to GraphFactory, because it does not crea…

…te arbitrary graphs.
renggli · Oct 8, 2023 · 5582bcb · 5582bcb
1 parent 339cec1
commit 5582bcb
Show file tree

Hide file tree

Showing 15 changed files with 197 additions and 167 deletions.
diff --git a/lib/graph.dart b/lib/graph.dart
@@ -2,18 +2,18 @@
 library graph;
 
 export 'src/graph/edge.dart' show Edge;
+export 'src/graph/factory.dart' show GraphFactory;
+export 'src/graph/factory/atlas.dart' show AtlasGraphFactoryExtension;
+export 'src/graph/factory/collection.dart' show CollectionGraphFactoryExtension;
+export 'src/graph/factory/complete.dart' show CompleteGraphFactoryExtension;
+export 'src/graph/factory/empty.dart' show EmptyGraphFactoryExtension;
+export 'src/graph/factory/partite.dart' show PartiteGraphFactoryExtension;
+export 'src/graph/factory/path.dart' show PathGraphFactoryExtension;
+export 'src/graph/factory/random.dart' show RandomGraphFactoryExtension;
+export 'src/graph/factory/ring.dart' show RingGraphFactoryExtension;
+export 'src/graph/factory/star.dart' show StarGraphFactoryExtension;
+export 'src/graph/factory/tree.dart' show TreeGraphFactoryExtension;
 export 'src/graph/graph.dart' show Graph;
-export 'src/graph/library.dart' show GraphLibrary;
-export 'src/graph/library/atlas.dart' show AtlasGraphLibraryExtension;
-export 'src/graph/library/collection.dart' show CollectionGraphLibraryExtension;
-export 'src/graph/library/complete.dart' show CompleteGraphLibraryExtension;
-export 'src/graph/library/empty.dart' show EmptyGraphLibraryExtension;
-export 'src/graph/library/partite.dart' show PartiteGraphLibraryExtension;
-export 'src/graph/library/path.dart' show PathGraphLibraryExtension;
-export 'src/graph/library/random.dart' show RandomGraphLibraryExtension;
-export 'src/graph/library/ring.dart' show RingGraphLibraryExtension;
-export 'src/graph/library/star.dart' show StarGraphLibraryExtension;
-export 'src/graph/library/tree.dart' show TreeGraphLibraryExtension;
 export 'src/graph/model/reversed.dart' show ReversedGraphExtension;
 export 'src/graph/model/unmodifiable.dart' show UnmodifiableGraphExtension;
 export 'src/graph/operations/connected.dart' show ConnectedGraphExtension;

diff --git a/lib/src/graph/library.dart → lib/src/graph/factory.dart b/lib/src/graph/library.dart → lib/src/graph/factory.dart
@@ -2,15 +2,15 @@ import 'dart:math';
 
 import 'package:meta/meta.dart';
 
-import 'library/builder.dart';
+import 'factory/builder.dart';
 import 'strategy.dart';
 
 typedef VertexProvider<V> = V Function(int index);
 typedef EdgeProvider<V, E> = E Function(V source, V target);
 
-/// Builds common graphs efficiently.
-class GraphLibrary<V, E> {
-  GraphLibrary({
+/// Factory methods to create commmon graphs types efficiently.
+class GraphFactory<V, E> {
+  GraphFactory({
     this.isDirected = true,
     this.isUnmodifiable = false,
     this.vertexProvider,

diff --git a/lib/src/graph/library/atlas.dart → lib/src/graph/factory/atlas.dart b/lib/src/graph/library/atlas.dart → lib/src/graph/factory/atlas.dart
@@ -1,7 +1,7 @@
+import '../factory.dart';
 import '../graph.dart';
-import '../library.dart';
 
-extension AtlasGraphLibraryExtension<V, E> on GraphLibrary<V, E> {
+extension AtlasGraphFactoryExtension<V, E> on GraphFactory<V, E> {
   /// Returns a graph from "An Atlas of Graphs" by Ronald C. Read and Robin J.
   /// Wilson, Oxford University Press, 1998. [number] is a number between `0`
   /// and `1252`.

diff --git a/lib/src/graph/library/builder.dart → lib/src/graph/factory/builder.dart b/lib/src/graph/library/builder.dart → lib/src/graph/factory/builder.dart
@@ -1,11 +1,11 @@
+import '../factory.dart';
 import '../graph.dart';
-import '../library.dart';
 import '../model/unmodifiable.dart';
 
 class GraphBuilder<V, E> {
   GraphBuilder(this.library) : graph = create<V, E>(library);
 
-  final GraphLibrary<V, E> library;
+  final GraphFactory<V, E> library;
   final Graph<V, E> graph;
 
   /// Adds a [vertex] to this graph.
@@ -24,7 +24,7 @@ class GraphBuilder<V, E> {
       library.vertexProvider?.call(target) ?? (target as V),
       data: data);
 
-  static Graph<V, E> create<V, E>(GraphLibrary<V, E> builder) =>
+  static Graph<V, E> create<V, E>(GraphFactory<V, E> builder) =>
       builder.isDirected
           ? Graph<V, E>.directed(vertexStrategy: builder.vertexStrategy)
           : Graph<V, E>.undirected(vertexStrategy: builder.vertexStrategy);

diff --git a/lib/src/graph/library/collection.dart → lib/src/graph/factory/collection.dart b/lib/src/graph/library/collection.dart → lib/src/graph/factory/collection.dart
@@ -1,9 +1,9 @@
 import 'package:collection/collection.dart';
 
+import '../factory.dart';
 import '../graph.dart';
-import '../library.dart';
 
-extension CollectionGraphLibraryExtension<V, E> on GraphLibrary<V, E> {
+extension CollectionGraphFactoryExtension<V, E> on GraphFactory<V, E> {
   /// Creates a [Graph] from a [Iterable] of chains.
   Graph<V, E> fromPath(Iterable<V> chain, {E? data}) =>
       fromPaths([chain], data: data);

diff --git a/lib/src/graph/library/complete.dart → lib/src/graph/factory/complete.dart b/lib/src/graph/library/complete.dart → lib/src/graph/factory/complete.dart
@@ -1,8 +1,8 @@
+import '../factory.dart';
 import '../graph.dart';
-import '../library.dart';
 
 /// https://mathworld.wolfram.com/CompleteGraph.html
-extension CompleteGraphLibraryExtension<V, E> on GraphLibrary<V, E> {
+extension CompleteGraphFactoryExtension<V, E> on GraphFactory<V, E> {
   /// Creates a complete [Graph] where all vertices are connected with each
   /// other.
   Graph<V, E> complete({required int vertexCount}) {

diff --git a/lib/src/graph/library/empty.dart → lib/src/graph/factory/empty.dart b/lib/src/graph/library/empty.dart → lib/src/graph/factory/empty.dart
@@ -1,7 +1,7 @@
+import '../factory.dart';
 import '../graph.dart';
-import '../library.dart';
 
-extension EmptyGraphLibraryExtension<V, E> on GraphLibrary<V, E> {
+extension EmptyGraphFactoryExtension<V, E> on GraphFactory<V, E> {
   /// Creates an empty graph.
   Graph<V, E> empty() => newBuilder().build();
 }
diff --git a/lib/src/graph/library/partite.dart → lib/src/graph/factory/partite.dart b/lib/src/graph/library/partite.dart → lib/src/graph/factory/partite.dart
@@ -1,8 +1,8 @@
+import '../factory.dart';
 import '../graph.dart';
-import '../library.dart';
 
 /// https://mathworld.wolfram.com/Completek-PartiteGraph.html
-extension PartiteGraphLibraryExtension<V, E> on GraphLibrary<V, E> {
+extension PartiteGraphFactoryExtension<V, E> on GraphFactory<V, E> {
   /// Creates a partite [Graph] with a number of vertices on each layer.
   Graph<V, E> partite({required Iterable<int> vertexCounts}) {
     final parts = vertexCounts.toList();

diff --git a/lib/src/graph/library/path.dart → lib/src/graph/factory/path.dart b/lib/src/graph/library/path.dart → lib/src/graph/factory/path.dart
@@ -1,8 +1,8 @@
+import '../factory.dart';
 import '../graph.dart';
-import '../library.dart';
 
 /// https://mathworld.wolfram.com/PathGraph.html
-extension PathGraphLibraryExtension<V, E> on GraphLibrary<V, E> {
+extension PathGraphFactoryExtension<V, E> on GraphFactory<V, E> {
   /// Creates a [Graph] that forms a linear path.
   Graph<V, E> path({required int vertexCount}) {
     final builder = newBuilder();

diff --git a/lib/src/graph/library/random.dart → lib/src/graph/factory/random.dart b/lib/src/graph/library/random.dart → lib/src/graph/factory/random.dart
@@ -1,12 +1,12 @@
 import '../../collection/iterable/combinations.dart';
 import '../../collection/iterable/permutations.dart';
 import '../../collection/range/integer.dart';
+import '../factory.dart';
 import '../graph.dart';
-import '../library.dart';
 import 'complete.dart';
 
 /// Creates random graphs using different models.
-extension RandomGraphLibraryExtension<V, E> on GraphLibrary<V, E> {
+extension RandomGraphFactoryExtension<V, E> on GraphFactory<V, E> {
   /// Generates a graph using the Erdős–Rényi model with [vertexCount] vertices
   /// and a constant [probability] of creating an edge between any pair of
   /// vertices.

diff --git a/lib/src/graph/library/ring.dart → lib/src/graph/factory/ring.dart b/lib/src/graph/library/ring.dart → lib/src/graph/factory/ring.dart
@@ -1,7 +1,7 @@
+import '../factory.dart';
 import '../graph.dart';
-import '../library.dart';
 
-extension RingGraphLibraryExtension<V, E> on GraphLibrary<V, E> {
+extension RingGraphFactoryExtension<V, E> on GraphFactory<V, E> {
   /// Creates a [Graph] that forms a closed ring.
   Graph<V, E> ring({required int vertexCount}) {
     final builder = newBuilder();

diff --git a/lib/src/graph/library/star.dart → lib/src/graph/factory/star.dart b/lib/src/graph/library/star.dart → lib/src/graph/factory/star.dart
@@ -1,8 +1,8 @@
+import '../factory.dart';
 import '../graph.dart';
-import '../library.dart';
 
 /// https://mathworld.wolfram.com/StarGraph.html
-extension StarGraphLibraryExtension<V, E> on GraphLibrary<V, E> {
+extension StarGraphFactoryExtension<V, E> on GraphFactory<V, E> {
   /// Creates a [Graph] that forms a star.
   Graph<V, E> star({required int vertexCount}) {
     final builder = newBuilder();

diff --git a/lib/src/graph/library/tree.dart → lib/src/graph/factory/tree.dart b/lib/src/graph/library/tree.dart → lib/src/graph/factory/tree.dart
@@ -2,14 +2,14 @@ import 'dart:math';
 
 import 'package:collection/collection.dart';
 
+import '../factory.dart';
 import '../graph.dart';
-import '../library.dart';
 
 /// Creates m-ary trees (also known as n-ary, k-ary or k-way tree) in which each
 /// node has no more than m children.
 ///
 /// See https://en.wikipedia.org/wiki/M-ary_tree.
-extension TreeGraphLibraryExtension<V, E> on GraphLibrary<V, E> {
+extension TreeGraphFactoryExtension<V, E> on GraphFactory<V, E> {
   /// Creates a complete tree with [vertexCount] nodes and a branching factor of
   /// [arity]. By definition it is completely filled on every level except for
   /// the last one; where all the nodes are as far left as possible.

diff --git a/lib/src/graph/operations/logical.dart b/lib/src/graph/operations/logical.dart
@@ -66,7 +66,8 @@ extension LogicalGraphExtension<V, E> on Graph<V, E> {
 
   /// Returns the complement of this graph, that is a graph with the same
   /// vertices but with edges between vertices that had no edge.
-  Graph<V, E> complement({E? Function(V source, V target)? edge}) {
+  Graph<V, E> complement(
+      {bool allowSelfLoops = false, E? Function(V source, V target)? edge}) {
     final result = copyEmpty<V, E>(this);
     // Copy all the vertices over.
     for (final vertex in vertices) {
@@ -76,8 +77,10 @@ extension LogicalGraphExtension<V, E> on Graph<V, E> {
     for (final source in vertices) {
       final targets = vertexStrategy.createSet()
         ..addAll(vertices)
-        ..removeAll(successorsOf(source))
-        ..remove(source);
+        ..removeAll(successorsOf(source));
+      if (!allowSelfLoops) {
+        targets.remove(source);
+      }
       for (final target in targets) {
         result.addEdge(source, target, data: edge?.call(source, target));
       }