Yield 陳述式 (Visual Basic)Yield Statement (Visual Basic)

將集合的下一個元素傳送至 For Each...Next 語句。Sends the next element of a collection to a For Each...Next statement.

語法Syntax

Yield expression  

參數Parameters

詞彙Term 定義Definition
expression 必要項。Required. 運算式,可隱含地轉換成包含 Yield 語句之反覆運算器函數或 Get 存取子的類型。An expression that is implicitly convertible to the type of the iterator function or Get accessor that contains the Yield statement.

備註Remarks

@No__t_0 語句一次會傳回集合的一個元素。The Yield statement returns one element of a collection at a time. @No__t_0 語句會包含在 iterator 函式或 Get 存取子中,這會在集合上執行自訂反復專案。The Yield statement is included in an iterator function or Get accessor, which perform custom iterations over a collection.

您可以使用 For Each 的來取用 iterator 函數 ... 下一個語句或 LINQ 查詢。You consume an iterator function by using a For Each...Next Statement or a LINQ query. @No__t_0 迴圈的每個反復專案都會呼叫 iterator 函數。Each iteration of the For Each loop calls the iterator function. 當反覆運算器函式中到達 Yield 語句時,會傳回 expression,並保留程式碼中的目前位置。When a Yield statement is reached in the iterator function, expression is returned, and the current location in code is retained. 下一次呼叫 Iterator 函式時,便會從這個位置重新開始執行。Execution is restarted from that location the next time that the iterator function is called.

隱含轉換必須存在於 Yield 語句中的 expression 類型,到反覆運算器的傳回型別中。An implicit conversion must exist from the type of expression in the Yield statement to the return type of the iterator.

您可以使用 Exit FunctionReturn 語句來結束反復專案。You can use an Exit Function or Return statement to end the iteration.

"Yield" 不是保留字,只有在 Iterator 函式或 Get 存取子中使用時,才具有特殊意義。"Yield" is not a reserved word and has special meaning only when it is used in an Iterator function or Get accessor.

如需 iterator 函數和 Get 存取子的詳細資訊,請參閱反覆運算器。For more information about iterator functions and Get accessors, see Iterators.

Iterator 函數和 Get 存取子Iterator Functions and Get Accessors

反覆運算器函數或 Get 存取子的宣告必須符合下列需求:The declaration of an iterator function or Get accessor must meet the following requirements:

反覆運算器函式不能出現在事件、實例的函數、靜態的函式或靜態的析構函數中。An iterator function cannot occur in an event, instance constructor, static constructor, or static destructor.

Iterator 函數可以是匿名函式。An iterator function can be an anonymous function. 如需詳細資訊,請參閱迭代器For more information, see Iterators.

例外狀況處理Exception Handling

@No__t_0 語句可以在 Try 的 Try 區塊內 ... Catch 。Finally 語句A Yield statement can be inside a Try block of a Try...Catch...Finally Statement. 具有 Yield 語句的 Try 區塊可以有 Catch 區塊,而且可以有 Finally 區塊。A Try block that has a Yield statement can have Catch blocks, and can have a Finally block.

@No__t_0 語句不能在 Catch 區塊或 Finally 區塊內。A Yield statement cannot be inside a Catch block or a Finally block.

如果 For Each 主體(iterator 函數之外)擲回例外狀況,則不會執行 iterator 函式中的 Catch 區塊,但會執行 iterator 函式中的 Finally 區塊。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. Iterator 函式內的 Catch 區塊只會攔截在 iterator 函式內發生的例外狀況。A Catch block inside an iterator function catches only exceptions that occur inside the iterator function.

技術實作Technical Implementation

下列程式碼會從 iterator 函式傳回 IEnumerable (Of String),然後逐一查看 IEnumerable (Of String) 的元素。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  

@No__t_0 的呼叫不會執行函式的主體。The call to MyIteratorFunction doesn't execute the body of the function. 呼叫會改為將 IEnumerable(Of String) 傳回至 elements 變數中。Instead the call returns an IEnumerable(Of String) into the elements variable.

For Each 迴圈的反覆項目上,會針對 MoveNext 呼叫 elements 方法。On an iteration of the For Each loop, the MoveNext method is called for elements. 這個呼叫會執行 MyIteratorFunction 的主體,直到下一個 Yield 陳述式為止。This call executes the body of MyIteratorFunction until the next Yield statement is reached. @No__t_0 語句傳回的運算式,不僅會判斷迴圈主體所使用之 element 變數的值,也會決定元素的 Current 屬性,這是 IEnumerable (Of String)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 Current property of elements, which is an IEnumerable (Of String).

For Each 迴圈的每個後續反覆項目上,迭代器主體會從上次停止的位置繼續執行,並且在到達 Yield 陳述式時再次停止。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. 當反覆運算器函數或 ReturnExit Function 語句的結尾達到時,For Each 迴圈就會完成。The For Each loop completes when the end of the iterator function or a Return or Exit Function statement is reached.

範例Example

下列範例中的 Yield 語句位於For 。下一個迴圈。The following example has a Yield statement that is inside a For…Next loop. @No__t_1 中個語句主體的每個反復專案都會建立對 Power iterator 函數的呼叫。Each iteration of the For Each statement body in Main creates a call to the Power iterator function. 每次呼叫 Iterator 函式都會執行下一個 Yield 陳述式,這會在 For…Next 迴圈的下一個反覆項目期間發生。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.

反覆運算器方法的傳回型別是 IEnumerable<T>,也就是反覆運算器介面型別。The return type of the iterator method is IEnumerable<T>, an iterator interface type. 呼叫 Iterator 方法時,它會傳回包含數字乘冪的可列舉物件。When the iterator method is called, it returns an enumerable object that contains the powers of a number.

Sub Main()
    For Each number In Power(2, 8)
        Console.Write(number & " ")
    Next
    ' Output: 2 4 8 16 32 64 128 256
    Console.ReadKey()
End Sub

Private Iterator Function Power(
ByVal base As Integer, ByVal highExponent As Integer) _
As System.Collections.Generic.IEnumerable(Of Integer)

    Dim result = 1

    For counter = 1 To highExponent
        result = result * base
        Yield result
    Next
End Function

範例Example

下列範例將示範本身為迭代器的 Get 存取子。The following example demonstrates a Get accessor that is an iterator. 屬性宣告包含 Iterator 的修飾詞。The property declaration includes an Iterator modifier.

Sub Main()
    Dim theGalaxies As New Galaxies
    For Each theGalaxy In theGalaxies.NextGalaxy
        With theGalaxy
            Console.WriteLine(.Name & "  " & .MegaLightYears)
        End With
    Next
    Console.ReadKey()
End Sub

Public Class Galaxies
    Public ReadOnly Iterator Property NextGalaxy _
    As System.Collections.Generic.IEnumerable(Of Galaxy)
        Get
            Yield New Galaxy With {.Name = "Tadpole", .MegaLightYears = 400}
            Yield New Galaxy With {.Name = "Pinwheel", .MegaLightYears = 25}
            Yield New Galaxy With {.Name = "Milky Way", .MegaLightYears = 0}
            Yield New Galaxy With {.Name = "Andromeda", .MegaLightYears = 3}
        End Get
    End Property
End Class

Public Class Galaxy
    Public Property Name As String
    Public Property MegaLightYears As Integer
End Class

如需其他範例,請參閱反覆運算器。For additional examples, see Iterators.

請參閱See also