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>
#include <UT/UT_Array.h>


// 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(); }

    /// Returns an exint value of this number.
    exint               exintValue() const
                            {
                                SYS_STATIC_ASSERT( 
                                        sizeof(ValueType) == sizeof(exint) );
                                return static_cast<exint>( 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) ); }

    /// 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 ); }

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


/// An index into a data container, referring to a data object.
/// Indices may be reused for new data objects, if old ones were deleted.
#define UN_DATA_INDEX(Class) \
class Class : public UN_DataIndex \
{ \
public: \
    explicit    Class( UN_DataIndex data_index = UN_DataIndex() ) \
                    : UN_DataIndex( data_index ) {} \
}; \
   \
using Class##List = UT_Array< Class >; \

UN_DATA_INDEX( UN_NodeIndex )
UN_DATA_INDEX( UN_ParmIndex )
UN_DATA_INDEX( UN_PortIndex )
UN_DATA_INDEX( UN_WireIndex )
UN_DATA_INDEX( UN_MetaDataIndex )
UN_DATA_INDEX( UN_SubnetIndex )


/// 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) ); }
};

/// A list of data IDs.
using UN_DataIDList = UT_Array< UN_DataID >;


/// Data ID is unique throughout the lifespan of a graph, but only for
/// within the same data class (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.

#define UN_DATA_ID( Class ) \
class Class : public UN_DataID \
{ \
public: \
    explicit    Class( UN_DataID data_id = UN_DataID() ) \
                    : UN_DataID( data_id ) {} \
}; \
   \
using Class##List = UT_Array< Class >; \

UN_DATA_ID( UN_NodeID )
UN_DATA_ID( UN_ParmID )
UN_DATA_ID( UN_PortID )
UN_DATA_ID( UN_WireID )
UN_DATA_ID( UN_MetaDataID )
UN_DATA_ID( UN_SubnetID )


/// For debug printouts, etc:
#define UN_NUMBER_FORMATTER(IdOrIndexType) \
inline size_t format(char *buffer, size_t buffer_size, const IdOrIndexType &v) \
{                                                                          \
    UT::Format::Writer w(buffer, buffer_size);                             \
    UT::Format::Formatter f;                                               \
    return f.format(w, #IdOrIndexType "({})", {v.exintValue()});           \
} \

UN_NUMBER_FORMATTER( UN_NodeID )
UN_NUMBER_FORMATTER( UN_ParmID )
UN_NUMBER_FORMATTER( UN_PortID )
UN_NUMBER_FORMATTER( UN_WireID )
UN_NUMBER_FORMATTER( UN_MetaDataID )
UN_NUMBER_FORMATTER( UN_SubnetID )


UN_NUMBER_FORMATTER( UN_NodeIndex )
UN_NUMBER_FORMATTER( UN_ParmIndex )
UN_NUMBER_FORMATTER( UN_PortIndex )
UN_NUMBER_FORMATTER( UN_WireIndex )
UN_NUMBER_FORMATTER( UN_MetaDataIndex )
UN_NUMBER_FORMATTER( UN_SubnetIndex )


// Needed for data IDs and indices in UT_ArrayMap and UT_ArraySet classes.
namespace UT
{
    template <typename T> struct DefaultClearer;


    template <>
    struct DefaultClearer< UN_DataID >
    {
        static void clear( UN_DataID &v )           { v = UN_DataID(); }
        static bool isClear( const UN_DataID &v )   { return !v.isValid(); }
        static void clearConstruct( UN_DataID *p )  { clear(*p); }
        static const bool clearNeedsDestruction     = false;
    };

#define UN_ID_CLEARER(ID) \
    template <> struct DefaultClearer<ID> : public DefaultClearer<UN_DataID> {};

    UN_ID_CLEARER( UN_NodeID )
    UN_ID_CLEARER( UN_ParmID )
    UN_ID_CLEARER( UN_PortID )
    UN_ID_CLEARER( UN_WireID )
    UN_ID_CLEARER( UN_SubnetID )


    template <>
    struct DefaultClearer< UN_DataIndex >
    {
        static void clear( UN_DataIndex &v )           { v.clear(); }
        static bool isClear( const UN_DataIndex &v )   { return !v.isValid(); }
        static void clearConstruct( UN_DataIndex *p )  { clear(*p); }
        static const bool clearNeedsDestruction        = false;
    };

#define UN_INDEX_CLEARER(ID) \
    template<> struct DefaultClearer<ID>: public DefaultClearer<UN_DataIndex>{};

    UN_INDEX_CLEARER( UN_NodeIndex )
    UN_INDEX_CLEARER( UN_ParmIndex )
    UN_INDEX_CLEARER( UN_PortIndex )
    UN_INDEX_CLEARER( UN_WireIndex )
    UN_INDEX_CLEARER( UN_SubnetIndex )

} // end: namespace UT


/// Differentiates between input and output ports.
enum class UN_PortKind
{ 
    Invalid,    // Unknown port kind; used for uninitialized state or errors.
    Input,      // Represents an input port.
    Output      // Represents 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