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

#ifndef __UNI_ID_h__
#define __UNI_ID_h__

#include <UT/UT_Format.h>
#include <UT/UT_Array.h>
#include <SYS/SYS_StaticAssert.h>
#include <SYS/SYS_Hash.h>   // For SYShash() use in hash_value().
#include <SYS/SYS_Types.h>  // for exint

                           
// ============================================================================
/// An ID for referencing elements within the UNI library, such as graphs,
/// but also local graph's elements, like nodes, wires, etc.
class UNI_ID 
{
public:
    /// Numerical representation of the ID.
    using               NumericType = exint;
    static constexpr    NumericType INVALID_ID = -1;

    /// Explicit constructor.
    constexpr explicit  UNI_ID( NumericType id_number = INVALID_ID )
                            : myNumericValue( id_number ) {}

    /// Resets the ID to an invalid value.
    constexpr void      clear()
                            { myNumericValue = INVALID_ID; } 

    /// @{ Returns true if this ID is valid; false otherwise.
    constexpr bool      isValid() const
                            { return myNumericValue != INVALID_ID; } 
    constexpr explicit operator bool() const
                            { return isValid(); }
    /// @}
 
    /// @{ Comparison operators.
    constexpr bool      operator==( const UNI_ID &other ) const
                            { return myNumericValue == other.myNumericValue; }
    constexpr bool      operator!=( const UNI_ID &other ) const
                            { return myNumericValue != other.myNumericValue; }
    /// @}
    
    /// @{ Remaining comparison operators, used for sorting, etc.
    // Ideally, we should not have these, but since an ID ultimately has
    // a numerical representation, we provide these for convenience.
    constexpr bool      operator<( const UNI_ID &other ) const
                            { return myNumericValue < other.myNumericValue; }
    constexpr bool      operator<=( const UNI_ID &other ) const
                            { return myNumericValue <= other.myNumericValue; }
    constexpr bool      operator>( const UNI_ID &other ) const
                            { return myNumericValue > other.myNumericValue; }
    constexpr bool      operator>=( const UNI_ID &other ) const
                            { return myNumericValue >= other.myNumericValue; }
    /// @}

    /// Returns the numeric value of this ID.
    constexpr NumericType numericValue() const
    {
        return myNumericValue;
    }

    /// Returns an exint value of this ID.
    constexpr exint exintValue() const
    {
        SYS_STATIC_ASSERT( sizeof(NumericType) == sizeof(exint) );
        return static_cast<exint>( myNumericValue );
    }

    /// Cast to `exint` for use in template functions that cast templated types,
    /// but for now make it explicit, to discourage the numerical aspect of IDs.
    explicit operator exint() const
                    { return exintValue(); }

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

private:
    /// Numerical representation of the ID.
    NumericType         myNumericValue = INVALID_ID;
};

// ============================================================================
/// An ID for referencing the specific UNI graph elements.
#define UNI_ID_SUBCLASS( SubClass ) \
class SubClass : public UNI_ID \
{ \
public: \
    constexpr explicit  SubClass( NumericType id = INVALID_ID ) \
                            : UNI_ID( id ) {} \
    constexpr explicit  SubClass( const UNI_ID &id ) \
                            : UNI_ID( id ) {} \
}; \
\
using SubClass##List = UT_Array< SubClass >;  \
\

UNI_ID_SUBCLASS( UNI_GraphID )
UNI_ID_SUBCLASS( UNI_MetaDataID )
UNI_ID_SUBCLASS( UNI_NodeID )
UNI_ID_SUBCLASS( UNI_ParmID )
UNI_ID_SUBCLASS( UNI_PortID )
UNI_ID_SUBCLASS( UNI_WireID )
UNI_ID_SUBCLASS( UNI_StickyNoteID )
UNI_ID_SUBCLASS( UNI_SubnetID )

// TODO: FIXME: Define UNI_ItemID that encodes the item type and 
//              converts to and fom UNI_NodeID, UNI_WireID, etc,
//              to allow a single array sof network "items" in OPUI/FUSE.

// ============================================================================
/// String formatting ID for debug printouts, etc:
#define UNI_ID_FORMATTER(UniID)                                                \
    inline size_t                                                              \
    UTformatBuffer(char *buffer, size_t buffer_size, const UniID &v)           \
    {                                                                          \
        UT::Format::Writer w(buffer, buffer_size);                             \
        UT::Format::Formatter f;                                               \
        return f.format(w, #UniID "({})", {v.exintValue()});                   \
    }                                                                          \
    inline size_t                                                              \
    UTformatBuffer(char *buffer, size_t buffer_size, const UT_Array<UniID> &v) \
    {                                                                          \
        UT::Format::Writer w(buffer, buffer_size);                             \
        UT::Format::Formatter f;                                               \
        size_t bytesWritten = w(                                               \
                "UT_Array<" #UniID ">([",                                      \
                sizeof("UT_Array<" #UniID ">([") - 1);                         \
        bool first = true;                                                     \
        for (auto &&item : v)                                                  \
        {                                                                      \
            bytesWritten += f.format(                                          \
                    w, first ? "{}" : ", {}", {item.exintValue()});            \
            first = false;                                                     \
        }                                                                      \
        bytesWritten += w("])", 2);                                            \
        return bytesWritten;                                                   \
    }

UNI_ID_FORMATTER( UNI_ID )
UNI_ID_FORMATTER( UNI_GraphID )
UNI_ID_FORMATTER( UNI_MetaDataID )
UNI_ID_FORMATTER( UNI_NodeID )
UNI_ID_FORMATTER( UNI_ParmID )
UNI_ID_FORMATTER( UNI_PortID )
UNI_ID_FORMATTER( UNI_WireID )
UNI_ID_FORMATTER( UNI_StickyNoteID )
UNI_ID_FORMATTER( UNI_SubnetID )


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

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

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

    UNI_ID_CLEARER( UNI_GraphID )
    UNI_ID_CLEARER( UNI_MetaDataID )
    UNI_ID_CLEARER( UNI_NodeID )
    UNI_ID_CLEARER( UNI_ParmID )
    UNI_ID_CLEARER( UNI_PortID )
    UNI_ID_CLEARER( UNI_WireID )
    UNI_ID_CLEARER( UNI_StickyNoteID )
    UNI_ID_CLEARER( UNI_SubnetID )
}

// ============================================================================

#endif