UN_Node.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_Node.h ( UN Library, C++)
 *
 * COMMENTS:
 *      
 */

#ifndef __UN_Node_h__
#define __UN_Node_h__

#include "UN_API.h"
#include "UN_Include.h"
#include "UN_GraphData.h"
#include "UN_Handle.h"
#include "UN_Iterator.h"
#include "UN_NodeUtils.h"
#include "UN_Parm.h"
#include "UN_Port.h"
#include "UN_StickyNote.h"
#include "UN_Wire.h"

#include <utility>

class UN_Graph;


// ============================================================================
/// Base class template for the UN node handle.
/// Its main purpose is to factor common code for const and non-const handles.
template <typename BASE_CLASS,  // class to derive from
          typename GRAPH_DATA,  // UN_GraphData or const UN_GraphData
          typename NODE,        // Node handle class (UN_Node or UN_ConstNode)
          typename PARM,        // Parm handle class (UN_Parm or UN_ConstParm)
          typename PORT,        // Port handle class (UN_Port or UN_ConstPort)
          typename STICKY_NOTE, // Sticky note handle class (UN_StickyNote..)
          typename WIRE>        // Wire handle class (UN_Wire or UN_ConstWire)
class UN_NodeBase : public BASE_CLASS
{
protected:
    /// Constructs a handle for an invalid node.
    UN_NodeBase() = default;

    /// Constructs a handle that references the given node in the given graph.
    UN_NodeBase( GRAPH_DATA *graph_data, UN_NodeID node_id )
        : BASE_CLASS( graph_data, node_id ) 
        {}

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

    /// Returns the unique ID of the node this handle refers to.
    UN_NodeID               nodeID() const
                                { return UN_NodeID( BASE_CLASS::dataID() ); }

    /// @{ Returns true if this node is valid within the graph; false otherwise.
    bool                    isValid() const
                                { return UN_NodeUtils::isValid( 
                                        graphData(), nodeID()); 
                                }

    explicit operator       bool() const
                                { return isValid(); }
    /// @}
   

    /// Returns the parent of this node.
    /// Note, for top-level nodes, this will return a graph's root node.
    NODE  parent() const
    { 
        return graphData()
            ? NODE( graphData(), graphData()->parent( nodeID() ))
            : NODE();
    }

    /// Returns a non-root parent node ID of the given child node.
    /// Note, for top-level nodes, this will return an invalid node ID, 
    /// because their parent is the implicitly created graph's root node.
    NODE nonRootParent() const
    { 
        return graphData()
            ? NODE( graphData(), graphData()->nonRootParent( nodeID() ))
            : NODE();
    }

    
    /// Returns the node name that differentiates it among its siblings. 
    const UT_StringHolder & name() const
    { 
        return UN_NodeUtils::name( graphData(), nodeID() );
    }

    /// Returns the node's type that determines its functional behavour.
    const UT_StringHolder & typeName() const
    { 
        return UN_NodeUtils::typeName( graphData(), nodeID() );
    }

    /// Returns the node's category that groups it with other nodes 
    /// that are operationally compatible (and connectable).
    const UT_StringHolder & categoryName() const
    { 
        return UN_NodeUtils::categoryName( graphData(), nodeID() );
    }

    /// Returns the signature for the node.
    const UT_StringHolder & signatureName() const
    {
        return UN_NodeUtils::signatureName( graphData(), nodeID() );
    }

    /// Returns the node path.
    UT_StringHolder path() const
    {
        return UN_NodeUtils::path( graphData(), nodeID() );
    }

    /// Returns the comment for the node.
    const UT_StringHolder & comment() const
    {
        return UN_NodeUtils::comment( graphData(), nodeID() );
    }

    /// Returns the node's position in the node editor.
    const UT_Vector2D & position() const
    { 
        return UN_NodeUtils::position( graphData(), nodeID() );
    }

    /// Returns the node's color.
    const UT_Color & color() const
    { 
        return UN_NodeUtils::color( graphData(), nodeID() );
    }

    /// Returns the node's tags.
    const UT_StringArray & tags() const
    { 
        return UN_NodeUtils::tags( graphData(), nodeID() );
    }

    /// Returns the node's metadata.
    const UN_MetadataHolder & metadata() const
    { 
        return UN_NodeUtils::metadata( graphData(), nodeID() );
    }


    /// Returns the names of the node parameters.
    UT_Array<UT_StringHolder> parmNames() const
    { 
        return UN_NodeUtils::parmNames( graphData(), nodeID() );
    }

    /// Returns the type names of the node parameters.
    UT_Array<UT_StringHolder> parmTypeNames() const
    { 
        return UN_NodeUtils::parmTypeNames( graphData(), nodeID() );
    }

    /// Returns a parameter by the given name, or an invalid parm if not found.
    PARM findParm( const UT_StringRef &parm_name ) const
    { 
        return PARM( graphData(), 
                UN_NodeUtils::findParm( graphData(), nodeID(), parm_name ));
    }

    /// An iterator and a range for parameters that belong to this node.
    using ParmIterator = UN_HandleIterator< 
            PARM, GRAPH_DATA, UN_NodeUtils::ParmIterator >;
    using ParmRange = UT_IteratorRange< ParmIterator >;

    /// Returns a range for iterating over node parameters.
    ParmRange parmRange() const
    {
        auto parm_range = UN_NodeUtils::parmRange( graphData(), nodeID() );
        return ParmRange( 
                ParmIterator( graphData(), parm_range.begin() ),
                ParmIterator( graphData(), parm_range.end() ));
    }

    /// Returns the parameters of this node.
    UT_Array<PARM> parms() const
    {
        return UNhandleArray<PARM>( graphData(), 
                UN_NodeUtils::parms( graphData(), nodeID() ));
    }


    /// Returns the names of the node ports of a given kind
    UT_Array<UT_StringHolder> portNames( UN_PortKind port_kind ) const
    { 
        return UN_NodeUtils::portNames( graphData(), nodeID(), port_kind );
    }

    /// Returns the type names of the node ports of a given kind
    UT_Array<UT_StringHolder> portTypeNames( UN_PortKind port_kind ) const
    { 
        return UN_NodeUtils::portTypeNames( graphData(), nodeID(), port_kind );
    }


    /// Returns this node's port by the given name, 
    /// or an invalid port handle, if no such port was found,
    PORT findPort( UN_PortKind port_kind,
            const UT_StringRef &port_name ) const
    { 
        return PORT( graphData(), 
                UN_NodeUtils::findPort( graphData(), nodeID(), 
                    port_kind, port_name ));
    }

    /// And iterator and a range for ports that belong to this node.
    using PortIterator = UN_HandleIterator< 
            PORT, GRAPH_DATA, UN_NodeUtils::PortIterator >;
    using PortRange = UT_IteratorRange< PortIterator >;

    /// Returns a range for iterating over this node's ports of the given kind, 
    /// forward from first to last.
    PortRange portRange( UN_PortKind port_kind ) const
    {
        auto port_range = 
            UN_NodeUtils::portRange( graphData(), nodeID(), port_kind );
        return PortRange( 
                PortIterator( graphData(), port_range.begin() ),
                PortIterator( graphData(), port_range.end() ));
    }

    /// And iterator and a range for ports that belong to this node.
    using PortReverseIterator = UN_HandleIterator< 
            PORT, GRAPH_DATA, UN_NodeUtils::PortReverseIterator >;
    using PortReverseRange = UT_IteratorRange< PortReverseIterator >;

    /// Returns a range for iterating over this node's ports of the given kind,
    /// backward from last to first.
    PortReverseRange portReverseRange( UN_PortKind port_kind ) const
    {
        auto port_range = 
            UN_NodeUtils::portReverseRange(graphData(), nodeID(), port_kind );
        return PortReverseRange( 
                PortReverseIterator( graphData(), port_range.begin() ),
                PortReverseIterator( graphData(), port_range.end() ));
    }

    /// Returns this node's ports of the given kind.
    UT_Array<PORT> ports( UN_PortKind port_kind ) const
    {
        return UNhandleArray<PORT>( graphData(), 
                UN_NodeUtils::ports( graphData(), nodeID(), port_kind ));
    }


    /// Returns true if any of the node's input ports has a connected source
    /// wire (feeding data from a source port).
    bool isAnyInputPortConnectedToSrc() const
    {
        return UN_NodeUtils::isAnyInputPortConnectedToSrc(
                graphData(), nodeID() );
    }

    /// Returns the names of the node input ports.
    UT_Array<UT_StringHolder> inputPortNames() const
    { 
        return portNames( UN_PortKind::Input ); 
    }

    /// Returns the type names of the node input ports.
    UT_Array<UT_StringHolder> inputPortTypeNames() const
    { 
        return portTypeNames( UN_PortKind::Input ); 
    }

    /// Returns this node's input port by the given name, 
    /// or an invalid port handle, if no such input was found,
    PORT findInputPort( const UT_StringRef &port_name ) const
    { 
        return findPort( UN_PortKind::Input, port_name ); 
    }

    /// Returns a range for iterating over node input ports,
    /// forward from first to last.
    PortRange inputPortRange() const
    {
        return portRange( UN_PortKind::Input ); 
    }

    /// Returns a range for iterating over node input ports,
    /// backwards from last to first.
    PortReverseRange inputPortReverseRange() const
    { 
        return portReverseRange( UN_PortKind::Input ); 
    }

    /// Returns this node's input ports of the given kind.
    UT_Array<PORT> inputPorts() const
    { 
        return ports( UN_PortKind::Input ); 
    }


    /// Returns true if any of the node's output ports has a connected
    /// destination wire feeding data to a destination port. 
    bool isAnyOutputPortConnectedToDst() const
    {
        return UN_NodeUtils::isAnyOutputPortConnectedToDst(
                graphData(), nodeID() );
    }

    /// Returns the names of the node output ports.
    UT_Array<UT_StringHolder> outputPortNames() const
    {
        return portNames( UN_PortKind::Output ); 
    }

    /// Returns the type names of the node output ports.
    UT_Array<UT_StringHolder> outputPortTypeNames() const
    { 
        return portTypeNames( UN_PortKind::Output ); 
    }

    /// Returns this node's output port by the given name, 
    /// or an invalid port handle, if no such output was found,
    PORT findOutputPort( const UT_StringRef &port_name ) const
    { 
        return findPort(UN_PortKind::Output, port_name); 
    }
    
    /// Returns a range for iterating over this node's output ports,
    /// forward from first to last.
    PortRange outputPortRange() const
    { 
        return portRange( UN_PortKind::Output ); 
    }

    /// Returns a range for iterating over this node's output ports,
    /// backwards from last to first.
    PortReverseRange outputPortReverseRange() const
    { 
        return portReverseRange( UN_PortKind::Output ); 
    }

    /// Returns this node's output ports of the given kind.
    UT_Array<PORT> outputPorts() const
    { 
        return ports( UN_PortKind::Output ); 
    }


    /// Returns a node name that is not taken by any of this nodes' children.
    UT_StringHolder findValidUniqueChildNodeName( 
                                const UT_StringRef &child_name ) const
    {
        return UN_NodeUtils::findValidUniqueChildNodeName( 
                graphData(), nodeID(), child_name );
    }

    /// Returns true if the node can have child nodes inside.
    bool isSubnet() const
    {
        return UN_NodeUtils::isSubnet( graphData(), nodeID() );
    }

    /// Returns the names of the node children nodes.
    UT_Array<UT_StringHolder> childNodeNames() const
    {
        return UN_NodeUtils::childNodeNames( graphData(), nodeID() );
    }
    
    /// Returns the child node by the given name, 
    /// or an invalid handle if no such child node was found.
    NODE findChildNode( const UT_StringRef &child_name ) const
    {
        return NODE( graphData(), 
                UN_NodeUtils::findChildNode( graphData(), nodeID(), 
                    child_name ));
    }

    /// Returns a node at the given path, or an invalid handle if not found.
    /// 
    /// @parm node_path - The node path identifying the node to find.
    ///     This can be either an absolute path (starting with a slash, '/')
    ///     or a relative path.  When the path is relative, this node 
    ///     is used as an anchor from which the relative path is followed 
    ///     to find the desired node. 
    ///     In particular, when the node path is just a name, this function 
    ///     will look for a child by that name directly inside this parent.
    ///     The path can contain '.' for the current node, and '..' for parent.
    NODE findNode( const UT_StringRef &node_path ) const
    {
        return NODE( graphData(), 
                UN_NodeUtils::findNode( graphData(), nodeID(), 
                    node_path ));
    }


    /// An iterator and a range for the children of this parent node.
    using ChildNodeIterator = UN_HandleIterator<
            NODE, GRAPH_DATA, UN_NodeUtils::ChildNodeIterator >;
    using ChildNodeRange = UT_IteratorRange< ChildNodeIterator >;

    /// Returns a range for iterating over node's immediate children.
    ChildNodeRange childNodeRange() const
    {
        auto node_range = UN_NodeUtils::childNodeRange( graphData(), nodeID() );

        return ChildNodeRange(
                ChildNodeIterator( graphData(), node_range.begin() ),
                ChildNodeIterator( graphData(), node_range.end() ));
    }


    /// Returns the children nodes directly inside this node.
    UT_Array<NODE> childNodes() const
    {
        return UNhandleArray<NODE>( graphData(), 
                UN_NodeUtils::childNodes( graphData(), nodeID() ));
    }
    

    /// An iterator and a range for traversing the descendant nodes
    /// of this (ancestor) node.
    using DescendantNodeIterator = UN_HandleIterator<
            NODE, GRAPH_DATA, UN_NodeUtils::DescendantNodeIterator >;
    using DescendantNodeRange = UT_IteratorRange< DescendantNodeIterator >;

    /// Returns a range for iterating over the descendant nodes 
    /// of this (ancestor) node.
    DescendantNodeRange descendantNodeRange() const
    {
        auto node_range = 
            UN_NodeUtils::descendantNodeRange( graphData(), nodeID() );
        return DescendantNodeRange( 
                DescendantNodeIterator( graphData(), node_range.begin() ),
                DescendantNodeIterator( graphData(), node_range.end() ));
    }


    /// An iterator and a range for the connection wires between immediate
    /// children inside this node.
    /// (And also direct wires between inputs and outputs on this node).
    using ChildWireIterator = UN_HandleIterator< 
            WIRE, GRAPH_DATA, UN_NodeUtils::ChildWireIterator >;
    using ChildWireRange = UT_IteratorRange< ChildWireIterator >;

    /// Returns a range for iterating over the connection wires between
    /// this node's immediate children, directly inside the this node.
    /// (And also direct wires between inputs and outputs on this node).
    ChildWireRange childWireRange() const
    {
        auto wire_range = UN_NodeUtils::childWireRange( graphData(), nodeID() );

        return ChildWireRange( 
                ChildWireIterator( graphData(), wire_range.begin() ),
                ChildWireIterator( graphData(), wire_range.end() ));
    }

    /// Returns the wires connecting child nodes directly inside this node
    /// (And also direct wires between inputs and outputs on this node).
    UT_Array<WIRE> childWires() const
    {
        return UNhandleArray<WIRE>( graphData(), 
                UN_NodeUtils::childWires( graphData(), nodeID() ));
    }


    /// An iterator and a range for the connection wires between 
    /// the descendants (children, grandchildren, etc) inside this node.
    /// (And also direct wires between inputs and outputs on this node).
    using DescendantWireIterator = UN_HandleIterator< 
            WIRE, GRAPH_DATA, UN_NodeUtils::DescendantWireIterator >;
    using DescendantWireRange = UT_IteratorRange< DescendantWireIterator >;

    /// Returns a range for iterating over the connection wires between
    /// this node's descendants (ie, its children and grandchildren, etc).
    /// (And also direct wires between inputs and outputs on this node).
    DescendantWireRange descendantWireRange() const
    {
        auto wire_range = 
            UN_NodeUtils::descendantWireRange( graphData(), nodeID());
        return DescendantWireRange( 
                DescendantWireIterator( graphData(), wire_range.begin() ),
                DescendantWireIterator( graphData(), wire_range.end() ));
    }

    /// Returns the child sticky note by the given name, 
    /// or an invalid handle if no such child node was found.
    STICKY_NOTE findChildStickyNote( const UT_StringRef &child_name ) const
    {
        return STICKY_NOTE( graphData(), 
                UN_NodeUtils::findChildStickyNote( graphData(), nodeID(), 
                    child_name ));
    }

    /// Returns the child sticky notes directly inside this node.
    UT_Array<STICKY_NOTE> childStickyNotes() const
    {
        return UNhandleArray<STICKY_NOTE>( graphData(), 
                UN_NodeUtils::childStickyNotes( graphData(), nodeID() ));
    }

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


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

    /// Constructs a handle referencing the given node in the given graph.
    UN_Node( UN_GraphData *graph_data, UN_NodeID node_id )
        : UN_NodeBase( graph_data, node_id ) 
    {}


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


    /// Returns the graph within which this node exists.
    UN_Graph graph() const;


    /// Sets the node  name that differentiates it among its siblings. 
    void setName( const UT_StringRef &name ) const
    { 
        UN_NodeUtils::setName( graphData(), nodeID(), name );
    }

    /// Sets the node's type that determines its functional behavour.
    void setTypeName( const UT_StringRef &type_name ) const
    { 
        UN_NodeUtils::setTypeName( graphData(), nodeID(), type_name );
    }

    /// Sets the signature on the node.
    void setSignature( const UT_StringRef &signature_name ) const
    {
        UN_NodeUtils::setSignature( graphData(), nodeID(), signature_name );
    }

    /// Sets the comment on the node. The comment can show up in network editor.
    void setComment( const UT_StringRef &comment ) const
    {
        UN_NodeUtils::setComment( graphData(), nodeID(), comment );
    }

    /// Sets the node's location. Used for the node position in network editor.
    void setPosition( const UT_Vector2D &position ) const
    { 
        UN_NodeUtils::setPosition( graphData(), nodeID(), position );
    }

    /// Sets the node's color. The color is used in network editor.
    void setColor( const UT_Color &color ) const
    { 
        UN_NodeUtils::setColor( graphData(), nodeID(), color );
    }

    /// Sets the tags for the node (copy-assignment).
    void setTags( const UT_StringArray &tags ) const
    { 
        UN_NodeUtils::setTags( graphData(), nodeID(), tags );
    }

    /// Sets the tags for the node (move-assignment).
    void setTags( UT_StringArray &&tags ) const
    { 
        UN_NodeUtils::setTags( graphData(), nodeID(), std::move(tags) );
    }

    /// Returns the tags moved out of the node.
    /// This is useful in combination with rvalue ref version of setTags()
    /// to optimize the edits to the tag list.
    UT_StringArray stealTags() const
    { 
        return UN_NodeUtils::stealTags( graphData(), nodeID() );
    }

    /// Sets tags in-place, which is faster than setting the whole dictionary. 
    /// Intended usage: 
    ///   n.updateTags([&value](auto &t) { t.set("key", value)  });
    template <typename OP>
    void updateTags( const OP &op ) const
    { 
        UN_NodeUtils::updateTags( graphData(), nodeID(), op );
    }


    /// Sets the metadata for the node (copy-assignment).
    void setMetadata( const UN_MetadataHolder &metadata ) const
    {
        UN_NodeUtils::setMetadata( graphData(), nodeID(), metadata );
    }

    /// Sets the metadata for the node (move-assignment).
    void setMetadata( UN_MetadataHolder &&metadata ) const
    {
        UN_NodeUtils::setMetadata( graphData(), nodeID(), std::move(metadata) );
    }

    /// Returns the metadata moved out of the node.
    UN_MetadataHolder stealMetadata() const
    { 
        return UN_NodeUtils::stealMetadata( graphData(), nodeID() );
    }

    /// Sets metadata in-place, which is faster than setting whole dictionary. 
    /// Intended usage: 
    ///   n.updateTags([&value](auto &m) { m.set("key", value)  });
    template <typename OP>
    void updateMetadata( const OP &op ) const
    { 
        UN_NodeUtils::updateMetadata( graphData(), nodeID(), op );
    }

    /// Simpler method to update a single metadata value in-place.
    void updateMetadata( const UT_StringHolder &key,
        UT_OptionEntryPtr &&value )
    {
        UN_NodeUtils::updateMetadata(
            graphData(), nodeID(), key, std::move(value) );
    }

    /// Deletes this node from the graph.
    void destroy() const
    { 
        UN_NodeUtils::deleteNode( graphData(), nodeID() );
    }


    /// Adds and returns a new parameter to this node.
    /// If another parameter of a given name already exists, returns an
    /// invalid parameter, indicating a failure because of the name collision.
    UN_Parm createParm( const UT_StringRef &parm_name,
            const UT_StringRef &parm_type_name =
                    UN_UNDEFINED_PARM_TYPE_NAME.asRef()) const
    { 
        return UN_Parm( graphData(), 
                UN_NodeUtils::createParm( graphData(), nodeID(), 
                    parm_name, parm_type_name ));
    }


    /// Adds a new port to this node and returns it.
    /// If another port of a given kind and name already exists, returns an
    /// invalid port, indicating a failure because of the name collision.
    UN_Port createPort( UN_PortKind port_kind,
            const UT_StringRef &port_name = UT_StringRef(),
            const UT_StringRef &port_type_name =
                UN_UNDEFINED_PORT_TYPE_NAME.asRef(),
            const UT_StringRef &port_label = UT_StringRef(),
            const UT_Optional<exint> &index = std::nullopt ) const
    { 
        return UN_Port( graphData(), 
                UN_NodeUtils::createPort( graphData(), nodeID(),
                    port_kind, port_name, port_type_name, port_label,
                    index ));
    }

    /// Returns an existing port by the given name, or creates one 
    /// (with the given type and label) if not found.
    UN_Port findOrCreatePort( UN_PortKind port_kind,
            const UT_StringRef &port_name,
            const UT_StringRef &port_type_name =
                UN_UNDEFINED_PORT_TYPE_NAME.asRef(),
            const UT_StringRef &port_label = UT_StringRef() ) const
    { 
        return UN_Port( graphData(), 
                UN_NodeUtils::findOrCreatePort( graphData(), nodeID(),
                    port_kind, port_name, port_type_name, port_label ));
    }


    /// Adds and returns a new input port to this node.
    /// If another input port of a given name already exists, returns an
    /// invalid port, indicating a failure because of the name collision.
    UN_Port createInputPort( 
            const UT_StringRef &port_name = UT_StringRef(),
            const UT_StringRef &port_type_name =
                UN_UNDEFINED_PORT_TYPE_NAME.asRef(),
            const UT_StringRef &port_label = UT_StringRef(),
            const UT_Optional<exint> &index = std::nullopt ) const
    { 
        return createPort( UN_PortKind::Input, 
                port_name, port_type_name, port_label, index ); 
    }

    /// Returns an existing input port by the given name, or creates one 
    /// (with the given type and label) if not found.
    UN_Port findOrCreateInputPort( 
            const UT_StringRef &port_name, 
            const UT_StringRef &port_type_name =
                UN_UNDEFINED_PORT_TYPE_NAME.asRef(),
            const UT_StringRef &port_label = UT_StringRef() ) const
    { 
        return findOrCreatePort( UN_PortKind::Input, 
                port_name, port_type_name, port_label ); 
    }


    /// Adds and returns a new output port to this node.
    /// If another outupt port of a given name already exists, returns an
    /// invalid port, indicating a failure because of the name collision.
    UN_Port createOutputPort( 
            const UT_StringRef &port_name = UT_StringRef(),
            const UT_StringRef &port_type_name =
                UN_UNDEFINED_PORT_TYPE_NAME.asRef(),
            const UT_StringRef &port_label = UT_StringRef(),
            const UT_Optional<exint> &index = std::nullopt ) const
    { 
        return createPort( UN_PortKind::Output,
                port_name, port_type_name, port_label, index ); 
    }

    /// Returns an existing output port by the given name, or creates one 
    /// (with the given type and label) if not found.
    UN_Port findOrCreateOutputPort( 
            const UT_StringRef &port_name, 
            const UT_StringRef &port_type_name =
                UN_UNDEFINED_PORT_TYPE_NAME.asRef(),
            const UT_StringRef &port_label = UT_StringRef() ) const
    { 
        return findOrCreatePort( UN_PortKind::Output, 
                port_name, port_type_name, port_label ); 
    }


    /// Creates and returns a new node that is a child of this node.
    UN_Node createChildNode( 
            const UT_StringRef &child_name = UT_StringRef(),
            const UT_StringRef &child_type = UT_StringRef(),
            const UT_StringRef &child_category = UT_StringRef()) const
    {
        return UN_Node( graphData(), 
                UN_NodeUtils::createChildNode( graphData(), nodeID(),
                    child_name, child_type, child_category ));
    }

    /// Deletes the child node from the graph (removing it from this network).
    void deleteChildNode( const UT_StringRef &child_name ) const
    {
        UN_NodeUtils::deleteChildNode( graphData(), nodeID(), child_name );
    }

    /// Creates and returns a new sticky note that is a child of this node.
    UN_StickyNote createChildStickyNote( 
            const UT_StringRef &note_name = UT_StringRef(),
            const UT_StringRef &note_text = UT_StringRef()) const
    {
        return UN_StickyNote( graphData(), 
                UN_NodeUtils::createChildStickyNote(graphData(), nodeID(),
                    note_name, note_text ));
    }

    /// Deletes the child sticky note from the graph 
    /// (removing it from this network).
    void deleteChildStickyNote( const UT_StringRef &sticky_note_name ) const
    {
        UN_NodeUtils::deleteChildStickyNote( graphData(), nodeID(), 
                sticky_note_name );
    }

    /// Configure the node based on the given options.
    void setFromOptions( const UN_Options &node_opts ) const
    {
        UN_NodeUtils::setFromOptions( graphData(), nodeID(), node_opts );
    }
};


// ============================================================================
/// A handle that references a const node in a graph.
/// It abstracts the APIs that operate on this node's data stored inside 
/// graph's data containers.
/// It is a constant handle, so allows only queries of the node's data,
/// and does not allow setting any new values for.
class UN_API UN_ConstNode : public UN_NodeBase< UN_ConstHandle,
    const UN_GraphData, UN_ConstNode, UN_ConstParm, UN_ConstPort, 
    UN_ConstStickyNote, UN_ConstWire >
{
public:
    /// Constructs a handle for an invalid node.
    UN_ConstNode() = default;

    /// Constructs a handle referencing the given node in the given graph.
    UN_ConstNode( const UN_GraphData *graph_data, UN_NodeID node_id )
        : UN_NodeBase( graph_data, node_id ) 
    {}

    /// Constructs a const handle from a mutable node handle.
    UN_ConstNode( const UN_Node &node )
        : UN_ConstNode( node.constGraphData(), node.nodeID() ) 
    {}


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


    /// Returns the graph within which this node exists.
    UN_ConstGraph graph() const;
};

// ============================================================================
// Free functions to compare a non-const node handle to a const node 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_Node &a,  const UN_ConstNode &b )
{
    return b == UN_ConstNode(a);
}

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

// ============================================================================


#endif