From Jason Turner

[iterator.requirements.general]

C++23 → Trunk 4.0 KB 44 lines
Current Draft | LaTeX Source
Archived: C++23
Markdown: C++23 | Trunk
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpabb1j4re/{from.md → to.md} +28 -12
tmp/tmpabb1j4re/{from.md → to.md} RENAMED
@@ -1,20 +1,20 @@
1
- ### In general <a id="iterator.requirements.general">[[iterator.requirements.general]]</a>
2
 
3
  Iterators are a generalization of pointers that allow a C++ program to
4
  work with different data structures (for example, containers and ranges)
5
  in a uniform manner. To be able to construct template algorithms that
6
  work correctly and efficiently on different types of data structures,
7
  the library formalizes not just the interfaces but also the semantics
8
  and complexity assumptions of iterators. An input iterator `i` supports
9
  the expression `*i`, resulting in a value of some object type `T`,
10
  called the *value type* of the iterator. An output iterator `i` has a
11
- non-empty set of types that are `indirectly_writable` to the iterator;
12
- for each such type `T`, the expression `*i = o` is valid where `o` is a
13
- value of type `T`. For every iterator type `X`, there is a corresponding
14
- signed integer-like type [[iterator.concept.winc]] called the
15
- *difference type* of the iterator.
16
 
17
  Since iterators are an abstraction of pointers, their semantics are a
18
  generalization of most of the semantics of pointers in C++. This ensures
19
  that every function template that takes iterators works as well with
20
  regular pointers. This document defines six categories of iterators,
@@ -111,21 +111,37 @@ A counted range `i`+\[0, `n`) is *valid* if and only if `n == 0`; or `n`
111
  is positive, `i` is dereferenceable, and `++i`+\[0, `–n`) is valid.
112
 
113
  The result of the application of library functions to invalid ranges is
114
  undefined.
115
 
 
 
 
 
 
 
 
 
 
 
 
 
 
116
  All the categories of iterators require only those functions that are
117
  realizable for a given category in constant time (amortized). Therefore,
118
  requirement tables and concept definitions for the iterators do not
119
  specify complexity.
120
 
121
- Destruction of a non-forward iterator may invalidate pointers and
122
- references previously obtained from that iterator.
 
 
123
 
124
  An *invalid iterator* is an iterator that may be singular.[^2]
125
 
126
- Iterators are called *constexpr iterators* if all operations provided to
127
- meet iterator category requirements are constexpr functions.
128
 
129
- [*Note 3*: For example, the types “pointer to `int`” and
130
- `reverse_iterator<int*>` are constexpr iterators. — *end note*]
 
131
 
 
1
+ ### General <a id="iterator.requirements.general">[[iterator.requirements.general]]</a>
2
 
3
  Iterators are a generalization of pointers that allow a C++ program to
4
  work with different data structures (for example, containers and ranges)
5
  in a uniform manner. To be able to construct template algorithms that
6
  work correctly and efficiently on different types of data structures,
7
  the library formalizes not just the interfaces but also the semantics
8
  and complexity assumptions of iterators. An input iterator `i` supports
9
  the expression `*i`, resulting in a value of some object type `T`,
10
  called the *value type* of the iterator. An output iterator `i` has a
11
+ non-empty set of types that are *writable* to the iterator; for each
12
+ such type `T`, the expression `*i = o` is valid where `o` is a value of
13
+ type `T`. For every iterator type `X`, there is a corresponding signed
14
+ integer-like type [[iterator.concept.winc]] called the *difference type*
15
+ of the iterator.
16
 
17
  Since iterators are an abstraction of pointers, their semantics are a
18
  generalization of most of the semantics of pointers in C++. This ensures
19
  that every function template that takes iterators works as well with
20
  regular pointers. This document defines six categories of iterators,
 
111
  is positive, `i` is dereferenceable, and `++i`+\[0, `–n`) is valid.
112
 
113
  The result of the application of library functions to invalid ranges is
114
  undefined.
115
 
116
+ For an iterator `i` of a type that models `contiguous_iterator`
117
+ [[iterator.concept.contiguous]], library functions are permitted to
118
+ replace \[`i`, `s`) with \[`to_address(i)`,
119
+ `to_address(i + ranges::distance(i, s))`), and to replace `i`+\[0, `n`)
120
+ with \[`to_address(i)`, `to_address(i + n)`).
121
+
122
+ [*Note 3*: This means a program cannot rely on any side effects of
123
+ dereferencing a contiguous iterator `i`, because library functions might
124
+ operate on pointers obtained by `to_address(i)` instead of operating on
125
+ `i`. Similarly, a program cannot rely on any side effects of individual
126
+ increments on a contiguous iterator `i`, because library functions might
127
+ advance `i` only once. — *end note*]
128
+
129
  All the categories of iterators require only those functions that are
130
  realizable for a given category in constant time (amortized). Therefore,
131
  requirement tables and concept definitions for the iterators do not
132
  specify complexity.
133
 
134
+ Destruction of an iterator may invalidate pointers and references
135
+ previously obtained from that iterator if its type does not meet the
136
+ *Cpp17ForwardIterator* requirements and does not model
137
+ `forward_iterator`.
138
 
139
  An *invalid iterator* is an iterator that may be singular.[^2]
140
 
141
+ Iterators meet the *constexpr iterator* requirements if all operations
142
+ provided to meet iterator category requirements are constexpr functions.
143
 
144
+ [*Note 4*: For example, the types “pointer to `int`” and
145
+ `reverse_iterator<int*>` meet the constexpr iterator
146
+ requirements. — *end note*]
147