[iterator.requirements.general]

Files changed (1) hide show

tmp/tmpvevux_ok/{from.md → to.md} +81 -71

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

@@ -1,48 +1,60 @@
 ### In general <a id="iterator.requirements.general">[[iterator.requirements.general]]</a>
 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.
-Since iterators are an abstraction of pointers, their semantics is a
 generalization of most of the semantics of pointers in C++. This ensures
 that every function template that takes iterators works as well with
-regular pointers. This International Standard defines five categories of
-iterators, according to the operations defined on them: *input
-iterators*, *output iterators*, *forward iterators*, *bidirectional
-iterators* and *random access iterators*, as shown in Table
-[[tab:iterators.relations]].
-**Table: Relations among iterator categories** <a id="tab:iterators.relations">[tab:iterators.relations]</a>
-| |                                 |                           |                          |
-| ----------------- | ------------------------------- | ------------------------- | ------------------------ |
-| **Random Access** | $\rightarrow$ **Bidirectional** | $\rightarrow$ **Forward** | $\rightarrow$ **Input**  |
-| |                                 |                           | $\rightarrow$ **Output** |
-Forward iterators satisfy all the requirements of input iterators and
-can be used whenever an input iterator is specified; Bidirectional
-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 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
@@ -50,24 +62,14 @@ 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.
@@ -76,52 +78,60 @@ 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.
 Most of the library’s algorithmic templates that operate on data
-structures have interfaces that use ranges. A *range* is a pair of
-iterators that designate the beginning and end of the computation. A
-range \[`i`, `i`) is an empty range; in general, a range \[`i`, `j`)
-refers to the elements in the data structure starting with the element
-pointed to by `i` and up to but not including the element pointed to by
-`j`. Range \[`i`, `j`) is valid if and only if `j` is reachable from
-`i`. The result of the application of functions in the library to
-invalid ranges is undefined.
 All the categories of iterators require only those functions that are
 realizable for a given category in constant time (amortized). Therefore,
-requirement tables for the iterators do not have a complexity column.
-Destruction of an iterator may invalidate pointers and references
-previously obtained from that iterator.
-An *invalid* iterator is an iterator that may be singular.[^1]
-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.
-[*Note 4*: For an iterator type `X` there must be an instantiation of
-`iterator_traits<X>` ([[iterator.traits]]). — *end note*]

 ### In general <a id="iterator.requirements.general">[[iterator.requirements.general]]</a>
 Iterators are a generalization of pointers that allow a C++ program to
+work with different data structures (for example, containers and ranges)
+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 `indirectly_writable` to the iterator;
+for each such type `T`, the expression `*i = o` is valid where `o` is a
+value of type `T`. For every iterator type `X`, there is a corresponding
+signed integer-like type [[iterator.concept.winc]] called the
+*difference type* of the iterator.
+Since iterators are an abstraction of pointers, their semantics are a
 generalization of most of the semantics of pointers in C++. This ensures
 that every function template that takes iterators works as well with
+regular pointers. This document defines six categories of iterators,
+according to the operations defined on them: *input iterators*, *output
+iterators*, *forward iterators*, *bidirectional iterators*, *random
+access iterators*, and *contiguous iterators*, as shown in
+[[iterators.relations]].
+**Table: Relations among iterator categories** <a id="iterators.relations">[iterators.relations]</a>
+| |                                 |                                 |                           |                          |
+| -------------- | ------------------------------- | ------------------------------- | ------------------------- | ------------------------ |
+| **Contiguous** | $\rightarrow$ **Random Access** | $\rightarrow$ **Bidirectional** | $\rightarrow$ **Forward** | $\rightarrow$ **Input**  |
+| |                                 |                                 |                           | $\rightarrow$ **Output** |
+The six categories of iterators correspond to the iterator concepts
+- `input_iterator` [[iterator.concept.input]],
+- `output_iterator` [[iterator.concept.output]],
+- `forward_iterator` [[iterator.concept.forward]],
+- `bidirectional_iterator` [[iterator.concept.bidir]]
+- `random_access_iterator` [[iterator.concept.random.access]], and
+- `contiguous_iterator` [[iterator.concept.contiguous]],
+respectively. The generic term *iterator* refers to any type that models
+the `input_or_output_iterator` concept [[iterator.concept.iterator]].
+Forward iterators meet all the requirements of input iterators and can
+be used whenever an input iterator is specified; Bidirectional iterators
+also meet all the requirements of forward iterators and can be used
+whenever a forward iterator is specified; Random access iterators also
+meet all the requirements of bidirectional iterators and can be used
+whenever a bidirectional iterator is specified; Contiguous iterators
+also meet all the requirements of random access iterators and can be
+used whenever a random access iterator is specified.
+Iterators that further meet 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
 [*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*]
 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. Such a value is called a *past-the-end value*.
 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.
 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 meet the *Cpp17DefaultConstructible*
 requirements, using a value-initialized iterator as the source of a copy
 or move operation.
+[*Note 2*: 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.
 Most of the library’s algorithmic templates that operate on data
+structures have interfaces that use ranges. A *range* is an iterator and
+a *sentinel* that designate the beginning and end of the computation, or
+an iterator and a count that designate the beginning and the number of
+elements to which the computation is to be applied.[^1]
+An iterator and a sentinel denoting a range are comparable. A range
+\[`i`, `s`) is empty if `i == s`; otherwise, \[`i`, `s`) refers to the
+elements in the data structure starting with the element pointed to by
+`i` and up to but not including the element, if any, pointed to by the
+first iterator `j` such that `j == s`.
+A sentinel `s` 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 == s`. If `s` is reachable from `i`, \[`i`, `s`) denotes a
+valid range.
+A *counted range* `i`+\[0, `n`) is empty if `n == 0`; otherwise,
+`i`+\[0, `n`) refers to the `n` elements in the data structure starting
+with the element pointed to by `i` and up to but not including the
+element, if any, pointed to by the result of `n` applications of `++i`.
+A counted range `i`+\[0, `n`) is valid if and only if `n == 0`; or `n`
+is positive, `i` is dereferenceable, and `++i`+\[0, `-``-``n`) is valid.
+The result of the application of library functions to invalid ranges is
+undefined.
 All the categories of iterators require only those functions that are
 realizable for a given category in constant time (amortized). Therefore,
+requirement tables and concept definitions for the iterators do not
+specify complexity.
+Destruction of a non-forward iterator may invalidate pointers and
+references previously obtained from that iterator.
+An *invalid iterator* is an iterator that may be singular.[^2]
+Iterators are called *constexpr iterators* if all operations provided to
+meet iterator category requirements are constexpr functions.
+[*Note 3*: For example, the types “pointer to `int`” and
+`reverse_iterator<int*>` are constexpr iterators. — *end note*]

Diff to HTML by rtfpessoa