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

#ifndef __UN_Port_h__
#define __UN_Port_h__

#include "UN_API.h"
#include "UN_Iterator.h"
#include "UN_Handle.h"
#include "UN_PortUtils.h"

class UN_ConstGraph;
class UN_ConstNode;
class UN_ConstPort;
class UN_ConstWire;
class UN_Graph;
class UN_Node;
class UN_Port;
class UN_Wire;
template<typename> class UT_Array;

// ============================================================================
// Port utility functions that take UN_Port and UN_ConstPort as parameters.
namespace UN_PortUtils
{
    /// Returns true if the given destination port is connected 
    /// to the given source port.
    UN_API bool
    isConnectedToSrc( const UN_GraphData *dst_graph_data, UN_PortID dst_port_id,
            const UN_ConstPort &src_port );

    /// Returns true if the given source port is connected 
    /// to the given destination port.
    UN_API bool
    isConnectedToDst( const UN_GraphData *src_graph_data, UN_PortID src_port_id,
            const UN_ConstPort &dst_port );
    

    /// Returns true if the given port is connected to the given other port
    /// either as a source or a destination.
    UN_API bool
    isConnected( const UN_GraphData *graph_data, UN_PortID port_id,
            const UN_ConstPort &src_or_dst_port );
}

// ============================================================================
/// Base class template for the UN port 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 PORT,        // Port handle class (UN_Port or UN_ConstPort)
          typename WIRE>        // Wire handle class (UN_Wire or UN_ConstWire)
class UN_PortBase : public BASE_CLASS
{
protected:
    /// Constructs a handle for an invalid port.
    UN_PortBase() = default;

    /// Constructs a handle that references the given port in the given graph.
    UN_PortBase( GRAPH_DATA *graph_data, UN_PortID port_id )
        : BASE_CLASS( graph_data, port_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 port this handle refers to.
    UN_PortID               portID() const
                                { return UN_PortID( BASE_CLASS::dataID() ); }

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

    explicit operator       bool() const
                                { return isValid(); }
    /// @}
   
    /// Returns the kind of a port. Ie, an input or an output.
    UN_PortKind kind() const
    { 
        return UN_PortUtils::portKind( graphData(), portID() ) ;
    }

    // Returns true if this is an input port.
    bool isInput() const
    { 
        return kind() == UN_PortKind::Input; 
    }

    // Returns true if this is an output port.
    bool isOutput() const
    { 
        return kind() == UN_PortKind::Output; 
    }

    /// Returns the port name that identifies it on the node.
    const UT_StringHolder & name() const
    { 
        return UN_PortUtils::name( graphData(), portID() );
    }

    /// Returns the port's type that determines the connection compatibility.
    const UT_StringHolder & typeName() const
    { 
        return UN_PortUtils::typeName( graphData(), portID() );
    }

    /// Returns the port's label.
    const UT_StringHolder & label() const
    { 
        return UN_PortUtils::label( graphData(), portID() );
    }

    /// Returns the port's tags.
    const UT_StringArray & tags() const
    { 
        return UN_PortUtils::tags( graphData(), portID() );
    }


    /// Returns the number of source ports connected to the given port. 
    UN_DataSize srcWireCount() const 
    {
        return UN_PortUtils::srcWireCount( graphData(), portID() );
    }

    /// Returns the number of destination ports connected to the given port. 
    UN_DataSize dstWireCount() const
    {
        return UN_PortUtils::dstWireCount( graphData(), portID() );
    }

    /// Returns the number of ports connected to the given port, 
    /// either as a source or a destination port.
    UN_DataSize wireCount() const
    {
        return UN_PortUtils::wireCount( graphData(), portID() );
    }

    /// Returns true if this port is connected to any source port.
    bool isConnectedToSrc() const
    {
        return UN_PortUtils::isConnectedToSrc( graphData(), portID() );
    }

    /// Returns true if this port is connected to the given source port.
    bool isConnectedToSrc( const UN_ConstPort &src_port ) const
    {
        return UN_PortUtils::isConnectedToSrc( graphData(), portID(), src_port);
    }

    /// Returns true if this port is connected to any destination port.
    bool isConnectedToDst() const
    {
        return UN_PortUtils::isConnectedToDst( graphData(), portID() );
    }

    /// Returns true if this port is connected to the given destination port.
    bool isConnectedToDst( const UN_ConstPort &dst_port ) const
    {
        return UN_PortUtils::isConnectedToDst( graphData(), portID(), dst_port);
    }

    /// Returns true if this port is connected to any other port.
    bool isConnected() const
    {
        return UN_PortUtils::isConnected( graphData(), portID() );
    }

    /// Returns true if this port is connected to the given port
    /// either as a source or a destination.
    bool isConnected( const UN_ConstPort &port ) const
    {
        return UN_PortUtils::isConnected( graphData(), portID(), port );
    }

    /// An iterator and a range for iterating over port's 
    /// connected source wires.
    using SrcWireIterator = UN_HandleIterator< 
            WIRE, GRAPH_DATA, UN_PortUtils::WireIterator >;
    using SrcWireRange = UT_IteratorRange< SrcWireIterator >;

    /// Returns a range for iterating over this port's source wires.
    /// 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.
    SrcWireRange srcWireRange() const
    {
        auto wire_range = UN_PortUtils::srcWireRange( graphData(), portID() );
        return SrcWireRange(
                SrcWireIterator( graphData(), wire_range.begin() ),
                SrcWireIterator( graphData(), wire_range.end() ));
    }


    /// An iterator and a range for iterating over the port's 
    /// connected destination wires.
    using DstWireIterator = UN_HandleIterator< 
            WIRE, GRAPH_DATA, UN_PortUtils::WireIterator >;
    using DstWireRange = UT_IteratorRange< DstWireIterator >;

    /// Returns a range for iterating over this port's destination wires.
    /// 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.
    DstWireRange dstWireRange() const
    {
        auto wire_range = UN_PortUtils::dstWireRange( graphData(), portID() );
        return DstWireRange(
                DstWireIterator( graphData(), wire_range.begin() ),
                DstWireIterator( graphData(), wire_range.end() ));
    }


    /// Returns the wires connecting this port to its sources.
    /// Ie, connection wires from which this port takes (receives) data.
    UT_Array<WIRE> srcWires() const
    {
        return UNhandleArray<WIRE>( graphData(), 
                UN_PortUtils::srcWires( graphData(), portID() ));
    }

    /// Returns the wires connecting this port to its destinations. 
    /// Ie, connection wires to which this port provides (sends) data.
    UT_Array<WIRE> dstWires() const
    {
        return UNhandleArray<WIRE>( graphData(), 
                UN_PortUtils::dstWires( graphData(), portID() ));
    }


    /// And iterator and a range for iterating over connected source ports.
    using SrcPortIterator = UN_HandleIterator< PORT, GRAPH_DATA,
          UN_PortUtils::PortIterator</*src=*/ true>>;
    using SrcPortRange = UT_IteratorRange< SrcPortIterator >;

    /// Returns a range for iterating over this port's source ports.
    /// 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.
    SrcPortRange srcPortRange() const
    {
        auto port_range = UN_PortUtils::srcPortRange( graphData(), portID() );

        return SrcPortRange(
                SrcPortIterator( graphData(), port_range.begin() ),
                SrcPortIterator( graphData(), port_range.end() ));
    }


    /// And iterator and a range for iterating over connected destination ports.
    using DstPortIterator = UN_HandleIterator< PORT, GRAPH_DATA,
          UN_PortUtils::PortIterator</*src=*/ false>>;
    using DstPortRange = UT_IteratorRange< DstPortIterator >;

    /// Returns a range for iterating over this port's destination ports.
    /// 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.
    DstPortRange dstPortRange() const
    {
        auto port_range = UN_PortUtils::dstPortRange( graphData(), portID() );

        return DstPortRange(
                DstPortIterator( graphData(), port_range.begin() ),
                DstPortIterator( graphData(), port_range.end() ));
    }


    /// Returns the first source port connected to this port,
    /// or an invalid port, if no source port is connected.
    PORT srcPort() const
    {
        return PORT( graphData(), 
                UN_PortUtils::srcPort( graphData(), portID() ));
    }

    /// Returns the first destination port connected to this port,
    /// or an invalid port, if no destination port is connected.
    PORT dstPort() const
    {
        return PORT( graphData(), 
                UN_PortUtils::dstPort( graphData(), portID() ));
    }


    /// Returns the source ports of this port.
    /// Ie, ports from which this port takes (receives) data.
    UT_Array<PORT> srcPorts() const
    {
        return connectedPorts</*src=*/ true>( graphData(), 
                UN_PortUtils::srcWires( graphData(), portID() ));
    }

    /// Returns the destination ports of this port.
    /// Ie, ports to which this port provides (sends) data.
    UT_Array<PORT> dstPorts() const
    {
        return connectedPorts</*src=*/ false>( graphData(), 
                UN_PortUtils::dstWires( graphData(), portID() ));
    }

private:
    /// A helper function to build an array of port handles from wire ID list.
    template <bool IS_SOURCE>
    static inline UT_Array< PORT >
    connectedPorts( GRAPH_DATA *graph_data, const UN_WireIDList &wire_ids )
    {
        UT_Array<PORT>   result( wire_ids.size() );
        for( auto &&wire_id: wire_ids )
        {
            if constexpr (IS_SOURCE)
                result.emplace_back( graph_data, graph_data->srcPort(wire_id));
            else
                result.emplace_back( graph_data, graph_data->dstPort(wire_id));
        }

        return result;
    }
};


// ============================================================================
/// A handle that references a mutable port in a graph.
/// It abstracts the APIs that operate on this port'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 port's data.
class UN_API UN_Port : public UN_PortBase< UN_Handle,
    UN_GraphData, UN_Port, UN_Wire >
{
public:
    /// Constructs a handle for an invalid node.
    UN_Port() = default;

    /// Constructs a handle referencing the given node in the given graph.
    UN_Port( UN_GraphData *graph_data, UN_PortID node_id )
        : UN_PortBase( graph_data, node_id ) 
    {}

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

    /// Returns the graph whithin which this port exists.
    UN_Graph graph() const;

    /// Returns the node to which this port belongs.
    UN_Node node() const;


    /// Sets the port name that identifies it on the node.
    void setName( const UT_StringRef &name ) const
    { 
        UN_PortUtils::setName( graphData(), portID(), name );
    }

    /// Sets the port label.
    void setLabel( const UT_StringRef &label ) const
    { 
        UN_PortUtils::setLabel( graphData(), portID(), label );
    }

    /// Sets the tags for the port (copy-assignment).
    void setTags( const UT_StringArray &tags ) const
    { 
        UN_PortUtils::setTags( graphData(), portID(), tags );
    }

    /// Sets the tags for the port (move-assignment).
    void setTags( UT_StringArray &&tags ) const
    { 
        UN_PortUtils::setTags( graphData(), portID(), std::move(tags) );
    }

    /// Returns the tags moved out of the port.
    /// 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_PortUtils::stealTags( graphData(), portID() );
    }

    /// Edits port's tags array in-place.
    /// Intended usage: 
    ///   n.updateTags([&value](auto &t) { t.set("key", value)  });
    template <typename OP>
    void updateTags( const OP &op ) const
    { 
        UN_PortUtils::updateTags( graphData(), portID(), op );
    }

    /// Connects this port to a source port from which it takes (receives)
    /// data or a value.
    /// Returns the newly created connection wire (may be invalid, if error).
    UN_Wire connectSrcPort( const UN_Port &src_port ) const;

    /// Connects this port to a destination port to which it provides (sends)
    /// data or a value.
    /// Returns the newly created connection wire (may be invalid, if error).
    UN_Wire connectDstPort( const UN_Port &dst_port ) const;

    /// Deletes this port from the graph.
    void destroy() const
    {
        UN_PortUtils::deletePort( graphData(), portID() );
    }
};


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

    /// Constructs a handle referencing the given port in the given graph.
    UN_ConstPort( const UN_GraphData *graph_data, UN_PortID port_id )
        : UN_PortBase( graph_data, port_id ) 
    {}

    /// Constructs a const handle from a mutable port handle.
    UN_ConstPort( const UN_Port &port )
        : UN_ConstPort( port.constGraphData(), port.portID() ) 
    {}

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

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

    /// Returns the node to which this port belongs.
    UN_ConstNode node() const;
};

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

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

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

#endif