PDG_AttributeRef.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.
 *
 * COMMENTS:
 */

#ifndef __PDG_ATTRIBUTE_REF_H__
#define __PDG_ATTRIBUTE_REF_H__

#include "PDG_API.h"

#include "PDG_AttributeArray.h"
#include "PDG_AttributeGeometry.h"
#include "PDG_AttributeHolder.h"
#include "PDG_AttributePyObject.h"
#include "PDG_Types.h"

#include <UT/UT_StringHolder.h>
#include <UT/UT_WorkBuffer.h>

class PDG_AttributeOwner;
class PDG_Node;

/**
 * Base class for attribute references
 */
class PDG_API PDG_AttributeRef
{
public:
    /// Enumeration of possible errors that could occur when attempting to
    /// to construct an attribute reference
    enum Error
    {
        /// No error was specified, i.e. the ref is valid
        eErrorNone,

        /// An unspecified error occured - the ref is invalid
        eErrorUnspecified,

        /// The requested attribute was not found - the ref is invalid
        eErrorNotFound,

        /// The requested attribute was a readonly when attempting to create 
        /// a RW ref - the ref is invalid
        eErrorReadOnly,

        /// The requested attribute is internal, and therefore cannot be
        /// removed by user code
        eErrorInternal,

        /// The entire attribute map is read only
        eErrorAttributesReadOnly,

        /// The requested attribute type did not match the attribute - the
        /// ref is invalid
        eErrorTypeConflict,

        /// The requested attribute is static and was not upgraded to dynamic
        eErrorTypeUpgrade,

        /// The requested attribute already exists, but the API call was 
        /// instruct to not overwrite existing values
        eErrorOverwrite,

        /// The ref is uninitialized and needs to be created at a later point
        eErrorUninitialized,

        /// The attribute doesn't support a flag that was passed to a SetFlag
        /// call
        eErrorInvalidFlag,
    };

public:
    explicit PDG_AttributeRef(const UT_StringHolder& name,
                              const PDG_AttributeOwner* owner,
                              Error error=eErrorNone)
        : myName(name)
        , myOwner(owner)
        , myError(error)
    {
    }

    /// Returns true if the handle is valid
    inline          operator bool() const
    {
        return isValid();
    }

    /// Returns true if the handle is valid
    inline bool     isValid() const
    {
        return (myError == eErrorNone);
    }

    /// Returns the error state of the handle
    inline Error    error() const
    {
        return myError;
    }

    /// Returns the name of the attribute referenced by this attrib ref
    inline const UT_StringHolder&
                    name() const
    {
        return myName;
    }

    /// Returns the PDG_AttributeOwner that owns the underlying attribute
    const PDG_AttributeOwner*
                    owner() const
    {
        return myOwner;
    }

    /// Returns false and Writes an attribute error message into the buffer if
    /// an error exists, or returns trues and does not modify the buffer if no
    /// error has been recorded.
    bool            validate(UT_WorkBuffer& buffer) const;

    /// Same as above, except the attribute error is reported on the specified
    /// node instead of returned as a buffer, if an error has occured. The
    /// method still returns true if no error has occured, and false if one
    /// has.
    /// 
    /// The report_errors argument is provided as a convenience, to make it 
    /// possible to parametrically skip error reporting
    bool            validate(const PDG_Node* node,
                             bool report_errors=true,
                             bool as_warning=false) const;

    /// Writes an attribute error format message to the buffer, based on the
    /// supply error, attrib name and optional work item. Returns True if no
    /// error is detected, or false if an error occured.
    static bool     attributeError(UT_WorkBuffer& buffer,
                                   Error error,
                                   const UT_StringHolder& attrib_name,
                                   const PDG_AttributeOwner* owner=nullptr);

    /// Emits events when the attribute is modified
    static void     attributeModified(
                        const PDG_AttributeOwner* owner,
                        PDG_AttributeType attrib_type,
                        const UT_StringHolder& attrib_name);

protected:
    UT_StringHolder             myName;
    const PDG_AttributeOwner*   myOwner;
    Error                       myError;
};

/**
 * Base class for templated attribute references
 */
template <typename Attribute, typename Holder>
class PDG_API_TMPL PDG_AttributeRefT : public PDG_AttributeRef
{
public:
    using Self = PDG_AttributeRefT<Attribute, Holder>;

public:
    explicit PDG_AttributeRefT(Holder* holder,
                               const UT_StringHolder& name,
                               const PDG_AttributeOwner* owner,
                               PDG_AttributeRef::Error error=eErrorNone)
        : PDG_AttributeRef(name, owner, error)
        , myHolder(holder)
    {
    }

    /// Returns the underlying attribute holder
    inline Holder*                  holder() const
    {
        return myHolder;
    }

    /// Returns a const pointer to the underlying attribute instance
    inline const Attribute*         attribute() const
    {
        return myHolder->template attribute<const Attribute>();
    }

    /// Returns a const pointer to the underlying attribute instance,
    /// casted to the specified type
    template <typename T> const T*  attributeT() const
    {
        return myHolder->template attribute<const T>();
    }

    /// Returns a const pointer to the underlying attribute instance
    inline const Attribute*         operator->() const
    {
        return attribute();
    }

    /// Returns true if the contained attribute has any data
    inline bool                     hasData() const
    {
        return myHolder->template hasData<Attribute>();
    }

    /// Returns true if the contained attribute holder owns its data
    inline bool                     isOwner() const
    {
        return myHolder->isOwner();
    }

    /// Returns the type of the contained attribute
    inline PDG_AttributeType        type() const
    {
        return myHolder->type();
    }

    /// Returns the flags on the contained holder
    inline uint16                   flags() const
    {
        return myHolder->flags();
    }

    /// Returns true if the contained holder has any flags set
    inline bool                     hasAnyFlags() const
    {
        return myHolder->hasAnyFlags();
    }

    /// Returns true if the contained holder has the specified flag set
    inline bool                     hasFlag(PDG_AttributeFlag flag) const
    {
        return myHolder->hasFlag(flag);
    }

    /// Returns true if the contained holder has all of the specified flags set
    inline bool                     hasFlags(uint16 flags) const
    {
        return myHolder->hasFlags(flags);
    }

    /// Returns true if the contained holder has any of the specified flags set
    inline bool                     hasAnyFlags(uint16 flags) const
    {
        return myHolder->hasAnyFlags(flags);
    }

    /// Returns true if the attribute is numeric
    inline bool                     isNumeric() const
    {
        return (myHolder->type() == PDG_AttributeType::eIntegerArray) ||
               (myHolder->type() == PDG_AttributeType::eFloatArray);
    }

    /// Returns true if the attribute is an array
    inline bool                     isArray() const
    {
        return (myHolder->type() <= PDG_AttributeType::eFileArray);
    }

    /// Casts the value contained in the attribute at the particular index to a
    /// numeric value, by looking up the value with the query string. Falls
    /// a regular cast if query strings aren't supported
    inline PDG_AttributeCast        asNumber(fpreal& number,
                                             const UT_StringHolder& query,
                                             int index,
                                             bool has_component) const
    {
        if (myHolder->type() == PDG_AttributeType::ePythonObject)
        {
            if (!has_component)
                index = -1;
            return myHolder->template attribute<PDG_AttributePyObject>()->query(
                number, query, index);
        }
        return asNumber(number, index);
    }

    /// Casts the value contained in the attribute at the particular index to a
    /// numeric value, if possible.
    inline PDG_AttributeCast        asNumber(fpreal& number, int index) const
    {
        if (myHolder->type() == PDG_AttributeType::eIntegerArray)
        {
            PDG_AttributeInteger::Data temp;
            if (myHolder->template attribute<PDG_AttributeInteger>()->value(
                    temp, index))
            {
                number = temp;
                return PDG_AttributeCast::eSuccess;
            }

            return PDG_AttributeCast::eErrorBounds;
        }
        else if (myHolder->type() == PDG_AttributeType::eFloatArray)
        {
            if (myHolder->template attribute<PDG_AttributeFloat>()->value(
                number, index))
            {
                return PDG_AttributeCast::eSuccess;
            }

            return PDG_AttributeCast::eErrorBounds;
        }

        return PDG_AttributeCast::eErrorType;
    }

    /// Casts the value contained in the attribute to a PDG_File object. Only
    /// valid for string, file and PyObject attribute types
    inline PDG_AttributeCast        asFile(
                                        PDG_File& file,
                                        int index,
                                        const UT_StringHolder& tag = 
                                            UT_StringHolder::theEmptyString,
                                        PDG_File::Hash hash = 0,
                                        bool own = false) const
    {
        UT_StringHolder file_path;
        UT_StringHolder file_tag = tag;
        PDG_File::Hash file_hash = hash;
        
        switch (myHolder->type())
        {
            case PDG_AttributeType::ePythonObject:
            {
                if (!myHolder->template attribute<PDG_AttributePyObject>()->str(
                        file_path))
                {
                    return PDG_AttributeCast::eErrorBounds;
                }

                break;
            }

            case PDG_AttributeType::eStringArray:
            {
                if (!myHolder->template attribute<PDG_AttributeString>()->value(
                        file_path, index))
                {
                    return PDG_AttributeCast::eErrorBounds;
                }

                break;
            }

            case PDG_AttributeType::eFileArray:
            {
                PDG_AttributeFile::Data temp;
                if (myHolder->template attribute<PDG_AttributeFile>()->value(
                        temp, index))
                {
                    file_path = temp.data();

                    if (file_tag.isEmpty())
                        file_tag = temp.tag();

                    if (!file_hash)
                        file_hash = temp.hash();

                    break;
                }

                return PDG_AttributeCast::eErrorBounds;
            }

            default:
                return PDG_AttributeCast::eErrorType;
        }

        file = PDG_File(file_path, file_tag, file_hash, own);
        return PDG_AttributeCast::eSuccess;
    }

    /// Casts the value contained in the attribute at the particular index to a
    /// string value, by looking up the value with the query string. Falls
    /// a regular cast if query strings aren't supported
    inline PDG_AttributeCast        asString(UT_WorkBuffer& buffer,
                                             const UT_StringHolder& query,
                                             int index,
                                             int pad,
                                             bool has_component) const
    {
        if (myHolder->type() == PDG_AttributeType::ePythonObject)
        {
            if (!has_component)
                index = -1;
            return myHolder->template attribute<PDG_AttributePyObject>()->query(
                buffer, query, index);
        }
        return asString(buffer, index, pad);
    }

    /// Casts the value contained in the attribute at the particular index to a
    /// string value, if possible.
    inline PDG_AttributeCast        asString(UT_WorkBuffer& buffer,
                                             int index,
                                             int pad=0) const
    {
        switch (myHolder->type())
        {
            case PDG_AttributeType::eIntegerArray:
            {
                PDG_AttributeInteger::Data temp;
                if (myHolder->template attribute<PDG_AttributeInteger>()->value(
                        temp, index))
                {
                    buffer.sprintf("%0*" SYS_PRId64, pad, temp);
                    return PDG_AttributeCast::eSuccess;
                }
                return PDG_AttributeCast::eErrorBounds;
            }

            case PDG_AttributeType::eFloatArray:
            {
                PDG_AttributeFloat::Data temp;
                if (myHolder->template attribute<PDG_AttributeFloat>()->value(
                        temp, index))
                {
                    // If a padding was specified, round to the nearest int and
                    // pad the integer value. This is the same behavior as the
                    // padzero() HScript function. Otherwise, format the value
                    // as-is.
                    if (pad > 0)
                        buffer.sprintf("%0*d", pad, (int)SYSrint(temp));
                    else
                        buffer.sprintf("%g", temp);
                    return PDG_AttributeCast::eSuccess;
                }
                return PDG_AttributeCast::eErrorBounds;
            }

            case PDG_AttributeType::eStringArray:
            {
                PDG_AttributeString::Data temp;
                if (myHolder->template attribute<PDG_AttributeString>()->value(
                        temp, index))
                {
                    buffer.sprintf("%s", temp.c_str());
                    return PDG_AttributeCast::eSuccess;
                }
                return PDG_AttributeCast::eErrorBounds;
            }

            case PDG_AttributeType::eFileArray:
            {
                PDG_AttributeFile::Data temp;
                if (myHolder->template attribute<PDG_AttributeFile>()->value(
                        temp, index))
                {
                    buffer.sprintf("%s", temp.data().c_str());
                    return PDG_AttributeCast::eSuccess;
                }
                return PDG_AttributeCast::eErrorBounds;
            }

            case PDG_AttributeType::ePythonObject:
            {
                UT_StringHolder temp;
                if (myHolder->template attribute<PDG_AttributePyObject>()->str(
                        temp))
                {
                    buffer.sprintf("%s", temp.c_str());
                    return PDG_AttributeCast::eSuccess;
                }
                return PDG_AttributeCast::eErrorBounds;
            }

            default:
                return PDG_AttributeCast::eErrorType;
        }
    }

    /// Prints the values contained in the attribute to space-separated string
    inline PDG_AttributeCast        asStringValues(UT_WorkBuffer& buffer,
                                                   int pad=0) const
    {
        switch (myHolder->type())
        {
            case PDG_AttributeType::eIntegerArray:
            {
                auto&& values = myHolder->template
                    attribute<PDG_AttributeInteger>()->values();
                for (auto&& value : values)
                    buffer.appendSprintf("%0*" SYS_PRId64 " ", pad, value);
                buffer.removeTrailingSpace();
                return PDG_AttributeCast::eSuccess;
            }

            case PDG_AttributeType::eFloatArray:
            {
                auto&& values = myHolder->template
                    attribute<PDG_AttributeFloat>()->values();
                for (auto&& value : values)
                {
                    // If a padding was specified, round to the nearest int and
                    // pad the integer value. This is the same behavior as the
                    // padzero() HScript function. Otherwise, format the value
                    // as-is.
                    if (pad > 0)
                        buffer.appendSprintf("%0*d ", pad, (int)SYSrint(value));
                    else
                        buffer.appendSprintf("%g ", value);
                }

                buffer.removeTrailingSpace();
                return PDG_AttributeCast::eSuccess;
            }

            case PDG_AttributeType::eStringArray:
            {
                auto&& values = myHolder->template
                    attribute<PDG_AttributeString>()->values();
                for (auto&& value : values)
                {
                    UT_String wrap(value);
                    wrap.protectString();
                    buffer.appendSprintf("%s ", wrap.buffer());
                }

                buffer.removeTrailingSpace();
                return PDG_AttributeCast::eSuccess;
            }

            case PDG_AttributeType::eFileArray:
            {
                auto&& values = myHolder->template
                    attribute<PDG_AttributeFile>()->values();
                for (auto&& value : values)
                {
                    UT_String wrap(value.data());
                    wrap.protectString();
                    buffer.appendSprintf("%s ", wrap.buffer());
                }

                buffer.removeTrailingSpace();
                return PDG_AttributeCast::eSuccess;
            }

            case PDG_AttributeType::ePythonObject:
            {
                UT_StringHolder value;
                if (myHolder->template attribute<PDG_AttributePyObject>()->str(
                        value))
                {
                    UT_String wrap(value);
                    wrap.protectString();
                    buffer.appendSprintf("%s", wrap.buffer());
                    return PDG_AttributeCast::eSuccess;
                }
                return PDG_AttributeCast::eErrorType;
            }

            default:
                return PDG_AttributeCast::eErrorType;
        }
    }

    /// Returns the size of the data stored in the attribute
    inline int                      size() const
    {
        switch (myHolder->type())
        {
            case PDG_AttributeType::eIntegerArray:
            {
                return myHolder->template attribute<
                    PDG_AttributeInteger>()->size();
            }

            case PDG_AttributeType::eFloatArray:
            {
                return myHolder->template attribute<
                    PDG_AttributeFloat>()->size();
            }

            case PDG_AttributeType::eStringArray:
            {
                return myHolder->template attribute<
                    PDG_AttributeString>()->size();
            }

            case PDG_AttributeType::eFileArray:
            {
                return myHolder->template attribute<
                    PDG_AttributeFile>()->size();
            }

            case PDG_AttributeType::ePythonObject:
            {
                return myHolder->template attribute<
                    PDG_AttributePyObject>()->size();
            }

            case PDG_AttributeType::eGeometry:
            {
                return myHolder->template attribute<
                    PDG_AttributeGeometry>()->size();
            }

            default:
                return 0;
        }
    }

protected:
    Holder*                         myHolder;
};

/**
 * Read-only, const attribute ref
 */
template <typename Attribute>
class PDG_API_TMPL PDG_ROAttributeRef :
    public PDG_AttributeRefT<Attribute, const PDG_AttributeHolder>
{
public:
    using Base = PDG_AttributeRefT<Attribute, const PDG_AttributeHolder>;
    using Base::Base;
};

/**
 * Read/write attribute ref that permits modifications of holder flags as
 * well as non-const access to the underlying data. Accessing the attribute
 * using either the named accessor or the -> overload will result in a deep
 * copy + ownership being taken, if the data is not already owned by the
 * holder.
 */
template <typename Attribute>
class PDG_API_TMPL PDG_RWAttributeRef :
    public PDG_AttributeRefT<Attribute, PDG_AttributeHolder>
{
public:
    using Base = PDG_AttributeRefT<Attribute, PDG_AttributeHolder>;
    using Self = PDG_RWAttributeRef<Attribute>;

    /// Constructs an uninitialized RW ref
    PDG_RWAttributeRef(const UT_StringHolder& name,
                       const PDG_AttributeOwner* owner)
        : Base(nullptr, name, owner, PDG_AttributeRef::eErrorUninitialized)
        , myModified(false)
    {
    }

    /// Constructs a ref that can modify attribute data. We store the work
    /// item so we can emit events.
    PDG_RWAttributeRef(PDG_AttributeHolder* holder,
                       const UT_StringHolder& name,
                       const PDG_AttributeOwner* owner,
                       PDG_AttributeRef::Error error=PDG_AttributeRef::eErrorNone)
        : Base(holder, name, owner, error)
        , myModified(false)
    {
    }

    /// Explicitly defined copy constructor, since we don't want to copy the
    /// myModified flag from the source reference. Doing so would mean that
    /// we'd potentially by emitting an extra data change event on destruction.
    PDG_RWAttributeRef(const Self& other)
        : Base(other)
        , myModified(false)
    {
    }

    /// Explicitly defined move constructor, since a copy constructor has been
    /// defined. When moving a ref we do want to preserve the myModified flag,
    /// unlike in the copy constructor.
    PDG_RWAttributeRef(Self&& other)
        : Base(std::move(other))
        , myModified(other.myModified)
    {
        other.myModified = false;
    }

    /// Emits data changed events if this attribute ref recorded a modification
    ~PDG_RWAttributeRef()
    {
        emitEvents();
    }

    /// Explicitly defined copy assignment operator, since the copy constructor
    /// is defined.
    Self&               operator=(const Self& other)
    {
        if (this != &other)
        {
            emitEvents();
        
            myModified = false;
            Base::operator=(other);
        }

        return *this;
    }

    /// Explicitly defined move assignment operator, since the move constructor
    /// is defined.
    Self&               operator=(Self&& other)
    {
        if (this != &other)
        {
            emitEvents();

            myModified = other.myModified;
            other.myModified = false;

            Base::operator=(std::move(other));
        }

        return *this;
    }

    /// Emits pending events from the ref
    inline void         emitEvents()
    {
        if (Base::myOwner && myModified)
            Base::attributeModified(Base::myOwner, Base::type(), Base::myName);

        myModified = false;
    }

    /// Clears any pending events
    inline void         clearEvents()
    {
        myModified = false;
    }

    /// Returns a non-const pointer to the underlying attribute instance. This
    /// induces a copy if the attribute is not already owned, and counts as a
    /// modification for the purpose of event handling.
    inline Attribute*   attribute()
    {
        Base::myHolder->own();
        Base::myHolder->setIsChanged(true);

        myModified = true;
        return Base::myHolder->template attribute<Attribute>();
    }

    /// Returns a non-const pointer to the underlying attribute instance
    inline Attribute*   operator->()
    {
        return attribute();
    }

    /// Sets the specific flag on or off, based on the set arugment, an
    /// returns whether or not the flag was changed.
    inline typename Base::Error
                        setFlag(PDG_AttributeFlag flag,
                                bool set,
                                bool& changed)
    {
        if (!Base::isValid())
            return Base::error();

        if (Base::myOwner && !Base::myOwner->isAttribFlagValid(flag))
            return Base::eErrorInvalidFlag;

        changed = Base::myHolder->setFlag(flag, set);
        return Base::eErrorNone;
    }

    /// Sets the specific flag on or off
    inline typename Base::Error
                        setFlag(PDG_AttributeFlag flag, bool set)
    {
        bool discard;
        return setFlag(flag, set, discard);
    }

    /// Directly sets the flag bits to the specified flags
    inline typename Base::Error
                        setFlags(uint16 flags, bool& changed)
    {
        if (!Base::isValid())
            return Base::error();

        if (Base::myOwner && !Base::myOwner->areAttribFlagsValid(flags))
            return Base::eErrorInvalidFlag;

        changed = Base::myHolder->setFlags(flags);
        return Base::eErrorNone;
    }

    /// Sets all flags
    inline typename Base::Error
                        setFlags(uint16 flags)
    {
        bool discard;
        return setFlags(flags, discard);
    }

    /// Truncates the array stored in the attribute
    inline void         truncate(int length)
    {
        switch (Base::myHolder->type())
        {
            case PDG_AttributeType::eIntegerArray:
            {
                return Base::myHolder->template attribute<
                    PDG_AttributeInteger>()->truncate(length);
            }

            case PDG_AttributeType::eFloatArray:
            {
                return Base::myHolder->template attribute<
                    PDG_AttributeFloat>()->truncate(length);
            }

            case PDG_AttributeType::eStringArray:
            {
                return Base::myHolder->template attribute<
                    PDG_AttributeString>()->truncate(length);
            }

            case PDG_AttributeType::eFileArray:
            {
                return Base::myHolder->template attribute<
                    PDG_AttributeFile>()->truncate(length);
            }

            default:
                return;
        }
    }

private:
    bool                myModified;
};

#endif