diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 5f19486655ab..f69d66207b67 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,8 @@ +2001-08-24 Phil Edwards + + * docs/html/23_containers/howto.html: Describe implementation of + insertion with hints. + 2001-08-24 Kenny Simpson libstdc++/3740 diff --git a/libstdc++-v3/docs/html/23_containers/howto.html b/libstdc++-v3/docs/html/23_containers/howto.html index 6f20c9b1d8a2..03ba35dd2a34 100644 --- a/libstdc++-v3/docs/html/23_containers/howto.html +++ b/libstdc++-v3/docs/html/23_containers/howto.html @@ -8,7 +8,7 @@ libstdc++-v3 HOWTO: Chapter 23 - + @@ -25,6 +25,7 @@
  • Making code unaware of the container/array difference
  • Variable-sized bitmasks
  • Containers and multithreading +
  • "Hinting" during insertion
    @@ -245,12 +246,85 @@ a catch-all general template solution would probably be more trouble than it's worth.

    -

    Return to top of page or to the FAQ.

    - +
    +

    "Hinting" during insertion

    +

    Section [23.1.2], Table 69, of the C++ standard lists this function + for all of the associative containers (map, set, etc): + 

    +      a.insert(p,t);
    + where 'p' is an iterator into the container 'a', and 't' is the item + to insert. The standard says that "iterator p is a hint + pointing to where the insert should start to search," but + specifies nothing more. (LWG Issue #233, currently in review, + addresses this topic, but I will ignore it here because it is not yet + finalized.) +

    +

    Here we'll describe how the hinting works in the libstdc++-v3 + implementation, and what you need to do in order to take advantage of + it. (Insertions can change from logarithmic complexity to amortized + constant time, if the hint is properly used.) Also, since the current + implementation is based on the SGI STL one, these points may hold true + for other library implementations also, since the HP/SGI code is used + in a lot of places. +

    +

    In the following text, the phrases greater than and less + than refer to the results of the strict weak ordering imposed on + the container by its comparison object, which defaults to (basically) + "<". Using those phrases is semantically sloppy, but I + didn't want to get bogged down in syntax. I assume that if you are + intelligent enough to use your own comparison objects, you are also + intelligent enough to assign "greater" and "lesser" + their new meanings in the next paragraph. *grin* +

    +

    If the hint parameter ('p' above) is equivalent to: +

      +
    • begin(), then the item being inserted should have a key + less than all the other keys in the container. The item will + be inserted at the beginning of the container, becoming the new + entry at begin(). +
    • end(), then the item being inserted should have a key + greater than all the other keys in the container. The item will + be inserted at the end of the container, becoming the new entry + at end(). +
    • neither begin() nor end(), then: Let h + be the entry in the container pointed to by hint, that + is, h = *hint. Then the item being inserted should have + a key less than that of h, and greater than that of the + item preceeding h. The new item will be inserted + between h and h's predecessor. +
    +

    +

    If the conditions are not met, then the hint is not used, and the + insertion proceeds as if you had called a.insert(t) + instead. (Note that GCC releases prior to 3.0.2 + had a bug in the case with hint == begin(). You should not + use a hint argument in those releases.) +(Was it just with map or with all the rbtree-using containers? Still need +to check that.) +

    +

    This behavior goes well with other container's insert() + functions which take an iterator: if used, the new item will be + inserted before the iterator passed as an argument, same as the other + containers. The exception + (in a sense) is with a hint of end(): the new item will + actually be inserted after end(), but it also becomes the + new end(). +

    +

    Note also that the hint in this implementation is a + one-shot. The insertion-with-hint routines check the immediately + surrounding entries to ensure that the new item would in fact belong + there. If the hint does not point to the correct place, then no + further local searching is done; the search begins from scratch in + logarithmic time. (Further local searching would only increase the + time required when the hint is too far off.) +

    +

    Return to top of page or + to the FAQ. +

    @@ -259,7 +333,7 @@

    Comments and suggestions are welcome, and may be sent to the mailing list. -
    $Id: howto.html,v 1.5 2001/05/31 02:45:02 ljrittle Exp $ +
    $Id: howto.html,v 1.6 2001/06/08 03:53:35 ljrittle Exp $