UN_GenericData.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_GenericData.h ( UN Library, C++)
 *
 * COMMENTS:
 *      Container for dynamically added data buffers of known types.
 */

#ifndef __UN_GenericData_h__
#define __UN_GenericData_h__

#include "UN_API.h"
#include "UN_DataBuffer.h"
#include "UN_Include.h"
#include <UT/UT_ArrayMap.h>
#include <variant>

class UN_DataMergeInfo;


// ============================================================================
/// Supported types for generic data buffers.
enum class UN_GenericBufferType
{
    String,         // UT_StringHolder
    StringArray,    // UT_StringArray
    Bool,           // bool (via UN_BoolDataBuffer)
    Int,            // exint
    Float,          // float
    Vector2D,       // UT_Vector2D
    Color           // UT_Color
};


// ============================================================================
/// A strongly-typed identifier for a generic data buffer.
/// Returned by UN_GenericData::addBuffer() and used to access
/// data in that buffer.

class UN_GenericBufferID
{
public:
                    UN_GenericBufferID() = default;
    explicit        UN_GenericBufferID(exint v) : myValue(v) {}

    bool            isValid() const     { return myValue >= 0; }
    exint           value() const       { return myValue; }
    explicit        operator bool() const { return isValid(); }

private:
    exint           myValue = -1;
};


// ============================================================================
/// A lightweight reference to a generic data buffer within a container.
/// Wraps a container pointer and a UN_GenericBufferID, forwarding
/// data access calls (set, get, steal, update) to the container.
///
/// Template parameters:
///   ContainerT - The data container type (e.g., UN_NodeData).
///   DataIDT    - The strongly-typed ID for data items (e.g., UN_NodeID).

template<typename ContainerT, typename DataIDT>
class UN_GenericDataBufferRef
{
public:
                    UN_GenericDataBufferRef() = default;
                    UN_GenericDataBufferRef(
                            ContainerT &container,
                            UN_GenericBufferID buf_id)
                        : myContainer(&container), myBufferID(buf_id) {}

    bool            isValid() const     { return myBufferID.isValid(); }
    explicit        operator bool() const { return isValid(); }

    UN_GenericBufferID bufferID() const { return myBufferID; }
    ContainerT &    container() const
                    {
                        UT_ASSERT(myContainer);
                        return *myContainer;
                    }

    /// Returns the data buffer type.
    UN_GenericBufferType bufferType(UN_GenericBufferID id) const
    {
        return myContainer->bufferType(myBufferID);
    }

    /// Returns the name of the data buffer.
    const UT_StringHolder & bufferName(UN_GenericBufferID id) const
    {
        return myContainer->bufferName(myBufferID);
    }

    /// Sets the data value for a given data ID.
    template<typename T>
    void setData(DataIDT id, T &&value)
    {
        myContainer->setGenericData(myBufferID, id, std::forward<T>(value));
    }

    /// Returns a const ref to the data value for a given data ID.
    template<typename T>
    const T & dataRef(DataIDT id) const
    {
        return myContainer->template genericDataRef<T>(myBufferID, id);
    }

    /// Returns a copy of the data value for a given data ID.
    template<typename T>
    T dataVal(DataIDT id) const
    {
        return myContainer->template genericDataVal<T>(myBufferID, id);
    }

    /// Moves the data value out of the buffer for a given data ID.
    template<typename T>
    T stealData(DataIDT id)
    {
        return myContainer->template stealGenericData<T>(myBufferID, id);
    }

    /// Updates the data value in-place via a callable.
    template<typename T, typename OP>
    void updateData(DataIDT id, const OP &op)
    {
        myContainer->template updateGenericData<T>(myBufferID, id, op);
    }

private:
    ContainerT         *myContainer = nullptr;
    UN_GenericBufferID  myBufferID;
};


// ============================================================================
/// Compile-time mapping from C++ type to UN_GenericBufferType enum value.
/// Used by template accessors to assert type correctness at runtime.

template<typename T>
struct UN_GenericBufferTraits;

template<>
struct UN_GenericBufferTraits<UT_StringHolder>
{ static constexpr auto type = UN_GenericBufferType::String; };

template<>
struct UN_GenericBufferTraits<UT_StringArray>
{ static constexpr auto type = UN_GenericBufferType::StringArray; };

template<>
struct UN_GenericBufferTraits<bool>
{ static constexpr auto type = UN_GenericBufferType::Bool; };

template<>
struct UN_GenericBufferTraits<exint>
{ static constexpr auto type = UN_GenericBufferType::Int; };

template<>
struct UN_GenericBufferTraits<float>
{ static constexpr auto type = UN_GenericBufferType::Float; };

template<>
struct UN_GenericBufferTraits<UT_Vector2D>
{ static constexpr auto type = UN_GenericBufferType::Vector2D; };

template<>
struct UN_GenericBufferTraits<UT_Color>
{ static constexpr auto type = UN_GenericBufferType::Color; };


// ============================================================================
/// Pairs a data buffer with its per-buffer default value.
/// When getDataRef() is called for an invalid index, the stored default is
/// returned instead of requiring callers to pass one at every call site.

template<typename T>
struct UN_GenericBuffer
{
    UN_DataBuffer<T>    myBuffer;
    T                   myDefault;

    explicit UN_GenericBuffer(UN_DataSize size = UN_DataSize(0))
        : myBuffer(size), myDefault{} {}

    template<typename D>
    UN_GenericBuffer(UN_DataSize size, D &&default_value)
        : myBuffer(size), myDefault(std::forward<D>(default_value)) {}
};


// ============================================================================
/// Variant holding all supported buffer types. No inheritance or virtual
/// dispatch — template accessors use std::get<>() for zero-overhead access.

using UN_GenericBufferVariant = std::variant<
    UN_GenericBuffer<UT_StringHolder>,  // String
    UN_GenericBuffer<UT_StringArray>,   // StringArray
    UN_GenericBuffer<bool>,             // Bool
    UN_GenericBuffer<exint>,            // Int
    UN_GenericBuffer<float>,            // Float
    UN_GenericBuffer<UT_Vector2D>,      // Vector2D
    UN_GenericBuffer<UT_Color>          // Color
>;


// ============================================================================
/// Container for dynamically added data buffers of known types.
///
/// Unlike the built-in buffers in UN_NodeData or UN_PortData, which are
/// fixed at compile time, this class allows buffers to be added on demand
/// at runtime by specifying a desired data type. Each buffer is identified
/// by a UN_GenericBufferID returned from addBuffer().
///
/// Data access uses template methods (setData<T>, getDataRef<T>) that compile
/// down to direct buffer access via std::get<>() — no virtual dispatch.
/// Lifecycle operations (addData, clearData, etc.) use std::visit.

class UN_API UN_GenericData
{
public:
    /// Adds a new named data buffer with a caller-specified default value.
    /// If a buffer with the same name already exists and the type matches,
    /// its existing ID is returned. If the name exists but the type
    /// conflicts, an invalid ID is returned.
    template<typename D>
    UN_GenericBufferID addBuffer(const UT_StringRef &name,
                                UN_GenericBufferType type,
                                const D &default_value,
                                UN_DataSize buffer_size)
    {
        // Check for an existing buffer with this name.
        auto it = myBufferIndexFromName.find( name );
        if( it != myBufferIndexFromName.end() )
        {
            if( myBuffers[it->second].myType == type )
                return UN_GenericBufferID( it->second );
            return UN_GenericBufferID(); // type conflict
        }

        auto id = addBuffer( name, type, buffer_size );
        if( !id )
            return id;

        std::visit( [&default_value]( auto &buf )
        {
            using T = std::decay_t<decltype(buf.myDefault)>;
            if constexpr( std::is_constructible_v<T, const D &> )
                buf.myDefault = T(default_value);
            else
                UT_ASSERT( !"Incompatible default value type" );
        }, myBuffers[id.value()].myBuffer );

        return id;
    }

    /// Returns the type of the buffer identified by the given ID.
    UN_GenericBufferType    bufferType(UN_GenericBufferID id) const
                                { return myBuffers[id.value()].myType; }

    /// Returns the number of generic buffers.
    exint                   numBuffers() const
                                { return myBuffers.size(); }

    /// Returns the ID of the buffer with the given name, or an invalid
    /// ID if no such buffer exists.
    UN_GenericBufferID      findBuffer( const UT_StringRef &name ) const;

    /// Returns the name of the buffer identified by the given ID.
    const UT_StringHolder & bufferName( UN_GenericBufferID id ) const
                                { return myBuffers[id.value()].myName; }

    /// Sets the data value for a given buffer and index.
    template<typename T>
    void setData( UN_GenericBufferID buf_id, UN_DataIndex index,
                  const T &value )
    {
        UT_ASSERT( myBuffers[buf_id.value()].myType
                   == UN_GenericBufferTraits<T>::type );
        auto &buf = std::get<UN_GenericBuffer<T>>(
                        myBuffers[buf_id.value()].myBuffer );
        UN_DataBufferUtils::setData( buf.myBuffer, index, value );
    }

    /// Sets the data value via move for a given buffer and index.
    template<typename T>
    void setData( UN_GenericBufferID buf_id, UN_DataIndex index,
                  T &&value )
    {
        UT_ASSERT( myBuffers[buf_id.value()].myType
                   == UN_GenericBufferTraits<std::decay_t<T>>::type );
        auto &buf = std::get<UN_GenericBuffer<std::decay_t<T>>>(
                        myBuffers[buf_id.value()].myBuffer );
        UN_DataBufferUtils::setData( buf.myBuffer, index,
                std::forward<T>(value) );
    }

    /// Returns a const ref to the data value for a given buffer and index.
    /// Returns the buffer's stored default for invalid indices.
    template<typename T>
    const T & getDataRef( UN_GenericBufferID buf_id,
                       UN_DataIndex index ) const
    {
        UT_ASSERT( myBuffers[buf_id.value()].myType
                   == UN_GenericBufferTraits<T>::type );
        auto &buf = std::get<UN_GenericBuffer<T>>(
                        myBuffers[buf_id.value()].myBuffer );
        return UN_DataBufferUtils::getDataRef( buf.myBuffer, index,
                buf.myDefault );
    }

    /// Returns a copy of the data value for a given buffer and index.
    /// Returns a copy of the buffer's stored default for invalid indices.
    /// Useful when cannot call getDataRef() for types that cannot 
    /// return by reference (eg, bool with bit-packed UN_DataBuffer<bool>).
    template<typename T>
    T getDataVal( UN_GenericBufferID buf_id, UN_DataIndex index ) const
    {
        UT_ASSERT( myBuffers[buf_id.value()].myType
                   == UN_GenericBufferTraits<T>::type );
        auto &buf = std::get<UN_GenericBuffer<T>>(
                        myBuffers[buf_id.value()].myBuffer );
        return UN_DataBufferUtils::getDataVal( buf.myBuffer, index,
                buf.myDefault );
    }

    /// Moves the data value out of a given buffer and index.
    /// Returns a copy of the buffer's stored default for invalid indices.
    template<typename T>
    T stealData( UN_GenericBufferID buf_id, UN_DataIndex index )
    {
        UT_ASSERT( myBuffers[buf_id.value()].myType
                   == UN_GenericBufferTraits<T>::type );
        auto &buf = std::get<UN_GenericBuffer<T>>(
                        myBuffers[buf_id.value()].myBuffer );
        return UN_DataBufferUtils::stealData(
                buf.myBuffer, index, buf.myDefault );
    }

    /// Updates the data value in-place via a callable.
    /// Usage: updateData<T>(buf_id, index, [](auto &v) { v = ...; });
    template<typename T, typename OP>
    void updateData( UN_GenericBufferID buf_id, UN_DataIndex index,
                     const OP &op )
    {
        UT_ASSERT( myBuffers[buf_id.value()].myType
                   == UN_GenericBufferTraits<T>::type );
        auto &buf = std::get<UN_GenericBuffer<T>>(
                        myBuffers[buf_id.value()].myBuffer );
        UN_DataBufferUtils::updateData( buf.myBuffer, index, op );
    }



    /// Adds a data slot at the given index to all generic buffers.
    void                    addData( UN_DataIndex index );

    /// Clears the data at the given index to defaults in all generic buffers.
    void                    clearData( UN_DataIndex index );

    /// Removes all data from all generic buffers.
    void                    removeAllData();

    /// Grows all generic buffers to the given minimum capacity if needed.
    void                    setCapacityIfNeeded( UN_DataSize min_capacity );

    /// Merges data from another UN_GenericData container.
    void                    mergeData( const UN_GenericData &src,
                                       const UN_DataMergeInfo &merge_info );

    /// @{ Returns true if all buffers have the expected size.
    bool                    isDataSizeConsistent(
                                UN_DataSize expected_size ) const;
    bool                    isDataSizeConsistent() const;
    /// @}

private:
    /// Adds a named buffer with a default-constructed default value.
    /// Used internally by the public template addBuffer() overload.
    UN_GenericBufferID      addBuffer(const UT_StringHolder &name,
                                UN_GenericBufferType type,
                                UN_DataSize buffer_size = UN_DataSize(0));

    /// 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             dataBufferSize() const;
    UN_DataSize             dataBufferSizeImpl() const;

private:
    /// Info about a generic buffer within this generic data container.
    struct BufferEntry
    {
        UT_StringHolder         myName;
        UN_GenericBufferType    myType;
        UN_GenericBufferVariant myBuffer;
    };

    /// The array of generic buffers added with addBuffer().
    UT_Array<BufferEntry>       myBuffers;

    /// Fast lookup from buffer name to index in myBuffers.
    UT_ArrayMap<UT_StringHolder, exint>  myBufferIndexFromName;
};

#endif