|
|
Boost-Commit : |
From: daniel_james_at_[hidden]
Date: 2008-01-06 06:38:55
Author: danieljames
Date: 2008-01-06 06:38:54 EST (Sun, 06 Jan 2008)
New Revision: 42517
URL: http://svn.boost.org/trac/boost/changeset/42517
Log:
Make it clear that pointers and references to elements are never invalidated.
Text files modified:
branches/unordered/trunk/libs/unordered/doc/buckets.qbk | 6 +++++-
branches/unordered/trunk/libs/unordered/doc/comparison.qbk | 7 +++++--
branches/unordered/trunk/libs/unordered/doc/ref.xml | 21 +++++++++++++++++----
3 files changed, 27 insertions(+), 7 deletions(-)
Modified: branches/unordered/trunk/libs/unordered/doc/buckets.qbk
==============================================================================
--- branches/unordered/trunk/libs/unordered/doc/buckets.qbk (original)
+++ branches/unordered/trunk/libs/unordered/doc/buckets.qbk 2008-01-06 06:38:54 EST (Sun, 06 Jan 2008)
@@ -115,11 +115,15 @@
]
+[h2 Iterator Invalidation]
+
It is not specified how member functions other than `rehash` affect
the bucket count, although `insert` is only allowed to invalidate iterators
when the insertion causes the load factor to be greater than or equal to the
maximum load factor. For most implementations this means that insert will only
-change the number of buckets when this happens.
+change the number of buckets when this happens. While iterators can be
+invalidated by calls to `insert` and `rehash`, pointers and references to the
+container's elements are never invalidated.
In a similar manner to using `reserve` for `vector`s, it can be a good idea
to call `rehash` before inserting a large number of elements. This will get
Modified: branches/unordered/trunk/libs/unordered/doc/comparison.qbk
==============================================================================
--- branches/unordered/trunk/libs/unordered/doc/comparison.qbk (original)
+++ branches/unordered/trunk/libs/unordered/doc/comparison.qbk 2008-01-06 06:38:54 EST (Sun, 06 Jan 2008)
@@ -50,8 +50,11 @@
[`iterator`, `const_iterator` are of at least the forward category.]
]
[
- [Inserts do not invalidate iterators or references to the container.]
- [Inserts can invalidate iterators but not references to the container.]
+ [Iterators, pointers and references to the container's elements are
+ never invalidated.]
+ [[link unordered.buckets.iterator_invalidation Iterators can
+ be invalidated by calls to insert or rehash]. Pointers and
+ references to the container's elements are never invalidated.]
]
[
[Iterators iterate through the container in the order defined by
Modified: branches/unordered/trunk/libs/unordered/doc/ref.xml
==============================================================================
--- branches/unordered/trunk/libs/unordered/doc/ref.xml (original)
+++ branches/unordered/trunk/libs/unordered/doc/ref.xml 2008-01-06 06:38:54 EST (Sun, 06 Jan 2008)
@@ -270,6 +270,7 @@
</throws>
<notes>
<para>Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor.</para>
+ <para>Pointers and references to elements are never invalidated.</para>
</notes>
</method>
<method name="insert">
@@ -293,6 +294,7 @@
<notes>
<para>The standard is fairly vague on the meaning of the hint. But the only practical way to use it, and the only way that Boost.Unordered supports is to point to an existing element with the same value. </para>
<para>Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor.</para>
+ <para>Pointers and references to elements are never invalidated.</para>
</notes>
</method>
<method name="insert">
@@ -315,6 +317,7 @@
</throws>
<notes>
<para>Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor.</para>
+ <para>Pointers and references to elements are never invalidated.</para>
</notes>
</method>
<method name="erase">
@@ -584,7 +587,7 @@
<type>void</type>
<description>
<para>Changes the number of buckets so that there at least <code>n</code> buckets, and so that the load factor is less than the maximum load factor.</para>
- <para>Invalidates iterators, and changes the order of elements</para>
+ <para>Invalidates iterators, and changes the order of elements. Pointers and references to elements are not invalidated.</para>
</description>
<throws>
<para>The function has no effect if an exception is thrown, unless it is thrown by the container's hash function or comparison function.</para>
@@ -881,6 +884,7 @@
</throws>
<notes>
<para>Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor.</para>
+ <para>Pointers and references to elements are never invalidated.</para>
</notes>
</method>
<method name="insert">
@@ -904,6 +908,7 @@
<notes>
<para>The standard is fairly vague on the meaning of the hint. But the only practical way to use it, and the only way that Boost.Unordered supports is to point to an existing element with the same value. </para>
<para>Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor.</para>
+ <para>Pointers and references to elements are never invalidated.</para>
</notes>
</method>
<method name="insert">
@@ -926,6 +931,7 @@
</throws>
<notes>
<para>Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor.</para>
+ <para>Pointers and references to elements are never invalidated.</para>
</notes>
</method>
<method name="erase">
@@ -1195,7 +1201,7 @@
<type>void</type>
<description>
<para>Changes the number of buckets so that there at least <code>n</code> buckets, and so that the load factor is less than the maximum load factor.</para>
- <para>Invalidates iterators, and changes the order of elements</para>
+ <para>Invalidates iterators, and changes the order of elements. Pointers and references to elements are not invalidated.</para>
</description>
<throws>
<para>The function has no effect if an exception is thrown, unless it is thrown by the container's hash function or comparison function.</para>
@@ -1509,6 +1515,7 @@
</throws>
<notes>
<para>Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor.</para>
+ <para>Pointers and references to elements are never invalidated.</para>
</notes>
</method>
<method name="insert">
@@ -1532,6 +1539,7 @@
<notes>
<para>The standard is fairly vague on the meaning of the hint. But the only practical way to use it, and the only way that Boost.Unordered supports is to point to an existing element with the same key. </para>
<para>Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor.</para>
+ <para>Pointers and references to elements are never invalidated.</para>
</notes>
</method>
<method name="insert">
@@ -1554,6 +1562,7 @@
</throws>
<notes>
<para>Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor.</para>
+ <para>Pointers and references to elements are never invalidated.</para>
</notes>
</method>
<method name="erase">
@@ -1707,6 +1716,7 @@
</throws>
<notes>
<para>Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor.</para>
+ <para>Pointers and references to elements are never invalidated.</para>
</notes>
</method>
<overloaded-method name="at">
@@ -1857,7 +1867,7 @@
<type>void</type>
<description>
<para>Changes the number of buckets so that there at least <code>n</code> buckets, and so that the load factor is less than the maximum load factor.</para>
- <para>Invalidates iterators, and changes the order of elements</para>
+ <para>Invalidates iterators, and changes the order of elements. Pointers and references to elements are not invalidated.</para>
</description>
<throws>
<para>The function has no effect if an exception is thrown, unless it is thrown by the container's hash function or comparison function.</para>
@@ -2164,6 +2174,7 @@
</throws>
<notes>
<para>Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor.</para>
+ <para>Pointers and references to elements are never invalidated.</para>
</notes>
</method>
<method name="insert">
@@ -2187,6 +2198,7 @@
<notes>
<para>The standard is fairly vague on the meaning of the hint. But the only practical way to use it, and the only way that Boost.Unordered supports is to point to an existing element with the same key. </para>
<para>Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor.</para>
+ <para>Pointers and references to elements are never invalidated.</para>
</notes>
</method>
<method name="insert">
@@ -2209,6 +2221,7 @@
</throws>
<notes>
<para>Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor.</para>
+ <para>Pointers and references to elements are never invalidated.</para>
</notes>
</method>
<method name="erase">
@@ -2478,7 +2491,7 @@
<type>void</type>
<description>
<para>Changes the number of buckets so that there at least <code>n</code> buckets, and so that the load factor is less than the maximum load factor.</para>
- <para>Invalidates iterators, and changes the order of elements</para>
+ <para>Invalidates iterators, and changes the order of elements. Pointers and references to elements are not invalidated.</para>
</description>
<throws>
<para>The function has no effect if an exception is thrown, unless it is thrown by the container's hash function or comparison function.</para>
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk