added iterators for dfs and bfs

docs/src/algorithms/iterators.md

@@ -0,0 +1,33 @@
+# Iterators
+
+_Graphs.jl_ includes various routines for iterating through graphs.
+
+## Index
+
+```@index
+Pages = ["iterators.md"]
+```
+
+## Full docs
+
+```@autodocs
+Modules = [Graphs]
+Pages   = [
+    "iterators/iterators.jl",
+    "iterators/bfs.jl",
+    "iterators/dfs.jl",
+]
+Private = false
+```
+
+The following names are internals, not part of the public API:
+
+```@autodocs
+Modules = [Graphs]
+Pages   = [
+    "iterators/iterators.jl",
+    "iterators/bfs.jl",
+    "iterators/dfs.jl",
+]
+Public = false
+```

src/Graphs.jl

@@ -185,6 +185,10 @@ export
     dfs_tree,
     dfs_parents,
 
+    # iterators
+    DFSIterator,
+    BFSIterator,
+
     # random
     randomwalk,
     self_avoiding_walk,
@@ -492,6 +496,8 @@ include("traversals/dfs.jl")
 include("traversals/maxadjvisit.jl")
 include("traversals/randomwalks.jl")
 include("traversals/diffusion.jl")
+include("iterators/bfs.jl")
+include("iterators/dfs.jl")
 include("traversals/eulerian.jl")
 include("connectivity.jl")
 include("distance.jl")

src/iterators/bfs.jl

@@ -0,0 +1,95 @@
+"""
+    BFSIterator
+
+`BFSIterator` is a subtype of [`VertexIterator`](@ref) to iterate through graph vertices using a breadth-first search. A source node(s) is optionally supplied as an `Int` or an array-like type that can be indexed if supplying multiple sources. If no source is provided, it defaults to the first vertex.
+
+# Examples
+```julia-repl
+julia> g = smallgraph(:house)
+{5, 6} undirected simple Int64 graph
+
+julia> for node in BFSIterator(g,3)
+           display(node)
+       end
+3
+1
+4
+5
+2
+```
+"""
+struct BFSIterator{S,G<:AbstractGraph}
+    graph::G
+    source::S
+end
+
+"""
+    BFSVertexIteratorState
+
+`BFSVertexIteratorState` is a struct to hold the current state of iteration
+in BFS which is needed for the `Base.iterate()` function.
+"""
+mutable struct BFSVertexIteratorState
+    visited::BitVector
+    queue::Vector{Int}
+    neighbor_idx::Int
+    n_visited::Int
+end
+
+BFSIterator(g::AbstractGraph) = BFSIterator(g, first(vertices(g)))
+
+Base.length(t::BFSIterator) = nv(t.graph)
+Base.eltype(t::BFSIterator) = eltype(t.graph)
+
+"""
+    Base.iterate(t::BFSIterator)
+
+First iteration to visit each vertex in a graph using breadth-first search.
+"""
+function Base.iterate(t::BFSIterator{<:Integer})
+    visited = falses(nv(t.graph))
+    visited[t.source] = true
+    return (t.source, BFSVertexIteratorState(visited, [t.source], 1, 1))
+end
+
+function Base.iterate(t::BFSIterator{<:AbstractArray})
+    visited = falses(nv(t.graph))
+    visited[first(t.source)] = true
+    state = BFSVertexIteratorState(visited, copy(t.source), 1, 1)
+    return (first(t.source), state)
+end
+
+"""
+    Base.iterate(t::BFSIterator, state::VertexIteratorState)
+
+Iterator to visit each vertex in a graph using breadth-first search.
+"""
+function Base.iterate(t::BFSIterator, state::BFSVertexIteratorState)
+    graph, visited, queue = t.graph, state.visited, state.queue
+    while !isempty(queue)
+        if state.n_visited == nv(graph)
+            return nothing
+        end
+        node_start = first(queue)
+        if !visited[node_start]
+            visited[node_start] = true
+            state.n_visited += 1
+            return (node_start, state)
+        end
+        idx = state.neighbor_idx
+        neigh = outneighbors(graph, node_start)
+        if idx <= length(neigh)
+            node = neigh[idx]
+            state.neighbor_idx += 1
+            if !visited[node]
+                push!(queue, node)
+                state.visited[node] = true
+                state.n_visited += 1
+                return (node, state)
+            end
+        else
+            popfirst!(queue)
+            state.neighbor_idx = 1
+        end
+    end
+end

src/iterators/dfs.jl

@@ -0,0 +1,83 @@
+"""
+    DFSIterator
+
+`DFSIterator` is a subtype of [`VertexIterator`](@ref) to iterate through graph vertices using a depth-first search. A source node(s) is optionally supplied as an `Int` or an array-like type that can be indexed if supplying multiple sources. If no source is provided, it defaults to the first vertex.
+
+# Examples
+```julia-repl
+julia> g = smallgraph(:house)
+{5, 6} undirected simple Int64 graph
+
+julia> for node in DFSIterator(g, 3)
+           display(node)
+       end
+1
+2
+4
+3
+5
+```
+"""
+struct DFSIterator{S,G<:AbstractGraph}
+    graph::G
+    source::S
+end
+
+"""
+    DFSVertexIteratorState
+
+`DFSVertexIteratorState` is a struct to hold the current state of iteration
+in DFS which is needed for the `Base.iterate()` function.
+"""
+mutable struct DFSVertexIteratorState
+    visited::BitVector
+    queue::Vector{Int}
+end
+
+DFSIterator(g::AbstractGraph) = DFSIterator(g, first(vertices(g)))
+
+Base.length(t::DFSIterator) = nv(t.graph)
+Base.eltype(t::DFSIterator) = eltype(t.graph)
+
+"""
+    Base.iterate(t::DFSIterator)
+
+First iteration to visit each vertex in a graph using depth-first search.
+"""
+function Base.iterate(t::DFSIterator{<:Integer})
+    visited = falses(nv(t.graph))
+    visited[t.source] = true
+    return (t.source, DFSVertexIteratorState(visited, [t.source]))
+end
+
+function Base.iterate(t::DFSIterator{<:AbstractArray})
+    visited = falses(nv(t.graph))
+    source_rev = reverse(t.source)
+    visited[last(source_rev)] = true
+    state = DFSVertexIteratorState(visited, source_rev)
+    return (last(source_rev), state)
+end
+
+"""
+    Base.iterate(t::DFSIterator, state::VertexIteratorState)
+
+Iterator to visit each vertex in a graph using depth-first search.
+"""
+function Base.iterate(t::DFSIterator, state::DFSVertexIteratorState)
+    graph, visited, queue = t.graph, state.visited, state.queue
+    while !isempty(queue)
+        node_start = last(queue)
+        if !visited[node_start]
+            visited[node_start] = true
+            return (node_start, state)
+        end
+        for node in outneighbors(graph, node_start)
+            if !visited[node]
+                push!(queue, node)
+                visited[node] = true
+                return (node, state)
+            end
+        end
+        pop!(queue)
+    end
+end

test/iterators/bfs.jl

@@ -0,0 +1,44 @@
+@testset "BFSIterator" begin
+    g = path_graph(7)
+    add_edge!(g, 6, 3)
+    add_edge!(g, 3, 1)
+    add_edge!(g, 4, 7)
+    g2 = deepcopy(g)
+    add_vertex!(g2)
+    add_vertex!(g2)
+    add_edge!(g2, 8, 9)
+
+    for g in testgraphs(g)
+        nodes_visited = fill(0, nv(g))
+        for (i, node) in enumerate(BFSIterator(g, 6))
+            nodes_visited[i] = node
+        end
+        @test nodes_visited[1] == 6
+        @test any(nodes_visited[2] .== [3, 5, 7])
+        if nodes_visited[2] == 3
+            @test nodes_visited[3:4] == [5, 7] || nodes_visited[3:4] == [7, 5]
+        elseif nodes_visited[2] == 5
+            @test nodes_visited[3:4] == [3, 7] || nodes_visited[3:4] == [7, 3]
+        else
+            @test nodes_visited[3:4] == [3, 5] || nodes_visited[3:4] == [5, 3]
+        end
+        @test any(nodes_visited[5] .== [1, 2, 4])
+        if nodes_visited[5] == 1
+            @test nodes_visited[6:7] == [2, 4] || nodes_visited[6:7] == [4, 2]
+        elseif nodes_visited[5] == 2
+            @test nodes_visited[6:7] == [1, 4] || nodes_visited[6:7] == [4, 1]
+        else
+            @test nodes_visited[6:7] == [1, 2] || nodes_visited[6:7] == [2, 1]
+        end
+    end
+    nodes_visited = Int[]
+    for (i, node) in enumerate(BFSIterator(g2, [1, 6]))
+        push!(nodes_visited, node)
+    end
+    @test nodes_visited == [1, 2, 3, 6, 5, 7, 4]
+    nodes_visited = Int[]
+    for (i, node) in enumerate(BFSIterator(g2, [8, 1, 6]))
+        push!(nodes_visited, node)
+    end
+    @test nodes_visited == [8, 9, 1, 2, 3, 6, 5, 7, 4]
+end

test/iterators/dfs.jl

@@ -0,0 +1,44 @@
+@testset "DFSIterator" begin
+    g = path_graph(7)
+    add_edge!(g, 6, 3)
+    add_edge!(g, 3, 1)
+    add_edge!(g, 4, 7)
+    g2 = deepcopy(g)
+    add_vertex!(g2)
+    add_vertex!(g2)
+    add_edge!(g2, 8, 9)
+
+    for g in testgraphs(g)
+        nodes_visited = fill(0, nv(g))
+        for (i, node) in enumerate(DFSIterator(g, 6))
+            nodes_visited[i] = node
+        end
+        @test nodes_visited[1:2] == [6, 3]
+        @test any(nodes_visited[3] .== [1, 4])
+        if nodes_visited[3] == 1
+            @test nodes_visited[4] == 2
+            @test nodes_visited[5] == 4
+            @test any(nodes_visited[6] .== [5, 7])
+            if nodes_visited[6] == 5
+                @test nodes_visited[7] == 7
+            end
+        else
+            @test any(nodes_visited[4] .== [5, 7])
+            if nodes_visited[4] == 5
+                @test nodes_visited[5] == 7
+            end
+            @test nodes_visited[6] == 1
+            @test nodes_visited[7] == 2
+        end
+    end
+    nodes_visited = Int[]
+    for (i, node) in enumerate(DFSIterator(g2, [1, 6]))
+        push!(nodes_visited, node)
+    end
+    @test nodes_visited == [1, 2, 3, 4, 5, 6, 7]
+    nodes_visited = Int[]
+    for (i, node) in enumerate(DFSIterator(g2, [8, 1, 6]))
+        push!(nodes_visited, node)
+    end
+    @test nodes_visited == [8, 9, 1, 2, 3, 4, 5, 6, 7]
+end

test/runtests.jl

@@ -106,6 +106,7 @@ tests = [
     "traversals/maxadjvisit",
     "traversals/randomwalks",
     "traversals/diffusion",
+    "iterators/iterators",
     "traversals/eulerian",
     "community/cliques",
     "community/core-periphery",