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

#ifndef __UN_GraphUtils_h__
#define __UN_GraphUtils_h__


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


namespace UN_GraphUtils
{
    /// Returns the root node of the graph's node parental hierarchy.
    /// The root is a special node that holds graph's top-level nodes.
    static inline UN_NodeID
    rootNode( const UN_GraphData *graph_data ) 
    {
        return graph_data ? graph_data->rootNode() : UN_NodeID();
    }

    /// Returns true if the graph accepts the given name as a legal node name.
    /// Note, even though the name is legal, it still may not be unique.
    static inline bool
    isValidNodeName( const UN_GraphData *graph_data, const UT_StringRef &name )
    {
        return graph_data && graph_data->isValidNodeName( name );
    }

    /// Based on the given name, returns a valid name that is not used 
    /// by any of the top level nodes.
    static inline UT_StringHolder
    findValidUniqueNodeName( const UN_GraphData *graph_data,
            const UT_StringRef &name = UT_StringRef() )
    {
        return UN_NodeUtils::findValidUniqueChildNodeName( 
                graph_data, rootNode(graph_data), name );
    }

    /// Returns an ID of a node at a given path, or an invalid ID if not found.
    ///
    /// @parm node_path - The node path identifying the node to find.
    ///     In particular, when the node path is just a name, this function 
    ///     will look for a top level node by that name inside the graph.
    ///     When the path contains slashes '/', the function will look
    ///     for the nested node inside the subnets.
    static inline UN_NodeID
    findNode( const UN_GraphData *graph_data, const UT_StringRef &node_path ) 
    {
        return graph_data 
            ? graph_data->findNode( rootNode(graph_data), node_path )
            : UN_NodeID();
    }

    /// Creates a new node in the given graph.
    static inline UN_NodeID
    createNode( UN_GraphData *graph_data, 
            const UT_StringRef &node_name_or_path = UT_StringRef(),
            const UT_StringRef &node_type_name = UT_StringRef(),
            const UT_StringRef &node_category_name = UT_StringRef())
    {
        UT_String parent_path, child_name;
        UT_StringWrap(node_name_or_path).splitPath( parent_path, child_name );

        UN_NodeID parent_id = parent_path 
            ? findNode( graph_data, parent_path ) 
            : rootNode( graph_data );

        if( graph_data && parent_id )
            return graph_data->createNode( parent_id, 
                    child_name, node_type_name, node_category_name );

        return UN_NodeID();
    }

    /// Removes and deletes the node from this graph.
    static inline void
    deleteNode( UN_GraphData *graph_data, const UT_StringRef &node_path )
    {
        UN_NodeID node_id = findNode( graph_data, node_path );
        if( graph_data && node_id )
            graph_data->deleteNode( node_id );
    }

    /// Returns the node IDs of the graph's top level nodes.
    static inline const UN_NodeIDList &
    topNodes( const UN_GraphData *graph_data )
    {
        return UN_NodeUtils::childNodes( graph_data, rootNode(graph_data) );
    }

    /// An iterator and a range for iterating over the IDs of graph's top nodes.
    using TopNodeIterator = UN_NodeUtils::ChildNodeIterator;
    using TopNodeRange = UT_IteratorRange< TopNodeIterator >;

    /// Returns a range for traversing the top nodes of the given graph.
    /// NOTE, the iterators hold a reference to the underlying node array, and 
    ///     therefore child nodes can't be added/removed during the iteration.
    ///     For adding/removing nodes use topNodes() function and make a copy.
    static inline TopNodeRange
    topNodeRange( const UN_GraphData *graph_data )
    {
        return UN_NodeUtils::childNodeRange( graph_data, rootNode(graph_data) );
    }

    /// Returns the names of the graph's top-level nodes.
    static inline UT_Array< UT_StringHolder >
    nodeNames( const UN_GraphData *graph_data )
    {
        return UN_NodeUtils::childNodeNames( graph_data, rootNode(graph_data) );
    }

    /// A range for traversing the all the nodes in the given graph.
    using AllNodeIterator = UN_NodeUtils::DescendantNodeIterator;
    using AllNodeRange = UT_IteratorRange< AllNodeIterator >;

    /// Returns a range for traversing the descendant nodes (children,
    /// grandchildren, etc) of a given ancestor node.
    static inline AllNodeRange 
    allNodeRange( const UN_GraphData *graph_data )
    {
        return UN_NodeUtils::descendantNodeRange( 
                graph_data, rootNode(graph_data) );
    }

    /// Returns the IDs of the top level wires directly inside the given graph.
    static inline const UN_WireIDList &
    topWires( const UN_GraphData *graph_data )
    {
        return UN_NodeUtils::childWires( graph_data, rootNode(graph_data) );
    }

    /// A range for traversing the top level wires contained directly 
    /// inside the graph.
    using TopWireIterator = UN_NodeUtils::ChildWireIterator;
    using TopWireRange = UT_IteratorRange< TopWireIterator >;

    /// Returns a range for traversing the wires contained directly inside 
    /// the given node node.
    static inline TopWireRange 
    topWireRange( const UN_GraphData *graph_data )
    {
        return UN_NodeUtils::childWireRange( graph_data, rootNode(graph_data) );
    }

    /// An range for traversing the wires between all nodes (top level 
    /// or deeply nested) inside the graph.
    using AllWireIterator = UN_NodeUtils::DescendantWireIterator;
    using AllWireRange = UT_IteratorRange< AllWireIterator >;

    /// Returns a range for traversing the wires between all nodes (top level 
    /// or deeply nested) inside the graph.
    static inline AllWireRange 
    allWireRange( const UN_GraphData *graph_data )
    {
        return UN_NodeUtils::descendantWireRange( 
                graph_data, rootNode(graph_data));
    }

    /// Creates a new sticky note in the given graph.
    static inline UN_StickyNoteID
    createStickyNote( UN_GraphData *graph_data, 
            const UT_StringRef &sticky_note_path = UT_StringRef(),
            const UT_StringRef &sticky_note_text = UT_StringRef())
    {
        UT_String parent_path, child_name;
        UT_StringWrap(sticky_note_path).splitPath( parent_path, child_name );

        UN_NodeID parent_id = parent_path 
            ? findNode( graph_data, parent_path ) 
            : rootNode( graph_data );

        if( graph_data && parent_id )
            return graph_data->createStickyNote( parent_id, 
                    sticky_note_path, sticky_note_text );

        return UN_StickyNoteID();
    }

    /// Returns an ID of a sticky note at a given path, 
    /// or an invalid ID if not found.
    ///
    /// @parm sticky_note_path - The path or name identifying the sticky note
    ///     to find.
    ///     In particular, when the path is just a name, this function 
    ///     will look for a top level sticky note by that name inside the graph.
    ///     When the path contains slashes '/', the function will look
    ///     for the nested sticky note inside the subnets.
    static inline UN_StickyNoteID
    findStickyNote( const UN_GraphData *graph_data, 
            const UT_StringRef &sticky_note_path ) 
    {
        return graph_data 
            ? graph_data->findStickyNote(rootNode(graph_data), sticky_note_path)
            : UN_StickyNoteID();
    }

    /// Removes and deletes the sticky note from this graph.
    static inline void
    deleteStickyNote( UN_GraphData *graph_data, 
            const UT_StringRef &sticky_note_path )
    {
        auto note_id = findStickyNote( graph_data, sticky_note_path );
        if( graph_data && note_id )
            graph_data->deleteStickyNote( note_id );
    }

    /// Returns the options object representing this graph.
    /// This can be then used for serialization to JSON, etc.
    UN_API UN_OptionsPtr
    asOptions( const UN_GraphData *graph_data );

    /// Load and set the graph based on the given options.
    UN_API void
    setFromOptions( UN_GraphData *graph_data, const UN_Options &graph_opts );
}

#endif