updated CHANGELOG, removed class conformance from Graph, updated some documentation, renamed CONTRIBUTOR

Author: davecom

.swift-version

@@ -1 +1 @@
-4.2
+5.0

CHANGELOG.md

@@ -1,6 +1,20 @@
+### 3.0.0
+- **This is an API breaking refactor**
+- This version requires Swift 5.0 (Xcode 10.2)
+- `Graph` no longer conforms to `class` so structs can be `Graph`s (@davecom)
+- `Graph` and `Edge` are now `Codable` meaning all implementations must be as well including all vertex types, leading to the removal of `CodableUnweightedGraph` and `CodableWeightedGraph`, which are now unnecessary (@davecom)
+- New CONTRIBUTORS.md file containing some history (@davecom)
+- New search traversal methods (@ferranpujolcamins)
+- Improvements to `UniqueElementsGraph` (@ferranpujolcamins)
+- Useful constructors for testing (@ferranpujolcamins)
+- Improvements to `UniqueElementsGraph` tests (@ferranpujolcamins)
+- Refactor many aspects of `UnweightedGraph` and `WeightedGraph` into conditional conformance extensions to `Graph` and new protocols (@ferranpujolcamins)
+- Add new performance tests (@ferranpujolcamins)
+- Add direction back to `Edge` (@ferranpujolcamins)
+
 ### 2.0.0
 - **This is an API breaking refactor**
-- This version requires Swift 4.2 (Xcode 10)
+- This version requires Swift 4.2 (Xcode 10.1)
 - `Graph` is now a protocol instead of a class
 - `edgesToVertices()` is now a method on `Graph` instead of a free function
 - The `Edge` protocol has been significantly simplifieid

HISTORYandCONTRIBUTORS.md renamed to CONTRIBUTORS.md

@@ -118,14 +118,14 @@ There is a large amount of documentation in the source code using the latest App
 ### Edges
 Edges connect the vertices in your graph to one another.
 
-* `Edge` (Protocol) - A protocol that all edges in a graph must conform to. An edge is a connection between two vertices in the graph. The vertices are specified by their index in the graph which is an integer.
+* `Edge` (Protocol) - A protocol that all edges in a graph must conform to. An edge is a connection between two vertices in the graph. The vertices are specified by their index in the graph which is an integer. All `Edge`s must be `Codable`.
 * `UnweightedEdge` - This is a concrete implementation of `Edge` for unweighted graphs.
-* `WeightedEdge` - A subclass of `UnweightedEdge` that adds weights. Weights are a generic type - they can be anything that implements `Comparable`, `Numeric` and `Codable`.  Typical weight types are `Int` and `Float`.
+* `WeightedEdge` - This is a concrete implementation of `Edge` for weighted graphs. Weights are a generic type - they can be anything that implements `Comparable`, `Numeric` and `Codable`.  Typical weight types are `Int` and `Float`.
 
 ### Graphs
 Graphs are the data structures at the heart of SwiftGraph. All vertices are assigned an integer index when they are inserted into a graph and it's generally faster to refer to them by their index than by the vertex's actual object.
 
-Graphs implement the standard Swift protocols `Collection` (for iterating through all vertices and for grabbing a vertex by its index through a subscript). For instance, the following example prints all vertices in a Graph on separate lines:
+Graphs implement the standard Swift protocols `Collection` (for iterating through all vertices and for grabbing a vertex by its index through a subscript) and `Codable` . For instance, the following example prints all vertices in a Graph on separate lines:
 ```swift
 for v in g {  // g is a Graph<String>
     print(v)
@@ -138,7 +138,7 @@ print(g[23]) // g is a Graph<String>
 
 Note: At this time, graphs are *not* thread-safe. However, once a graph is constructed, if you will only be doing lookups and searches through it (no removals of vertices/edges and no additions of vertices/edges) then you should be able to do that from multiple threads. A fully thread-safe graph implementation is a possible future direction.
 
-* `Graph` (Protocol) - This is the base protocol for all graphs.  Generally, you should use one of its canonical class implementations, `UnweightedGraph` or `WeightedGraph`, instead of rolling your own adopter, because they offer significant built-in functionality. The vertices in a `Graph` (defined as a generic at graph creation time) can be of any type that conforms to `Equatable`. `Graph` has methods for:
+* `Graph` (Protocol) - This is the base protocol for all graphs.  Generally, you should use one of its canonical class implementations, `UnweightedGraph` or `WeightedGraph`, instead of rolling your own adopter, because they offer significant built-in functionality. The vertices in a `Graph` (defined as a generic at graph creation time) can be of any type that conforms to `Equatable` and `Codable`. All `Graph`s are `Codable`.  `Graph` has methods for:
   * Adding a vertex
   * Getting the index of a vertex
   * Finding the neighbors of an index/vertex
@@ -150,7 +150,6 @@ Note: At this time, graphs are *not* thread-safe. However, once a graph is const
   * Removing a particular vertex (all other edge relationships are automatically updated at the same time (because the indices of their connections changes) so this is slow - O(v + e) where v is the number of vertices and e is the number of edges)
 * `UnweightedGraph` - A generic class implementation of `Graph` that adds convenience methods for adding and removing edges of type `UnweightedEdge`. `UnweightedGraph` is generic over the type of the vertices.
 * `WeightedGraph` - A generic class implementation of `Graph` that adds convenience methods for adding and removing edges of type `WeightedEdge`. `WeightedGraph` also adds a method for returning a list of tuples containing all of the neighbor vertices of an index along with their respective weights. `WeightedGraph` is generic over the types of the vertices and its weights.
-* `CodableUnweightedGraph` and `CodableWeightedGraph` - Subclasses of `UnweightedGraph` and `WeightedGraph` that add support for the `Codable` protocol. Their vertex and weight types must also be `Codable`. This allows serialization of graphs to formats like JSON.
 * `UniqueElementsGraph` - an experimental subclass of `UnweightedGraph` with support for union operations that ensures all vertices and edges in a graph are unique.
 
 ### Search
@@ -159,6 +158,7 @@ Search methods are defined in extensions of `Graph` and `WeightedGraph` in `Sear
 * `dfs()` (method on `Graph`) - Finds a path from one vertex to another in a `Graph` using a depth-first search. Returns an array of `Edge`s going from the source vertex to the destination vertex or an empty array if no path could be found. A version of this method takes a function, `goalTest()`, that operates on a vertex and returns a boolean to indicate whether it is a goal for the search. It returns a path to the first vertex that returns true from `goalTest()`.
 * `findAll()` Uses a breadth-first search to find all connected vertices from the starting vertex that return true when run through a `goalTest()` function. Paths to the connected vertices are returned in an array, which is empty if no vertices are found.
 * `dijkstra()` (method on `WeightedGraph`) - Finds the shortest path from a starting vertex to every other vertex in a `WeightedGraph`. Returns a tuple who's first element is an array of the distances to each vertex in the graph arranged by index. The second element of the tuple is a dictionary mapping graph indices to the previous `Edge` that gets them there in the shortest time from the staring vertex. Using this dictionary and the function `pathDictToPath()`, you can find the shortest path from the starting vertex to any other connected vertex. See the `dijkstra()` unit tests in `DijkstraGraphTests.swift` for a demo of this.
+* Graph traversal versions of `bfs()` and `dfs()` that allow a visit function to execute at each stop
 
 ### Sort & Miscellaneous
 An extension to `Graph` in `Sort.swift` provides facilities for topological sort and detecting a DAG.
@@ -172,7 +172,7 @@ An extension to `Graph` in `Cycles.swift` finds all of the cycles in a graph.
 * `detectCycles()` - Uses an algorithm developed by Liu/Wang to find all of the cycles in a graph. Optionally, this method can take one parameter, `upToLength`, that specifies a length at which to stop searching for cycles. For instance, if `upToLength` is 3, `detectCycles()` will find all of the 1 vertex cycles (self-cycles, vertices with edges to themselves), and 3 vertex cycles (connection to another vertex and back again, present in all undirected graphs with more than 1 vertex). There is no such thing as a 2 vertex cycle.
 
 ## Authorship, License, & Contributors
-SwiftGraph is written by David Kopec and released under the Apache License (see `LICENSE`). You can find my email address on my GitHub profile page. I encourage you to submit pull requests and open issues here on GitHub. 
+SwiftGraph is written by David Kopec and other contributors (see `CONTRIBUTORS.md`). It is released under the Apache License (see `LICENSE`). You can find my email address on my GitHub profile page. I encourage you to submit pull requests and open issues here on GitHub. 
 
 I would like to thank all of the contributors who have helped improve SwiftGraph over the years, and have kept me motivated. Contributing to SwiftGraph, in-line with the Apache license, means also releasing your contribution under the same license as the original project. However, the Apache license is permissive, and you are free to include SwiftGraph in a commercial, closed source product as long as you give it & its author credit (in fact SwiftGraph has already found its way into several products). See `LICENSE` for details.
 
@@ -181,4 +181,4 @@ Future directions for this project to take could include:
 * More utility functions
 * A thread safe implementation of `Graph`
 * More extensive performance testing
-* GraphML Support
+* GraphML and Other Format Support

README.md

@@ -19,7 +19,7 @@
 /// The protocol for all graphs.
 /// You should generally use one of its two canonical class implementations,
 /// *UnweightedGraph* and *WeightedGraph*
-public protocol Graph: class, CustomStringConvertible, Collection, Codable {
+public protocol Graph: CustomStringConvertible, Collection, Codable {
     associatedtype V: Equatable & Codable
     associatedtype E: Edge & Equatable
     var vertices: [V] { get set }
@@ -128,7 +128,7 @@ extension Graph {
     ///
     /// - parameter v: The vertex to be added.
     /// - returns: The index where the vertex was added.
-    public func addVertex(_ v: V) -> Int {
+    public mutating func addVertex(_ v: V) -> Int {
         vertices.append(v)
         edges.append([E]())
         return vertices.count - 1
@@ -140,7 +140,7 @@ extension Graph {
     /// - parameter directed: If false, undirected edges are created.
     ///                       If true, a reversed edge is also created.
     ///                       Default is false.
-    public func addEdge(_ e: E, directed: Bool = false) {
+    public mutating func addEdge(_ e: E, directed: Bool = false) {
         edges[e.u].append(e)
         if !directed && e.u != e.v {
             edges[e.v].append(e.reversed())
@@ -152,7 +152,7 @@ extension Graph {
     /// - parameter from: The starting vertex's index.
     /// - parameter to: The ending vertex's index.
     /// - parameter bidirectional: Remove edges coming back (to -> from)
-    public func removeAllEdges(from: Int, to: Int, bidirectional: Bool = true) {
+    public mutating func removeAllEdges(from: Int, to: Int, bidirectional: Bool = true) {
         edges[from].removeAll(where: { $0.v == to })
 
         if bidirectional {
@@ -165,7 +165,7 @@ extension Graph {
     /// - parameter from: The starting vertex.
     /// - parameter to: The ending vertex.
     /// - parameter bidirectional: Remove edges coming back (to -> from)
-    public func removeAllEdges(from: V, to: V, bidirectional: Bool = true) {
+    public mutating func removeAllEdges(from: V, to: V, bidirectional: Bool = true) {
         if let u = indexOfVertex(from) {
             if let v = indexOfVertex(to) {
                 removeAllEdges(from: u, to: v, bidirectional: bidirectional)
@@ -176,7 +176,7 @@ extension Graph {
     /// Remove the first edge found to be equal to *e*
     ///
     /// - parameter e: The edge to remove.
-    public func removeEdge(_ e: E) {
+    public mutating func removeEdge(_ e: E) {
         if let index = edges[e.u].firstIndex(where: { $0 == e }) {
             edges[e.u].remove(at: index)
         }
@@ -185,7 +185,7 @@ extension Graph {
     /// Removes a vertex at a specified index, all of the edges attached to it, and renumbers the indexes of the rest of the edges.
     ///
     /// - parameter index: The index of the vertex.
-    public func removeVertexAtIndex(_ index: Int) {
+    public mutating func removeVertexAtIndex(_ index: Int) {
         //remove all edges ending at the vertex, first doing the ones below it
         //renumber edges that end after the index
         for j in 0..<index {
@@ -231,7 +231,7 @@ extension Graph {
     /// Removes the first occurence of a vertex, all of the edges attached to it, and renumbers the indexes of the rest of the edges.
     ///
     /// - parameter vertex: The vertex to be removed..
-    public func removeVertex(_ vertex: V) {
+    public mutating func removeVertex(_ vertex: V) {
         if let i = indexOfVertex(vertex) {
             removeVertexAtIndex(i)
         }

Sources/SwiftGraph/Graph.swift

@@ -19,7 +19,7 @@
 public typealias UnweightedUniqueElementsGraph<V: Equatable & Codable> = UniqueElementsGraph<V, UnweightedEdge>
 public typealias WeightedUniqueElementsGraph<V: Equatable & Codable, W: Equatable & Codable> = UniqueElementsGraph<V, WeightedEdge<W>>
 
-/// A subclass of UnweightedGraph that ensures there are no pairs of equal vertices and no repeated edges.
+/// An implementation Graph that ensures there are no pairs of equal vertices and no repeated edges.
 open class UniqueElementsGraph<V: Equatable & Codable, E: Edge & Equatable>: Graph {
     public var vertices: [V] = [V]()
     public var edges: [[E]] = [[E]]() //adjacency lists

Sources/SwiftGraph/UniqueElementsGraph.swift

@@ -16,7 +16,7 @@
 //  See the License for the specific language governing permissions and
 //  limitations under the License.
 
-/// A subclass of Graph with some convenience methods for adding and removing UnweightedEdges. WeightedEdges may be added to an UnweightedGraph but their weights will be ignored.
+/// An implementation of Graph with some convenience methods for adding and removing UnweightedEdges. WeightedEdges may be added to an UnweightedGraph but their weights will be ignored.
 open class UnweightedGraph<V: Equatable & Codable>: Graph {
     public var vertices: [V] = [V]()
     public var edges: [[UnweightedEdge]] = [[UnweightedEdge]]() //adjacency lists
@@ -29,6 +29,29 @@ open class UnweightedGraph<V: Equatable & Codable>: Graph {
             _ = self.addVertex(vertex)
         }
     }
+    
+    /// Add an edge to the graph.
+    ///
+    /// - parameter e: The edge to add.
+    /// - parameter directed: If false, undirected edges are created.
+    ///                       If true, a reversed edge is also created.
+    ///                       Default is false.
+    public func addEdge(_ e: UnweightedEdge, directed: Bool) {
+        edges[e.u].append(e)
+        if !directed && e.u != e.v {
+            edges[e.v].append(e.reversed())
+        }
+    }
+    
+    /// Add a vertex to the graph.
+    ///
+    /// - parameter v: The vertex to be added.
+    /// - returns: The index where the vertex was added.
+    public func addVertex(_ v: V) -> Int {
+        vertices.append(v)
+        edges.append([E]())
+        return vertices.count - 1
+    }
 }
 
 extension Graph where E == UnweightedEdge {

Sources/SwiftGraph/UnweightedGraph.swift

@@ -16,8 +16,9 @@
 //  See the License for the specific language governing permissions and
 //  limitations under the License.
 
-/// A subclass of Graph that has convenience methods for adding and removing WeightedEdges. All added Edges should have the same generic Comparable type W as the WeightedGraph itself.
+/// An implementation of Graph that has convenience methods for adding and removing WeightedEdges. All added Edges should have the same generic Comparable type W as the WeightedGraph itself.
 open class WeightedGraph<V: Equatable & Codable, W: Equatable & Codable>: Graph {
+    
     public var vertices: [V] = [V]()
     public var edges: [[WeightedEdge<W>]] = [[WeightedEdge<W>]]() //adjacency lists
 
@@ -29,6 +30,29 @@ open class WeightedGraph<V: Equatable & Codable, W: Equatable & Codable>: Graph
             _ = self.addVertex(vertex)
         }
     }
+    
+    /// Add an edge to the graph.
+    ///
+    /// - parameter e: The edge to add.
+    /// - parameter directed: If false, undirected edges are created.
+    ///                       If true, a reversed edge is also created.
+    ///                       Default is false.
+    public func addEdge(_ e: WeightedEdge<W>, directed: Bool) {
+        edges[e.u].append(e)
+        if !directed && e.u != e.v {
+            edges[e.v].append(e.reversed())
+        }
+    }
+    
+    /// Add a vertex to the graph.
+    ///
+    /// - parameter v: The vertex to be added.
+    /// - returns: The index where the vertex was added.
+    public func addVertex(_ v: V) -> Int {
+        vertices.append(v)
+        edges.append([E]())
+        return vertices.count - 1
+    }
 }
 
 extension Graph where E: WeightedEdgeProtocol {

Sources/SwiftGraph/WeightedGraph.swift

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
   s.name             = 'SwiftGraph'
-  s.version          = '2.0.0'
+  s.version          = '3.0.0'
   s.license          = { :type => "Apache License, Version 2.0", :file => "LICENSE" }
   s.summary          = 'A Graph Data Structure in Pure Swift'
   s.homepage         = 'https://github.com/davecom/SwiftGraph'

SwiftGraph.podspec

@@ -242,7 +242,7 @@ class DijkstraGraphTests: XCTestCase {
     }
 
     func testRemovalWithDijkstra() {
-        let cityGraph3 = cityGraph
+        var cityGraph3 = cityGraph
         cityGraph3.removeVertex("Kansas City")
         let (distances, pathDict) = cityGraph3.dijkstra(root: "Miami", startDistance: 0)
         let nameDistance: [String: Int?] = distanceArrayToVertexDict(distances: distances, graph: cityGraph3)