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

#ifndef __UN_Wire_h__
#define __UN_Wire_h__

#include "UN_API.h"
#include "UN_Handle.h"
#include "UN_Port.h"
#include "UN_WireUtils.h"

class UN_ConstGraph;
class UN_Graph;


// ============================================================================
/// Base class template for the UN wire 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)
class UN_WireBase : public BASE_CLASS
{
protected:
    /// Constructs a handle for an invalid wire.
    UN_WireBase() = default;

    /// Constructs a handle that references the given wire in the given graph.
    UN_WireBase( GRAPH_DATA *graph_data, UN_WireID wire_id )
        : BASE_CLASS( graph_data, wire_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 wire this handle refers to.
    UN_WireID               wireID() const
                                { return UN_WireID( BASE_CLASS::dataID() ); }

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

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

    /// Returns the source port of this wire.
    /// Ie, port that produces and sends the data.
    PORT srcPort() const
    {
        return PORT( graphData(),
                UN_WireUtils::srcPort( graphData(), wireID() ));
    }

    /// Returns the destination port of this wire.
    /// Ie, port that receives and consumes the data.
    PORT dstPort() const
    {
        return PORT( graphData(),
                UN_WireUtils::dstPort( graphData(), wireID() ));
    }
};

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

    /// Constructs a handle referencing the given wire in the given graph.
    UN_Wire( UN_GraphData *graph_data, UN_WireID wire_id )
        : UN_WireBase( graph_data, wire_id ) 
    {}

    /// @{ Comparison operators.  
    // Allows comparing wire handles, but guards against 
    // comparing wires to ports, for example.
    bool    operator==( const UN_Wire &other ) const
                { return UN_ConstHandle::operator==( other ); }
    bool    operator!=( const UN_Wire &other ) const
                { return UN_ConstHandle::operator!=( other ); }
    /// @}
    
    /// Returns the graph whithin which this wire exists.
    UN_Graph graph() const;
};


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

    /// Constructs a handle referencing the given wire in the given graph.
    UN_ConstWire( const UN_GraphData *graph_data, UN_WireID wire_id )
        : UN_WireBase( graph_data, wire_id ) 
    {}

    /// Constructs a const handle from a mutable wire handle.
    UN_ConstWire( const UN_Wire &wire )
        : UN_ConstWire( wire.constGraphData(), wire.wireID() ) 
    {}

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


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

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

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

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