diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html index 07675ab9d4d..2709b2298d8 100644 --- a/docs/ProgrammersManual.html +++ b/docs/ProgrammersManual.html @@ -97,8 +97,8 @@
  • Important iterator invalidation semantics to be aware of -

    Written by Dinakar Dhurjati - Chris Lattner, and +

    Written by Chris Lattner, + Dinakar Dhurjati, and Joel Stanley

    @@ -235,7 +235,20 @@ checks to see if the operand is of the specified type, and if so, returns a pointer to it (this operator does not work with references). If the operand is not of the correct type, a null pointer is returned. Thus, this works very much like the dynamic_cast operator in C++, and should be used in the same -circumstances. An example is:

    +circumstances. Typically, the dyn_cast<> operator is used in an +if statement or some other flow control statement like this:

    + +

    +  if (AllocationInst *AI = dyn_cast<AllocationInst>(Val)) {
+    ...
+  }
+

    + +This form of the if statement effectively combines together a call to +isa<> and a call to cast<> into one statement, +which is very convenient.

    + +Another common example is:

       // Loop over all of the phi nodes in a basic block
@@ -244,12 +257,36 @@ circumstances.  An example is:
    
     cerr << *PN;

    -Note that you should not use the dyn_cast<> operator in a series -of chained if statements, use an visitor instead... FIXME: continue.

    +Note that the dyn_cast<> operator, like C++'s +dynamic_cast or Java's instanceof operator, can be abused. In +particular you should not use big chained if/then/else blocks to check +for lots of different variants of classes. If you find yourself wanting to do +this, it is much cleaner and more efficient to use the InstVisitor class to +dispatch over the instruction type directly.

    +

    cast_or_null<>: + +
    The cast_or_null<> operator works just like the +cast<> operator, except that it allows for a null pointer as an +argument (which it then propogates). This can sometimes be useful, allowing you +to combine several null checks into one.

    + + +

    dyn_cast_or_null<>: + +
    The dyn_cast_or_null<> operator works just like the +dyn_cast<> operator, except that it allows for a null pointer as +an argument (which it then propogates). This can sometimes be useful, allowing +you to combine several null checks into one.

    + +These five templates can be used with any classes, whether they have a v-table +or not. To add support for these templates, you simply need to add +classof static methods to the class you are interested casting to. +Describing this is currently outside the scope of this document, but there are +lots of examples in the LLVM sourcebase.

    @@ -1352,6 +1389,6 @@ pointer to the parent Function. Chris Lattner -Last modified: Mon Sep 9 19:38:23 CDT 2002 +Last modified: Tue Sep 10 10:19:56 CDT 2002