Skip to content

Commit ac5ac45

Browse files
jwakelyjwakely
committed
Jonathan adds wording to 4123
1 parent effb6cf commit ac5ac45

File tree

1 file changed

+364
-0
lines changed

1 file changed

+364
-0
lines changed

‎xml/issue4123.xml

Lines changed: 364 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,13 +77,377 @@ is exactly equal to the size of the range.
7777
This should talk about calls to `allocator_traits::destroy`.
7878
</p>
7979
<p>
80+
<sref ref="[deque.modifiers]"/> is similar.
8081
Look for similar problems elsewhere.
8182
</p>
83+
84+
<note>2024-12-06; Jonathan adds wording, incorporating Arthur's wording</note>
8285
</discussion>
8386

8487
<resolution>
8588
<p>
89+
This wording is relative to <paper num="N4993"/>.
90+
</p>
91+
92+
<ol>
93+
<li>
94+
<p>Modify <sref ref="[deque.capacity]"/> as indicated:</p>
95+
<blockquote>
96+
<pre>void shrink_to_fit();</pre>
97+
<p>
98+
-5- <i>Preconditions</i>:
99+
`T` is <i>CppMoveInsertable</i> into `deque`.
100+
</p>
101+
<p>
102+
-6- <i>Effects</i>:
103+
`shrink_to_fit` is a non-binding request to reduce memory use
104+
but does not change the size of the sequence.
105+
[<i>Note 1</i>:
106+
The request is non-binding to allow latitude for
107+
implementation-specific optimizations.
108+
&mdash; <i>end note</i>]
109+
If the size is equal to the old capacity, or
110+
if an exception is thrown other than by the <del>move constructor</del>
111+
<ins>move-construction of one object</ins>
112+
of a non-<i>Cpp17CopyInsertable</i> <ins>type</ins> `T`
113+
<ins>from another</ins>,
114+
then there are no effects.
115+
</p>
116+
</blockquote>
117+
</li>
118+
<li>
119+
<p>Modify <sref ref="[deque.modifiers]"/> as indicated:</p>
120+
<blockquote>
121+
<pre>iterator insert(const_iterator position, const T&amp; x);
122+
...
123+
template&lt;<i>container-compatible-range</i>&lt;T&gt; R&gt;
124+
void append_range(R&amp;&amp; rg);</pre>
125+
<p>
126+
-1- <i>Effects</i>: [...]
86127
</p>
128+
<p>
129+
-2- <i>Complexity</i>:
130+
The complexity is linear in the number of elements inserted plus
131+
the lesser of the distances to the beginning and end of the deque.
132+
Inserting a single element at either the beginning or end of a deque
133+
always takes constant time and causes
134+
<del>a single call to a constructor of T</del>
135+
<ins>construction of a single object of type `T`</ins>.
136+
</p>
137+
<p>
138+
-3- <i>Remarks</i>:
139+
If an exception is thrown other than by the
140+
<del>copy constructor, move constructor,
141+
assignment operator, or move assignment operator of `T`
142+
</del>
143+
<ins>
144+
construction or assignment of one object of type `T` from another
145+
</ins>,
146+
there are no effects.
147+
If an exception is thrown while inserting a single element at either end,
148+
there are no effects.
149+
Otherwise, if an exception is thrown by the
150+
<del>move constructor of a</del>
151+
<ins>move-construction of one object of</ins>
152+
non-<i>Cpp17CopyInsertable</i>
153+
<ins>type</ins>
154+
`T` <ins>from another</ins>, the effects are unspecified.
155+
<p>[...]</p>
156+
-5- <i>Throws</i>:
157+
Nothing unless an exception is thrown by
158+
<del>the assignment operator of `T`</del>
159+
<ins>
160+
the assignment of one object of type `T` from another
161+
</ins>.
162+
</p>
163+
<pre>iterator erase(const_iterator position);
164+
iterator erase(const_iterator first, const_iterator last);
165+
void pop_front();
166+
void pop_back();</pre>
167+
<p>
168+
-4- <i>Effects</i>:
169+
An erase operation that erases the last element of a deque invalidates only
170+
the past-the-end iterator
171+
and all iterators and references to the erased elements.
172+
An erase operation that erases the first element of a deque but not the last
173+
element invalidates only iterators and references to the erased elements.
174+
An erase operation that erases neither the first element nor the last element
175+
of a deque invalidates the past-the-end iterator and all iterators and
176+
references to all the elements of the deque.
177+
</p>
178+
<p>
179+
[<i>Note 1</i>:
180+
`pop_front` and `pop_back` are erase operations.
181+
&mdash; <i>end note</i>]
182+
</p>
183+
<p>
184+
-5- <i>Throws</i>:
185+
Nothing unless an exception is thrown by <del>the</del><ins>an</ins>
186+
assignment operator of `T`.
187+
</p>
188+
<p>
189+
-6- <i>Complexity</i>:
190+
The number of
191+
<del>calls to the destructor of `T`</del>
192+
<ins>objects of type `T` destroyed</ins>
193+
is the same as the number of
194+
elements erased, but the number of calls to the assignment operator of `T`
195+
is no more than the lesser of the number of elements before the erased
196+
elements and the number of elements after the erased elements.
197+
</p>
198+
</blockquote>
199+
</li>
200+
<li>
201+
<p>Modify <sref ref="[forward.list.modifiers]"/> as indicated:</p>
202+
<blockquote>
203+
<p>
204+
-1- [...]
205+
Inserting `n` elements into a `forward_list` is linear in
206+
`n`, and the number of <del>calls to the copy or move constructor of</del>
207+
<ins>objects of type</ins> `T` <ins>constructed</ins> is
208+
exactly equal to `n`. Erasing `n` elements from a `forward_list` is
209+
linear in `n` and the number of <del>calls to the destructor of</del>
210+
<ins>objects of</ins> type `T` <ins>destroyed</ins> is exactly equal to `n`.
211+
</p>
212+
</blockquote>
213+
</li>
214+
<li>
215+
<p>Modify <sref ref="[list.modifiers]"/> as indicated:</p>
216+
<blockquote>
217+
<p>
218+
-1- <i>Complexity</i>:
219+
Insertion of a single element into a list takes constant time and exactly one
220+
<del>call to a constructor of `T`</del>
221+
<ins>object of type `T` is constructed</ins>
222+
Insertion of multiple elements into a list is linear in the number of
223+
elements inserted and the number of
224+
<del>calls to the copy constructor or move constructor of `T`</del>
225+
<ins>objects of type `T` constructed</ins>
226+
is exactly equal to the number of elements inserted.
227+
</p>
228+
<p>
229+
-2- <i>Remarks</i>:
230+
Does not affect the validity of iterators and references.
231+
If an exception is thrown, there are no effects.
232+
</p>
233+
<pre>iterator erase(const_iterator position);
234+
iterator erase(const_iterator first, const_iterator last);
235+
void pop_front();
236+
void pop_back();
237+
void clear() noexcept;</pre>
238+
<p>
239+
-3- <i>Effects</i>:
240+
Invalidates only the iterators and references to the erased elements.
241+
</p>
242+
<p>
243+
-4- <i>Throws</i>: Nothing.
244+
</p>
245+
<p>
246+
-5- <i>Complexity</i>:
247+
Erasing a single element is a constant time operation with a single
248+
<del>call to the destructor of `T`</del>
249+
<ins>object of type `T` destroyed</ins>.
250+
Erasing a range in a list is linear time in the
251+
size of the range and the number of
252+
<del>calls to the destructor of type `T`</del>
253+
<ins>objects of type `T` destroyed</ins>
254+
is exactly equal to the size of the range.
255+
</p>
256+
</blockquote>
257+
</li>
258+
<li>
259+
<p>Modify <sref ref="[vector.cons]"/> as indicated:</p>
260+
<blockquote>
261+
<pre>template&lt;class InputIterator&gt;
262+
constexpr vector(InputIterator first, InputIterator last,
263+
const Allocator&amp; = Allocator());</pre>
264+
<p>
265+
-9- <i>Effects</i>:
266+
Constructs a `vector` equal to the range [`first`, `last`),
267+
using the specified allocator.
268+
</p>
269+
<p>
270+
-10- <i>Complexity</i>:
271+
<del>Makes only <i>N</i> calls to the copy constructor of</del>
272+
<ins>Initializes exactly <i>N</i> objects of type</ins>
273+
`T`
274+
(where <i>N</i> is the distance between `first` and `last`)
275+
and no reallocations if iterators `first` and `last` are of forward,
276+
bidirectional, or random access categories.
277+
It <del>makes</del> <ins>initializes</ins> order
278+
<i>N</i>
279+
<del>calls to the copy constructor of</del>
280+
<ins>objects of type</ins>
281+
`T` and <ins>performs</ins>
282+
order log <i>N</i> reallocations if they are just input iterators.
283+
</p>
284+
<pre>template&lt;<i>container-compatible-range</i>&lt;T&gt; R&gt;
285+
constexpr vector(from_range_t, R&amp;&amp; rg, const Allocator&amp; = Allocator());</pre>
286+
<p>
287+
-11- <i>Effects</i>:
288+
Constructs a `vector` object with the elements of the range `rg`,
289+
using the specified allocator.
290+
</p>
291+
<p>
292+
-12- <i>Complexity</i>:
293+
Initializes exactly <i>N</i> elements from the results of dereferencing
294+
successive iterators of `rg`, where <i>N</i> is `ranges::distance(rg)`.
295+
Performs no reallocations if `R` models `ranges::forward_range` or
296+
`ranges::sized_range`; otherwise, performs order log <i>N</i> reallocations
297+
and <ins>initializes</ins> order <i>N</i>
298+
<del>calls to the copy or move constructor of</del>
299+
<ins>objects of type</ins> `T`.
300+
</p>
301+
</blockquote>
302+
</li>
303+
<li>
304+
<p>Modify <sref ref="[vector.capacity]"/> as indicated:</p>
305+
<blockquote>
306+
<pre>constexpr void reserve(size_type n);</pre>
307+
<p>
308+
-3- <i>Preconditions</i>:
309+
`T` is <i>CppMoveInsertable</i> into `vector`.
310+
</p>
311+
<p>
312+
-4- <i>Effects</i>:
313+
A directive that informs a `vector` of a planned change in size,
314+
so that it can manage the storage allocation accordingly.
315+
After `reserve<del>()</del>`, `capacity()` is greater or equal to
316+
the argument of `reserve` if reallocation happens;
317+
and equal to the previous value of `capacity()` otherwise.
318+
Reallocation happens at this point if and only if
319+
the current capacity is less than the argument of `reserve<del>()</del>`.
320+
If an exception is thrown other than by the
321+
<del>move constructor of a</del>
322+
<ins>move-construction of one object of</ins>
323+
non-<i>Cpp17CopyInsertable</i>
324+
<ins>type</ins> `T` <ins>from another</ins>, there are no effects.
325+
</p>
326+
<p>[...]</p>
327+
<pre>constexpr shrink_to_fit();</pre>
328+
<p>
329+
-8- <i>Preconditions</i>:
330+
`T` is <i>CppMoveInsertable</i> into `vector`.
331+
</p>
332+
<p>
333+
-9- <i>Effects</i>:
334+
`shrink_to_fit` is a non-binding request to reduce `capacity()` to `size()`.
335+
[<i>Note 2</i>:
336+
The request is non-binding to allow latitude for
337+
implementation-specific optimizations.
338+
&mdash; <i>end note</i>]
339+
It does not increase `capacity()`, but may reduce `capacity()` by causing
340+
reallocation.
341+
If an exception is thrown other than by the <del>move constructor</del>
342+
<ins>move-construction of one object</ins>
343+
of a non-<i>Cpp17CopyInsertable</i> <ins>type</ins> `T`
344+
<ins>from another</ins>,
345+
there are no effects.
346+
</p>
347+
<p>[...]</p>
348+
<pre>constexpr void resize(size_type sz);</pre>
349+
<p>
350+
-14- <i>Preconditions</i>:
351+
`T` is <i>Cpp17MoveInsertable</i> and <i>Cpp17DefaultInsertable</i> into
352+
`vector`.
353+
</p>
354+
<p>
355+
-15- <i>Effects</i>: [...]
356+
</p>
357+
<p>
358+
-16- <i>Remarks</i>:
359+
If an exception is thrown other than by the <del>move constructor</del>
360+
<ins>move-construction of one object</ins>
361+
of a non-<i>Cpp17CopyInsertable</i> <ins>type</ins> `T`
362+
<ins>from another</ins>,
363+
there are no effects.
364+
</p>
365+
</blockquote>
366+
</li>
367+
<li>
368+
<p>Modify <sref ref="[vector.modifiers]"/> as indicated:</p>
369+
<blockquote>
370+
<pre>iterator insert(const_iterator position, const T&amp; x);
371+
...
372+
template&lt;<i>container-compatible-range</i>&lt;T&gt; R&gt;
373+
void append_range(R&amp;&amp; rg);</pre>
374+
<p>
375+
-1- <i>Complexity</i>: [...]
376+
</p>
377+
<p>
378+
-2- <i>Remarks</i>:
379+
Causes reallocation if the new size is greater than the old capacity.
380+
Reallocation invalidates all the references, pointers, and iterators
381+
referring to the elements in the sequence, as well as the past-the-end iterator.
382+
If no reallocation happens, then
383+
references, pointers, and iterators
384+
before the insertion point remain valid
385+
but those at or after the insertion point,
386+
including the past-the-end iterator,
387+
are invalidated.
388+
If an exception is thrown other than by the
389+
<del>copy constructor, move constructor,
390+
assignment operator, or move assignment operator of
391+
`T` or by any \tcode{InputIterator} operation</del>
392+
<ins>the construction or assignment of one object of type `T` from another,
393+
or by any `InputIterator` operation</ins>,
394+
there are no effects.
395+
If an exception is thrown while inserting a single element at the end and
396+
`T` is <i>Cpp17CopyInsertable</i> or
397+
<code>is_nothrow_move_constructible_v&lt;T&gt;</code> is `true`,
398+
there are no effects.
399+
Otherwise, if an exception is thrown by the
400+
<del>move constructor of a</del>
401+
<ins>move-construction of one object of</ins>
402+
non-<i>Cpp17CopyInsertable</i>
403+
<ins>type</ins>
404+
`T` <ins>from another</ins>, the effects are unspecified.
405+
</p>
406+
<pre>constexpr iterator erase(const_iterator position);
407+
constexpr iterator erase(const_iterator first, const_iterator last);
408+
constexpr void pop_back();</pre>
409+
<p>
410+
-3- <i>Effects</i>:
411+
Invalidates iterators and references at or after the point of the erase.
412+
</p>
413+
<p>
414+
-4- <i>Throws</i>:
415+
Nothing unless an exception is thrown by the
416+
<del>assignment operator or move assignment operator of `T`</del>
417+
<ins>construction or assignment of one object of type `T` from another</ins>.
418+
</p>
419+
<p>
420+
-5- <i>Complexity</i>:
421+
The
422+
<del>destructor of `T` is called the number of times</del>
423+
<ins>number of objects of type `T` destroyed is</ins>
424+
equal to the number of the elements erased,
425+
but <del>the</del><ins>an</ins>
426+
assignment operator of `T` is called the number of times equal to
427+
the number of elements in the vector after the erased elements.
428+
</p>
429+
</blockquote>
430+
</li>
431+
<li>
432+
<p>Modify <sref ref="[inplace.vector.modifiers]"/> as indicated:</p>
433+
<blockquote>
434+
<pre>constexpr iterator erase(const_iterator position);
435+
constexpr iterator erase(const_iterator first, const_iterator last);
436+
constexpr void pop_back();</pre>
437+
<p>
438+
-29- <i>Complexity</i>:
439+
The
440+
<del>destructor of `T` is called the number of times</del>
441+
<ins>number of objects of type `T` destroyed is</ins>
442+
equal to the number of the elements erased,
443+
but <del>the</del><ins>an</ins>
444+
assignment operator of `T` is called the number of times equal to
445+
the number of elements after the erased elements.
446+
</p>
447+
</blockquote>
448+
</li>
449+
450+
</ol>
87451
</resolution>
88452

89453
</issue>

0 commit comments

Comments
 (0)