From 096603ada5559414e4a923ebd2c2ca0524b42325 Mon Sep 17 00:00:00 2001 From: Reid Spencer Date: Wed, 26 May 2004 08:41:35 +0000 Subject: [PATCH] Added a section on the SymbolTable class. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@13786 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/ProgrammersManual.html | 266 +++++++++++++++++++++++++++++++++--- 1 file changed, 247 insertions(+), 19 deletions(-) diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html index ec97e332f67..3628aa935ca 100644 --- a/docs/ProgrammersManual.html +++ b/docs/ProgrammersManual.html @@ -86,31 +86,29 @@ with another Value - -
  • The SymbolTable class
    • -
  • The ilist and iplist classes - -
    • -
  • Important iterator invalidation semantics to be aware of.
    • - +
  • The Argument class
    • + + +
  • The SymbolTable class
    • +
  • The ilist and iplist classes + +
    • +
  • Important iterator invalidation semantics to be aware of.
    • @@ -204,6 +202,10 @@ STL.
  • Bjarne Stroustrup's C++ Page
    • +
  • +Bruce Eckel's Thinking in C++, 2nd ed. Volume 2 Revision 4.0 (even better, get +the book).
    • +

    You are also encouraged to take a look at the + +

    + The SymbolTable class +
    +
    +

    This class provides a symbol table that the +Function and +Module classes use for naming definitions. The symbol table can +provide a name for any Value or +Type. SymbolTable is an abstract data +type. It hides the data it contains and provides access to it through a +controlled interface.

    + +

    To use the SymbolTable well, you need to understand the +structure of the information it holds. The class contains two +std::map objects. The first, pmap, is a map of +Type* to maps of name (std::string) to Value*. +The second, tmap, is a map of names to Type*. Thus, Values +are stored in two-dimensions and accessed by Type and name. Types, +however, are stored in a single dimension and accessed only by name.

    + +

    The interface of this class provides three basic types of operations: +

      +
    1. Accessors. Accessors provide read-only access to information + such as finding a value for a name with the + lookup method.
      2. +
    2. Mutators. Mutators allow the user to add information to the + SymbolTable with methods like + insert.
      3. +
    3. Iterators. Iterators allow the user to traverse the content + of the symbol table in well defined ways, such as the method + type_begin.
      4. +
    + +

    Accessors

    +
    +
    Value* lookup(const Type* Ty, const std::string& name) const: +
    +
    The lookup method searches the type plane given by the + Ty parameter for a Value with the provided name. + If a suitable Value is not found, null is returned.
    + +
    Type* lookupType( const std::string& name) const:
    +
    The lookupType method searches through the types for a + Type with the provided name. If a suitable Type + is not found, null is returned.
    + +
    bool hasTypes() const:
    +
    This function returns true if an entry has been made into the type + map.
    + +
    bool isEmpty() const:
    +
    This function returns true if both the value and types maps are + empty
    + +
    std::string get_name(const Value*) const:
    +
    This function returns the name of the Value provided or the empty + string if the Value is not in the symbol table.
    + +
    std::string get_name(const Type*) const:
    +
    This function returns the name of the Type provided or the empty + string if the Type is not in the symbol table.
    +
    + +

    Mutators

    +
    +
    void insert(Value *Val):
    +
    This method adds the provided value to the symbol table. The Value must + have both a name and a type which are extracted and used to place the value + in the correct type plane under the value's name.
    + +
    void insert(const std::string& Name, Value *Val):
    +
    Inserts a constant or type into the symbol table with the specified + name. There can be a many to one mapping between names and constants + or types.
    + +
    void insert(const std::string& Name, Type *Typ):
    +
    Inserts a type into the symbol table with the specified name. There + can be a many-to-one mapping between names and types. This method + allows a type with an existing entry in the symbol table to get + a new name.
    + +
    void remove(Value* Val):
    +
    This method removes a named value from the symbol table. The + type and name of the Value are extracted from \p N and used to + lookup the Value in the correct type plane. If the Value is + not in the symbol table, this method silently ignores the + request.
    + +
    void remove(Type* Typ):
    +
    This method removes a named type from the symbol table. The + name of the type is extracted from \P T and used to look up + the Type in the type map. If the Type is not in the symbol + table, this method silently ignores the request.
    + +
    Value* remove(const std::string& Name, Value *Val):
    +
    Remove a constant or type with the specified name from the + symbol table.
    + +
    Type* remove(const std::string& Name, Type* T):
    +
    Remove a type with the specified name from the symbol table. + Returns the removed Type.
    + +
    Value *value_remove(const value_iterator& It):
    +
    Removes a specific value from the symbol table. + Returns the removed value.
    + +
    bool strip():
    +
    This method will strip the symbol table of its names leaving + the type and values.
    + +
    void clear():
    +
    Empty the symbol table completely.
    +
    + +

    Iteration

    +

    The following functions describe three types of iterators you can obtain +the beginning or end of the sequence for both const and non-const. It is +important to keep track of the different kinds of iterators. There are +three idioms worth pointing out:

    + + + + + + + + + + + + + + +
    UnitsIteratorIdiom
    Planes Of name/Value mapsPI
    +for (SymbolTable::plane_const_iterator PI = ST.plane_begin(),
+PE = ST.plane_end(); PI != PE; ++PI ) {
+  PI->first // This is the Type* of the plane
+  PI->second // This is the SymbolTable::ValueMap of name/Value pairs
+
    All name/Type PairsTI
    +for (SymbolTable::type_const_iterator TI = ST.type_begin(),
+     TE = ST.type_end(); TI != TE; ++TI )
+  TI->first  // This is the name of the type
+  TI->second // This is the Type* value associated with the name
+
    name/Value pairs in a planeVI
    +for (SymbolTable::value_const_iterator VI = ST.value_begin(SomeType),
+     VE = ST.value_end(SomeType); VI != VE; ++VI )
+  VI->first  // This is the name of the Value
+  VI->second // This is the Value* value associated with the name
+
    +

    Using the recommended iterator names and idioms will help you avoid +making mistakes. Of particular note, make sure that whenever you use +value_begin(SomeType) that you always compare the resulting iterator +with value_end(SomeType) not value_end(SomeOtherType) or else you +will loop infinitely.

    + +
    + +
    plane_iterator plane_begin():
    +
    Get an iterator that starts at the beginning of the type planes. + The iterator will iterate over the Type/ValueMap pairs in the + type planes.
    + +
    plane_const_iterator plane_begin() const:
    +
    Get a const_iterator that starts at the beginning of the type + planes. The iterator will iterate over the Type/ValueMap pairs + in the type planes.
    + +
    plane_iterator plane_end():
    +
    Get an iterator at the end of the type planes. This serves as + the marker for end of iteration over the type planes.
    + +
    plane_const_iterator plane_end() const:
    +
    Get a const_iterator at the end of the type planes. This serves as + the marker for end of iteration over the type planes.
    + +
    value_iterator value_begin(const Type *Typ):
    +
    Get an iterator that starts at the beginning of a type plane. + The iterator will iterate over the name/value pairs in the type plane. + Note: The type plane must already exist before using this.
    + +
    value_const_iterator value_begin(const Type *Typ) const:
    +
    Get a const_iterator that starts at the beginning of a type plane. + The iterator will iterate over the name/value pairs in the type plane. + Note: The type plane must already exist before using this.
    + +
    value_iterator value_end(const Type *Typ):
    +
    Get an iterator to the end of a type plane. This serves as the marker + for end of iteration of the type plane. + Note: The type plane must already exist before using this.
    + +
    value_const_iterator value_end(const Type *Typ) const:
    +
    Get a const_iterator to the end of a type plane. This serves as the + marker for end of iteration of the type plane. + Note: the type plane must already exist before using this.
    + +
    type_iterator type_begin():
    +
    Get an iterator to the start of the name/Type map.
    + +
    type_const_iterator type_begin() cons:
    +
    Get a const_iterator to the start of the name/Type map.
    + +
    type_iterator type_end():
    +
    Get an iterator to the end of the name/Type map. This serves as the + marker for end of iteration of the types.
    + +
    type_const_iterator type_end() const:
    +
    Get a const-iterator to the end of the name/Type map. This serves + as the marker for end of iteration of the types.
    + +
    plane_const_iterator find(const Type* Typ ) const:
    +
    This method returns a plane_const_iterator for iteration over + the type planes starting at a specific plane, given by \p Ty.
    + +
    plane_iterator find( const Type* Typ :
    +
    This method returns a plane_iterator for iteration over the + type planes starting at a specific plane, given by \p Ty.
    + +
    const ValueMap* findPlane( const Type* Typ ) cons:
    +
    This method returns a ValueMap* for a specific type plane. This + interface is deprecated and may go away in the future.
    +
    +
    +
    @@ -1806,3 +2032,5 @@ arguments. An argument has a pointer to the parent Function.

    + -- 2.34.1