UN_PortData.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_PortData.h ( UN Library, C++)
 *
 * COMMENTS:
 *      Core functionality for a utility-based ports.
 */

#ifndef __UN_PortData_h__
#define __UN_PortData_h__

#include "UN_API.h"
#include "UN_Data.h"
#include "UN_Utils.h"
class UN_GraphData;


// ============================================================================
using UN_CustomPortData     = UN_CustomDataT< UN_PortID, UN_PortIndex >;
using UN_CustomPortDataPtr  = UT_UniquePtr< UN_CustomPortData >;

// ============================================================================
/// Container of data for all the ports in the graph.
/// 
/// NOTE: This class is generally not trivially relocatable, because 
/// its base class (UN_Data) is not trivially relocatable (see comment there).

class UN_API UN_PortData : public UN_Data
{
public:
    /// Constructors and destructors.
     UN_PortData( UN_CustomPortDataPtr custom_data = UN_CustomPortDataPtr() );
    ~UN_PortData() = default;

                                UN_PortData(UN_PortData&&);
    UN_PortData &               operator=(UN_PortData&&);

protected:
    /// This container can have large data, so generally, forbid 
    /// the costly copy operations to the public.
    /// Knowledgable friends and derived classes can still use them.
    friend UN_GraphData;
                                UN_PortData(const UN_PortData&) = default;
    UN_PortData &               operator=(const UN_PortData&)   = default;

public:
    /// Increases the capacity of the data buffer arrays to the given minimum,
    /// unless the capacity is already greater or equal to that minimum,
    /// in which case the capacity remains unchanged.
    void                        setCapacityIfNeeded(UN_DataSize min_capacity);

    /// @{ Returns port's custom data container, if one was provided.
    UN_CustomPortData *         customPortData()
    { 
        return UTverify_cast<UN_CustomPortData*>( customData() );
    }

    const UN_CustomPortData *   customPortData() const
    { 
        return UTverify_cast<const UN_CustomPortData*>( customData() ); 
    }
    /// @}
    
    /// Merges another port data container into this one.
    /// Returns a mapping between the port IDs in the merge source 
    /// and destination (this) data buffers.
    UN_PortIDRemap              merge( const UN_PortData &src_port_data );

    // TODO: FIXME: maybe factor it out to a (non-virtual) base class 
    //              with other data classes.
    /// @{ Configure the port based on the information in the given option entry
    void                        merge( UN_PortID port_id, 
                                        const UT_OptionEntry &port_entry );
    void                        merge( UN_PortID parm_id,
                                        const UN_Options &port_opts );
    /// @}

    /// Returns the options object representing this port data.
    // TODO: FIXME: is the include_name still needed?
    // TODO: FIXME: sweep all classes to clean up and unify asOptions()
    // TODO: FIXME: should pass config dictionary of what/how to save UN objects
    //      rather than having a series of parameters on the method.
    /// @param include_name If true, the result will contain the entry for
    ///     the node name; otherwise, the name will be skipped.
    UN_OptionsPtr               asOptionsClassic( UN_PortID port_id, 
                                        bool include_name = true ) const;


    /// Adds a slot for a new port in this container.
    /// Returns an ID that should be used to refer to this new port
    /// for accessing its data (eg, name, connection wire, etc).
    UN_PortID                   addPort();

    /// Clears the data for the given port to the default state.
    void                        clearPort( UN_PortID port_id );

    /// Removes the port from this container and frees the
    /// data slot it occupied. After calling this method the container will 
    /// have no knowledge of the port by this ID.
    /// Returns true on successs; false if the port was not found.
    bool                        removePort( UN_PortID port_id );

    /// Frees the data slots occupied by all the ports.
    /// @param 'reset_next_id' If true, the node ID generator is reset to zero.
    void                        removeAllPorts( bool reset_next_id );

    /// Returns true if the given ID refers to a valid port entry 
    /// in the data buffers. Ie, such a port exists and is valid.
    bool                        isValid( UN_PortID port_id ) const
                                    { return UN_Data::isValid( port_id ); }


    /// Iterator for traversing valid port IDs.
    class IDIterator : public UN_DataIndexMap::IDIterator
    {
    public:
        using value_type = UN_PortID;

        IDIterator( const UN_DataIndexMap::IDIterator &id_iterator )
            : UN_DataIndexMap::IDIterator( id_iterator )
        {}

        value_type operator*() const
        { return UN_PortID( UN_DataIndexMap::IDIterator::operator*() ); }
    };

    /// Iterator for traversing valid port IDs in an ascending order.
    class OrderedIDIterator : public UN_DataIndexMap::OrderedIDIterator
    {
    public:
        using value_type = UN_PortID;

        OrderedIDIterator(const UN_DataIndexMap::OrderedIDIterator &id_iterator)
            : UN_DataIndexMap::OrderedIDIterator( id_iterator )
        {}

        value_type operator*() const
        { return UN_PortID( UN_DataIndexMap::OrderedIDIterator::operator*() ); }
    };


    /// Returns a range for iterating valid port IDs. 
    using IDRange = UT_IteratorRange< IDIterator >;
    IDRange idRange() const
    {
        auto id_range( UN_Data::idRange() );
        return IDRange( id_range.begin(), id_range.end() );
    }

    /// Returns a range for iterating valid port IDs. 
    using OrderedIDRange = UT_IteratorRange< OrderedIDIterator >;
    OrderedIDRange orderedIDRange() const
    {
        auto id_range( UN_Data::orderedIDRange() );
        return OrderedIDRange( id_range.begin(), id_range.end() );
    }

    /// Returns a list of all the valid port IDs in the graph.
    UN_PortIDList portIDs() const
    {
        SYS_STATIC_ASSERT( sizeof(UN_PortID) == sizeof(UN_DataID) );
        return reinterpret_cast<UN_PortIDList&&>( std::move( dataIDs() ));
    }

    /// Returns a list of all the valid port IDs in the graph.
    UN_PortIDList sortedPortIDs() const
    {
        SYS_STATIC_ASSERT( sizeof(UN_PortID) == sizeof(UN_DataID) );
        return reinterpret_cast<UN_PortIDList&&>( std::move(sortedDataIDs() ));
    }


public:
    /// Sets the port's kind indicating whether it is an input or an output.
    void setKind( UN_PortID port_id, UN_PortKind port_kind )
    {
        // The port is either input or output; no need for invalid. 
        // Invalid is used elsewhere to indicate error in queries, etc.
        // Here, we use a bit array to conserve space and pack more data 
        // into cache lines, so it's either input or output.
        UT_ASSERT( port_kind != UN_PortKind::Invalid );
        setData( myKind, port_id, port_kind == UN_PortKind::Input );
    }

    /// Returns the port's kind indicating whether it is an input or an output.
    UN_PortKind kind( UN_PortID port_id ) const
    {
        auto index = portIndex( port_id );
        if( index )
            return myKind[ index ] ? UN_PortKind::Input : UN_PortKind::Output;

        return UN_PortKind::Invalid;
    }

protected:
    /// Sets the port name that identifies it on the node.
    // Only the friend UN_GraphData can call it because it may need to
    // enforce a unique port name.
    void setName( UN_PortID port_id, const UT_StringRef &name )
    {
        UT_ASSERT( !myCheckValidPortNames || UN_Utils::isValidPortName( name ));
        setData( myName, port_id, name );
    }

public:
    /// Returns the port name that identifies it on the node.
    const UT_StringHolder & name( UN_PortID port_id ) const
    {
        return getDataRef( myName, port_id, UT_StringHolder::theEmptyString );
    }

    /// Sets the name of the port's type.
    void setTypeName( UN_PortID port_id, const UT_StringRef &type_name )
    {
        UT_ASSERT( !myCheckValidPortTypeNames 
                || UN_Utils::isValidPortTypeName( type_name ));
        setData( myTypeName, port_id, type_name );
    }

    /// Returns the name of the port's type.
    const UT_StringHolder & typeName( UN_PortID port_id ) const
    {
        return getDataRef(myTypeName, port_id, UT_StringHolder::theEmptyString);
    }

    /// Sets the port's label.
    void setLabel( UN_PortID port_id, const UT_StringRef &label )
    {
        setData( myLabel, port_id, label );
    }

    /// Returns the port's label.
    const UT_StringHolder & label( UN_PortID port_id ) const
    {
        return getDataRef( myLabel, port_id, UT_StringHolder::theEmptyString );
    } 

    // TODO: FIXME:  consider refactoring buffers into UN-friendly objects
    //          for reuse. Eg UN_StringArrayBuffer, wchich would have
    //          set(), get(), steal(), and update(). Then UN_NodeData class
    //          would just return that buffer object.
    //          The calls would loo like node_data.tags().set(id, val);
    //
    //          Another variation would be to return a data entry handle
    //          that has set(), get(), steal(), and update() methods.
    //          node_data.tags(id).set(val).

    /// Updates the port tags in-place.
    /// Usage: updateTags(id, [&t](auto &tags) { tags.append(t);  });
    template <typename OP>
    void updateTags( UN_PortID port_id, const OP &op )
    {
        updateData( myTags, port_id, op ); 
    }

    /// Sets new tags on a port via copy-assignment.
    void setTags( UN_PortID port_id, const UT_StringArray &tags )
    {
        setData( myTags, port_id, tags );
    }

    /// Sets new tags on a port via move-assignment.
    void setTags( UN_PortID port_id, UT_StringArray &&tags )
    {
        setData( myTags, port_id, std::move(tags) );
    }

    /// Returns port's tags.
    const UT_StringArray & tags( UN_PortID port_id ) const
    {
        return getDataRef( myTags, port_id, theDefTags );
    }

    /// Returns port's tags moved from the data buffer entry.
    UT_StringArray stealTags( UN_PortID port_id )
    {
        return stealData( myTags, port_id, theDefTags );
    } 


    /// Sets the data value in a generic buffer for a given port.
    template<typename T>
    void setGenericData( UN_GenericBufferID buf_id, UN_PortID port_id,
                         const T &value )
    { UN_Data::setGenericData( buf_id, port_id, value ); }

    /// Sets the data value in a generic buffer via move.
    template<typename T>
    void setGenericData( UN_GenericBufferID buf_id, UN_PortID port_id,
                         T &&value )
    { UN_Data::setGenericData( buf_id, port_id, std::forward<T>(value) ); }

    /// Returns a const ref to the data value in a generic buffer.
    template<typename T>
    const T & genericDataRef( UN_GenericBufferID buf_id,
                           UN_PortID port_id ) const
    { return UN_Data::genericDataRef<T>( buf_id, port_id ); }

    /// Returns a copy of a data value from a generic buffer.
    template<typename T>
    T genericDataVal( UN_GenericBufferID buf_id, UN_PortID port_id ) const
    { return UN_Data::genericDataVal<T>( buf_id, port_id ); }


    /// Moves the data value out of a generic buffer.
    template<typename T>
    T stealGenericData( UN_GenericBufferID buf_id, UN_PortID port_id )
    { return UN_Data::stealGenericData<T>( buf_id, port_id ); }

    /// Updates the data value in a generic buffer in-place via a callable.
    template<typename T, typename OP>
    void updateGenericData( UN_GenericBufferID buf_id, UN_PortID port_id,
                            const OP &op )
    { UN_Data::updateGenericData<T>( buf_id, port_id, op ); }


    /// Asserts that the port names are alphanumeric.
    void                        setCheckValidPortNames( bool flag )
                                    { myCheckValidPortNames = flag; }

    /// Asserts that the port type names are alphanumeric.
    void                        setCheckValidPortTypeNames( bool flag )
                                    { myCheckValidPortTypeNames = flag; }

protected:
    /// Returns the port's data index into the data buffer arrays.
    UN_PortIndex portIndex( UN_PortID id ) const
    {
        return UN_PortIndex( UN_Data::dataIndex( id ));
    }

private:
    /// Returns the current size of the internals data buffers.
    /// The number of valid entries (slots) in data buffers is less than
    /// or equal to that number, since some data slots may be free.
    UN_DataSize coreDataBufferSize() const
    {
        UN_DataSize size( myName.size() );
        UT_ASSERT( isCoreDataSizeConsistent( size ));
        return size;
    }

    /// Handles merging of another port data container into this one.
    void        mergeCoreData( const UN_PortData &src,
                               const UN_DataMergeInfo &merge_info );

    /// Adds a new data slot to accommodate a new data piece at the given index.
    void        addCoreData( UN_PortIndex port_index );

    /// Clears the data for the given port to the default state.
    void        clearCoreData( UN_PortIndex port_index );

    /// Frees the data slot occupied by the given port,
    /// clearing it if necessary.
    void        removeCoreData() //, index)
                    // Nothing urgent to free; will clear lazily
                    { UT_ASSERT( isDataSizeConsistent() ); }

    /// Frees all the data slots.
    void        removeAllCoreData();

    /// Sets the capacity of core data buffers if needed.
    void        setCoreDataCapacityIfNeeded( UN_DataSize min_capacity );

    /// @{ Returns true if the sizes of all core data buffers are equal.
    bool        isCoreDataSizeConsistent( UN_DataSize expected_size ) const;
    bool        isCoreDataSizeConsistent() const
                    { return isCoreDataSizeConsistent( myKind.size() ); }
    /// @}

    /// Returns true if the sizes of data buffers and index map are equal.
    bool        isDataSizeConsistent() const;

public:
    // The default values for the UN port data.
    static inline const UT_StringArray  theDefTags;

private: 
    /// The port's kind. Ie, input vs. output (input == 1 or an output == 0).
    static constexpr bool       UN_INPUT_PORT  = true;
    static constexpr bool       UN_OUTPUT_PORT = false;
    static constexpr bool       UN_DEFAULT_PORT_KIND = 
                                        //arbitrary; assume input
                                        UN_PortData::UN_INPUT_PORT; 
    UN_BoolDataBuffer           myKind;

    /// The name of the port.
    UN_StringDataBuffer         myName;

    /// The type of the port.
    UN_StringDataBuffer         myTypeName;

    /// The label of the port (for GUI)
    UN_StringDataBuffer         myLabel;

    /// Port's tags.
    UN_StringArrayDataBuffer    myTags;

    /// Check an assertion that the port names are alphanumeric.
    bool                        myCheckValidPortNames = false;

    /// Check an assertion that the port type names are alphanumeric.
    bool                        myCheckValidPortTypeNames = false;
};


#endif