Introduce Arc and interfaces.

Still lots of conversion to do.

Author: sdboyer

edge.go

@@ -11,35 +11,54 @@ package gogl
 // the varying constraints and implementation needs, but still achieve optimal
 // performance given those constraints.
 
-// The Edge interface describes a connection between two vertices.
-//
-// Edge does not have an intrinsic opinion about directionality; gogl treats
-// that as a property of the overall Graph object in which the Edge appears
-// rather than a property of any individual Edge.
+// Edge describes an undirected connection between two vertices.
 type Edge interface {
+	Both() (u Vertex, v Vertex) // No order consistency is implied.
+}
+
+// Arc describes a directed connection between two vertices.
+type Arc interface {
+	Both() (u Vertex, v Vertex) // u is tail/source, v is head/target.
 	Source() Vertex
 	Target() Vertex
-	Both() (Vertex, Vertex)
 }
 
-// A WeightedEdge is an Edge that also has a numerical weight.
+// WeightedEdge describes an Edge that carries a numerical weight.
 type WeightedEdge interface {
 	Edge
 	Weight() float64
 }
 
-// A LabeledEdge is an Edge that also has a string label.
+// WeightedArc describes an Arc that carries a numerical weight.
+type WeightedArc interface {
+	Arc
+	Weight() float64
+}
+
+// LabeledEdge describes an Edge that also has a string label.
 type LabeledEdge interface {
 	Edge
 	Label() string
 }
 
-// A DataEdge is an Edge that also holds arbitrary data.
+// LabeledArc describes an Arc that also has a string label.
+type LabeledArc interface {
+	Arc
+	Label() string
+}
+
+// DataEdge describes an Edge that also holds arbitrary data.
 type DataEdge interface {
 	Edge
 	Data() interface{}
 }
 
+// DataArc describes an Arc that also holds arbitrary data.
+type DataArc interface {
+	Arc
+	Data() interface{}
+}
+
 /* Base implementations of Edge interfaces */
 
 // BaseEdge is a struct used to represent edges and meet the Edge interface
@@ -50,14 +69,6 @@ type baseEdge struct {
 	v Vertex
 }
 
-func (e baseEdge) Source() Vertex {
-	return e.u
-}
-
-func (e baseEdge) Target() Vertex {
-	return e.v
-}
-
 func (e baseEdge) Both() (Vertex, Vertex) {
 	return e.u, e.v
 }
@@ -67,6 +78,23 @@ func NewEdge(u, v Vertex) Edge {
 	return baseEdge{u: u, v: v}
 }
 
+type baseArc struct {
+	baseEdge
+}
+
+func (e baseArc) Source() Vertex {
+	return e.u
+}
+
+func (e baseArc) Target() Vertex {
+	return e.v
+}
+
+// Create a new basic arc.
+func NewArc(u, v Vertex) Arc {
+	return baseArc{baseEdge{u: u, v: v}}
+}
+
 // BaseWeightedEdge extends BaseEdge with weight data.
 type baseWeightedEdge struct {
 	baseEdge
@@ -82,6 +110,20 @@ func NewWeightedEdge(u, v Vertex, weight float64) WeightedEdge {
 	return baseWeightedEdge{baseEdge{u: u, v: v}, weight}
 }
 
+type baseWeightedArc struct {
+	baseArc
+	w float64
+}
+
+func (e baseWeightedArc) Weight() float64 {
+	return e.w
+}
+
+// Create a new weighted arc.
+func NewWeightedArc(u, v Vertex, weight float64) WeightedArc {
+	return baseWeightedArc{baseArc{baseEdge{u: u, v: v}}, weight}
+}
+
 // BaseLabeledEdge extends BaseEdge with label data.
 type baseLabeledEdge struct {
 	baseEdge
@@ -97,6 +139,21 @@ func NewLabeledEdge(u, v Vertex, label string) LabeledEdge {
 	return baseLabeledEdge{baseEdge{u: u, v: v}, label}
 }
 
+// BaseLabeledArc extends BaseArc with label data.
+type baseLabeledArc struct {
+	baseArc
+	l string
+}
+
+func (e baseLabeledArc) Label() string {
+	return e.l
+}
+
+// Create a new labeled arc.
+func NewLabeledArc(u, v Vertex, label string) LabeledArc {
+	return baseLabeledArc{baseArc{baseEdge{u: u, v: v}}, label}
+}
+
 // BaseDataEdge extends BaseEdge with arbitrary data.
 type baseDataEdge struct {
 	baseEdge
@@ -111,3 +168,18 @@ func (e baseDataEdge) Data() interface{} {
 func NewDataEdge(u, v Vertex, data interface{}) DataEdge {
 	return baseDataEdge{baseEdge{u: u, v: v}, data}
 }
+
+// BaseDataArc extends BaseArc with arbitrary data.
+type baseDataArc struct {
+	baseArc
+	d interface{}
+}
+
+func (e baseDataArc) Data() interface{} {
+	return e.d
+}
+
+// Create a new "data" edge - an edge with arbitrary embedded data.
+func NewDataArc(u, v Vertex, data interface{}) DataArc {
+	return baseDataArc{baseArc{baseEdge{u: u, v: v}}, data}
+}

graph.go

@@ -49,12 +49,20 @@ type GraphSource interface {
 	EdgeEnumerator
 }
 
+// DigraphSource is a subset of Digraph, describing the minimal set of methods
+// necessary to accomplish a naive full digraph traversal and copy.
+type DigraphSource interface {
+	GraphSource
+	ArcEnumerator
+}
+
 // Digraph (directed graph) describes a Graph where all the edges are directed.
 //
 // gogl treats edge directionality as a property of the graph, not the edge itself.
 // Thus, implementing this interface is gogl's only signal that a graph's edges are directed.
 type Digraph interface {
 	Graph
+	ArcEnumerator         // Enumerates all arcs to an injected step function
 	IncidentArcEnumerator // Enumerates a vertex's incident in- or out-arcs to an injected step function
 	DirectedDegreeChecker // Reports in- and out-degree of vertices
 	ProcessionEnumerator  // Enumerates a vertex's predecessor or successor vertices to a step function
@@ -167,6 +175,11 @@ type MutableDataGraph interface {
 // If the step function returns true, the calling enumerator is expected to end enumeration and return control to its caller.
 type EdgeStep func(Edge) (terminate bool)
 
+// ArcSteps are used as arguments to various enumerators. They are called once for each arc produced by the enumerator.
+//
+// If the step function returns true, the calling enumerator is expected to end enumeration and return control to its caller.
+type ArcStep func(Arc) (terminate bool)
+
 // VertexSteps are used as arguments to various enumerators. They are called once for each vertex produced by the enumerator.
 //
 // If the step function returns true, the calling enumerator is expected to end enumeration and return control to its caller.
@@ -187,6 +200,14 @@ type EdgeEnumerator interface {
 	EachEdge(EdgeStep)
 }
 
+// An ArcEnumerator iteratively enumerates edges, and can indicate the number of edges present.
+type ArcEnumerator interface {
+	// Calls the provided step function once with each edge in the graph. If a
+	// specialized edge type (e.g., weighted) is known to be used by the
+	// graph, it is the calling code's responsibility to type assert.
+	EachArc(ArcStep)
+}
+
 // An IncidentEdgeEnumerator iteratively enumerates a given vertex's incident edges.
 type IncidentEdgeEnumerator interface {
 	// Calls the provided step function once with each edge incident to the
@@ -257,24 +278,48 @@ type EdgeSetMutator interface {
 	RemoveEdges(edges ...Edge)
 }
 
+// An ArcSetMutator allows the addition and removal of arcs from a set.
+type ArcSetMutator interface {
+	AddArcs(arcs ...Arc)
+	RemoveArcs(arcs ...Arc)
+}
+
 // A WeightedEdgeSetMutator allows the addition and removal of weighted edges from a set.
 type WeightedEdgeSetMutator interface {
 	AddEdges(edges ...WeightedEdge)
 	RemoveEdges(edges ...WeightedEdge)
 }
 
+// A WeightedArcSetMutator allows the addition and removal of weighted arcs from a set.
+type WeightedArcSetMutator interface {
+	AddArcs(arcs ...WeightedArc)
+	RemoveArcs(arcs ...WeightedArc)
+}
+
 // A LabeledEdgeSetMutator allows the addition and removal of labeled edges from a set.
 type LabeledEdgeSetMutator interface {
 	AddEdges(edges ...LabeledEdge)
 	RemoveEdges(edges ...LabeledEdge)
 }
 
+// A LabeledArcSetMutator allows the addition and removal of labeled arcs from a set.
+type LabeledArcSetMutator interface {
+	AddArcs(arcs ...LabeledArc)
+	RemoveArcs(arcs ...LabeledArc)
+}
+
 // A DataEdgeSetMutator allows the addition and removal of data edges from a set.
 type DataEdgeSetMutator interface {
 	AddEdges(edges ...DataEdge)
 	RemoveEdges(edges ...DataEdge)
 }
 
+// A DataArcSetMutator allows the addition and removal of data arcs from a set.
+type DataArcSetMutator interface {
+	AddArcs(arcs ...DataArc)
+	RemoveArcs(arcs ...DataArc)
+}
+
 /* Optional optimization interfaces
 
 These interfaces describe behaviors and information about a graph which can be

null.go

@@ -20,6 +20,7 @@ var _ DataGraph = nullGraph(false)
 
 func (g nullGraph) EachVertex(f VertexStep)                   {}
 func (g nullGraph) EachEdge(f EdgeStep)                       {}
+func (g nullGraph) EachArc(f ArcStep)                         {}
 func (g nullGraph) EachEdgeIncidentTo(Vertex, EdgeStep)       {}
 func (g nullGraph) EachArcFrom(Vertex, EdgeStep)              {}
 func (g nullGraph) EachPredecessorOf(Vertex, VertexStep)      {}