UT_Options.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:        UT_Options.h (C++, Utility Library)
 *
 * COMMENTS:    This is a smaller, faster, more type-safe version of
 *              UT_OptionFile. The reason UT_OptionFile was not simply
 *              re-implemented is that when saving and loading UT_OptionFiles,
 *              no information about the type of each option is saved. This
 *              implementation writes out the type of each data item.
 *
 */

#ifndef _UT_OPTIONS_H_
#define _UT_OPTIONS_H_

#include "UT_API.h"
#include "UT_SmallObject.h"
#include "UT_StringArray.h"
#include "UT_StringHolder.h"
#include "UT_ArrayStringMap.h"
#include "UT_UniquePtr.h"
#include "UT_SharedPtr.h"
#include "UT_VectorTypes.h"
#include "UT_ValArray.h"
#include <SYS/SYS_TypeTraits.h>
#include <iosfwd>
#include <string>
#include <memory>


class UT_IStream;
class UT_JSONValue;
class UT_JSONValueMap;
class UT_JSONParser;
class UT_JSONWriter;
class UT_WorkBuffer;

// NOTE: The values of UT_OptionType are saved to disk, thus we should NOT 
//       reorder these options if we want to maintain compatibility with older
//       saved options.
enum UT_OptionType
{
    UT_OPTION_INVALID = -1,
    UT_OPTION_INT = 0,
    UT_OPTION_BOOL = 1,
    UT_OPTION_FPREAL = 2,
    UT_OPTION_STRING = 3,
    UT_OPTION_VECTOR2 = 4,
    UT_OPTION_VECTOR3 = 5,
    UT_OPTION_VECTOR4 = 6,
    UT_OPTION_QUATERNION = 7,
    UT_OPTION_MATRIX3 = 8,
    UT_OPTION_MATRIX4 = 9,
    UT_OPTION_UV = 10,
    UT_OPTION_UVW = 11,
    UT_OPTION_STRINGRAW = 12,   // used by getPyOptionString
    UT_OPTION_INTARRAY = 13,    // Array of integers
    UT_OPTION_FPREALARRAY = 14, // Array of float/double
    UT_OPTION_MATRIX2 = 15,
    UT_OPTION_STRINGARRAY = 16,
    UT_OPTION_DICT = 17,        // Option of option
    UT_OPTION_DICTARRAY = 18,

    UT_OPTION_NUM_TYPES // Sentinal
};

/// String formatting options for getOptionString
enum UT_OptionFormat
{
    UT_OPTFMT_DISPLAY,          // Format for display
    UT_OPTFMT_PYTHON,           // Format for python
    UT_OPTFMT_VEX,              // Format for VEX arguments
    UT_OPTFMT_NUM_TYPES
};

class UT_OptionsHolder;
class UT_OptionEntry;
using UT_OptionEntryPtr = UT_UniquePtr<UT_OptionEntry>;

/// A map of string to various well defined value types
class UT_API UT_Options
{
private:
    /// Storage type for the option map
    using MapType = UT_ArrayStringMap<UT_OptionEntryPtr>;

public:
    // Default constructor (empty options)
    UT_Options();
    // Copy c-tor
    UT_Options(const UT_Options &src);
    virtual ~UT_Options();

    /// Variadic constructor that allows addition of options during
    /// construction.  Using this option requires very careful coding (as does
    /// all variadic coding).  For example, there is no type checking of
    /// variadic arguments.  If there are floating point arguments, they @b
    /// must be specified as double (i.e. Not "0", but rather "0.0").
    /// Type tokens expected are:
    ///   - "int"               @n A single @b int value follows
    ///   - "int64"             @n A single @b int64 value follows
    ///   - "bool"              @n A single @b int follows
    ///   - "float"             @n A single @b double follows
    ///   - "string"            @n A single string value follows
    ///   - "vector2"           @n Two (2) double arguments follow
    ///   - "vector3"           @n Three (3) double arguments follow
    ///   - "vector4"           @n Four (4) double arguments follow
    ///   - "quaternion"        @n Four (4) double arguments follow
    ///   - "matrix2"           @n Four (4) double arguments follow
    ///   - "matrix3"           @n Nine (9) double arguments follow
    ///   - "matrix4"           @n Sixteen (16) double arguments follow
    ///   - "uv"                @n Two (2) double arguments follow
    ///   - "uvw"               @n Three (3) double arguments follow
    ///   - "stringraw"         @n A single string value follows
    ///   - "int[N]"            @n
    ///         @c N @b int values follow (creating an integer array).
    ///         Replace @c N with the actual value (of course).
    ///         No spaces may occur in the type name.
    ///   - "int64[N]"          @n
    ///         @c N @b int64 values follow (creating an integer array).
    ///         Replace @c N with the actual value (of course).
    ///         No spaces may occur in the type name.
    ///   - "float[N]"          @n
    ///         @c N @b double values follow (creating a float array).
    ///         Replace @c N with the actual value (of course).
    ///         No spaces may occur in the type name.
    ///    - "string[N]"        @n
    ///         @c N @b string values follow (creating a string array).
    ///         Replace @c N with the actual value (of course).
    ///         No spaces may occur in the type name.
    ///
    /// Special type tokens
    ///   - "i_vector2", "i_vector3", "i_vector4", @n
    ///         A single @b double is used to set all components of the vector
    ///   - "i_quaternion"              @n
    ///         A single @b double is used to set all components of the vector
    ///   - "i_uv", "i_uvw"             @n
    ///         A single @b double is used to set all components of the vector
    ///   - "i_matrix3", "i_matrix4"    @n
    ///         A single @b double is used to set the diagonal of the matrix3.
    ///   - "i_int[N]"          @n
    ///         A single @b int64 is used to set all components of the array
    ///   - "i_float[N]"        @n
    ///         A single @b double is used to set all components of the array
    ///
    /// The option name should follow the type specifier (separated by a single
    /// space).
    ///
    /// A nullptr keyword determines the end of the options.
    ///
    /// Examples: @code
    ///   UT_Options    options("int ival",     0,
    ///                         "int64 i64val", (int64)5,
    ///                         "bool toggle",  (int)1,
    ///                         "float fval",   (fpreal64)0,
    ///                         "vector3 P",    0.0, 1.0, 2.0,
    ///                         "string map",   "texture.pic",
    ///                         "int[2] iarray", int64(0), int64(1),
    ///                         nullptr); <======= MUST TERMINATE =======
    /// @code
    /// Common errors include: @code
    ///   UT_Options    options(
    ///         "int ival",     (int64)0,       // Error, must be int
    ///         "int64 ival",   (int)0,         // Error, must be int64
    ///         "vector3 fval", 0, 1.0, 2.0,    // First entry is an int!
    ///         "float[3] farray", 0.0, 1.0,    // Missing 3rd value
    ///         /* MISSING nullptr TERMINATOR */);
    /// @endcode
    ///
    /// This function effectively does not call optionChanged.
    UT_Options(const char *type_and_name, ...);

    /// Lookup an option type based on a keyword
    static UT_OptionType        optionType(const UT_StringRef &kwd);

    // This function does not call optionChanged.
    void clear();

    // Returns true on success or if the file didn't exist;
    // returns false only if the file encounters an error.
    // The load methods can handle files saved either with this save
    // or with saveAsJSON.  saveAsJSON is preferable as it handles 64bit
    // floats and ints, but can't be read before H10.5
    // When 'compact' parameter is true, the info is not explicitly saved.
    bool load(const char *filename);
    bool save(const char *filename) const;
    bool saveOrdered(const char *filename) const;
    bool load(const char *filename, UT_IStream &is);
    bool save(const char *filename, std::ostream &os) const;
    bool saveOrdered(const char *filename, std::ostream &os) const;
    
    bool saveAsJSON(const char *filename,
                    bool binary = true,
                    bool compact = false) const;
    bool saveAsJSON(const char *filename, std::ostream &os,
                    bool binary = true,
                    bool compact = false) const;

    // Remove an option.
    void                 removeOption(const UT_StringHolder &name);
    
    // Get the string representation of any of our options.  Note that, if
    // the value contains binary data with null characters, you can't determine
    // the length of the data with UT_String version of these methods.
    bool                 getOptionString(const UT_StringHolder &name,
                                         UT_OptionFormat format,
                                         UT_WorkBuffer &result) const;
    bool                 getOptionString(const UT_StringHolder &name,
                                         UT_OptionFormat format,
                                         UT_String &result) const;
    
    // Append the python dictionary representation of ALL our options to the
    // buffer
    bool                 appendPyDictionary(UT_WorkBuffer &result,
                                bool sorted=false) const;
                                
    // Parse a python dictionary string and merge the results into our
    // options.
    bool                 setFromPyDictionary(const char *dict);

    // Parse a python formatted value and set it as the named option.
    bool                 setPyOptionString(const UT_StringHolder &name, 
                                           const char *value);

    /// Save a UT_Options to JSON format using UT_JSONWriter
    /// @param compact If true, the type info is not explicitly saved.
    bool                 save(UT_JSONWriter &w, bool compact = false) const;

    /// Save a UT_Options to a UT_JSONValue
    /// @param compact If true, the type info is not explicitly saved.
    void                 save(UT_JSONValueMap &map, bool compact = false) const;

    /// Load a UT_Options from a JSON parser.
    /// @param parser           Parser
    /// @param do_clear         Clear existing map before loading
    ///   If true and the first object in the JSON stream is not a map object,
    ///   then the parser will fail (with an error).  Otherwise a warning will
    ///   be added and the object will be skipped.
    /// @param is   If this is specified, then data will be read from that
    ///   stream rather than the stream associated with the parser.
    /// @param require_type If true, the JSON input must contain option entries
    ///   in a format that explicitly specifies both the 'type' and the 'value'.
    ///   Otherwise, JSON may specify value directly, and the type will be
    ///   deduced implicitly from the value.
    bool                 load(UT_JSONParser &parser,
                                bool do_clear,
                                UT_IStream *is = 0,
                                bool require_type = true);

    /// Loads a UT_Options from a JSONValue map.
    /// @param allow_type  Controls if a map with "type" and "value" entries
    ///   will be interpreted as an explicit type request.
    /// @param allow_dict  Controls if a map will be turned into a nested 
    ///   dictionary.  
    /// Note: if both 'allow_type' and 'allow_dict' are true , things that 
    ///   look like types will be treated as such; the rest as dictionaries.
    bool                 load(UT_JSONValueMap &map,
                                bool do_clear,
                                bool allow_type = true,
                                bool allow_dict = false);

    /// Writes a JSON dump to ostream of the current options.
    void                dump(std::ostream &os) const;
    /// Dump to stdout/cout
    void                dump() const;

    // Functions for accessing the options by name.
    bool                 hasOption(const UT_StringRef &name) const;
    UT_OptionType        getOptionType(const UT_StringRef &name) const;
    const UT_OptionEntry*getOptionEntry(const UT_StringRef &name) const;

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

    // Functions for accessing all options sequentially.
    class UT_API iterator
    {
    public:
        iterator()
            : myOptions(nullptr)
        {}
        iterator(const iterator &i)
            : myOptions(i.myOptions)
            , myIterator(i.myIterator)
            , myEnd(i.myEnd)
        {}
        const UT_StringHolder &name() const
                            { return myIterator->first; }
        const UT_OptionEntry     *entry() const
                            { return myIterator->second.get(); }
        UT_OptionType    type() const;
        const UT_OptionEntry    *operator*() const { return entry(); }

        iterator        &operator=(const iterator &i)
                         {
                             myOptions = i.myOptions;
                             myIterator = i.myIterator;
                             myEnd = i.myEnd;
                             return *this;
                         }
        bool             operator==(const iterator &i) const
                         {
                             return myIterator == i.myIterator;
                         }
        bool             operator!=(const iterator &i) const
                         { return !(*this == i); }
        iterator        &operator++()   { advance(); return *this; }
        bool             atEnd() const  { return myIterator == myEnd; }
        void             advance()      { ++myIterator; }
    private:
        iterator(const UT_Options &opts, const MapType::const_iterator &it,
                 const MapType::const_iterator &end)
            : myOptions(&opts)
            , myIterator(it)
            , myEnd(end)
        {
        }
        const UT_Options        *myOptions;
        MapType::const_iterator  myIterator;
        MapType::const_iterator  myEnd;
        friend class             UT_Options;
    };
    class UT_API ordered_iterator
    {
    public:
        ordered_iterator()
            : myKeys()
            , myValues()
            , myOrder()
            , myPos(0)
            , myCurr(0)
        {
        }
        ordered_iterator(const ordered_iterator &src)
            : myKeys(src.myKeys)
            , myValues(src.myValues)
            , myOrder(src.myOrder)
            , myPos(src.myPos)
            , myCurr(src.myCurr)
        {
        }
        const UT_StringHolder &name() const
                            { return myKeys(myCurr); }
        const UT_OptionEntry     *entry() const
                            { return myValues(myCurr); }
        UT_OptionType    type() const;
        const UT_OptionEntry    *operator*() const { return entry(); }

        ordered_iterator &operator=(const ordered_iterator &i)
                         {
                             myKeys = i.myKeys;
                             myValues = i.myValues;
                             myOrder = i.myOrder;
                             myPos = i.myPos;
                             myCurr = i.myCurr;
                             return *this;
                         }
        bool             operator==(const ordered_iterator &i) const
                         {
                             if (i.atEnd() && atEnd())
                                 return true;
                             // Iterators are only equal if they are both at
                             // the end.
                             return false;
                         }
        bool             operator!=(const ordered_iterator &i) const
                         { return !(*this == i); }
        ordered_iterator &operator++()  { advance(); return *this; }
        bool             atEnd() const  { return myPos >= myOrder.entries(); }
        void             advance()
                         {
                             myPos++;
                             if (myPos < myOrder.entries())
                                 myCurr = myOrder(myPos);
                         }
    private:
        class comparator
        {
        public:
            comparator(const UT_ValArray<UT_StringHolder> &keys)
                : myKeys(keys)
            {
            }
            bool        operator()(int a, int b) const
                        {
                            UT_ASSERT(a >= 0 && a < myKeys.entries());
                            UT_ASSERT(b >= 0 && b < myKeys.entries());
                            return myKeys(a) < myKeys(b);
                        }
        private:
            const UT_ValArray<UT_StringHolder>  &myKeys;
        };
        // If you get an error here, maybe you meant to call obegin()?
        explicit ordered_iterator(iterator it)
            : myKeys()
            , myValues()
            , myOrder()
            , myPos(0)
            , myCurr(0)
        {
            int         index = 0;
            for (; !it.atEnd(); ++it, ++index)
            {
                myKeys.append(it.name());
                myValues.append(it.entry());
                myOrder.append(index);
            }
            myOrder.sort(comparator(myKeys));
            if (myOrder.entries())
                myCurr = myOrder(0);
        }

        UT_ValArray<UT_StringHolder>            myKeys;
        UT_ValArray<const UT_OptionEntry *>     myValues;
        UT_IntArray                             myOrder;
        int                                     myPos;
        int                                     myCurr;
        friend class             UT_Options;
    };
    iterator             begin() const
                         { return iterator(*this, myMap.begin(), myMap.end()); }
    iterator             end() const
                         { return iterator(*this, myMap.end(), myMap.end()); }
    ordered_iterator     obegin() const
                         { return ordered_iterator(begin()); }
    ordered_iterator     oend() const
                         { return ordered_iterator(end()); }

    // Functions for accessing specific option values.
    int64                getOptionI(const UT_StringRef &name) const;
    bool                 getOptionB(const UT_StringRef &name) const;
    fpreal64             getOptionF(const UT_StringRef &name) const;
    const UT_Vector2D    &getOptionV2(const UT_StringRef &name) const;
    const UT_Vector3D    &getOptionV3(const UT_StringRef &name) const;
    const UT_Vector4D    &getOptionV4(const UT_StringRef &name) const;
    const UT_QuaternionD &getOptionQ(const UT_StringRef &name) const;
    const UT_Matrix2D    &getOptionM2(const UT_StringRef &name) const;
    const UT_Matrix3D    &getOptionM3(const UT_StringRef &name) const;
    const UT_Matrix4D    &getOptionM4(const UT_StringRef &name) const;
    const UT_Vector2D    &getOptionUV(const UT_StringRef &name) const;
    const UT_Vector3D    &getOptionUVW(const UT_StringRef &name) const;

    // Note that, if the string value contains binary data with null
    // characters, the UT_String version of getOptionS will not be able to
    // tell you the length of the data, since UT_String doesn't store the
    // length.
    const UT_StringHolder &getOptionS(const UT_StringRef &name) const;
    void                 getOptionS(const UT_StringRef &name, 
                                    std::string &value) const;
    void                 getOptionS(const UT_StringRef &name, 
                                    UT_String &value) const;
    void                 getOptionS(const UT_StringRef &name,
                                    UT_StringHolder &value) const;
    void                 getOptionS(const UT_StringRef &,
                                    UT_WorkBuffer &value) const;
    const UT_OptionsHolder &getOptionDict(const UT_StringRef &name) const;

    const UT_Int64Array         &getOptionIArray(const UT_StringRef &) const;
    const UT_Fpreal64Array      &getOptionFArray(const UT_StringRef &) const;
    const UT_StringArray        &getOptionSArray(const UT_StringRef &) const;
    const UT_Array<UT_OptionsHolder>    &getOptionDictArray(const UT_StringRef &) const;

    // Returns a valid number if this option is a float or an int.
    // In the case of an int, it is converted to a float.
    fpreal64             getOptionNum(const UT_StringRef &) const;

    // Functions for accessing option values.  These methods will perform some
    // minimal "casting".
    //  importOption(... bool &value)   - Tests integers and string options
    //  importOption(... fpreal &value) - Evaluates integer/bool options
    //  importOption(... UT_Vector2 &)  - Evaluates Vector2 or UV
    //  importOption(... UT_Vector3 &)  - Evaluates Vector3 or UVW
    //  
    bool         importOption(const UT_StringRef &name, int &value) const;
    bool         importOption(const UT_StringRef &name, int64 &value) const;
    bool         importOption(const UT_StringRef &name, bool &value) const;
    bool         importOption(const UT_StringRef &name, 
                              fpreal32 &value) const;
    bool         importOption(const UT_StringRef &name, 
                              fpreal64 &value) const;
    bool         importOption(const UT_StringRef &name, 
                              std::string &value) const;
    bool         importOption(const UT_StringRef &name, 
                              UT_String &value) const;
    bool         importOption(const UT_StringRef &name, 
                              UT_StringHolder &value) const;
    bool         importOption(const UT_StringRef &name, 
                              UT_OptionsHolder &value) const;
    bool         importOption(const UT_StringRef &name, 
                              UT_Vector2F &value) const;
    bool         importOption(const UT_StringRef &name, 
                              UT_Vector3F &value) const;
    bool         importOption(const UT_StringRef &name, 
                              UT_Vector4F &value) const;
    bool         importOption(const UT_StringRef &name, 
                              UT_QuaternionF &value) const;
    bool         importOption(const UT_StringRef &name, 
                              UT_Matrix2F &value) const;
    bool         importOption(const UT_StringRef &name, 
                              UT_Matrix3F &value) const;
    bool         importOption(const UT_StringRef &name, 
                              UT_Matrix4F &value) const;
    bool         importOption(const UT_StringRef &name, 
                              UT_Vector2D &value) const;
    bool         importOption(const UT_StringRef &name, 
                              UT_Vector3D &value) const;
    bool         importOption(const UT_StringRef &name, 
                              UT_Vector4D &value) const;
    bool         importOption(const UT_StringRef &name, 
                              UT_QuaternionD &value) const;
    bool         importOption(const UT_StringRef &name, 
                              UT_Matrix2D &value) const;
    bool         importOption(const UT_StringRef &name, 
                              UT_Matrix3D &value) const;
    bool         importOption(const UT_StringRef &name, 
                              UT_Matrix4D &value) const;

    // Generic import which handles arbitrary length int/float data
    bool         importOption(const UT_StringRef &name, 
                              UT_Array<int32> &value) const;
    bool         importOption(const UT_StringRef &name, 
                              UT_Array<int64> &value) const;
    bool         importOption(const UT_StringRef &name, 
                              UT_Array<fpreal32> &value) const;
    bool         importOption(const UT_StringRef &name, 
                              UT_Array<fpreal64> &value) const;

    // Import a string array
    bool         importOption(const UT_StringRef &name,
                              UT_StringArray &value) const;
    bool         importOption(const UT_StringRef &name,
                              UT_Array<UT_StringHolder> &value) const;

    // Import a dictionary array.
    bool         importOption(const UT_StringRef &name,
                              UT_Array<UT_OptionsHolder> &value) const;

    // Import a single element from a scalar, vector, matrix or array
    bool         importElement(const UT_StringRef &name,
                               fpreal &value,
                               exint index = 0) const;
    bool         importElement(const UT_StringRef &name,
                               int64 &value,
                               exint index = 0) const;
    

    // All these functions cause optionChanged to be called.
    UT_Options           &setOptionI(const UT_StringHolder &name,
                                     int64 value);
    UT_Options           &setOptionB(const UT_StringHolder &name,
                                     bool value);
    UT_Options           &setOptionF(const UT_StringHolder &name,
                                     fpreal64 value);
    // Note that you can store binary data (that can contain null characters
    // or that isn't null-terminated) in a string option by passing in a
    // UT_WorkBuffer, or std::string.
    UT_Options           &setOptionS(const UT_StringHolder &name,
                                     const UT_StringHolder &value);
    // setOptionSRaw() is the same as setOptionS() instead of it being
    // additionally tagged as a "raw" string so that getPyOptionString() and
    // appendPyDictionary() won't add quotes around the value. To retrieve its
    // value, use getOptionS().
    UT_Options           &setOptionSRaw(const UT_StringHolder &name,
                                        const UT_StringHolder &value);
    UT_Options           &setOptionDict(const UT_StringHolder &name,
                                     const UT_OptionsHolder &value);
    UT_Options           &setOptionV2(const UT_StringHolder &name,
                                      const UT_Vector2F &value);
    UT_Options           &setOptionV2(const UT_StringHolder &name,
                                      const UT_Vector2D &value);
    UT_Options           &setOptionV2(const UT_StringHolder &name,
                                      fpreal64 x, fpreal64 y);
    UT_Options           &setOptionV3(const UT_StringHolder &name,
                                      const UT_Vector3F &value);
    UT_Options           &setOptionV3(const UT_StringHolder &name,
                                      const UT_Vector3D &value);
    UT_Options           &setOptionV3(const UT_StringHolder &name,
                                      fpreal64 x, fpreal64 y, fpreal64 z);
    UT_Options           &setOptionV4(const UT_StringHolder &name,
                                      const UT_Vector4F &value);
    UT_Options           &setOptionV4(const UT_StringHolder &name,
                                      const UT_Vector4D &value);
    UT_Options           &setOptionV4(const UT_StringHolder &name,
                                      fpreal64 x, fpreal64 y,
                                      fpreal64 z, fpreal64 w);
    UT_Options           &setOptionQ(const UT_StringHolder &name,
                                     const UT_QuaternionF &value);
    UT_Options           &setOptionQ(const UT_StringHolder &name,
                                     const UT_QuaternionD &value);
    UT_Options           &setOptionM2(const UT_StringHolder &name,
                                      const UT_Matrix2F &value);
    UT_Options           &setOptionM2(const UT_StringHolder &name,
                                      const UT_Matrix2D &value);
    UT_Options           &setOptionM3(const UT_StringHolder &name,
                                      const UT_Matrix3F &value);
    UT_Options           &setOptionM3(const UT_StringHolder &name,
                                      const UT_Matrix3D &value);
    UT_Options           &setOptionM4(const UT_StringHolder &name,
                                      const UT_Matrix4F &value);
    UT_Options           &setOptionM4(const UT_StringHolder &name,
                                      const UT_Matrix4D &value);
    UT_Options           &setOptionUV(const UT_StringHolder &name,
                                      const UT_Vector2F &value);
    UT_Options           &setOptionUV(const UT_StringHolder &name,
                                      const UT_Vector2D &value);
    UT_Options           &setOptionUVW(const UT_StringHolder &name,
                                       const UT_Vector3F &value);
    UT_Options           &setOptionUVW(const UT_StringHolder &name,
                                       const UT_Vector3D &value);
    /// @{
    /// Set integer array options
    UT_Options           &setOptionIArray(const UT_StringHolder &name,
                                          const int32 *values, size_t size);
    UT_Options           &setOptionIArray(const UT_StringHolder &name,
                                          const int64 *values, size_t size);
    UT_Options           &setOptionIArray(const UT_StringHolder &name,
                                          const UT_Array<int64> &value);
    /// @}
    /// @{
    /// Set float/double array options
    UT_Options           &setOptionFArray(const UT_StringHolder &name,
                                          const fpreal32 *values, size_t size);
    UT_Options           &setOptionFArray(const UT_StringHolder &name,
                                          const fpreal64 *values, size_t size);
    UT_Options           &setOptionFArray(const UT_StringHolder &name,
                                          const UT_Array<fpreal64> &value);
    /// @}

    /// Set string array options
    UT_Options           &setOptionSArray(const UT_StringHolder &name,
                                          const UT_StringHolder *values,
                                          size_t size);
    UT_Options           &setOptionSArray(const UT_StringHolder &name,
                                          const char *const*values,
                                          size_t size);
    UT_Options           &setOptionSArray(const UT_StringHolder &name,
                                          const UT_StringArray &value);

    /// Set dict array options
    UT_Options           &setOptionDictArray(const UT_StringHolder &name,
                                          const UT_OptionsHolder *values,
                                          size_t size);
    UT_Options           &setOptionDictArray(const UT_StringHolder &name,
                                          const UT_Array<UT_OptionsHolder> &value);

    /// Get a hash code for the options
    unsigned             hash() const;

    /// Comparison operator
    bool                 operator==(const UT_Options &src) const
                            { return isEqual(src, 0.0); }
    bool                 operator!=(const UT_Options &src) const
                            { return !(*this == src); }

    /// Comparison operator with a tolerance for float values.
    bool                 isEqual(const UT_Options &src, fpreal64 tol) const;

    /// Assignment operator
    const UT_Options    &operator=(const UT_Options &src);
    void                 merge(const UT_Options &src);
    void                 merge(const UT_Options &src,
                               bool (*match)(const UT_StringHolder &name,
                                             const UT_OptionEntry *, void *),
                               void *data);
    virtual int64        getMemoryUsage(bool inclusive) const;

    // This will steal the option from the unique ptr.
    void                 setOption(const UT_StringHolder &name,
                                   UT_OptionEntryPtr value);

protected:
    const UT_StringHolder       *findOptionS(const UT_StringRef &name) const;
    void                 addError(const char *filename, int linecount,
                                  const char *error_str) const;
    bool                 sendOptionChanges() const
                            { return mySendOptionChanges; }
    void                 setSendOptionChanges(bool f)
                            { mySendOptionChanges = f; }
    virtual void         optionChanged(const char *name);
    UT_OptionEntryPtr   parsePyValue(const char *&value,
                                              char sep_delim,
                                              char close_delim = '\0');

private:
    template <class ITER>
    bool save(ITER start, const char *filename, std::ostream &os) const;

    MapType                              myMap;
    bool                                 mySendOptionChanges;
};

/// A holder for a options, which caches the hash value.
/// A UT_OptionsRef does not necessarily own the options, and it is therefore
/// not safe to e.g. store a UT_OptionsRef in a container or member variable.
/// @see UT_OptionsHolder
class UT_API UT_OptionsRef
{
public:
    typedef UT_Options value_type;

    SYS_FORCE_INLINE
    UT_OptionsRef()
    {
        init();
    }

    /// Will make a shallow reference.
    SYS_FORCE_INLINE
    UT_OptionsRef(const UT_Options *opt)
    {
        init();
        reference(opt);
    }

    /// Shares a reference with the source.
    SYS_FORCE_INLINE
    UT_OptionsRef(const UT_OptionsRef &s)
    {
        mySoftRef = s.mySoftRef;
        mySharedRef = s.mySharedRef;
        myHash = s.myHash;
    }

    /// Move constructor. Steals the working data from the original.
    SYS_FORCE_INLINE
    UT_OptionsRef(UT_OptionsRef &&s) noexcept
    {
        mySoftRef = s.mySoftRef;
        mySharedRef = std::move(s.mySharedRef);
        myHash = s.myHash;
        s.init();
    }

    SYS_FORCE_INLINE
    ~UT_OptionsRef()
    {
    }

    /// Special sentinel value support
    /// @{
    enum UT_OptionsSentinelType { SENTINEL };

    SYS_FORCE_INLINE explicit
    UT_OptionsRef(UT_OptionsSentinelType)
        : mySoftRef((const UT_Options *)SENTINEL_DATA)
        , myHash(SENTINEL_HASH)
    {
    }

    SYS_FORCE_INLINE
    bool isSentinel() const
    {
        return uintptr_t(mySoftRef) == SENTINEL_DATA && myHash == SENTINEL_HASH;
    }

    SYS_FORCE_INLINE
    void makeSentinel()
    {
        init();
        myHash = SENTINEL_HASH;
        mySoftRef = (const UT_Options *) SENTINEL_DATA;
    }
    /// @}

    /// Returns true this object is the sole owner of the underlying options
    bool isUnique() const
    {
        // Soft references are not unique.  (This includes sentinels)
        if (mySoftRef)
            return false;
        // If the shared ref is null, it isn't unique.
        if (!mySharedRef.get())
            return false;

        return mySharedRef.unique();
    }

    /// Returns the shared ptr use count.  0 if not a shared
    /// pointer.  (null or soft ref)
    int use_count() const
    {
        if (mySoftRef)
            return 0;
        if (!mySharedRef.get())
            return 0;
        return mySharedRef.use_count();
    }

    /// Shares a reference with the source.
    UT_OptionsRef &operator=(const UT_OptionsRef &s)
    {
        // Can now blindly copy.
        mySoftRef = s.mySoftRef;
        mySharedRef = s.mySharedRef;
        myHash = s.myHash;
        return *this;
    }

    /// Move the contents of about-to-be-destructed options
    /// s to this string.
    SYS_FORCE_INLINE
    UT_OptionsRef &operator=(UT_OptionsRef &&s)
    {
        // Can just swap, since s is about to be destructed.
        swap(s);
        return *this;
    }

    SYS_FORCE_INLINE
    const UT_Options *optionsOrNull() const
    {
        if (isSentinel())
            return nullptr;
        return rawOptions();
    }

    SYS_FORCE_INLINE
    const UT_Options *options() const
    {
        const UT_Options *result = optionsOrNull();
        if (result == nullptr)
            return &theEmptyOptionsData;
        return result;
    }

    bool                operator==(const UT_OptionsRef &s) const
    { 
        const UT_Options *a = rawOptions();
        const UT_Options *b = s.rawOptions();

        if (a == b)
            return true;

        // If they are not equal, we have to test null and sentinel.
        // If either one is null or sentinel, we know they must be
        // unequal.
        if (!a || !b || (uintptr_t(a) == SENTINEL_DATA) || (uintptr_t(b) == SENTINEL_DATA))
            return false;

        // If we have hashes and they are unequal, we must
        // be unequal.
        if (myHash && s.myHash)
        {
            if (myHash != s.myHash)
                return false;
        }

        // Now we have de-referenceable options pointers.
        return (*a == *b);
    }

    bool                operator==(const UT_Options *b) const
    { 
        const UT_Options *a = rawOptions();

        if (a == b)
            return true;

        // If they are not equal, we have to test null and sentinel.
        // If either one is null or sentinel, we know they must be
        // unequal.
        if (!a || !b || (uintptr_t(a) == SENTINEL_DATA) || (uintptr_t(b) == SENTINEL_DATA))
            return false;
        
        // Can't test hashes as we don't have it for a raw pointer.

        // Now we have de-referenceable options pointers.
        return (*a == *b);
    }

    bool                operator!=(const UT_OptionsRef &s) const
                            { return !operator==(s); }
    bool                operator!=(const UT_Options *s) const
                            { return !operator==(s); }

    /// Comparison operator with a tolerance for float values.
    bool                isEqual(const UT_OptionsRef &s, fpreal64 tol) const;

    SYS_FORCE_INLINE const UT_Options *operator->() const { return options(); }
    SYS_FORCE_INLINE const UT_Options &operator*() const { return *options(); }

    SYS_FORCE_INLINE
    void swap( UT_OptionsRef &other )
    {
        UTswap(mySoftRef, other.mySoftRef);
        UTswap(mySharedRef, other.mySharedRef);
        UTswap(myHash, other.myHash);
    }

    /// Friend specialization of std::swap() to use UT_OptionsRef::swap()
    friend void swap(UT_OptionsRef& a, UT_OptionsRef& b) { a.swap(b); }

    SYS_FORCE_INLINE
    void clear()
    {
        init();
    }

    bool                isEmpty() const
    {
        const UT_Options *opt = optionsOrNull();
        if (!opt)
            return true;

        if (opt->getNumOptions() == 0)
            return true;

        return false;
    }

    explicit operator bool() const { return !isEmpty(); }

    unsigned            hash() const
    {
        if (myHash)
            return myHash;

        const UT_Options              *opt = optionsOrNull();
        if (!opt)
            return 0;

        unsigned localhash = opt->hash();
        if (!localhash)
            localhash++;
        myHash = localhash;
        return myHash;
    }

    /// Make a light weight reference to the source.
    /// Caller must make sure src lives for the duration of this object,
    /// and any objects value copied from this!
    void                reference(const UT_Options *src)
    {
        init();
        mySoftRef = src;
    }

    int64               getMemoryUsage(bool inclusive) const
    {
        int64 mem = inclusive ? sizeof(*this) : 0;

        const UT_Options *opt = optionsOrNull();
        if (opt)
            mem += opt->getMemoryUsage(true);
        return mem;
    }

    static const UT_Options     &emptyOptions() { return theEmptyOptionsData; }

private:
    void init()
    {
        mySoftRef = nullptr;
        mySharedRef.reset();
        myHash = 0;
    }

    void copy(const UT_OptionsRef &s)
    {
        mySoftRef = s.mySoftRef;
        mySharedRef = s.mySharedRef;
        myHash = s.myHash;
    }

    SYS_FORCE_INLINE
    const UT_Options *rawOptions() const
    {
        if (mySoftRef)
            return mySoftRef;
        return mySharedRef.get();
    }


    /// Either softref or shared ref should be set, never both.
    /// Note that this might be possible to collapse into a single
    /// shared ptr using the semantic that use_count==0 means soft ref.
    const UT_Options    *mySoftRef;
    UT_SharedPtr<UT_Options>    mySharedRef;

    /// Optional hash, 0 if not computed yet.
    mutable int          myHash;

    // UT_OptionsHolder needs to be a friend class so that the
    // UT_OptionsHolder(const UT_OptionsRef &) constructor can access myHash and
    // getHolder() for the UT_OptionsRef that is passed in.
    friend class UT_OptionsHolder;

    static constexpr uintptr_t SENTINEL_DATA = 1;
    static constexpr uint32 SENTINEL_HASH = 0xdeadbeef;

    // Because we want a null options pointer to return an empty options,
    // we need a canonical empty options to return.
    static const UT_Options theEmptyOptionsData;

    template<typename T>
    static SYS_FORCE_INLINE bool isSentinelOrNullPtr(const T *p)
    {
        return uintptr_t(p) <= SENTINEL_DATA;
    }
};

SYS_FORCE_INLINE size_t hash_value(const UT_OptionsRef &opt)
{
    return opt.hash();
}


class UT_API UT_OptionsHolder : public UT_OptionsRef
{
public:
    /// UT_OptionsHolder can be constructed with UT_OptionsHolder::REFERENCE to
    /// create a shallow reference to the const char *.
    enum UT_OptionsReferenceType { REFERENCE };

    SYS_FORCE_INLINE
    UT_OptionsHolder()
        : UT_OptionsRef()
    {
    }

    /// Will make a copy of the provided options.
    SYS_FORCE_INLINE
    UT_OptionsHolder(const UT_Options *opt)
    {
        mySoftRef = nullptr;
        if (opt)
            mySharedRef = UTmakeShared<UT_Options>(*opt);
        else
            mySharedRef.reset();
    }

    /// Will make a shallow reference.
    SYS_FORCE_INLINE
    UT_OptionsHolder(UT_OptionsReferenceType, const UT_Options *opt)
        : UT_OptionsRef(opt)
    {
    }

    /// Makes a shallow reference to the contents of the UT_OptionsRef.
    SYS_FORCE_INLINE
    UT_OptionsHolder(UT_OptionsReferenceType, const UT_OptionsRef &ref)
        : UT_OptionsRef(ref)
    {
    }

    /// Makes a deep copy of the provided UT_OptionsRef.
    /// This constructor is not marked explicit since we often want this
    /// conversion (e.g. when inserting a UT_OptionsRef into a UT_OptionsMap, as
    /// with the const char* constructor).
    UT_OptionsHolder(const UT_OptionsRef &ref);

    /// Construct as a sentinel value
    SYS_FORCE_INLINE explicit
    UT_OptionsHolder(UT_OptionsSentinelType sentinel)
        : UT_OptionsRef(sentinel)
    {
    }

    /// Makes a copy of the provided options.
    SYS_FORCE_INLINE
    UT_OptionsHolder(const UT_OptionsHolder &str)
        : UT_OptionsRef(str)
    {
    }

    /// Move constructor. Steals the working data from the original.
    SYS_FORCE_INLINE
    UT_OptionsHolder(UT_OptionsHolder &&a) noexcept
        : UT_OptionsRef(std::move(a))
    {
    }

    /// Makes a bit-wise copy of the options and adjust the reference count.
    SYS_FORCE_INLINE
    UT_OptionsHolder &operator=(const UT_OptionsHolder &s)
    {
        UT_OptionsRef::operator=(s);
        return *this;
    }

    /// Move the contents of about-to-be-destructed options
    /// s to this options.
    SYS_FORCE_INLINE
    UT_OptionsHolder &operator=(UT_OptionsHolder &&s)
    {
        UT_OptionsRef::operator=(std::move(s));
        return *this;
    }

    SYS_FORCE_INLINE
    void swap(UT_OptionsHolder &other)
    {
        UT_OptionsRef::swap(other);
    }

    SYS_FORCE_INLINE
    void swap(UT_OptionsRef &other)
    {
        UT_OptionsRef::swap(other);
        // harden ourselves like UT_OptionsHolder::operator=(UT_OptionsRef&)
        if (isSentinelOrNullPtr(mySoftRef))
           return; // already a holder
        mySharedRef = UTmakeShared<UT_Options>(*mySoftRef);
        mySoftRef = nullptr;
    }

    /// Returns a writeable UT_Options which will modify the contents
    /// of this options holder.  When this is copied or deleted, the
    /// returned pointer must not be used any more.  (Ideally we could
    /// erase ourself and return a UniquePtr for correct life time,
    /// but we can't steal from a shared pointer)
    ///
    /// Use update() whereever possible instead as it is much safer.
    UT_Options *makeUnique()
    {
        // Harden if soft.
        if (!isUnique())
        {
            mySharedRef = UTmakeShared<UT_Options>(*options());
            mySoftRef = nullptr;
        }
        UT_ASSERT(isUnique());

        // Since we are going to be edited, we must reset our hash.
        myHash = 0;

        return SYSconst_cast(options());
    }

    /// Updates the contents of this option, first making sure it is
    /// unique.  The provided operator should take a reference to
    /// a UT_Options that it will update.
    /// UT_OptionsHolder value;
    /// value.update([](UT_Options &opt) { opt.setOptionS("test", "bar"); });
    template <typename OP>
    void update(const OP &op)
    {
        UT_Options *opt = makeUnique();
        op(*opt);
    }

    /// Friend specialization of std::swap() to use UT_OptionsHolder::swap()
    /// @{
    friend void swap(UT_OptionsHolder& a, UT_OptionsRef& b) { a.swap(b); }
    friend void swap(UT_OptionsHolder& a, UT_OptionsHolder& b) { a.swap(b); }
    /// @}

    /// In some functions it's nice to be able to return a const-reference to a
    /// UT_OptionsHolder.  However, in error cases, you likely want to return an
    /// empty options.  This would mean that you'd have to return a real
    /// UT_OptionsHolder (not a const reference).  This static lets you return a
    /// reference to an empty options.
    static const UT_OptionsHolder theEmptyOptions;

    static const UT_OptionsHolder theSentinel;
    
protected:
};

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

template <>
struct DefaultClearer<UT_OptionsHolder>
{
    static void clear(UT_OptionsHolder &v) { v.makeSentinel(); }
    static bool isClear(const UT_OptionsHolder &v) { return v.isSentinel(); }
    static void clearConstruct(UT_OptionsHolder *p)
                { new ((void *)p) UT_OptionsHolder(UT_OptionsRef::SENTINEL); }
    static const bool clearNeedsDestruction = false;
};
} // namespace UT

UT_API size_t format(char *buffer, size_t buffer_size, const UT_Options &v);
UT_API size_t format(char *buffer, size_t buffer_size, const UT_OptionsRef &v);

// Most people only include UT_Options.  But we can't include this at the start
// as we are a pre-req.
#include "UT_OptionEntry.h"

#endif