UT/UT_SymbolTable.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:
 *      Side Effects Software Inc
 *      477 Richmond Street West
 *      Toronto, Ontario
 *      Canada   M5V 3E7
 *      416-504-9876
 *
 * NAME:        UT_SymbolTable.h
 *
 * COMMENTS:
 */

#ifndef __UT_SymbolTable_h__
#define __UT_SymbolTable_h__

#include "UT_API.h"
#include <stdio.h>
#include <SYS/SYS_Types.h>
#include "UT_Thing.h"
#include "UT_SymList.h"

class UT_String;

class UT_API UT_SymbolTable
{
public:
    explicit UT_SymbolTable();
    virtual ~UT_SymbolTable();

    void         addSymbol(const char *symbol, UT_Thing data);
    int          findSymbol(const char *symbol, UT_Thing *datap) const;

    int          contains(const char *symbol) const
    { UT_Thing value; return findSymbol(symbol, &value); }

    template <typename T>
    T           *findPointer(const char *symbol) const
    {
        UT_Thing thing;
        if (!findSymbol(symbol, &thing))
            return NULL;
        return thing.template asPointer<T>();
    }

    int          findOrCreateSymbol(const char *symbol, UT_Thing **datap);
    int          deleteSymbol(const char *symbol);
    void         clear();

    const char  *addSymbolAndGetReference(const char *symbol, UT_Thing data);


    unsigned     entries() const { return myNbrEntries; }
    bool         empty() const { return !myNbrEntries; }
    int          size() const { return mySize; }

    // Retrieve an entry in the table by name, creating it if it doesn't
    // already exist.
    UT_Thing    &operator[](const char *symbol);

    // Call this method when you're adding entries to a table inside a loop
    // and you know how many entries you'll be adding.
    void         reserveTableSize(int size);

    // The table will automatically rebuild itself to keep the load factor
    // within the specified range.  A minimum load factor of 0 means that
    // the table will never shrink when elements are deleted from it.
    float        getMaxLoadFactor() const { return myMaxLoadFactor; }
    void         setMaxLoadFactor(float max_load_factor);
    float        getMinLoadFactor() const { return myMinLoadFactor; }
    void         setMinLoadFactor(float min_load_factor);

    // Merge the specified table with ourselves.
    void        mergeTable(const UT_SymbolTable &table);

    // "getStringReference" returns a pointer to the actual string that
    // is maintained in the symbol table. This can be used to implement
    // a shared string symbol table.
    const char  *getStringReference(const char *symbol);

    // Create a new name derived from symbol such that both old and new name
    // have the same base, but different suffixes. A suffix consists of a 
    // string of digits >= 1. If symbol is not encountered in the table, the
    // method returns 0; otherwise, it allocates space for a string which you
    // should delete when done with.
    char        *newName(const char *symbol) const;

    // Given the supplied symbol string, return a new numbered prefix string
    // in unique_prefix, that does not occur as a prefix to any symbol in the
    // table and shares the same base prefix (string minus trailing digits).
    bool         getUniqueNumberedPrefix(const char *symbol,
                                         UT_String &unique_prefix) const;

    void         outputStats(FILE *output) const;
    void         dumpTable(FILE *output) const;

    int64        getMemUsage(bool only_this=false) const;

    // "traverse" invokes the given function with every member of the
    // symbol table. The order of traversal is undefined. If the function
    // returns a non-zero value the traversal continues. If it returns
    // zero then traversal stops. The return value is zero if the traversal
    // was interupted and one otherwise.
    //
    // Call traverseConst() if you will not be removing things from the table
    // while traversing, and traverse() if you might be.  If you call traverse()
    // and add something to the table, you may or may not encounter it later
    // in the traversal.
    int          traverseConst(
                          int (*function)(UT_Thing &, const char *, void *),
                          void *data) const;
    int          traverse(int (*function)(UT_Thing &, const char *, void *),
                          void *data);

    class UT_API traverser
    {
        public:
            traverser()
                : myCurrList(0), myEndList(0) { }
            traverser(const traverser &src)
                         { *this = src; }
            ~traverser() { }

            UT_Thing    &thing() { return myCurrSym.thing(); }
            const char  *name() const { return myCurrSym.name(); }

            int          operator==(const traverser &cmp) const
                         {
                             return ((!myCurrList && !cmp.myCurrList) ||
                                     ((myCurrList == cmp.myCurrList) &&
                                      (myCurrSym == cmp.myCurrSym)));
                         }
            int          operator!=(const traverser &cmp) const
                         { return !(*this == cmp); }

            bool        atEnd() const
                         {
                             return !myCurrList;
                         }

            traverser   &operator++()
                         {
                             if( ++myCurrSym == myCurrList->end() )
                             {
                                 ++myCurrList;
                                 advanceToNextList();
                             }
                             return *this;
                         }

            const traverser     &operator=(const traverser &src)
                         {
                             myCurrList = src.myCurrList;
                             myEndList = src.myEndList;
                             myCurrSym = src.myCurrSym;
                             return *this;
                         }

        private:
            traverser(const UT_SymList *list, const UT_SymList *endlist)
                : myCurrList(list), myEndList(endlist)
                         { advanceToNextList(); }

            void         advanceToNextList()
                         {
                             while( myCurrList != myEndList &&
                                    myCurrList->begin() == myCurrList->end() )
                                 ++myCurrList;
                             if( myCurrList == myEndList )
                                 myCurrList = 0;
                             else
                                 myCurrSym = myCurrList->begin();
                         }

            const UT_SymList            *myCurrList;
            const UT_SymList            *myEndList;
            UT_SymList::traverser        myCurrSym;

            friend class UT_SymbolTable;
    };

    traverser    begin() const
    {
        if (myTable)
            return traverser(myTable, myTable + mySize);
        return traverser();     // same as end()
    }
    traverser    end() const { return traverser(); }

private:
#ifndef INTEL_COMPILER  
        // Intel's compiler throws an internal compiler error
        // in BM_OpHandleLink.C if we include this constructor
        // here. Hence, it'll be excluded in these cases for now.
        UT_SymbolTable(const UT_SymbolTable&) {  }
#endif
    UT_SymbolTable& operator=(const UT_SymbolTable&);

private:
    enum UT_AdjustType { UT_ADJUST_INCREASE, UT_ADJUST_DECREASE };
    void         adjustTableSize(UT_AdjustType adjust_type);
    void         allocateTableOfNewSize(int size);

    // Data:
    UT_SymList  *myTable;
    int          mySize;
    unsigned int myNbrEntries;
    fpreal       myMaxLoadFactor;
    fpreal       myMinLoadFactor;
    bool         myIsTraversing;
};


class UT_API UT_SnapshotTable : public UT_SymbolTable
{
public:
              UT_SnapshotTable() : UT_SymbolTable() {}
     virtual ~UT_SnapshotTable();

    virtual void     setSnapshotWatch(UT_Thing watch) = 0;
    virtual void     snapshot(const char *symbol) = 0;
    virtual void     updateWatch(const char *symbol) = 0;
    void             getSnapshot(const char *symbol, UT_Thing *data) const
                        {
                            if (!findSymbol(symbol, data))
                                data->value.longv = 0L;
                        }

protected:
    virtual void     getWatch(UT_Thing *watch) const = 0;
private:
};

#endif

---