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

#ifndef __UN_NodeUtils_h__
#define __UN_NodeUtils_h__


#include "UN_API.h"
#include "UN_GraphData.h"


namespace UN_NodeUtils
{
    /// Returns true if the node by the given ID is valid in the given graph.
    static inline bool
    isValid( const UN_GraphData *graph_data, UN_NodeID node_id )
    {
        return graph_data && graph_data->isValid( node_id );
    }

    /// Deletes the given node from the given graph.
    static inline void
    deleteNode( UN_GraphData *graph_data, UN_NodeID node_id )
    {
        if( isValid( graph_data, node_id ))
            graph_data->deleteNode( node_id );
    }

    /// Sets the node  name that differentiates it among its siblings. 
    static inline void
    setName( UN_GraphData *graph_data, UN_NodeID node_id,
             const UT_StringRef &name ) 
    { 
        if( graph_data )
            graph_data->setNodeName( node_id, name );
    }

    /// Returns the node name that differentiates it among its siblings. 
    static inline const UT_StringHolder &
    name( const UN_GraphData *graph_data, UN_NodeID node_id )
    {
        return graph_data 
            ? graph_data->nodeData().name( node_id )
            : UT_StringHolder::theEmptyString;
    }

    /// Sets the node's type that determines its functional behavour.
    static inline void
    setTypeName( UN_GraphData *graph_data, UN_NodeID node_id,
            const UT_StringRef &type_name ) 
    {
        if( graph_data )
            graph_data->nodeData().setTypeName( node_id, type_name );
    }

    /// Returns the name of the node's type 
    /// that determines its functional behavour.
    static inline const UT_StringHolder &
    typeName( const UN_GraphData *graph_data, UN_NodeID node_id )
    { 
        return graph_data 
            ? graph_data->nodeData().typeName( node_id )
            : UT_StringHolder::theEmptyString;
    }

    /// Returns the node's category that groups it with other nodes
    /// that are operationally compatible (and connectable).
    static inline const UT_StringHolder &
    categoryName( const UN_GraphData *graph_data, UN_NodeID node_id )
    { 
        return graph_data 
            ? graph_data->nodeData().categoryName( node_id )
            : UT_StringHolder::theEmptyString;
    }

    /// Returns the node path.
    UN_API UT_StringHolder 
    path( const UN_GraphData *graph_data, UN_NodeID node_id );
    
    /// Sets the signature on the node.
    static inline void
    setSignature( UN_GraphData *graph_data, UN_NodeID node_id,
            const UT_StringRef &signature_name )
    {
        if( graph_data )
            graph_data->setNodeSignature( node_id, signature_name );
    }

    /// Returns the signature for the node.
    static inline const UT_StringHolder &
    signatureName( const UN_GraphData *graph_data, UN_NodeID node_id )
    {
        return graph_data
            ? graph_data->nodeData().signatureName( node_id )
            : UN_NodeData::theDefSignatureName;
    }

    /// Sets the comment on the node. The comment can show up in network editor.
    static inline void
    setComment( UN_GraphData *graph_data, UN_NodeID node_id,
            const UT_StringRef &comment )
    {
        if( graph_data )
            graph_data->nodeData().setComment( node_id, comment );
    }

    /// Returns the comment for the node.
    static inline const UT_StringHolder &
    comment( const UN_GraphData *graph_data, UN_NodeID node_id )
    {
        return graph_data
            ? graph_data->nodeData().comment( node_id )
            : UN_NodeData::theDefComment;
    }

    /// Sets the node's location. Used for the node position in network editor.
    static inline void
    setPosition( UN_GraphData *graph_data, UN_NodeID node_id,
            const UT_Vector2D &position )
    {
        if( graph_data )
            graph_data->nodeData().setPosition( node_id, position );
    }

    /// Returns the node's position in the node editor pane.
    static inline const UT_Vector2D &
    position( const UN_GraphData *graph_data, UN_NodeID node_id )
    { 
        return graph_data 
            ? graph_data->nodeData().position( node_id )
            : UN_NodeData::theDefPos;
    }

    /// Sets the node's color. The color is used in network editor.
    static inline void
    setColor( UN_GraphData *graph_data, UN_NodeID node_id,
            const UT_Color &color )
    {
        if( graph_data )
            graph_data->nodeData().setColor( node_id, color );
    }

    /// Returns the node's color.
    static inline const UT_Color &
    color( const UN_GraphData *graph_data, UN_NodeID node_id )
    { 
        return graph_data 
            ? graph_data->nodeData().color( node_id )
            : UN_NodeData::theDefColor;
    }

    /// Sets the tags for the node (copy-assignment).
    static inline void
    setTags( UN_GraphData *graph_data, UN_NodeID node_id, 
             const UT_StringArray &tags ) 
    {
        if( graph_data )
            graph_data->nodeData().setTags( node_id, tags );
    }

    /// Sets the tags for the node (move-assignment).
    static inline void
    setTags( UN_GraphData *graph_data, UN_NodeID node_id, 
             UT_StringArray &&tags ) 
    {
        if( graph_data )
            graph_data->nodeData().setTags( node_id, std::move(tags) );
    }

    /// Returns the tags moved out of the node data.
    static inline UT_StringArray
    stealTags( UN_GraphData *graph_data, UN_NodeID node_id )
    { 
        return graph_data 
            ? graph_data->nodeData().stealTags( node_id ) 
            : UT_StringArray();
    }

    /// Sets tags in-place, which is faster than setting the whole dictionary. 
    /// Intended usage: 
    ///   updateTags(g, n, [&value](auto &t) { t.set("key", value); });
    template <typename OP>
    static inline void
    updateTags( UN_GraphData *graph_data, UN_NodeID node_id, const OP &op  )
    {
        if( graph_data )
            graph_data->nodeData().updateTags( node_id, op );
    }

    /// Returns the node's tags.
    static inline const UT_StringArray &
    tags( const UN_GraphData *graph_data, UN_NodeID node_id )
    { 
        return graph_data 
            ? graph_data->nodeData().tags( node_id )
            : UN_NodeData::theDefTags;
    }

    /// Sets the metadata for the node (copy-assignment).
    static inline void
    setMetadata( UN_GraphData *graph_data, UN_NodeID node_id, 
             const UN_MetadataHolder &metadata ) 
    {
        if( graph_data )
            graph_data->nodeData().setMetadata( node_id, metadata );
    }

    /// Sets the metadata for the node (move-assignment).
    static inline void
    setMetadata( UN_GraphData *graph_data, UN_NodeID node_id, 
             UN_MetadataHolder &&metadata ) 
    {
        if( graph_data )
            graph_data->nodeData().setMetadata( node_id, std::move(metadata) );
    }

    /// Returns the metadata moved out of the node data.
    static inline UN_MetadataHolder
    stealMetadata( UN_GraphData *graph_data, UN_NodeID node_id )
    { 
        return graph_data 
            ? graph_data->nodeData().stealMetadata( node_id ) 
            : UN_MetadataHolder();
    }

    /// Sets metadata in-place, which is faster than setting whole dictionary. 
    /// Intended usage: 
    ///   updateMetadata(g, n, [&value](auto &m) { m->set("key", value)  });
    template <typename OP>
    static inline void
    updateMetadata( UN_GraphData *graph_data, UN_NodeID node_id, const OP &op  )
    {
        if( graph_data )
            graph_data->nodeData().updateMetadata( node_id, op );
    }

    /// Simpler method to update a single metadata value in-place.
    static inline void
    updateMetadata( UN_GraphData *graph_data,
        UN_NodeID node_id,
        const UT_StringHolder &key,
        UT_OptionEntryPtr &&value )
    {
        if( graph_data )
            graph_data->nodeData().updateMetadata(
                node_id, key, std::move(value) );
    }

    /// Returns the node's metadata.
    static inline const UN_MetadataHolder &
    metadata( const UN_GraphData *graph_data, UN_NodeID node_id )
    { 
        return graph_data 
            ? graph_data->nodeData().metadata( node_id )
            : UN_NodeData::theDefMetadata;
    }

    /// 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 due to the name collision.
    UN_API UN_ParmID
    createParm( UN_GraphData *graph_data, UN_NodeID node_id, 
            const UT_StringRef &parm_name,
            const UT_StringRef &parm_type_name =
                UN_UNDEFINED_PARM_TYPE_NAME.asRef());

    /// Returns the IDs of the given node's parameters.
    static inline const UN_ParmIDList &
    parms( const UN_GraphData *graph_data, UN_NodeID node_id )
    {
        static UN_ParmIDList theEmpty;
        return graph_data ? graph_data->parms( node_id ) : theEmpty;
    }

    // An iterator and a range for iterating over node parameter IDs.
    using ParmIterator = UN_ParmIDList::const_iterator;
    using ParmRange = UT_IteratorRange< ParmIterator >;

    /// Returns a range for traversing the parameters of the given node.
    /// NOTE, the iterators hold a reference to the underlying parm array, 
    ///     and therefore parms can't be added/removed during the iteration.
    ///     For adding/removing parms, use parms() function and make a copy.
    static inline ParmRange
    parmRange( const UN_GraphData *graph_data, UN_NodeID node_id )
    {
        const UN_ParmIDList &parm_ids = parms( graph_data, node_id );
        return ParmRange(
                ParmIterator( parm_ids.begin() ),
                ParmIterator( parm_ids.end() ));
    }

    /// Returns a parameter by the given name, or an invalid param if not found.
    static inline UN_ParmID
    findParm( const UN_GraphData *graph_data, UN_NodeID node_id,
            const UT_StringRef &parm_name )
    {
        return graph_data 
            ? graph_data->parm( node_id, parm_name )
            : UN_ParmID();
    }

    /// Returns the names of the node parameters.
    UN_API UT_Array< UT_StringHolder >
    parmNames( const UN_GraphData *graph_data, UN_NodeID node_id );

    /// Returns the type names of the node parameters.
    UN_API UT_Array< UT_StringHolder >
    parmTypeNames( const UN_GraphData *graph_data, UN_NodeID node_id );


    /// Adds a new port to this node and returns its ID.
    /// If another port of a given name already exists, returns an
    /// invalid port, indicating a failure due to the name collision.
    UN_API UN_PortID
    createPort( UN_GraphData *graph_data, UN_NodeID node_id, 
            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 UT_Optional<exint> &index = std::nullopt);

    /// Adds a new input port to this node and returns its ID.
    /// If another port of a given name already exists, returns an
    /// invalid port, indicating a failure due to the name collision.
    static inline UN_PortID
    createInputPort( UN_GraphData *graph_data, UN_NodeID node_id, 
            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 UT_Optional<exint> &index = std::nullopt)
    {
        return createPort( graph_data, node_id, UN_PortKind::Input,
            port_name, port_type_name, port_label, index );
    }

    /// Adds a new output port to this node and returns its ID.
    /// If another port of a given name already exists, returns an
    /// invalid port, indicating a failure due to the name collision.
    static inline UN_PortID
    createOutputPort( UN_GraphData *graph_data, UN_NodeID node_id, 
            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 UT_Optional<exint> &index = std::nullopt)
    {
        return createPort( graph_data, node_id, UN_PortKind::Output,
            port_name, port_type_name, port_label, index );
    }


    /// Returns a node port by the given name, or an invalid ID if not found.
    static inline UN_PortID
    findPort( const UN_GraphData *graph_data, UN_NodeID node_id,
            UN_PortKind port_kind, const UT_StringRef &port_name )
    {
        return graph_data 
            ? graph_data->port( node_id, port_kind, port_name )
            : UN_PortID();
    }

    /// Returns an input port by the given name, or invalid ID if not found.
    static inline UN_PortID
    findInputPort( const UN_GraphData *graph_data, UN_NodeID node_id,
            const UT_StringRef &port_name )
    {
        return findPort( graph_data, node_id, UN_PortKind::Input, port_name );
    }

    /// Returns an output port by the given name, or invalid ID if not found.
    static inline UN_PortID
    findOutputPort( const UN_GraphData *graph_data, UN_NodeID node_id,
            const UT_StringRef &port_name )
    {
        return findPort( graph_data, node_id, UN_PortKind::Output, port_name );
    }


    /// Returns an existing port by the given name, or creates and 
    /// returns a new one (with the given type and label) if not found.
    static inline UN_PortID
    findOrCreatePort( UN_GraphData *graph_data, UN_NodeID node_id, 
            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() )
    {
        auto port = findPort( graph_data, node_id, port_kind, port_name );
        if( !port )
            port = createPort( graph_data, node_id, 
                    port_kind, port_name, port_type_name, port_label );
        return port;
    }

    /// Returns an existing input port by the given name, or creates and 
    /// returns a new one (with the given type and label) if not found.
    static inline UN_PortID
    findOrCreateInputPort( UN_GraphData *graph_data, UN_NodeID node_id, 
            const UT_StringRef &port_name,
            const UT_StringRef &port_type_name =
                UN_UNDEFINED_PORT_TYPE_NAME.asRef(),
            const UT_StringRef &port_label = UT_StringRef() )
    {
        return findOrCreatePort( graph_data, node_id, 
                UN_PortKind::Input, port_name, port_type_name, port_label );
    }

    /// Returns an existing output port by the given name, or creates and 
    /// returns a new one (with the given type and label) if not found.
    static inline UN_PortID
    findOrCreateOutputPort( UN_GraphData *graph_data, UN_NodeID node_id, 
            const UT_StringRef &port_name,
            const UT_StringRef &port_type_name =
                UN_UNDEFINED_PORT_TYPE_NAME.asRef(),
            const UT_StringRef &port_label = UT_StringRef() )
    {
        return findOrCreatePort( graph_data, node_id, 
                UN_PortKind::Output, port_name, port_type_name, port_label );
    }


    /// Returns ports of the given node.
    static inline const UN_PortIDList &
    ports( const UN_GraphData *graph_data, UN_NodeID node_id,
            UN_PortKind port_kind )
    {
        static UN_PortIDList theEmpty;
        return graph_data ? graph_data->ports( node_id, port_kind ) : theEmpty;
    }

    /// Returns input ports of the given node.
    static inline const UN_PortIDList &
    inputPorts( const UN_GraphData *graph_data, UN_NodeID node_id )
    {
        return ports( graph_data, node_id, UN_PortKind::Input );
    }

    /// Returns output ports of the given node.
    static inline const UN_PortIDList &
    outputPorts( const UN_GraphData *graph_data, UN_NodeID node_id )
    {
        return ports( graph_data, node_id, UN_PortKind::Output );
    }


    /// An iterator and a range for iterating over node port IDs.
    using PortIterator = UN_PortIDList::const_iterator;
    using PortRange = UT_IteratorRange< PortIterator >;

    /// Returns a range for traversing the ports of the given node.
    /// NOTE, the iterators hold a reference to the underlying port array, 
    ///     and therefore ports can't be added/removed during the iteration.
    ///     For adding/removing ports, use ports() function and make a copy.
    static inline PortRange
    portRange( const UN_GraphData *graph_data, UN_NodeID node_id,
            UN_PortKind port_kind )
    {
        const UN_PortIDList &port_ids = ports( graph_data, node_id, port_kind );
        return PortRange(
                PortIterator( port_ids.begin() ),
                PortIterator( port_ids.end() ));
    }

    /// Returns a range for traversing the input ports of the given node.
    static inline PortRange
    inputPortRange( const UN_GraphData *graph_data, UN_NodeID node_id )
    {
        return portRange( graph_data, node_id, UN_PortKind::Input );
    }

    /// Returns a range for traversing the output ports of the given node.
    static inline PortRange
    outputPortRange( const UN_GraphData *graph_data, UN_NodeID node_id )
    {
        return portRange( graph_data, node_id, UN_PortKind::Output );
    }


    /// An iterator and a range for iterating over node port IDs 
    /// in reverse order.
    using PortReverseIterator = UN_PortIDList::const_reverse_iterator;
    using PortReverseRange = UT_IteratorRange< PortReverseIterator >;

    /// Returns a range for traversing the ports of the given node
    /// in a reverse order than the one in node's port array.
    /// NOTE, the iterators hold a reference to the underlying port array, 
    ///     and therefore ports can't be added/removed during the iteration.
    ///     For adding/removing ports, use ports() function and make a copy.
    static inline PortReverseRange
    portReverseRange( const UN_GraphData *graph_data, UN_NodeID node_id,
            UN_PortKind port_kind )
    {
        const UN_PortIDList &port_ids = ports( graph_data, node_id, port_kind );
        return PortReverseRange(
                PortReverseIterator( port_ids.rbegin() ),
                PortReverseIterator( port_ids.rend() ));
    }

    /// Returns a range for traversing the input ports of the given node
    /// in a reverse order than the one in node's port array.
    static inline PortReverseRange
    inputPortReverseRange( const UN_GraphData *graph_data, UN_NodeID node_id )
    {
        return portReverseRange( graph_data, node_id, UN_PortKind::Input );
    }
    
    /// Returns a range for traversing the output ports of the given node
    /// in a reverse order than the one in node's port array.
    static inline PortReverseRange
    outputPortReverseRange( const UN_GraphData *graph_data, UN_NodeID node_id )
    {
        return portReverseRange( graph_data, node_id, UN_PortKind::Output );
    }


    /// Returns the names of the node ports of a given kind.
    UN_API UT_Array< UT_StringHolder >
    portNames( const UN_GraphData *graph_data, UN_NodeID node_id,
            UN_PortKind port_kind );

    /// Returns the input port names of the given node.
    static inline UT_Array< UT_StringHolder >
    inputPortNames( const UN_GraphData *graph_data, UN_NodeID node_id )
    {
        return portNames( graph_data, node_id, UN_PortKind::Input );
    }

    /// Returns the output port names of the given node.
    static inline UT_Array< UT_StringHolder >
    outputPortNames( const UN_GraphData *graph_data, UN_NodeID node_id )
    {
        return portNames( graph_data, node_id, UN_PortKind::Output );
    }


    /// Returns the type names of the node ports of a given kind.
    UN_API UT_Array< UT_StringHolder >
    portTypeNames( const UN_GraphData *graph_data, UN_NodeID node_id,
            UN_PortKind port_kind );

    /// Returns the input port type names of the given node.
    static inline UT_Array< UT_StringHolder >
    inputPortTypeNames( const UN_GraphData *graph_data, UN_NodeID node_id )
    {
        return portTypeNames( graph_data, node_id, UN_PortKind::Input );
    }

    /// Returns the output port type names of the given node.
    static inline UT_Array< UT_StringHolder >
    outputPortTypeNames( const UN_GraphData *graph_data, UN_NodeID node_id )
    {
        return portTypeNames( graph_data, node_id, UN_PortKind::Output );
    }


    /// Returns true if any of the node's input ports has a connected source
    /// wire (feeding data from a source port).
    UN_API bool
    isAnyInputPortConnectedToSrc(
            const UN_GraphData *graph_data, UN_NodeID node_id);

    /// Returns true if any of the node's output ports has a connected
    /// destination wire feeding data to a destination port. 
    UN_API bool
    isAnyOutputPortConnectedToDst(
            const UN_GraphData *graph_data, UN_NodeID node_id);


    /// Returns a node name that is not taken by any of this nodes' children,
    /// given the suggested candidate child name.
    UN_API UT_StringHolder
    findValidUniqueChildNodeName( const UN_GraphData *graph_data, UN_NodeID node_id,
            const UT_StringRef &child_name = UT_StringRef() );

    /// Returns true if the given node can have child nodes inside.
    static inline bool
    isSubnet( const UN_GraphData *graph_data, UN_NodeID node_id )
    {
        return graph_data && graph_data->isSubnet( node_id );
    }

    /// Creates and returns a new node that is a child of this node.
    UN_API UN_NodeID
    createChildNode( UN_GraphData *graph_data, UN_NodeID parent_id,
            const UT_StringRef &child_name = UT_StringRef(),
            const UT_StringRef &child_type = UT_StringRef(),
            const UT_StringRef &child_category = UT_StringRef());

    /// Returns a child node by the given name, or an invalid ID if not found.
    static inline UN_NodeID
    findChildNode( const UN_GraphData *graph_data, UN_NodeID parent_id,
            const UT_StringRef &node_name )
    {
        return graph_data 
            ? graph_data->findChildNode( parent_id, node_name )
            : UN_NodeID();
    }

    /// Returns an ID of a node at a given path, or an invalid ID if not found.
    ///
    /// @parm parent - When the given node path is relative, 
    ///     this is the anchor node from which the relative path is followed 
    ///     to find the desired node. 
    /// 
    /// @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 (in which case the parent parameter is used
    ///     as a starting point).
    ///     In particular, when the node path is just a name, this function 
    ///     will look for a child by that name directly inside the given parent.
    ///     The path can contain '.' for the current node, and '..' for 
    ///     the parent node.
    static inline UN_NodeID
    findNode( const UN_GraphData *graph_data, UN_NodeID parent_id, 
              const UT_StringRef &node_path ) 
    {
        return graph_data 
            ? graph_data->findNode( parent_id, node_path )
            : UN_NodeID();
    }

    /// Deletes the child node from the graph (removing it from this network).
    UN_API void
    deleteChildNode( UN_GraphData *graph_data, UN_NodeID parent_id,
            const UT_StringRef &child_name ) ;


    /// Returns the node IDs of the given node's children.
    static inline const UN_NodeIDList &
    childNodes( const UN_GraphData *graph_data, UN_NodeID parent_id )
    {
        static UN_NodeIDList theEmpty;
        return graph_data ? graph_data->childNodes( parent_id ) : theEmpty;
    }

    /// An iterator and a range for iterating over child node IDs.
    using ChildNodeIterator = UN_NodeIDList::const_iterator;
    using ChildNodeRange = UT_IteratorRange< ChildNodeIterator >;

    /// Returns a range for traversing the child nodes of the given node.
    /// NOTE, the iterators hold a reference to the underlying node array, and 
    ///     therefore child nodes can't be added/removed during the iteration.
    ///     For adding/removing nodes use childNodes() function and make a copy.
    static inline ChildNodeRange
    childNodeRange( const UN_GraphData *graph_data, UN_NodeID node_id )
    {
        const UN_NodeIDList &child_ids = childNodes( graph_data, node_id );
        return ChildNodeRange(
                ChildNodeIterator( child_ids.begin() ),
                ChildNodeIterator( child_ids.end() ));
    }

    /// Returns the names of the children nodes of the given parent node.
    UN_API UT_Array< UT_StringHolder >
    childNodeNames( const UN_GraphData *graph_data, UN_NodeID node_id );


    /// An iterator for traversing the descendant nodes (children, 
    /// grandchildren, etc) of a given ancestor node.
    class DescendantNodeIterator
    {
    public:
        using iterator_category = std::input_iterator_tag;
        using value_type = UN_NodeID;
        using difference_type = std::ptrdiff_t;
        using pointer = value_type*;
        using reference = value_type&;

        /// Constructor for the start iterator of the given node ancestral tree.
        DescendantNodeIterator( const UN_GraphData *graph_data, UN_NodeID node_id )
            : myGraphData( graph_data )
        {
            pushChildren( node_id );
        }

        /// Constructor for the end iterator.
        DescendantNodeIterator( const UN_GraphData *graph_data )
            : myGraphData( graph_data )
        {}

        /// @{ Comparison operators.
        bool operator ==( const DescendantNodeIterator &other ) const
        { 
            // Loops compare iterators only against the 'end' iterator, 
            // which has an empty array, so comparing sizes is enough.
            return myNodeIDs.size() == other.myNodeIDs.size()
                && myGraphData == other.myGraphData;
        }

        bool operator !=( const DescendantNodeIterator &other ) const
        { 
            return !(operator==(other));
        }
        /// @}

        /// Increment operator.
        DescendantNodeIterator &operator++()    
        { 
            UN_NodeID node_id = popChild();
            pushChildren( node_id );
            return *this; 
        }


        /// Returns the ID of the current node.
        UN_NodeID operator*() const
        {
            return !myNodeIDs.isEmpty() ? myNodeIDs.last() : UN_NodeID();
        }

        /// Returns the underlying graph in which the current node exists.
        const UN_GraphData *graph() const
        {
            return myGraphData;
        }
            

    private:
        /// Adds the children of the given node to the stack for traversal.
        void pushChildren( UN_NodeID parent_id )
        {
            if( !myGraphData )
                return;

            myNodeIDs.concat( myGraphData->childNodes( parent_id ));
        }

        /// Removes and returns the top (the current) child (or descendant)
        /// node on the traversal stack.
        UN_NodeID popChild()
        {
            UN_NodeID data_id;
            if( !myNodeIDs.isEmpty() )
            {
                data_id = myNodeIDs.last();
                myNodeIDs.removeLast();
            }

            return data_id;
        }

    private:
        /// The graph that owns the node objects.
        const UN_GraphData *myGraphData = nullptr;

        /// The stack of pending node IDs to traverse.
        /// The top of the stack is considered to be the "current" node.
        UN_NodeIDList       myNodeIDs;
    }; // end: DescendantNodeIterator

    /// A range for traversing the descendant nodes of a given ancestor node.
    using DescendantNodeRange = UT_IteratorRange< DescendantNodeIterator >;

    /// Returns a range for traversing the descendant nodes (children,
    /// grandchildren, etc) of a given ancestor node.
    static inline DescendantNodeRange 
    descendantNodeRange( const UN_GraphData *graph_data, UN_NodeID node_id )
    {
        return DescendantNodeRange( 
                DescendantNodeIterator( graph_data, node_id ),
                DescendantNodeIterator( graph_data ));
    }


    /// Returns the source wires connected to all of the ports 
    /// of the given kind on the given node. 
    /// Source wires carry data to the given node.
    UN_API UN_WireIDList
    srcWires( const UN_GraphData *graph_data, UN_NodeID node_id,
            UN_PortKind port_kind );

    /// Returns the source wires connected to all of the input ports 
    /// on the given node.  These are the wires that carry the data received 
    /// (and consumed) by the given node.
    static inline const UN_WireIDList
    inputSrcWires( const UN_GraphData *graph_data, UN_NodeID node_id )
    {
        return srcWires( graph_data, node_id, UN_PortKind::Input );
    }

    /// Returns the source wires connected to all of the output ports 
    /// on the given node. 
    /// These are the wires that carry the data received by the given node,
    /// on output ports, although the node  usually does not consume 
    /// that data; it forwards it to any dst wires connected to the output
    /// ports. This is most commonly applies to the subnet nodes.
    static inline const UN_WireIDList
    outputSrcWires( const UN_GraphData *graph_data, UN_NodeID node_id )
    {
        return srcWires( graph_data, node_id, UN_PortKind::Output );
    }


    /// Returns the destination wires connected to the of all the ports 
    /// of the given kind on the given node. 
    /// Destination wires carry data from the given node.
    UN_API UN_WireIDList
    dstWires( const UN_GraphData *graph_data, UN_NodeID node_id,
            UN_PortKind port_kind );

    /// Returns the destination wires connected to all of the input ports 
    /// on the given node. 
    /// These are the wires that carry the data sent by the given node,
    /// on input ports, although the node  usually does not produce that data; 
    /// it forwards it from any src wires connected to the input ports. 
    /// This is most commonly applies to the subnet nodes.
    static inline const UN_WireIDList
    inputDstWires( const UN_GraphData *graph_data, UN_NodeID node_id )
    {
        return dstWires( graph_data, node_id, UN_PortKind::Input );
    }

    /// Returns the destination wires connected to all of the output ports 
    /// on the given node.  These are the wires that carry the data produced
    /// (and sent) by the given node.
    static inline const UN_WireIDList
    outputDstWires( const UN_GraphData *graph_data, UN_NodeID node_id )
    {
        return dstWires( graph_data, node_id, UN_PortKind::Output );
    }



    /// Returns the IDs of the given node's child wires 
    /// (ie wires directly inside the node).
    static inline const UN_WireIDList &
    childWires( const UN_GraphData *graph_data, UN_NodeID parent_id )
    {
        static UN_WireIDList theEmpty;
        return graph_data ? graph_data->childWires( parent_id ) : theEmpty;
    }

    /// A range for traversing the wires contained directly inside a node.
    using ChildWireIterator = UN_WireIDList::const_iterator;
    using ChildWireRange = UT_IteratorRange< ChildWireIterator >;

    /// Returns a range for traversing the wires contained directly inside 
    /// the given node node.
    static inline ChildWireRange 
    childWireRange( const UN_GraphData *graph_data, UN_NodeID node_id )
    {
        const UN_WireIDList &child_ids = childWires( graph_data, node_id );
        return ChildWireRange( 
                ChildWireIterator( child_ids.begin() ),
                ChildWireIterator( child_ids.end() ));
    }


    /// An iterator for traversing the wires deep inside the given node.
    class DescendantWireIterator
    {
    public:
        using iterator_category = std::input_iterator_tag;
        using value_type = UN_WireID;
        using difference_type = std::ptrdiff_t;
        using pointer = value_type*;
        using reference = value_type&;

        /// Constructor for the start and end iterator for node's wires.
        DescendantWireIterator( const UN_GraphData *graph_data, UN_NodeID node_id )
            : myGraphData( graph_data )
            {
                myNodeIDs.append( node_id );
                advance();
            }

        /// Constructor for the end iterator.
        DescendantWireIterator( const UN_GraphData *graph_data )
            : myGraphData( graph_data )
            {}


        /// Increment operator.
        DescendantWireIterator &operator++()    
            { 
                advance();
                return *this; 
            }

        /// @{ Comparison operators.
        bool operator ==( const DescendantWireIterator &other ) const
        { 
            // Loops compare iterators only against the 'end' iterator, 
            // which has an empty array, so comparing sizes is enough.
            return myWireIDs.size() == other.myWireIDs.size()
                && myGraphData == other.myGraphData;
        }

        bool operator !=( const DescendantWireIterator &other ) const
        { 
            return !(operator==(other));
        }
        /// @}

        /// Returns the ID of the current wire.
        UN_WireID operator*() const
        { 
            return !myWireIDs.isEmpty() ? myWireIDs.last() : UN_WireID();
        }

        /// Returns the underlying graph in which the current node exists.
        const UN_GraphData *graph() const
        {
            return myGraphData;
        }

    private:
        /// Moves to the next wire in the iteration.
        void advance()
        {
            if( !myWireIDs.isEmpty() )
                myWireIDs.removeLast();

            // If needed, get the next batch of wires to traverse.
            while( myWireIDs.isEmpty() && !myNodeIDs.isEmpty() )
            {
                auto next_node_id = myNodeIDs.last();
                myNodeIDs.removeLast();

                if( myGraphData )
                {
                    myNodeIDs.concat( myGraphData->childNodes( next_node_id ));
                    myWireIDs.concat( myGraphData->childWires( next_node_id ));
                }
            }
        }

    private:
        /// The graph that owns the node objects.
        const UN_GraphData *myGraphData = nullptr;

        /// The list of pending wires in the current node to traverse.
        /// The top of the stack is considered to be the "current" wire.
        UN_WireIDList       myWireIDs;

        /// The stack of pending nodes to traverse.
        UN_NodeIDList       myNodeIDs;
    }; // end: DescendantWireIterator


    /// An range for traversing the wires between the descendants 
    /// (children, grandchildren, etc) inside a node.
    using DescendantWireRange = UT_IteratorRange< DescendantWireIterator >;

    /// Returns a range for traversing the wires between the descendants 
    /// (children, grandchildren, etc) inside the given node.
    static inline DescendantWireRange 
    descendantWireRange( const UN_GraphData *graph_data, UN_NodeID node_id )
    {
        return DescendantWireRange( 
                DescendantWireIterator( graph_data, node_id ),
                DescendantWireIterator( graph_data ));
    }


    /// Creates and returns a new sticky note that is a child of this node.
    UN_API UN_StickyNoteID
    createChildStickyNote( UN_GraphData *graph_data, UN_NodeID parent_id,
            const UT_StringRef &sticky_note_name = UT_StringRef(),
            const UT_StringRef &sticky_note_text = UT_StringRef());

    /// Returns a child sticky note by the given name, 
    /// or an invalid ID if not found.
    static inline UN_StickyNoteID
    findChildStickyNote( const UN_GraphData *graph_data, UN_NodeID parent_id,
            const UT_StringRef &sticky_note_name )
    {
        return graph_data 
            ? graph_data->findChildStickyNote( parent_id, sticky_note_name )
            : UN_StickyNoteID();
    }

    /// Deletes the child sticky note from the graph 
    /// (removing it from this network).
    UN_API void
    deleteChildStickyNote( UN_GraphData *graph_data, UN_NodeID parent_id,
            const UT_StringRef &child_sticky_note_name );

    /// Returns the sticky notes IDs directly inside the given parent node.
    static inline const UN_StickyNoteIDList &
    childStickyNotes( const UN_GraphData *graph_data, UN_NodeID parent_id )
    {
        static UN_StickyNoteIDList theEmpty;
        return graph_data ? graph_data->childStickyNotes(parent_id) : theEmpty;
    }


    /// Returns the options object representing this node.
    /// This can be then used for serialization to JSON, etc.
    UN_API UN_OptionsPtr
    asOptions( const UN_GraphData *graph_data, UN_NodeID node_id );

    /// Load and set the node based on the given options.
    UN_API void
    setFromOptions( UN_GraphData *graph_data, UN_NodeID node_id,
            const UN_Options &node_opts );
}

#endif