C # 2.0 specification (iterator) (i)

22 iterators
22.1 iterator block
An iterator block is a statement block that produces an ordered sequence of values. An iterator block differs from a regular statement block by one or more yield statements.

L The yield return statement produces the next value of the iteration.

The L yield break statement indicates that the iteration is complete.

An iterator block can be used as a method body (method-body), an operation Fu (Operator-body), an accessor body (accessor-body), provided that the return type of the corresponding function member is one of the enumerator (enumerator) interfaces or enumerable ( Enumerable) One of the interfaces.

Iterator blocks are not unique elements in C # syntax. They are limited in several ways, and the main role is in the semantics of the function member declarations, but they are just sentence blocks in syntax.

When a function member is implemented using an iterator block, specifying any ref or out parameter for the formal argument list results in a compile-time error.

A return statement that appears in an iterator block will result in a compile-time error (but yield the return statement is allowed).

Including an unsafe context (§18.1) in an iterator block will result in a compile-time error. Even when an iterator declaration is embedded in an unsafe context, the iterator block is always defined as a security contextual.

22.1.1 Enumerator interface
The enumerator interface (enumerator interface) is the System.Collections.IEnumerator interface and the system.collections.generic.ienumerator<t> All instances of. In this chapter, these interfaces are referenced accordingly as IEnumerator and ienumerator<t>.

22.1.2 an enumerable interface
The enumerable interfaces (enumerable interface) are System.Collections.IEnumerable interfaces and system.collections.generic.ienumerable<t> All instances of. In this chapter, these interfaces will be referenced accordingly as IEnumerable and Ienumerable<t>.





22.1.3Yield type
The iterator block generates a sequence of all values of the same type. The type is called the yield type of the iterator block (yield type).

The yield type of the L iterator block is typically used to implement a function member that returns IEnumerator or IEnumerable as an object.

The yield type of the L iterator block is typically used to implement a function member that returns ienumerator<t> or ienumerable<t> as T.

22.1.4 this access
Within the iterator block of an instance member of a class, the this expression is categorized as a value. The type of the value is the class type, which can be used in this type, which is the reference to the object when the member is called.

Within the iterator block of an instance member of a struct, this expression is categorized as a variable. The type of the variable is the struct type, which can be used in this structure. The variable represents a copy of the corresponding structure when a member is called. Within the iterator block of a struct instance member, the this variable behaves as if it were a value parameter of a struct type.

22.2 Enumeration Objects
When a function member that returns an enumerator interface type is implemented using an iterator block, calling the function member does not immediately execute the code in the iterator block. Instead, the enumerator object (enumerator object) is created and returned. The object encapsulates the code specified in the iterator block, and the code in the iterator block executes when the MoveNext method of the enumerator object is invoked. The enumerator object has the following characteristics.

L It implements IEnumerator and Ienumerator<t>,t is the yield type of the iterator block (the resulting type).

L it implements the System.IDisposable.







L It is initialized with a copy of the argument value (if any), and the instance value is passed to the function member.

L It has four potential states before, running, suspended and after, and it is initialized before before state.



An enumerator object is usually an instance of a compiler-generated enumerator class that encapsulates the code in the iterator statement block and implements the enumerator interface, but other implementation methods are also possible. If an enumerator class is generated by the compiler, the class will be embedded, and in the class that contains the function member, the class will have private accessibility, and the class has a name that is reserved for the compiler (§2.4.2).

The enumerator object can implement more interfaces than is specified here.

The following sections describe the exact behavior of the MoveNext, current, and dispose members implemented by the IEnumerable and Ienumerable<t> interfaces, which are provided by enumeration objects.

Note that the enumerator object does not support the Ienumerator.reset method. Calling this method throws a System.NotSupportedException exception.

22.2.1MoveNext method
The MoveNext method of the enumerator object encapsulates the code for the iterator block. Calling the MoveNext method executes the code within the iterator and sets the current property of the enumeration object to the appropriate value. The exact action performed by the MoveNext method depends on the state of the enumerator object when the MoveNext method is invoked.

L If the enumerator object state is before, call MoveNext

N will change the state to running.

N initializes the arguments of the iterator block, including this, to the argument value and the instance value that are saved when the enumerator object is initialized.

N Executes the iterator block from the beginning until execution is interrupted (as described below).

L If the state of the enumerator object is running, the result of the call MoveNext is unspecified.

L If the state of the enumerator object is suspended, call MoveNext

N will change the state to running.





L restores the values of all local variables and parameters (including this) to the execution state when the last time the iterator was suspended (suspended). Note that the contents of any object referenced by these variables may change because of a previous call to MoveNext.

N Restarts the execution of the iterator block after the execution of the pending yield return statement, and the state continues until execution is interrupted (as described below).

L If the state of the enumerator object is after, then calling MoveNext will return false.

When MoveNext executes an iterator block, there are four ways to break execution: through a yield return statement, the end point of the iterator block is reached through a yield break statement, and an exception is thrown and propagated outside the iterator block.

L When a yield return statement is encountered (§22.4), the following occurs

n the expression given in the statement is evaluated, implicitly converted to the resulting type (yield type), and assigned to the current property of the enumeration object.

Execution of the N iterator body will be suspended. The values and parameters of all local variables (including this) are saved, and the location of the yield return statement is also saved. If the yield return statement is within one or more try blocks, the finally block associated with it will not be executed at this time.

n the state of the enumerator object is changed to suspended.

The N MoveNext method returns true to the caller, indicating that the iterator successfully advances to the next value.

L when the yield break statement is encountered, the following occurs

n If the yield break statement is within one or more try blocks, the finally statement associated with it is executed.

n the state of the enumerator object is changed to after.

The N MoveNext method returns false to the caller, indicating that the iteration is complete.

L The following occurs when the end point of an iterator block is encountered.

n the state of the enumerator object is changed to after.

The N MoveNext method returns false to the caller, indicating that the iteration is complete.





L When an exception is thrown and propagated outside the iterator block, the following occurs.

N will execute the appropriate finally block within the iterator block due to exception propagation (exception propagation).

n the state of the enumerator object is changed to after.

N for a call to the MoveNext method callers says that exception propagation will continue.

22.2.2 Current Property
The current property of an enumerator object is affected by the yield return statement of the iterator block.

When the enumerator object is in the suspended state, the value of current is the value that was set when the last call to MoveNext. When an enumerator object is in a before, running, or after state, the resulting result of accessing current is unspecified.

For a yield type iterator block with a non-object type, accessing the current derived implementation through the IEnumerable implementation of the enumerator object corresponds to accessing the current gain implementation through the ienumerator<t> of the enumerator object. and converts the result to the type object.

22.2.3 Dispose method
The Dispose method cleans up the iteration results by placing the state of the enumerator object after.

L If the state of the enumerator object is before, calling Dispose will change its state to after.

L If the state of the enumerator object is running, the result of the call to dispose is specified.

L If the state of the enumerator object is suspended, calling Dispose will

N changes its state to running.

N Executes the finally block, as if the last yield return statement is a yield break statement. If an exception is thrown and propagated outside the iterator body, the state of the enumerator object is set to after, and the exception is propagated to the caller of the Dispose method.

n changes its status to after.

L The call to Dispose has no effect if the state of the enumerator object is after.



22.3 Enumerable objects
When a function member that returns an enumerable interface type is implemented using an iterator block, the calling function member does not immediately execute the iterator block code. Instead, an enumerable object (enumerable object) is created and returned. The GetEnumerator method of an enumerable object returns an enumerator object that encapsulates the code specified in the iterator block, triggering the execution of the iterator block code when the MoveNext method of the enumerator object is invoked. An enumerable object has the following characteristics.

L It implements the IEnumerable and Ienumerable<t> interfaces, where T is the type of generation (yield type) of the iterator block.

L It initializes (if any) with a copy of the argument value and passes the instance value to the function member.



A reusable object is usually an instance of a compiler-generated enumerable class that encapsulates the code of an iterator block and implements an enumerable interface, but other implementations are also possible. If the enumerable class is generated by the compiler, the class is embedded in the class that contains the function member and has private accessibility and a name that is reserved for the compiler (§2.4.2).

A single object can implement more interfaces than is described here. In particular, enumerable objects can also implement IEnumerator and Ienumerator<t> interfaces, making it both an enumerable and an enumerator object. In that implementation type, the first invocation of the GetEnumerator method of an enumerable object returns the enumerable object itself. Subsequent calls to the GetEnumerator method of the enumerable object, if any, will return a copy of the enumerable object. Therefore, each returned enumerator will have its own state, and the changes made in one enumerator will not affect the other enumerator.

22.3.1 GetEnumerator Method
The enumerable object provides an implementation of the GetEnumerator method of the IEnumerable and Ienumerable<t> interfaces. These two GetEnumerator methods share a common implementation that is used to get and return a valid enumerator object.

The enumerator object is initialized with an argument value and the instance value is saved when the enumerable object is initialized, on the other hand, the enumerator object function is described as §22.2.