description | title | ms.date | f1_keywords | helpviewer_keywords | ms.assetid | ||||
---|---|---|---|---|---|---|---|---|---|
Learn more about: Yield Statement (Visual Basic) |
Yield Statement |
07/20/2015 |
|
|
f33126c5-d7c4-43e2-8e36-4ae3f0703d97 |
Sends the next element of a collection to a For Each...Next
statement.
Yield expression
Term | Definition |
---|---|
expression |
Required. An expression that is implicitly convertible to the type of the iterator function or Get accessor that contains the Yield statement. |
The Yield
statement returns one element of a collection at a time. The Yield
statement is included in an iterator function or Get
accessor, which perform custom iterations over a collection.
You consume an iterator function by using a For Each...Next Statement or a LINQ query. Each iteration of the For Each
loop calls the iterator function. When a Yield
statement is reached in the iterator function, expression
is returned, and the current location in code is retained. Execution is restarted from that location the next time that the iterator function is called.
An implicit conversion must exist from the type of expression
in the Yield
statement to the return type of the iterator.
You can use an Exit Function
or Return
statement to end the iteration.
"Yield" is not a reserved word and has special meaning only when it is used in an Iterator
function or Get
accessor.
For more information about iterator functions and Get
accessors, see Iterators.
The declaration of an iterator function or Get
accessor must meet the following requirements:
-
It must include an Iterator modifier.
-
The return type must be xref:System.Collections.IEnumerable, xref:System.Collections.Generic.IEnumerable%601, xref:System.Collections.IEnumerator, or xref:System.Collections.Generic.IEnumerator%601.
-
It cannot have any
ByRef
parameters.
An iterator function cannot occur in an event, instance constructor, static constructor, or static destructor.
An iterator function can be an anonymous function. For more information, see Iterators.
A Yield
statement can be inside a Try
block of a Try...Catch...Finally Statement. A Try
block that has a Yield
statement can have Catch
blocks, and can have a Finally
block.
A Yield
statement cannot be inside a Catch
block or a Finally
block.
If the For Each
body (outside of the iterator function) throws an exception, a Catch
block in the iterator function is not executed, but a Finally
block in the iterator function is executed. A Catch
block inside an iterator function catches only exceptions that occur inside the iterator function.
The following code returns an IEnumerable (Of String)
from an iterator function and then iterates through the elements of the IEnumerable (Of String)
.
Dim elements As IEnumerable(Of String) = MyIteratorFunction()
…
For Each element As String In elements
Next
The call to MyIteratorFunction
doesn't execute the body of the function. Instead the call returns an IEnumerable(Of String)
into the elements
variable.
On an iteration of the For Each
loop, the xref:System.Collections.IEnumerator.MoveNext%2A method is called for elements
. This call executes the body of MyIteratorFunction
until the next Yield
statement is reached. The Yield
statement returns an expression that determines not only the value of the element
variable for consumption by the loop body but also the xref:System.Collections.Generic.IEnumerator%601.Current%2A property of elements, which is an IEnumerable (Of String)
.
On each subsequent iteration of the For Each
loop, the execution of the iterator body continues from where it left off, again stopping when it reaches a Yield
statement. The For Each
loop completes when the end of the iterator function or a Return
or Exit Function
statement is reached.
The following example has a Yield
statement that is inside a For…Next loop. Each iteration of the For Each statement body in Main
creates a call to the Power
iterator function. Each call to the iterator function proceeds to the next execution of the Yield
statement, which occurs during the next iteration of the For…Next
loop.
The return type of the iterator method is xref:System.Collections.Generic.IEnumerable%601, an iterator interface type. When the iterator method is called, it returns an enumerable object that contains the powers of a number.
[!code-vbVbVbalrStatements#98]
The following example demonstrates a Get
accessor that is an iterator. The property declaration includes an Iterator
modifier.
[!code-vbVbVbalrStatements#99]
For additional examples, see Iterators.