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

#ifndef __UN_ParmData_h__
#define __UN_ParmData_h__

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


// ============================================================================
using UN_CustomParmData     = UN_CustomDataT< UN_ParmID, UN_ParmIndex >;
using UN_CustomParmDataPtr  = UT_UniquePtr< UN_CustomParmData >;

// ============================================================================
/// Container of data for all the parameters 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_ParmData : public UN_Data
{
public:
    /// Constructors and destructors.
     UN_ParmData( UN_CustomParmDataPtr custom_data = UN_CustomParmDataPtr() );
    ~UN_ParmData() = default;

                                UN_ParmData(UN_ParmData &&);
    UN_ParmData &               operator=(UN_ParmData &&);

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_ParmData(const UN_ParmData &) = default;
    UN_ParmData &               operator=(const UN_ParmData &)   = 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 parm's custom data container, if one was provided.
    UN_CustomParmData *         customParmData()
    { 
        return UTverify_cast<UN_CustomParmData*>( customData() );
    }

    const UN_CustomParmData *   customParmData() const
    { 
        return UTverify_cast<const UN_CustomParmData*>( customData() ); 
    }
    /// @}

    /// Merges another parameter data container into this one.
    /// Returns a mapping between the data IDs in the merge source 
    /// and destination (this) data buffers.
    UN_ParmIDRemap              merge( const UN_ParmData &src_parm_data );

    /// @{ Sets and configures the parameter based on the given options.
    void                        merge( UN_ParmID parm_id,
                                        const UT_OptionEntry &parm_entry );
    void                        merge( UN_ParmID parm_id,
                                        const UN_Options &parm_opts );
    /// @}
    
    /// Returns the options object representing this parameter data,
    /// such as name, type and value.
    /// This can be then used for serialization to JSON, etc.
    /// @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_ParmID parm_id, 
                                        bool include_name = true ) const;



    /// Adds a slot for a new parameter in this container.
    /// Returns an ID that should be used to refer to this new parameter
    /// for accessing its data (eg, name, value, etc).
    UN_ParmID                   addParm();

    /// Clears the data for the given parameter to the default state.
    void                        clearParm( UN_ParmID parm_id );

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

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

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


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

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

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

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

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

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


    /// Returns a range for iterating valid parm 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 parm 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 parm IDs in the graph.
    UN_ParmIDList parmIDs() const
    {
        SYS_STATIC_ASSERT( sizeof(UN_ParmID) == sizeof(UN_DataID) );
        return reinterpret_cast<UN_ParmIDList&&>( std::move( dataIDs() ));
    }

    /// Returns a list of all the valid parm IDs in the graph.
    UN_ParmIDList sortedParmIDs() const
    {
        SYS_STATIC_ASSERT( sizeof(UN_ParmID) == sizeof(UN_DataID) );
        return reinterpret_cast<UN_ParmIDList&&>( std::move(sortedDataIDs() ));
    }


public:
    /// @{ The name of the parameter.
    void                        setName( UN_ParmID parm_id, 
                                         const UT_StringRef &name );
    const UT_StringHolder &     name( UN_ParmID parm_id ) const;
    /// @}
    
    /// @{ The name of the parameter.
    void                        setTypeName( UN_ParmID parm_id, 
                                         const UT_StringRef &type_name );
    const UT_StringHolder &     typeName( UN_ParmID parm_id ) const;
    /// @}
    
    /// @{ The parameter value. 
    void                        setValue( UN_ParmID parm_id,
                                        const UT_OptionEntry &opt );
    void                        setValue( UN_ParmID parm_id,
                                        UT_OptionEntryPtr &&opt );
    const UT_OptionEntryPtr &   value( UN_ParmID parm_id ) const;
    /// @}


protected:
    /// Returns the parm's data index into the data buffer arrays.
    UN_ParmIndex                parmIndex( UN_ParmID id ) const
                                    {
                                        return UN_ParmIndex( 
                                                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 node data container into this one.
    void                        mergeCoreData( const UN_ParmData &src,
                                        const UN_DataMergeInfo &merge_info );

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

    /// Clears the data for the given parm to the default state.
    void                        clearCoreData( UN_ParmIndex parm_index );

    /// Frees the data slot occupied by the given parm,
    /// 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(
                                                myName.size() ); }
    /// @}

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

private: 
    /// The name of the prameter.
    UN_StringDataBuffer         myName;

    /// The type of the parameter
    UN_StringDataBuffer         myTypeName;

    /// The value of the parameter
    UN_ValueDataBuffer          myValue;
};


#endif