[iterator.requirements] - C++14 → C++17

Files changed (1) hide show

tmp/tmpoj47cqx3/{from.md → to.md} +86 -56

tmp/tmpoj47cqx3/{from.md → to.md} RENAMED Viewed

@@ -5,16 +5,16 @@
 Iterators are a generalization of pointers that allow a C++program to
 work with different data structures (containers) in a uniform manner. To
 be able to construct template algorithms that work correctly and
 efficiently on different types of data structures, the library
 formalizes not just the interfaces but also the semantics and complexity
-assumptions of iterators. All input iterators `i` support the expression
 `*i`, resulting in a value of some object type `T`, called the *value
-type* of the iterator. All output iterators support the expression
-`*i = o` where `o` is a value of some type that is in the set of types
-that are *writable* to the particular iterator type of `i`. All
-iterators `i` for which the expression `(*i).m` is well-defined, support
 the expression `i->m` with the same semantics as `(*i).m`. For every
 iterator type `X` for which equality is defined, there is a
 corresponding signed integer type called the *difference type* of the
 iterator.
@@ -41,33 +41,58 @@ iterators also satisfy all the requirements of forward iterators and can
 be used whenever a forward iterator is specified; Random access
 iterators also satisfy all the requirements of bidirectional iterators
 and can be used whenever a bidirectional iterator is specified.
 Iterators that further satisfy the requirements of output iterators are
-called *mutable iterator*s. Nonmutable iterators are referred to as
-*constant iterator*s.
 Just as a regular pointer to an array guarantees that there is a pointer
 value pointing past the last element of the array, so for any iterator
 type there is an iterator value that points past the last element of a
 corresponding sequence. These values are called *past-the-end* values.
 Values of an iterator `i` for which the expression `*i` is defined are
 called *dereferenceable*. The library never assumes that past-the-end
 values are dereferenceable. Iterators can also have singular values that
-are not associated with any sequence. After the declaration of an
-uninitialized pointer `x` (as with `int* x;`), `x` must always be
-assumed to have a singular value of a pointer. Results of most
-expressions are undefined for singular values; the only exceptions are
-destroying an iterator that holds a singular value, the assignment of a
-non-singular value to an iterator that holds a singular value, and, for
-iterators that satisfy the `DefaultConstructible` requirements, using a
-value-initialized iterator as the source of a copy or move operation.
-This guarantee is not offered for default initialization, although the
-distinction only matters for types with trivial default constructors
-such as pointers or aggregates holding pointers. In these cases the
-singular value is overwritten the same way as any other value.
-Dereferenceable values are always non-singular.
 An iterator `j` is called *reachable* from an iterator `i` if and only
 if there is a finite sequence of applications of the expression `++i`
 that makes `i == j`. If `j` is reachable from `i`, they refer to
 elements of the same sequence.
@@ -95,23 +120,24 @@ In the following sections, `a` and `b` denote values of type `X` or
 `const X`, `difference_type` and `reference` refer to the types
 `iterator_traits<X>::difference_type` and
 `iterator_traits<X>::reference`, respectively, `n` denotes a value of
 `difference_type`, `u`, `tmp`, and `m` denote identifiers, `r` denotes a
 value of `X&`, `t` denotes a value of value type `T`, `o` denotes a
-value of some type that is writable to the output iterator. For an
-iterator type `X` there must be an instantiation of
-`iterator_traits<X>` ([[iterator.traits]]).
 ### Iterator <a id="iterator.iterators">[[iterator.iterators]]</a>
 The `Iterator` requirements form the basis of the iterator concept
 taxonomy; every iterator satisfies the `Iterator` requirements. This set
 of requirements specifies operations for dereferencing and incrementing
 an iterator. Most algorithms will require additional operations to
 read ([[input.iterators]]) or write ([[output.iterators]]) values, or
 to provide a richer set of iterator movements ([[forward.iterators]],
-[[bidirectional.iterators]], [[random.access.iterators]]).)
 A type `X` satisfies the `Iterator` requirements if:
 - `X` satisfies the `CopyConstructible`, `CopyAssignable`, and
   `Destructible` requirements ([[utility.arg.requirements]]) and
@@ -120,85 +146,89 @@ A type `X` satisfies the `Iterator` requirements if:
   have the indicated semantics.
 ### Input iterators <a id="input.iterators">[[input.iterators]]</a>
 A class or pointer type `X` satisfies the requirements of an input
-iterator for the value type `T` if X satisfies the `Iterator` (
 [[iterator.iterators]]) and `EqualityComparable` (Table
-[[equalitycomparable]]) requirements and the expressions in Table
 [[tab:iterator.input.requirements]] are valid and have the indicated
 semantics.
 In Table  [[tab:iterator.input.requirements]], the term *the domain of
 `==`* is used in the ordinary mathematical sense to denote the set of
 values over which `==` is (required to be) defined. This set can change
 over time. Each algorithm places additional requirements on the domain
 of `==` for the iterator values it uses. These requirements can be
-inferred from the uses that algorithm makes of `==` and `!=`. the call
-`find(a,b,x)` is defined only if the value of `a` has the property *p*
-defined as follows: `b` has property *p* and a value `i` has property
-*p* if `(*i==x)` or if `(*i!=x` and `++i` has property `p`).
-For input iterators, `a == b` does not imply `++a == ++b`. (Equality
-does not guarantee the substitution property or referential
 transparency.) Algorithms on input iterators should never attempt to
 pass through the same iterator twice. They should be *single pass*
-algorithms. Value type T is not required to be a `CopyAssignable` type
-(Table  [[copyassignable]]). These algorithms can be used with istreams
-as the source of the input data through the `istream_iterator` class
-template.
 ### Output iterators <a id="output.iterators">[[output.iterators]]</a>
 A class or pointer type `X` satisfies the requirements of an output
 iterator if `X` satisfies the `Iterator` requirements (
 [[iterator.iterators]]) and the expressions in Table
 [[tab:iterator.output.requirements]] are valid and have the indicated
 semantics.
-The only valid use of an `operator*` is on the left side of the
-assignment statement. *Assignment through the same value of the iterator
-happens only once.* Algorithms on output iterators should never attempt
-to pass through the same iterator twice. They should be *single pass*
-algorithms. Equality and inequality might not be defined. Algorithms
-that take output iterators can be used with ostreams as the destination
-for placing data through the `ostream_iterator` class as well as with
-insert iterators and insert pointers.
 ### Forward iterators <a id="forward.iterators">[[forward.iterators]]</a>
 A class or pointer type `X` satisfies the requirements of a forward
 iterator if
 - `X` satisfies the requirements of an input iterator (
   [[input.iterators]]),
-- X satisfies the `DefaultConstructible` requirements (
   [[utility.arg.requirements]]),
 - if `X` is a mutable iterator, `reference` is a reference to `T`; if
-  `X` is a const iterator, `reference` is a reference to `const T`,
 - the expressions in Table  [[tab:iterator.forward.requirements]] are
   valid and have the indicated semantics, and
 - objects of type `X` offer the multi-pass guarantee, described below.
-The domain of == for forward iterators is that of iterators over the
 same underlying sequence. However, value-initialized iterators may be
 compared and shall compare equal to other value-initialized iterators of
-the same type. value initialized iterators behave as if they refer past
-the end of the same empty sequence
 Two dereferenceable iterators `a` and `b` of type `X` offer the
 *multi-pass guarantee* if:
 - `a == b` implies `++a == ++b` and
 - `X` is a pointer type or the expression `(void)++X(a), *a` is
   equivalent to the expression `*a`.
-The requirement that `a == b` implies `++a == ++b` (which is not true
-for input and output iterators) and the removal of the restrictions on
-the number of the assignments through a mutable iterator (which applies
-to output iterators) allows the use of multi-pass one-directional
-algorithms with forward iterators.
 If `a` and `b` are equal, then either `a` and `b` are both
 dereferenceable or else neither is dereferenceable.
 If `a` and `b` are both dereferenceable, then `a == b` if and only if
@@ -209,12 +239,12 @@ If `a` and `b` are both dereferenceable, then `a == b` if and only if
 A class or pointer type `X` satisfies the requirements of a
 bidirectional iterator if, in addition to satisfying the requirements
 for forward iterators, the following expressions are valid as shown in
 Table  [[tab:iterator.bidirectional.requirements]].
-Bidirectional iterators allow algorithms to move iterators backward as
-well as forward.
 ### Random access iterators <a id="random.access.iterators">[[random.access.iterators]]</a>
 A class or pointer type `X` satisfies the requirements of a random
 access iterator if, in addition to satisfying the requirements for

 Iterators are a generalization of pointers that allow a C++program to
 work with different data structures (containers) in a uniform manner. To
 be able to construct template algorithms that work correctly and
 efficiently on different types of data structures, the library
 formalizes not just the interfaces but also the semantics and complexity
+assumptions of iterators. An input iterator `i` supports the expression
 `*i`, resulting in a value of some object type `T`, called the *value
+type* of the iterator. An output iterator `i` has a non-empty set of
+types that are *writable* to the iterator; for each such type `T`, the
+expression `*i = o` is valid where `o` is a value of type `T`. An
+iterator `i` for which the expression `(*i).m` is well-defined supports
 the expression `i->m` with the same semantics as `(*i).m`. For every
 iterator type `X` for which equality is defined, there is a
 corresponding signed integer type called the *difference type* of the
 iterator.
 be used whenever a forward iterator is specified; Random access
 iterators also satisfy all the requirements of bidirectional iterators
 and can be used whenever a bidirectional iterator is specified.
 Iterators that further satisfy the requirements of output iterators are
+called *mutable iterators*. Nonmutable iterators are referred to as
+*constant iterators*.
+In addition to the requirements in this subclause, the nested
+*typedef-name*s specified in [[iterator.traits]] shall be provided for
+the iterator type.
+[*Note 1*: Either the iterator type must provide the *typedef-name*s
+directly (in which case `iterator_traits` pick them up automatically),
+or an `iterator_traits` specialization must provide them. — *end note*]
+Iterators that further satisfy the requirement that, for integral values
+`n` and dereferenceable iterator values `a` and `(a + n)`, `*(a + n)` is
+equivalent to `*(addressof(*a) + n)`, are called *contiguous iterators*.
+[*Note 2*: For example, the type “pointer to `int`” is a contiguous
+iterator, but `reverse_iterator<int *>` is not. For a valid iterator
+range [`a`,`b`) with dereferenceable `a`, the corresponding range
+denoted by pointers is [`addressof(*a)`,`addressof(*a) + (b - a)`); `b`
+might not be dereferenceable. — *end note*]
 Just as a regular pointer to an array guarantees that there is a pointer
 value pointing past the last element of the array, so for any iterator
 type there is an iterator value that points past the last element of a
 corresponding sequence. These values are called *past-the-end* values.
 Values of an iterator `i` for which the expression `*i` is defined are
 called *dereferenceable*. The library never assumes that past-the-end
 values are dereferenceable. Iterators can also have singular values that
+are not associated with any sequence.
+[*Example 1*: After the declaration of an uninitialized pointer `x` (as
+with `int* x;`), `x` must always be assumed to have a singular value of
+a pointer. — *end example*]
+Results of most expressions are undefined for singular values; the only
+exceptions are destroying an iterator that holds a singular value, the
+assignment of a non-singular value to an iterator that holds a singular
+value, and, for iterators that satisfy the `DefaultConstructible`
+requirements, using a value-initialized iterator as the source of a copy
+or move operation.
+[*Note 3*: This guarantee is not offered for default-initialization,
+although the distinction only matters for types with trivial default
+constructors such as pointers or aggregates holding
+pointers. — *end note*]
+In these cases the singular value is overwritten the same way as any
+other value. Dereferenceable values are always non-singular.
 An iterator `j` is called *reachable* from an iterator `i` if and only
 if there is a finite sequence of applications of the expression `++i`
 that makes `i == j`. If `j` is reachable from `i`, they refer to
 elements of the same sequence.
 `const X`, `difference_type` and `reference` refer to the types
 `iterator_traits<X>::difference_type` and
 `iterator_traits<X>::reference`, respectively, `n` denotes a value of
 `difference_type`, `u`, `tmp`, and `m` denote identifiers, `r` denotes a
 value of `X&`, `t` denotes a value of value type `T`, `o` denotes a
+value of some type that is writable to the output iterator.
+[*Note 4*: For an iterator type `X` there must be an instantiation of
+`iterator_traits<X>` ([[iterator.traits]]). — *end note*]
 ### Iterator <a id="iterator.iterators">[[iterator.iterators]]</a>
 The `Iterator` requirements form the basis of the iterator concept
 taxonomy; every iterator satisfies the `Iterator` requirements. This set
 of requirements specifies operations for dereferencing and incrementing
 an iterator. Most algorithms will require additional operations to
 read ([[input.iterators]]) or write ([[output.iterators]]) values, or
 to provide a richer set of iterator movements ([[forward.iterators]],
+[[bidirectional.iterators]], [[random.access.iterators]]).
 A type `X` satisfies the `Iterator` requirements if:
 - `X` satisfies the `CopyConstructible`, `CopyAssignable`, and
   `Destructible` requirements ([[utility.arg.requirements]]) and
   have the indicated semantics.
 ### Input iterators <a id="input.iterators">[[input.iterators]]</a>
 A class or pointer type `X` satisfies the requirements of an input
+iterator for the value type `T` if `X` satisfies the `Iterator` (
 [[iterator.iterators]]) and `EqualityComparable` (Table
+[[tab:equalitycomparable]]) requirements and the expressions in Table
 [[tab:iterator.input.requirements]] are valid and have the indicated
 semantics.
 In Table  [[tab:iterator.input.requirements]], the term *the domain of
 `==`* is used in the ordinary mathematical sense to denote the set of
 values over which `==` is (required to be) defined. This set can change
 over time. Each algorithm places additional requirements on the domain
 of `==` for the iterator values it uses. These requirements can be
+inferred from the uses that algorithm makes of `==` and `!=`.
+[*Example 1*: The call `find(a,b,x)` is defined only if the value of
+`a` has the property *p* defined as follows: `b` has property *p* and a
+value `i` has property *p* if (`*i==x`) or if (`*i!=x` and `++i` has
+property *p*). — *end example*]
+[*Note 1*: For input iterators, `a == b` does not imply `++a == ++b`.
+(Equality does not guarantee the substitution property or referential
 transparency.) Algorithms on input iterators should never attempt to
 pass through the same iterator twice. They should be *single pass*
+algorithms. Value type `T` is not required to be a `CopyAssignable` type
+(Table  [[tab:copyassignable]]). These algorithms can be used with
+istreams as the source of the input data through the `istream_iterator`
+class template. — *end note*]
 ### Output iterators <a id="output.iterators">[[output.iterators]]</a>
 A class or pointer type `X` satisfies the requirements of an output
 iterator if `X` satisfies the `Iterator` requirements (
 [[iterator.iterators]]) and the expressions in Table
 [[tab:iterator.output.requirements]] are valid and have the indicated
 semantics.
+[*Note 1*: The only valid use of an `operator*` is on the left side of
+the assignment statement. *Assignment through the same value of the
+iterator happens only once.* Algorithms on output iterators should never
+attempt to pass through the same iterator twice. They should be *single
+pass* algorithms. Equality and inequality might not be defined.
+Algorithms that take output iterators can be used with ostreams as the
+destination for placing data through the `ostream_iterator` class as
+well as with insert iterators and insert pointers. — *end note*]
 ### Forward iterators <a id="forward.iterators">[[forward.iterators]]</a>
 A class or pointer type `X` satisfies the requirements of a forward
 iterator if
 - `X` satisfies the requirements of an input iterator (
   [[input.iterators]]),
+- `X` satisfies the `DefaultConstructible` requirements (
   [[utility.arg.requirements]]),
 - if `X` is a mutable iterator, `reference` is a reference to `T`; if
+  `X` is a constant iterator, `reference` is a reference to `const T`,
 - the expressions in Table  [[tab:iterator.forward.requirements]] are
   valid and have the indicated semantics, and
 - objects of type `X` offer the multi-pass guarantee, described below.
+The domain of `==` for forward iterators is that of iterators over the
 same underlying sequence. However, value-initialized iterators may be
 compared and shall compare equal to other value-initialized iterators of
+the same type.
+[*Note 1*: Value-initialized iterators behave as if they refer past the
+end of the same empty sequence. — *end note*]
 Two dereferenceable iterators `a` and `b` of type `X` offer the
 *multi-pass guarantee* if:
 - `a == b` implies `++a == ++b` and
 - `X` is a pointer type or the expression `(void)++X(a), *a` is
   equivalent to the expression `*a`.
+[*Note 2*: The requirement that `a == b` implies `++a == ++b` (which is
+not true for input and output iterators) and the removal of the
+restrictions on the number of the assignments through a mutable iterator
+(which applies to output iterators) allows the use of multi-pass
+one-directional algorithms with forward iterators. — *end note*]
 If `a` and `b` are equal, then either `a` and `b` are both
 dereferenceable or else neither is dereferenceable.
 If `a` and `b` are both dereferenceable, then `a == b` if and only if
 A class or pointer type `X` satisfies the requirements of a
 bidirectional iterator if, in addition to satisfying the requirements
 for forward iterators, the following expressions are valid as shown in
 Table  [[tab:iterator.bidirectional.requirements]].
+[*Note 1*: Bidirectional iterators allow algorithms to move iterators
+backward as well as forward. — *end note*]
 ### Random access iterators <a id="random.access.iterators">[[random.access.iterators]]</a>
 A class or pointer type `X` satisfies the requirements of a random
 access iterator if, in addition to satisfying the requirements for

Diff to HTML by rtfpessoa