[Doc] Modernize programmers manual

[Prazek]

Summary

Fixed bunch of for loops to range based for loop
and bunch of rendundat types with auto.

[Prazek]

moved * to the right

[mehdi_amini]

LGTM.

[kparzysz]

docs/ProgrammersManual.rst

2265 ↗

(On Diff #89673)

BB.size()

[Prazek]

Small fixes.

[Prazek]

docs/ProgrammersManual.rst

2265 ↗

(On Diff #89673)

thanks, missed that

[Prazek]

other changes to comments nearby changed code

[Prazek]

docs/ProgrammersManual.rst

2267–2271 ↗

(On Diff #89686)

Mehdi, is it fine if I will delete this? The example doesn't contain the iterator now, and I would expect someone who would use the iterator to know how iterators works.

[mehdi_amini]

docs/ProgrammersManual.rst

2267–2271 ↗

(On Diff #89686)

Fine with me.

llvm/trunk/docs/ProgrammersManual.rst

 It's quite common to have a ``Function`` instance that you'd like to transform
 in some way; in particular, you'd like to manipulate its ``BasicBlock``\ s.  To
 facilitate this, you'll need to iterate over all of the ``BasicBlock``\ s that
 constitute the ``Function``.  The following is an example that prints the name
 of a ``BasicBlock`` and the number of ``Instruction``\ s it contains:
 
 .. code-block:: c++
 
-  // func is a pointer to a Function instance
-  for (Function::iterator i = func->begin(), e = func->end(); i != e; ++i)
+  Function &Func = ...
+  for (BasicBlock &BB : Func)
     // Print out the name of the basic block if it has one, and then the
     // number of instructions that it contains
-    errs() << "Basic block (name=" << i->getName() << ") has "
-               << i->size() << " instructions.\n";
-
-Note that i can be used as if it were a pointer for the purposes of invoking
-member functions of the ``Instruction`` class.  This is because the indirection
-operator is overloaded for the iterator classes.  In the above code, the
-expression ``i->size()`` is exactly equivalent to ``(*i).size()`` just like
-you'd expect.
+    errs() << "Basic block (name=" << BB.getName() << ") has "
+               << BB.size() << " instructions.\n";
 
 .. _iterate_basicblock:
 
 Iterating over the ``Instruction`` in a ``BasicBlock``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Just like when dealing with ``BasicBlock``\ s in ``Function``\ s, it's easy to
 iterate over the individual instructions that make up ``BasicBlock``\ s.  Here's
 a code snippet that prints out each instruction in a ``BasicBlock``:
 
 .. code-block:: c++
 
-  // blk is a pointer to a BasicBlock instance
-  for (BasicBlock::iterator i = blk->begin(), e = blk->end(); i != e; ++i)
+  BasicBlock& BB = ...
+  for (Instruction &I : BB)
      // The next statement works since operator<<(ostream&,...)
      // is overloaded for Instruction&
-     errs() << *i << "\n";
+     errs() << I << "\n";
 
 
 However, this isn't really the best way to print out the contents of a
 ``BasicBlock``!  Since the ostream operators are overloaded for virtually
 anything you'll care about, you could have just invoked the print routine on the
-basic block itself: ``errs() << *blk << "\n";``.
+basic block itself: ``errs() << BB << "\n";``.
 
 .. _iterate_insiter:
 
 Iterating over the ``Instruction`` in a ``Function``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 If you're finding that you commonly iterate over a ``Function``'s
 ``BasicBlock``\ s and then that ``BasicBlock``'s ``Instruction``\ s,
.. code-block:: c++
 
   Function* targetFunc = ...;
 
   class OurFunctionPass : public FunctionPass {
     public:
       OurFunctionPass(): callCounter(0) { }
 
       virtual runOnFunction(Function& F) {
-        for (Function::iterator b = F.begin(), be = F.end(); b != be; ++b) {
-          for (BasicBlock::iterator i = b->begin(), ie = b->end(); i != ie; ++i) {
-            if (CallInst* callInst = dyn_cast<CallInst>(&*i)) {
+        for (BasicBlock &B : F) {
+          for (Instruction &I: B) {
+            if (auto *CallInst = dyn_cast<CallInst>(&I)) {
               // We know we've encountered a call instruction, so we
               // need to determine if it's a call to the
               // function pointed to by m_func or not.
-              if (callInst->getCalledFunction() == targetFunc)
+              if (CallInst->getCalledFunction() == targetFunc)
                 ++callCounter;
             }
           }
         }
       }
 
     private:
       unsigned callCounter;

 routines defined in ``"llvm/IR/CFG.h"``.  Just use code like this to
 iterate over all predecessors of BB:
 
 .. code-block:: c++
 
   #include "llvm/IR/CFG.h"
   BasicBlock *BB = ...;
 
-  for (pred_iterator PI = pred_begin(BB), E = pred_end(BB); PI != E; ++PI) {
-    BasicBlock *Pred = *PI;
+  for (BasicBlock *Pred : predecessors(BB)) {
     // ...
   }
 
-Similarly, to iterate over successors use ``succ_iterator/succ_begin/succ_end``.
+Similarly, to iterate over successors use ``successors``.
 
 .. _simplechanges:
 
 Making simple changes
 ---------------------
 
 There are some primitive transformation operations present in the LLVM
 infrastructure that are worth knowing about.  When performing transformations,
 it's fairly common to manipulate the contents of basic blocks.  This section
 describes some of the common methods for doing so and gives example code.
 
 .. _schanges_creating:
 
 Creating and inserting new ``Instruction``\ s
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 *Instantiating Instructions*
 
 Creation of ``Instruction``\ s is straight-forward: simply call the constructor
 for the kind of instruction to instantiate and provide the necessary parameters.
 For example, an ``AllocaInst`` only *requires* a (const-ptr-to) ``Type``.  Thus:
 
 .. code-block:: c++
 
-  AllocaInst* ai = new AllocaInst(Type::Int32Ty);
+  auto *ai = new AllocaInst(Type::Int32Ty);
 
 will create an ``AllocaInst`` instance that represents the allocation of one
 integer in the current stack frame, at run time.  Each ``Instruction`` subclass
 is likely to have varying default parameters which change the semantics of the
 instruction, so refer to the `doxygen documentation for the subclass of
 Instruction <http://llvm.org/doxygen/classllvm_1_1Instruction.html>`_ that
 you're interested in instantiating.
 
 *Naming values*
 
 It is very useful to name the values of instructions when you're able to, as
 this facilitates the debugging of your transformations.  If you end up looking
 at generated LLVM machine code, you definitely want to have logical names
 associated with the results of instructions!  By supplying a value for the
 ``Name`` (default) parameter of the ``Instruction`` constructor, you associate a
 logical name with the result of the instruction's execution at run time.  For
 example, say that I'm writing a transformation that dynamically allocates space
 for an integer on the stack, and that integer is going to be used as some kind
 of index by some other code.  To accomplish this, I place an ``AllocaInst`` at
 the first point in the first ``BasicBlock`` of some ``Function``, and I'm
 intending to use it within the same ``Function``.  I might do:
 
 .. code-block:: c++
 
-  AllocaInst* pa = new AllocaInst(Type::Int32Ty, 0, "indexLoc");
+  auto *pa = new AllocaInst(Type::Int32Ty, 0, "indexLoc");
 
 where ``indexLoc`` is now the logical name of the instruction's execution value,
 which is a pointer to an integer on the run time stack.
 
 *Inserting instructions*
 
 There are essentially three ways to insert an ``Instruction`` into an existing
 sequence of instructions that form a ``BasicBlock``:
 
 * Insertion into an explicit instruction list
 
   Given a ``BasicBlock* pb``, an ``Instruction* pi`` within that ``BasicBlock``,
   and a newly-created instruction we wish to insert before ``*pi``, we do the
   following:
 
   .. code-block:: c++
 
       BasicBlock *pb = ...;
       Instruction *pi = ...;
-      Instruction *newInst = new Instruction(...);
+      auto *newInst = new Instruction(...);
 
       pb->getInstList().insert(pi, newInst); // Inserts newInst before pi in pb
 
   Appending to the end of a ``BasicBlock`` is so common that the ``Instruction``
   class and ``Instruction``-derived classes provide constructors which take a
   pointer to a ``BasicBlock`` to be appended to.  For example code that looked
   like:
 
   .. code-block:: c++
 
     BasicBlock *pb = ...;
-    Instruction *newInst = new Instruction(...);
+    auto *newInst = new Instruction(...);
 
     pb->getInstList().push_back(newInst); // Appends newInst to pb
 
   becomes:
 
   .. code-block:: c++
 
     BasicBlock *pb = ...;
-    Instruction *newInst = new Instruction(..., pb);
+    auto *newInst = new Instruction(..., pb);
 
   which is much cleaner, especially if you are creating long instruction
   streams.
 
 * Insertion into an implicit instruction list
 
   ``Instruction`` instances that are already in ``BasicBlock``\ s are implicitly
   associated with an existing instruction list: the instruction list of the
   enclosing basic block.  Thus, we could have accomplished the same thing as the
   above code without being given a ``BasicBlock`` by doing:
 
   .. code-block:: c++
 
     Instruction *pi = ...;
-    Instruction *newInst = new Instruction(...);
+    auto *newInst = new Instruction(...);
 
     pi->getParent()->getInstList().insert(pi, newInst);
 
   In fact, this sequence of steps occurs so frequently that the ``Instruction``
   class and ``Instruction``-derived classes provide constructors which take (as
   a default parameter) a pointer to an ``Instruction`` which the newly-created
   ``Instruction`` should precede.  That is, ``Instruction`` constructors are
   capable of inserting the newly-created instance into the ``BasicBlock`` of a
   provided instruction, immediately before that instruction.  Using an
   ``Instruction`` constructor with a ``insertBefore`` (default) parameter, the
   above code becomes:
 
   .. code-block:: c++
 
     Instruction* pi = ...;
-    Instruction* newInst = new Instruction(..., pi);
+    auto *newInst = new Instruction(..., pi);
 
   which is much cleaner, especially if you're creating a lot of instructions and
   adding them to ``BasicBlock``\ s.
 
 * Insertion using an instance of ``IRBuilder``
 
   Inserting several ``Instruction``\ s can be quite laborious using the previous
   methods. The ``IRBuilder`` is a convenience class that can be used to add