Add DigraphByEdges variant for list of arbitrary vertex labels and list of edges

doc/digraph.xml

@@ -244,9 +244,9 @@ gap> gr := Digraph([1 .. 10], ReturnTrue);
 gap> Digraph("Diamond");
 <immutable digraph with 4 vertices, 10 edges>]]></Example>
 
-      The next example illustrates the uses of the fourth and fifth variants of
-      this constructor. The resulting digraph is a strongly regular graph, and
-      it is actually the point graph of the van Lint-Schrijver partial
+      The next example illustrates the uses of the variants of this constructor
+      involving functions. The resulting digraph is a strongly regular graph,
+      and it is actually the point graph of the van Lint-Schrijver partial
       geometry, <Cite Key="vLS81"/>.  The algebraic description
       is taken from the seminal paper of Calderbank and Kantor <Cite
         Key="CK86"/>.
@@ -323,6 +323,8 @@ gap> D := DigraphByAdjacencyMatrix(IsMutableDigraph,
 <#GAPDoc Label="DigraphByEdges">
 <ManSection>
   <Oper Name="DigraphByEdges" Arg="[filt, ]list[, n]"/>
+  <Oper Name="DigraphByEdges" Arg="[filt, ]labels, edges"
+        Label="for vertex labels and edges"/>
   <Returns>A digraph.</Returns>
   <Description>
     &STANDARD_FILT_TEXT;
@@ -336,8 +338,15 @@ gap> D := DigraphByAdjacencyMatrix(IsMutableDigraph,
     then this function returns the digraph with <A>n</A> vertices and list
     <A>list</A>. <P/>
 
-    See <Ref Attr="DigraphEdges"/>.
+    If <A>labels</A> is a duplicate-free list, and <A>edges</A> is a list of
+    pairs of elements from <A>labels</A>, then this function returns a digraph
+    with vertices <C>[1 .. Length(<A>labels</A>)]</C> and
+    <C>Length(<A>edges</A>)</C> edges. For each <C>i</C> in
+    <C>[1 .. Length(<A>edges</A>)]</C> there exists an edge given by the
+    pair at <C>edges[i]</C>. The vertices of the digraph will be labelled by
+    the elements of <A>labels</A>. <P/>
 
+    See <Ref Attr="DigraphEdges"/>.
     <Example><![CDATA[
 gap> DigraphByEdges(
 > [[1, 3], [2, 1], [2, 3], [2, 5], [3, 6],
@@ -351,6 +360,12 @@ gap> DigraphByEdges(IsMutableDigraph,
 > [[1, 3], [2, 1], [2, 3], [2, 5], [3, 6],
 >  [4, 6], [5, 2], [5, 4], [5, 6], [6, 6]], 12);
 <mutable digraph with 12 vertices, 10 edges>
+gap> gr := DigraphByEdges(
+> ["a", "b", "x", "y"],
+> [["a", "x"], ["x", "b"]]);
+<immutable digraph with 4 vertices, 2 edges>
+gap> IsIsomorphicDigraph(Digraph([[3], [], [2], []]), gr);
+true
 ]]></Example>
   </Description>
 </ManSection>

gap/digraph.gd

@@ -90,6 +90,7 @@ DeclareOperation("DigraphByEdges", [IsFunction, IsList]);
 DeclareOperation("DigraphByEdges", [IsFunction, IsList, IsInt]);
 DeclareOperation("DigraphByEdges", [IsList]);
 DeclareOperation("DigraphByEdges", [IsList, IsInt]);
+DeclareOperation("DigraphByEdges", [IsList, IsList]);
 
 DeclareConstructor("DigraphByInNeighboursCons", [IsDigraph, IsList]);
 DeclareConstructor("DigraphByInNeighboursConsNC", [IsDigraph, IsList]);

gap/digraph.gi

@@ -969,6 +969,42 @@ InstallMethod(DigraphByEdges, "for a function, a list, and an integer",
 InstallMethod(DigraphByEdges, "for a function and a list",
 [IsFunction, IsList], DigraphByEdgesCons);
 
+InstallMethod(DigraphByEdges, "for a list and a list", [IsList, IsList],
+function(vertex_labels, edges)
+  local label_counts, duplicates, badpos, labels, D, nrverts;
+
+  label_counts := Collected(vertex_labels);
+  duplicates := List(Filtered(label_counts, x -> x[2] > 1), x -> x[1]);
+  if not IsEmpty(duplicates) then
+    ErrorNoReturn("<vertex_labels> contains duplicate labels: ",
+                  duplicates, ",");
+  fi;
+
+  # get first invalid edge - malformed
+  badpos := PositionProperty(edges, e -> not IsList(e) or Length(e) <> 2);
+  if badpos <> fail then
+    ErrorNoReturn("invalid edge ", edges[badpos], " in position ", badpos,
+                  " in <edges>; edges must be pairs of elements,");
+  fi;
+
+  #  get first invalid edge - bad reference
+  labels := Set(vertex_labels);  # set makes it faster to check containment
+  badpos := PositionProperty(edges,
+                             e -> not (e[1] in labels and e[2] in labels));
+  if badpos <> fail then
+    ErrorNoReturn("invalid edge ", edges[badpos], " in <edges> at position ",
+                  badpos, "; edges must reference vertices from ",
+                  vertex_labels, ",");
+  fi;
+
+  nrverts := Length(vertex_labels);
+  D := DigraphByEdges(List(edges,
+                           x -> [Position(vertex_labels, x[1]),
+                                 Position(vertex_labels, x[2])]), nrverts);
+  SetDigraphVertexLabels(D, vertex_labels);
+  return D;
+end);
+
 InstallMethod(DigraphByInNeighboursCons, "for IsMutableDigraph, and a list",
 [IsMutableDigraph, IsList],
 function(_, list)

tst/standard/digraph.tst

@@ -332,6 +332,20 @@ Error, the 1st argument (list of edges) must be pairs of positive integers but\
 gap> DigraphByEdges([12], 10);
 Error, the 1st argument (list of edges) must be a list of lists, but found int\
 eger in position 1
+gap> DigraphByEdges(["a", "b"], [["a", "a"]]);
+<immutable digraph with 2 vertices, 1 edge>
+gap> DigraphByEdges(["a", "b"], [["a", "a"], ["a", "a"]]);
+<immutable multidigraph with 2 vertices, 2 edges>
+gap> D1 := DigraphByEdges([[1], -1, "abc", true],
+>                         [[-1, [1]], ["abc", -1]]);;
+gap> D2 := Digraph([[], [1], [2], []]);;
+gap> IsIsomorphicDigraph(D1, D2);
+true
+gap> DigraphByEdges([1, 2], [[2, 3]]);
+Error, invalid edge [ 2, 3 ] in <edges> at position 
+1; edges must reference vertices from [ 1, 2 ],
+gap> DigraphByEdges([1, 1, 2], [1, 2]);
+Error, <vertex_labels> contains duplicate labels: [ 1 ],
 
 #  DigraphByAdjacencyMatrix (by an integer matrix)