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 function or function template.

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 static constexpr auto&& range = expansion-initializer; static constexpr auto begin = begin-expr; // see [stmt.ranged] static constexpr auto end = end-expr; // see [stmt.ranged] $S_{0}$ ⋮ $S_{N - 1}$ } where N is the result of evaluating the expression [] consteval { std::ptrdiff_t result = 0; for (auto i = begin; i != end; ++i, ++result); return result; // distance from begin to end }() and $S_{i}$ is { static constexpr auto iter = begin + i; for-range-declaration = *iter; compound-statement }
The variables range, begin, end, and iter are defined for exposition only.

[Note 1:
The instantiation is ill-formed if range is not a constant expression ([expr.const]).
— end note]
(5.3)
Otherwise, S is a destructuring expansion statement and 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 = $u_{i}$ ; compound-statement }
The keyword constexpr is present in the 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]