UN_Graph.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        UN_Graph.h ( UN Library, C++)
 *
 * COMMENTS:
 *      
 */

#ifndef __UN_Graph_h__
#define __UN_Graph_h__

#include "UN_API.h"
#include "UN_GraphUtils.h"
#include "UN_Node.h"
#include "UN_StickyNote.h"
#include "UN_Wire.h"

class UN_GraphData;

// ============================================================================
/// Base class template for the UN graph handle.
/// Its main purpose is to factor common code for const and non-const handles.
template <typename GRAPH_DATA,  // UN_GraphData or const UN_GraphData
          typename NODE,        // Node handle class (UN_Node or UN_ConstNode)
          typename WIRE,        // Wire handle class (UN_Wire or UN_ConstWire)
          typename STICKY_NOTE> // Sticky note handle (UN_StickyNote or const)
class UN_GraphBase 
{
protected:
    /// Constructs a handle for an invalid wire.
    UN_GraphBase() = default;

    /// Constructs a handle that references the given wire in the given graph.
    UN_GraphBase( GRAPH_DATA *graph_data )
        : myGraphData( graph_data )
        {}

public:
    /// @{ Returns the owner container of the underlying graph data structures.
    GRAPH_DATA *            graphData() const
                                { return myGraphData; }
    const UN_GraphData *    constGraphData() const
                                { return myGraphData; }
    /// @}

    /// @{ Returns true if this is a valid graph; false otherwise.
    bool                    isValid() const
                                { return myGraphData; }
    explicit operator       bool() const
                                { return isValid(); }
    /// @}

    /// Returns the root node of the graph's node parental hierarchy.
    /// The root is a special node that is a parent to graph's top-level nodes.
    NODE rootNode() const
    {
        return NODE( myGraphData, UN_GraphUtils::rootNode( myGraphData ));
    }

    /// Returns true if the graph accepts the given name as a legal node name.
    /// Note, even though the name is legal, it still may not be unique.
    bool isValidNodeName( const UT_StringRef &name ) const
    {
        return UN_GraphUtils::isValidNodeName( myGraphData, name );
    }

    /// Based on the given name, returns a valid name that is not used 
    /// by any of the top level nodes.
    UT_StringHolder findValidUniqueNodeName(
            const UT_StringRef &name = UT_StringRef() ) const
    {
        return UN_GraphUtils::findValidUniqueNodeName( myGraphData, name );
    }

    /// Returns the names of the graph's top-level nodes.
    UT_Array<UT_StringHolder> nodeNames() const
    {
        return UN_GraphUtils::nodeNames( myGraphData );
    }


    /// Returns a node at the given path, or an invalid handle if not found.
    /// If the path is just a name, it looks for the top-level node,
    /// otherwise if the path contains slashes '/', it looks for
    /// nested nodes inside subnets.
    NODE findNode( const UT_StringRef &node_path ) const
    {
        return NODE( graphData(), 
                UN_GraphUtils::findNode( myGraphData, node_path ));
    }

    /// Returns a sticky note at the given path, or an invalid handle 
    /// if not found.
    /// If the path is just a name, it looks for the top-level sticky note,
    /// otherwise if the path contains slashes '/', it looks for
    /// sticky notes nested inside subnets.
    STICKY_NOTE findStickyNote( const UT_StringRef &sticky_note_path ) const
    {
        return STICKY_NOTE( graphData(), 
                UN_GraphUtils::findStickyNote( myGraphData, sticky_note_path ));
    }
    
    /// Iterarates over the top-level nodes of the graph.
    using TopNodeIterator = typename NODE::ChildNodeIterator;
    using TopNodeRange = UT_IteratorRange< TopNodeIterator >;

    /// Returns a range for iterating over graph's top-level nodes.
    TopNodeRange topNodeRange() const
    {
        return rootNode().childNodeRange();
    }

    /// Returns the top level nodes directly inside this graph.
    UT_Array<NODE> topNodes() const
    {
        return UNhandleArray<NODE>( graphData(), 
                UN_GraphUtils::topNodes( graphData() ));
    }

    /// Iterarates over all the nodes in the graph,
    /// both the top-level nodes and their descendants too.
    using AllNodeIterator = typename NODE::DescendantNodeIterator;
    using AllNodeRange = UT_IteratorRange< AllNodeIterator >;

    /// Returns a range for iterating over all of the graph's nodes,
    /// both top-level as well as deeply nested ones.
    AllNodeRange allNodeRange() const
    {
        return rootNode().descendantNodeRange();
    }


    /// An iterator and a range for the top-level wires inside this graph.
    using TopWireIterator = typename NODE::ChildWireIterator;
    using TopWireRange = UT_IteratorRange< TopWireIterator >;

    /// Returns a range for iterating over graph's top-level connection wires.
    TopWireRange topWireRange() const
    {
        return rootNode().childWireRange();
    }

    /// Returns the wires connecting top level nodes directly inside this graph.
    UT_Array<WIRE> topWires() const
    {
        return UNhandleArray<WIRE>( graphData(), 
                UN_GraphUtils::topWires( graphData() ));
    }


    /// An iterator and a range for all the connection wires in this graph.
    using AllWireIterator = typename NODE::DescendantWireIterator;
    using AllWireRange = UT_IteratorRange< AllWireIterator >;

    /// Returns a range for iterating over all the graph's connection wires,
    /// both top-level as well as deeply nested ones.
    AllWireRange allWireRange() const
    {
        return rootNode().descendantWireRange();
    }


    /// Returns the options object representing this graph.
    /// This can be then used for serialization to JSON, etc.
    UN_OptionsPtr asOptions() const
    {
        return UN_GraphUtils::asOptions( graphData() );
    }

protected:
    /// @{ Comparison operators.
    bool                operator==( const UN_GraphBase &other ) const
                            { return myGraphData == other.myGraphData; }
    bool                operator!=( const UN_GraphBase &other ) const
                            { return !( *this == other ); }
    /// @}


private:
    /// Graph data object containing the details about the graph as a whole
    /// such as its nodes and connections between them.
    GRAPH_DATA *    myGraphData = nullptr;
};

// ============================================================================
/// A handle that references a non-const (mutable) graph.
/// It abstracts the APIs that operate on this graph's data, 
/// which is stored inside graph's data container.
/// It is a non-const (read-write) handle, so allows both queries 
/// and mutations of the graph's data.
class UN_API UN_Graph : public UN_GraphBase< UN_GraphData, 
    UN_Node, UN_Wire, UN_StickyNote >
{
public:
    /// Constructs a handle for an invalid graph.
    UN_Graph() = default;

    /// Constructor that creates handle for the given graph data.
    UN_Graph( UN_GraphData *graph_data )
        : UN_GraphBase( graph_data )
    {}

    /// @{ Comparison operators
    // Allows comparing graph handles, but guards against 
    // comparing graph to nodes, for example.
    bool                operator==( const UN_Graph &other ) const
                            { return UN_GraphBase::operator==( other ); }
    bool                operator!=( const UN_Graph &other ) const
                            { return UN_GraphBase::operator!=( other ); }
    /// @}


    /// Creates a node in the graph.
    UN_Node createNode( 
            const UT_StringRef &node_name_or_path = UT_StringRef(), 
            const UT_StringRef &node_type = UT_StringRef(),
            const UT_StringRef &node_category = UT_StringRef()) const
    {
        return UN_Node( graphData(), 
                UN_GraphUtils::createNode( graphData(), 
                    node_name_or_path, node_type, node_category ));
    }

    /// Removes and deletes the node from this graph.
    void deleteNode( const UT_StringRef &node_name_or_path ) const
    {
        UN_GraphUtils::deleteNode( graphData(), node_name_or_path );
    }


    /// Creates a sticky note in the graph.
    UN_StickyNote createStickyNote( 
            const UT_StringRef &sticky_note_name_or_path = UT_StringRef(), 
            const UT_StringRef &sticky_note_text = UT_StringRef()) const
    {
        return UN_StickyNote( graphData(), 
                UN_GraphUtils::createStickyNote( graphData(), 
                    sticky_note_name_or_path, sticky_note_text ));
    }

    /// Removes and deletes the sticky note from this graph.
    void deleteStickyNote( const UT_StringRef &sticky_note_name_or_path ) const
    {
        UN_GraphUtils::deleteStickyNote( graphData(), sticky_note_name_or_path);
    }

    /// Load and set the graph based on the given options.
    void setFromOptions( const UN_Options &graph_opts ) const
    {
        UN_GraphUtils::setFromOptions( graphData(), graph_opts );
    }
};


// ============================================================================
/// A handle that references a const graph.
/// It abstracts the APIs that operate on this graph's data.
/// It is a constant handle, so allows only queries of the graph's data,
/// and does not allow modifying it.
class UN_API UN_ConstGraph : public UN_GraphBase< const UN_GraphData, 
    UN_ConstNode, UN_ConstWire, UN_ConstStickyNote>
{
public:
    /// Constructs a handle for an invalid graph.
    UN_ConstGraph() = default;

    /// Constructor that creates handle for the given graph data.
    UN_ConstGraph( const UN_GraphData *graph_data )
        : UN_GraphBase( graph_data )
    {}

    /// Constructs a const handle from a mutable graph handle.
    UN_ConstGraph( const UN_Graph &graph )
        : UN_ConstGraph( graph.constGraphData() ) 
    {}

    /// @{ Comparison operators
    // Allows comparing graph handles, but guards against 
    // comparing graph to nodes, for example.
    bool                operator==( const UN_ConstGraph &other ) const
                            { return UN_GraphBase::operator==( other ); }
    bool                operator!=( const UN_ConstGraph &other ) const
                            { return UN_GraphBase::operator!=( other ); }
    /// @}
};

// ============================================================================
// Free functions to compare a non-const graph handle to a const graph handle.
// Note, the const to non-const comparison is covered by implicit conversion
// of non-const handle to const handle, and using const to const handle comp.
static inline bool
operator==( const UN_Graph &a,  const UN_ConstGraph &b )
{
    return b == UN_ConstGraph(a);
}

static inline bool
operator!=( const UN_Graph &a,  const UN_ConstGraph &b )
{
    return !(b == a);
}

// ============================================================================
#endif