which points to temporary (stack allocated) objects. Twines can be implicitly
constructed as the result of the plus operator applied to strings (i.e., a C
strings, an <tt>std::string</tt>, or a <tt>StringRef</tt>). The twine delays the
-actual concatentation of strings until it is actually required, at which point
+actual concatenation of strings until it is actually required, at which point
it can be efficiently rendered directly into a character array. This avoids
unnecessary heap allocation involved in constructing the temporary results of
string concatenation. See
</div>
<div class="doc_text">
-<p><tt>ilist</tt>s have another speciality that must be considered. To be a good
+<p><tt>ilist</tt>s have another specialty that must be considered. To be a good
citizen in the C++ ecosystem, it needs to support the standard container
operations, such as <tt>begin</tt> and <tt>end</tt> iterators, etc. Also, the
<tt>operator--</tt> must work correctly on the <tt>end</tt> iterator in the
<div class="doc_text">
-<p>SmallPtrSet has all the advantages of SmallSet (and a SmallSet of pointers is
-transparently implemented with a SmallPtrSet), but also supports iterators. If
+<p>SmallPtrSet has all the advantages of <tt>SmallSet</tt> (and a <tt>SmallSet</tt> of pointers is
+transparently implemented with a <tt>SmallPtrSet</tt>), but also supports iterators. If
more than 'N' insertions are performed, a single quadratically
probed hash table is allocated and grows as needed, providing extremely
efficient access (constant time insertion/deleting/queries with low constant
factors) and is very stingy with malloc traffic.</p>
-<p>Note that, unlike std::set, the iterators of SmallPtrSet are invalidated
+<p>Note that, unlike <tt>std::set</tt>, the iterators of <tt>SmallPtrSet</tt> are invalidated
whenever an insertion occurs. Also, the values visited by the iterators are not
visited in sorted order.</p>
</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<llvm::Instruction *, 16>(B->begin(), B->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>
<!--_______________________________________________________________________-->
</pre>
</div>
-<p>Alternately, it's common to have an instance of the <a
+<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.</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
<tt>Value</tt>s are used by it. The list of all <tt>Value</tt>s used by a
<tt>User</tt> is known as a <i>use-def</i> chain. Instances of class
</pre>
</div>
-<!--
- def-use chains ("finding all users of"): Value::use_begin/use_end
- use-def chains ("finding all values used"): User::op_begin/op_end [op=operand]
--->
+<p>Declaring objects as <tt>const</tt> is an important tool of enforcing
+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.</p>
</div>
<div class="doc_text">
<ul>
- <li><tt>bool isInteger() const</tt>: Returns true for any integer type.</li>
+ <li><tt>bool isIntegerTy() const</tt>: Returns true for any integer type.</li>
- <li><tt>bool isFloatingPoint()</tt>: Return true if this is one of the two
+ <li><tt>bool isFloatingPointTy()</tt>: Return true if this is one of the five
floating point types.</li>
<li><tt>bool isAbstract()</tt>: Return true if the type is abstract (contains
<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>
<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>
projects / oota-llvm.git / blobdiff