8 Statements [stmt]

8.7 Expansion statements [stmt.expand]

Expansion statements specify repeated instantiations ([temp.decls.general]) of their substatement.

expansion-statement:
template for ( init-statement

_{o p t}

for-range-declaration : expansion-initializer ) compound-statement

expansion-initializer:
expression
expansion-init-list

expansion-init-list:
{ expression-list ,

_{o p t}

}
{ }

The compound-statement of an expansion-statement is a control-flow-limited statement ([stmt.label]).

For an expression E, let the expressions begin-expr and end-expr be determined as specified in [stmt.ranged].

An expression is expansion-iterable if it does not have array type and either

(3.1)
begin-expr and end-expr are of the form E.begin() and E.end(), or
(3.2)
argument-dependent lookups for begin(E) and for end(E) each find at least one viable candidate ([over.match.viable]).

An expansion statement is

(4.1)
an enumerating expansion statement if its expansion-initializer is of the form expansion-init-list;
(4.2)
otherwise, an iterating expansion statement if its expansion-initializer is an expansion-iterable expression;
(4.3)
otherwise, a destructuring expansion statement.

An expansion statement S is equivalent to a compound-statement containing instantiations of the for-range-declaration (including its implied initialization), together with the compound-statement of S, as follows:

(5.1)
If S is an enumerating expansion statement, S is equivalent to: { init-statement $S_{0}$ ⋮ $S_{N - 1}$ } where N is the number of elements in the expression-list, $S_{i}$ is { for-range-declaration = $E_{i}$ ; compound-statement } and $E_{i}$ is the $i^{th}$ element of the expression-list.
(5.2)
Otherwise, if S is an iterating expansion statement, S is equivalent to: { init-statement constexpr $_{o p t}$ decltype(auto) range = (expansion-initializer); constexpr $_{o p t}$ auto begin = begin-expr; // see [stmt.ranged] $S_{0}$ ⋮ $S_{N - 1}$ } where N is the result of evaluating the expression [&] consteval { std::ptrdiff_t result = 0; auto b = begin-expr; auto e = end-expr; for (; b != e; ++b) ++result; return result; // distance from begin to end }() and $S_{i}$ is { constexpr $_{o p t}$ auto iter = begin + decltype(begin - begin){i}; for-range-declaration = *iter; compound-statement }
The variables range, begin, and iter are defined for exposition only.

The keyword constexpr is present in the declarations of range, begin, and iter if and only if constexpr is one of the decl-specifiers of the decl-specifier-seq of the for-range-declaration.

The identifier i is considered to be a prvalue of type std::ptrdiff_t; the program is ill-formed if i is not representable as such a value.
(5.3)
Otherwise, S is a destructuring expansion statement and, if N is 0, S is equivalent to: { init-statement constexpr $_{o p t}$ auto&& range = expansion-initializer; } otherwise, S is equivalent to: { init-statement constexpr $_{o p t}$ auto&& [ $u_{0}$ , $u_{1}$ , …, $u_{N - 1}$ ] = expansion-initializer; $S_{0}$ ⋮ $S_{N - 1}$ } where N is the structured binding size of the type of the expansion-initializer and $S_{i}$ is { for-range-declaration = $v_{i}$ ; compound-statement }
If the expansion-initializer is an lvalue, then $v_{i}$ is $u_{i}$ ; otherwise, $v_{i}$ is static_cast<decltype( $u_{i}$ )&&>( $u_{i}$ ).

The keyword constexpr is present in the structured-binding-declaration of $u_{0}, u_{1}, \dots, u_{N - 1}$ if and only if constexpr is one of the decl-specifiers of the decl-specifier-seq of the for-range-declaration.

[Example 1: consteval int f(auto const&... Containers) { int result = 0; template for (auto const& c : {Containers...}) { // OK, enumerating expansion statement result += c[0]; } return result; } constexpr int c1[] = {1, 2, 3}; constexpr int c2[] = {4, 3, 2, 1}; static_assert(f(c1, c2) == 5); — end example]

[Example 2: consteval int f() { constexpr std::array<int, 3> arr {1, 2, 3}; int result = 0; template for (constexpr int s : arr) { // OK, iterating expansion statement result += sizeof(char[s]); } return result; } static_assert(f() == 6); — end example]

[Example 3: struct S { int i; short s; }; consteval long f(S s) { long result = 0; template for (auto x : s) { // OK, destructuring expansion statement result += sizeof(x); } return result; } static_assert(f(S{}) == sizeof(int) + sizeof(short)); — end example]