<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Issue 1253: invalidation of iterators and emplace vs. insert inconsistence in assoc. containers</title>
<meta property="og:title" content="Issue 1253: invalidation of iterators and emplace vs. insert inconsistence in assoc. containers">
<meta property="og:description" content="C++ library issue. Status: C++11">
<meta property="og:url" content="https://cplusplus.github.io/LWG/issue1253.html">
<meta property="og:type" content="website">
<meta property="og:image" content="http://cplusplus.github.io/LWG/images/cpp_logo.png">
<meta property="og:image:alt" content="C++ logo">
<style>
  p {text-align:justify}
  li {text-align:justify}
  pre code.backtick::before { content: "`" }
  pre code.backtick::after { content: "`" }
  blockquote.note
  {
    background-color:#E0E0E0;
    padding-left: 15px;
    padding-right: 15px;
    padding-top: 1px;
    padding-bottom: 1px;
  }
  ins {background-color:#A0FFA0}
  del {background-color:#FFA0A0}
  table.issues-index { border: 1px solid; border-collapse: collapse; }
  table.issues-index th { text-align: center; padding: 4px; border: 1px solid; }
  table.issues-index td { padding: 4px; border: 1px solid; }
  table.issues-index td:nth-child(1) { text-align: right; }
  table.issues-index td:nth-child(2) { text-align: left; }
  table.issues-index td:nth-child(3) { text-align: left; }
  table.issues-index td:nth-child(4) { text-align: left; }
  table.issues-index td:nth-child(5) { text-align: center; }
  table.issues-index td:nth-child(6) { text-align: center; }
  table.issues-index td:nth-child(7) { text-align: left; }
  table.issues-index td:nth-child(5) span.no-pr { color: red; }
  @media (prefers-color-scheme: dark) {
     html {
        color: #ddd;
        background-color: black;
     }
     ins {
        background-color: #225522
     }
     del {
        background-color: #662222
     }
     a {
        color: #6af
     }
     a:visited {
        color: #6af
     }
     blockquote.note
     {
        background-color: rgba(255, 255, 255, .10)
     }
  }
</style>
</head>
<body>
<hr>
<p><em>This page is a snapshot from the LWG issues list, see the <a href="lwg-active.html">Library Active Issues List</a> for more information and the meaning of <a href="lwg-active.html#C++11">C++11</a> status.</em></p>
<h3 id="1253"><a href="lwg-defects.html#1253">1253</a>. invalidation of iterators and <code>emplace</code> vs. <code>insert</code> inconsistence in assoc. containers</h3>
<p><b>Section:</b> 23.2.7 <a href="https://wg21.link/associative.reqmts">[associative.reqmts]</a> <b>Status:</b> <a href="lwg-active.html#C++11">C++11</a>
 <b>Submitter:</b> Boris Du&scaron;ek <b>Opened:</b> 2009-10-24 <b>Last modified:</b> 2016-01-28</p>
<p><b>Priority: </b>Not Prioritized
</p>
<p><b>View other</b> <a href="lwg-index-open.html#associative.reqmts">active issues</a> in [associative.reqmts].</p>
<p><b>View all other</b> <a href="lwg-index.html#associative.reqmts">issues</a> in [associative.reqmts].</p>
<p><b>View all issues with</b> <a href="lwg-status.html#C++11">C++11</a> status.</p>
<p><b>Discussion:</b></p>
<p>
In the latest published draft
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2960.pdf">N2960</a>,
section 23.2.7 <a href="https://wg21.link/associative.reqmts">[associative.reqmts]</a>, paragraph 8, it is specified
that that <code>insert</code> does not invalidate any iterators. As per
23.2.2 <a href="https://wg21.link/container.requirements.general">[container.requirements.general]</a>, paragraph 12, this holds
true not only for <code>insert</code>, but <code>emplace</code> as well. This
gives the <code>insert</code> member a special treatment w.r.t.
<code>emplace</code> member in 23.2.7 <a href="https://wg21.link/associative.reqmts">[associative.reqmts]</a>, par. 8,
since both modify the container. For the sake of consistency, in 23.2.7 <a href="https://wg21.link/associative.reqmts">[associative.reqmts]</a>, par. 8: either reference to <code>insert</code> 
should be removed (i.e. count on 23.2.2 <a href="https://wg21.link/container.requirements.general">[container.requirements.general]</a>, 
par. 12), or reference to <code>emplace</code> be added (i.e. mention all 
members of assoc. containers that modify it).
</p>

<p><i>[
2009-11-18 Chris provided wording.
]</i></p>


<blockquote><p>
This suggested wording covers both the issue discussed, and a number of other
identical issues (namely <code>insert</code> being discussed without <code>emplace</code>). I'm happy to
go back and split and introduce a new issue if appropriate, but I think the
changes are fairly mechanical and obvious.
</p></blockquote>

<p><i>[
2010-01-23 Daniel Kr&uuml;gler and J. Daniel Garc&iacute;a updated wording to
make the use of <code>hint</code> consistent with <code>insert</code>.
]</i></p>


<p><i>[
2011-02-23 Daniel Kr&uuml;gler adapts wording to numbering changes to match the N3225 draft. During this
action it was found that 23.2.8 <a href="https://wg21.link/unord.req">[unord.req]</a> had been changed considerably
due to acceptance of <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3068.pdf">N3068</a>
during the Pittsburgh meeting, such that the suggested wording change to
p. 6 can no longer be applied. The new wording is more general and should
now include <code>insert()</code> and <code>emplace()</code> calls as well ("mutating operations").
]</i></p>


<p><i>[2011-03-06 Daniel Kr&uuml;gler adapts wording to numbering changes to match the N3242 draft]</i></p>




<p id="res-1253"><b>Proposed resolution:</b></p>
<ol>
<li>
<p>
Modify bullet 1 of 23.2.2 <a href="https://wg21.link/container.requirements.general">[container.requirements.general]</a>, p. 10:
</p>

<p>
10 Unless otherwise specified (see [associative.reqmts.except], [unord.req.except], [deque.modifiers], and [vector.modifiers])
all container types defined in this Clause meet the following additional
requirements:
</p>

<ul>
<li>
if an exception is thrown by an <code>insert()</code> <ins>or
<code>emplace()</code></ins> function while inserting a single element, that
function has no effects.
</li>
<li>...</li>
</ul>

</li>

<li>
<p>
Modify 23.2.7 <a href="https://wg21.link/associative.reqmts">[associative.reqmts]</a>, p. 4:
</p>

<blockquote><p>
4 An associative container supports <i>unique keys</i> if it may contain at most
one element for each key. Otherwise, it supports <i>equivalent keys</i>. The
<code>set</code> and <code>map</code> classes support unique keys; the <code>multiset</code>
and <code>multimap</code> classes support equivalent keys. For <code>multiset</code> and
<code>multimap</code>, <code>insert</code><ins>, <code>emplace</code>,</ins> and
<code>erase</code> preserve the relative ordering of equivalent elements.
</p></blockquote>

</li>

<li>
<p>
Modify Table 102 &mdash; Associative container requirements in 
23.2.7 <a href="https://wg21.link/associative.reqmts">[associative.reqmts]</a>:
</p>

<blockquote>
<table border="1">
<caption>Table 102 &mdash; Associative container requirements (in addition to container)</caption>
<tr>
<th>Expression</th>
<th>Return type</th>
<th>Assertion&#47;note<br />pre-&#47;post-condition</th>
<th>Complexity</th>
</tr>

<tr>
<td colspan="4" style="text-align:center;">[&hellip;]</td>
</tr>

<tr>
<td><code>a_eq.emplace(args)</code></td>
<td><code>iterator</code></td>
<td>[&hellip;] <i>Effects:</i> Inserts a <code>T</code> object <code>t</code> constructed with
<code>std::forward&lt;Args&gt;(args)...</code> and returns the iterator pointing to
the newly inserted element. <ins>If a range containing elements equivalent to
<code>t</code> exists in <code>a_eq</code>, <code>t</code> is inserted at the end of that
range.</ins></td>
<td>logarithmic</td>
</tr>

<tr>
<td><code>a.emplace_hint(p, args)</code></td>
<td><code>iterator</code></td>
<td>equivalent to <code>a.emplace(std::forward&lt;Args&gt;(args)...)</code>. Return
value is an iterator pointing to the element with the key equivalent to the
newly inserted element. <del>The <code>const_iterator p</code> is a hint pointing to
where the search should start.</del> <ins>The element is inserted as close as
possible to the position just prior to <code>p</code>.</ins> <del>Implementations
are permitted to ignore the hint.</del></td>
<td>logarithmic in general, but amortized constant if the element is inserted
right <del>after</del> <ins>before</ins> <code>p</code></td>
</tr>

<tr>
<td colspan="4" style="text-align:center;">[&hellip;]</td>
</tr>

</table>
</blockquote>

</li>

<li>
<p>
Modify 23.2.7 <a href="https://wg21.link/associative.reqmts">[associative.reqmts]</a>, p. 9:
</p>

<blockquote><p>
9 The <code>insert</code> <ins>and <code>emplace</code></ins> members shall not affect
the validity of iterators and references to the container, and the
<code>erase</code> members shall invalidate only iterators and references to the
erased elements.
</p></blockquote>

</li>

<li>
<p>
Modify 23.2.7.2 <a href="https://wg21.link/associative.reqmts.except">[associative.reqmts.except]</a>, p. 2:
</p>

<blockquote><p>
2 For associative containers, if an exception is thrown by any operation from
within an <code>insert()</code> <ins> or <code>emplace()</code></ins> function inserting
a single element, the <del><code>insert()</code> function</del> <ins>insertion</ins>
has no effect.
</p></blockquote>

</li>

<li>
<p>
Modify 23.2.8 <a href="https://wg21.link/unord.req">[unord.req]</a>, p. 13 and p. 14:
</p>

<blockquote>
<p>
6 An unordered associative container supports <i>unique keys</i> if it may
contain at most one element for each key. Otherwise, it supports <i>equivalent
keys</i>. <code>unordered_set</code> and <code>unordered_map</code> support unique keys.
<code>unordered_multiset</code> and <code>unordered_multimap</code> support equivalent
keys. In containers that support equivalent keys, elements with equivalent keys
are adjacent to each other in the iteration order of the container. Thus, although 
the absolute order of elements in an unordered container is not specified, its 
elements are grouped into <i>equivalent-key groups</i> such that all elements of each 
group have equivalent keys. Mutating operations on unordered containers shall 
preserve the relative order of elements within each equivalent-key group unless 
otherwise specified.
</p>

<p>[&hellip;]</p>

<p>
13 The <code>insert</code> <ins>and <code>emplace</code></ins> members shall not affect
the validity of references to container elements, but may invalidate all
iterators to the container. The erase members shall invalidate only iterators
and references to the erased elements.
</p>

<p>
14 The <code>insert</code> <ins>and <code>emplace</code></ins> members shall not affect
the validity of iterators if <code>(N+n) &lt; z * B</code>, where <code>N</code> is the
number of elements in the container prior to the insert operation, <code>n</code> is
the number of elements inserted, <code>B</code> is the container's bucket count, and
<code>z</code> is the container's maximum load factor.
</p>
</blockquote>

</li>

<li>
<p>
Modify 23.2.8.2 <a href="https://wg21.link/unord.req.except">[unord.req.except]</a>, p. 2:
</p>

<blockquote><p>
2 For unordered associative containers, if an exception is thrown by any
operation other than the container's hash function from within an
<code>insert()</code> <ins>or <code>emplace()</code></ins> function inserting a single
element, the <del><code>insert()</code></del> <ins>insertion</ins>
<del>function</del> has no effect.
</p></blockquote>

</li>
</ol>






</body>
</html>
