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

#ifndef __GA_AIFSharedDictArray__
#define __GA_AIFSharedDictArray__

#include "GA_API.h"

#include "GA_BlobContainer.h"
// Following for the Index Type
#include "GA_AIFSharedDictTuple.h"
#include "GA_Types.h"

#include <UT/UT_Array.h>

#include <stddef.h>

class GA_Attribute;
class GA_Range;

/// @brief A specialization of GA_AIFDictArray 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_AIFSharedDictArray
{
public:
             GA_AIFSharedDictArray();
    virtual ~GA_AIFSharedDictArray();

    /// 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> &strings,
                                    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;

    /// @{
    /// Return the length of longest array
    virtual exint       findMaximumArrayLength(const GA_Attribute *attrib) 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 &string) const = 0;

    /// GA_DictIndexType indices may not be contiguous, this method allows
    /// you to get a string given an ordered index.  Dicts 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.replaceDict(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 &string) const = 0;

    /// Class to iterate over all the strings in the shared string 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)
                            {
                                myDict = myAIF->getTableDict(myAttrib,
                                                GA_DictIndexType(myIndex));
                                if (myDict)
                                    break;
                                myIndex++;
                            }
                        }
            iterator(const GA_AIFSharedDictArray *aif,
                        const GA_Attribute *a)
                : myAIF(aif)
                , myAttrib(a)
                , myIndex(0)
                , myCount(aif ? aif->getTableEntries(a) : 0)
            {
                setupDict();
            }

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

    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 &string) const = 0;
    /// Decrement reference to a handle
    virtual void                delHandleReference(GA_Attribute *attribute,
                                        GA_DictIndexType handle) const = 0;

public:
    // --------------------------------------------------------------
    // Array Interface
    // --------------------------------------------------------------

    virtual int         getTupleSize(const GA_Attribute *attrib) const = 0;
    virtual bool        setTupleSize(GA_Attribute *attrib, int size) const = 0;

    virtual GA_Storage  getStorage(const GA_Attribute *attrib) const = 0;

    /// Get a single string from the array for a single tuple of an element.
    virtual void                 getDict(const GA_Attribute *attribute, GA_Offset offset, UT_Array<UT_OptionsHolder> &strings) const = 0;

    /// Get the handle from the array for a single tuple of an element
    virtual void                 getDictIndex(const GA_Attribute *attribute, GA_Offset offset, UT_Array<GA_DictIndexType> &indices) const = 0;

    /// Set a single component for a single element.
    virtual void                 setDict(GA_Attribute *attribute, GA_Offset offset, const UT_Array<UT_OptionsHolder> &strings) const = 0;
    /// Set a single component for a range of elements.
    virtual void                 setDictIndex(GA_Attribute *attribute, GA_Offset offset, const UT_Array<GA_DictIndexType> &indices) const = 0;

    /// Return the size of the array for the GA_Offset
    virtual exint       arraySize(const GA_Attribute *atr, GA_Offset off) const = 0;

    /// Get a UT_Array<UT_OptionsHolder> at specific GA_Offset. This is an 
    /// alias for getDict() so that we can treat this AIF similar to
    /// GA_AIFNumericArray.
    bool get(const GA_Attribute *attrib, GA_Offset o, UT_Array<UT_OptionsHolder> &v) const
    {
        getDict(attrib, o, v);
        return true;
    }

    /// Set a UT_DictArray at specific GA_Offset. This is an alias for
    /// setDict() so that we can treat this AIF similar to
    /// GA_AIFNumericArray.
    bool set(GA_Attribute *attrib, GA_Offset o, const UT_Array<UT_OptionsHolder> &v) const
    {
        setDict(attrib, o, v);
        return true;
    }

};

#endif