.. _cpp-dg/GraphInterface:

**********************************************************
dg/GraphInterface.hpp
**********************************************************
.. default-domain:: cpp
.. default-role:: cpp:expr

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

This header contains the definitions for the hypergraph interface for :class:`dg::DG`.


Class ``dg::DG::Vertex``
--------------------------------------------------------------------------------------------------------------------------------

.. class:: dg::DG::Vertex
    

    A descriptor of either a vertex in a graph, or a null vertex.


Synopsis
^^^^^^^^

.. code-block:: c++
    
    class MOD_DECL DG::Vertex {
        friend class lib::DG::Hyper;
        Vertex(std::shared_ptr<DG> g, std::size_t vId);
    public:
        Vertex();
        MOD_DECL friend std::ostream &operator<<(std::ostream &s, const Vertex &v);
        MOD_DECL friend bool operator==(const Vertex &v1, const Vertex &v2);
        MOD_DECL friend bool operator!=(const Vertex &v1, const Vertex &v2);
        MOD_DECL friend bool operator<(const Vertex &v1, const Vertex &v2);
        std::size_t hash() const;
        explicit operator bool() const;
        bool isNull() const;
        std::size_t getId() const;
        std::shared_ptr<DG> getDG() const;
        std::size_t inDegree() const;
        InEdgeRange inEdges() const;
        std::size_t outDegree() const;
        OutEdgeRange outEdges() const;
        std::shared_ptr<graph::Graph> getGraph() const;
    private:
        std::shared_ptr<DG> g;
        std::size_t vId;
    };

Details
^^^^^^^

.. cpp:namespace-push:: dg::DG::Vertex

.. function:: Vertex()

    Constructs a null descriptor.
.. function:: explicit operator bool() const

    :returns: `!isNull()`
.. function:: bool isNull() const

    :returns: whether this is a null descriptor or not.
.. function:: std::size_t getId() const

    :returns: the index of the vertex. It will be in the range :math:`[0, numVertices + numEdges[`.
    :throws: :class:`LogicError` if it is a null descriptor.
.. function:: std::shared_ptr<DG> getDG() const

    :returns: the derivation graph the vertex belongs to.
    :throws: :class:`LogicError` if it is a null descriptor.
.. function:: std::size_t inDegree() const

    :returns: the in-degree of the vertex, including multiplicity of target multisets.
    :throws: :class:`LogicError` if it is a null descriptor.
.. function:: InEdgeRange inEdges() const

    :returns: a range of in-hyperedges for this vertex.
    :throws: :class:`LogicError` if it is a null descriptor.
.. function:: std::size_t getOutDegree() const

    :returns: the out-degree of the vertex, including multiplicity of source multisets.
    :throws: :class:`LogicError` if it is a null descriptor.
.. function:: OutEdgeRange outEdges() const

    :returns: a range of out-hyperedges for this vertex.
    :throws: :class:`LogicError` if it is a null descriptor.
.. function:: std::shared_ptr<graph::Graph> &getGraph() const

    :returns: the graph label of the vertex.
    :throws: :class:`LogicError` if it is a null descriptor.

.. cpp:namespace-pop::


Class ``dg::DG::HyperEdge``
--------------------------------------------------------------------------------------------------------------------------------

.. class:: dg::DG::HyperEdge
    

    A descriptor of either a hyperedge in a derivation graph, or a null edge.

Synopsis
^^^^^^^^

.. code-block:: c++
    
    class MOD_DECL DG::HyperEdge {
        friend class lib::DG::Hyper;
        HyperEdge(std::shared_ptr<DG> g, std::size_t eId);
    public:
        HyperEdge();
        MOD_DECL friend std::ostream &operator<<(std::ostream &s, const HyperEdge &e);
        MOD_DECL friend bool operator==(const HyperEdge &e1, const HyperEdge &e2);
        MOD_DECL friend bool operator!=(const HyperEdge &e1, const HyperEdge &e2);
        MOD_DECL friend bool operator<(const HyperEdge &e1, const HyperEdge &e2);
        std::size_t hash() const;
        explicit operator bool() const;
        bool isNull() const;
        std::size_t getId() const;
        std::shared_ptr<DG> getDG() const;
        std::size_t numSources() const;
        SourceRange sources() const;
        std::size_t numTargets() const;
        TargetRange targets() const;
        RuleRange rules() const;
        HyperEdge getInverse() const;
    public:
        std::vector<std::pair<std::string, std::string>>
        print(const graph::Printer &printer, const std::string &nomatchColour, const std::string &matchColour) const;
    private:
        std::shared_ptr<DG> g;
        std::size_t eId;
    };

Details
^^^^^^^

.. cpp:namespace-push:: dg::DG::HyperEdge

.. function:: HyperEdge()

    Constructs a null descriptor.
.. function:: explicit operator bool() const

    :returns: `!isNull()`
.. function:: bool isNull() const

    :returns: whether this is a null descriptor or not.
.. function:: std::size_t getId() const

    :returns: the index of the hyperedge. It will be in the range :math:`[0, numVertices + numEdges[`.
    :throws: :class:`LogicError` if it is a null descriptor.
.. function:: std::shared_ptr<DG> getDG() const

    :returns: the derivation graph the hyperedge belongs to.
    :throws: :class:`LogicError` if it is a null descriptor.
.. function:: std::size_t numSources() const

    :returns: the number of sources of the hyperedge.
    :throws: :class:`LogicError` if it is a null descriptor.
.. function:: SourceRange sources() const

    :returns: the sources of the hyperedge.
    :throws: :class:`LogicError` if it is a null descriptor.
.. function:: std::size_t numTargets() const

    :returns: the number of targets of the hyperedge.
    :throws: :class:`LogicError` if it is a null descriptor.
.. function:: TargetRange targets() const

    :returns: the targets of the hyperedge.
    :throws: :class:`LogicError` if it is a null descriptor.
.. function:: RuleRange rules() const

    :returns: a range of the rules associated with the hyperedge.
    :throws: :class:`LogicError` if it is a null descriptor.
.. function:: HyperEdge getInverse() const

    :returns: a descriptor for the inverse hyperedge of this one, if it exists.
        Otherwise a null descriptor is returned.
    :throws: :class:`LogicError` if it is a null descriptor.
    :throws: :class:`LogicError` if not `getDG()->isLocked()`.
.. function:: std::vector<std::pair<std::string, std::string>> \
              print(const graph::Printer &printer, const std::string &nomatchColour, const std::string &matchColour) const

    Print the derivations represented by the hyperedge.
    All possible Double-Pushout diagrams are printed.
    The `matchColour` must be a valid colour for TikZ, which is applied to the rule
    and its image in the bottom span.

    :returns: A list with file data for each DPO diagram printed.
        Each element is a pair of filename prefixes, where the first entry is completed by appending ``_derL``, ``_derK``, or ``_derR``.
        The second entry is completed similarly by appending ``_derG``, ``_derD``, or ``_derH``.
    :throws: :class:`LogicError` if it is a null descriptor.
    :throws: :class:`LogicError` if it has no rules.

.. cpp:namespace-pop::


Class ``dg::DG::VertexIterator``
--------------------------------------------------------------------------------------------------------------------------------

.. class:: dg::DG::VertexIterator
    

    An iterator for traversing all vertices in a derivation graph.
    It models a forward iterator.


Synopsis
^^^^^^^^

.. code-block:: c++
    
    class MOD_DECL DG::VertexIterator
            : public boost::iterator_facade<VertexIterator, Vertex, std::forward_iterator_tag, Vertex> {
        friend class DG;
        VertexIterator(std::shared_ptr<DG> g);
    public:
        VertexIterator();
    private:
        friend class boost::iterator_core_access;
        Vertex dereference() const;
        bool equal(const VertexIterator &iter) const;
        void increment();
    private:
        std::shared_ptr<DG> g;
        std::size_t vId;
    };

Details
^^^^^^^

.. cpp:namespace-push:: dg::DG::VertexIterator

.. function:: VertexIterator()

    Construct a past-the-end iterator.

.. cpp:namespace-pop::


Class ``dg::DG::VertexRange``
--------------------------------------------------------------------------------------------------------------------------------

.. class:: dg::DG::VertexRange
    

    A range of all vertices in a derivation graph.


Synopsis
^^^^^^^^

.. code-block:: c++
    
    struct DG::VertexRange {
        using iterator = VertexIterator;
        using const_iterator = iterator;
    private:
        friend class DG;
        VertexRange(std::shared_ptr<DG> g);
    public:
        VertexIterator begin() const;
        VertexIterator end() const;
    private:
        std::shared_ptr<DG> g;
    };

Class ``dg::DG::EdgeIterator``
--------------------------------------------------------------------------------------------------------------------------------

.. class:: dg::DG::EdgeIterator
    

    An iterator for traversing all edges in a graph.
    It models a forward iterator.


Synopsis
^^^^^^^^

.. code-block:: c++
    
    class MOD_DECL DG::EdgeIterator
            : public boost::iterator_facade<EdgeIterator, HyperEdge, std::forward_iterator_tag, HyperEdge> {
        friend class DG;
        EdgeIterator(std::shared_ptr<DG> g);
    public:
        EdgeIterator();
    private:
        friend class boost::iterator_core_access;
        HyperEdge dereference() const;
        bool equal(const EdgeIterator &iter) const;
        void increment();
    private:
        std::shared_ptr<DG> g;
        std::size_t eId;
    };

Details
^^^^^^^

.. cpp:namespace-push:: dg::DG::EdgeIterator

.. function:: EdgeIterator()

    Construct a past-the-end iterator.

.. cpp:namespace-pop::


Class ``dg::DG::EdgeRange``
--------------------------------------------------------------------------------------------------------------------------------

.. class:: dg::DG::EdgeRange
    

    A range of all edges in a derivation graph.


Synopsis
^^^^^^^^

.. code-block:: c++
    
    struct DG::EdgeRange {
        using iterator = EdgeIterator;
        using const_iterator = iterator;
    private:
        friend class DG;
        EdgeRange(std::shared_ptr<DG> g);
    public:
        EdgeIterator begin() const;
        EdgeIterator end() const;
    private:
        std::shared_ptr<DG> g;
    };

Class ``dg::DG::InEdgeIterator``
--------------------------------------------------------------------------------------------------------------------------------

.. class:: dg::DG::InEdgeIterator
    

    An iterator for enumerating all in-edges of a vertex.
    It models a forward iterator.


Synopsis
^^^^^^^^

.. code-block:: c++
    
    class MOD_DECL DG::InEdgeIterator
            : public boost::iterator_facade<InEdgeIterator, HyperEdge, std::forward_iterator_tag, HyperEdge> {
        friend class InEdgeRange;
        InEdgeIterator(std::shared_ptr<DG> g, std::size_t vId);
    public:
        InEdgeIterator();
    private:
        friend class boost::iterator_core_access;
        HyperEdge dereference() const;
        bool equal(const InEdgeIterator &iter) const;
        void increment();
    private:
        std::shared_ptr<DG> g;
        std::size_t vId, eId;
    };

Details
^^^^^^^

.. cpp:namespace-push:: dg::DG::InEdgeIterator

.. function:: InEdgeIterator()

    Construct a past-the-end iterator.

.. cpp:namespace-pop::


Class ``dg::DG::InEdgeRange``
--------------------------------------------------------------------------------------------------------------------------------

.. class:: dg::DG::InEdgeRange
    

    A range of all in-edges of a vertex.


Synopsis
^^^^^^^^

.. code-block:: c++
    
    struct DG::InEdgeRange {
        using iterator = InEdgeIterator;
        using const_iterator = iterator;
    private:
        friend class Vertex;
        InEdgeRange(std::shared_ptr<DG> g, std::size_t vId);
    public:
        InEdgeIterator begin() const;
        InEdgeIterator end() const;
    private:
        std::shared_ptr<DG> g;
        std::size_t vId;
    };

Class ``dg::DG::OutEdgeIterator``
--------------------------------------------------------------------------------------------------------------------------------

.. class:: dg::DG::OutEdgeIterator
    

    An iterator for enumerating all out-edges of a vertex.
    It models a forward iterator.


Synopsis
^^^^^^^^

.. code-block:: c++
    
    class MOD_DECL DG::OutEdgeIterator
            : public boost::iterator_facade<OutEdgeIterator, HyperEdge, std::forward_iterator_tag, HyperEdge> {
        friend class OutEdgeRange;
        OutEdgeIterator(std::shared_ptr<DG> g, std::size_t vId);
    public:
        OutEdgeIterator();
    private:
        friend class boost::iterator_core_access;
        HyperEdge dereference() const;
        bool equal(const OutEdgeIterator &iter) const;
        void increment();
    private:
        std::shared_ptr<DG> g;
        std::size_t vId, eId;
    };

Details
^^^^^^^

.. cpp:namespace-push:: dg::DG::OutEdgeIterator

.. function:: OutEdgeIterator()

    Construct a past-the-end iterator.

.. cpp:namespace-pop::


Class ``dg::DG::OutEdgeRange``
--------------------------------------------------------------------------------------------------------------------------------

.. class:: dg::DG::OutEdgeRange
    

    A range of all out-edges of a vertex.


Synopsis
^^^^^^^^

.. code-block:: c++
    
    struct DG::OutEdgeRange {
        using iterator = OutEdgeIterator;
        using const_iterator = iterator;
    private:
        friend class Vertex;
        OutEdgeRange(std::shared_ptr<DG> g, std::size_t vId);
    public:
        OutEdgeIterator begin() const;
        OutEdgeIterator end() const;
    private:
        std::shared_ptr<DG> g;
        std::size_t vId;
    };

Class ``dg::DG::SourceIterator``
--------------------------------------------------------------------------------------------------------------------------------

.. class:: dg::DG::SourceIterator
    

    An iterator for enumerating all sources of a hyperedge.
    It models a forward iterator.


Synopsis
^^^^^^^^

.. code-block:: c++
    
    class MOD_DECL DG::SourceIterator
            : public boost::iterator_facade<SourceIterator, Vertex, std::forward_iterator_tag, Vertex> {
        friend class SourceRange;
        SourceIterator(std::shared_ptr<DG> g, std::size_t eId);
    public:
        SourceIterator();
    private:
        friend class boost::iterator_core_access;
        Vertex dereference() const;
        bool equal(const SourceIterator &iter) const;
        void increment();
    private:
        std::shared_ptr<DG> g;
        std::size_t eId, vId;
    };

Details
^^^^^^^

.. cpp:namespace-push:: dg::DG::SourceIterator

.. function:: SourceIterator()

    Construct a past-the-end iterator.

.. cpp:namespace-pop::


Class ``dg::DG::SourceRange``
--------------------------------------------------------------------------------------------------------------------------------

.. class:: dg::DG::SourceRange
    

    A range of all sources of a hyperedge.


Synopsis
^^^^^^^^

.. code-block:: c++
    
    struct DG::SourceRange {
        using iterator = SourceIterator;
        using const_iterator = iterator;
    private:
        friend class HyperEdge;
        SourceRange(std::shared_ptr<DG> g, std::size_t eId);
    public:
        SourceIterator begin() const;
        SourceIterator end() const;
    private:
        std::shared_ptr<DG> g;
        std::size_t eId;
    };

Class ``dg::DG::TargetIterator``
--------------------------------------------------------------------------------------------------------------------------------

.. class:: dg::DG::TargetIterator
    

    An iterator for enumerating all targets of a hyperedge.
    It models a forward iterator.


Synopsis
^^^^^^^^

.. code-block:: c++
    
    class MOD_DECL DG::TargetIterator
            : public boost::iterator_facade<TargetIterator, Vertex, std::forward_iterator_tag, Vertex> {
        friend class TargetRange;
        TargetIterator(std::shared_ptr<DG> g, std::size_t eId);
    public:
        TargetIterator();
    private:
        friend class boost::iterator_core_access;
        Vertex dereference() const;
        bool equal(const TargetIterator &iter) const;
        void increment();
    private:
        std::shared_ptr<DG> g;
        std::size_t eId, vId;
    };

Details
^^^^^^^

.. cpp:namespace-push:: dg::DG::TargetIterator

.. function:: TargetIterator()

    Construct a past-the-end iterator.

.. cpp:namespace-pop::


Class ``dg::DG::TargetRange``
--------------------------------------------------------------------------------------------------------------------------------

.. class:: dg::DG::TargetRange
    

    A range of all sources of a hyperedge.


Synopsis
^^^^^^^^

.. code-block:: c++
    
    struct DG::TargetRange {
        using iterator = TargetIterator;
        using const_iterator = iterator;
    private:
        friend class HyperEdge;
        TargetRange(std::shared_ptr<DG> g, std::size_t eId);
    public:
        TargetIterator begin() const;
        TargetIterator end() const;
    private:
        std::shared_ptr<DG> g;
        std::size_t eId;
    };

Class ``dg::DG::RuleIterator``
--------------------------------------------------------------------------------------------------------------------------------

.. class:: dg::DG::RuleIterator
    

    An iterator for enumerating all rules of a hyperedge.
    It models a forward iterator.


Synopsis
^^^^^^^^

.. code-block:: c++
    
    class MOD_DECL DG::RuleIterator
            : public boost::iterator_facade<RuleIterator, std::shared_ptr<rule::Rule>, std::forward_iterator_tag, std::shared_ptr<rule::Rule> > {
        friend class RuleRange;
        RuleIterator(HyperEdge e);
    public:
        RuleIterator();
    private:
        friend class boost::iterator_core_access;
        std::shared_ptr<rule::Rule> dereference() const;
        bool equal(const RuleIterator &iter) const;
        void increment();
    private:
        HyperEdge e;
        std::size_t i;
    };

Details
^^^^^^^

.. cpp:namespace-push:: dg::DG::RuleIterator

.. function:: RuleIterator()

    Construct a past-the-end iterator.

.. cpp:namespace-pop::


Class ``dg::DG::RuleRange``
--------------------------------------------------------------------------------------------------------------------------------

.. class:: dg::DG::RuleRange
    

    A range of all rules of a hyperedge.


Synopsis
^^^^^^^^

.. code-block:: c++
    
    struct MOD_DECL DG::RuleRange {
        using iterator = RuleIterator;
        using const_iterator = iterator;
    private:
        friend class HyperEdge;
        RuleRange(HyperEdge e);
    public:
        RuleIterator begin() const;
        RuleIterator end() const;
        std::size_t size() const;
    private:
        HyperEdge e;
    };