UT_JSONValue.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_JSONValue.h ( UT Library, C++)
 *
 * COMMENTS:    This class represents a JSON object.
 */

#ifndef __UT_JSONValue__
#define __UT_JSONValue__

#include "UT_API.h"
#include "UT_SymbolTable.h"
#include "UT_VectorTypes.h"
#include "UT_StringArray.h"
#include "UT_StringHolder.h"
#include "UT_Compression.h"
#include <SYS/SYS_Compiler.h>
#include <SYS/SYS_Inline.h>
#include <SYS/SYS_Hash.h>

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

/// Ideally, this should be an inner class to UT_JSONValue, but it needs to be
/// forward declared
struct UT_API UT_JSONFindResult
{
    explicit    UT_JSONFindResult(UT_JSONValue *v = nullptr, int64 idx=-1)
                    : myValue(v)
                    , myIndex(idx)
                {
                }

    SYS_SAFE_BOOL        operator bool() const { return myValue != nullptr; }
    const UT_JSONValue  *operator->() const { return get(); }
    UT_JSONValue        *operator->() { return get(); }
    const UT_JSONValue  &operator*() const { return *get(); }
    UT_JSONValueMap     *getMap() const;
    UT_JSONValueArray   *getArray() const;

    UT_JSONValue        *get() const { return myValue; }
    int64                index() const { return myIndex; }

    UT_JSONValue        *myValue;
    int64                myIndex;
};

/// @brief Class to store JSON objects as C++ objects
///
/// This class is able to represent a JSON object in its entirety.  Arrays and
/// Maps store arrays and maps of JSON values.
///
/// There are methods to load a JSONValue from a UT_JSONParser and to save to a
/// UT_JSONWriter object.
///
/// To load an entire JSON file into memory, you can do something like
/// @code
///     UT_JSONIStream *is(utistream);
///     UT_JSONParser parser;
///     UT_JSONValue value;
///     if (!value.load(parser, *is))
///             reportFailure(parser.getErrors());
/// @endcode
///
/// To save a value:
/// @code
///     UT_JSONWriterSubclass    &os;
///     value.save(os);
/// @endcode
///
/// Alternatively, it's possible to use the UT_JSONValue class from within
/// other UT_JSONHandle classes.  For example, when loading key/value pairs for
/// an arbitrary map:
/// @code
///     bool
///     my_handle::jsonKey(UT_JSONParser &parser, const char *token, int64)
///     {
///          UT_String          keyword;
///          UT_JSONValue       value;
///          keyword.harden(token);
///          if (!value.load(parser))
///             return false;
///          process(keyword, value);
///          return true;
///     }
/// @endcode
/// @see UT_JSONParser, UT_JSONWriter, UT_JSONHandle, UT_JSONValueArray,
/// UT_JSONValueMap

class UT_API UT_JSONValue
{
public:
    /// Types held in the UT_JSONValue.  The number type has been broken out
    /// into an integer and a real.
    enum Type {
        JSON_NULL,      // Null
        JSON_BOOL,      // Bool
        JSON_INT,       // Integer
        JSON_REAL,      // Real
        JSON_STRING,    // String value
        JSON_KEY,       // Key value
        JSON_ARRAY,     // An array of UT_JSON_VALUE
        JSON_MAP,       // A map of keyword, UT_JSONValue object
    };

     UT_JSONValue();
     explicit UT_JSONValue(Type type);
     explicit UT_JSONValue(bool value);
     explicit UT_JSONValue(int64 value);
     explicit UT_JSONValue(fpreal64 value);
     explicit UT_JSONValue(const char *string, int64 length=-1);
     explicit UT_JSONValue(const UT_StringHolder &s);
     UT_JSONValue(const UT_JSONValue &v);
    ~UT_JSONValue();

    UT_JSONValue        &operator=(const UT_JSONValue &v)
                         {
                             copyFrom(v);
                             return *this;
                         }

    /// Normally JSON values store shared pointers to the array and map
    /// objects.  This method will make a deep copy of the JSON Value.
    UT_JSONValue        deepCopy() const;

    /// Read the next value from the parser and store it in this object
    /// @param parser   The parser
    /// @param is       If specified, data will be read from this stream.
    /// @param record_source_offsets  Track offsets in stream for later seeking
    /// Otherwise, the stream associated with the parser will be used.
    bool         parseValue(UT_JSONParser &parser,
                                UT_IStream *is = 0,
                                bool record_source_offsets = false);

    bool         parseValue(const UT_StringRef &json_source);
    bool         parseValue(std::istream& is);

    /// Loads an entire JSON file into this value.
    bool         loadFromFile(const char* file_name,
                                bool record_source_offsets = false);

    /// Saves an entire JSON value to the specified file.
    bool         saveToFile(const char* file_name,
                                bool binary = false,
                                UT_CompressionType compressionType =
                                    UT_COMPRESSION_TYPE_NONE);

    /// Save the object the output stream
    bool                 save(UT_JSONWriter &os) const;

    /// Dump the value to stdout (same as save to cout)
    void                 dump() const;
    UT_StringHolder      toString() const;

    /// Get the type of data stored in the object
    SYS_NO_DISCARD_RESULT Type getType() const { return myType; }
    SYS_NO_DISCARD_RESULT bool isMap() const { return myType == JSON_MAP; }
    SYS_NO_DISCARD_RESULT bool isArray() const { return myType == JSON_ARRAY; }
    SYS_NO_DISCARD_RESULT bool isNull() const { return myType == JSON_NULL; }
    SYS_NO_DISCARD_RESULT bool isValueType() const
    {
        return !isMap() && !isArray();
    }

    /// Get the bool value.  Interprets integer/float as bool
    SYS_NO_DISCARD_RESULT bool getB() const;
    /// Get the integer value.  Intereprets bool/real as integer
    /// @note Real values are cast to integer.
    SYS_NO_DISCARD_RESULT int64 getI() const;
    /// Get the real value.  Interprets bool/int as reals.
    SYS_NO_DISCARD_RESULT fpreal64 getF() const;
    /// Get the string value. If the value is not a string it returns the empty
    /// string. Either check the type prior to calling this function or use
    /// import<>() if you need to tell if there was an error.
    SYS_NO_DISCARD_RESULT const UT_StringHolder& getString() const
    {
        const UT_StringHolder* v = getStringHolder();
        if (v != nullptr)
            return *v;
        return UT_StringHolder::theEmptyString;
    }

    /// Get the string value (may return a NULL pointer)
    SYS_NO_DISCARD_RESULT const char *getS() const;
    /// Return the string length (returns -1 if not a string)
    SYS_NO_DISCARD_RESULT int64 getSLength() const;
    /// Return the string value.
    SYS_NO_DISCARD_RESULT const UT_StringHolder *getStringHolder() const;

    SYS_NO_DISCARD_RESULT int32 get(const UT_StringRef& key, int32 def_value) const;
    SYS_NO_DISCARD_RESULT int64 get(const UT_StringRef& key, int64 def_value) const;
    SYS_NO_DISCARD_RESULT UT_StringHolder get(const UT_StringRef& key, const UT_StringRef& def_value) const;
    SYS_NO_DISCARD_RESULT UT_StringArray get(const UT_StringRef& key, const UT_StringArray& def_value) const;

    /// Get a key value
    SYS_NO_DISCARD_RESULT const char *getKey() const;
    /// Get the length of the key
    SYS_NO_DISCARD_RESULT int64 getKeyLength() const;
    /// Return a string holder for the key.
    SYS_NO_DISCARD_RESULT const UT_StringHolder *getKeyHolder() const;

    /// Get the array value (may return a NULL pointer)
    SYS_NO_DISCARD_RESULT UT_JSONValueArray     *getArray() const;
    /// Get the map value (may return a NULL pointer)
    SYS_NO_DISCARD_RESULT UT_JSONValueMap       *getMap() const;

    /// Get the "uniform" type of an array.  This will return:
    ///  - JSON_NULL:  The array is heterogeneous (or not an array)
    ///  - JSON_BOOL:  The array is only bool values
    ///  - JSON_INT:   The array is all bool or int values
    ///  - JSON_REAL:  The array is bool, int or real values
    ///  - JSON_STRING: The array is all strings
    SYS_NO_DISCARD_RESULT Type           getUniformArrayType() const;

    /// Extract a bool (returns false if type is invalid)
    SYS_FORCE_INLINE bool import(bool &result) const
    {
        switch (myType)
        {
            case JSON_BOOL:
                result = myData.myBool;
                return true;
            case JSON_INT:
                result = myData.myInt != 0;
                return true;
            case JSON_REAL:
                result = myData.myReal != 0;
                return true;
            default:
                break;
        }
        return false;
    }
    /// Extract an integer (returns false if type is invalid)
    SYS_FORCE_INLINE bool import(int64 &result) const
    {
        switch (myType)
        {
            case JSON_BOOL:
                result = myData.myBool ? 1 : 0;
                return true;
            case JSON_INT:
                result = myData.myInt;
                return true;
            case JSON_REAL:
                result = (int64)myData.myReal;
                return true;
            default:
                break;
        }
        return false;
    }
    /// Extract an float (returns false if type is invalid)
    SYS_FORCE_INLINE bool import(fpreal64 &result) const
    {
        switch (myType)
        {
            case JSON_BOOL:
                result = myData.myBool ? 1. : 0.;
                return true;
            case JSON_INT:
                result = myData.myInt;
                return true;
            case JSON_REAL:
                result = myData.myReal;
                return true;
            default:
                break;
        }
        return false;
    }
    /// Extract a string @b or key (returns false if type is invalid)
    bool                 import(UT_WorkBuffer &result) const;
    bool                 import(UT_StringHolder &result) const;
    /// Extract a tuple of integers from an JSON_Array.  If there aren't enough
    /// elements in the array, this method fails
    bool                 import(int64 *result, int size) const;
    /// Extract a tuple of floats from an JSON_Array.  If there aren't enough
    /// elements in the array, this method fails
    bool                 import(fpreal64 *result, int size) const;
    /// Extract a vector of integers from a JSON_Array
    bool                 import(UT_Array<int64> &array) const;
    /// Extract a vector of reals from a JSON_Array
    bool                 import(UT_Array<fpreal64> &array) const;
    /// Extract a vector of strings from a JSON_Array
    bool                 import(UT_StringArray &array) const;
    /// Extract a value from the object. Only applies to json objects.
    template <typename T>
    bool                 import(const UT_StringRef &key, T &reuslt) const;

    /// Returns whether the value can be interpreted as a number
    bool         isNumber() const
                 {
                    return  myType == JSON_REAL || myType == JSON_INT ||
                            myType == JSON_BOOL;
                 }

    /// Set value to a null
    void         setNull()      { clearValue(); }
    /// Set value to an bool
    void         setBool(bool v);
    /// Set value to an int
    void         setInt(int64 v);
    /// Set value to an int
    void         setReal(fpreal64 v);
    /// Set string.  If the length is not specified, the length of the string
    /// will be used.
    void         setString(const char *s, int64 length=-1)
                    { setStringType(s, length, JSON_STRING); }
    void         setString(const UT_StringHolder &s)
                    { setStringType(s, JSON_STRING); }
    /// Set string.  If the length is not specified, the length of the string
    /// will be used.
    void         setKey(const char *s, int64 length=-1)
                    { setStringType(s, length, JSON_KEY); }
    void         setKey(const UT_StringHolder &s)
                    { setStringType(s, JSON_KEY); }
    /// Set value to the array
    void         setArray(UT_JSONValueArray *array);
    /// Set value to the map
    void         setMap(UT_JSONValueMap *map);

    /// Start building an array from scratch. @see appendArray
    UT_JSONValueArray   *startArray();
    /// Add an element to an array (returns false if operation fails)
    /// The current value must be an array object
    bool         appendArray(const UT_JSONValue &v);

    /// Start building a map from scratch. @see appendMap
    UT_JSONValueMap     *startMap();
    /// Add an element to a map (returns false if operation fails)
    /// The current value must be a map object
    bool         appendMap(const UT_StringHolder &key, const UT_JSONValue &v);

    /// Adds a new map child to this value. The current value must
    /// be either an array or a map. If this value is an array,
    /// the map_key parameter is ignored. This is due to overly
    /// convoluted JSON syntax design.
    UT_JSONValueMap* addMapChild(const UT_StringHolder &map_key);

    /// Adds a new array child to this value. The current value must
    /// be either an array or a map. If this value is an array,
    /// the map_key parameter is ignored. This is due to overly
    /// convoluted JSON syntax design.
    UT_JSONValueArray* addArrayChild(const UT_StringHolder &map_key);

    /// Set json value as a json map.
    bool setAsMap();
    /// Set json value as a json array.
    bool setAsArray();

    /// @{
    /// Build a uniform array of values
    bool         setUniformArray(int nvalues, const int32 *data);
    bool         setUniformArray(int nvalues, const int64 *data);
    bool         setUniformArray(int nvalues, const fpreal16 *data);
    bool         setUniformArray(int nvalues, const fpreal32 *data);
    bool         setUniformArray(int nvalues, const fpreal64 *data);
    bool         setUniformArray(int nvalues, const UT_StringHolder *data);
    /// @}

    /// Used internally by UT_JSONValueMap
    SYS_NO_DISCARD_RESULT int                    getMapIndex() const
                         { return myMapIndex; }
    /// Used internally by UT_JSONValueMap
    void                 setMapIndex(int i)
                         { myMapIndex = i; }

    /// Used by UT_JSONValue parsing from a stream
    SYS_NO_DISCARD_RESULT int getSourceLine() const
                         { return mySourceLine; }
    SYS_NO_DISCARD_RESULT int getSourceOffset() const
                         { return mySourceOffset; }
    void                 setSourceOffset(int line, int offset)
                         { mySourceLine = line; mySourceOffset = offset; }

    /// {@
    /// Helper access operators.
    /// - operator() allow for the value to not exist.
    /// - operator[] does not allow for the value to not exist.
    SYS_NO_DISCARD_RESULT const UT_JSONValue* operator()(int64 i) const
    {
        return get(i);
    }
    SYS_NO_DISCARD_RESULT UT_JSONValue* operator()(int64 i)
    {
        return get(i);
    }
    SYS_NO_DISCARD_RESULT const UT_JSONValue* operator()(const UT_StringRef& k) const
    {
        return get(k);
    }
    SYS_NO_DISCARD_RESULT UT_JSONValue* operator()(const UT_StringRef& k)
    {
        return get(k);
    }
    SYS_NO_DISCARD_RESULT const UT_JSONValue& operator[](int64 i) const
    {
        // Matching std::vector where accessing out of bounds is undefined
        // behaviour. If bounds checking is necessary use operator().
        const UT_JSONValue* v = get(i);
        UT_ASSERT_P(v != nullptr);
        return *v;
    }
    SYS_NO_DISCARD_RESULT UT_JSONValue& operator[](int64 i)
    { 
        // Matching std::vector where accessing out of bounds is undefined
        // behaviour. If bounds checking is necessary use operator().   
        UT_JSONValue* v = get(i);
        UT_ASSERT_P(v != nullptr);
        return *v;
    }
    SYS_NO_DISCARD_RESULT UT_JSONValue& operator[](const UT_StringRef& k)
    {
        if (UT_JSONValue* v = get(k); v != nullptr)
            return *v;
        auto it = emplace(k, UT_JSONValue::JSON_NULL);
        return *it.first;
    }
    /// @}

    /// @brief Traverse the children of the current value.
    ///
    /// This class will iterate over all items in this value, whether they
    /// are in the form of an array or a map. For values with neither,
    /// it will return the current value itself.
    /// Note that the getKey() function is only available when this
    /// value is a map.
    ///
    /// Example:
    /// @code
    /// UT_JSONValue::traverser it;
    /// for (it = value.beginTraversal(); !it.atEnd(); ++it)
    /// @endcode
    class UT_API traverser
    {
        public:
            using difference_type = exint;
            using value_type = UT_JSONValue;
            using pointer = value_type*;
            using reference = value_type&;
            using iterator_category = std::forward_iterator_tag;

            traverser()
                : myValue(NULL),
                  myIsValid(false)
            {
                myCurrArrayPos = myNumArrayEntries = 0;
            }
            traverser(const traverser &src)
            {
                *this = src;
            }
            ~traverser() {}

            const traverser     &operator=(const traverser &src)
                        {
                            myValue = src.myValue;
                            myIsValid = src.myIsValid;
                            myCurrArrayPos = src.myCurrArrayPos;
                            myNumArrayEntries = src.myNumArrayEntries;
                            myValueType =  src.myValueType;
                            myMapKeys = src.myMapKeys;
                            return *this;
                        }

            /// ++iterator
            traverser   &operator++()    { advance(); return *this; }
            /// No post increment as it is harmful.

            bool operator==(const traverser &rhs) const
            {
                return myCurrArrayPos == rhs.myCurrArrayPos
                       && myIsValid == rhs.myIsValid;
            }
            bool operator!=(const traverser& rhs) const
            {
                return !(*this == rhs);
            }
            const UT_JSONValue& operator*() const
            {
                return *this->getValue();
            }
            UT_JSONValue& operator*()
            {
                return *this->getValue();
            }
            const UT_JSONValue* operator->() const
            {
                return getValue();
            }
            UT_JSONValue* operator->()
            {
                return getValue();
            }
            bool        atEnd() const   { return !myIsValid; }
            void        advance()
                        {
                            if(myValue && myIsValid)
                            {
                                if(myValueType == JSON_MAP)
                                {
                                    myCurrArrayPos++;
                                    if(myCurrArrayPos >= myMapKeys.entries())
                                        myIsValid = false;
                                }
                                else if(myValueType == JSON_ARRAY)
                                {
                                    myCurrArrayPos++;
                                    if(myCurrArrayPos >= myNumArrayEntries)
                                        myIsValid = false;
                                }
                                else
                                    // Any non-array, non-map values only
                                    // have one item.
                                    myIsValid = false;

                            }
                        }

            /// Returns the child value which corresponds to the current
            /// traversal position.
            UT_JSONValue        *getValue()
            {
                if (myValue && myIsValid)
                    return iteratorValue();
                return nullptr;
            }
            const UT_JSONValue* getValue() const
            {
                if (myValue && myIsValid)
                    return SYSconst_cast(this)->iteratorValue();
                return nullptr;
            }
            int64       getArrayIndex() const
            {
                if (myValue && myIsValid
                        && (myValueType == JSON_ARRAY || myValueType == JSON_MAP))
                {
                    return myCurrArrayPos;
                }
                return -1;
            }

            /// Deprecated in favour of UT_StringHolder method
            SYS_DEPRECATED(14.0) bool getKey(UT_String &key)
            {
                UT_StringHolder tmp;
                if (!getKey(tmp))
                    return false;
                key = tmp;
                return true;
            }
            /// Deprecated in favour of UT_StringHolder method
            SYS_DEPRECATED(14.0) bool getLowerCaseKey(UT_String &key)
            {
                UT_StringHolder tmp;
                if (!getLowerCaseKey(tmp))
                    return false;
                key = tmp;
                return true;
            }

            bool getKey(UT_StringHolder &key) const
            {
                if(myValue && myIsValid)
                {
                    if(myValueType == JSON_MAP)
                    {
                        key = myMapKeys(myCurrArrayPos);
                        return true;
                    }
                    else
                    {
                        key.clear();
                    }
                }
                else
                {
                    key.clear();
                }
                return false;
            }

            /// Get a lower case map key (for case insensitive maps)
            bool        getLowerCaseKey(UT_StringHolder &key)
                        {
                            if (getKey(key))
                            {
                                key = key.toLower();
                                return true;
                            }
                            return false;
                        }
        private:
             traverser(UT_JSONValue *value_in)
                 : myValue(value_in),
                   myIsValid(false)
             {
                 myCurrArrayPos = 0;
                 myNumArrayEntries = 0;
                 initData(value_in);
             }
             traverser(UT_JSONValue *value_in, exint start_idx)
                 : myValue(value_in), myIsValid(false), myCurrArrayPos(start_idx)
             {
                 myNumArrayEntries = 0;
                 initData(value_in);
             }
             // Outline these to fix dependencies on UT_JSONValueArray/Map
             void                initData(const UT_JSONValue *value_in);
             UT_JSONValue       *iteratorValue();

            UT_JSONValue        *myValue;
            UT_JSONValue::Type   myValueType;
            UT_StringArray       myMapKeys;
            int64                myCurrArrayPos;
            int64                myNumArrayEntries;
            bool                 myIsValid;

            friend class UT_JSONValue;
    };

    class UT_API indexed_traverser : public traverser
    {
    public:
        using difference_type = exint;
        using iterator_category = std::forward_iterator_tag;
        using reference = std::pair<exint, UT_JSONValue&>;
        using pointer = std::pair<exint, UT_JSONValue*>;

        explicit indexed_traverser(UT_JSONValue *v, exint end_len)
            : traverser(v, end_len)
        {
        }
        explicit indexed_traverser(UT_JSONValue *v) : traverser(v) {}

        using traverser::operator++;
        using traverser::operator==;
        using traverser::operator!=;

        reference operator*()
        {
                 return std::make_pair(
                         this->getArrayIndex(), std::ref(*this->getValue()));
        }
        pointer operator->()
        {
            return std::make_pair(this->getArrayIndex(), this->getValue());
        }

        const UT_JSONValue& value() const
        {
            return *getValue();
        }
    };

    class UT_API indexed_map_traverser : public traverser
    {
    public:
        using difference_type = exint;
        using iterator_category = std::forward_iterator_tag;
        using reference = std::tuple<exint, UT_StringHolder, UT_JSONValue&>;
        using pointer = std::tuple<exint, UT_StringHolder, UT_JSONValue*>;

        explicit indexed_map_traverser(UT_JSONValue *v, exint end_len)
            : traverser(v, end_len)
        {
        }
        explicit indexed_map_traverser(UT_JSONValue *v) : traverser(v) {}

        using traverser::operator++;
        using traverser::operator==;
        using traverser::operator!=;

        reference operator*()
        {
            UT_StringHolder key;
            getKey(key);
            return std::make_tuple(
                    this->getArrayIndex(), key, std::ref(*this->getValue()));
        }
        pointer operator->()
        {
            UT_StringHolder key;
            getKey(key);
            return std::make_tuple(
                    this->getArrayIndex(), key, this->getValue());
        }

        const UT_StringHolder &key() const
        {
            if (myValue && myIsValid)
            {
                if (myValueType == JSON_MAP)
                {
                    return myMapKeys(myCurrArrayPos);
                }
            }
            return UT_StringHolder::theEmptyString;
        }

        const UT_JSONValue& value() const
        {
            return *getValue();
        }
    };

    /// Helper traverser to retrieve the key/value on the contained map.
    /// Structured bindings are also offered with this type.
    class UT_API map_traverser : public traverser
    {
    public:
        using difference_type = exint;
        using value_type = map_traverser;
        using pointer = value_type *;
        using reference = value_type &;
        using iterator_category = std::forward_iterator_tag;

        explicit map_traverser(UT_JSONValue* v, exint end_len) :
            traverser(v, end_len)
        {}
        explicit map_traverser(UT_JSONValue* v) :
            traverser(v)
        {
        }

        using traverser::operator++;
        using traverser::operator==;
        using traverser::operator!=;

        reference operator*() { return *this; }
        pointer operator->() { return this; }

        const UT_StringHolder &key() const
        {
            if (myValue && myIsValid)
            {
                if (myValueType == JSON_MAP)
                {
                    return myMapKeys(myCurrArrayPos);
                }
            }
            return UT_StringHolder::theEmptyString;
        }

        const UT_JSONValue& value() const { return *getValue(); }
    };

    /// Used to iterate over a map from a json value.
    template <typename IteratorT>
    class json_proxy
    {
    public:
        IteratorT begin()
        {
            return IteratorT(myValue);
        }
        IteratorT end()
        {
            return IteratorT(myValue, myValue->count());
        }
        const IteratorT begin() const
        {
            json_proxy<IteratorT>* me = SYSconst_cast(this);
            return IteratorT(me->myValue);
        }
        const IteratorT end() const
        {
            json_proxy<IteratorT>* me = SYSconst_cast(this);
            return IteratorT(me->myValue, me->myValue->count());
        }
    private:
        explicit json_proxy(UT_JSONValue* v) :
            myValue(v)
        {}

        friend class UT_JSONValue;
        UT_JSONValue* myValue;
    };

    using map_proxy = json_proxy<map_traverser>;
    using indexed_proxy = json_proxy<indexed_traverser>;
    using indexed_map_proxy = json_proxy<indexed_map_traverser>;

    using const_iterator = const traverser;
    /// {@
    /// Iterate over contained values.
    /// Map: iterate over the json values of the map (excludes keys).
    /// Array: iterate over the json values in the array.
    /// Value: iterate over the single element contained in the json value.
    SYS_NO_DISCARD_RESULT traverser begin() { return traverser(this); }
    SYS_NO_DISCARD_RESULT traverser end() { return traverser(this, count()); }
    SYS_NO_DISCARD_RESULT const_iterator begin() const
    {
        return traverser(SYSconst_cast(this));
    }
    SYS_NO_DISCARD_RESULT const_iterator end() const
    {
        return traverser(SYSconst_cast(this), count());
    }
    SYS_NO_DISCARD_RESULT const_iterator cbegin() const
    {
        return traverser(SYSconst_cast(this));
    }
    SYS_NO_DISCARD_RESULT const_iterator cend() const
    {
        return traverser(SYSconst_cast(this), count());
    }
    /// @}
    /// {@
    /// Return a proxy map object to iterate over [key,value] on the contained
    /// map.
    SYS_NO_DISCARD_RESULT map_proxy items()
    {
        UT_ASSERT(isMap());
        return map_proxy(this);
    }
    SYS_NO_DISCARD_RESULT const map_proxy items() const
    {
        UT_ASSERT(isMap());
        return map_proxy(SYSconst_cast(this));
    }
    /// @}
    /// {@
    /// Return a proxy indexed object to iterate over [index, value] on the
    /// contained object.
    SYS_NO_DISCARD_RESULT indexed_proxy enumerate()
    {
        UT_ASSERT(isMap() || isArray());
        return indexed_proxy(this);
    }
    SYS_NO_DISCARD_RESULT const indexed_proxy enumerate() const
    {
        UT_ASSERT(isMap() || isArray());
        return indexed_proxy(SYSconst_cast(this));
    }
    SYS_NO_DISCARD_RESULT indexed_map_proxy enumerateMap()
    {
        UT_ASSERT(isMap());
        return indexed_map_proxy(this);
    }
    SYS_NO_DISCARD_RESULT const indexed_map_proxy enumerateMap() const
    {
        UT_ASSERT(isMap());
        return indexed_map_proxy(SYSconst_cast(this));
    }
    /// @}
    SYS_NO_DISCARD_RESULT traverser beginTraversal()    { return traverser(this); }

    /// Number of elements contained inside the json value.
    SYS_NO_DISCARD_RESULT exint count() const;

    /// Add a key/value pair to the contained map.
    std::pair<traverser, bool> insert(
            const UT_StringHolder &key,
            const UT_JSONValue &value);

    /// Add an entry to the contained map
    template <typename... ARGS>
    std::pair<traverser, bool> emplace(
            const UT_StringHolder &key,
            ARGS &&... args)
    {
        return insert(key, UT_JSONValue(std::forward<ARGS>(args)...));
    }

    /// Insert a json value to the back of the contained array.
    traverser append(const UT_JSONValue& v);
    /// Insert a json value to the back of the contained array.
    template <typename... ARGS>
    traverser emplace_back(ARGS &&... args)
    {
        return append(UT_JSONValue(std::forward<ARGS>(args)...));
    }

    /// {@
    /// Find the value contained in the json object by key. The json value must
    /// be a map object.
    traverser find(const UT_StringRef& key);
    const_iterator find(const UT_StringRef& key) const;
    /// @}

    /// {@
    /// Access a value by index. nullptr is returned if the element does not
    /// exist.
    UT_JSONValue* get(int64 idx);
    const UT_JSONValue* get(int64 idx) const;
    /// @}

    /// {@
    /// Lookup a value by key. The key is allowed to not exist.
    UT_JSONValue* get(const UT_StringRef& k);
    const UT_JSONValue* get(const UT_StringRef& k) const;
    /// @}

    /// {@
    /// Check if a key exists on the map.
    bool contains(const UT_StringRef& key) const;
    /// @}

    /// {@
    /// Remove a value by index.
    void remove(int64 index);
    /// @}

    /// {@
    /// Erase an element by map key.
    void erase(const UT_StringRef& k);
    /// @}

    /// Searches all children of this value recursively for another value
    /// with a child that contains the given map key set to the given value.
    SYS_NO_DISCARD_RESULT UT_JSONFindResult    findValueRecursive(
            const UT_StringHolder &map_key,
            const char *key_value);
    SYS_NO_DISCARD_RESULT UT_JSONFindResult    findParentValueRecursive(
            const UT_StringHolder &map_key,
            const char *key_value);

    /// Removes NULL values from all arrays recursively.
    /// Note that maps are currently unsupported, and null values will
    /// not be removed from them.
    void removeNullValuesRecursive();

    /// Compute a hash
    SYS_NO_DISCARD_RESULT SYS_HashType  hash() const;
    /// @{
    /// Test equality
    SYS_NO_DISCARD_RESULT bool  operator==(const UT_JSONValue &src) const;
    SYS_NO_DISCARD_RESULT bool  operator!=(const UT_JSONValue &src) const
                        { return !(*this == src); }
    /// @}

private:
    void                 clearValue();
    void                 copyFrom(const UT_JSONValue &s);
    void                 setStringType(const char *s, int64 l, Type t);
    void                 setStringType(const UT_StringHolder &s, Type t);
    union {
        bool             myBool;
        int64            myInt;
        fpreal64         myReal;
    } myData;
    union {
        // NOTE:  Keep the pointers and scalars separate.  The string is stored
        // as a pointer and a length so that null characters may be contained.
        UT_JSONValueArray       *myArray;
        UT_JSONValueMap         *myMap;
    } myPointers;
    UT_StringHolder      myString;
    int                  myMapIndex;            // Location in a map
    int                  mySourceLine;          // Line in source stream
    int                  mySourceOffset;        // Offset in source line
    Type                 myType;
};

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

// Structured Bindings Support
template <std::size_t N, std::enable_if_t<N == 0, int> = 0>
auto
get(const UT_JSONValue::map_traverser &m)
        -> decltype(m.key())
{
    return m.key();
}
// Structured Bindings Support
template <std::size_t N, std::enable_if_t<N == 1, int> = 0>
auto
get(const UT_JSONValue::map_traverser &m) -> decltype(m.value())
{
    return m.value();
}

template <std::size_t N, std::enable_if_t<N==0, int> = 0>
auto
get(const UT_JSONValue::indexed_traverser& it) -> decltype(it.getArrayIndex())
{
    return it.getArrayIndex();
}

template <std::size_t N, std::enable_if_t<N == 1, int> = 0>
auto
get(const UT_JSONValue::indexed_traverser& it) -> decltype(it.value())
{
    return it.value();
}

template <std::size_t N, std::enable_if_t<N==0, int> = 0>
auto
get(const UT_JSONValue::indexed_map_traverser& it) -> decltype(it.getArrayIndex())
{
    return it.getArrayIndex();
}

template <std::size_t N, std::enable_if_t<N == 1, int> = 0>
auto
get(const UT_JSONValue::indexed_map_traverser& it) -> decltype(it.key())
{
    return it.key();
}

template <std::size_t N, std::enable_if_t<N == 2, int> = 0>
auto
get(const UT_JSONValue::indexed_map_traverser& it) -> decltype(it.value())
{
    return it.value();
}

namespace std
{
template <>
struct tuple_size<UT_JSONValue::map_traverser>
    : public std::integral_constant<std::size_t, 2>
{
};
template <std::size_t N>
struct tuple_element<N, UT_JSONValue::map_traverser>
{
    using type = decltype(get<N>(std::declval<UT_JSONValue::map_traverser>()));
};

template <>
struct tuple_size<UT_JSONValue::indexed_traverser>
    : public std::integral_constant<std::size_t, 2>
{
};
template <std::size_t N>
struct tuple_element<N, UT_JSONValue::indexed_traverser>
{
    using type = decltype(get<N>(std::declval<UT_JSONValue::indexed_traverser>()));
};

template <>
struct tuple_size<UT_JSONValue::indexed_map_traverser>
    : public std::integral_constant<std::size_t, 3>
{
};
template <std::size_t N>
struct tuple_element<N, UT_JSONValue::indexed_map_traverser>
{
    using type = decltype(get<N>(
            std::declval<UT_JSONValue::indexed_map_traverser>()));
};
} // namespace std

#endif