UN_Types.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_Types.h ( UN Library, C++)
 *
 * COMMENTS:    Common C++ types used in the UN library.
 *      
 */

#ifndef __UN_Types_h__
#define __UN_Types_h__

#include "UN_API.h"
#include <SYS/SYS_Types.h>
#include <SYS/SYS_Hash.h>       // For SYShash() use in hash_value().
#include <UT/UT_StringHolder.h>

template <typename> class UT_Array;


// TODO: FIXME: Can the data numbers be `int` instead of `int64`?
//              Will they be different for indexing and for identification?
class UN_DataNumber 
{
public:
    /// A numerical value for indexing into data containers and for 
    /// unique IDs to validate of data objects.
    ///
    /// An enum class `ValueType` and `UN_DataNumber` should be interchangeable.
    /// UN_DataNumber really just provides methods to operate on it and
    /// the ability to "derive" from it.
    /// In particular, it should be possible to implicitly cast `ValueType`
    /// to UN_DataNumber class type.
    /// It should be possible to implicitly cast this UN_DataNumber class type
    /// to ValueType since it is an enum class, and therefore
    /// not implicitly castable to other types such as `exint` or `int`
    /// (and therefore deemed "safe" without the risk of data narrowing).
    using               ValueIntType = exint;
    enum class          ValueType : ValueIntType {};

    /// A numerical value for an invalid data object number. 
    /// It is used in initialization to denote a non-existent, invalid, 
    /// or an unknown data object.
    /// The value of -1 is consistent in its use as an index into data arrays.
    static constexpr ValueType  INVALID_NUMBER = ValueType(-1);

    /// A constructor for the data number.
    /// Note, this is not an explicit constructor to allow asting from
    /// ValueType to UN_DataNumber. See comment for `ValueType` definition.
                        UN_DataNumber( ValueType value = INVALID_NUMBER )
                            : myValue( value ) {}

    /// @{ Returns true if this data number is valid; false otherwise.
    bool                isValid() const
                            { return myValue != INVALID_NUMBER; } 
    explicit operator   bool() const
                            { return isValid(); }
    /// @}

    /// Sets the numerical value of this number.
    void                setValue( ValueType value) 
                             { myValue = value; }

    /// Returns the numerical value of this number.
    ValueType           value() const
                            { return myValue; }

    /// Implicit cast to `ValueType` since it is an enum class.
    /// See the comment for `ValueType` definition.
    operator            ValueType() const
                            { return value(); }

    /// @{ Comparison operators.
    bool                operator==( const UN_DataNumber &other ) const
                            { return myValue == other.myValue; }
    bool                operator!=( const UN_DataNumber &other ) const
                            { return myValue != other.myValue; }
    bool                operator<( const UN_DataNumber &other ) const
                            { return myValue < other.myValue; }
    bool                operator<=( const UN_DataNumber &other ) const
                            { return myValue <= other.myValue; }
    bool                operator>( const UN_DataNumber &other ) const
                            { return myValue > other.myValue; }
    bool                operator>=( const UN_DataNumber &other ) const
                            { return myValue >= other.myValue; }
    /// @}
    
    /// @{ Basic arithmetic operators.
    UN_DataNumber &     operator++()
                            { 
                                myValue = ValueType( ValueIntType(myValue) + 1);
                                return *this; 
                            }
    UN_DataNumber       operator++(int)
                            { 
                                UN_DataNumber tmp( *this ); 
                                myValue = ValueType( ValueIntType(myValue) + 1);
                                return tmp;
                            }
    /// @}

    /// Hash function for use of UN_DataNumber as a key in the UT_Map class.
    friend size_t       hash_value( const UN_DataNumber &data_number )
                            { return SYShash( data_number.value() ); }

private:
    /// The value of the data number.
    ValueType           myValue;
};


/// A type denoting the size of data arrays indexed with UN_DataIndex.
class UN_DataSize : public UN_DataNumber
{
public:
    explicit    UN_DataSize( ValueType value = ValueType(0) )
                    : UN_DataNumber( value ) {}

    /// An exint is used for UT_Array sizes, and UN_DataSize represents
    /// such size, so these types should be interchangeable.
    /// Thus providing a constructor from exint.
    explicit    UN_DataSize( exint value )
                    : UN_DataNumber( static_cast<ValueType>( value ))
                    { SYS_STATIC_ASSERT( sizeof(value) == sizeof(ValueType) ); }

    /// Returns an exint value of this data index.
    exint       exintValue() const
                    {
                        SYS_STATIC_ASSERT( sizeof(ValueType) == sizeof(exint) );
                        return static_cast<exint>( value() );
                    }

    /// Implicit cast to `exint` for sizing arrays (eg, UT_Array).
    operator    exint() const
                    { return exintValue(); }
};


/// An index into a data container, referring to a particular data object.
/// Indices may be reused for new data objects, if old objects were deleted.
class UN_DataIndex : public UN_DataNumber
{
public:
    explicit    UN_DataIndex( ValueType value = INVALID_NUMBER )
                    : UN_DataNumber( value ) {}

    /// For past-end array index.
    explicit    UN_DataIndex( UN_DataSize size )
                    : UN_DataNumber( size ) {}

    /// An exint is used for indexing into UT_Array, and UN_DataIndex represents
    /// such index, so these types should be interchangeable.
    /// Thus providing a constructor from exint.
    explicit    UN_DataIndex( exint value )
                    : UN_DataNumber( static_cast<ValueType>( value ))
                    { SYS_STATIC_ASSERT( sizeof(value) == sizeof(ValueType) ); }

    /// Resets the index to an invalid value.
    void        clear()
                    { setValue( INVALID_NUMBER ); }

    /// Returns an exint value of this data index.
    exint       exintValue() const
                    {
                        SYS_STATIC_ASSERT( sizeof(ValueType) == sizeof(exint) );
                        return static_cast<exint>( value() );
                    }

    /// Implicit cast to `exint` for indexing into arrays (eg, UT_Array).
    operator    exint() const
                    { return exintValue(); }
};


/// An index into a node data container, referring to a node data object.
/// Indices may be reused for new node data objects, if old ones were deleted.
class UN_NodeIndex : public UN_DataIndex
{
public:
    /// An index of the graph's root node.
    /// Note, the graph root node's index value of 0 is asserted as an
    /// invariant in UN_GraphData constructor.
    static constexpr ValueType  ROOT_NODE_INDEX = ValueType(0);

    /// A constructor for the node data index.
    explicit    UN_NodeIndex( UN_DataIndex data_index = UN_DataIndex() )
                    : UN_DataIndex( data_index ) {}

    /// Returns true if this index refers to the root node.
    bool        isRootNode() const
                    { return value() == ROOT_NODE_INDEX; }
};


/// An index of the graph's root node.
static const UN_NodeIndex UN_ROOT_NODE_INDEX = UN_NodeIndex( UN_DataIndex( 
            UN_NodeIndex::ROOT_NODE_INDEX ));

/// An array of node indices.
using UN_NodeIndexArray = UT_Array< UN_NodeIndex >;



/// An index into a wire data container, referring to a wire data object.
/// Indices may be reused for new wire data objects, if old ones were deleted.
class UN_WireIndex : public UN_DataIndex
{
public:
    explicit    UN_WireIndex( UN_DataIndex data_index = UN_DataIndex() )
                    : UN_DataIndex( data_index ) {}
};

/// An array of wire IDs
using UN_WireIndexArray = UT_Array< UN_WireIndex >;


/// An index into a parameter data container, referring to a parm data object.
/// Indices may be reused for new data objects, if old ones were deleted.
class UN_ParmIndex : public UN_DataIndex
{
public:
    explicit    UN_ParmIndex( UN_DataIndex data_index = UN_DataIndex() )
                    : UN_DataIndex( data_index ) {}
};

/// An array of parameter indices.
using UN_ParmIndexArray =  UT_Array< UN_ParmIndex >;


/// An index into a port data container, referring to a port data object.
/// Indices may be reused for new data objects, if old ones were deleted.
class UN_PortIndex : public UN_DataIndex
{
public:
    explicit    UN_PortIndex( UN_DataIndex data_index = UN_DataIndex() )
                    : UN_DataIndex( data_index ) {}
};

/// An array of port indices.
using UN_PortIndexArray = UT_Array< UN_PortIndex >;


/// A unique identifier of a particular data object. 
/// Data objects of the same type (eg, nodes or ports) are assigned a unique ID
/// in a given graph, and no two data objects of that type share same ID,
/// withing the lifespan of the given graph. 
/// Ie, unlike indices, the IDs are not reused for new data objects, 
/// even if some old objects were deleted. 
class UN_DataID : public UN_DataNumber
{
public:
    explicit    UN_DataID( ValueType value = INVALID_NUMBER )
                    : UN_DataNumber( value ) {}

    // Convenience constructor to create an ID from an exint value.
    explicit    UN_DataID( exint value )
                    : UN_DataNumber( static_cast<ValueType>( value ))
                    { SYS_STATIC_ASSERT( sizeof(value) == sizeof(ValueType) ); }
};

/// An array of data IDs.
using UN_DataIDArray = UT_Array< UN_DataID >;


/// Data ID is unique throughout the lifespan of a graph, but only for
/// within the same data (eg, nodes). Ie, a node may have same data id 
/// as a wire. So it's a good idea to keep these type spaces separate.
/// Defines types for various data ID numbers.

/// An node ID.
class UN_NodeID : public UN_DataID
{
public:
    explicit    UN_NodeID( UN_DataID data_id = UN_DataID() )
                    : UN_DataID( data_id ) {}
};

/// An array of node IDs.
using UN_NodeIDArray = UT_Array< UN_NodeID >;


/// A wire ID.
class UN_WireID : public UN_DataID
{
public:
    explicit    UN_WireID( UN_DataID data_id = UN_DataID() )
                    : UN_DataID( data_id ) {}
};

/// An array of node IDs.
using UN_WireIDArray = UT_Array< UN_WireID >;


/// A port ID.
class UN_PortID : public UN_DataID
{
public:
    explicit    UN_PortID( UN_DataID data_id = UN_DataID() )
                    : UN_DataID( data_id ) {}
};

/// An array of port IDs.
using UN_PortIDArray = UT_Array< UN_PortID >;


/// A parameter ID.
class UN_ParmID : public UN_DataID
{
public:
    explicit    UN_ParmID( UN_DataID data_id = UN_DataID() )
                    : UN_DataID( data_id ) {}
};

/// An array of parameter IDs.
using UN_ParmIDArray = UT_Array< UN_ParmID >;



/// Differentiates input node ports from output node ports.
enum class UN_PortKind
{ 
    INVALID,    // Unknown port kind; used for uninitialized state or errors.
    INPUT,      // Indicates an input port.
    OUTPUT      // Indicates an output port.
};


/// Unknown or undefined port type name: an empty string.
static constexpr UT_StringLit   UN_UNDEFINED_PORT_TYPE_NAME;


/// Unknown or undefined parameter type name: an empty string.
static constexpr UT_StringLit   UN_UNDEFINED_PARM_TYPE_NAME;


/// Returns true if the given type name is invalid; false otherwise;
static inline bool      UNisValid( const UT_StringRef &type_name )
                                { return type_name.isstring(); }

#endif