<html>
<head>
<title>n2206 Consistent Insertion into Standard Containers</title>
</head>

<body>
<h1>Consistent Insertion into Standard Containers</h1>
Document Number: n2206(07-0066)<br/>
2007-03-09<br/>
Alisdair Meredith &lt;alisdair.meredith@uk.renaultf1.com><br/>

<h2>Motivation</h2>
The standard library offers a variety of containers that strive to offer a consistent interface.  One common feature is the ability to insert elements into the container, and where efficiently supported there are special functions to insert at the beginning or end.  However, these operations are not consistently overloaded to accept the same set of values.  This leads to unfulfilled user expectations, and in the worst cases (such as container adapters) inefficent code that is easily worked around by the user supplying their own replacement adapter.
<p>
By supplying the missing overloads, implementers can use additional information to provide more effient implementations for range operations, or stronger exception-safety semantics.  This paper does make either of these a requirement though.
<p>

<h2>Recommended changes</h2>
All sequence containers with an <code>insert</code> member function should have overloads that accept single values and ranges of values marked by an iterator pair.  If concept-based overloading is adopted, it would be further recommended to overload on a single range/view value as well.
<p>

All sequence containers with a <code>push_back</code> member function should have overloads that accept single values and ranges of values marked by an iterator pair.  If concept-based overloading is adopted, it would be further recommended to overload on a single range/view value as well.
<p>

All sequence containers with a <code>push_front</code> member function should have overloads that accept single values and ranges of values marked by an iterator pair.  If concept-based overloading is adopted, it would be further recommended to overload on a single range/view value as well.
<p>

All sequence-adapters with a <code>push</code> member function should have overloads that accept single values and ranges of values marked by an iterator pair.  If concept-based overloading is adopted, it would be further recommended to overload on a single range/view value as well.  These overloads will call the appropiately function in the adapted type i.e. <code>stack</code> would call the appropariate <code>push_back</code> overload while <code>queue</code> would call <code>push_front</code>
<p>

All sequence-adapters have a constructor template that accepts ranges of values marked by an iterator pair.  If concept-based overloading is adopted, it would be further recommended to overload on a single range/view value as well.
<p>

It is noted that the associative containers already have the appropriate interface.
<p>

<h2>Optional changes</h2>
Many containers overload their <code>insert</code> function to accept a number of values marked by a count, and a value to copy.  To maintain a consistent interface, these might be overloaded as well.

<h2>Normative changes</h2>
Add the following overloads to the <code>deque</code> template:<br/>
<li><code>template &lt;InputIterator> void push_back( InputIterator first, InputIterator last )</code></li>
<li><code>void push_back( size_type n, const T & value )</code></li>
<li><code>template &lt;InputIterator> void push_front( InputIterator first, InputIterator last )</code></li>
<li><code>void push_front( size_type n, const T & value )</code></li>

<p>

Add the following overloads to the <code>list</code> template:<br/>
<li><code>template &lt;InputIterator> void push_back( InputIterator first, InputIterator last )</code></li>
<li><code>void push_back( size_type n, const T & value )</code></li>
<li><code>template &lt;InputIterator> void push_front( InputIterator first, InputIterator last )</code></li>
<li><code>void push_front( size_type n, const T & value )</code></li>

<p>

Add the following overloads to the <code>vector</code> template:
<li><code>template &lt;InputIterator> void push_back( InputIterator first, InputIterator last )</code></li>
<li><code>void push_back( size_type n, const T & value )</code></li>

<p>

Add the following overloads to the <code>priority_queue</code> template:
<li><code>template &lt;InputIterator> void push( InputIterator first, InputIterator last )</code></li>
<li><code>void push( size_type n, const T & value )</code></li>

<p>

Add the following overloads to the <code>queue</code> template:
<li><code>template &lt;InputIterator> queue( InputIterator first, InputIterator last )</code></li>
<li><code>template &lt;InputIterator> void push( InputIterator first, InputIterator last )</code></li>
<li><code>void push( size_type n, const T & value )</code></li>

<p>

Add the following overloads to the <code>stack</code> template:
<li><code>template &lt;InputIterator> stack( InputIterator first, InputIterator last )</code></li>
<li><code>template &lt;InputIterator> void push( InputIterator first, InputIterator last )</code></li>
<li><code>void push( size_type n, const T & value )</code></li>

<p>

</body>
</html>
