UT_JSONValueMap.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_JSONValueMap.h ( UT Library, C++)
 *
 * COMMENTS:    The order is maintained as objects are added to the map
 */

#ifndef __UT_JSONValueMap__
#define __UT_JSONValueMap__

#include "UT_API.h"
#include "UT_Array.h"
#include "UT_ArrayStringMap.h"
#include "UT_StringArray.h"
#include "UT_StringHolder.h"
#include "UT_JSONValue.h"
#include <SYS/SYS_AtomicInt.h>
#include <SYS/SYS_Compiler.h>
#include <SYS/SYS_Types.h>
#include <SYS/SYS_Hash.h>

#include <stdexcept>

class UT_JSONValueArray;
class UT_JSONWriter;

/// @brief UT_JSONValueMap stores a map/dictionary of UT_JSONValue objects
///
/// UT_JSONValueMap stores a map of UT_JSONValue objects.  Unlike a standard
/// Houdini UT_StringMap, this object maintains the sort order in which
/// objects were added.
///
/// @see UT_JSONValue, UT_JSONValueArray
class UT_API UT_JSONValueMap
{
public:
     UT_JSONValueMap();
    ~UT_JSONValueMap();

    /// Reference count (for shared maps).
    void                 bumpRef(int d)
                         {
                             if (!myRef.add(d))
                                 delete this;
                         }
    /// Get the number of references to this map.
    SYS_NO_DISCARD_RESULT int getRef() const    { return myRef.relaxedLoad(); }

    /// Maps are typically stored as shared pointers.  This method will make a
    /// unique copy. May return "this" (if the reference count is already unique).
    UT_JSONValueMap     *makeUnique() const;

    /// Save to an output stream
    bool                 save(UT_JSONWriter &os) const;

    /// Dump to stdout (same as save to std::cout)
    void                 dump() const;

    /// Get the list of keys
    int64                getKeys(UT_StringArray &keys) const;

    /// Get a list of the keys.  However, rather than duplicating the string
    /// values, this method simply keeps shallow references.  While it's more
    /// efficient, it's also relies on the fact that the map will not change
    /// while the string array exists.
    int64                getKeyReferences(UT_StringArray &keys) const;

    /// Return the number of entries in the map
    SYS_NO_DISCARD_RESULT int64 entries() const
                         { return myArray.entries(); }
    SYS_NO_DISCARD_RESULT int64 size() const
                         { return myArray.entries(); }

    /// Clear the entries in the map.
    void                 clear();

    /// Access const entry by index
    SYS_NO_DISCARD_RESULT const UT_JSONValue    *operator()(int64 i) const
                         { return get(i); }
    /// Access entry by index
    SYS_NO_DISCARD_RESULT UT_JSONValue  *operator()(int64 i)
                         { return get(i); }
    /// Access const entry by name (may be NULL pointer if k is not a key)
    SYS_NO_DISCARD_RESULT const UT_JSONValue    *operator()(const UT_StringRef &k) const
                         { return get(k); }
    /// Access entry by name (may be NULL pointer if k is not a key)
    SYS_NO_DISCARD_RESULT UT_JSONValue  *operator()(const UT_StringRef &k)
                         { return get(k); }

    /// Access const entry by index
    SYS_NO_DISCARD_RESULT const UT_JSONValue    *operator[](int64 i) const
                         { return get(i); }
    /// Access entry by index
    SYS_NO_DISCARD_RESULT UT_JSONValue  *operator[](int64 i)
                         { return get(i); }
    /// Access const entry by name (may be NULL pointer if k is not a key)
    SYS_NO_DISCARD_RESULT const UT_JSONValue    *operator[](const UT_StringRef &k) const
                         { return get(k); }
    /// Access entry by name (may be NULL pointer if k is not a key)
    SYS_NO_DISCARD_RESULT UT_JSONValue  *operator[](const UT_StringRef &k)
                         { return get(k); }

    /// Access a const entry by index
    SYS_NO_DISCARD_RESULT const UT_JSONValue    *get(int64 i) const
                         { return myArray(i); }
    /// Access an entry by index
    SYS_NO_DISCARD_RESULT UT_JSONValue  *get(int64 i)
                         { return myArray(i); }
    /// Access const entry by name (may be NULL pointer if k is not a key)
    SYS_NO_DISCARD_RESULT const UT_JSONValue    *get(const UT_StringRef &k) const;
    /// Access entry by name (may be NULL pointer if k is not a key)
    SYS_NO_DISCARD_RESULT UT_JSONValue  *get(const UT_StringRef &k);

    /// Access entry by name. If not found the default value is returned.
    SYS_NO_DISCARD_RESULT int32 get(const UT_StringRef& key, int32 def_value) const;
    /// Access entry by name. If not found the default value is returned.
    SYS_NO_DISCARD_RESULT int64 get(const UT_StringRef& key, int64 def_value) const;
    /// Access entry by name. If not found the default value is returned.
    SYS_NO_DISCARD_RESULT UT_StringHolder get(const UT_StringRef& key, const UT_StringRef& def_value) const;
    /// Access entry by name. If not found the default value is returned.
    SYS_NO_DISCARD_RESULT UT_StringArray get(const UT_StringRef& key, const UT_StringArray& def_value) const;

    /// Access const object entry by name (may be NULL pointer if k is not a key)
    /// This is a convenience function to get() if we know the key is an object.
    SYS_NO_DISCARD_RESULT  const UT_JSONValueMap *getObject(const UT_StringRef& k) const;
    /// Access object entry by name (may be NULL pointer if k is not a key)
    /// This is a convenience function to get() if we know the key is an object.
    SYS_NO_DISCARD_RESULT UT_JSONValueMap* getObject(const UT_StringRef& k);
    /// Access const array entry by name (may be NULL pointer if k is not a key)
    /// This is a convenience function to get() if we know the key is an array.
    SYS_NO_DISCARD_RESULT const UT_JSONValueArray* getArray(const UT_StringRef& k) const;
    /// Access array entry by name (may be NULL pointer if k is not a key)
    /// This is a convenience function to get() if we know the key is an array.
    SYS_NO_DISCARD_RESULT UT_JSONValueArray* getArray(const UT_StringRef& k);

    struct InsertResult
    {
        UT_JSONValue    *operator->() { return myValue; }
        UT_JSONValue    &operator*() { return *myValue; }
        int64            index() const { return myIndex; }
        UT_JSONValue    *value() const { return myValue; }

        bool             inserted() const { return second; }
        bool             replaced() const { return !second; }

        int64            myIndex;
        UT_JSONValue    *myValue;
        // second is a bool that mimics the std::map::insert() return value.
        // It's true if the value was inserted.  However, when it's false, the
        // value in the map was @b REPLACED
        bool             second;
    };

    /// Add key/value pair to the map.  If the key already exists, the previous
    /// value will be deleted.
    InsertResult        insert(const UT_StringHolder& key,
                                    const UT_JSONValue& value);

    /// Emplace a value into the map
    template <typename... ARGS>
    InsertResult        emplace(const UT_StringHolder &key, ARGS&&... args)
    {
        return insert(key, UT_JSONValue(std::forward<ARGS>(args)...));
    }

    /// Remove key/value pair from the map.
    /// Do nothing if the key does not exist.
    void                 remove(const UT_StringHolder &key);

    /// Rename a key in the map.
    /// Do nothing if the old key does not exist.
    /// If the old key exists and another entry uses the new key
    /// then remove the other entry and rename the entry with the old key.
    void                 rename(
                            const UT_StringHolder &old_key,
                            const UT_StringHolder &new_key);

    /// Adds a new array child to this map.
    UT_JSONValueArray   *addArrayChild(const UT_StringHolder &map_key);

    /// Adds a new map child to this map.
    UT_JSONValueMap     *addMapChild(const UT_StringHolder &map_key);

    /// Key/Value imports. See UT_JSONValue for all available import types.
    /// Returns false if the key isn't in the map, or if the import from the
    /// UT_JSONValue fails.
    template <typename T>
    bool        import(const UT_StringRef &key, T &result) const;

    SYS_NO_DISCARD_RESULT SYS_HashType  hash() const;
    /// @{
    /// Check equality
    SYS_NO_DISCARD_RESULT bool operator==(const UT_JSONValueMap &arr) const;
    SYS_NO_DISCARD_RESULT bool operator!=(const UT_JSONValueMap &arr) const
                            { return !(*this == arr); }
    /// @}


private:
    using BaseMap = UT_ArrayStringMap<UT_JSONValue *>;

    SYS_NO_DISCARD_RESULT BaseMap::value_type* getItemAt_(exint index);

    /// Iterator functionality so we can utilize C++11 range base for loops.
    /// C++17 has deprecated inheritance from std::iterator.
    /// We could easily promote myMap's iterators here but then we wouldn't
    /// respect the 'append' order.
public:
    class iterator
    {
    public:
        iterator(exint _num, UT_JSONValueMap *_obj) : myIndex(_num), myObj(_obj){}
        iterator& operator++()
        {
            if (myIndex < myObj->myArray.entries())
                ++myIndex;
            return *this;
        }
        iterator operator++(int)
        {
            iterator     retval = *this; ++(*this);
            return retval;
        }
        iterator& operator--()
        {
            if (myIndex > 0)
                --myIndex;
            return *this;
        }
        iterator operator--(int)
        {
            iterator     retval = *this; --(*this);
            return retval;
        }
        bool operator==(const iterator &other) const {return (myObj == other.myObj) && (myIndex == other.myIndex);}
        bool operator!=(const iterator &other) const {return !(*this == other);}
        BaseMap::value_type &operator*()
        {
            return *myObj->getItemAt_(myIndex);
        }
        BaseMap::value_type *operator->()
        {
            return myObj->getItemAt_(myIndex);
        }

        // iterator traits
        using difference_type = exint;
        using value_type = BaseMap::value_type;
        using pointer = const exint*;
        using reference = const exint&;
        using iterator_category = std::forward_iterator_tag;
    private:
        exint            myIndex = 0;
        UT_JSONValueMap *myObj;
    };
    iterator begin() { return iterator(0, this); }
    iterator end() { return iterator(this->myArray.entries(), this); }
    using const_iterator = const iterator;
    const_iterator begin() const { return iterator(0, SYSconst_cast(this)); }
    const_iterator end() const { return iterator(this->myArray.entries(), SYSconst_cast(this)); }

private:
    UT_Array<UT_JSONValue *>             myArray;
    BaseMap                              myMap;
    SYS_AtomicInt32                      myRef;

    friend class iterator;
};

#endif