#############################################################################
##
#W  labels.xml
#Y  Copyright (C) 2019                                  James D. Mitchell
##                                                      Wilf A. Wilson
##
##  Licensing information can be found in the README file of this package.
##
#############################################################################
##

<#GAPDoc Label="DigraphVertexLabel">
<ManSection>
  <Oper Name = "DigraphVertexLabel" Arg="digraph, i"/>
  <Oper Name ="SetDigraphVertexLabel" Arg="digraph, i, obj"/>
  <Description>
    If <A>digraph</A> is a digraph, then the first operation returns the label
    of the vertex <A>i</A>. The second operation can be used to set the label
    of the vertex <A>i</A> in <A>digraph</A> to the arbitrary &GAP; object
    <A>obj</A>.  <P/>

    The label of a vertex can be changed an arbitrary number of times. If no
    label has been set for the vertex <A>i</A>, then the default value is
    <A>i</A>. <P/>

    If <A>digraph</A> is a digraph created from a record with a component
    <C>vertices</C>, then the labels of the vertices are set to the value of
    this component.<P/>

    Induced subdigraphs, and some other operations which create new digraphs from
    old ones, inherit their labels from their parents.

    <Example><![CDATA[
gap> D := DigraphFromDigraph6String("&DHUEe_");
<immutable digraph with 5 vertices, 11 edges>
gap> DigraphVertexLabel(D, 3);
3
gap> D := Digraph(["a", "b", "c"], [], []);
<immutable empty digraph with 3 vertices>
gap> DigraphVertexLabel(D, 2);
"b"
gap> SetDigraphVertexLabel(D, 2, "d");
gap> DigraphVertexLabel(D, 2);
"d"
gap> D := InducedSubdigraph(D, [1, 2]);
<immutable empty digraph with 2 vertices>
gap> DigraphVertexLabel(D, 2);
"d"
gap> D := Digraph(IsMutableDigraph, ["e", "f", "g"], [], []);
<mutable empty digraph with 3 vertices>
gap> DigraphVertexLabel(D, 1);
"e"
gap> SetDigraphVertexLabel(D, 1, "h");
gap> DigraphVertexLabel(D, 1);
"h"
gap> InducedSubdigraph(D, [1, 2]);
<mutable empty digraph with 2 vertices>
gap> DigraphVertexLabel(D, 1);
"h"
]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="DigraphVertexLabels">
<ManSection>
  <Oper Name="DigraphVertexLabels" Arg="digraph"/>
  <Oper Name="SetDigraphVertexLabels" Arg="digraph, list"/>
  <Description>
    If <A>digraph</A> is a digraph, then <C>DigraphVertexLabels</C> returns a
    copy of the labels of the vertices in <A>digraph</A>.
    <C>SetDigraphVertexLabels</C> can be used to set the labels of the vertices
    in <A>digraph</A> to the list of
    arbitrary &GAP; objects <A>list</A>. <P/>

    The label of a vertex can be changed an arbitrary number of times. If no
    label has been set for the vertex <A>i</A>, then the default value is
    <A>i</A>. <P/>

    If <A>digraph</A> is a digraph created from a record with a component
    <C>vertices</C>, then the labels of the vertices are set to the value of
    this component.<P/>

    Induced subdigraphs, and other operations which create new digraphs from
    old ones, inherit their labels from their parents.

    <Example><![CDATA[
gap> D := DigraphFromDigraph6String("&DHUEe_");
<immutable digraph with 5 vertices, 11 edges>
gap> DigraphVertexLabels(D);
[ 1 .. 5 ]
gap> D := Digraph(["a", "b", "c"], [], []);
<immutable empty digraph with 3 vertices>
gap> DigraphVertexLabels(D);
[ "a", "b", "c" ]
gap> SetDigraphVertexLabel(D, 2, "d");
gap> DigraphVertexLabels(D);
[ "a", "d", "c" ]
gap> D := InducedSubdigraph(D, [1, 3]);
<immutable empty digraph with 2 vertices>
gap> DigraphVertexLabels(D);
[ "a", "c" ]
gap> D := Digraph(IsMutableDigraph, ["e", "f", "g"], [], []);
<mutable empty digraph with 3 vertices>
gap> SetDigraphVertexLabels(D, ["h", "i", "j"]);
gap> DigraphVertexLabels(D);
[ "h", "i", "j" ]
gap> InducedSubdigraph(D, [1, 3]);
<mutable empty digraph with 2 vertices>
gap> DigraphVertexLabels(D);
[ "h", "j" ]
]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="DigraphEdgeLabel">
<ManSection>
  <Oper Name = "DigraphEdgeLabel" Arg="digraph, i, j"/>
  <Oper Name = "SetDigraphEdgeLabel" Arg="digraph, i, j, obj"/>
  <Description>
    If <A>digraph</A> is a digraph without multiple edges, then the first
    operation returns the label of the edge from vertex <A>i</A> to vertex
    <A>j</A>.  The second operation can be used to set the label of the edge
    between vertex <A>i</A> and vertex <A>j</A> to the arbitrary &GAP; object
    <A>obj</A>. <P/>

    The label of an edge can be changed an arbitrary number of times. If no
    label has been set for the edge, then the default value is <A>1</A>. <P/>

    Induced subdigraphs, and some other operations which create new digraphs from
    old ones, inherit their edge labels from their parents.

    See also <Ref Oper="DigraphEdgeLabels"/>.

    <Example><![CDATA[
gap> D := DigraphFromDigraph6String("&DHUEe_");
<immutable digraph with 5 vertices, 11 edges>
gap> DigraphEdgeLabel(D, 3, 1);
1
gap> SetDigraphEdgeLabel(D, 2, 5, [42]);
gap> DigraphEdgeLabel(D, 2, 5);
[ 42 ]
gap> D := InducedSubdigraph(D, [2, 5]);
<immutable digraph with 2 vertices, 3 edges>
gap> DigraphEdgeLabel(D, 1, 2);
[ 42 ]
gap> D := ChainDigraph(IsMutableDigraph, 5);
<mutable digraph with 5 vertices, 4 edges>
gap> DigraphEdgeLabel(D, 2, 3);
1
gap> SetDigraphEdgeLabel(D, 4, 5, [1729]);
gap> DigraphEdgeLabel(D, 4, 5);
[ 1729 ]
gap> InducedSubdigraph(D, [4, 5]);
<mutable digraph with 2 vertices, 1 edge>
gap> DigraphEdgeLabel(D, 1, 2);
[ 1729 ]
]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="DigraphEdgeLabels">
<ManSection>
  <Oper Name="DigraphEdgeLabels" Arg="digraph"/>
  <Oper Name="SetDigraphEdgeLabels" Arg="digraph, labels"
    Label="for a digraph and a list of lists"/>
  <Oper Name="SetDigraphEdgeLabels" Arg="digraph, func"
    Label="for a digraph and a function"/>
  <Description>
    If <A>digraph</A> is a digraph without multiple edges, then
    <C>DigraphEdgeLabels</C> returns a copy of the labels of the edges
    in <A>digraph</A> as a list of lists <C>labels</C> such that
    <C>labels[i][j]</C> is the label on the edge from vertex <C>i</C>
    to vertex <C>OutNeighbours(digraph)[i][j]</C>.

    <C>SetDigraphEdgeLabels</C> can be used to set the labels of the edges in
    <A>digraph</A> without multiple edges to the list <A>labels</A> of lists of
    arbitrary &GAP; objects such that <C>list[i][j]</C> is the label on the edge
    from vertex <C>i</C> to the vertex <C>OutNeighbours(digraph>[i][j]</C>.

    Alternatively <C>SetDigraphEdgeLabels</C> can be called with binary function
    <A>func</A> that as its second argument that when passed two vertices <C>i</C>
    and <C>j</C> returns the label for the edge between vertex <C>i</C> and vertex
    <C>j</C>. <P/>

    The label of an edge can be changed an arbitrary number of times. If no
    label has been set for an edge, then the default value is <C>1</C>. <P/>

    Induced subdigraphs, and some other operations which create new digraphs
    from old ones, inherit their labels from their parents.

    <Example><![CDATA[
gap> D := DigraphFromDigraph6String("&DHUEe_");
<immutable digraph with 5 vertices, 11 edges>
gap> DigraphEdgeLabels(D);
[ [ 1 ], [ 1, 1, 1 ], [ 1 ], [ 1, 1, 1 ], [ 1, 1, 1 ] ]
gap> SetDigraphEdgeLabel(D, 2, 1, "d");
gap> DigraphEdgeLabels(D);
[ [ 1 ], [ "d", 1, 1 ], [ 1 ], [ 1, 1, 1 ], [ 1, 1, 1 ] ]
gap> D := InducedSubdigraph(D, [1, 2, 3]);
<immutable digraph with 3 vertices, 4 edges>
gap> DigraphEdgeLabels(D);
[ [ 1 ], [ "d", 1 ], [ 1 ] ]
gap> OutNeighbours(D);
[ [ 3 ], [ 1, 3 ], [ 1 ] ]
gap> D := CompleteBipartiteDigraph(IsMutableDigraph, 2, 3);
<mutable digraph with 5 vertices, 12 edges>
gap> DigraphEdgeLabels(D);
[ [ 1, 1, 1 ], [ 1, 1, 1 ], [ 1, 1 ], [ 1, 1 ], [ 1, 1 ] ]
gap> SetDigraphEdgeLabel(D, 2, 4, "a");
gap> DigraphEdgeLabels(D);
[ [ 1, 1, 1 ], [ 1, "a", 1 ], [ 1, 1 ], [ 1, 1 ], [ 1, 1 ] ]
gap> InducedSubdigraph(D, [1, 2, 3, 4]);
<mutable digraph with 4 vertices, 8 edges>
gap> DigraphEdgeLabels(D);
[ [ 1, 1 ], [ 1, "a" ], [ 1, 1 ], [ 1, 1 ] ]
gap> OutNeighbors(D);
[ [ 3, 4 ], [ 3, 4 ], [ 1, 2 ], [ 1, 2 ] ]
]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>
