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

#ifndef __APEX_FLEXIBLEDICT_H__
#define __APEX_FLEXIBLEDICT_H__

#include "APEX_API.h"
#include "APEX_Buffer.h"
#include "APEX_COW.h" // IWYU pragma: export
#include "APEX_Include.h"
#include "APEX_Types.h"
#include <GU/GU_Detail.h>
#include <UT/UT_Array.h>
#include <UT/UT_ArrayMap.h>
#include <UT/UT_ArrayStringMap.h>
#include <UT/UT_Assert.h>
#include <UT/UT_Base64.h>
#include <UT/UT_Optional.h>
#include <UT/UT_OptionEntry.h>
#include <UT/UT_Options.h>
#include <UT/UT_StringArray.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_StringStream.h>
#include <UT/UT_UniquePtr.h>
#include <UT/UT_ValArray.h>
#include <UT/UT_WorkBuffer.h>
#include <SYS/SYS_Types.h>

#include <new>
#include <typeindex>
#include <utility>

#include <stddef.h>

// For UT::ArraySet.
namespace UT
{
template <typename T>
struct DefaultClearer;

template <>
struct DefaultClearer<apex::APEX_TrackedArgument>
{
    static void clear(apex::APEX_TrackedArgument &v) { v = apex::APEX_TrackedArgument(); }
    static bool isClear(const apex::APEX_TrackedArgument &v) { return v.offset == -1; }
    static void clearConstruct(apex::APEX_TrackedArgument *p)
    {
        new ((void *)p) apex::APEX_TrackedArgument();
    }
    static const bool clearNeedsDestruction = true;
};

}; // namespace UT

namespace apex
{

class APEX_ParmDict;
using Dict = APEX_COWHandle<APEX_ParmDict>;
using DictArray = ApexArray<Dict>;

class APEX_Graph;
class APEX_Signature;

class APEX_API APEX_ParmDict
{
public:
    static constexpr UT_StringLit theTypeSuffix = ".__type__";

    APEX_ParmDict()
        : myBuffer(UTmakeUnique<APEX_Buffer>())
    {
    }

    explicit APEX_ParmDict(APEX_Buffer *external)
        : myExternalBuffer(external)
    {
    }

    APEX_ParmDict(const UT_OptionsHolder &opt)
        : myBuffer(UTmakeUnique<APEX_Buffer>())
    {
        mergeUtOptions(opt, true);
    }

    APEX_ParmDict(const APEX_ParmDict &other)
        : myExternalBuffer(other.myExternalBuffer)
        , myDataId(other.myDataId)
    {
        if (myExternalBuffer)
        {
            myMap = other.myMap;
        }
        else
        {
            myBuffer = UTmakeUnique<APEX_Buffer>();
            update(other, true);
        }
    }

    APEX_ParmDict &operator=(const APEX_ParmDict &other)
    {
        if (this == &other)
            return *this;

        myExternalBuffer = other.myExternalBuffer;
        myDataId = other.myDataId;

        if (myExternalBuffer)
        {
            myMap = other.myMap;
            myBuffer = nullptr;
        }
        else
        {
            myMap.clear();
            myBuffer = UTmakeUnique<APEX_Buffer>();
            update(other, true);
        }

        return *this;
    }

    void operator=(const UT_OptionsHolder &opt)
    {
        myMap.clear();
        myBuffer = UTmakeUnique<APEX_Buffer>();
        myExternalBuffer = nullptr;
        mergeUtOptions(opt, true);
    }

    bool contains(const UT_StringRef &key) const
    {
        return myMap.contains(key);
    }

    bool empty() const
    {
        return myMap.empty();
    }

    exint size() const
    {
        return myMap.size();
    }

    void bindGraphData(const APEX_Graph &graph, const APEX_PortIDRange &ports);
    APEX_TrackedArgument *getHandle(const UT_StringRef &key);
    const APEX_TrackedArgument *getHandle(const UT_StringRef &key) const;

    template <typename T>
    const T *get(const UT_StringRef &key) const
    {
        auto it = myMap.find(key);
        if (it.atEnd())
            return nullptr;
        return castArg<T>(&it->second);
    }

    template <typename T>
    T *get(const UT_StringRef &key)
    {
        auto it = myMap.find(key);
        if (it.atEnd())
            return nullptr;
        return castArg<T>(&it->second);
    }

    /// Helper function to extract a boolean value from either an int or bool dict value.
    const UT_Optional<Bool>
    getBoolOrInt(const UT_StringRef &key) const
    {
        if (const Bool *val = get<Bool>(key))
            return UTmakeOptional<Bool>(*val);
        else if (const Int *val = get<Int>(key))
            return UTmakeOptional<Bool>(*val != 0);

        return UT_NULLOPT;
    }

    template <typename T>
    T getValueOr(const UT_StringRef &key, T defValue) const
    {
        auto value = get<T>(key);
        if (value)
            return *value;
        return defValue;
    }

    template <typename T>
    void set(
            const UT_StringRef &key,
            const T &value,
            bool add_missing = true,
            bool allow_type_change = false,
            bool bump_data_id = true)
    {
        if (!isValidKey(key))
        {
            UT_WorkBuffer msg;
            msg.format("set() called with invalid key {}", key);
            UT_ASSERT_MSG(false, msg.buffer());
            return;
        }

        auto it = myMap.find(key);
        const APEX_TypeDefinitionBase *type_defn = findTypeDef<T>();
        if (!type_defn)
        {
            UT_ASSERT_MSG(false, "set() called with unregistered type");
            return;
        }
        APEX_TrackedArgument *arg;
        if (it.atEnd())
        {
            if (!add_missing)
                return;
            myMap[key] = appendTrackedArgument(type_defn);
            arg = &myMap[key];
        }
        else
        {
            arg = &it->second;
            if (type_defn != arg->type_defn)
            {
                if (!allow_type_change)
                    return;
                // playing it safe and not allowing type change on a buffer we
                // don't own
                // FIXME: currently not deallocating on the buffer if we change
                // the type of any entry
                else
                    it->second = appendTrackedArgument(type_defn);
            }
        }
        T &dst = *castArg<T>(arg);
        dst = value;
        arg->bumpDataId();
        if (bump_data_id)
            bumpDataId();
        // UTdebugPrint(key, arg->modCounter);
    }

    bool set(
            const UT_StringRef &key,
            const APEX_Argument &arg,
            bool add_missing = true,
            bool allow_type_change = false,
            bool force_update = false,
            bool bump_data_id = true,
            bool bump_data_id_on_conversion = true);

    bool set(
            const UT_StringRef &key,
            const APEX_TrackedArgument &arg,
            bool add_missing = true,
            bool allow_type_change = false,
            bool force_update = false,
            bool bump_data_id = true,
            bool bump_data_id_on_conversion = true);

    void renameEntry(const UT_StringRef &key, const UT_StringRef &newname);

    bool sharesBuffer(const APEX_ParmDict &other) const;

    // void setPyDict(void *pydict);

    // void writeToUtOptions(UT_Options &opt);
    // void writeToPyDict(void *pydict);

    // FIXME: No const-correctness here! As the buffer is pending a rewrite
    //  I won't clutter the current API
    // APEX_Buffer *buffer();
    APEX_Buffer *buffer() const;

    UT_StringArray compareDataIds(const APEX_ParmDict &other, bool check_missing = false);

    void update(
            const APEX_ParmDict &other,
            bool add_missing = false,
            bool allow_type_change = false,
            bool force_copy = false,
            UT_StringArray *changelist = nullptr,
            bool bump_data_id_on_conversion = true);
    void mergeUtOptions(
            const UT_OptionsHolder &opt_h,
            bool clear = false,
            bool add_missing = true,
            bool allow_type_change = true,
            const APEX_Signature *signature = nullptr);
    void updateUtOptions(
            UT_Options &opt_h,
            bool clear = false,
            bool include_geometry = false,
            bool include_typeinfo = true) const;
    void updateUtOptions(
            UT_OptionsHolder &opt_h,
            bool clear = false,
            bool include_geometry = false,
            bool include_typeinfo = true) const;

    UT_ArrayStringMap<APEX_TrackedArgument> &map() { return myMap; }
    const UT_ArrayStringMap<APEX_TrackedArgument> &map() const { return myMap; }

    void clear()
    {
        myMap.clear();
        if (!myExternalBuffer)
            myBuffer->clear();
        bumpDataId();
    }

    /// This function removes any previously set value such that subsequent
    /// execution will act as if set() were never called on that key. It will
    /// also reset the value back to its default state. However, the default
    /// value will continue to occupy memory in the buffer until the entire
    /// buffer is cleared using @ref clear().
    bool remove(const UT_StringRef &key);

    APEX_DataID dataId() const { return myDataId; }
    void bumpDataId() { myDataId = APEX_Buffer::nextDataId(); }
    void copyDataId(const APEX_ParmDict &other) { myDataId = other.dataId(); }

    static bool isValidKey(const UT_StringRef &key,
                           UT_StringHolder *err_msg=nullptr);

    int64 getMemoryUsage() const;

private:
    template <typename T>
    void setReinterpretFloatArray(
            const UT_StringRef &name,
            const UT_Array<Float> &src,
            bool add_missing)
    {
        static_assert(std::is_same_v<typename T::value_type, Float>);
        auto tmp = ApexArray<T>();
        tmp->append((T *)src.data(), src.size() / T::tuple_size);
        set<ApexArray<T>>(name, tmp, add_missing, false, false);
    }

    APEX_TrackedArgument appendTrackedArgument(const APEX_TypeDefinitionBase *type_defn)
    {
        APEX_Argument arg = buffer()->append(type_defn);
        return {{arg.buffer, arg.type_defn, arg.offset}, /*default*/};
    }

    UT_ArrayStringMap<APEX_TrackedArgument> myMap;
    UT_UniquePtr<APEX_Buffer> myBuffer;
    APEX_Buffer *myExternalBuffer = nullptr;
    APEX_DataID myDataId = APEX_Buffer::nextDataId();
};

// Overload for custom formatting with UTformat, must be in the same namespace
// as APEX_ParmDict in order to be found via ADL.
APEX_API size_t
UTformatBuffer(char *buffer, size_t buffer_size, const APEX_ParmDict &v);

// Overload for custom formatting of Dict with UTformat.
APEX_API size_t
UTformatBuffer(char *buffer, size_t buffer_size, const Dict &v);

// Specialization ApexArray<T> for custom formatting of ApexArray<Dict> with
// UTformat.
template <>
APEX_API size_t
UTformatBuffer<Dict>(
        char *buffer,
        size_t bufsize,
        const ApexArray<Dict> &v);

template <typename T>
static std::type_index
typeIndexT()
{
    return std::type_index(typeid(T));
}

void
setUtOption(
        UT_Options &opt,
        const UT_StringRef &key,
        const APEX_Argument &arg,
        bool include_geometry = false,
        bool include_typeinfo = true);

} // namespace apex

#endif // header guard