26 Ranges library [ranges]

26.3 Range access [range.access]

26.3.1 General [range.access.general]

1
#
In addition to being available via inclusion of the <ranges> header, the customization point objects in [range.access] are available when <iterator> is included.
2
#
Within [range.access], the reified object of a subexpression E denotes
  • (2.1)
    the same object as E if E is a glvalue, or
  • (2.2)
    the result of applying the temporary materialization conversion ([conv.rval]) to E otherwise.

26.3.2 ranges​::​begin [range.access.begin]

1
#
The name ranges​::​begin denotes a customization point object ([customization.point.object]).
2
#
Given a subexpression E with type T, let t be an lvalue that denotes the reified object for E.
Then:
  • (2.1)
    If E is an rvalue and enable_­borrowed_­range<remove_­cv_­t<T>> is false, ranges​::​begin(E) is ill-formed.
  • (2.2)
    Otherwise, if T is an array type ([dcl.array]) and remove_­all_­extents_­t<T> is an incomplete type, ranges​::​begin(E) is ill-formed with no diagnostic required.
  • (2.3)
    Otherwise, if T is an array type, ranges​::​begin(E) is expression-equivalent to t + 0.
  • (2.4)
    Otherwise, if auto(t.begin()) is a valid expression whose type models input_­or_­output_­iterator, ranges​::​begin(E) is expression-equivalent to auto(t.begin()).
  • (2.5)
    Otherwise, if T is a class or enumeration type and auto(begin(t)) is a valid expression whose type models input_­or_­output_­iterator with overload resolution performed in a context in which unqualified lookup for begin finds only the declarations void begin(auto&) = delete; void begin(const auto&) = delete; then ranges​::​begin(E) is expression-equivalent to auto(begin(t)) with overload resolution performed in the above context.
  • (2.6)
    Otherwise, ranges​::​begin(E) is ill-formed.
3
#
[Note 1:
Diagnosable ill-formed cases above result in substitution failure when ranges​::​begin(E) appears in the immediate context of a template instantiation.
— end note]
4
#
[Note 2:
Whenever ranges​::​begin(E) is a valid expression, its type models input_­or_­output_­iterator.
— end note]

26.3.3 ranges​::​end [range.access.end]

1
#
The name ranges​::​end denotes a customization point object ([customization.point.object]).
2
#
Given a subexpression E with type T, let t be an lvalue that denotes the reified object for E.
Then:
  • (2.1)
    If E is an rvalue and enable_­borrowed_­range<remove_­cv_­t<T>> is false, ranges​::​end(E) is ill-formed.
  • (2.2)
    Otherwise, if T is an array type ([dcl.array]) and remove_­all_­extents_­t<T> is an incomplete type, ranges​::​end(E) is ill-formed with no diagnostic required.
  • (2.3)
    Otherwise, if T is an array of unknown bound, ranges​::​end(E) is ill-formed.
  • (2.4)
    Otherwise, if T is an array, ranges​::​end(E) is expression-equivalent to t + extent_­v<T>.
  • (2.5)
    Otherwise, if auto(t.end()) is a valid expression whose type models sentinel_­for<iterator_­t<T>> then ranges​::​end(E) is expression-equivalent to auto(t.end()).
  • (2.6)
    Otherwise, if T is a class or enumeration type and auto(end(t)) is a valid expression whose type models sentinel_­for<iterator_­t<T>> with overload resolution performed in a context in which unqualified lookup for end finds only the declarations void end(auto&) = delete; void end(const auto&) = delete; then ranges​::​end(E) is expression-equivalent to auto(end(t)) with overload resolution performed in the above context.
  • (2.7)
    Otherwise, ranges​::​end(E) is ill-formed.
3
#
[Note 1:
Diagnosable ill-formed cases above result in substitution failure when ranges​::​end(E) appears in the immediate context of a template instantiation.
— end note]
4
#
[Note 2:
Whenever ranges​::​end(E) is a valid expression, the types S and I of ranges​::​end(E) and ranges​::​begin(E) model sentinel_­for<S, I>.
— end note]

26.3.4 ranges​::​cbegin [range.access.cbegin]

1
#
The name ranges​::​cbegin denotes a customization point object ([customization.point.object]).
Given a subexpression E with type T, let t be an lvalue that denotes the reified object for E.
Then:
  • (1.1)
    If E is an rvalue and enable_­borrowed_­range<remove_­cv_­t<T>> is false, ranges​::​cbegin(E) is ill-formed.
  • (1.2)
    Otherwise, let U be ranges​::​begin(possibly-const-range(t)).
    ranges​::​cbegin(E) is expression-equivalent to const_­iterator<decltype(U)>(U).
2
#
[Note 1:
Whenever ranges​::​cbegin(E) is a valid expression, its type models input_­or_­output_­iterator and constant-iterator.
— end note]

26.3.5 ranges​::​cend [range.access.cend]

1
#
The name ranges​::​cend denotes a customization point object ([customization.point.object]).
Given a subexpression E with type T, let t be an lvalue that denotes the reified object for E.
Then:
  • (1.1)
    If E is an rvalue and enable_­borrowed_­range<remove_­cv_­t<T>> is false, ranges​::​cend(E) is ill-formed.
  • (1.2)
    Otherwise, let U be ranges​::​end(possibly-const-range(t)).
    ranges​::​cend(E) is expression-equivalent to const_­sentinel<decltype(U)>(U).
2
#
[Note 1:
Whenever ranges​::​cend(E) is a valid expression, the types S and I of the expressions ranges​::​cend(E) and ranges​::​cbegin(E) model sentinel_­for<S, I>.
If S models input_­iterator, then S also models constant-iterator.
— end note]

26.3.6 ranges​::​rbegin [range.access.rbegin]

1
#
The name ranges​::​rbegin denotes a customization point object ([customization.point.object]).
2
#
Given a subexpression E with type T, let t be an lvalue that denotes the reified object for E.
Then:
  • (2.1)
    If E is an rvalue and enable_­borrowed_­range<remove_­cv_­t<T>> is false, ranges​::​rbegin(E) is ill-formed.
  • (2.2)
    Otherwise, if T is an array type ([dcl.array]) and remove_­all_­extents_­t<T> is an incomplete type, ranges​::​rbegin(E) is ill-formed with no diagnostic required.
  • (2.3)
    Otherwise, if auto(t.rbegin()) is a valid expression whose type models input_­or_­output_­iterator, ranges​::​rbegin(E) is expression-equivalent to auto(t.rbegin()).
  • (2.4)
    Otherwise, if T is a class or enumeration type and auto(rbegin(t)) is a valid expression whose type models input_­or_­output_­iterator with overload resolution performed in a context in which unqualified lookup for rbegin finds only the declarations void rbegin(auto&) = delete; void rbegin(const auto&) = delete; then ranges​::​rbegin(E) is expression-equivalent to auto(rbegin(t)) with overload resolution performed in the above context.
  • (2.5)
    Otherwise, if both ranges​::​begin(t) and ranges​::​end(t) are valid expressions of the same type which models bidirectional_­iterator ([iterator.concept.bidir]), ranges​::​rbegin(E) is expression-equivalent to make_­reverse_­iterator(ranges​::​end(t)).
  • (2.6)
    Otherwise, ranges​::​rbegin(E) is ill-formed.
3
#
[Note 1:
Diagnosable ill-formed cases above result in substitution failure when ranges​::​rbegin(E) appears in the immediate context of a template instantiation.
— end note]
4
#
[Note 2:
Whenever ranges​::​rbegin(E) is a valid expression, its type models input_­or_­output_­iterator.
— end note]

26.3.7 ranges​::​rend [range.access.rend]

1
#
The name ranges​::​rend denotes a customization point object ([customization.point.object]).
2
#
Given a subexpression E with type T, let t be an lvalue that denotes the reified object for E.
Then:
  • (2.1)
    If E is an rvalue and enable_­borrowed_­range<remove_­cv_­t<T>> is false, ranges​::​rend(E) is ill-formed.
  • (2.2)
    Otherwise, if T is an array type ([dcl.array]) and remove_­all_­extents_­t<T> is an incomplete type, ranges​::​rend(E) is ill-formed with no diagnostic required.
  • (2.3)
    Otherwise, if auto(t.rend()) is a valid expression whose type models sentinel_­for<decltype(​ranges​::​rbegin(E))> then ranges​::​rend(E) is expression-equivalent to auto(t.rend()).
  • (2.4)
    Otherwise, if T is a class or enumeration type and auto(rend(t)) is a valid expression whose type models sentinel_­for<decltype(ranges​::​rbegin(E))> with overload resolution performed in a context in which unqualified lookup for rend finds only the declarations void rend(auto&) = delete; void rend(const auto&) = delete; then ranges​::​rend(E) is expression-equivalent to auto(rend(t)) with overload resolution performed in the above context.
  • (2.5)
    Otherwise, if both ranges​::​begin(t) and ranges​::​end(t) are valid expressions of the same type which models bidirectional_­iterator ([iterator.concept.bidir]), then ranges​::​rend(E) is expression-equivalent to make_­reverse_­iterator(ranges​::​begin(t)).
  • (2.6)
    Otherwise, ranges​::​rend(E) is ill-formed.
3
#
[Note 1:
Diagnosable ill-formed cases above result in substitution failure when ranges​::​rend(E) appears in the immediate context of a template instantiation.
— end note]
4
#
[Note 2:
Whenever ranges​::​rend(E) is a valid expression, the types S and I of the expressions ranges​::​rend(E) and ranges​::​rbegin(E) model sentinel_­for<S, I>.
— end note]

26.3.8 ranges​::​crbegin [range.access.crbegin]

1
#
The name ranges​::​crbegin denotes a customization point object ([customization.point.object]).
Given a subexpression E with type T, let t be an lvalue that denotes the reified object for E.
Then:
  • (1.1)
    If E is an rvalue and enable_­borrowed_­range<remove_­cv_­t<T>> is false, ranges​::​crbegin(E) is ill-formed.
  • (1.2)
    Otherwise, let U be ranges​::​rbegin(possibly-const-range(t)).
    ranges​::​crbegin(E) is expression-equivalent to const_­iterator<decltype(U)>(U).
2
#
[Note 1:
Whenever ranges​::​crbegin(E) is a valid expression, its type models input_­or_­output_­iterator and constant-iterator.
— end note]

26.3.9 ranges​::​crend [range.access.crend]

1
#
The name ranges​::​crend denotes a customization point object ([customization.point.object]).
Given a subexpression E with type T, let t be an lvalue that denotes the reified object for E.
Then:
  • (1.1)
    If E is an rvalue and enable_­borrowed_­range<remove_­cv_­t<T>> is false, ranges​::​crend(E) is ill-formed.
  • (1.2)
    Otherwise, let U be ranges​::​rend(possibly-const-range(t)).
    ranges​::​crend(E) is expression-equivalent to const_­sentinel<decltype(U)>(U).
2
#
[Note 1:
Whenever ranges​::​crend(E) is a valid expression, the types S and I of the expressions ranges​::​crend(E) and ranges​::​crbegin(E) model sentinel_­for<S, I>.
If S models input_­iterator, then S also models constant-iterator.
— end note]

26.3.10 ranges​::​size [range.prim.size]

1
#
The name ranges​::​size denotes a customization point object ([customization.point.object]).
2
#
Given a subexpression E with type T, let t be an lvalue that denotes the reified object for E.
Then:
  • (2.1)
    If T is an array of unknown bound ([dcl.array]), ranges​::​size(E) is ill-formed.
  • (2.2)
    Otherwise, if T is an array type, ranges​::​size(E) is expression-equivalent to auto(extent_­v<T>).
  • (2.3)
    Otherwise, if disable_­sized_­range<remove_­cv_­t<T>> ([range.sized]) is false and auto(t.size()) is a valid expression of integer-like type ([iterator.concept.winc]), ranges​::​size(E) is expression-equivalent to auto(​t.size()).
  • (2.4)
    Otherwise, if T is a class or enumeration type, disable_­sized_­range<remove_­cv_­t<T>> is false and auto(size(t)) is a valid expression of integer-like type with overload resolution performed in a context in which unqualified lookup for size finds only the declarations void size(auto&) = delete; void size(const auto&) = delete; then ranges​::​size(E) is expression-equivalent to auto(size(t)) with overload resolution performed in the above context.
  • (2.5)
    Otherwise, if to-unsigned-like(ranges​::​end(t) - ranges​::​begin(t)) ([ranges.syn]) is a valid expression and the types I and S of ranges​::​begin(t) and ranges​::​end(t) (respectively) model both sized_­sentinel_­for<S, I> ([iterator.concept.sizedsentinel]) and forward_­iterator<I>, then ranges​::​size(E) is expression-equivalent to to-unsigned-like(ranges​::​end(t) - ranges​::​begin(t)).
  • (2.6)
    Otherwise, ranges​::​size(E) is ill-formed.
3
#
[Note 1:
Diagnosable ill-formed cases above result in substitution failure when ranges​::​size(E) appears in the immediate context of a template instantiation.
— end note]
4
#
[Note 2:
Whenever ranges​::​size(E) is a valid expression, its type is integer-like.
— end note]

26.3.11 ranges​::​ssize [range.prim.ssize]

1
#
The name ranges​::​ssize denotes a customization point object ([customization.point.object]).
2
#
Given a subexpression E with type T, let t be an lvalue that denotes the reified object for E.
If ranges​::​size(t) is ill-formed, ranges​::​ssize(E) is ill-formed.
Otherwise let D be make-signed-like-t<decltype(ranges​::​​size(t))>, or ptrdiff_­t if it is wider than that type; ranges​::​ssize(E) is expression-equivalent to static_­cast<D>(ranges​::​size(t)).

26.3.12 ranges​::​empty [range.prim.empty]

1
#
The name ranges​::​empty denotes a customization point object ([customization.point.object]).
2
#
Given a subexpression E with type T, let t be an lvalue that denotes the reified object for E.
Then:
  • (2.1)
    If T is an array of unknown bound ([dcl.array]), ranges​::​empty(E) is ill-formed.
  • (2.2)
    Otherwise, if bool(t.empty()) is a valid expression, ranges​::​empty(E) is expression-equivalent to bool(t.empty()).
  • (2.3)
    Otherwise, if (ranges​::​size(t) == 0) is a valid expression, ranges​::​empty(E) is expression-equivalent to (ranges​::​size(t) == 0).
  • (2.4)
    Otherwise, if bool(ranges​::​begin(t) == ranges​::​end(t)) is a valid expression and the type of ranges​::​begin(t) models forward_­iterator, ranges​::​empty(E) is expression-equivalent to bool(​ranges​::​begin(t) == ranges​::​end(t)).
  • (2.5)
    Otherwise, ranges​::​empty(E) is ill-formed.
3
#
[Note 1:
Diagnosable ill-formed cases above result in substitution failure when ranges​::​empty(E) appears in the immediate context of a template instantiation.
— end note]
4
#
[Note 2:
Whenever ranges​::​empty(E) is a valid expression, it has type bool.
— end note]

26.3.13 ranges​::​data [range.prim.data]

1
#
The name ranges​::​data denotes a customization point object ([customization.point.object]).
2
#
Given a subexpression E with type T, let t be an lvalue that denotes the reified object for E.
Then:
  • (2.1)
    If E is an rvalue and enable_­borrowed_­range<remove_­cv_­t<T>> is false, ranges​::​data(E) is ill-formed.
  • (2.2)
    Otherwise, if T is an array type ([dcl.array]) and remove_­all_­extents_­t<T> is an incomplete type, ranges​::​data(E) is ill-formed with no diagnostic required.
  • (2.3)
    Otherwise, if auto(t.data()) is a valid expression of pointer to object type, ranges​::​data(E) is expression-equivalent to auto(t.data()).
  • (2.4)
    Otherwise, if ranges​::​begin(t) is a valid expression whose type models contiguous_­iterator, ranges​::​data(E) is expression-equivalent to to_­address(ranges​::​begin(t)).
  • (2.5)
    Otherwise, ranges​::​data(E) is ill-formed.
3
#
[Note 1:
Diagnosable ill-formed cases above result in substitution failure when ranges​::​data(E) appears in the immediate context of a template instantiation.
— end note]
4
#
[Note 2:
Whenever ranges​::​data(E) is a valid expression, it has pointer to object type.
— end note]

26.3.14 ranges​::​cdata [range.prim.cdata]

template<class T> constexpr auto as-const-pointer(const T* p) { return p; } // exposition only
1
#
The name ranges​::​cdata denotes a customization point object ([customization.point.object]).
Given a subexpression E with type T, let t be an lvalue that denotes the reified object for E.
Then:
  • (1.1)
    If E is an rvalue and enable_­borrowed_­range<remove_­cv_­t<T>> is false, ranges​::​cdata(E) is ill-formed.
  • (1.2)
    Otherwise, ranges​::​cdata(E) is expression-equivalent to as-const-pointer(ranges​::​data(possibly-const-range(t))).
2
#
[Note 1:
Whenever ranges​::​cdata(E) is a valid expression, it has pointer to constant object type.
— end note]