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 index 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 INDEX_ARRAY, 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, 
            INDEX_ARRAY &&data_indices,
            ID_ARRAY &&data_ids,
            exint begin = 0 )
        : myGraphData( graph_data )
        , myDataIndices( data_indices )
        , 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 myDataIndices.isValidIndex( myCurrent )
                ? HANDLE( myGraphData, 
                        myDataIndices[ myCurrent ], myDataIDs[ myCurrent ])
                : HANDLE(); 
        }


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

    /// The IDs of the data objects that are being iterated over.
    INDEX_ARRAY                 myDataIndices;

    /// 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 output ports of the wire objects
/// in the given wire index 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_WireIndexArray, UN_WireIDArray>
{
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_WireIndexArray &&data_indices, 
            UN_WireIDArray &&data_ids,
            exint begin = 0 )
        : UN_DataArrayIterator<UN_Wire, UN_WireIndexArray, UN_WireIDArray>( 
                graph_data, std::move(data_indices), std::move(data_ids), begin)
        {}

    /// Constructor for the end iterator.
    UN_WireArrayPortIterator( UN_GraphData *graph_data, exint end )
        : UN_DataArrayIterator<UN_Wire, UN_WireIndexArray, UN_WireIDArray>( 
                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_NodeIndex node_index,
            UN_NodeID node_id )
        : myGraphData( graph_data )
        {
            pushChildData( node_index, node_id );
        }

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

    /// Increment operator.
    UN_NodeDescendantIterator &operator++()     
        { 
            UN_NodeIndex node_index;
            UN_NodeID    node_id;

            popData( node_index, node_id );
            pushChildData( node_index, 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 myDataIndices.size() != other.myDataIndices.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 pushChildData( UN_NodeIndex parent_index, UN_NodeID parent_id );

    /// Removes and returns the index the top child on the traversal stack.
    void popData( UN_NodeIndex &node_index, UN_NodeID &node_id );

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

    /// The stack of pending node indices to traverse.
    UN_NodeIndexArray           myDataIndices;

    /// The stack of pending node IDs to traverse.
    UN_NodeIDArray              myDataIDs;
};


// ============================================================================
/// 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_NodeIndex node_index,
            UN_NodeID node_id,
            UN_WireIndex index,
            UN_WireIndex end )
        : myGraphData( graph_data )
        , myNodeIndex( node_index )
        , myNodeID( node_id )
        , myCurrent( index )
        , myEnd( end )
        {
            if( !isCurrentValid() )
                advance();
        }

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

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

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

private:
    /// Returns true if the current node satisfies this iterator type.
    bool                        isCurrentValid() const;

    /// Moves the iterator forward to the next valid wire, if possible.
    void                        advance();

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

    /// The index of the node inside which the iterated wires exist.
    UN_NodeIndex                myNodeIndex;

    /// The ID of the node inside which the iterated wires exist.
    UN_NodeID                   myNodeID;

    /// The current wire when iterating.
    UN_WireIndex                myCurrent;

    /// The end of range to iterate. 
    UN_WireIndex                myEnd;
};



#endif