- tmp/tmpeknxjejv/{from.md → to.md} +204 -146
tmp/tmpeknxjejv/{from.md → to.md}
RENAMED
|
@@ -36,11 +36,11 @@ access iterators*, and *contiguous iterators*, as shown in
|
|
| 36 |
The six categories of iterators correspond to the iterator concepts
|
| 37 |
|
| 38 |
- `input_iterator` [[iterator.concept.input]],
|
| 39 |
- `output_iterator` [[iterator.concept.output]],
|
| 40 |
- `forward_iterator` [[iterator.concept.forward]],
|
| 41 |
-
- `bidirectional_iterator` [[iterator.concept.bidir]]
|
| 42 |
- `random_access_iterator` [[iterator.concept.random.access]], and
|
| 43 |
- `contiguous_iterator` [[iterator.concept.contiguous]],
|
| 44 |
|
| 45 |
respectively. The generic term *iterator* refers to any type that models
|
| 46 |
the `input_or_output_iterator` concept [[iterator.concept.iterator]].
|
|
@@ -71,22 +71,16 @@ value pointing past the last element of the array, so for any iterator
|
|
| 71 |
type there is an iterator value that points past the last element of a
|
| 72 |
corresponding sequence. Such a value is called a *past-the-end value*.
|
| 73 |
Values of an iterator `i` for which the expression `*i` is defined are
|
| 74 |
called *dereferenceable*. The library never assumes that past-the-end
|
| 75 |
values are dereferenceable. Iterators can also have singular values that
|
| 76 |
-
are not associated with any sequence.
|
| 77 |
-
|
| 78 |
-
|
| 79 |
-
|
| 80 |
-
|
| 81 |
-
|
| 82 |
-
Results of most expressions are undefined for singular values; the only
|
| 83 |
-
exceptions are destroying an iterator that holds a singular value, the
|
| 84 |
-
assignment of a non-singular value to an iterator that holds a singular
|
| 85 |
-
value, and, for iterators that meet the *Cpp17DefaultConstructible*
|
| 86 |
-
requirements, using a value-initialized iterator as the source of a copy
|
| 87 |
-
or move operation.
|
| 88 |
|
| 89 |
[*Note 2*: This guarantee is not offered for default-initialization,
|
| 90 |
although the distinction only matters for types with trivial default
|
| 91 |
constructors such as pointers or aggregates holding
|
| 92 |
pointers. — *end note*]
|
|
@@ -107,18 +101,18 @@ elements in the data structure starting with the element pointed to by
|
|
| 107 |
first iterator `j` such that `j == s`.
|
| 108 |
|
| 109 |
A sentinel `s` is called *reachable from* an iterator `i` if and only if
|
| 110 |
there is a finite sequence of applications of the expression `++i` that
|
| 111 |
makes `i == s`. If `s` is reachable from `i`, \[`i`, `s`) denotes a
|
| 112 |
-
valid range.
|
| 113 |
|
| 114 |
A *counted range* `i`+\[0, `n`) is empty if `n == 0`; otherwise,
|
| 115 |
`i`+\[0, `n`) refers to the `n` elements in the data structure starting
|
| 116 |
with the element pointed to by `i` and up to but not including the
|
| 117 |
element, if any, pointed to by the result of `n` applications of `++i`.
|
| 118 |
-
A counted range `i`+\[0, `n`) is valid if and only if `n == 0`; or `n`
|
| 119 |
-
is positive, `i` is dereferenceable, and `++i`+\[0, `
|
| 120 |
|
| 121 |
The result of the application of library functions to invalid ranges is
|
| 122 |
undefined.
|
| 123 |
|
| 124 |
All the categories of iterators require only those functions that are
|
|
@@ -214,10 +208,16 @@ template<class T>
|
|
| 214 |
requires is_object_v<T>
|
| 215 |
struct cond-value-type<T> {
|
| 216 |
using value_type = remove_cv_t<T>;
|
| 217 |
};
|
| 218 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 219 |
template<class> struct indirectly_readable_traits { };
|
| 220 |
|
| 221 |
template<class T>
|
| 222 |
struct indirectly_readable_traits<T*>
|
| 223 |
: cond-value-type<T> { };
|
|
@@ -230,20 +230,28 @@ struct indirectly_readable_traits<I> {
|
|
| 230 |
|
| 231 |
template<class I>
|
| 232 |
struct indirectly_readable_traits<const I>
|
| 233 |
: indirectly_readable_traits<I> { };
|
| 234 |
|
| 235 |
-
template<
|
| 236 |
-
requires requires { typename T::value_type; }
|
| 237 |
struct indirectly_readable_traits<T>
|
| 238 |
: cond-value-type<typename T::value_type> { };
|
| 239 |
|
| 240 |
-
template<
|
| 241 |
-
requires requires { typename T::element_type; }
|
| 242 |
struct indirectly_readable_traits<T>
|
| 243 |
: cond-value-type<typename T::element_type> { };
|
| 244 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 245 |
template<class T> using iter_value_t = see below;
|
| 246 |
```
|
| 247 |
|
| 248 |
Let R_`I` be `remove_cvref_t<I>`. The type `iter_value_t<I>` denotes
|
| 249 |
|
|
@@ -301,15 +309,15 @@ The definitions in this subclause make use of the following
|
|
| 301 |
exposition-only concepts:
|
| 302 |
|
| 303 |
``` cpp
|
| 304 |
template<class I>
|
| 305 |
concept cpp17-iterator =
|
| 306 |
-
|
| 307 |
{ *i } -> can-reference;
|
| 308 |
{ ++i } -> same_as<I&>;
|
| 309 |
{ *i++ } -> can-reference;
|
| 310 |
-
};
|
| 311 |
|
| 312 |
template<class I>
|
| 313 |
concept cpp17-input-iterator =
|
| 314 |
cpp17-iterator<I> && equality_comparable<I> && requires(I i) {
|
| 315 |
typename incrementable_traits<I>::difference_type;
|
|
@@ -322,11 +330,11 @@ concept cpp17-input-iterator =
|
|
| 322 |
};
|
| 323 |
|
| 324 |
template<class I>
|
| 325 |
concept cpp17-forward-iterator =
|
| 326 |
cpp17-input-iterator<I> && constructible_from<I> &&
|
| 327 |
-
|
| 328 |
same_as<remove_cvref_t<iter_reference_t<I>>,
|
| 329 |
typename indirectly_readable_traits<I>::value_type> &&
|
| 330 |
requires(I i) {
|
| 331 |
{ i++ } -> convertible_to<const I&>;
|
| 332 |
{ *i++ } -> same_as<iter_reference_t<I>>;
|
|
@@ -418,10 +426,16 @@ The members of a specialization `iterator_traits<I>` generated from the
|
|
| 418 |
|
| 419 |
Explicit or partial specializations of `iterator_traits` may have a
|
| 420 |
member type `iterator_concept` that is used to indicate conformance to
|
| 421 |
the iterator concepts [[iterator.concepts]].
|
| 422 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 423 |
`iterator_traits` is specialized for pointers as
|
| 424 |
|
| 425 |
``` cpp
|
| 426 |
namespace std {
|
| 427 |
template<class T>
|
|
@@ -435,11 +449,11 @@ namespace std {
|
|
| 435 |
using reference = T&;
|
| 436 |
};
|
| 437 |
}
|
| 438 |
```
|
| 439 |
|
| 440 |
-
[*Example
|
| 441 |
|
| 442 |
To implement a generic `reverse` function, a C++ program can do the
|
| 443 |
following:
|
| 444 |
|
| 445 |
``` cpp
|
|
@@ -458,26 +472,23 @@ void reverse(BI first, BI last) {
|
|
| 458 |
}
|
| 459 |
```
|
| 460 |
|
| 461 |
— *end example*]
|
| 462 |
|
| 463 |
-
### Customization
|
| 464 |
|
| 465 |
#### `ranges::iter_move` <a id="iterator.cust.move">[[iterator.cust.move]]</a>
|
| 466 |
|
| 467 |
The name `ranges::iter_move` denotes a customization point object
|
| 468 |
[[customization.point.object]]. The expression `ranges::iter_move(E)`
|
| 469 |
for a subexpression `E` is expression-equivalent to:
|
| 470 |
|
| 471 |
- `iter_move(E)`, if `E` has class or enumeration type and
|
| 472 |
`iter_move(E)` is a well-formed expression when treated as an
|
| 473 |
-
unevaluated operand,
|
| 474 |
-
|
| 475 |
-
|
| 476 |
-
``` cpp
|
| 477 |
-
void iter_move();
|
| 478 |
-
```
|
| 479 |
- Otherwise, if the expression `*E` is well-formed:
|
| 480 |
- if `*E` is an lvalue, `std::move(*E)`;
|
| 481 |
- otherwise, `*E`.
|
| 482 |
- Otherwise, `ranges::iter_move(E)` is ill-formed. \[*Note 1*: This case
|
| 483 |
can result in substitution failure when `ranges::iter_move(E)` appears
|
|
@@ -523,20 +534,23 @@ The expression `ranges::iter_swap(E1, E2)` for subexpressions `E1` and
|
|
| 523 |
|
| 524 |
and does not include a declaration of `ranges::iter_swap`. If the
|
| 525 |
function selected by overload resolution does not exchange the values
|
| 526 |
denoted by `E1` and `E2`, the program is ill-formed, no diagnostic
|
| 527 |
required.
|
|
|
|
|
|
|
|
|
|
| 528 |
- Otherwise, if the types of `E1` and `E2` each model
|
| 529 |
`indirectly_readable`, and if the reference types of `E1` and `E2`
|
| 530 |
model `swappable_with` [[concept.swappable]], then
|
| 531 |
`ranges::swap(*E1, *E2)`.
|
| 532 |
- Otherwise, if the types `T1` and `T2` of `E1` and `E2` model
|
| 533 |
`indirectly_movable_storable<T1, T2>` and
|
| 534 |
`indirectly_movable_storable<T2, T1>`, then
|
| 535 |
`(void)(*E1 = iter-exchange-move(E2, E1))`, except that `E1` is
|
| 536 |
evaluated only once.
|
| 537 |
-
- Otherwise, `ranges::iter_swap(E1, E2)` is ill-formed. \[*Note
|
| 538 |
case can result in substitution failure when
|
| 539 |
`ranges::iter_swap(E1, E2)` appears in the immediate context of a
|
| 540 |
template instantiation. — *end note*]
|
| 541 |
|
| 542 |
### Iterator concepts <a id="iterator.concepts">[[iterator.concepts]]</a>
|
|
@@ -571,11 +585,10 @@ struct I {
|
|
| 571 |
I operator++(int);
|
| 572 |
I& operator--();
|
| 573 |
I operator--(int);
|
| 574 |
|
| 575 |
bool operator==(I) const;
|
| 576 |
-
bool operator!=(I) const;
|
| 577 |
};
|
| 578 |
```
|
| 579 |
|
| 580 |
`iterator_traits<I>::iterator_category` denotes `input_iterator_tag`,
|
| 581 |
and `ITER_CONCEPT(I)` denotes `random_access_iterator_tag`.
|
|
@@ -610,14 +623,10 @@ template<class In>
|
|
| 610 |
```
|
| 611 |
|
| 612 |
Given a value `i` of type `I`, `I` models `indirectly_readable` only if
|
| 613 |
the expression `*i` is equality-preserving.
|
| 614 |
|
| 615 |
-
[*Note 1*: The expression `*i` is indirectly required to be valid via
|
| 616 |
-
the exposition-only `dereferenceable` concept
|
| 617 |
-
[[iterator.synopsis]]. — *end note*]
|
| 618 |
-
|
| 619 |
#### Concept <a id="iterator.concept.writable">[[iterator.concept.writable]]</a>
|
| 620 |
|
| 621 |
The `indirectly_writable` concept specifies the requirements for writing
|
| 622 |
a value into an iterator’s referenced object.
|
| 623 |
|
|
@@ -637,11 +646,11 @@ template<class Out, class T>
|
|
| 637 |
Let `E` be an expression such that `decltype((E))` is `T`, and let `o`
|
| 638 |
be a dereferenceable object of type `Out`. `Out` and `T` model
|
| 639 |
`indirectly_writable<Out, T>` only if
|
| 640 |
|
| 641 |
- If `Out` and `T` model
|
| 642 |
-
`indirectly_readable<Out> && same_as<iter_value_t<Out>, decay_t<T>
|
| 643 |
then `*o` after any above assignment is equal to the value of `E`
|
| 644 |
before the assignment.
|
| 645 |
|
| 646 |
After evaluating any above assignment expression, `o` is not required to
|
| 647 |
be dereferenceable.
|
|
@@ -667,99 +676,126 @@ that can be incremented with the pre- and post-increment operators. The
|
|
| 667 |
increment operations are not required to be equality-preserving, nor is
|
| 668 |
the type required to be `equality_comparable`.
|
| 669 |
|
| 670 |
``` cpp
|
| 671 |
template<class T>
|
| 672 |
-
|
| 673 |
|
| 674 |
template<class T>
|
| 675 |
-
|
| 676 |
|
| 677 |
template<class I>
|
| 678 |
concept weakly_incrementable =
|
| 679 |
-
|
| 680 |
requires(I i) {
|
| 681 |
typename iter_difference_t<I>;
|
| 682 |
requires is-signed-integer-like<iter_difference_t<I>>;
|
| 683 |
{ ++i } -> same_as<I&>; // not required to be equality-preserving
|
| 684 |
i++; // not required to be equality-preserving
|
| 685 |
};
|
| 686 |
```
|
| 687 |
|
| 688 |
A type `I` is an *integer-class type* if it is in a set of
|
| 689 |
-
implementation-defined
|
| 690 |
-
defined
|
|
|
|
|
|
|
|
|
|
| 691 |
|
| 692 |
The range of representable values of an integer-class type is the
|
| 693 |
-
continuous set of values over which it is defined.
|
| 694 |
-
|
| 695 |
-
|
| 696 |
-
*signed-integer-class type*
|
| 697 |
-
*unsigned-integer-class type*.
|
|
|
|
|
|
|
|
|
|
| 698 |
|
| 699 |
-
|
| 700 |
-
|
| 701 |
-
|
| 702 |
-
|
|
|
|
|
|
|
| 703 |
|
| 704 |
-
|
| 705 |
-
|
| 706 |
-
as `
|
| 707 |
-
type.
|
| 708 |
|
| 709 |
-
|
| 710 |
-
|
| 711 |
-
|
| 712 |
-
|
| 713 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 714 |
- For every assignment operator `@=` for which `c @= x` is well-formed,
|
| 715 |
`c @= a` shall also be well-formed and shall have the same value and
|
| 716 |
effects as `c @= x`. The expression `c @= a` shall be an lvalue
|
| 717 |
referring to `c`.
|
| 718 |
-
- For every
|
| 719 |
-
`a @ b` shall also be well-formed and shall have the same
|
| 720 |
-
|
| 721 |
-
|
| 722 |
-
|
| 723 |
-
|
| 724 |
-
|
| 725 |
-
|
| 726 |
-
|
| 727 |
-
|
|
|
|
|
|
|
|
|
|
| 728 |
|
| 729 |
An expression `E` of integer-class type `I` is contextually convertible
|
| 730 |
to `bool` as if by `bool(E != I(0))`.
|
| 731 |
|
| 732 |
All integer-class types model `regular` [[concepts.object]] and
|
| 733 |
-
`
|
| 734 |
|
| 735 |
A value-initialized object of integer-class type has value 0.
|
| 736 |
|
| 737 |
For every (possibly cv-qualified) integer-class type `I`,
|
| 738 |
-
`numeric_limits<I>` is specialized such that
|
|
|
|
|
|
|
| 739 |
|
| 740 |
-
- `
|
| 741 |
-
- `
|
| 742 |
-
|
| 743 |
-
- `
|
| 744 |
-
-
|
| 745 |
-
- `numeric_limits<I>::digits` is equal to the width of the integer-class
|
| 746 |
-
type,
|
| 747 |
-
- `numeric_limits<I>::digits10` is equal to
|
| 748 |
-
`static_cast<int>(digits * log10(2))`, and
|
| 749 |
-
- `numeric_limits<I>::min()` and `numeric_limits<I>::max()` return the
|
| 750 |
-
lowest and highest representable values of `I`, respectively, and
|
| 751 |
-
`numeric_limits<I>::lowest()` returns `numeric_limits<I>::{}min()`.
|
| 752 |
-
|
| 753 |
-
A type `I` is *integer-like* if it models `integral<I>` or if it is an
|
| 754 |
-
integer-class type. A type `I` is *signed-integer-like* if it models
|
| 755 |
-
`signed_integral<I>` or if it is a signed-integer-class type. A type `I`
|
| 756 |
-
is *unsigned-integer-like* if it models `unsigned_integral<I>` or if it
|
| 757 |
-
is an unsigned-integer-class type.
|
| 758 |
|
| 759 |
`is-integer-like<I>` is `true` if and only if `I` is an integer-like
|
| 760 |
-
type. `is-signed-integer-like<I>` is `true` if and only if I is a
|
| 761 |
signed-integer-like type.
|
| 762 |
|
| 763 |
Let `i` be an object of type `I`. When `i` is in the domain of both pre-
|
| 764 |
and post-increment, `i` is said to be *incrementable*. `I` models
|
| 765 |
`weakly_incrementable<I>` only if
|
|
@@ -768,17 +804,20 @@ and post-increment, `i` is said to be *incrementable*. `I` models
|
|
| 768 |
- If `i` is incrementable, then both `++i` and `i++` advance `i` to the
|
| 769 |
next element.
|
| 770 |
- If `i` is incrementable, then `addressof(++i)` is equal to
|
| 771 |
`addressof(i)`.
|
| 772 |
|
| 773 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 774 |
imply that `++a` equals `++b`. (Equality does not guarantee the
|
| 775 |
-
substitution property or referential transparency.)
|
| 776 |
-
|
| 777 |
-
|
| 778 |
-
algorithms can be used with istreams as the source of the input data
|
| 779 |
-
through the `istream_iterator` class template. — *end note*]
|
| 780 |
|
| 781 |
#### Concept <a id="iterator.concept.inc">[[iterator.concept.inc]]</a>
|
| 782 |
|
| 783 |
The `incrementable` concept specifies requirements on types that can be
|
| 784 |
incremented with the pre- and post-increment operators. The increment
|
|
@@ -815,13 +854,12 @@ The `input_or_output_iterator` concept forms the basis of the iterator
|
|
| 815 |
concept taxonomy; every iterator models `input_or_output_iterator`. This
|
| 816 |
concept specifies operations for dereferencing and incrementing an
|
| 817 |
iterator. Most algorithms will require additional operations to compare
|
| 818 |
iterators with sentinels [[iterator.concept.sentinel]], to read
|
| 819 |
[[iterator.concept.input]] or write [[iterator.concept.output]] values,
|
| 820 |
-
or to provide a richer set of iterator movements
|
| 821 |
-
[[iterator.concept.forward]], [[iterator.concept.bidir]],
|
| 822 |
-
[[iterator.concept.random.access]]).
|
| 823 |
|
| 824 |
``` cpp
|
| 825 |
template<class I>
|
| 826 |
concept input_or_output_iterator =
|
| 827 |
requires(I i) {
|
|
@@ -843,19 +881,20 @@ denote a range.
|
|
| 843 |
``` cpp
|
| 844 |
template<class S, class I>
|
| 845 |
concept sentinel_for =
|
| 846 |
semiregular<S> &&
|
| 847 |
input_or_output_iterator<I> &&
|
| 848 |
-
weakly-equality-comparable-with<S, I>;
|
| 849 |
```
|
| 850 |
|
| 851 |
Let `s` and `i` be values of type `S` and `I` such that \[`i`, `s`)
|
| 852 |
denotes a range. Types `S` and `I` model `sentinel_for<S, I>` only if
|
| 853 |
|
| 854 |
- `i == s` is well-defined.
|
| 855 |
- If `bool(i != s)` then `i` is dereferenceable and \[`++i`, `s`)
|
| 856 |
denotes a range.
|
|
|
|
| 857 |
|
| 858 |
The domain of `==` is not static. Given an iterator `i` and sentinel `s`
|
| 859 |
such that \[`i`, `s`) denotes a range and `i != s`, `i` and `s` are not
|
| 860 |
required to continue to denote a range after incrementing any other
|
| 861 |
iterator equal to `i`. Consequently, `i == s` is no longer required to
|
|
@@ -889,11 +928,11 @@ and `I` model `sized_sentinel_for<S, I>` only if
|
|
| 889 |
- If -N is representable by `iter_difference_t<I>`, then `i - s` is
|
| 890 |
well-defined and equals -N.
|
| 891 |
|
| 892 |
``` cpp
|
| 893 |
template<class S, class I>
|
| 894 |
-
|
| 895 |
```
|
| 896 |
|
| 897 |
*Remarks:* Pursuant to [[namespace.std]], users may specialize
|
| 898 |
`disable_sized_sentinel_for` for cv-unqualified non-array object types
|
| 899 |
`S` and `I` if `S` and/or `I` is a program-defined type. Such
|
|
@@ -957,13 +996,13 @@ be a dereferenceable object of type `I`. `I` and `T` model
|
|
| 957 |
``` cpp
|
| 958 |
*i = E;
|
| 959 |
++i;
|
| 960 |
```
|
| 961 |
|
| 962 |
-
|
| 963 |
-
through the same iterator twice
|
| 964 |
-
|
| 965 |
|
| 966 |
#### Concept <a id="iterator.concept.forward">[[iterator.concept.forward]]</a>
|
| 967 |
|
| 968 |
The `forward_iterator` concept adds copyability, equality comparison,
|
| 969 |
and the multi-pass guarantee, specified below.
|
|
@@ -991,11 +1030,11 @@ range.
|
|
| 991 |
|
| 992 |
Two dereferenceable iterators `a` and `b` of type `X` offer the
|
| 993 |
*multi-pass guarantee* if:
|
| 994 |
|
| 995 |
- `a == b` implies `++a == ++b` and
|
| 996 |
-
-
|
| 997 |
expression `*a`.
|
| 998 |
|
| 999 |
[*Note 2*: The requirement that `a == b` implies `++a == ++b` and the
|
| 1000 |
removal of the restrictions on the number of assignments through a
|
| 1001 |
mutable iterator (which applies to output iterators) allow the use of
|
|
@@ -1101,15 +1140,21 @@ non-dereferenceable iterator of type `I` such that `b` is reachable from
|
|
| 1101 |
`a` and `c` is reachable from `b`, and let `D` be
|
| 1102 |
`iter_difference_t<I>`. The type `I` models `contiguous_iterator` only
|
| 1103 |
if
|
| 1104 |
|
| 1105 |
- `to_address(a) == addressof(*a)`,
|
| 1106 |
-
- `to_address(b) == to_address(a) + D(b - a)`,
|
| 1107 |
-
- `to_address(c) == to_address(a) + D(c - a)`
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1108 |
|
| 1109 |
### C++17 iterator requirements <a id="iterator.cpp17">[[iterator.cpp17]]</a>
|
| 1110 |
|
|
|
|
|
|
|
| 1111 |
In the following sections, `a` and `b` denote values of type `X` or
|
| 1112 |
`const X`, `difference_type` and `reference` refer to the types
|
| 1113 |
`iterator_traits<X>::difference_type` and
|
| 1114 |
`iterator_traits<X>::reference`, respectively, `n` denotes a value of
|
| 1115 |
`difference_type`, `u`, `tmp`, and `m` denote identifiers, `r` denotes a
|
|
@@ -1124,19 +1169,18 @@ value of some type that is writable to the output iterator.
|
|
| 1124 |
The *Cpp17Iterator* requirements form the basis of the iterator
|
| 1125 |
taxonomy; every iterator meets the *Cpp17Iterator* requirements. This
|
| 1126 |
set of requirements specifies operations for dereferencing and
|
| 1127 |
incrementing an iterator. Most algorithms will require additional
|
| 1128 |
operations to read [[input.iterators]] or write [[output.iterators]]
|
| 1129 |
-
values, or to provide a richer set of iterator movements
|
| 1130 |
-
[[forward.iterators]], [[bidirectional.iterators]],
|
| 1131 |
-
[[random.access.iterators]]).
|
| 1132 |
|
| 1133 |
-
A type `X` meets the
|
| 1134 |
|
| 1135 |
-
- `X` meets the *Cpp17CopyConstructible*, *Cpp17CopyAssignable*,
|
| 1136 |
-
*
|
| 1137 |
-
|
| 1138 |
- `iterator_traits<X>::difference_type` is a signed integer type or
|
| 1139 |
`void`, and
|
| 1140 |
- the expressions in [[iterator]] are valid and have the indicated
|
| 1141 |
semantics.
|
| 1142 |
|
|
@@ -1158,31 +1202,35 @@ uses that algorithm makes of `==` and `!=`.
|
|
| 1158 |
[*Example 1*: The call `find(a,b,x)` is defined only if the value of
|
| 1159 |
`a` has the property *p* defined as follows: `b` has property *p* and a
|
| 1160 |
value `i` has property *p* if (`*i==x`) or if (`*i!=x` and `++i` has
|
| 1161 |
property *p*). — *end example*]
|
| 1162 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1163 |
[*Note 1*: For input iterators, `a == b` does not imply `++a == ++b`.
|
| 1164 |
(Equality does not guarantee the substitution property or referential
|
| 1165 |
-
transparency.)
|
| 1166 |
-
|
| 1167 |
-
|
| 1168 |
-
|
| 1169 |
-
istreams as the source of the input data through the `istream_iterator`
|
| 1170 |
-
class template. — *end note*]
|
| 1171 |
|
| 1172 |
#### Output iterators <a id="output.iterators">[[output.iterators]]</a>
|
| 1173 |
|
| 1174 |
A class or pointer type `X` meets the requirements of an output iterator
|
| 1175 |
if `X` meets the *Cpp17Iterator* requirements [[iterator.iterators]] and
|
| 1176 |
the expressions in [[outputiterator]] are valid and have the indicated
|
| 1177 |
semantics.
|
| 1178 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1179 |
[*Note 1*: The only valid use of an `operator*` is on the left side of
|
| 1180 |
the assignment statement. Assignment through the same value of the
|
| 1181 |
-
iterator happens only once.
|
| 1182 |
-
attempt to pass through the same iterator twice. They should be
|
| 1183 |
-
single-pass algorithms. Equality and inequality might not be
|
| 1184 |
defined. — *end note*]
|
| 1185 |
|
| 1186 |
#### Forward iterators <a id="forward.iterators">[[forward.iterators]]</a>
|
| 1187 |
|
| 1188 |
A class or pointer type `X` meets the requirements of a forward iterator
|
|
@@ -1244,85 +1292,95 @@ requirements, the following expressions are valid as shown in
|
|
| 1244 |
### Indirect callable requirements <a id="indirectcallable">[[indirectcallable]]</a>
|
| 1245 |
|
| 1246 |
#### General <a id="indirectcallable.general">[[indirectcallable.general]]</a>
|
| 1247 |
|
| 1248 |
There are several concepts that group requirements of algorithms that
|
| 1249 |
-
take callable objects
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1250 |
|
| 1251 |
#### Indirect callables <a id="indirectcallable.indirectinvocable">[[indirectcallable.indirectinvocable]]</a>
|
| 1252 |
|
| 1253 |
The indirect callable concepts are used to constrain those algorithms
|
| 1254 |
-
that accept callable objects
|
| 1255 |
|
| 1256 |
``` cpp
|
| 1257 |
namespace std {
|
| 1258 |
template<class F, class I>
|
| 1259 |
concept indirectly_unary_invocable =
|
| 1260 |
indirectly_readable<I> &&
|
| 1261 |
copy_constructible<F> &&
|
| 1262 |
-
invocable<F&,
|
| 1263 |
invocable<F&, iter_reference_t<I>> &&
|
| 1264 |
invocable<F&, iter_common_reference_t<I>> &&
|
| 1265 |
common_reference_with<
|
| 1266 |
-
invoke_result_t<F&,
|
| 1267 |
invoke_result_t<F&, iter_reference_t<I>>>;
|
| 1268 |
|
| 1269 |
template<class F, class I>
|
| 1270 |
concept indirectly_regular_unary_invocable =
|
| 1271 |
indirectly_readable<I> &&
|
| 1272 |
copy_constructible<F> &&
|
| 1273 |
-
regular_invocable<F&,
|
| 1274 |
regular_invocable<F&, iter_reference_t<I>> &&
|
| 1275 |
regular_invocable<F&, iter_common_reference_t<I>> &&
|
| 1276 |
common_reference_with<
|
| 1277 |
-
invoke_result_t<F&,
|
| 1278 |
invoke_result_t<F&, iter_reference_t<I>>>;
|
| 1279 |
|
| 1280 |
template<class F, class I>
|
| 1281 |
concept indirect_unary_predicate =
|
| 1282 |
indirectly_readable<I> &&
|
| 1283 |
copy_constructible<F> &&
|
| 1284 |
-
predicate<F&,
|
| 1285 |
predicate<F&, iter_reference_t<I>> &&
|
| 1286 |
predicate<F&, iter_common_reference_t<I>>;
|
| 1287 |
|
| 1288 |
template<class F, class I1, class I2>
|
| 1289 |
concept indirect_binary_predicate =
|
| 1290 |
indirectly_readable<I1> && indirectly_readable<I2> &&
|
| 1291 |
copy_constructible<F> &&
|
| 1292 |
-
predicate<F&,
|
| 1293 |
-
predicate<F&,
|
| 1294 |
-
predicate<F&, iter_reference_t<I1>,
|
| 1295 |
predicate<F&, iter_reference_t<I1>, iter_reference_t<I2>> &&
|
| 1296 |
predicate<F&, iter_common_reference_t<I1>, iter_common_reference_t<I2>>;
|
| 1297 |
|
| 1298 |
template<class F, class I1, class I2 = I1>
|
| 1299 |
concept indirect_equivalence_relation =
|
| 1300 |
indirectly_readable<I1> && indirectly_readable<I2> &&
|
| 1301 |
copy_constructible<F> &&
|
| 1302 |
-
equivalence_relation<F&,
|
| 1303 |
-
equivalence_relation<F&,
|
| 1304 |
-
equivalence_relation<F&, iter_reference_t<I1>,
|
| 1305 |
equivalence_relation<F&, iter_reference_t<I1>, iter_reference_t<I2>> &&
|
| 1306 |
equivalence_relation<F&, iter_common_reference_t<I1>, iter_common_reference_t<I2>>;
|
| 1307 |
|
| 1308 |
template<class F, class I1, class I2 = I1>
|
| 1309 |
concept indirect_strict_weak_order =
|
| 1310 |
indirectly_readable<I1> && indirectly_readable<I2> &&
|
| 1311 |
copy_constructible<F> &&
|
| 1312 |
-
strict_weak_order<F&,
|
| 1313 |
-
strict_weak_order<F&,
|
| 1314 |
-
strict_weak_order<F&, iter_reference_t<I1>,
|
| 1315 |
strict_weak_order<F&, iter_reference_t<I1>, iter_reference_t<I2>> &&
|
| 1316 |
strict_weak_order<F&, iter_common_reference_t<I1>, iter_common_reference_t<I2>>;
|
| 1317 |
}
|
| 1318 |
```
|
| 1319 |
|
| 1320 |
#### Class template `projected` <a id="projected">[[projected]]</a>
|
| 1321 |
|
| 1322 |
Class template `projected` is used to constrain algorithms that accept
|
| 1323 |
-
callable objects and projections [[defns.projection]]. It combines
|
| 1324 |
`indirectly_readable` type `I` and a callable object type `Proj` into a
|
| 1325 |
new `indirectly_readable` type whose `reference` type is the result of
|
| 1326 |
applying `Proj` to the `iter_reference_t` of `I`.
|
| 1327 |
|
| 1328 |
``` cpp
|
|
@@ -1358,12 +1416,12 @@ different sequences: `indirectly_comparable`.
|
|
| 1358 |
below imposes constraints on the concepts’ arguments in addition to
|
| 1359 |
those that appear in the concepts’ bodies [[range.cmp]]. — *end note*]
|
| 1360 |
|
| 1361 |
#### Concept <a id="alg.req.ind.move">[[alg.req.ind.move]]</a>
|
| 1362 |
|
| 1363 |
-
The `indirectly_movable` concept specifies the relationship between
|
| 1364 |
-
`indirectly_readable` type and
|
| 1365 |
which values may be moved.
|
| 1366 |
|
| 1367 |
``` cpp
|
| 1368 |
template<class In, class Out>
|
| 1369 |
concept indirectly_movable =
|
|
@@ -1399,12 +1457,12 @@ iter_value_t<In> obj(ranges::iter_move(i));
|
|
| 1399 |
state of the value denoted by `*i` is valid but unspecified
|
| 1400 |
[[lib.types.movedfrom]].
|
| 1401 |
|
| 1402 |
#### Concept <a id="alg.req.ind.copy">[[alg.req.ind.copy]]</a>
|
| 1403 |
|
| 1404 |
-
The `indirectly_copyable` concept specifies the relationship between
|
| 1405 |
-
`indirectly_readable` type and
|
| 1406 |
which values may be copied.
|
| 1407 |
|
| 1408 |
``` cpp
|
| 1409 |
template<class In, class Out>
|
| 1410 |
concept indirectly_copyable =
|
|
|
|
| 36 |
The six categories of iterators correspond to the iterator concepts
|
| 37 |
|
| 38 |
- `input_iterator` [[iterator.concept.input]],
|
| 39 |
- `output_iterator` [[iterator.concept.output]],
|
| 40 |
- `forward_iterator` [[iterator.concept.forward]],
|
| 41 |
+
- `bidirectional_iterator` [[iterator.concept.bidir]],
|
| 42 |
- `random_access_iterator` [[iterator.concept.random.access]], and
|
| 43 |
- `contiguous_iterator` [[iterator.concept.contiguous]],
|
| 44 |
|
| 45 |
respectively. The generic term *iterator* refers to any type that models
|
| 46 |
the `input_or_output_iterator` concept [[iterator.concept.iterator]].
|
|
|
|
| 71 |
type there is an iterator value that points past the last element of a
|
| 72 |
corresponding sequence. Such a value is called a *past-the-end value*.
|
| 73 |
Values of an iterator `i` for which the expression `*i` is defined are
|
| 74 |
called *dereferenceable*. The library never assumes that past-the-end
|
| 75 |
values are dereferenceable. Iterators can also have singular values that
|
| 76 |
+
are not associated with any sequence. Results of most expressions are
|
| 77 |
+
undefined for singular values; the only exceptions are destroying an
|
| 78 |
+
iterator that holds a singular value, the assignment of a non-singular
|
| 79 |
+
value to an iterator that holds a singular value, and, for iterators
|
| 80 |
+
that meet the *Cpp17DefaultConstructible* requirements, using a
|
| 81 |
+
value-initialized iterator as the source of a copy or move operation.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 82 |
|
| 83 |
[*Note 2*: This guarantee is not offered for default-initialization,
|
| 84 |
although the distinction only matters for types with trivial default
|
| 85 |
constructors such as pointers or aggregates holding
|
| 86 |
pointers. — *end note*]
|
|
|
|
| 101 |
first iterator `j` such that `j == s`.
|
| 102 |
|
| 103 |
A sentinel `s` is called *reachable from* an iterator `i` if and only if
|
| 104 |
there is a finite sequence of applications of the expression `++i` that
|
| 105 |
makes `i == s`. If `s` is reachable from `i`, \[`i`, `s`) denotes a
|
| 106 |
+
*valid range*.
|
| 107 |
|
| 108 |
A *counted range* `i`+\[0, `n`) is empty if `n == 0`; otherwise,
|
| 109 |
`i`+\[0, `n`) refers to the `n` elements in the data structure starting
|
| 110 |
with the element pointed to by `i` and up to but not including the
|
| 111 |
element, if any, pointed to by the result of `n` applications of `++i`.
|
| 112 |
+
A counted range `i`+\[0, `n`) is *valid* if and only if `n == 0`; or `n`
|
| 113 |
+
is positive, `i` is dereferenceable, and `++i`+\[0, `–n`) is valid.
|
| 114 |
|
| 115 |
The result of the application of library functions to invalid ranges is
|
| 116 |
undefined.
|
| 117 |
|
| 118 |
All the categories of iterators require only those functions that are
|
|
|
|
| 208 |
requires is_object_v<T>
|
| 209 |
struct cond-value-type<T> {
|
| 210 |
using value_type = remove_cv_t<T>;
|
| 211 |
};
|
| 212 |
|
| 213 |
+
template<class T>
|
| 214 |
+
concept has-member-value-type = requires { typename T::value_type; }; // exposition only
|
| 215 |
+
|
| 216 |
+
template<class T>
|
| 217 |
+
concept has-member-element-type = requires { typename T::element_type; }; // exposition only
|
| 218 |
+
|
| 219 |
template<class> struct indirectly_readable_traits { };
|
| 220 |
|
| 221 |
template<class T>
|
| 222 |
struct indirectly_readable_traits<T*>
|
| 223 |
: cond-value-type<T> { };
|
|
|
|
| 230 |
|
| 231 |
template<class I>
|
| 232 |
struct indirectly_readable_traits<const I>
|
| 233 |
: indirectly_readable_traits<I> { };
|
| 234 |
|
| 235 |
+
template<has-member-value-type T>
|
|
|
|
| 236 |
struct indirectly_readable_traits<T>
|
| 237 |
: cond-value-type<typename T::value_type> { };
|
| 238 |
|
| 239 |
+
template<has-member-element-type T>
|
|
|
|
| 240 |
struct indirectly_readable_traits<T>
|
| 241 |
: cond-value-type<typename T::element_type> { };
|
| 242 |
|
| 243 |
+
template<has-member-value-type T>
|
| 244 |
+
requires has-member-element-type<T>
|
| 245 |
+
struct indirectly_readable_traits<T> { };
|
| 246 |
+
|
| 247 |
+
template<has-member-value-type T>
|
| 248 |
+
requires has-member-element-type<T> &&
|
| 249 |
+
same_as<remove_cv_t<typename T::element_type>, remove_cv_t<typename T::value_type>>
|
| 250 |
+
struct indirectly_readable_traits<T>
|
| 251 |
+
: cond-value-type<typename T::value_type> { };
|
| 252 |
+
|
| 253 |
template<class T> using iter_value_t = see below;
|
| 254 |
```
|
| 255 |
|
| 256 |
Let R_`I` be `remove_cvref_t<I>`. The type `iter_value_t<I>` denotes
|
| 257 |
|
|
|
|
| 309 |
exposition-only concepts:
|
| 310 |
|
| 311 |
``` cpp
|
| 312 |
template<class I>
|
| 313 |
concept cpp17-iterator =
|
| 314 |
+
requires(I i) {
|
| 315 |
{ *i } -> can-reference;
|
| 316 |
{ ++i } -> same_as<I&>;
|
| 317 |
{ *i++ } -> can-reference;
|
| 318 |
+
} && copyable<I>;
|
| 319 |
|
| 320 |
template<class I>
|
| 321 |
concept cpp17-input-iterator =
|
| 322 |
cpp17-iterator<I> && equality_comparable<I> && requires(I i) {
|
| 323 |
typename incrementable_traits<I>::difference_type;
|
|
|
|
| 330 |
};
|
| 331 |
|
| 332 |
template<class I>
|
| 333 |
concept cpp17-forward-iterator =
|
| 334 |
cpp17-input-iterator<I> && constructible_from<I> &&
|
| 335 |
+
is_reference_v<iter_reference_t<I>> &&
|
| 336 |
same_as<remove_cvref_t<iter_reference_t<I>>,
|
| 337 |
typename indirectly_readable_traits<I>::value_type> &&
|
| 338 |
requires(I i) {
|
| 339 |
{ i++ } -> convertible_to<const I&>;
|
| 340 |
{ *i++ } -> same_as<iter_reference_t<I>>;
|
|
|
|
| 426 |
|
| 427 |
Explicit or partial specializations of `iterator_traits` may have a
|
| 428 |
member type `iterator_concept` that is used to indicate conformance to
|
| 429 |
the iterator concepts [[iterator.concepts]].
|
| 430 |
|
| 431 |
+
[*Example 1*: To indicate conformance to the `input_iterator` concept
|
| 432 |
+
but a lack of conformance to the *Cpp17InputIterator* requirements
|
| 433 |
+
[[input.iterators]], an `iterator_traits` specialization might have
|
| 434 |
+
`iterator_concept` denote `input_iterator_tag` but not define
|
| 435 |
+
`iterator_category`. — *end example*]
|
| 436 |
+
|
| 437 |
`iterator_traits` is specialized for pointers as
|
| 438 |
|
| 439 |
``` cpp
|
| 440 |
namespace std {
|
| 441 |
template<class T>
|
|
|
|
| 449 |
using reference = T&;
|
| 450 |
};
|
| 451 |
}
|
| 452 |
```
|
| 453 |
|
| 454 |
+
[*Example 2*:
|
| 455 |
|
| 456 |
To implement a generic `reverse` function, a C++ program can do the
|
| 457 |
following:
|
| 458 |
|
| 459 |
``` cpp
|
|
|
|
| 472 |
}
|
| 473 |
```
|
| 474 |
|
| 475 |
— *end example*]
|
| 476 |
|
| 477 |
+
### Customization point objects <a id="iterator.cust">[[iterator.cust]]</a>
|
| 478 |
|
| 479 |
#### `ranges::iter_move` <a id="iterator.cust.move">[[iterator.cust.move]]</a>
|
| 480 |
|
| 481 |
The name `ranges::iter_move` denotes a customization point object
|
| 482 |
[[customization.point.object]]. The expression `ranges::iter_move(E)`
|
| 483 |
for a subexpression `E` is expression-equivalent to:
|
| 484 |
|
| 485 |
- `iter_move(E)`, if `E` has class or enumeration type and
|
| 486 |
`iter_move(E)` is a well-formed expression when treated as an
|
| 487 |
+
unevaluated operand, where the meaning of `iter_move` is established
|
| 488 |
+
as-if by performing argument-dependent lookup only
|
| 489 |
+
[[basic.lookup.argdep]].
|
|
|
|
|
|
|
|
|
|
| 490 |
- Otherwise, if the expression `*E` is well-formed:
|
| 491 |
- if `*E` is an lvalue, `std::move(*E)`;
|
| 492 |
- otherwise, `*E`.
|
| 493 |
- Otherwise, `ranges::iter_move(E)` is ill-formed. \[*Note 1*: This case
|
| 494 |
can result in substitution failure when `ranges::iter_move(E)` appears
|
|
|
|
| 534 |
|
| 535 |
and does not include a declaration of `ranges::iter_swap`. If the
|
| 536 |
function selected by overload resolution does not exchange the values
|
| 537 |
denoted by `E1` and `E2`, the program is ill-formed, no diagnostic
|
| 538 |
required.
|
| 539 |
+
\[*Note 1*: This precludes calling unconstrained `std::iter_swap`.
|
| 540 |
+
When the deleted overload is viable, program-defined overloads need to
|
| 541 |
+
be more specialized [[temp.func.order]] to be selected. — *end note*]
|
| 542 |
- Otherwise, if the types of `E1` and `E2` each model
|
| 543 |
`indirectly_readable`, and if the reference types of `E1` and `E2`
|
| 544 |
model `swappable_with` [[concept.swappable]], then
|
| 545 |
`ranges::swap(*E1, *E2)`.
|
| 546 |
- Otherwise, if the types `T1` and `T2` of `E1` and `E2` model
|
| 547 |
`indirectly_movable_storable<T1, T2>` and
|
| 548 |
`indirectly_movable_storable<T2, T1>`, then
|
| 549 |
`(void)(*E1 = iter-exchange-move(E2, E1))`, except that `E1` is
|
| 550 |
evaluated only once.
|
| 551 |
+
- Otherwise, `ranges::iter_swap(E1, E2)` is ill-formed. \[*Note 2*: This
|
| 552 |
case can result in substitution failure when
|
| 553 |
`ranges::iter_swap(E1, E2)` appears in the immediate context of a
|
| 554 |
template instantiation. — *end note*]
|
| 555 |
|
| 556 |
### Iterator concepts <a id="iterator.concepts">[[iterator.concepts]]</a>
|
|
|
|
| 585 |
I operator++(int);
|
| 586 |
I& operator--();
|
| 587 |
I operator--(int);
|
| 588 |
|
| 589 |
bool operator==(I) const;
|
|
|
|
| 590 |
};
|
| 591 |
```
|
| 592 |
|
| 593 |
`iterator_traits<I>::iterator_category` denotes `input_iterator_tag`,
|
| 594 |
and `ITER_CONCEPT(I)` denotes `random_access_iterator_tag`.
|
|
|
|
| 623 |
```
|
| 624 |
|
| 625 |
Given a value `i` of type `I`, `I` models `indirectly_readable` only if
|
| 626 |
the expression `*i` is equality-preserving.
|
| 627 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 628 |
#### Concept <a id="iterator.concept.writable">[[iterator.concept.writable]]</a>
|
| 629 |
|
| 630 |
The `indirectly_writable` concept specifies the requirements for writing
|
| 631 |
a value into an iterator’s referenced object.
|
| 632 |
|
|
|
|
| 646 |
Let `E` be an expression such that `decltype((E))` is `T`, and let `o`
|
| 647 |
be a dereferenceable object of type `Out`. `Out` and `T` model
|
| 648 |
`indirectly_writable<Out, T>` only if
|
| 649 |
|
| 650 |
- If `Out` and `T` model
|
| 651 |
+
`indirectly_readable<Out> && same_as<iter_value_t<Out>, decay_t<T>>`,
|
| 652 |
then `*o` after any above assignment is equal to the value of `E`
|
| 653 |
before the assignment.
|
| 654 |
|
| 655 |
After evaluating any above assignment expression, `o` is not required to
|
| 656 |
be dereferenceable.
|
|
|
|
| 676 |
increment operations are not required to be equality-preserving, nor is
|
| 677 |
the type required to be `equality_comparable`.
|
| 678 |
|
| 679 |
``` cpp
|
| 680 |
template<class T>
|
| 681 |
+
constexpr bool is-integer-like = see below; // exposition only
|
| 682 |
|
| 683 |
template<class T>
|
| 684 |
+
constexpr bool is-signed-integer-like = see below; // exposition only
|
| 685 |
|
| 686 |
template<class I>
|
| 687 |
concept weakly_incrementable =
|
| 688 |
+
movable<I> &&
|
| 689 |
requires(I i) {
|
| 690 |
typename iter_difference_t<I>;
|
| 691 |
requires is-signed-integer-like<iter_difference_t<I>>;
|
| 692 |
{ ++i } -> same_as<I&>; // not required to be equality-preserving
|
| 693 |
i++; // not required to be equality-preserving
|
| 694 |
};
|
| 695 |
```
|
| 696 |
|
| 697 |
A type `I` is an *integer-class type* if it is in a set of
|
| 698 |
+
*implementation-defined* types that behave as integer types do, as
|
| 699 |
+
defined below.
|
| 700 |
+
|
| 701 |
+
[*Note 1*: An integer-class type is not necessarily a class
|
| 702 |
+
type. — *end note*]
|
| 703 |
|
| 704 |
The range of representable values of an integer-class type is the
|
| 705 |
+
continuous set of values over which it is defined. For any integer-class
|
| 706 |
+
type, its range of representable values is either -2ᴺ⁻¹ to 2ᴺ⁻¹-1
|
| 707 |
+
(inclusive) for some integer N, in which case it is a
|
| 708 |
+
*signed-integer-class type*, or 0 to 2ᴺ-1 (inclusive) for some integer
|
| 709 |
+
N, in which case it is an *unsigned-integer-class type*. In both cases,
|
| 710 |
+
N is called the *width* of the integer-class type. The width of an
|
| 711 |
+
integer-class type is greater than that of every integral type of the
|
| 712 |
+
same signedness.
|
| 713 |
|
| 714 |
+
A type `I` other than cv `bool` is *integer-like* if it models
|
| 715 |
+
`integral<I>` or if it is an integer-class type. An integer-like type
|
| 716 |
+
`I` is *signed-integer-like* if it models `signed_integral<I>` or if it
|
| 717 |
+
is a signed-integer-class type. An integer-like type `I` is
|
| 718 |
+
*unsigned-integer-like* if it models `unsigned_integral<I>` or if it is
|
| 719 |
+
an unsigned-integer-class type.
|
| 720 |
|
| 721 |
+
For every integer-class type `I`, let `B(I)` be a unique hypothetical
|
| 722 |
+
extended integer type of the same signedness with the same width
|
| 723 |
+
[[basic.fundamental]] as `I`.
|
|
|
|
| 724 |
|
| 725 |
+
[*Note 2*: The corresponding hypothetical specialization
|
| 726 |
+
`numeric_limits<B(I)>` meets the requirements on `numeric_limits`
|
| 727 |
+
specializations for integral types [[numeric.limits]]. — *end note*]
|
| 728 |
+
|
| 729 |
+
For every integral type `J`, let `B(J)` be the same type as `J`.
|
| 730 |
+
|
| 731 |
+
Expressions of integer-class type are explicitly convertible to any
|
| 732 |
+
integer-like type, and implicitly convertible to any integer-class type
|
| 733 |
+
of equal or greater width and the same signedness. Expressions of
|
| 734 |
+
integral type are both implicitly and explicitly convertible to any
|
| 735 |
+
integer-class type. Conversions between integral and integer-class types
|
| 736 |
+
and between two integer-class types do not exit via an exception. The
|
| 737 |
+
result of such a conversion is the unique value of the destination type
|
| 738 |
+
that is congruent to the source modulo 2ᴺ, where N is the width of the
|
| 739 |
+
destination type.
|
| 740 |
+
|
| 741 |
+
Let `a` be an object of integer-class type `I`, let `b` be an object of
|
| 742 |
+
integer-like type `I2` such that the expression `b` is implicitly
|
| 743 |
+
convertible to `I`, let `x` and `y` be, respectively, objects of type
|
| 744 |
+
`B(I)` and `B(I2)` as described above that represent the same values as
|
| 745 |
+
`a` and `b`, and let `c` be an lvalue of any integral type.
|
| 746 |
+
|
| 747 |
+
- The expressions `a++` and `a--` shall be prvalues of type `I` whose
|
| 748 |
+
values are equal to that of `a` prior to the evaluation of the
|
| 749 |
+
expressions. The expression `a++` shall modify the value of `a` by
|
| 750 |
+
adding `1` to it. The expression `a--` shall modify the value of `a`
|
| 751 |
+
by subtracting `1` from it.
|
| 752 |
+
- The expressions `++a`, `--a`, and `&a` shall be expression-equivalent
|
| 753 |
+
to `a += 1`, `a -= 1`, and `addressof(a)`, respectively.
|
| 754 |
+
- For every *unary-operator* `@` other than `&` for which the expression
|
| 755 |
+
`@x` is well-formed, `@a` shall also be well-formed and have the same
|
| 756 |
+
value, effects, and value category as `@x`. If `@x` has type `bool`,
|
| 757 |
+
so too does `@a`; if `@x` has type `B(I)`, then `@a` has type `I`.
|
| 758 |
- For every assignment operator `@=` for which `c @= x` is well-formed,
|
| 759 |
`c @= a` shall also be well-formed and shall have the same value and
|
| 760 |
effects as `c @= x`. The expression `c @= a` shall be an lvalue
|
| 761 |
referring to `c`.
|
| 762 |
+
- For every assignment operator `@=` for which `x @= y` is well-formed,
|
| 763 |
+
`a @= b` shall also be well-formed and shall have the same effects as
|
| 764 |
+
`x @= y`, except that the value that would be stored into `x` is
|
| 765 |
+
stored into `a`. The expression `a @= b` shall be an lvalue referring
|
| 766 |
+
to `a`.
|
| 767 |
+
- For every non-assignment binary operator `@` for which `x @ y` and
|
| 768 |
+
`y @ x` are well-formed, `a @ b` and `b @ a` shall also be well-formed
|
| 769 |
+
and shall have the same value, effects, and value category as `x @ y`
|
| 770 |
+
and `y @ x`, respectively. If `x @ y` or `y @ x` has type `B(I)`, then
|
| 771 |
+
`a @ b` or `b @ a`, respectively, has type `I`; if `x @ y` or `y @ x`
|
| 772 |
+
has type `B(I2)`, then `a @ b` or `b @ a`, respectively, has type
|
| 773 |
+
`I2`; if `x @ y` or `y @ x` has any other type, then `a @ b` or
|
| 774 |
+
`b @ a`, respectively, has that type.
|
| 775 |
|
| 776 |
An expression `E` of integer-class type `I` is contextually convertible
|
| 777 |
to `bool` as if by `bool(E != I(0))`.
|
| 778 |
|
| 779 |
All integer-class types model `regular` [[concepts.object]] and
|
| 780 |
+
`three_way_comparable<strong_ordering>` [[cmp.concept]].
|
| 781 |
|
| 782 |
A value-initialized object of integer-class type has value 0.
|
| 783 |
|
| 784 |
For every (possibly cv-qualified) integer-class type `I`,
|
| 785 |
+
`numeric_limits<I>` is specialized such that each static data member `m`
|
| 786 |
+
has the same value as `numeric_limits<B(I)>::m`, and each static member
|
| 787 |
+
function `f` returns `I(numeric_limits<B(I)>::f())`.
|
| 788 |
|
| 789 |
+
For any two integer-like types `I1` and `I2`, at least one of which is
|
| 790 |
+
an integer-class type, `common_type_t<I1, I2>` denotes an integer-class
|
| 791 |
+
type whose width is not less than that of `I1` or `I2`. If both `I1` and
|
| 792 |
+
`I2` are signed-integer-like types, then `common_type_t<I1, I2>` is also
|
| 793 |
+
a signed-integer-like type.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 794 |
|
| 795 |
`is-integer-like<I>` is `true` if and only if `I` is an integer-like
|
| 796 |
+
type. `is-signed-integer-like<I>` is `true` if and only if `I` is a
|
| 797 |
signed-integer-like type.
|
| 798 |
|
| 799 |
Let `i` be an object of type `I`. When `i` is in the domain of both pre-
|
| 800 |
and post-increment, `i` is said to be *incrementable*. `I` models
|
| 801 |
`weakly_incrementable<I>` only if
|
|
|
|
| 804 |
- If `i` is incrementable, then both `++i` and `i++` advance `i` to the
|
| 805 |
next element.
|
| 806 |
- If `i` is incrementable, then `addressof(++i)` is equal to
|
| 807 |
`addressof(i)`.
|
| 808 |
|
| 809 |
+
*Recommended practice:* The implementaton of an algorithm on a weakly
|
| 810 |
+
incrementable type should never attempt to pass through the same
|
| 811 |
+
incrementable value twice; such an algorithm should be a single-pass
|
| 812 |
+
algorithm.
|
| 813 |
+
|
| 814 |
+
[*Note 3*: For `weakly_incrementable` types, `a` equals `b` does not
|
| 815 |
imply that `++a` equals `++b`. (Equality does not guarantee the
|
| 816 |
+
substitution property or referential transparency.) Such algorithms can
|
| 817 |
+
be used with istreams as the source of the input data through the
|
| 818 |
+
`istream_iterator` class template. — *end note*]
|
|
|
|
|
|
|
| 819 |
|
| 820 |
#### Concept <a id="iterator.concept.inc">[[iterator.concept.inc]]</a>
|
| 821 |
|
| 822 |
The `incrementable` concept specifies requirements on types that can be
|
| 823 |
incremented with the pre- and post-increment operators. The increment
|
|
|
|
| 854 |
concept taxonomy; every iterator models `input_or_output_iterator`. This
|
| 855 |
concept specifies operations for dereferencing and incrementing an
|
| 856 |
iterator. Most algorithms will require additional operations to compare
|
| 857 |
iterators with sentinels [[iterator.concept.sentinel]], to read
|
| 858 |
[[iterator.concept.input]] or write [[iterator.concept.output]] values,
|
| 859 |
+
or to provide a richer set of iterator movements
|
| 860 |
+
[[iterator.concept.forward]], [[iterator.concept.bidir]], [[iterator.concept.random.access]].
|
|
|
|
| 861 |
|
| 862 |
``` cpp
|
| 863 |
template<class I>
|
| 864 |
concept input_or_output_iterator =
|
| 865 |
requires(I i) {
|
|
|
|
| 881 |
``` cpp
|
| 882 |
template<class S, class I>
|
| 883 |
concept sentinel_for =
|
| 884 |
semiregular<S> &&
|
| 885 |
input_or_output_iterator<I> &&
|
| 886 |
+
weakly-equality-comparable-with<S, I>; // see [concept.equalitycomparable]
|
| 887 |
```
|
| 888 |
|
| 889 |
Let `s` and `i` be values of type `S` and `I` such that \[`i`, `s`)
|
| 890 |
denotes a range. Types `S` and `I` model `sentinel_for<S, I>` only if
|
| 891 |
|
| 892 |
- `i == s` is well-defined.
|
| 893 |
- If `bool(i != s)` then `i` is dereferenceable and \[`++i`, `s`)
|
| 894 |
denotes a range.
|
| 895 |
+
- `assignable_from<I&, S>` is either modeled or not satisfied.
|
| 896 |
|
| 897 |
The domain of `==` is not static. Given an iterator `i` and sentinel `s`
|
| 898 |
such that \[`i`, `s`) denotes a range and `i != s`, `i` and `s` are not
|
| 899 |
required to continue to denote a range after incrementing any other
|
| 900 |
iterator equal to `i`. Consequently, `i == s` is no longer required to
|
|
|
|
| 928 |
- If -N is representable by `iter_difference_t<I>`, then `i - s` is
|
| 929 |
well-defined and equals -N.
|
| 930 |
|
| 931 |
``` cpp
|
| 932 |
template<class S, class I>
|
| 933 |
+
constexpr bool disable_sized_sentinel_for = false;
|
| 934 |
```
|
| 935 |
|
| 936 |
*Remarks:* Pursuant to [[namespace.std]], users may specialize
|
| 937 |
`disable_sized_sentinel_for` for cv-unqualified non-array object types
|
| 938 |
`S` and `I` if `S` and/or `I` is a program-defined type. Such
|
|
|
|
| 996 |
``` cpp
|
| 997 |
*i = E;
|
| 998 |
++i;
|
| 999 |
```
|
| 1000 |
|
| 1001 |
+
*Recommended practice:* The implementation of an algorithm on output
|
| 1002 |
+
iterators should never attempt to pass through the same iterator twice;
|
| 1003 |
+
such an algorithm should be a single-pass algorithm.
|
| 1004 |
|
| 1005 |
#### Concept <a id="iterator.concept.forward">[[iterator.concept.forward]]</a>
|
| 1006 |
|
| 1007 |
The `forward_iterator` concept adds copyability, equality comparison,
|
| 1008 |
and the multi-pass guarantee, specified below.
|
|
|
|
| 1030 |
|
| 1031 |
Two dereferenceable iterators `a` and `b` of type `X` offer the
|
| 1032 |
*multi-pass guarantee* if:
|
| 1033 |
|
| 1034 |
- `a == b` implies `++a == ++b` and
|
| 1035 |
+
- the expression `((void)[](X x){++x;}(a), *a)` is equivalent to the
|
| 1036 |
expression `*a`.
|
| 1037 |
|
| 1038 |
[*Note 2*: The requirement that `a == b` implies `++a == ++b` and the
|
| 1039 |
removal of the restrictions on the number of assignments through a
|
| 1040 |
mutable iterator (which applies to output iterators) allow the use of
|
|
|
|
| 1140 |
`a` and `c` is reachable from `b`, and let `D` be
|
| 1141 |
`iter_difference_t<I>`. The type `I` models `contiguous_iterator` only
|
| 1142 |
if
|
| 1143 |
|
| 1144 |
- `to_address(a) == addressof(*a)`,
|
| 1145 |
+
- `to_address(b) == to_address(a) + D(b - a)`,
|
| 1146 |
+
- `to_address(c) == to_address(a) + D(c - a)`,
|
| 1147 |
+
- `ranges::iter_move(a)` has the same type, value category, and effects
|
| 1148 |
+
as `std::move(*a)`, and
|
| 1149 |
+
- if `ranges::iter_swap(a, b)` is well-formed, it has effects equivalent
|
| 1150 |
+
to `ranges::swap(*a, *b)`.
|
| 1151 |
|
| 1152 |
### C++17 iterator requirements <a id="iterator.cpp17">[[iterator.cpp17]]</a>
|
| 1153 |
|
| 1154 |
+
#### General <a id="iterator.cpp17.general">[[iterator.cpp17.general]]</a>
|
| 1155 |
+
|
| 1156 |
In the following sections, `a` and `b` denote values of type `X` or
|
| 1157 |
`const X`, `difference_type` and `reference` refer to the types
|
| 1158 |
`iterator_traits<X>::difference_type` and
|
| 1159 |
`iterator_traits<X>::reference`, respectively, `n` denotes a value of
|
| 1160 |
`difference_type`, `u`, `tmp`, and `m` denote identifiers, `r` denotes a
|
|
|
|
| 1169 |
The *Cpp17Iterator* requirements form the basis of the iterator
|
| 1170 |
taxonomy; every iterator meets the *Cpp17Iterator* requirements. This
|
| 1171 |
set of requirements specifies operations for dereferencing and
|
| 1172 |
incrementing an iterator. Most algorithms will require additional
|
| 1173 |
operations to read [[input.iterators]] or write [[output.iterators]]
|
| 1174 |
+
values, or to provide a richer set of iterator movements
|
| 1175 |
+
[[forward.iterators]], [[bidirectional.iterators]], [[random.access.iterators]].
|
|
|
|
| 1176 |
|
| 1177 |
+
A type `X` meets the requirements if:
|
| 1178 |
|
| 1179 |
+
- `X` meets the *Cpp17CopyConstructible*, *Cpp17CopyAssignable*,
|
| 1180 |
+
*Cpp17Swappable*, and *Cpp17Destructible* requirements
|
| 1181 |
+
[[utility.arg.requirements]], [[swappable.requirements]], and
|
| 1182 |
- `iterator_traits<X>::difference_type` is a signed integer type or
|
| 1183 |
`void`, and
|
| 1184 |
- the expressions in [[iterator]] are valid and have the indicated
|
| 1185 |
semantics.
|
| 1186 |
|
|
|
|
| 1202 |
[*Example 1*: The call `find(a,b,x)` is defined only if the value of
|
| 1203 |
`a` has the property *p* defined as follows: `b` has property *p* and a
|
| 1204 |
value `i` has property *p* if (`*i==x`) or if (`*i!=x` and `++i` has
|
| 1205 |
property *p*). — *end example*]
|
| 1206 |
|
| 1207 |
+
*Recommended practice:* The implementation of an algorithm on input
|
| 1208 |
+
iterators should never attempt to pass through the same iterator twice;
|
| 1209 |
+
such an algorithm should be a single pass algorithm.
|
| 1210 |
+
|
| 1211 |
[*Note 1*: For input iterators, `a == b` does not imply `++a == ++b`.
|
| 1212 |
(Equality does not guarantee the substitution property or referential
|
| 1213 |
+
transparency.) Value type `T` is not required to be a
|
| 1214 |
+
*Cpp17CopyAssignable* type ([[cpp17.copyassignable]]). Such an
|
| 1215 |
+
algorithm can be used with istreams as the source of the input data
|
| 1216 |
+
through the `istream_iterator` class template. — *end note*]
|
|
|
|
|
|
|
| 1217 |
|
| 1218 |
#### Output iterators <a id="output.iterators">[[output.iterators]]</a>
|
| 1219 |
|
| 1220 |
A class or pointer type `X` meets the requirements of an output iterator
|
| 1221 |
if `X` meets the *Cpp17Iterator* requirements [[iterator.iterators]] and
|
| 1222 |
the expressions in [[outputiterator]] are valid and have the indicated
|
| 1223 |
semantics.
|
| 1224 |
|
| 1225 |
+
*Recommended practice:* The implementation of an algorithm on output
|
| 1226 |
+
iterators should never attempt to pass through the same iterator twice;
|
| 1227 |
+
such an algorithm should be a single-pass algorithm.
|
| 1228 |
+
|
| 1229 |
[*Note 1*: The only valid use of an `operator*` is on the left side of
|
| 1230 |
the assignment statement. Assignment through the same value of the
|
| 1231 |
+
iterator happens only once. Equality and inequality are not necessarily
|
|
|
|
|
|
|
| 1232 |
defined. — *end note*]
|
| 1233 |
|
| 1234 |
#### Forward iterators <a id="forward.iterators">[[forward.iterators]]</a>
|
| 1235 |
|
| 1236 |
A class or pointer type `X` meets the requirements of a forward iterator
|
|
|
|
| 1292 |
### Indirect callable requirements <a id="indirectcallable">[[indirectcallable]]</a>
|
| 1293 |
|
| 1294 |
#### General <a id="indirectcallable.general">[[indirectcallable.general]]</a>
|
| 1295 |
|
| 1296 |
There are several concepts that group requirements of algorithms that
|
| 1297 |
+
take callable objects [[func.def]] as arguments.
|
| 1298 |
+
|
| 1299 |
+
#### Indirect callable traits <a id="indirectcallable.traits">[[indirectcallable.traits]]</a>
|
| 1300 |
+
|
| 1301 |
+
To implement algorithms taking projections, it is necessary to determine
|
| 1302 |
+
the projected type of an iterator’s value type. For the exposition-only
|
| 1303 |
+
alias template *`indirect-value-t`*, `indirect-value-t<T>` denotes
|
| 1304 |
+
|
| 1305 |
+
- `invoke_result_t<Proj&, indirect-value-t<I>>` if `T` names
|
| 1306 |
+
`projected<I, Proj>`, and
|
| 1307 |
+
- `iter_value_t<T>&` otherwise.
|
| 1308 |
|
| 1309 |
#### Indirect callables <a id="indirectcallable.indirectinvocable">[[indirectcallable.indirectinvocable]]</a>
|
| 1310 |
|
| 1311 |
The indirect callable concepts are used to constrain those algorithms
|
| 1312 |
+
that accept callable objects [[func.def]] as arguments.
|
| 1313 |
|
| 1314 |
``` cpp
|
| 1315 |
namespace std {
|
| 1316 |
template<class F, class I>
|
| 1317 |
concept indirectly_unary_invocable =
|
| 1318 |
indirectly_readable<I> &&
|
| 1319 |
copy_constructible<F> &&
|
| 1320 |
+
invocable<F&, indirect-value-t<I>> &&
|
| 1321 |
invocable<F&, iter_reference_t<I>> &&
|
| 1322 |
invocable<F&, iter_common_reference_t<I>> &&
|
| 1323 |
common_reference_with<
|
| 1324 |
+
invoke_result_t<F&, indirect-value-t<I>>,
|
| 1325 |
invoke_result_t<F&, iter_reference_t<I>>>;
|
| 1326 |
|
| 1327 |
template<class F, class I>
|
| 1328 |
concept indirectly_regular_unary_invocable =
|
| 1329 |
indirectly_readable<I> &&
|
| 1330 |
copy_constructible<F> &&
|
| 1331 |
+
regular_invocable<F&, indirect-value-t<I>> &&
|
| 1332 |
regular_invocable<F&, iter_reference_t<I>> &&
|
| 1333 |
regular_invocable<F&, iter_common_reference_t<I>> &&
|
| 1334 |
common_reference_with<
|
| 1335 |
+
invoke_result_t<F&, indirect-value-t<I>>,
|
| 1336 |
invoke_result_t<F&, iter_reference_t<I>>>;
|
| 1337 |
|
| 1338 |
template<class F, class I>
|
| 1339 |
concept indirect_unary_predicate =
|
| 1340 |
indirectly_readable<I> &&
|
| 1341 |
copy_constructible<F> &&
|
| 1342 |
+
predicate<F&, indirect-value-t<I>> &&
|
| 1343 |
predicate<F&, iter_reference_t<I>> &&
|
| 1344 |
predicate<F&, iter_common_reference_t<I>>;
|
| 1345 |
|
| 1346 |
template<class F, class I1, class I2>
|
| 1347 |
concept indirect_binary_predicate =
|
| 1348 |
indirectly_readable<I1> && indirectly_readable<I2> &&
|
| 1349 |
copy_constructible<F> &&
|
| 1350 |
+
predicate<F&, indirect-value-t<I1>, indirect-value-t<I2>> &&
|
| 1351 |
+
predicate<F&, indirect-value-t<I1>, iter_reference_t<I2>> &&
|
| 1352 |
+
predicate<F&, iter_reference_t<I1>, indirect-value-t<I2>> &&
|
| 1353 |
predicate<F&, iter_reference_t<I1>, iter_reference_t<I2>> &&
|
| 1354 |
predicate<F&, iter_common_reference_t<I1>, iter_common_reference_t<I2>>;
|
| 1355 |
|
| 1356 |
template<class F, class I1, class I2 = I1>
|
| 1357 |
concept indirect_equivalence_relation =
|
| 1358 |
indirectly_readable<I1> && indirectly_readable<I2> &&
|
| 1359 |
copy_constructible<F> &&
|
| 1360 |
+
equivalence_relation<F&, indirect-value-t<I1>, indirect-value-t<I2>> &&
|
| 1361 |
+
equivalence_relation<F&, indirect-value-t<I1>, iter_reference_t<I2>> &&
|
| 1362 |
+
equivalence_relation<F&, iter_reference_t<I1>, indirect-value-t<I2>> &&
|
| 1363 |
equivalence_relation<F&, iter_reference_t<I1>, iter_reference_t<I2>> &&
|
| 1364 |
equivalence_relation<F&, iter_common_reference_t<I1>, iter_common_reference_t<I2>>;
|
| 1365 |
|
| 1366 |
template<class F, class I1, class I2 = I1>
|
| 1367 |
concept indirect_strict_weak_order =
|
| 1368 |
indirectly_readable<I1> && indirectly_readable<I2> &&
|
| 1369 |
copy_constructible<F> &&
|
| 1370 |
+
strict_weak_order<F&, indirect-value-t<I1>, indirect-value-t<I2>> &&
|
| 1371 |
+
strict_weak_order<F&, indirect-value-t<I1>, iter_reference_t<I2>> &&
|
| 1372 |
+
strict_weak_order<F&, iter_reference_t<I1>, indirect-value-t<I2>> &&
|
| 1373 |
strict_weak_order<F&, iter_reference_t<I1>, iter_reference_t<I2>> &&
|
| 1374 |
strict_weak_order<F&, iter_common_reference_t<I1>, iter_common_reference_t<I2>>;
|
| 1375 |
}
|
| 1376 |
```
|
| 1377 |
|
| 1378 |
#### Class template `projected` <a id="projected">[[projected]]</a>
|
| 1379 |
|
| 1380 |
Class template `projected` is used to constrain algorithms that accept
|
| 1381 |
+
callable objects and projections [[defns.projection]]. It combines an
|
| 1382 |
`indirectly_readable` type `I` and a callable object type `Proj` into a
|
| 1383 |
new `indirectly_readable` type whose `reference` type is the result of
|
| 1384 |
applying `Proj` to the `iter_reference_t` of `I`.
|
| 1385 |
|
| 1386 |
``` cpp
|
|
|
|
| 1416 |
below imposes constraints on the concepts’ arguments in addition to
|
| 1417 |
those that appear in the concepts’ bodies [[range.cmp]]. — *end note*]
|
| 1418 |
|
| 1419 |
#### Concept <a id="alg.req.ind.move">[[alg.req.ind.move]]</a>
|
| 1420 |
|
| 1421 |
+
The `indirectly_movable` concept specifies the relationship between an
|
| 1422 |
+
`indirectly_readable` type and an `indirectly_writable` type between
|
| 1423 |
which values may be moved.
|
| 1424 |
|
| 1425 |
``` cpp
|
| 1426 |
template<class In, class Out>
|
| 1427 |
concept indirectly_movable =
|
|
|
|
| 1457 |
state of the value denoted by `*i` is valid but unspecified
|
| 1458 |
[[lib.types.movedfrom]].
|
| 1459 |
|
| 1460 |
#### Concept <a id="alg.req.ind.copy">[[alg.req.ind.copy]]</a>
|
| 1461 |
|
| 1462 |
+
The `indirectly_copyable` concept specifies the relationship between an
|
| 1463 |
+
`indirectly_readable` type and an `indirectly_writable` type between
|
| 1464 |
which values may be copied.
|
| 1465 |
|
| 1466 |
``` cpp
|
| 1467 |
template<class In, class Out>
|
| 1468 |
concept indirectly_copyable =
|