UT/UT_AssocArray.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.
 *
 * Produced by:
 *      Joe Drew
 *      Side Effects Software Inc
 *      123 Front Street West, Suite 1401
 *      Toronto, Ontario
 *      Canada   M5J 2M2
 *      416-504-9876
 *
 * NAME:        UT_AssocArray.h (UT Library, C++)
 *
 * COMMENTS:
 */

#ifndef __UT_AssocArray__
#define __UT_AssocArray__

#include "UT_API.h"


#ifdef WIN32
    #include <hash_map>
    using stdext::hash_map;
#endif

#if defined(LINUX) || defined(MBSD)
    #include <ext/hash_map>
    using __gnu_cxx::hash_map;

    namespace __gnu_cxx
    {
        template<typename T>
        struct hash<T *>
        {
            size_t operator()(T *x) const 
            { return reinterpret_cast<size_t>(x); }
        };
    };
#endif

template<typename Key, typename Value>
class UT_AssocArray
{
public:
    /// This allows you to type UT_AssocArray<Key, Value::iterator.
    typedef typename hash_map<Key, Value>::iterator iterator;
    typedef typename hash_map<Key, Value>::const_iterator const_iterator;

     UT_AssocArray() {}
    ~UT_AssocArray() {}

    /// How many key-value pairs this associative array contains.
    unsigned     entries() const
                 { return myHashMap.size(); }

    /// Whether this associative array contains exactly zero key-value pairs.
    bool         empty() const
                 { return myHashMap.empty(); }

    /// Remove all key-value pairs from this array.
    void         clear()
                 { myHashMap.clear();   }

    /// As with other UT_.*Arrays, square bracket operators "check bounds," 
    /// allowing you to retrieve an entry in the array, creating the entry
    /// if it doesn't already exist.
    /// No const version of this exists - just use () if you need constness.
    Value       &operator[](const Key & key)
                 {
                     return myHashMap[key];
                 }

    /// Round brackets do not check bounds, and simply assume that you know
    /// the element already exists in the array.
    const Value &operator()(const Key & key) const
                 {
                    typename hash_map<Key, Value>::const_iterator elem = myHashMap.find(key);
                    UT_ASSERT_P(elem != myHashMap.end());
                    return elem->second;
                 }
    Value       &operator()(const Key & key)
                 {
                    typename hash_map<Key, Value>::const_iterator elem = myHashMap.find(key);
                    UT_ASSERT_P(elem != myHashMap.end());
                    return elem->second;
                 }

    /// Set a key's value to a particular value.
    void         set(const Key & key, const Value & data)
                 {
                     if (myHashMap.find(key) != myHashMap.end())
                     {
                         // An element with this key already exists.
                     }
                     myHashMap[key] = data;
                 }

    /// See if a particular key has a value in this array. Returns false if
    /// the key has no value.
    /// Use this instead of operator[] if you just want to test for the
    /// existence of a key's value.
    bool         find(const Key & key, Value & value) const
                 {
                    const_iterator elem = myHashMap.find(key);
                    if (elem != myHashMap.end())
                    {
                        value = elem->second;
                        return true;
                    }
                    return false;
                 }

    /// Instead of copying the Value, this will simply return the iterator.
    /// Useful for cases where the copy constructor for Value is ill-defined.
    const_iterator find(const Key &key) const
                 { return myHashMap.find(key); }

    /// Remove a key-value pair from this associative array. Returns false
    /// if none existed.
    bool         remove(const Key & key)
                 { return myHashMap.erase(key) != 0; }

    /// Iterators. For those not familiar with the STL, to visit every element
    /// in this array, do the following:
    /// \code
    /// typedef UT_AssocArray<Key, Value> arrayType;
    /// arrayType array;
    /// for (arrayType::iterator it = array.begin(); it != array.end(); ++it)
    /// {
    ///         Key k = it->first;
    ///         Value v = it->second;
    /// }
    /// \endcode
    iterator     begin()
                 { return myHashMap.begin(); }
    iterator     end()
                 { return myHashMap.end(); }

    const_iterator begin() const
                 { return myHashMap.begin(); }
    const_iterator end() const
                 { return myHashMap.end(); }

private:
    hash_map<Key, Value> myHashMap;
};

#endif

---