[sequence.reqmts] - C++23 → Trunk

Files changed (1) hide show

tmp/tmp5lwfn90h/{from.md → to.md} +79 -59

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

@@ -1,27 +1,20 @@
 ### Sequence containers <a id="sequence.reqmts">[[sequence.reqmts]]</a>
 A sequence container organizes a finite set of objects, all of the same
-type, into a strictly linear arrangement. The library provides four
-basic kinds of sequence containers: `vector`, `forward_list`, `list`,
-and `deque`. In addition, `array` is provided as a sequence container
-which provides limited sequence operations because it has a fixed number
-of elements. The library also provides container adaptors that make it
 easy to construct abstract data types, such as `stack`s, `queue`s,
 `flat_map`s, `flat_multimap`s, `flat_set`s, or `flat_multiset`s, out of
 the basic sequence container kinds (or out of other program-defined
 sequence containers).
-[*Note 1*: The sequence containers offer the programmer different
-complexity trade-offs. `vector` is appropriate in most circumstances.
-`array` has a fixed size known during translation. `list` or
-`forward_list` support frequent insertions and deletions from the middle
-of the sequence. `deque` supports efficient insertions and deletions
-taking place at the beginning or at the end of the sequence. When
-choosing a container, remember `vector` is best; leave a comment to
-explain if you choose from the rest! — *end note*]
 In this subclause,
 - `X` denotes a sequence container class,
 - `a` denotes a value of type `X` containing elements of type `T`,
 - `u` denotes the name of a variable being declared,
@@ -29,18 +22,18 @@ In this subclause,
   `X::allocator_type` is valid and denotes a type [[temp.deduct]] and
   `allocator<T>` if it doesn’t,
 - `i` and `j` denote iterators that meet the *Cpp17InputIterator*
   requirements and refer to elements implicitly convertible to
   `value_type`,
-- `[i, j)` denotes a valid range,
 - `rg` denotes a value of a type `R` that models
   `container-compatible-range<T>`,
 - `il` designates an object of type `initializer_list<value_type>`,
 - `n` denotes a value of type `X::size_type`,
 - `p` denotes a valid constant iterator to `a`,
 - `q` denotes a valid dereferenceable constant iterator to `a`,
-- `[q1, q2)` denotes a valid range of constant iterators in `a`,
 - `t` denotes an lvalue or a const rvalue of `X::value_type`, and
 - `rv` denotes a non-const rvalue of `X::value_type`.
 - `Args` denotes a template parameter pack;
 - `args` denotes a function parameter pack with the pattern `Args&&`.
@@ -67,27 +60,34 @@ X u(i, j);
 *Preconditions:* `T` is *Cpp17EmplaceConstructible* into `X` from `*i`.
 For `vector`, if the iterator does not meet the *Cpp17ForwardIterator*
 requirements [[forward.iterators]], `T` is also *Cpp17MoveInsertable*
 into `X`.
-*Effects:* Constructs a sequence container equal to the range `[i, j)`.
-Each iterator in the range \[`i`, `j`) is dereferenced exactly once.
 *Ensures:* `distance(u.begin(), u.end()) == distance(i, j)` is `true`.
 ``` cpp
 X(from_range, rg)
 ```
 *Preconditions:* `T` is *Cpp17EmplaceConstructible* into `X` from
-`*ranges::begin(rg)`. For `vector`, if `R` models neither
-`ranges::sized_range` nor `ranges::forward_range`, `T` is also
-*Cpp17MoveInsertable* into `X`.
 *Effects:* Constructs a sequence container equal to the range `rg`. Each
 iterator in the range `rg` is dereferenced exactly once.
 *Ensures:* `distance(begin(), end()) == ranges::distance(rg)` is `true`.
 ``` cpp
 X(il)
 ```
@@ -113,30 +113,29 @@ a.emplace(p, args)
 ```
 *Result:* `iterator`.
 *Preconditions:* `T` is *Cpp17EmplaceConstructible* into `X` from
-`args`. For `vector` and `deque`, `T` is also *Cpp17MoveInsertable* into
-`X` and *Cpp17MoveAssignable*.
 *Effects:* Inserts an object of type `T` constructed with
 `std::forward<Args>(args)...` before `p`.
 [*Note 1*: `args` can directly or indirectly refer to a value in
 `a`. — *end note*]
-*Returns:* An iterator that points to the new element constructed from
-`args` into `a`.
 ``` cpp
 a.insert(p, t)
 ```
 *Result:* `iterator`.
-*Preconditions:* `T` is *Cpp17CopyInsertable* into `X`. For `vector` and
-`deque`, `T` is also *Cpp17CopyAssignable*.
 *Effects:* Inserts a copy of `t` before `p`.
 *Returns:* An iterator that points to the copy of `t` inserted into `a`.
@@ -144,12 +143,12 @@ a.insert(p, t)
 a.insert(p, rv)
 ```
 *Result:* `iterator`.
-*Preconditions:* `T` is *Cpp17MoveInsertable* into `X`. For `vector` and
-`deque`, `T` is also *Cpp17MoveAssignable*.
 *Effects:* Inserts a copy of `rv` before `p`.
 *Returns:* An iterator that points to the copy of `rv` inserted into
 `a`.
@@ -173,16 +172,17 @@ a.insert(p, i, j)
 ```
 *Result:* `iterator`.
 *Preconditions:* `T` is *Cpp17EmplaceConstructible* into `X` from `*i`.
-For `vector` and `deque`, `T` is also *Cpp17MoveInsertable* into `X`,
-and `T` meets the *Cpp17MoveConstructible*, *Cpp17MoveAssignable*, and
 *Cpp17Swappable*[[swappable.requirements]] requirements. Neither `i` nor
 `j` are iterators into `a`.
-*Effects:* Inserts copies of elements in `[i, j)` before `p`. Each
 iterator in the range \[`i`, `j`) shall be dereferenced exactly once.
 *Returns:* An iterator that points to the copy of the first element
 inserted into `a`, or `p` if `i == j`.
@@ -191,12 +191,12 @@ a.insert_range(p, rg)
 ```
 *Result:* `iterator`.
 *Preconditions:* `T` is *Cpp17EmplaceConstructible* into `X` from
-`*ranges::begin(rg)`. For `vector` and `deque`, `T` is also
-*Cpp17MoveInsertable* into `X`, and `T` meets the
 *Cpp17MoveConstructible*, *Cpp17MoveAssignable*, and
 *Cpp17Swappable*[[swappable.requirements]] requirements. `rg` and `a` do
 not overlap.
 *Effects:* Inserts copies of elements in `rg` before `p`. Each iterator
@@ -215,11 +215,12 @@ a.insert(p, il)
 a.erase(q)
 ```
 *Result:* `iterator`.
-*Preconditions:* For `vector` and `deque`, `T` is *Cpp17MoveAssignable*.
 *Effects:* Erases the element pointed to by `q`.
 *Returns:* An iterator that points to the element immediately following
 `q` prior to the element being erased. If no such element exists,
@@ -229,13 +230,14 @@ a.erase(q)
 a.erase(q1, q2)
 ```
 *Result:* `iterator`.
-*Preconditions:* For `vector` and `deque`, `T` is *Cpp17MoveAssignable*.
-*Effects:* Erases the elements in the range `[q1, q2)`.
 *Returns:* An iterator that points to the element pointed to by `q2`
 prior to any elements being erased. If no such element exists, `a.end()`
 is returned.
@@ -263,14 +265,15 @@ a.assign(i, j)
 and assignable from `*i`. For `vector`, if the iterator does not meet
 the forward iterator requirements [[forward.iterators]], `T` is also
 *Cpp17MoveInsertable* into `X`. Neither `i` nor `j` are iterators into
 `a`.
-*Effects:* Replaces elements in `a` with a copy of `[i, j)`. Invalidates
-all references, pointers and iterators referring to the elements of `a`.
-For `vector` and `deque`, also invalidates the past-the-end iterator.
-Each iterator in the range \[`i`, `j`) is dereferenced exactly once.
 ``` cpp
 a.assign_range(rg)
 ```
@@ -278,20 +281,26 @@ a.assign_range(rg)
 *Mandates:* `assignable_from<T&, ranges::range_reference_t<R>>` is
 modeled.
 *Preconditions:* `T` is *Cpp17EmplaceConstructible* into `X` from
-`*ranges::begin(rg)`. For `vector`, if `R` models neither
-`ranges::sized_range` nor `ranges::forward_range`, `T` is also
-*Cpp17MoveInsertable* into `X`. `rg` and `a` do not overlap.
 *Effects:* Replaces elements in `a` with a copy of each element in `rg`.
 Invalidates all references, pointers, and iterators referring to the
 elements of `a`. For `vector` and `deque`, also invalidates the
 past-the-end iterator. Each iterator in the range `rg` is dereferenced
 exactly once.
 ``` cpp
 a.assign(il)
 ```
 *Effects:* Equivalent to `a.assign(il.begin(), il.end())`.
@@ -353,31 +362,35 @@ containers but not others. Operations other than `prepend_range` and
 a.front()
 ```
 *Result:* `reference; const_reference` for constant `a`.
 *Returns:* `*a.begin()`
 *Remarks:* Required for `basic_string`, `array`, `deque`,
-`forward_list`, `list`, and `vector`.
 ``` cpp
 a.back()
 ```
 *Result:* `reference; const_reference` for constant `a`.
 *Effects:* Equivalent to:
 ``` cpp
 auto tmp = a.end();
 --tmp;
 return *tmp;
 ```
-*Remarks:* Required for `basic_string`, `array`, `deque`, `list`, and
-`vector`.
 ``` cpp
 a.emplace_front(args)
 ```
@@ -405,11 +418,11 @@ a.emplace_back(args)
 *Effects:* Appends an object of type `T` constructed with
 `std::forward<Args>(args)...`.
 *Returns:* `a.back()`.
-*Remarks:* Required for `deque`, `list`, and `vector`.
 ``` cpp
 a.push_front(t)
 ```
@@ -461,11 +474,12 @@ a.push_back(t)
 *Preconditions:* `T` is *Cpp17CopyInsertable* into `X`.
 *Effects:* Appends a copy of `t`.
-*Remarks:* Required for `basic_string`, `deque`, `list`, and `vector`.
 ``` cpp
 a.push_back(rv)
 ```
@@ -473,11 +487,12 @@ a.push_back(rv)
 *Preconditions:* `T` is *Cpp17MoveInsertable* into `X`.
 *Effects:* Appends a copy of `rv`.
-*Remarks:* Required for `basic_string`, `deque`, `list`, and `vector`.
 ``` cpp
 a.append_range(rg)
 ```
@@ -488,19 +503,19 @@ a.append_range(rg)
 into `X`.
 *Effects:* Inserts copies of elements in `rg` before `end()`. Each
 iterator in the range `rg` is dereferenced exactly once.
-*Remarks:* Required for `deque`, `list`, and `vector`.
 ``` cpp
 a.pop_front()
 ```
 *Result:* `void`
-*Preconditions:* `a.empty()` is `false`.
 *Effects:* Destroys the first element.
 *Remarks:* Required for `deque`, `forward_list`, and `list`.
@@ -508,33 +523,38 @@ a.pop_front()
 a.pop_back()
 ```
 *Result:* `void`
-*Preconditions:* `a.empty()` is `false`.
 *Effects:* Destroys the last element.
-*Remarks:* Required for `basic_string`, `deque`, `list`, and `vector`.
 ``` cpp
 a[n]
 ```
-*Result:* `reference; const_reference` for constant `a`
-*Returns:* `*(a.begin() + n)`
-*Remarks:* Required for `basic_string`, `array`, `deque`, and `vector`.
 ``` cpp
 a.at(n)
 ```
-*Result:* `reference; const_reference` for constant `a`
 *Returns:* `*(a.begin() + n)`
 *Throws:* `out_of_range` if `n >= a.size()`.
-*Remarks:* Required for `basic_string`, `array`, `deque`, and `vector`.

 ### Sequence containers <a id="sequence.reqmts">[[sequence.reqmts]]</a>
 A sequence container organizes a finite set of objects, all of the same
+type, into a strictly linear arrangement. The library provides the
+following basic kinds of sequence containers: `vector`,
+`inplace_vector`, `forward_list`, `list`, and `deque`. In addition,
+`array` and `hive` are provided as sequence containers which provide
+limited sequence operations, in `array`’s case because it has a fixed
+number of elements, and in `hive`’s case because insertion order is
+unspecified. The library also provides container adaptors that make it
 easy to construct abstract data types, such as `stack`s, `queue`s,
 `flat_map`s, `flat_multimap`s, `flat_set`s, or `flat_multiset`s, out of
 the basic sequence container kinds (or out of other program-defined
 sequence containers).
 In this subclause,
 - `X` denotes a sequence container class,
 - `a` denotes a value of type `X` containing elements of type `T`,
 - `u` denotes the name of a variable being declared,
   `X::allocator_type` is valid and denotes a type [[temp.deduct]] and
   `allocator<T>` if it doesn’t,
 - `i` and `j` denote iterators that meet the *Cpp17InputIterator*
   requirements and refer to elements implicitly convertible to
   `value_type`,
+- \[`i`, `j`) denotes a valid range,
 - `rg` denotes a value of a type `R` that models
   `container-compatible-range<T>`,
 - `il` designates an object of type `initializer_list<value_type>`,
 - `n` denotes a value of type `X::size_type`,
 - `p` denotes a valid constant iterator to `a`,
 - `q` denotes a valid dereferenceable constant iterator to `a`,
+- \[`q1`, `q2`) denotes a valid range of constant iterators in `a`,
 - `t` denotes an lvalue or a const rvalue of `X::value_type`, and
 - `rv` denotes a non-const rvalue of `X::value_type`.
 - `Args` denotes a template parameter pack;
 - `args` denotes a function parameter pack with the pattern `Args&&`.
 *Preconditions:* `T` is *Cpp17EmplaceConstructible* into `X` from `*i`.
 For `vector`, if the iterator does not meet the *Cpp17ForwardIterator*
 requirements [[forward.iterators]], `T` is also *Cpp17MoveInsertable*
 into `X`.
+*Effects:* Constructs a sequence container equal to the range \[`i`,
+`j`). Each iterator in the range \[`i`, `j`) is dereferenced exactly
+once.
 *Ensures:* `distance(u.begin(), u.end()) == distance(i, j)` is `true`.
 ``` cpp
 X(from_range, rg)
 ```
 *Preconditions:* `T` is *Cpp17EmplaceConstructible* into `X` from
+`*ranges::begin(rg)`. For `vector`, if `R` models
+`ranges::approximately_sized_range` but not `ranges::sized_range` or
+models `ranges::input_range` but not `ranges::forward_range`, `T` is
+also *Cpp17MoveInsertable* into `X`.
 *Effects:* Constructs a sequence container equal to the range `rg`. Each
 iterator in the range `rg` is dereferenced exactly once.
+*Recommended practice:* If `R` models
+`ranges::approximately_sized_range` and
+`ranges::distance(rg) <= ranges::reserve_hint(rg)` is `true`, an
+implementation should not perform more than a single reallocation.
 *Ensures:* `distance(begin(), end()) == ranges::distance(rg)` is `true`.
 ``` cpp
 X(il)
 ```
 ```
 *Result:* `iterator`.
 *Preconditions:* `T` is *Cpp17EmplaceConstructible* into `X` from
+`args`. For `vector`, `inplace_vector`, and `deque`, `T` is also
+*Cpp17MoveInsertable* into `X` and *Cpp17MoveAssignable*.
 *Effects:* Inserts an object of type `T` constructed with
 `std::forward<Args>(args)...` before `p`.
 [*Note 1*: `args` can directly or indirectly refer to a value in
 `a`. — *end note*]
+*Returns:* An iterator that points to the new element.
 ``` cpp
 a.insert(p, t)
 ```
 *Result:* `iterator`.
+*Preconditions:* `T` is *Cpp17CopyInsertable* into `X`. For `vector`,
+`inplace_vector`, and `deque`, `T` is also *Cpp17CopyAssignable*.
 *Effects:* Inserts a copy of `t` before `p`.
 *Returns:* An iterator that points to the copy of `t` inserted into `a`.
 a.insert(p, rv)
 ```
 *Result:* `iterator`.
+*Preconditions:* `T` is *Cpp17MoveInsertable* into `X`. For `vector`,
+`inplace_vector`, and `deque`, `T` is also *Cpp17MoveAssignable*.
 *Effects:* Inserts a copy of `rv` before `p`.
 *Returns:* An iterator that points to the copy of `rv` inserted into
 `a`.
 ```
 *Result:* `iterator`.
 *Preconditions:* `T` is *Cpp17EmplaceConstructible* into `X` from `*i`.
+For `vector`, `inplace_vector`, and `deque`, `T` is also
+*Cpp17MoveInsertable* into `X`, and `T` meets the
+*Cpp17MoveConstructible*, *Cpp17MoveAssignable*, and
 *Cpp17Swappable*[[swappable.requirements]] requirements. Neither `i` nor
 `j` are iterators into `a`.
+*Effects:* Inserts copies of elements in \[`i`, `j`) before `p`. Each
 iterator in the range \[`i`, `j`) shall be dereferenced exactly once.
 *Returns:* An iterator that points to the copy of the first element
 inserted into `a`, or `p` if `i == j`.
 ```
 *Result:* `iterator`.
 *Preconditions:* `T` is *Cpp17EmplaceConstructible* into `X` from
+`*ranges::begin(rg)`. For `vector`, `inplace_vector`, and `deque`, `T`
+is also *Cpp17MoveInsertable* into `X`, and `T` meets the
 *Cpp17MoveConstructible*, *Cpp17MoveAssignable*, and
 *Cpp17Swappable*[[swappable.requirements]] requirements. `rg` and `a` do
 not overlap.
 *Effects:* Inserts copies of elements in `rg` before `p`. Each iterator
 a.erase(q)
 ```
 *Result:* `iterator`.
+*Preconditions:* For `vector`, `inplace_vector`, and `deque`, `T` is
+*Cpp17MoveAssignable*.
 *Effects:* Erases the element pointed to by `q`.
 *Returns:* An iterator that points to the element immediately following
 `q` prior to the element being erased. If no such element exists,
 a.erase(q1, q2)
 ```
 *Result:* `iterator`.
+*Preconditions:* For `vector`, `inplace_vector`, and `deque`, `T` is
+*Cpp17MoveAssignable*.
+*Effects:* Erases the elements in the range \[`q1`, `q2`).
 *Returns:* An iterator that points to the element pointed to by `q2`
 prior to any elements being erased. If no such element exists, `a.end()`
 is returned.
 and assignable from `*i`. For `vector`, if the iterator does not meet
 the forward iterator requirements [[forward.iterators]], `T` is also
 *Cpp17MoveInsertable* into `X`. Neither `i` nor `j` are iterators into
 `a`.
+*Effects:* Replaces elements in `a` with a copy of \[`i`, `j`).
+Invalidates all references, pointers and iterators referring to the
+elements of `a`. For `vector` and `deque`, also invalidates the
+past-the-end iterator. Each iterator in the range \[`i`, `j`) is
+dereferenced exactly once.
 ``` cpp
 a.assign_range(rg)
 ```
 *Mandates:* `assignable_from<T&, ranges::range_reference_t<R>>` is
 modeled.
 *Preconditions:* `T` is *Cpp17EmplaceConstructible* into `X` from
+`*ranges::begin(rg)`. For `vector`, if `R` models
+`ranges::approximately_sized_range` but not `ranges::sized_range` or
+models `ranges::input_range` but not `ranges::forward_range`, `T` is
+also *Cpp17MoveInsertable* into `X`. `rg` and `a` do not overlap.
 *Effects:* Replaces elements in `a` with a copy of each element in `rg`.
 Invalidates all references, pointers, and iterators referring to the
 elements of `a`. For `vector` and `deque`, also invalidates the
 past-the-end iterator. Each iterator in the range `rg` is dereferenced
 exactly once.
+*Recommended practice:* If `R` models
+`ranges::approximately_sized_range` and
+`ranges::distance(rg) <= ranges::reserve_hint(rg)` is `true`, an
+implementation should not perform any reallocation.
 ``` cpp
 a.assign(il)
 ```
 *Effects:* Equivalent to `a.assign(il.begin(), il.end())`.
 a.front()
 ```
 *Result:* `reference; const_reference` for constant `a`.
+`a.empty()` is `false`.
 *Returns:* `*a.begin()`
 *Remarks:* Required for `basic_string`, `array`, `deque`,
+`forward_list`, `inplace_vector`, `list`, and `vector`.
 ``` cpp
 a.back()
 ```
 *Result:* `reference; const_reference` for constant `a`.
+`a.empty()` is `false`.
 *Effects:* Equivalent to:
 ``` cpp
 auto tmp = a.end();
 --tmp;
 return *tmp;
 ```
+*Remarks:* Required for `basic_string`, `array`, `deque`,
+`inplace_vector`, `list`, and `vector`.
 ``` cpp
 a.emplace_front(args)
 ```
 *Effects:* Appends an object of type `T` constructed with
 `std::forward<Args>(args)...`.
 *Returns:* `a.back()`.
+*Remarks:* Required for `deque`, `inplace_vector`, `list`, and `vector`.
 ``` cpp
 a.push_front(t)
 ```
 *Preconditions:* `T` is *Cpp17CopyInsertable* into `X`.
 *Effects:* Appends a copy of `t`.
+*Remarks:* Required for `basic_string`, `deque`, `inplace_vector`,
+`list`, and `vector`.
 ``` cpp
 a.push_back(rv)
 ```
 *Preconditions:* `T` is *Cpp17MoveInsertable* into `X`.
 *Effects:* Appends a copy of `rv`.
+*Remarks:* Required for `basic_string`, `deque`, `inplace_vector`,
+`list`, and `vector`.
 ``` cpp
 a.append_range(rg)
 ```
 into `X`.
 *Effects:* Inserts copies of elements in `rg` before `end()`. Each
 iterator in the range `rg` is dereferenced exactly once.
+*Remarks:* Required for `deque`, `inplace_vector`, `list`, and `vector`.
 ``` cpp
 a.pop_front()
 ```
 *Result:* `void`
+`a.empty()` is `false`.
 *Effects:* Destroys the first element.
 *Remarks:* Required for `deque`, `forward_list`, and `list`.
 a.pop_back()
 ```
 *Result:* `void`
+`a.empty()` is `false`.
 *Effects:* Destroys the last element.
+*Remarks:* Required for `basic_string`, `deque`, `inplace_vector`,
+`list`, and `vector`.
 ``` cpp
 a[n]
 ```
+*Result:* `reference; const_reference` for constant `a`.
+`n < a.size()` is `true`.
+*Effects:* Equivalent to: `return *(a.begin() + n);`
+*Remarks:* Required for `basic_string`, `array`, `deque`,
+`inplace_vector`, and `vector`.
 ``` cpp
 a.at(n)
 ```
+*Result:* `reference; const_reference` for constant `a`.
 *Returns:* `*(a.begin() + n)`
 *Throws:* `out_of_range` if `n >= a.size()`.
+*Remarks:* Required for `basic_string`, `array`, `deque`,
+`inplace_vector`, and `vector`.

Diff to HTML by rtfpessoa