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

#ifndef __UN_Include_h__
#define __UN_Include_h__

#include "UN_API.h"
#include <UNI/UNI_Include.h>
#include <UT/UT_Array.h>
#include <UT/UT_ArrayMap.h>
#include <UT/UT_Options.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_UniquePtr.h>    // IWYU pragma: export
#include <SYS/SYS_Types.h>
#include <SYS/SYS_Hash.h>       // For SYShash() use in hash_value().


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.
    constexpr           UN_DataNumber( ValueType value = INVALID_NUMBER )
                            : myValue( value ) {}

    /// @{ Returns true if this data number is valid; false otherwise.
    constexpr bool      isValid() const
                            { return myValue != INVALID_NUMBER; } 
    constexpr 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.
    constexpr 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.
    constexpr exint     exintValue() const
                            {
                                SYS_STATIC_ASSERT( 
                                        sizeof(ValueType) == sizeof(exint) );
                                return static_cast<exint>( value() );
                            }


    /// @{ Comparison operators.
    constexpr bool      operator==( const UN_DataNumber &other ) const
                            { return myValue == other.myValue; }
    constexpr bool      operator!=( const UN_DataNumber &other ) const
                            { return myValue != other.myValue; }
    constexpr bool      operator<( const UN_DataNumber &other ) const
                            { return myValue < other.myValue; }
    constexpr bool      operator<=( const UN_DataNumber &other ) const
                            { return myValue <= other.myValue; }
    constexpr bool      operator>( const UN_DataNumber &other ) const
                            { return myValue > other.myValue; }
    constexpr 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.
/// It can also be used as the size of the interval between indices,
/// eg, to offset an index by a delta.
class UN_DataSize : public UN_DataNumber
{
public:
    /// Constructs the size object given the numerical value.
    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:
    /// Constructs the index object given the numerical value.
    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(); }

    /// @{ Some arithmetic operators that make sense on indices.
    UN_DataIndex    operator+( UN_DataSize offset )
                        { 
                            return UN_DataIndex( ValueType( 
                                        exintValue() + offset.exintValue() ));
                        }

    UN_DataIndex    operator-( UN_DataSize offset )
                        { 
                            return UN_DataIndex( ValueType( 
                                        exintValue() - offset.exintValue() ));
                        }

    UN_DataIndex    operator+=( UN_DataSize offset )
                        { 
                            *this = *this + offset;
                            return *this; 
                        }

    UN_DataIndex    operator-=( UN_DataSize offset )
                        { 
                            *this = *this - offset;
                            return *this; 
                        }
    /// @}
                    
};


/// A range of contiguous data indices.
/// Commonly used for copying blocks of data in the buffers.
class UN_DataIndexSpan
{
public:
    /// Construct the data index span range object given.
    explicit        UN_DataIndexSpan( UN_DataIndex start, UN_DataSize size )
                        : myStart(start), mySize(size)
                        {}

    /// Returns the first index in the range.
    UN_DataIndex    start() const
                        { return myStart; }

    /// Returns the number of indices in the range.
    UN_DataSize     size() const 
                        { return mySize; }

private:
    UN_DataIndex    myStart;
    UN_DataSize     mySize;
};

/// 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 )
UN_DATA_INDEX( UN_StickyNoteIndex )


/// 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. 
using UN_DataID = UNI_ID;
using UN_DataIDList = UT_Array< UN_DataID >;

// Forward declare the templated remap, to use in the macro below.
template <typename ID> class UN_DataIDRemapT;

/// 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.
/// Note, since UN is an implementation of the UNI interface, it reuses
/// (aliases) the UNI IDs to avoid frequent type casts. 
/// However, it is possible to decouple them if really needed in the future.
#define UN_DATA_ID( SubClass, BaseClass ) \
using SubClass = BaseClass; \
using SubClass##List  = BaseClass##List; \
using SubClass##Remap = UN_DataIDRemapT< SubClass >; \

UN_DATA_ID( UN_NodeID,      UNI_NodeID )
UN_DATA_ID( UN_ParmID,      UNI_ParmID )
UN_DATA_ID( UN_PortID,      UNI_PortID )
UN_DATA_ID( UN_WireID,      UNI_WireID )
UN_DATA_ID( UN_SubnetID,    UNI_SubnetID )
UN_DATA_ID( UN_MetaDataID,  UNI_MetaDataID )
UN_DATA_ID( UN_StickyNoteID,UNI_StickyNoteID )


/// Template function to return an array of data handles constructed
/// from an range of data IDs (eg, an array, a span, or a pair of iterators).
template <typename HANDLE, typename GRAPH_DATA, typename ID_RANGE>
static inline UT_Array< HANDLE >
UNhandleArray( GRAPH_DATA *graph_data, const ID_RANGE &data_ids )
{
    UT_Array<HANDLE> result( data_ids.size() );

    for( auto &&data_id : data_ids )
        result.append( HANDLE( graph_data, data_id ));

    return result;
}


/// Index and ID of the graph's root node.
/// We often treat the root node in a special way,
/// eg, skip it when iterating actual graph nodes, skip it in merging graphs.
/// We can make that code simpler and faster if we can assume that
/// the root ID and INDEX is 0. 
static constexpr UN_DataID      UN_ID_ZERO( UN_DataID(0) );
static constexpr UN_NodeID      UN_ROOT_NODE_ID( UN_ID_ZERO );
static constexpr UN_SubnetID    UN_ROOT_SUBNET_ID( UN_ID_ZERO );

/// Returns true if the given node ID corresponds to the graph root node.
static inline bool          UNisRoot( UN_NodeID node_id )
                                { return node_id == UN_ROOT_NODE_ID; }
static inline bool          UNisRoot( UN_SubnetID subnet_id )
                                { return subnet_id == UN_ROOT_SUBNET_ID; }


/// Class that remaps data IDs. 
/// Eg, between merged data conainers, like UN_NodeData.
/// It's a lightweight object representing a mapping of old IDs to new ones. 
/// NOTE: Assumes the underlying mapping is representable as a constant shift.
///       However it has a few range checks for consistency. 
class UN_DataIDRemap 
{
public:
    /// Default constructor
    UN_DataIDRemap() = default;

    /// Convenience constructor.
    /// @p old_id_end - the limit on the original IDs in the source.
    ///     Used for rudimentary range checks.
    /// @p new_id_start - the base destination ID at which the entries 
    ///     copied from the source begin their new IDs in the destination.
    /// If @p combine_id_zero is true, the data for the ID zero is not mapped
    ///     to a brand new data slot, but is remapped to an existing ID of zero.
    ///     Some data containers use ID of zero for a special entry 
    ///     that is treated differently than the other ones.  Notably, 
    ///     the node data container uses ID of zero for the root node, and 
    ///     the root node from the src should not become a regular node in dest.
    ///     Instead, src root ID maps to dst root ID and their data is combined.
    UN_DataIDRemap( UN_DataID old_id_end, 
            UN_DataID new_id_start, 
            bool combine_id_zero = false )
        : myNewStartID( new_id_start.exintValue() )
        , myShouldCombineIDZero( combine_id_zero )
        , myOldEndID( old_id_end.exintValue() )
    {}

    /// Returns the start offset for the destination ID range. 
    /// I.e. the ID which source ID zero would be mapped to. 
    /// Can be used with @ref remapIdFromOffsets to map between ID sets
    /// with identical structure.
    UN_DataID           newStartOffset() const 
                            { return myNewStartID; }

    /// Returns the limit for the old IDs source range.
    UN_DataID           oldEndOffset() const 
                            { return myOldEndID; }

    /// Returns the number of IDs reserved by this merge map.
    UN_DataSize         size() const 
                            { return UN_DataSize( myOldEndID.exintValue() ); }

    /// Return @c true if the mergemap was constructed with a valid 
    /// @c newStartOffset().
    /// Default-constructed instances will return @c false.
    explicit operator   bool() const 
                            { return myNewStartID.isValid(); }

    /// Returns the new ID corresponding to the @p old ID,
    /// if the @p old ID is an ID contained within the source ID range; 
    /// otherwise, returns an invalid ID.
    UN_DataID           operator[]( UN_DataID old_id ) const
    {
        if( !old_id )
            return UN_DataID(); // invalid ID
        else if( old_id.exintValue() >= myOldEndID.exintValue() )
            return UN_DataID(); // invalid old range
        else if( myShouldCombineIDZero && old_id == UN_ID_ZERO )
            return UN_ID_ZERO;
        else
            return UN_DataID( myNewStartID.exintValue() + old_id.exintValue() 
                    - (myShouldCombineIDZero ? 1 : 0) );
    }

    /// Returns the data ID that should be used for the data created next time.
    UN_DataID           nextDataID() const
    {
        return UN_DataID( myNewStartID.exintValue() + myOldEndID.exintValue()
                - (myShouldCombineIDZero ? 1 : 0) );
    }


    /// Let O be some object in an ID set S. 
    /// If S is remapped multiple times at offsets A and B,
    /// with I being its ID within A, then @c{remapIdFromOffsets(I, A, B)} will 
    /// return the ID of O within the remapping starting at B. 
    /// If these conditions are not met, an undefined ID is returned.
    static UN_DataID    remapIDFromOffsets( UN_DataID old_id, 
                                UN_DataID old_offset, UN_DataID new_offset )
    {
        return UN_DataID( old_id.exintValue() - old_offset.exintValue() 
                + new_offset.exintValue() );
    }

private:
    /// The base destination ID that shifts the old IDs to the new IDs.
    UN_DataID           myNewStartID;

    /// The flag to indicate whether the data for the ID zero is mapped
    /// to a brand new data slot or is mapped to an existing ID of zero.
    /// Some data containers use ID of zero for a special entry 
    /// that is treated differently than the other ones.  Notably, 
    /// the node data container uses ID of zero for the root node, and 
    /// the root node from the src should not become a regular node in dest.
    /// Instead, src root ID maps to dst root ID and their data is combined.
    bool                myShouldCombineIDZero = false;

    /// The range limit of the original IDs (for basic consistency checks).
    UN_DataID           myOldEndID;
};


/// Adaptor of the UN_DataIDRemap to specific data types.
template <typename ID>
class UN_DataIDRemapT : public UN_DataIDRemap
{
public:
    /// Default constructor
    UN_DataIDRemapT() = default;

    /// Convenience constructor that takes an instance of the base class.
    UN_DataIDRemapT( const UN_DataIDRemap &remap_base )
        : UN_DataIDRemap( remap_base )
    {}

    /// Convenience constructor. See UN_DataIDRemap.
    UN_DataIDRemapT( ID old_id_end, ID new_id_start, 
            bool combine_id_zero = false )
        : UN_DataIDRemap( old_id_end, new_id_start, combine_id_zero )
    {}

    /// Returns the new ID corresponding to the @p old ID,
    /// if the @p old ID is an ID contained within the source ID range; 
    /// otherwise, returns an invalid ID.
    ID                  operator[]( ID old_id ) const
                            { return ID(UN_DataIDRemap::operator[]( old_id )); }

    /// @see operator[]
    ID                  at( ID old_id ) const 
                            { return operator[]( old_id ); }
};


/// Information about data entries merged from another map.
/// Data buffers use this info to actually copy over the corresponding data.
class UN_DataMergeInfo
{
public:
    /// Constructor.
    UN_DataMergeInfo( UN_DataIDRemap &&data_id_remap, 
                  UT_Array<UN_DataIndexSpan> &&data_idx_spans )
        : myDataIDRemap( std::move( data_id_remap ))
        , myDataIndexSpans( std::move( data_idx_spans ))
        {}

    /// Returns the continous index ranges that can be block-copied. 
    const UT_Array< UN_DataIndexSpan > & dataIndexSpans() const 
                                        { return myDataIndexSpans; }

    /// Returns the data IDs remapping that occured during a merge.
    /// Maps the old ID from the merge source to the new ID in destination.
    const UN_DataIDRemap &          dataIDRemap() const 
                                        { return myDataIDRemap; }


private:
    /// A map between merged data's old IDs in the source 
    /// and the new IDs in the destination.
    UN_DataIDRemap                  myDataIDRemap;

    /// Data buffers often use contiguous arrays. To optimize copying
    /// data during a merge, they can use this info to bulk-copy entries.
    UT_Array< UN_DataIndexSpan >    myDataIndexSpans;
};


/// Package of remappings for various data ID types (nodes, ports, subnets).
class UN_IDRemapInfo
{
public:
    /// Constructors
    UN_IDRemapInfo() = default;
    UN_IDRemapInfo( 
            UN_NodeID root_destination_node,
            UN_NodeIDRemap &&node_id_remap,
            UN_SubnetIDRemap &&subnet_id_remap,
            UN_PortIDRemap &&port_id_remap,
            UN_WireIDRemap &&wire_id_remap,
            UN_StickyNoteIDRemap &&sticky_note_id_remap )
        :   myRootDstNode( root_destination_node )
        ,   myNodeIDRemap( std::move(node_id_remap) )
        ,   mySubnetIDRemap( std::move(subnet_id_remap) )
        ,   myPortIDRemap( std::move(port_id_remap) )
        ,   myWireIDRemap( std::move(wire_id_remap) )
        ,   myStickyNoteIDRemap( std::move(sticky_note_id_remap) )
    {}

    // An existing node in the destination graph to which the source root
    // should map to. Ie, into which node to merge the other graph.
    UN_NodeID               rootDstNode() const     { return myRootDstNode; }

    /// @{ Returns the object the remaps the various data IDs 
    /// from the src to dst after the graph merge.
    const UN_NodeIDRemap &  nodeIDRemap() const     { return myNodeIDRemap; }
    const UN_SubnetIDRemap& subnetIDRemap() const   { return mySubnetIDRemap; }
    const UN_PortIDRemap &  portIDRemap() const     { return myPortIDRemap; }
    const UN_WireIDRemap &  wireIDRemap() const     { return myWireIDRemap; }
    const UN_StickyNoteIDRemap &stickyNoteIDRemap() const
                                                { return myStickyNoteIDRemap; }
    /// @}
        
private:
    // TODO: FIXME: should the root be moved to UN_GraphMergeInfo?
    // An existing node in the destination graph to which the source root
    // should map to. Ie, into which node to merge the other graph.
    UN_NodeID           myRootDstNode;

    // Objects that remap data IDs from the src to the dst after the merge.
    UN_NodeIDRemap      myNodeIDRemap;
    UN_SubnetIDRemap    mySubnetIDRemap;
    UN_PortIDRemap      myPortIDRemap;
    UN_WireIDRemap      myWireIDRemap;
    UN_StickyNoteIDRemap myStickyNoteIDRemap;
};

/// Information about the result of a merge from another graph.
class UN_GraphMergeInfo
{
public:
    /// Constructors
    UN_GraphMergeInfo() = default;
    UN_GraphMergeInfo( UN_IDRemapInfo &&id_remap_info )
        : myIDRemapInfo( std::move( id_remap_info ))
    {}

    /// Returns the object that contains mapping between data IDs after merge.
    const UN_IDRemapInfo & idRemapInfo()    
                                { return myIDRemapInfo; }

private:
    /// Contains mapping of IDs from source graph to IDs in destination graph.
    UN_IDRemapInfo      myIDRemapInfo;
};

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


UN_NUMBER_FORMATTER( UN_DataIndex )
UN_NUMBER_FORMATTER( UN_DataSize )

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 )
UN_NUMBER_FORMATTER( UN_StickyNoteIndex )


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

    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 )
    UN_INDEX_CLEARER( UN_StickyNoteIndex )

} // end: namespace UT


/// Differentiates between input and output ports.
using UN_PortKind = UNI_PortKind;

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

/// Graph serialization to UT_Options.
/// Using UT_UniquePtr<UT_Options> to return values, to indicate the ownership.
/// Using UT_UniquePtr<UT_OPtions> rather than UT_OptionsHolder because
/// it is more flexible: it's easier to further edit options (editing
/// UT_OptionsHolder is cumbersome), and it's easy to create UT_OptionsHolder
/// from the UT_UniquePtr, if need be.
using UN_Options = UT_Options;
using UN_OptionsPtr = UT_UniquePtr<UN_Options>;

/// Returns a non-null pointer to the UN_Options.
static inline UN_OptionsPtr
UNmakeOptions()
{
    return UN_OptionsPtr(new UT_Options());
}


#endif