Iteration statements

Iteration statements

Iteration statements repeatedly execute an embedded statement.

iteration-statement:
while-statement
do-statement
for-statement
foreach-statement

The while statement

The while statement conditionally executes an embedded statement zero or more times.

while-statement:
while ( boolean-expression ) embedded-statement

A while statement is executed as follows:

The boolean-expression (‎7.16) is evaluated.

If the boolean expression yields true, control is transferred to the embedded statement. When and if control reaches the end point of the embedded statement (possibly from execution of a continue statement), control is transferred to the beginning of the while statement.

If the boolean expression yields false, control is transferred to the end point of the while statement.

Within the embedded statement of a while statement, a break statement (‎8.9.1) may be used to transfer control to the end point of the while statement (thus ending iteration of the embedded statement), and a continue statement (‎8.9.2) may be used to transfer control to the end point of the embedded statement (thus performing another iteration of the while statement).

The embedded statement of a while statement is reachable if the while statement is reachable and the boolean expression does not have the constant value false.

The end point of a while statement is reachable if at least one of the following is true:

The while statement contains a reachable break statement that exits the while statement.

The while statement is reachable and the boolean expression does not have the constant value true.

The do statement

The do statement conditionally executes an embedded statement one or more times.

do-statement:
do embedded-statement while ( boolean-expression ) ;

A do statement is executed as follows:

Control is transferred to the embedded statement.

When and if control reaches the end point of the embedded statement (possibly from execution of a continue statement), the boolean-expression (‎7.16) is evaluated. If the boolean expression yields true, control is transferred to the beginning of the do statement. Otherwise, control is transferred to the end point of the do statement.

Within the embedded statement of a do statement, a break statement (‎8.9.1) may be used to transfer control to the end point of the do statement (thus ending iteration of the embedded statement), and a continue statement (‎8.9.2) may be used to transfer control to the end point of the embedded statement (thus performing another iteration of the do statement).

The embedded statement of a do statement is reachable if the do statement is reachable.

The end point of a do statement is reachable if at least one of the following is true:

The do statement contains a reachable break statement that exits the do statement.

The end point of the embedded statement is reachable and the boolean expression does not have the constant value true.

The for statement

The for statement evaluates a sequence of initialization expressions and then, while a condition is true, repeatedly executes an embedded statement and evaluates a sequence of iteration expressions.

for-statement:
for ( for-initializer_opt ; for-condition_opt ; for-iterator_opt ) embedded-statement

for-initializer:
local-variable-declaration
statement-expression-list

for-condition:
boolean-expression

for-iterator:
statement-expression-list

statement-expression-list:
statement-expression
statement-expression-list , statement-expression

The for-initializer, if present, consists of either a local-variable-declaration (‎8.5.1) or a list of statement-expressions (‎8.6) separated by commas. The scope of a local variable declared by a for-initializer starts at the variable-declarator for the variable and extends to the end of the embedded statement. The scope includes the for-condition and the for-iterator.

The for-condition, if present, must be a boolean-expression (‎7.16).

The for-iterator, if present, consists of a list of statement-expressions (‎8.6) separated by commas.

A for statement is executed as follows:

If a for-initializer is present, the variable initializers or statement expressions are executed in the order they are written. This step is only performed once.

If a for-condition is present, it is evaluated.

If the for-condition is not present or if the evaluation yields true, control is transferred to the embedded statement. When and if control reaches the end point of the embedded statement (possibly from execution of a continue statement), the expressions of the for-iterator, if any, are evaluated in sequence, and then another iteration is performed, starting with evaluation of the for-condition in the step above.

If the for-condition is present and the evaluation yields false, control is transferred to the end point of the for statement.

Within the embedded statement of a for statement, a break statement (‎8.9.1) may be used to transfer control to the end point of the for statement (thus ending iteration of the embedded statement), and a continue statement (‎8.9.2) may be used to transfer control to the end point of the embedded statement (thus executing another iteration of the for statement).

The embedded statement of a for statement is reachable if one of the following is true:

The for statement is reachable and no for-condition is present.

The for statement is reachable and a for-condition is present and does not have the constant value false.

The end point of a for statement is reachable if at least one of the following is true:

The for statement contains a reachable break statement that exits the for statement.

The for statement is reachable and a for-condition is present and does not have the constant value true.

The foreach statement

The foreach statement enumerates the elements of a collection, executing an embedded statement for each element of the collection.

foreach-statement:
foreach ( type identifier in expression ) embedded-statement

The type and identifier of a foreach statement declare the iteration variable of the statement. The iteration variable corresponds to a read-only local variable with a scope that extends over the embedded statement. During execution of a foreach statement, the iteration variable represents the collection element for which an iteration is currently being performed. A compile-time error occurs if the embedded statement attempts to assign to the iteration variable or pass the iteration variable as a ref or out parameter.

The type of the expression of a foreach statement must be a collection type (as defined below), and an explicit conversion (‎6.2) must exist from the element type of the collection to the type of the iteration variable.

A type C is said to be a collection type if it implements the System.IEnumerable interface or implements the collection pattern by meeting all of the following criteria:

C contains a public instance method with the signature GetEnumerator() that returns a struct-type, class-type, or interface-type, which is called E in the following text.

E contains a public instance method with the signature MoveNext() and the return type bool.

E contains a public instance property named Current that permits reading the current value. The type of this property is said to be the element type of the collection type.

The System.Array type (‎12.1.1) is a collection type, and since all array types derive from System.Array, any array type expression is permitted in a foreach statement. The order in which foreach traverses the elements of an array is defined in ‎7.5.10.2.

A foreach statement is executed as follows:

The collection expression is evaluated to produce an instance of the collection type. This instance is referred to as c in the following. If c is of a reference-type and has the value null, a System.NullReferenceException is thrown.

If the collection type C implements the collection pattern defined above and E implements the System.IDisposable interface then:

An enumerator instance is obtained by evaluating the method invocation c.GetEnumerator(). The returned enumerator is stored in a temporary local variable, in the following referred to as enumerator. It is not possible for the embedded statement to access this temporary variable. If enumerator is of a reference-type and has the value null, a System.NullReferenceException is thrown.

A try-statement (‎8.10) consisting of a try block followed by a finally block is executed:

The try block consists of the following steps:

The enumerator is advanced to the next element by evaluating the method invocation enumerator.MoveNext().

If the value returned by enumerator.MoveNext() is true, the following steps are performed:

The current enumerator value is obtained by evaluating the property access enumerator.Current, and the value is converted to the type of the iteration variable by an explicit conversion (‎6.2). The resulting value is stored in the iteration variable such that it can be accessed in the embedded statement.

Control is transferred to the embedded statement. When and if control reaches the end point of the embedded statement (possibly from execution of a continue statement), another foreach iteration is performed, starting with the step above that advances the enumerator.

If the value returned by e.MoveNext() is false, control is transferred to the end point of the foreach statement.

The finally block disposes the enumerator by converting enumerator to System.IDisposable and calling the Dispose method. Because E implements Sytsem.IDisposable, the conversion is guaranteed to succeed.

Otherwise, if the collection type C implements the collection pattern defined above and E does not implement the System.IDisposable interface then:

An enumerator instance is obtained by evaluating the method invocation c.GetEnumerator(). The returned enumerator is stored in a temporary local variable, in the following referred to as enumerator. It is not possible for the embedded statement to access this temporary variable. If enumerator is of a reference-type and has the value null, a System.NullReferenceException is thrown.

The enumerator is advanced to the next element by evaluating the method invocation enumerator.MoveNext().

If the value returned by enumerator.MoveNext() is true, the following steps are performed:

The current enumerator value is obtained by evaluating the property access enumerator.Current, and the value is converted to the type of the iteration variable by an explicit conversion (‎6.2). The resulting value is stored in the iteration variable such that it can be accessed in the embedded statement.

Control is transferred to the embedded statement. When and if control reaches the end point of the embedded statement (possibly from execution of a continue statement), another foreach iteration is performed, starting with the step above that advances the enumerator.

If the value returned by e.MoveNext() is false, control is transferred to the end point of the foreach statement.

Otherwise, C implements System.IEnumerable, and statement execution proceeds as follows:

An enumerable instance is obtained by casting c to the System.IEnumerable interface. The returned instance is stored in a temporary local variable, in the following referred to as enumerable. It is not possible for the embedded statement to access this temporary variable.

An enumerator instance is obtained by evaluating the method invocation enumerable.GetEnumerator(). The returned enumerator is stored in a temporary local variable, in the following referred to as enumerator. It is not possible for the embedded statement to access this temporary variable. If enumerator has the value null, a System.NullReferenceException is thrown.

A try-statement (‎8.10) consisting of a try block followed by a finally block is executed:

The try block consists of the following steps:

The enumerator is advanced to the next element by evaluating the method invocation enumerator.MoveNext().

If the value returned by enumerator.MoveNext() is true, the following steps are performed:

The current enumerator value is obtained by evaluating the property access enumerator.Current, and the value is converted to the type of the iteration variable by an explicit conversion (‎6.2). The resulting value is stored in the iteration variable such that it can be accessed in the embedded statement.

Control is transferred to the embedded statement. When and if control reaches the end point of the embedded statement (possibly from execution of a continue statement), another foreach iteration is performed, starting with the step above that advances the enumerator.

If the value returned by enumerator.MoveNext() is false, control is transferred to the end point of the foreach statement.

The finally block consists of the following steps:

Evaluate the expression (enumerator as System.IDisposable) and store the result in a temporary local variable, in the following referred to as disposable.

If disposable is non-null then call its Dispose method.

The embedded statement of a foreach statement is reachable if the foreach statement is reachable. Likewise, the end point of a foreach statement is reachable if the foreach statement is reachable.

The following example prints out each value in a two-dimensional array, in element order:

class Test
,
};

foreach (double elementValue in values)
Console.Write(' ', elementValue);

Console.WriteLine();
}
}

The output is:

1.2 3.4 4.5 6.7 5.6 9.8 5.4 3.8