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

#ifndef __UN_PortUtils_h__
#define __UN_PortUtils_h__


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


// Port utility functions that take UN_GraphData and UN_PortID parameters.
namespace UN_PortUtils
{
    /// Returns true if the port by the given ID is valid in the given graph.
    static inline bool
    isValid( const UN_GraphData *graph_data, UN_PortID port_id )
    {
        return graph_data && graph_data->isValid( port_id );
    }

    /// Deletes the given port from the graph data structures.
    static inline void
    deletePort( UN_GraphData *graph_data, UN_PortID port_id )
    {
        if( isValid( graph_data, port_id ))
            graph_data->deletePort( port_id );
    }

    /// Returns what kind of a port this is: an input or an output.
    static inline UN_PortKind
    portKind( const UN_GraphData *graph_data, UN_PortID port_id )
    {
        return graph_data 
            ? graph_data->portData().kind( port_id ) 
            : UN_PortKind::Invalid;
    }

    /// Sets the port name that identifies it on the node.
    static inline void
    setName( UN_GraphData *graph_data, UN_PortID port_id,
             const UT_StringRef &name ) 
    { 
        if( graph_data )
            graph_data->setPortName( port_id, name );
    }

    /// Returns the port name that identifies it on the node.
    static inline const UT_StringHolder &
    name( const UN_GraphData *graph_data, UN_PortID port_id )
    {
        return graph_data 
            ? graph_data->portData().name( port_id )
            : UT_StringHolder::theEmptyString;
    }

    /// Sets the port type, which determines connection compatibility.
    static inline void
    setTypeName( UN_GraphData *graph_data, UN_PortID port_id,
             const UT_StringRef &type_name ) 
    { 
        if( graph_data )
            graph_data->portData().setTypeName( port_id, type_name );
    }

    /// Returns the port type, which determines connection compatibility.
    static inline const UT_StringHolder &
    typeName( const UN_GraphData *graph_data, UN_PortID port_id )
    { 
        return graph_data 
            ? graph_data->portData().typeName( port_id )
            : UT_StringHolder::theEmptyString;
    }

    /// Sets the port label.
    static inline void
    setLabel( UN_GraphData *graph_data, UN_PortID port_id,
             const UT_StringRef &name ) 
    { 
        if( graph_data )
            graph_data->portData().setLabel( port_id, name );
    }

    /// Returns the port label.
    static inline const UT_StringHolder &
    label( const UN_GraphData *graph_data, UN_PortID port_id )
    {
        return graph_data 
            ? graph_data->portData().label( port_id )
            : UT_StringHolder::theEmptyString;
    }

    /// Sets the tags for the port (copy-assignment).
    static inline void
    setTags( UN_GraphData *graph_data, UN_PortID port_id, 
             const UT_StringArray &tags ) 
    {
        if( graph_data )
            graph_data->portData().setTags( port_id, tags );
    }

    /// Sets the tags for the port (move-assignment).
    static inline void
    setTags( UN_GraphData *graph_data, UN_PortID port_id, 
             UT_StringArray &&tags ) 
    {
        if( graph_data )
            graph_data->portData().setTags( port_id, std::move(tags) );
    }

    /// Returns the tags moved out of the port data.
    static inline UT_StringArray
    stealTags( UN_GraphData *graph_data, UN_PortID port_id )
    { 
        return graph_data 
            ? graph_data->portData().stealTags( port_id ) 
            : UT_StringArray(UN_PortData::theDefTags);
    }

    /// 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_PortID port_id, const OP &op  )
    {
        if( graph_data )
            graph_data->portData().updateTags( port_id, op );
    }

    /// Returns the port's tags.
    static inline const UT_StringArray &
    tags( const UN_GraphData *graph_data, UN_PortID port_id )
    { 
        return graph_data 
            ? graph_data->portData().tags( port_id )
            : UN_PortData::theDefTags;
    }


    /// Connects the source port to the destination port and returns the
    /// resulting wire that represents that connection.
    // TODO: FIXME: add a 'mode' parm to specify whether to replace, append, or
    //      prepend the new connection. Currently we replace.
    UN_API UN_WireID
    connectPorts( UN_GraphData *graph_data, 
            UN_PortID src_port_id, UN_PortID dst_port_id );

    /// Returns IDs of the wires that connect this port to its source ports.
    /// Ie, connection wires from which this port takes (receives) data.
    static inline const UN_WireIDList &
    srcWires( const UN_GraphData *graph_data, UN_PortID dst_port_id )
    {
        static const UN_WireIDList theEmptyList;

        return isValid( graph_data, dst_port_id )
            ? graph_data->srcWires( dst_port_id )
            : theEmptyList;
    }

    /// Return IDs of the wires that connect this port to its destination ports.
    /// Ie, connection wires to which this port provides (sends) data.
    static inline const UN_WireIDList &
    dstWires( const UN_GraphData *graph_data, UN_PortID src_port_id )
    {
        static const UN_WireIDList theEmptyList;

        return isValid( graph_data, src_port_id )
            ? graph_data->dstWires( src_port_id )
            : theEmptyList;
    }

    // An iterator and a range for iterating over port connection wires.
    using WireIterator = UN_WireIDList::const_iterator;
    using WireRange = UT_IteratorRange< WireIterator >;

    /// Returns a range for traversing the source wires of the given port.
    /// Ie, wires from which this port takes (receives) data.
    /// NOTE, the iterators hold a reference to the underlying wire array, 
    ///     and therefore wires can't be added/removed during the iteration.
    ///     For adding/removing wires, use srcWires() function and make a copy.
    UN_API WireRange
    srcWireRange( const UN_GraphData *graph_data, UN_PortID dst_port_id );

    /// Returns a range for traversing the destination wires of the given port.
    /// Ie, wires to which this port provides (sends) data.
    /// NOTE, the iterators hold a reference to the underlying wire array, 
    ///     and therefore wires can't be added/removed during the iteration.
    ///     For adding/removing wires, use dstWires() function and make a copy.
    UN_API WireRange
    dstWireRange( const UN_GraphData *graph_data, UN_PortID src_port_id ); 

    /// Returns the number of source ports connected to the given port. 
    static inline UN_DataSize 
    srcWireCount( const UN_GraphData *graph_data, UN_PortID dst_port_id )
    {
        return graph_data
                ? UN_DataSize( graph_data->srcWires( dst_port_id ).size() )
                : UN_DataSize();
    }

    /// Returns the number of destination ports connected to the given port. 
    static inline UN_DataSize 
    dstWireCount( const UN_GraphData *graph_data, UN_PortID src_port_id )
    {
        return graph_data
                ? UN_DataSize( graph_data->dstWires( src_port_id ).size() )
                : UN_DataSize();
    }

    /// Returns the number of ports connected to the given port, 
    /// either as a source or a destination port.
    static inline UN_DataSize 
    wireCount( const UN_GraphData *graph_data, UN_PortID port_id )
    {
        return graph_data
                ? UN_DataSize( graph_data->srcWires( port_id ).size() +
                               graph_data->dstWires( port_id ).size() )
                : UN_DataSize();
    }

    /// Returns the number of source ports connected to the given port. 
    static inline UN_DataSize 
    srcPortCount( const UN_GraphData *graph_data, UN_PortID dst_port_id )
    {
        return srcWireCount( graph_data, dst_port_id );
    }

    /// Returns the number of destination ports connected to the given port. 
    static inline UN_DataSize 
    dstPortCount( const UN_GraphData *graph_data, UN_PortID src_port_id )
    {
        return dstWireCount( graph_data, src_port_id );
    }

    /// Returns the number of ports connected to the given port, 
    /// either as a source or a destination port.
    static inline UN_DataSize 
    portCount( const UN_GraphData *graph_data, UN_PortID port_id )
    {
        return wireCount( graph_data, port_id );
    }

    /// @{ Returns the ID of the first source wire/port 
    /// connected to the given destination port.
    /// Or returns an invalid ID if no source port is connected to it.
    /// This is a convenience method for very common graphs,  
    /// where ports can have at most one source.
    UN_API UN_WireID
    srcWire( const UN_GraphData *graph_data, UN_PortID dst_port_id );
    UN_API UN_PortID
    srcPort( const UN_GraphData *graph_data, UN_PortID dst_port_id );
    /// @}

    /// @{ Returns the ID of the first destination wire/port 
    /// connected to the given source port.
    /// Or returns an invalid ID if no destination port is connected to it.
    /// This is a convenience method for some graphs,  
    /// where ports can have at most one destination.
    UN_API UN_WireID
    dstWire( const UN_GraphData *graph_data, UN_PortID src_port_id );
    UN_API UN_PortID
    dstPort( const UN_GraphData *graph_data, UN_PortID src_port_id );
    /// @}

    /// An iterator for traversing the ports connected to the given port.
    /// NOTE, it holds a reference to the given wires array, and therefore
    ///     node ports can't be safely added/removed during the iteration.
    template <bool IS_SOURCE_ITERATOR>
    class PortIterator
    {
    public:
        using iterator_category = std::input_iterator_tag;
        using value_type = UN_PortID;
        using difference_type = std::ptrdiff_t;
        using pointer = value_type*;
        using reference = value_type&;

        /// Constructor for the start iterator.
        PortIterator( const UN_GraphData *graph_data, 
                      const UN_WireIDList::const_iterator &wire_id_iterator )
            : myGraphData( graph_data )
            , myWireIDIterator( wire_id_iterator )
        {}

        /// Equality comparison operator.
        bool operator ==( const PortIterator &other ) const
        { 
            return myWireIDIterator == other.myWireIDIterator
                && myGraphData == other.myGraphData;
        }

        /// Inequality comparison operator.
        bool operator !=( const PortIterator &other ) const
        { 
            return !(operator==(other));
        }

        /// Increment operator.
        PortIterator &operator++()      
        { 
            ++myWireIDIterator; 
            return *this; 
        }

        /// Returns the current port ID.
        UN_PortID operator*() const
        {
            if( !myGraphData )
                return UN_PortID();
            if constexpr (IS_SOURCE_ITERATOR)
                return myGraphData->srcPort( *myWireIDIterator );
            else
                return myGraphData->dstPort( *myWireIDIterator );
        }

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

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

        /// The underlying wire iterator to which to delegate the calls.
        UN_WireIDList::const_iterator myWireIDIterator;
    };

    /// A range for traversing the source ports of the given port.
    using SrcPortIterator = PortIterator< /*is_src=*/ true >;
    using SrcPortRange = UT_IteratorRange< SrcPortIterator >;

    /// Returns a range for traversing the source ports of the given port.
    /// Ie, ports from which this port takes (receives) data.
    /// NOTE, the iterators hold a reference to the underlying wire array, 
    ///     and therefore ports can't be added/removed during the iteration.
    ///     For adding/removing ports, use srcPorts() function.
    UN_API SrcPortRange
    srcPortRange( const UN_GraphData *graph_data, UN_PortID dst_port_id );

    /// A range for traversing the destination ports of the given port.
    using DstPortIterator = PortIterator< /*is_src=*/ false >;
    using DstPortRange = UT_IteratorRange< DstPortIterator >;

    /// Returns a range for traversing the destination ports of the given port.
    /// Ie, ports to which this port provides (sends) data.
    /// NOTE, the iterators hold a reference to the underlying wire array, 
    ///     and therefore ports can't be added/removed during the iteration.
    ///     For adding/removing ports, use dstPorts() function.
    UN_API DstPortRange
    dstPortRange( const UN_GraphData *graph_data, UN_PortID src_port_id ); 

    /// Returns the IDs of the ports connected as sources to the given port.
    /// Ie, ports from which this port takes (receives) data.
    UN_API UN_PortIDList 
    srcPorts( const UN_GraphData *graph_data, UN_PortID dst_port_id );

    /// Returns the IDs of the ports connected as destinations to the given port.
    /// Ie, ports to which this port provides (sends) data.
    UN_API UN_PortIDList 
    dstPorts( const UN_GraphData *graph_data, UN_PortID src_port_id ); 

    /// Returns true if the given port is connected to any source port.
    static inline bool
    isConnectedToSrc( const UN_GraphData *graph_data, UN_PortID dst_port_id )
    {
        return srcPortCount( graph_data, dst_port_id ) > 0;
    }

    /// Returns true if the given destination port is connected to 
    /// (and takes/receives data from) the given source port.
    static inline bool
    isConnectedToSrc( const UN_GraphData *graph_data, UN_PortID dst_port_id,
            UN_PortID src_port_id )
    {
        for( auto p : srcPortRange( graph_data, dst_port_id ))
            if( p == src_port_id )
                return true;

        return false;
    }

    /// Returns true if the given port is connected to any destination port.
    static inline bool
    isConnectedToDst( const UN_GraphData *graph_data, UN_PortID src_port_id )
    {
        return dstPortCount( graph_data, src_port_id ) > 0;
    }

    /// Returns true if the given source port is connected to 
    /// (and provides/sends data to) the given destination port.
    static inline bool
    isConnectedToDst( const UN_GraphData *graph_data, UN_PortID src_port_id,
            UN_PortID dst_port_id )
    {
        for( auto p : dstPortRange( graph_data, src_port_id ))
            if( p == dst_port_id )
                return true;

        return false;
    }

    /// Returns true if the given port is connected to any other port.
    static inline bool
    isConnected( const UN_GraphData *graph_data, UN_PortID port_id )
    {
        return isConnectedToSrc( graph_data, port_id ) 
            || isConnectedToDst( graph_data, port_id );
    }

    /// Returns true if the given ports are connected together,
    /// either as source and destination, or vice versa.
    static inline bool
    isConnected( const UN_GraphData *graph_data, 
            UN_PortID port_id, UN_PortID src_or_dst_port_id )
    {
        return isConnectedToSrc( graph_data, port_id, src_or_dst_port_id ) 
            || isConnectedToDst( graph_data, port_id, src_or_dst_port_id );
    }
}

#endif