GA_AIFSharedDictTuple.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:        GA_AIFSharedDictTuple.h ( GA Library, C++)
 *
 * COMMENTS:    Attribute Interface class for options index table methods
 */

#ifndef __GA_AIFSharedDictTuple__
#define __GA_AIFSharedDictTuple__

#include "GA_API.h"

#include "GA_BlobContainer.h"
#include "GA_Types.h"

#include <UT/UT_Array.h>
#include <UT/UT_VectorTypes.h>
#include <UT/UT_Options.h>

#include <stddef.h>


class GA_Attribute;
class GA_Range;


/// Index type
/// WARNING: We assume that GA_DictIndexType and GA_BlobIndexType
/// are binary compatible, so do not change this!
typedef GA_BlobIndex    GA_DictIndexType;
#define GA_INVALID_DICT_INDEX           GA_DictIndexType(-1)

class GA_API GA_DictTableStatistics
{
public:
    GA_DictTableStatistics()
        : myCapacity(0)
        , myEntries(0)
    {
    }
    ~GA_DictTableStatistics() {}

    GA_Size     getEntries() const { return myEntries; }
    GA_Size     getCapacity() const { return myCapacity; }

    void        setEntries(GA_Size n) { myEntries = n; }
    void        setCapacity(GA_Size n) { myCapacity = n; }
private:
    GA_Size             myEntries, myCapacity;
};

/// @brief A specialization of GA_AIFDictTuple to access "shared strings"
///
/// This class provides the interface to access string table data.  Each
/// attribute type may provide this interface if it makes sense.
class GA_API GA_AIFSharedDictTuple
{
public:
             GA_AIFSharedDictTuple();
    virtual ~GA_AIFSharedDictTuple();

    /// Query information about the string storage.
    virtual bool        getStatistics(const GA_Attribute *attrib,
                                GA_DictTableStatistics &stats) const = 0;

    /// Compact the string storage
    virtual bool        compactStorage(GA_Attribute *attrib) const = 0;

    /// Extract data from the string table.  This will extract all the unique
    /// strings which are referenced by the attribute.
    /// The string handles are guaranteed to be in ascending order, but
    /// may or may not be contiguous.
    virtual bool        extractDicts(const GA_Attribute *attrib,
                                    UT_Array<UT_OptionsHolder> &options,
                                    UT_IntArray &handles) const = 0;

    /// Extract all of the unique string handles of the attribute.
    /// The string handles are guaranteed to be in ascending order, but
    /// may or may not be contiguous.
    virtual bool        extractHandles(const GA_Attribute *attrib,
                                       UT_IntArray &handles) const = 0;

public:
    // --------------------------------------------------------------
    // Interface to deal with string handles.
    // --------------------------------------------------------------

    /// Return the number of entries in the shared string table
    GA_Size     getTableEntries(const GA_Attribute *attrib) const
                {
                    GA_DictTableStatistics      stats;
                    if (attrib && getStatistics(attrib, stats))
                        return stats.getCapacity();
                    return 0;
                }

    /// It's possible that there are invalid handle indexes mixed with the
    /// valid handles.  When iterating over all the handles, you can call @c
    /// validateTableHandle() which will ensure that there's a string
    /// associated with the given handle.
    virtual GA_DictIndexType     validateTableHandle(const GA_Attribute *attrib,
                                        GA_DictIndexType index) const = 0;

    /// Get a string from the string table (without going through an attribute)
    virtual UT_OptionsHolder      getTableDict(const GA_Attribute *attrib,
                                        GA_DictIndexType handle) const = 0;

    /// Get the handle (index) corresponding to the given string, returning -1
    /// if none.
    virtual GA_DictIndexType    getTableHandle(const GA_Attribute *attrib,
                                       const UT_OptionsRef &opt) const = 0;

    /// GA_DictIndexType indices may not be contiguous, this method allows
    /// you to get a string given an ordered index.  Strings will be defined
    /// for all contiguous strings.  This may be an expensive operation, it's
    /// better to access strings by their index if possible.
    ///
    /// This method will return a NULL pointer past the end of the string table
    virtual UT_OptionsHolder     getTableOrderedDict(const GA_Attribute *a,
                                        exint index) const = 0;


    /// Replace a string in the shared string table with a new value.  Warning,
    /// it's possible that the table will "collapse" after the replacement.
    /// For example: @code
    ///   table := [ "foo", "bar" ]
    ///   table.replaceString(1, "foo") # Replace "bar" with "foo"
    ///   table := [ "foo" ]
    /// @endcode
    /// In the above example, all elements which originally referenced "bar"
    /// will now reference "foo".  This means that trying to swap two values
    /// will not work as expected.
    virtual bool                replaceTableDict(GA_Attribute *attrib,
                                        GA_DictIndexType handle,
                                        const UT_OptionsHolder &opt) const = 0;

    /// Class to iterate over all the options in the shared options table
    class GA_API iterator
    {
        public:
            iterator()
                : myAIF(NULL)
                , myAttrib(NULL)
                , myCount(0)
                , myIndex(0)
            {
            }
            ~iterator() {}
            iterator    &operator=(const iterator &src)
                        {
                            myAIF = src.myAIF;
                            myAttrib = src.myAttrib;
                            myDict = src.myDict;
                            myCount = src.myCount;
                            myIndex = src.myIndex;
                            return *this;
                        }
            bool        operator==(const iterator &src)
                        {
                            if (!src.myAIF)
                                return atEnd();
                            if (!myAIF)
                                return src.atEnd();
                            return myAIF == src.myAIF &&
                                    myAttrib == src.myAttrib &&
                                    myCount == src.myCount &&
                                    myIndex == src.myIndex;
                        }
            iterator    &operator++()           { advance(); return *this; }

            SYS_DEPRECATED_REPLACE(22.0, prefix increment operator)
            iterator    &operator++(int)        { advance(); return *this; }

            void        rewind()
                        {
                            myIndex = 0;
                            setupDict();
                        }
            bool        atEnd() const   { return myIndex >= myCount; }
            void        advance()
                        {
                            myIndex++;
                            setupDict();
                        }
            GA_Size              getCount() const       { return myCount; }
            GA_Size              getIndex() const       { return myIndex; }
            GA_DictIndexType     getHandle() const
                                    { return GA_DictIndexType(myIndex); }
            UT_OptionsHolder     getDict() const        { return myDict; }
        private:
            void setupDict()
            {
                while (myIndex < myCount)
                {
                    if (myAIF->validateTableHandle(myAttrib,GA_DictIndexType(myIndex)) >= 0)
                    {
                        myDict = myAIF->getTableDict(myAttrib, GA_DictIndexType(myIndex));
                        UT_ASSERT_P(!myDict.isEmpty());
                        break;
                    }
                    myIndex++;
                }
            }
            iterator(const GA_AIFSharedDictTuple *aif,
                        const GA_Attribute *a)
                : myAIF(aif)
                , myAttrib(a)
                , myIndex(0)
                , myCount(aif ? aif->getTableEntries(a) : 0)
            {
                setupDict();
            }

            const GA_AIFSharedDictTuple *myAIF;
            const GA_Attribute                  *myAttrib;
            UT_OptionsHolder                     myDict;
            GA_Size                              myCount;
            GA_Size                              myIndex;
            friend class GA_AIFSharedDictTuple;
    };

    iterator    begin(const GA_Attribute *a) const
                        { return iterator(this, a); }
    iterator    end() const
                        { return iterator(); }

protected:
    /// Add (or increment) reference to a string
    virtual GA_DictIndexType    addDictReference(GA_Attribute *attribute,
                                        const UT_OptionsHolder &opt) const = 0;
    /// Decrement reference to a handle
    virtual void                delHandleReference(GA_Attribute *attribute,
                                        GA_DictIndexType handle) const = 0;

public:
    // --------------------------------------------------------------
    // Tuple Interface
    // --------------------------------------------------------------

    /// Query the tuple size
    virtual int         getTupleSize(const GA_Attribute *attrib) const = 0;

    /// Set the tuple size
    virtual bool        setTupleSize(GA_Attribute *attrib, int size) const = 0;

    /// Get a string version to save writing marshalling code
    /// This lets you use this AIF in string-aware code and get sensible
    /// outputs.
    /// JSON normally has returns and tabs for formatting, onlyspaces will
    /// collapse these for a more compact output.
    UT_StringHolder      getString(const GA_Attribute *attrib, GA_Offset offset, int component=0, bool onlyspaces=false) const;

    /// Get a single string from the array for a single tuple of an element.
    virtual UT_OptionsHolder getDict(const GA_Attribute *attrib, GA_Offset ai,
                                int tuple_index=0) const;

    /// Get the handle from the array for a single tuple of an element
    virtual GA_DictIndexType    getHandle(const GA_Attribute *attrib,
                                        GA_Offset ai,
                                        int tuple_index=0) const = 0;

    /// Get the full tuple of indices for a single element
    virtual bool        getHandles(const GA_Attribute *attrib, GA_Offset ai,
                                GA_DictIndexType *handles,
                                int count, int start=0) const;

    /// Set a single component for a single element.
    virtual bool        setDict(GA_Attribute *attrib, GA_Offset ai,
                                const UT_OptionsHolder &opt, 
                                int tuple_index) const;
    /// Set a single component for a range of elements.
    virtual bool        setDict(GA_Attribute *attrib, const GA_Range &ai,
                                const UT_OptionsHolder &opt, 
                                int tuple_index) const;
    /// Set a single component for a single element.
    virtual bool        setHandle(GA_Attribute *attrib, GA_Offset ai,
                                GA_DictIndexType handle,
                                int tuple_index) const = 0;
    /// Set a single component for a range of elements.
    virtual bool        setHandle(GA_Attribute *attrib, const GA_Range &ai,
                                GA_DictIndexType handle,
                                int tuple_index) const;

    /// Set multiple components for a single element
    virtual bool        setHandles(GA_Attribute *attrib, GA_Offset ai,
                                const GA_DictIndexType *handles,
                                int count, int start=0) const;
    /// Set multiple components for a range of elements
    virtual bool        setHandles(GA_Attribute *attrib, const GA_Range &ai,
                                const GA_DictIndexType *handles,
                                int count, int start=0) const;
};

#endif