dictionary.h

Go to the documentation of this file.

//
// Copyright 2016 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
#ifndef PXR_BASE_VT_DICTIONARY_H
#define PXR_BASE_VT_DICTIONARY_H
 
 
#include "pxr/pxr.h"
#include "pxr/base/vt/api.h"
#include "pxr/base/vt/traits.h"
#include "pxr/base/vt/value.h"
 
#include "pxr/base/tf/diagnostic.h"
#include "pxr/base/tf/functionRef.h"
#include "pxr/base/tf/hash.h"
#include "pxr/base/tf/mallocTag.h"
 
#include <initializer_list>
#include <iosfwd>
#include <map>
#include <memory>
#include <optional>
 
PXR_NAMESPACE_OPEN_SCOPE
 
// VtDictionary can compose over itself and must support value transforms in
// general, since it can contain values that support transforms.
class VtDictionary;
VT_VALUE_TYPE_CAN_COMPOSE(VtDictionary);
VT_VALUE_TYPE_CAN_TRANSFORM(VtDictionary);
 
 
class VtDictionary {
    typedef std::map<std::string, VtValue, std::less<>> _Map;
    std::unique_ptr<_Map> _dictMap;
 
public:
    // The iterator class, used to make both const and non-const iterators.
    // Currently only forward traversal is supported. In order to support lazy
    // allocation, VtDictionary's Map pointer (_dictMap) must be nullable,
    // but that would break the VtDictionary iterators. So instead, VtDictionary
    // uses this Iterator class, which considers an iterator to an empty
    // VtDictionary to be the same as an iterator at the end of a VtDictionary
    // (i.e. if Iterator's _dictMap pointer is null, that either means that the
    // VtDictionary is empty, or the Iterator is at the end of a VtDictionary
    // that contains values).
    template<class UnderlyingMapPtr, class UnderlyingIterator>
    class Iterator {
    public:
        using iterator_category = std::bidirectional_iterator_tag;
        using value_type = typename UnderlyingIterator::value_type;
        using reference = typename UnderlyingIterator::reference;
        using pointer = typename UnderlyingIterator::pointer;
        using difference_type = typename UnderlyingIterator::difference_type;
 
 
        // Default constructor creates an Iterator equivalent to end() (i.e.
        // UnderlyingMapPtr is null)
        Iterator() = default;
 
        // Copy constructor (also allows for converting non-const to const).
        template <class OtherUnderlyingMapPtr, class OtherUnderlyingIterator>
        Iterator(Iterator<OtherUnderlyingMapPtr,
                          OtherUnderlyingIterator> const &other)
            : _underlyingIterator(other._underlyingIterator),
              _underlyingMap(other._underlyingMap) {}
 
        reference operator*() const { return *_underlyingIterator; }
        pointer operator->() const { return _underlyingIterator.operator->(); }
 
        Iterator& operator++() {
            increment();
            return *this;
        }
 
        Iterator operator++(int) {
            Iterator result = *this;
            increment();
            return result;
        }
 
        Iterator& operator--() {
            --_underlyingIterator;
            return *this;
        }
 
        Iterator operator--(int) {
            Iterator result = *this;
            --_underlyingIterator;
            return result;
        }
 
        template <class OtherUnderlyingMapPtr, class OtherUnderlyingIterator>
        bool operator==(const Iterator<OtherUnderlyingMapPtr,
                                       OtherUnderlyingIterator>& other) const {
            return equal(other);
        }
 
        template <class OtherUnderlyingMapPtr, class OtherUnderlyingIterator>
        bool operator!=(const Iterator<OtherUnderlyingMapPtr,
                                       OtherUnderlyingIterator>& other) const {
            return !equal(other);
        }
 
    private:
 
        // Private constructor allowing the find, begin and insert methods
        // to create and return the proper Iterator.
        Iterator(UnderlyingMapPtr m, UnderlyingIterator i)
            : _underlyingIterator(i),
              _underlyingMap(m) {
                if (m && i == m->end())
                    _underlyingMap = nullptr;
            }
       
        friend class VtDictionary;
 
        UnderlyingIterator GetUnderlyingIterator(UnderlyingMapPtr map)
        const {
            TF_AXIOM(!_underlyingMap || _underlyingMap == map);
            return (!_underlyingMap) ? map->end() : _underlyingIterator;
        }
 
        // Fundamental functionality to implement the iterator.
        // These will be invoked these as necessary to implement
        // the full iterator public interface.
 
        // Increments the underlying iterator, and sets the underlying map to
        // null when the iterator reaches the end of the map. 
        void increment() {
            if (!_underlyingMap) {
                TF_FATAL_ERROR("Attempted invalid increment operation on a "
                    "VtDictionary iterator");
                return;
            }
            if (++_underlyingIterator == _underlyingMap->end()) {
                _underlyingMap = nullptr;
            }
        }
 
        // Equality comparison. Iterators are considered equal if:
        // 1) They both point to empty VtDictionaries
        // 2) They both point to the end() of a VtDictionary
        // - or-
        // 3) They both point to the same VtDictionary and their
        //    underlying iterators are the same
        // In cases 1 and 2 above, _underlyingMap will be null
        template <class OtherUnderlyingMapPtr, class OtherUnderlyingIterator>
        bool equal(Iterator<OtherUnderlyingMapPtr,
                            OtherUnderlyingIterator> const& other) const {
            if (_underlyingMap == other._underlyingMap)
                if (!_underlyingMap ||
                    (_underlyingIterator == other._underlyingIterator))
                    return true;
            return false;
        }
 
        UnderlyingIterator _underlyingIterator;
        UnderlyingMapPtr _underlyingMap = nullptr;
    };
 
    TF_MALLOC_TAG_NEW("Vt", "VtDictionary");
 
    typedef _Map::key_type key_type;
    typedef _Map::mapped_type mapped_type;
    typedef _Map::value_type value_type;
    typedef _Map::allocator_type allocator_type;
    typedef _Map::size_type size_type;
 
    typedef Iterator<_Map*, _Map::iterator> iterator;
    typedef Iterator<_Map const*, _Map::const_iterator> const_iterator;
 
    VtDictionary() {}
 
    explicit VtDictionary(int size) {}
 
    template<class _InputIterator>
    VtDictionary(_InputIterator f, _InputIterator l){
        TfAutoMallocTag2 tag("Vt", "VtDictionary::VtDictionary (range)");
        insert(f, l);
    }
 
    VT_API
    VtDictionary(VtDictionary const& other);
 
    VT_API
    VtDictionary(VtDictionary && other) = default;
 
    VT_API
    VtDictionary(std::initializer_list<value_type> init);
 
    VT_API
    VtDictionary& operator=(VtDictionary const& other);
 
    VT_API
    VtDictionary& operator=(VtDictionary && other) = default;
 
    VT_API
    VtValue& operator[](const std::string& key);
 
    VT_API
    size_type count(const std::string& key) const;
 
    VT_API
    size_type count(const char* key) const;
 
    VT_API
    size_type erase(const std::string& key);
 
    VT_API
    iterator erase(iterator it);
 
    VT_API
    iterator erase(iterator f, iterator l);
 
    VT_API
    void clear();
 
    VT_API
    iterator find(const std::string& key);
 
    VT_API
    iterator find(const char* key);
 
    VT_API
    const_iterator find(const std::string& key) const;
 
    VT_API
    const_iterator find(const char* key) const;
 
    VT_API
    iterator begin();
 
    VT_API
    const_iterator begin() const;
 
    VT_API
    iterator end();
    
    VT_API
    const_iterator end() const;
 
    VT_API
    size_type size() const;
        
    VT_API
    bool empty() const;
    
    VT_API
    void swap(VtDictionary& dict); 
 
    // Global overload for swap for unqualified calls in generic code.
    friend void swap(VtDictionary &lhs, VtDictionary &rhs) {
        lhs.swap(rhs);
    }
 
    friend size_t hash_value(VtDictionary const &dict) {
        // Hash empty dict as zero.
        if (dict.empty())
            return 0;
        // Otherwise hash the map.
        return TfHash()(*dict._dictMap);
    }
 
    template<class _InputIterator>
    void insert(_InputIterator f, _InputIterator l) {
        TfAutoMallocTag2 tag("Vt", "VtDictionary::insert (range)");
        if (f != l) {
            _CreateDictIfNeeded();
            _dictMap->insert(f, l);
        }
    }
 
    VT_API
    std::pair<iterator, bool> insert(const value_type& obj);
 
    template<class... Args>
    std::pair<iterator, bool>
    try_emplace(const key_type& key, 
                Args&&... args)
    {
        TfAutoMallocTag tag("Vt", "VtDictionary::try_emplace");
        _CreateDictIfNeeded();
        std::pair<_Map::iterator, bool> inserted = 
            _dictMap->try_emplace(key, std::forward<Args>(args)...);
        return {iterator(_dictMap.get(), inserted.first), inserted.second};
    }
 
    template<class... Args>
    std::pair<iterator, bool>
    try_emplace(key_type&& key, 
                Args&&... args)
    {
        TfAutoMallocTag tag("Vt", "VtDictionary::try_emplace");
        _CreateDictIfNeeded();
        std::pair<_Map::iterator, bool> inserted = 
            _dictMap->try_emplace(std::move(key), std::forward<Args>(args)...);
        return {iterator(_dictMap.get(), inserted.first), inserted.second};
    }
 
    template<class... Args>
    std::pair<iterator, bool> 
    insert_or_assign(const key_type& key, 
                     Args&&... args)
    {
        TfAutoMallocTag tag("Vt", "VtDictionary::insert_or_assign");
        _CreateDictIfNeeded();
        std::pair<_Map::iterator, bool> inserted = 
            _dictMap->insert_or_assign(key, std::forward<Args>(args)...);
        return {iterator(_dictMap.get(), inserted.first), inserted.second};
    }
 
    template<class... Args>
    std::pair<iterator, bool> 
    insert_or_assign(key_type&& key, 
                     Args&&... args)
    {
        TfAutoMallocTag tag("Vt", "VtDictionary::insert_or_assign");
        _CreateDictIfNeeded();
        std::pair<_Map::iterator, bool> inserted = 
            _dictMap->insert_or_assign(
                std::move(key), std::forward<Args>(args)...);
        return {iterator(_dictMap.get(), inserted.first), inserted.second};
    }
 
    VT_API
    VtValue const *
    GetValueAtPath(std::string const &keyPath,
                   char const *delimiters = ":") const;
 
    VT_API
    VtValue const *
    GetValueAtPath(std::vector<std::string> const &keyPath) const;
 
    VT_API
    void SetValueAtPath(std::string const &keyPath,
                        VtValue const &value, char const *delimiters = ":");
 
    VT_API
    void SetValueAtPath(std::vector<std::string> const &keyPath,
                        VtValue const &value);
 
    VT_API
    void EraseValueAtPath(std::string const &keyPath,
        char const *delimiters = ":");
 
    VT_API
    void EraseValueAtPath(std::vector<std::string> const &keyPath);
 
private:
    void
    _SetValueAtPathImpl(std::vector<std::string>::const_iterator curKeyElem,
                        std::vector<std::string>::const_iterator keyElemEnd,
                        VtValue const &value);
 
    void _EraseValueAtPathImpl(
        std::vector<std::string>::const_iterator curKeyElem,
        std::vector<std::string>::const_iterator keyElemEnd);
 
    VT_API
    void _CreateDictIfNeeded();
 
};
 
VT_API bool operator==(VtDictionary const &, VtDictionary const &);
VT_API bool operator!=(VtDictionary const &, VtDictionary const &);
 
VT_API  std::ostream &operator<<(std::ostream &, VtDictionary const &);
 
//
// Return a const reference to an empty VtDictionary.
//
VT_API VtDictionary const &VtGetEmptyDictionary();
 
template <typename T>
bool
VtDictionaryIsHolding( const VtDictionary &dictionary,
                       const std::string &key )
{
    VtDictionary::const_iterator i = dictionary.find(key);
    if ( i == dictionary.end() ) {
        return false;
    }
 
    return i->second.IsHolding<T>();
}
 
template <typename T>
bool
VtDictionaryIsHolding( const VtDictionary &dictionary,
                       const char *key )
{
    VtDictionary::const_iterator i = dictionary.find(key);
    if ( i == dictionary.end() ) {
        return false;
    }
 
    return i->second.IsHolding<T>();
}
 
 
template <typename T>
const T &
VtDictionaryGet( const VtDictionary &dictionary,
                 const std::string &key )
{
    VtDictionary::const_iterator i = dictionary.find(key);
    if (ARCH_UNLIKELY(i == dictionary.end())) {
        TF_FATAL_ERROR("Attempted to get value for key '" + key +
                       "', which is not in the dictionary.");
    }
 
    return i->second.Get<T>();
}
 
template <typename T>
const T &
VtDictionaryGet( const VtDictionary &dictionary,
                 const char *key )
{
    VtDictionary::const_iterator i = dictionary.find(key);
    if (ARCH_UNLIKELY(i == dictionary.end())) {
        TF_FATAL_ERROR("Attempted to get value for key '%s', "
                       "which is not in the dictionary.", key);
    }
 
    return i->second.Get<T>();
}
 
 
// This is an internal holder class that is used in the version of
// VtDictionaryGet that takes a default.
template <class T>
struct Vt_DefaultHolder {
    explicit Vt_DefaultHolder(T const &t) : val(t) {}    
    T const &val;
};
 
// This internal class has a very unusual assignment operator that returns an
// instance of Vt_DefaultHolder, holding any type T.  This is used to get the
// "VtDefault = X" syntax for VtDictionaryGet.
struct Vt_DefaultGenerator {
    template <class T>
    Vt_DefaultHolder<T> operator=(T const &t) {
        return Vt_DefaultHolder<T>(t);
    }
};
 
// This is a global stateless variable used to get the VtDefault = X syntax in
// VtDictionaryGet.
extern VT_API Vt_DefaultGenerator VtDefault;
 
template <class T, class U>
T VtDictionaryGet( const VtDictionary &dictionary,
                   const std::string &key,
                   Vt_DefaultHolder<U> const &def )
{
    VtDictionary::const_iterator i = dictionary.find(key);
    if (i == dictionary.end() || !i->second.IsHolding<T>())
        return def.val;
    return i->second.UncheckedGet<T>();
}
 
template <class T, class U>
T VtDictionaryGet( const VtDictionary &dictionary,
                   const char *key,
                   Vt_DefaultHolder<U> const &def )
{
    VtDictionary::const_iterator i = dictionary.find(key);
    if (i == dictionary.end() || !i->second.IsHolding<T>())
        return def.val;
    return i->second.UncheckedGet<T>();
}
 
 
 
VT_API VtDictionary
VtDictionaryOver(const VtDictionary &strong, const VtDictionary &weak,
                 bool coerceToWeakerOpinionType = false);
 
VT_API void
VtDictionaryOver(VtDictionary *strong, const VtDictionary &weak,
                 bool coerceToWeakerOpinionType = false);
 
VT_API void
VtDictionaryOver(const VtDictionary &strong, VtDictionary *weak,
                 bool coerceToWeakerOpinionType = false);
 
VT_API VtDictionary
VtDictionaryOverRecursive(const VtDictionary &strong, const VtDictionary &weak);
 
VT_API void
VtDictionaryOverRecursive(VtDictionary *strong, const VtDictionary &weak);
 
VT_API void
VtDictionaryOverRecursive(const VtDictionary &strong, VtDictionary *weak);
 
struct VtDictionaryHash {
    inline size_t operator()(VtDictionary const &dict) const {
        return hash_value(dict);
    }
};
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif /* PXR_BASE_VT_DICTIONARY_H */