.. _py-graph/Union:

**********************************************************
graph/Union
**********************************************************
.. default-domain:: py

.. py:currentmodule:: mod
.. cpp:namespace:: mod

.. class:: UnionGraph

    An adaptor for a multiset of :class:`Graph`\ s to present them
    as their disjoint union.

    It functions as an iterable of the adapted graphs,
    and it implements the :class:`protocols.LabelledGraph` protocol.

    .. method:: __init__()
                __init__(graphs)

        Construct a graph representing the disjoint union of ``graphs``.
        Thus, if no graphs are given the empty graph is constructed.

        :param graphs: the list of graphs to adapt.
        :type graphs: list[Graph]
        :raises LogicError: if a given graph is ``None``.
    .. method:: __str__()

        :rtype: str
    .. method:: __len__()

        :returns: the number of adapted graphs.
        :rtype: int
    .. method:: __iter__()

        :returns: the range of graphs adapted by this object.
    .. method:: __getitem__(i)

        :returns: the ``i``\ th adapted graph.
        :rtype: Graph
        :raises: :class:`LogicError` if ``i`` is out of range.
    .. method:: printTermState

        Print the term state for the graph.
    .. class:: Vertex

        Implements the :class:`protocols.LabelledGraph.Vertex` protocol.
        Additionally, the :attr:`id <protocols.Graph.Vertex.id>` is in the range :math:`[0, numVertices[`.

        A non-null vertex represents a specific :class:`Graph.Vertex`.
        As the same :class:`Graph` can be part of a :class:`UnionGraph` multiple times,
        a vertex also has a graph index to determine which instance of a :class:`Graph`
        in the :class:`UnionGraph` the vertex refers to.

        .. attribute:: graphIndex

            (Read-only) The index of the graph in the owning :class:`UnionGraph` this vertex
            is from. The index is thus in the range :math:`[0, len(graph)[`.

            We can obtain the underlying :class:`Graph` this vertex, ``self``,
            is from both directly via the :attr:`vertex` attribute as ``self.vertex.graph``,
            or via the graph index as ``self.graph[self.graphIndex]``.

            :type: int
            :raises: :class:`LogicError` if it is a null vertex.
        .. attribute:: vertex

            (Read-only) The underlying :class:`Graph.Vertex` this vertex represents.

            We can obtain the underlying :class:`Graph` this vertex, ``self``,
            is from both directly via the :attr:`vertex` attribute as ``self.vertex.graph``,
            or via the graph index as ``self.graph[self.graphIndex]``.

            :type: Graph.Vertex
            :raises: :class:`LogicError` if it is a null vertex.
    .. class:: Edge

        Implements the :class:`protocols.LabelledGraph.Vertex` protocol.

        A non-null edge represents a specific :class:`Graph.Edge`.
        As the same :class:`Graph` can be part of a :class:`UnionGraph` multiple times,
        an edge also has a graph index to determine which instance of a :class:`Graph`
        in the :class:`UnionGraph` the edge refers to.

        .. attribute:: graphIndex

            (Read-only) The index of the graph in the owning :class:`UnionGraph` this edge
            is from. The index is thus in the range :math:`[0, len(graph)[`.

            We can obtain the underlying :class:`Graph` this edge, ``self``,
            is from both directly via the :attr:`edge` attribute as ``self.edge.graph``,
            or via the graph index as ``self.graph[self.graphIndex]``.

            :type: int
            :raises: :class:`LogicError` if it is a null edge.
        .. attribute:: edge

            (Read-only) The underlying :class:`Graph.Edge` this edge represents.

            We can obtain the underlying :class:`Graph` this edge, ``self``,
            is from both directly via the :attr:`edge` attribute as ``self.edge.graph``,
            or via the graph index as ``self.graph[self.graphIndex]``.

            :type: Graph.Edge
            :raises: :class:`LogicError` if it is a null edge.
    .. class:: VertexRange

        Implements the :class:`protocols.Graph.VertexRange` protocol,
        in addition to the following functionality.

        .. method:: __getitem__(i)

            :returns: the ``i``\ th vertex of the graph.
            :rtype: UnionGraph.Vertex
    .. class:: EdgeRange

        Implements the :class:`protocols.Graph.EdgeRange` protocol.

    .. class:: IncidentEdgeRange

        Implements the :class:`protocols.Graph.IncidentEdgeRange` protocol.

.. class:: VertexMapUnionGraphUnionGraph

    Implements the :class:`protocols.VertexMap` protocol.