Improve explanation.

[oota-llvm.git] / docs / ProgrammersManual.html

diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html
index a2d32d4e9857234698c56c70567ff5e45eae1b91..46fd33f40d552827589b83ebfbc05c70a1539053 100644 (file)
--- a/docs/ProgrammersManual.html
+++ b/docs/ProgrammersManual.html
@@ -1843,6 +1843,21 @@ void printNextInstruction(Instruction* inst) {
 </pre>
 </div>
 
+<p>Unfortunately, these implicit conversions come at a cost; they prevent
+these iterators from conforming to standard iterator conventions, and thus
+from being usable with standard algorithms and containers. For example, they
+prevent the following code, where <tt>B</tt> is a <tt>BasicBlock</tt>,
+from compiling:</p>
+
+<div class="doc_code">
+<pre>
+  llvm::SmallVector&lt;llvm::Instruction *, 16&gt;(B-&gt;begin(), B-&gt;end());
+</pre>
+</div>
+
+<p>Because of this, these implicit conversions may be removed some day,
+and <tt>operator*</tt> changed to return a pointer instead of a reference.</p>
+
 </div>
 
 <!--_______________________________________________________________________-->
@@ -1962,9 +1977,9 @@ for (Value::use_iterator i = F-&gt;use_begin(), e = F-&gt;use_end(); i != e; ++i
 </pre>
 </div>
 
-Note that dereferencing a <tt>Value::use_iterator</tt> is not a very cheap
+<p>Note that dereferencing a <tt>Value::use_iterator</tt> is not a very cheap
 operation. Instead of performing <tt>*i</tt> above several times, consider
-doing it only once in the loop body and reusing its result.
+doing it only once in the loop body and reusing its result.</p>
 
 <p>Alternatively, it's common to have an instance of the <a
 href="/doxygen/classllvm_1_1User.html">User Class</a> and need to know what
@@ -1986,12 +2001,13 @@ for (User::op_iterator i = pi-&gt;op_begin(), e = pi-&gt;op_end(); i != e; ++i)
 </div>
 
 <p>Declaring objects as <tt>const</tt> is an important tool of enforcing
-mutation free algorithms (such as analyses etc.). For this purpose above
+mutation free algorithms (such as analyses, etc.). For this purpose above
 iterators come in constant flavors as <tt>Value::const_use_iterator</tt>
 and <tt>Value::const_op_iterator</tt>.  They automatically arise when
 calling <tt>use/op_begin()</tt> on <tt>const Value*</tt>s or
 <tt>const User*</tt>s respectively.  Upon dereferencing, they return
-<tt>const Use*</tt>s. Otherwise the above patterns remain unchanged.
+<tt>const Use*</tt>s. Otherwise the above patterns remain unchanged.</p>
+
 </div>
 
 <!--_______________________________________________________________________-->
@@ -3064,7 +3080,7 @@ the <tt>lib/VMCore</tt> directory.</p>
   <dt><tt><a name="FunctionType">FunctionType</a></tt></dt>
   <dd>Subclass of DerivedTypes for function types.
     <ul>
-      <li><tt>bool isVarArg() const</tt>: Returns true if its a vararg
+      <li><tt>bool isVarArg() const</tt>: Returns true if it's a vararg
       function</li>
       <li><tt> const Type * getReturnType() const</tt>: Returns the
       return type of the function.</li>
@@ -3282,7 +3298,7 @@ simplifies the representation and makes it easier to manipulate.</p>
 <ul>
   <li><tt>Value::use_iterator</tt> - Typedef for iterator over the
 use-list<br>
-    <tt>Value::use_const_iterator</tt> - Typedef for const_iterator over
+    <tt>Value::const_use_iterator</tt> - Typedef for const_iterator over
 the use-list<br>
     <tt>unsigned use_size()</tt> - Returns the number of users of the
 value.<br>