#############################################################################
##
#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>DigraphVertices</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>, which must be of the same length
    as the number of vertices of <A>digraph</A>. <P/>

    If the list <A>list</A> is immutable, then the vertex labels are set to a
    mutable copy of <A>list</A>. Otherwise, the labels are set to exactly
    <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>DigraphVertices</C>, then the labels of the vertices are set to the
    value of this component. As in the above, if the component is immutable
    then the digraph's vertex labels are set to a mutable copy of
    <C>DigraphVertices</C>. Otherwise, they are set to exactly
    <C>DigraphVertices</C>. <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>
