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

#ifndef __UN_Iterator_h__
#define __UN_Iterator_h__

#include "UN_API.h"
#include "UN_Types.h"
#include <UT/UT_Array.h> // for UN_WireArrayPortIterator
#include <SYS/SYS_Types.h>
#include <iterator>

class UN_GraphData;
class UN_Node;
class UN_Port;
class UN_Wire;


// ============================================================================
/// Iterator for traversing the given data ID array. 
/// The iterator dereferences as a handle to the data object.
/// Used for iterating children of a node, parameters of a node, etc.

template <typename HANDLE, typename ID_ARRAY>
class UN_DataArrayIterator
{
public:
    using iterator_category = std::input_iterator_tag;
    using value_type = HANDLE;
    using difference_type = std::ptrdiff_t;
    using pointer = value_type*;
    using reference = value_type&;

    /// Constructor for the start iterator of the given data array.
    UN_DataArrayIterator( UN_GraphData *graph_data, 
            ID_ARRAY &&data_ids,
            exint begin = 0 )
        : myGraphData( graph_data )
        , myDataIDs( data_ids )
        , myCurrent( begin )
        {}

    /// Constructor for the end iterator.
    UN_DataArrayIterator( UN_GraphData *graph_data, exint end )
        : myGraphData( graph_data )
        , myCurrent( end )
        {}

    /// Increment operator.
    UN_DataArrayIterator &operator++()  
        { 
            ++myCurrent; 
            return *this; 
        }

    /// Comparison operator.
    bool operator !=( const UN_DataArrayIterator &other ) const
        { 
            return myCurrent   != other.myCurrent
                || myGraphData != other.myGraphData;
        }

    /// Dereferencing operator, returns the handle to the current data object.
    HANDLE operator*() const
        {
            return handle();
        }

    /// Returns the handle to the current data object.
    HANDLE handle() const
        { 
            return myDataIDs.isValidIndex( myCurrent )
                ? HANDLE( myGraphData, myDataIDs[ myCurrent ])
                : HANDLE(); 
        }


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

    /// The ID numbers of the data ojects that are bing iterated over.
    ID_ARRAY                    myDataIDs;

    /// The current data object when iterating.
    exint                       myCurrent;
};


// ============================================================================
/// Iterator for traversing the input or the output ports of wire objects
/// in the given wire ID array. 
/// The iterator dereferences as a handle to the port data object.
/// Used for iterating connected ports.
template <bool IS_SOURCE_ITERATOR>
class UN_WireArrayPortIterator : 
    public UN_DataArrayIterator<UN_Wire, UN_WireIDList>
{
public:
    using iterator_category = std::input_iterator_tag;
    using value_type = UN_Port;
    using difference_type = std::ptrdiff_t;
    using pointer = value_type*;
    using reference = value_type&;

    /// Constructor for the start iterator of the given data array.
    UN_WireArrayPortIterator( UN_GraphData *graph_data, 
            UN_WireIDList &&data_ids,
            exint begin = 0 )
        : UN_DataArrayIterator<UN_Wire, UN_WireIDList>( 
                graph_data, std::move(data_ids), begin)
        {}

    /// Constructor for the end iterator.
    UN_WireArrayPortIterator( UN_GraphData *graph_data, exint end )
        : UN_DataArrayIterator<UN_Wire, UN_WireIDList>( 
                graph_data, end )
        {}

    /// Dereferencing operator, returns the handle to the connected port 
    /// of the data object.
    UN_Port operator*() const;
};

// These are implemented in .C file.
template <> UN_API UN_Port UN_WireArrayPortIterator<true>::operator*() const;
template <> UN_API UN_Port UN_WireArrayPortIterator<false>::operator*() const;


// ============================================================================
/// Iterator for traversing the node data objects that are arranged in
/// a parental tree hierarchy.
/// The iterator dereferences as a handle to node data object.
/// Used for iterating connected nodes in nested subnetworks.
class UN_API UN_NodeDescendantIterator
{
public:
    using iterator_category = std::input_iterator_tag;
    using value_type = UN_Node;
    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.
    UN_NodeDescendantIterator( UN_GraphData *graph_data, UN_NodeID node_id )
        : myGraphData( graph_data )
        {
            pushChild( node_id );
        }

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

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

    /// Comparison operator.
    bool operator !=( const UN_NodeDescendantIterator &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;
        }

    /// Dereferencing operator, returns the handle to the current node data obj.
    UN_Node             operator*() const;
        

private:
    /// Adds the children of the given node to the stack for traversal.
    void                pushChild( UN_NodeID parent_id );

    /// Removes and returns the top (the current) child on the traversal stack.
    UN_NodeID           popChild();

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

    /// The stack of pending node IDs to traverse.
    UN_NodeIDList       myNodeIDs;
};


// ============================================================================
/// Iterator for traversing the wires inside the given node.
/// The iterator dereferences as a handle to the wire data object.
/// Used for iterating wires inside a node.
template <bool CHILD_ONLY>
class UN_API UN_NodeWireIterator
{
public:
    using iterator_category = std::input_iterator_tag;
    using value_type = UN_Wire;
    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.
    UN_NodeWireIterator( UN_GraphData *graph_data, UN_NodeID node_id )
        : myGraphData( graph_data )
        {
            myNodeIDs.append( node_id );
            advance();
        }

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


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

    /// Comparison operator.
    bool operator !=( const UN_NodeWireIterator &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;
        }

    /// Dereferencing operator, returns the handle to the wire inside the node.
    UN_Wire             operator*() const;
 

private:
    /// Moves to the next wire in the iteration.
    void                advance();

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

    /// The list of pending wires in the current node to traverse.
    UN_WireIDList       myWireIDs;

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



#endif