Yield 陳述式 (Visual Basic)

發行項
05/22/2023

將集合的下一個元素傳送至 For Each...Next 陳述式。

語法

Yield expression

參數

詞彙	定義
`expression`	必要。可隱含轉換為包含 `Yield` 陳述式之迭代器函式或 `Get` 存取子之類型的運算式。

備註

Yield 陳述式一次會傳回集合的一個元素。 Yield 陳述式包括於迭代器函式或 Get 存取子中，其會在集合上執行自訂的反覆運算。

您可以使用 For Each...Next 陳述式或 LINQ 查詢來取用迭代器函式。 For Each 迴圈的每次反覆運算都會呼叫迭代器函式。當迭代器函式中到達 Yield 陳述式時，就會傳回 expression，並保留程式碼中目前的位置。下一次呼叫 Iterator 函式時，便會從這個位置重新開始執行。

必須存在從 Yield 陳述式中的 expression 類型轉換為迭代器之傳回類型的隱含轉換。

您可以使用 Exit Function 或 Return 陳述式來結束反覆運算。

"Yield" 不是保留字，且只有在 Iterator 函式或 Get 存取子中使用時才具有特殊意義。

如需迭代器函式和 Get 存取子的詳細資訊，請參閱迭代器。

迭代器函式和 Get 存取子

迭代器函式或 Get 存取子的宣告必須符合下列需求：

其必須包括迭代器修飾元。
傳回類型必須是 IEnumerable、IEnumerable<T>、IEnumerator 或 IEnumerator<T>。
其不能具有任何 ByRef 參數。

迭代器函式不能出現在事件、執行個體建構函式、靜態建構函式或靜態解構函式中。

迭代器函式可以是匿名函式。如需詳細資訊，請參閱 Iterator。

例外狀況處理

Yield 陳述式可以位於 Try...Catch...Finally 陳述式的 Try 區塊內。具有 Yield 陳述式的 Try 區塊可以有 Catch 區塊，也可以有 Finally 區塊。

Yield 陳述式不能位於 Catch 區塊或 Finally 區塊中。

如果 For Each 主體 (位於迭代器函式外部) 擲回例外狀況，則不會執行迭代器函式中的 Catch 區塊，但會執行迭代器函式中的 Finally 區塊。迭代器函式內的 Catch 區塊僅會攔截迭代器函式內發生的例外狀況。

技術實作

下列程式碼會從迭代器函式傳回 IEnumerable (Of String)，然後逐一查看 IEnumerable (Of String) 的元素。

Dim elements As IEnumerable(Of String) = MyIteratorFunction()  
    …  
For Each element As String In elements  
Next

對 MyIteratorFunction 的呼叫不會執行該函式的主體。呼叫會改為將 IEnumerable(Of String) 傳回至 elements 變數中。

在 For Each 迴圈的反覆項目上，會針對 MoveNext 呼叫 elements 方法。這個呼叫會執行 MyIteratorFunction 的主體，直到下一個 Yield 陳述式為止。 Yield 陳述式所傳回的運算式不僅會判斷迴圈主體所取用之 element 變數的值，也會判斷元素的 Current 屬性，該屬性是 IEnumerable (Of String)。

在 For Each 迴圈的每個後續反覆項目上，迭代器主體會從上次停止的位置繼續執行，並且在到達 Yield 陳述式時再次停止。當迭代器函式結束或到達 Return 或 Exit Function 陳述式時，For Each 迴圈便會完成。

範例 1

下列範例在 For…Next 迴圈內有一個 Yield 陳述式。 Main 中 For Each 陳述式主體的每次反覆運算都會建立對 Power 迭代器函式的呼叫。每次呼叫 Iterator 函式都會執行下一個 Yield 陳述式，這會在 For…Next 迴圈的下一個反覆項目期間發生。

迭代器方法的傳回類型是 IEnumerable<T>，其為迭代器介面類型。呼叫 Iterator 方法時，它會傳回包含數字乘冪的可列舉物件。

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

範例 2

下列範例將示範本身為迭代器的 Get 存取子。屬性宣告包括 Iterator 修飾元。

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

如需其他範例，請參閱迭代器。

另請參閱

陳述式

共用方式為