X-Git-Url: http://demsky.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FProgrammersManual.html;h=e8d81a25061daa2db8d873767113226f2c1b5b2e;hb=2bf4b54a800c2dd44c0a5939fe629ea120bee2ad;hp=b6c9a8793c218a6c59c28ff4daa6f526c1ef083f;hpb=4de7368bf92897d3b943423934e0a95d5a99d2cd;p=oota-llvm.git diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html index b6c9a8793c2..e8d81a25061 100644 --- a/docs/ProgrammersManual.html +++ b/docs/ProgrammersManual.html @@ -269,9 +269,9 @@ can get, so it will not be discussed in this document.

    -
  1. Dinkumware C++ Library -reference - an excellent reference for the STL and other parts of the -standard C++ library.
    2. +
  2. Dinkumware +C++ Library reference - an excellent reference for the STL and other parts +of the standard C++ library.
  3. C++ In a Nutshell - This is an O'Reilly book in the making. It has a decent Standard Library @@ -309,8 +309,6 @@ to write maintainable code more than where to put your curly braces.

      -
    1. CVS -Branch and Tag Primer
    2. Using static and shared libraries across platforms
    @@ -457,8 +455,8 @@ StringMap class which is used extensively in LLVM and Clang.

    may have embedded null characters. Therefore, they cannot simply take a const char *, and taking a const std::string& requires clients to perform a heap allocation which is usually unnecessary. Instead, -many LLVM APIs use a const StringRef& or a const -Twine& for passing strings efficiently.

    +many LLVM APIs use a StringRef or a const Twine& for +passing strings efficiently.

    @@ -477,19 +475,17 @@ on std:string, but does not require heap allocation.

    an std::string, or explicitly with a character pointer and length. For example, the StringRef find function is declared as:

    -
    - iterator find(const StringRef &Key); -
    +
    +  iterator find(StringRef Key);
+

    and clients can call it using any one of:

    -
    -
    +
       Map.find("foo");                 // Lookup "foo"
   Map.find(std::string("bar"));    // Lookup "bar"
   Map.find(StringRef("\0baz", 4)); // Lookup "\0baz"
 
    
-

    Similarly, APIs which need to return a string may return a StringRef instance, which can be used directly or converted to an std::string @@ -499,7 +495,8 @@ for more information.

    You should rarely use the StringRef class directly, because it contains pointers to external memory it is not generally safe to store an instance of the -class (unless you know that the external storage will not be freed).

    +class (unless you know that the external storage will not be freed). StringRef is +small and pervasive enough in LLVM that it should always be passed by value.

    @@ -1437,7 +1434,7 @@ to the key string for a value.

    The StringMap is very fast for several reasons: quadratic probing is very cache efficient for lookups, the hash value of strings in buckets is not -recomputed when lookup up an element, StringMap rarely has to touch the +recomputed when looking up an element, StringMap rarely has to touch the memory for unrelated objects when looking up a value (even when hash collisions happen), hash table growth does not recompute the hash values for strings already in the table, and each pair in the map is store in a single allocation @@ -1843,6 +1840,21 @@ void printNextInstruction(Instruction* inst) { +

    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 B is a BasicBlock, +from compiling:

    + +
    +
    +  llvm::SmallVector<llvm::Instruction *, 16>(B->begin(), B->end());
+
    +
    + +

    Because of this, these implicit conversions may be removed some day, +and operator* changed to return a pointer instead of a reference.

    + @@ -1960,12 +1972,12 @@ for (Value::use_iterator i = F->use_begin(), e = F->use_end(); i != e; ++i errs() << *Inst << "\n"; } -Note that dereferencing a Value::use_iterator*i above several times, consider -doing it only once in the loop body and reusing its result. - +

    Note that dereferencing a Value::use_iterator is not a very cheap +operation. Instead of performing *i above several times, consider +doing it only once in the loop body and reusing its result.

    +

    Alternatively, it's common to have an instance of the User Class and need to know what Values are used by it. The list of all Values used by a @@ -1986,12 +1998,13 @@ for (User::op_iterator i = pi->op_begin(), e = pi->op_end(); i != e; ++i)

    Declaring objects as const 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 Value::const_use_iterator and Value::const_op_iterator. They automatically arise when calling use/op_begin() on const Value*s or const User*s respectively. Upon dereferencing, they return -const Use*s. Otherwise the above patterns remain unchanged. +const Use*s. Otherwise the above patterns remain unchanged.

    + @@ -3064,7 +3077,7 @@ the lib/VMCore directory.

    FunctionType
    Subclass of DerivedTypes for function types.
      -
    • bool isVarArg() const: Returns true if its a vararg +
    • bool isVarArg() const: Returns true if it's a vararg function
    • const Type * getReturnType() const: Returns the return type of the function.
      • @@ -3282,7 +3295,7 @@ simplifies the representation and makes it easier to manipulate.

      • Value::use_iterator - Typedef for iterator over the use-list
        - Value::use_const_iterator - Typedef for const_iterator over + Value::const_use_iterator - Typedef for const_iterator over the use-list
        unsigned use_size() - Returns the number of users of the value.