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 ステートメントを含む iterator 関数または Get アクセサーの型に暗黙的に変換可能な式。An expression that is implicitly convertible to the type of the iterator function or Get accessor that contains the Yield statement.

RemarksRemarks

Yield ステートメントでは、コレクションの要素を一度に 1 つずつ返します。The Yield statement returns one element of a collection at a time. Yield ステートメントは、コレクションに対してカスタムの反復を実行する iterator 関数または Get アクセサーに含まれます。The Yield statement is included in an iterator function or Get accessor, which perform custom iterations over a collection.

iterator 関数を使用するには、For Each...Next ステートメントまたは LINQ クエリを使用します。You consume an iterator function by using a For Each...Next Statement or a LINQ query. For Each ループの各反復は、iterator 関数を呼び出します。Each iteration of the For Each loop calls the iterator function. Yield ステートメントが iterator 関数に到達すると、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 の型から、iterator の戻り値の型への暗黙的な変換が存在する必要があります。An implicit conversion must exist from the type of expression in the Yield statement to the return type of the iterator.

Exit Function または Return ステートメントを使用すると、反復を終了できます。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

iterator 関数または Get アクセサーの宣言では、次の要件を満たしている必要があります。The declaration of an iterator function or Get accessor must meet the following requirements:

iterator 関数を、イベント、インスタンス コンストラクター、静的コンストラクター、静的デストラクターで指定することはできません。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

Yield ステートメントは Try...Catch...Finally ステートメントTry ブロック内に指定できます。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.

Yield ステートメントを Catch ブロックや Finally ブロックに記述することはできません。A Yield statement cannot be inside a Catch block or a Finally block.

(iterator 関数の外部の) For Each 本体で例外がスローされた場合、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  

MyIteratorFunction への呼び出しでは、関数の本体は実行されません。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. Yield ステートメントによって、ループ本体で使用するための element 変数の値だけでなく、IEnumerable (Of String) である要素の Current プロパティも判断する式が返されます。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. iterator 関数または Return または Exit 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

次の例では、For…Next ループ内に Yield ステートメントが含まれます。The following example has a Yield statement that is inside a For…Next loop. Main 内の For Each ステートメント本体の各反復処理では、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.

Iterator メソッドの戻り値の型は、反復子インターフェイス型の 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