Yield (Instrucción) (Visual Basic)Yield Statement (Visual Basic)

Envía el siguiente elemento de una colección a una instrucción For Each...Next.Sends the next element of a collection to a For Each...Next statement.

SintaxisSyntax

Yield expression  

ParámetrosParameters

TérminoTerm DefiniciónDefinition
expression Obligatorio.Required. Una expresión que se pueda convertir implícitamente al tipo de la función de iterador o Get descriptor de acceso que contiene la instrucción Yield.An expression that is implicitly convertible to the type of the iterator function or Get accessor that contains the Yield statement.

ComentariosRemarks

La instrucción Yield devuelve un elemento de una colección a la vez.The Yield statement returns one element of a collection at a time. La instrucción Yield se incluye en una función de iterador o en un descriptor de acceso Get, que realiza iteraciones personalizadas en una colección.The Yield statement is included in an iterator function or Get accessor, which perform custom iterations over a collection.

Utilice una función de iterador mediante un ... Instrucción Next o una consulta LINQ.You consume an iterator function by using a For Each...Next Statement or a LINQ query. Cada iteración del bucle For Each llama a la función de iterador.Each iteration of the For Each loop calls the iterator function. Cuando se alcanza una instrucción Yield en la función de iterador, se devuelve expression y se conserva la ubicación actual en el código.When a Yield statement is reached in the iterator function, expression is returned, and the current location in code is retained. La ejecución se reinicia desde esa ubicación la próxima vez que se llama a la función del iterador.Execution is restarted from that location the next time that the iterator function is called.

Debe existir una conversión implícita del tipo de expression de la instrucción Yield al tipo de valor devuelto del iterador.An implicit conversion must exist from the type of expression in the Yield statement to the return type of the iterator.

Puede usar una instrucción Exit Function o Return para finalizar la iteración.You can use an Exit Function or Return statement to end the iteration.

"Yield" no es una palabra reservada y tiene un significado especial solo cuando se utiliza en una función de Iterator o un descriptor de acceso Get."Yield" is not a reserved word and has special meaning only when it is used in an Iterator function or Get accessor.

Para obtener más información sobre las funciones de iterador y los descriptores de acceso Get, vea iteradores.For more information about iterator functions and Get accessors, see Iterators.

Funciones de iterador y obtener descriptores de accesoIterator Functions and Get Accessors

La declaración de una función de iterador o Get descriptor de acceso debe cumplir los siguientes requisitos:The declaration of an iterator function or Get accessor must meet the following requirements:

Una función de iterador no puede aparecer en un evento, un constructor de instancia, un constructor estático o un destructor estático.An iterator function cannot occur in an event, instance constructor, static constructor, or static destructor.

Una función de iterador puede ser una función anónima.An iterator function can be an anonymous function. Para obtener más información, consulta Iteradores.For more information, see Iterators.

Control de excepcionesException Handling

Una instrucción Yield puede estar dentro de un bloque Try de una instrucción try... Detectar... Finally.A Yield statement can be inside a Try block of a Try...Catch...Finally Statement. Un bloque Try que tiene una instrucción Yield puede tener bloques Catch y puede tener un bloque Finally.A Try block that has a Yield statement can have Catch blocks, and can have a Finally block.

Una instrucción Yield no puede estar dentro de un bloque de Catch o un bloque Finally.A Yield statement cannot be inside a Catch block or a Finally block.

Si el cuerpo de For Each (fuera de la función de iterador) produce una excepción, no se ejecuta un bloque de Catch en la función de iterador, pero se ejecuta un bloque de Finally en la función de iterador.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. Un bloque Catch dentro de una función de iterador solo detecta las excepciones que se producen dentro de la función de iterador.A Catch block inside an iterator function catches only exceptions that occur inside the iterator function.

Implementación técnicaTechnical Implementation

El código siguiente devuelve un IEnumerable (Of String) de una función de iterador y, a continuación, recorre en iteración los elementos de la 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  

La llamada a MyIteratorFunction no ejecuta el cuerpo de la función.The call to MyIteratorFunction doesn't execute the body of the function. En su lugar, la llamada devuelve un valor IEnumerable(Of String) en la variable elements.Instead the call returns an IEnumerable(Of String) into the elements variable.

En una iteración del bucle For Each, se llama al método MoveNext para elements.On an iteration of the For Each loop, the MoveNext method is called for elements. Esta llamada ejecuta el cuerpo de MyIteratorFunction hasta que se alcanza la siguiente instrucción Yield.This call executes the body of MyIteratorFunction until the next Yield statement is reached. La instrucción Yield devuelve una expresión que determina no solo el valor de la variable element para su consumo por parte del cuerpo del bucle, sino también la propiedad Current de los elementos, que es una 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).

En cada iteración subsiguiente del bucle For Each, la ejecución del cuerpo del iterador continúa desde donde se dejó, deteniéndose de nuevo al alcanzar una instrucción 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. El bucle de For Each se completa cuando se alcanza el final de la función de iterador o una instrucción Return o Exit Function.The For Each loop completes when the end of the iterator function or a Return or Exit Function statement is reached.

EjemploExample

El ejemplo siguiente tiene una instrucción Yield que está dentro de un ... Siguiente bucle.The following example has a Yield statement that is inside a For…Next loop. Cada iteración del cuerpo de la instrucción for each en Main crea una llamada a la función de iterador Power.Each iteration of the For Each statement body in Main creates a call to the Power iterator function. Cada llamada a la función de iterador prosigue con la siguiente ejecución de la instrucción Yield, que se produce durante la siguiente iteración del bucle 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.

El tipo de valor devuelto del método iterador es IEnumerable<T>, un tipo de interfaz de iterador.The return type of the iterator method is IEnumerable<T>, an iterator interface type. Cuando se llama al método iterador, este devuelve un objeto enumerable que contiene las potencias de un número.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

EjemploExample

En el ejemplo siguiente se muestra un descriptor de acceso Get que es un iterador.The following example demonstrates a Get accessor that is an iterator. La declaración de propiedad incluye un modificador 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

Para obtener más ejemplos, vea iteradores.For additional examples, see Iterators.

Vea tambiénSee also