<html>
<head>
<title>N4284: Contiguous Iterators</title>

<style type="text/css">
  ins { text-decoration:none; font-weight:bold; background-color:#A0FFA0 }
  .new { text-decoration:none; font-weight:bold; background-color:#D0FFD0 }
  del { text-decoration:line-through; background-color:#FFA0A0 }  
  strong { font-weight: inherit; color: #2020ff }
</style>
</head>

<body>
N4284<br/>
revision of N4132<br/>
Jens Maurer &lt;Jens.Maurer@gmx.net><br/>
2014-11-07<br/>

<h1>N4284: Contiguous Iterators</h1>

<h2>Introduction</h2>

There are four containers in the standard library
that guarantee contiguous storage: <code>vector</code>,
<code>string</code>, <code>valarray</code>, and
<code>array</code>.  In the Library Fundamentals TS, there is also
<code>string_view</code>.  This paper introduces the term "contiguous
iterator" as a refinement of random-access iterator, without
introducing a corresponding <code>contiguous_iterator_tag</code>,
which was found to break code during the Issaquah discussions of Nevin
Liber's paper <a
href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n3884.pdf">N3884</a>
"Contiguous Iterators: A Refinement of Random Access Iterators".



<h2>Wording Changes</h2>


Add a new paragraph after 24.2.1 [iterator.requirements.general] paragraph 4:

<blockquote>
Iterators that further satisfy the requirements of output iterators
are called <em>mutable iterators</em>. Nonmutable iterators are
referred to as <em>constant iterators</em>.

</blockquote>

<blockquote class="new">
Iterators that further satisfy the requirement that, for integral
values <code>n</code> and dereferenceable
iterator values <code>a</code> and <code>(a +
n)</code>, <code>*(a + n)</code> is equivalent to
<code>*(addressof(*a) + n)</code>, are called <em>contiguous
iterators</em>. [ Note: For example, the type "pointer to int" is a
contiguous iterator, but <code>reverse_iterator&lt;int *></code> is
not.

For a valid iterator range [a, b) with dereferenceable <code>a</code>,
the corresponding range denoted by pointers is
[<code>addressof(*a)</code>, <code>addressof(*a) + (b - a)</code> );
<code>b</code> might not be dereferenceable. -- end note ]

</blockquote>


Change in 21.4 [basic.string] paragraph 3:

<blockquote>
<del>The iterators supported by <code>basic_string</code> are random
access iterators (24.2.7 [random.access.iterators]).</del> <ins>A
<code>basic_string</code> is a contiguous container (23.2.1
[container.requirements.general]).</ins>

</blockquote>

Delete in 21.4.1 [string.require] paragraph 4:

<blockquote>
<del>The char-like objects in a <code>basic_string</code> object shall be
stored contiguously. That is, for any <code>basic_string</code> object
s, the identity <code>&*(s.begin() + n) == &*s.begin() + n</code>
shall hold for all values of n such that <code>0 <= n <
s.size()</code>.</del>


</blockquote>


Add a new paragraph after 23.2.1 [container.requirements.general] paragraph 12:

<blockquote>
Unless otherwise specified (either explicitly or by defining a
function in terms of other functions), invoking a container member
function or passing a container as an argument to a library function
shall not invalidate iterators to, or change the values of, objects
within that container.

</blockquote>

<blockquote class="new">
A <em>contiguous container</em> is a container that
supports random access iterators (24.2.7
[random.access.iterators]) and whose
member types <code>iterator</code> and <code>const_iterator</code> are
contiguous iterators (24.2.1 [iterator.requirements.general]).

</blockquote>


Change in 23.3.2.1 [array.overview] paragraph 1:

<blockquote>
... An array <del>supports random access iterators</del>
<ins>is a contiguous container</ins>. ... <del>The
elements of an array are stored contiguously, meaning that if a is an
array&lt;T, N> then it obeys the identity <code>&a[n] == &a[0] +
n</code> for all <code>0 <= n < N.</code>

</blockquote>


Change in 23.3.6.1 [vector.overview] paragraphs 1 and 2:

<blockquote>
A vector is a sequence container that <del>supports random access
iterators . In addition, it</del> supports (amortized) constant time
insert and erase operations at the end; insert and erase in the middle
take linear time. ...

<del>The elements of a vector are
stored contiguously, meaning that if v is a vector<T, Allocator> where
T is some type otherthan bool, then it obeys the identity <code>&v[n]
== &v[0] + n for all 0 <= n < v.size()</code>.</del>
<p>
A vector satisfies all of the requirements of a container and of a
reversible container (given in two tables in 23.2), of a sequence
container, including most of the optional sequence container
requirements (23.2.3 [sequence.reqmts]), <del>and</del> of an
allocator-aware container (Table 99)<ins>, and, for an element type
other than <code>bool</code>, of a contiguous container (23.2.1
[container.requirements.general])</ins>. The exceptions are ...

</blockquote>

Change in 26.6.10 [valarray.range] paragraph 1:

<blockquote>
In the <code>begin</code> and <code>end</code> function templates that
follow, <em>unspecified1</em> is a type that meets the requirements of
a mutable random access iterator (24.2.7 [random.access.iterators])
<ins>and of a contiguous iterator (24.2.1
iterator.requirements.general])</ins> whose <code>value_type</code> is
the template parameter T and whose reference type is
T&. <em>unspecified2</em> is a type that meets the requirements of a
constant random access iterator (24.2.7 [random.access.iterators])
<ins>and of a contiguous iterator (24.2.1
[iterator.requirements.general])</ins> whose <code>value_type</code>
is the template parameter T and whose reference type is const T&.

</blockquote>


<em>[ Drafting note: In the library fundamentals TS, section 7.4, replace</em>

<blockquote>
<pre>typedef implementation-defined const_iterator;</pre>

A constant random-access <ins>and contiguous</ins>
iterator type<del> such that, for a const_iterator it, if &*(it+N) is
valid, then it is equal to (&*it)+N</del>.

</blockquote>
<em>]</em>

</body>
</html>
