What does "yield break;" do in C#?

Question

I have seen this syntax in MSDN: yield break, but I don't know what it does. Does anyone know?

Laddie

Yield return eliminates the need for a backing list, that is you don't need to code something like MyList.Add(...) just do yield return .... If you need to break out of the loop prematurely and return the virtual backing list you use yield break; – Stitch

Answer 1

It specifies that an iterator has come to an end. You can think of yield break as a return statement which does not return a value.

For example, if you define a function as an iterator, the body of the function may look like this:

for (int i = 0; i < 5; i++)
{
    yield return i;
}

Console.Out.WriteLine("You will see me");

Note that after the loop has completed all its cycles, the last line gets executed and you will see the message in your console app.

Or like this with yield break:

int i = 0;
while (true)
{
    if (i < 5)
    {
        yield return i;
    }
    else
    {
        // note that i++ will not be executed after this
        yield break;
    }
    i++;
}

Console.Out.WriteLine("Won't see me");

In this case the last statement is never executed because we left the function early.

Amusing

Could it be simply break instead of yield break in your example above? Compiler doesn't complain on that. – Racialism

@Racialism a simple break in this case would stop the loop, but it wouldn't abort the method execution, thus the last line would be executed and the "Won't see me text" would actually be seen. – Cramoisy

@DamirZekić, does the iterator complete all cycles in the case of break? – Richelieu

@Richelieu I'm not sure what exactly you're asking, but after yield break no other code in the iterator is going to be executed, so there would be no further cycles. – Cramoisy

so it's when we don't want to conditionally skip the the remained yield returns... – Index

@deadManN you would use yield break to unconditionally skip remaining yield returns. – Cramoisy

@Damir Zekić Could you also add to your answer why you should prefer yield break over return and what are the differences from the two? – Yuma

@DamirZekić returning null and yield break is not the same. If you return null then you can have a NullReferenceException getting the enumerator of the IEnumerable, while with yield break you don't (there is an instance with no elements). – Yuma

@BrunoCosta Trying to have regular returns in the same method gives a compiler error. Using yield return x alerts the compiler you want this method to be syntactic sugar for creating an Enumerator object. This Enumerator has method MoveNext() and property Current. MoveNext() executes the method until a yield return statement, and turns that value into Current. The next time MoveNext is called, execution continues from there. yield break sets Current to null, signaling the end of this enumerator, so that a foreach (var x in myEnum()) will end. – Drupelet

@Drupelet Instead of seeing yield break as setting Current to nul, I see it as MoveNext returning false. The former returns a null value, the latter doesn't. – Yuma

Note that in order to use this example you should put it inside a function, e.g. public IEnumerable<int> GetEnumerable() { ... } and then use it like foreach (var e in GetEnumerable()) { e.Dump(); }. To try it out, see DotNetFiddle. – Hardshell

Answer 2

Ends an iterator block (e.g. says there are no more elements in the IEnumerable).

Tetherball

with [+1] -- although academically there are no iterators in .NET. only enumerators (one direction, forward.) – Vaientina

@Shaun Wilson, but with yield keyword you can iterate collection in both directions, moreover you can take every next element of collection not in a row – Aloft

@Aloft you can iterate collection in any fashion and you don't need yield to do it. i'm not saying you're wrong, i see what you're suggesting; but, academically there are no iterators in .NET, only enumerators (one direction, forward) -- unlike stdc++ there is no "generic iterator framework" defined in the CTS/CLR. LINQ helps close the gap with extension methods that utilize yield return and also callback methods, but they are first-class extension methods, not first-class iterators. the resulting IEnumerable can't itself iterate in any direction other than forward wrt the caller. – Vaientina

Answer 3

Tells the iterator that it's reached the end.

As an example:

public interface INode
{
    IEnumerable<Node> GetChildren();
}

public class NodeWithTenChildren : INode
{
    private Node[] m_children = new Node[10];

    public IEnumerable<Node> GetChildren()
    {
        for( int n = 0; n < 10; ++n )
        {
            yield return m_children[ n ];
        }
    }
}

public class NodeWithNoChildren : INode
{
    public IEnumerable<Node> GetChildren()
    {
        yield break;
    }
}

Positivism

Answer 4

yield basically makes an IEnumerable<T> method behave similarly to a cooperatively (as opposed to preemptively) scheduled thread.

yield return is like a thread calling a "schedule" or "sleep" function to give up control of the CPU. Just like a thread, the IEnumerable<T> method regains controls at the point immediately afterward, with all local variables having the same values as they had before control was given up.

yield break is like a thread reaching the end of its function and terminating.

People talk about a "state machine", but a state machine is all a "thread" really is. A thread has some state (I.e. values of local variables), and each time it is scheduled it takes some action(s) in order to reach a new state. The key point about yield is that, unlike the operating system threads we're used to, the code that uses it is frozen in time until the iteration is manually advanced or terminated.

Mohammadmohammed

Answer 5

yield break is just a way of saying return for the last time and don't return any value

e.g

// returns 1,2,3,4,5
IEnumerable<int> CountToFive()
{
    yield return 1;
    yield return 2;
    yield return 3;
    yield return 4;
    yield return 5;
    yield break;
    yield return 6;
    yield return 7;
    yield return 8;
    yield return 9;
 }

Hydrant

Answer 6

The yield break statement causes the enumeration to stop. In effect, yield break completes the enumeration without returning any additional items.

Consider that there are actually two ways that an iterator method could stop iterating. In one case, the logic of the method could naturally exit the method after returning all the items. Here is an example:

IEnumerable<uint> FindPrimes(uint startAt, uint maxCount)
{
    for (var i = 0UL; i < maxCount; i++)
    {
        startAt = NextPrime(startAt);
        yield return startAt;
    }

    Debug.WriteLine("All the primes were found.");
}

In the above example, the iterator method will naturally stop executing once maxCount primes have been found.

The yield break statement is another way for the iterator to cease enumerating. It is a way to break out of the enumeration early. Here is the same method as above. This time, the method has a limit on the amount of time that the method can execute.

IEnumerable<uint> FindPrimes(uint startAt, uint maxCount, int maxMinutes)
{
    var sw = System.Diagnostics.Stopwatch.StartNew();
    for (var i = 0UL; i < maxCount; i++)
    {
        startAt = NextPrime(startAt);
        yield return startAt;

        if (sw.Elapsed.TotalMinutes > maxMinutes)
            yield break;
    }

    Debug.WriteLine("All the primes were found.");
}

Notice the call to yield break. In effect, it is exiting the enumeration early.

Notice too that the yield break works differently than just a plain break. In the above example, yield break exits the method without making the call to Debug.WriteLine(..).

Incardinate

Answer 7

Here http://www.alteridem.net/2007/08/22/the-yield-statement-in-c/ is very good example:

public static IEnumerable<int> Range( int min, int max )
{
   while ( true )
   {
      if ( min >= max )
      {
         yield break;
      }
      yield return min++;
   }
}

and explanation, that if a yield break statement is hit within a method, execution of that method stops with no return. There are some time situations, when you don't want to give any result, then you can use yield break.

Hattiehatton

Answer 8

Apart from the other good answers, note that yield break does not work like a normal break when in comes to nested loops. Where a break would only stop the current loop but not any outer loop, yield break will stop the whole enumeration:

IEnumerable<int> Iterate() {
  for(int i=0; i<5; i++) {
    yield return i;

    for(int j=0; j<5; j++) {
      if ((i*10 + j) > 30)
        // This will stop the whole enumeration, even if there's
        // an outer "for" loop
        yield break;

      yield return (i*10 + j);
    }
  }
}

Console.WriteLine(string.Join(", ", Iterate().Select(i => i.ToString())));
// 0, 0, 1, 2, 3, 4, 1, 10, 11, 12, 13, 14, 2, 20, 21, 22, 23, 24, 3, 30

Bengaline

Answer 9

The yield keyword is used together with the return keyword to provide a value to the enumerator object. yield return specifies the value, or values, returned. When the yield return statement is reached, the current location is stored. Execution is restarted from this location the next time the iterator is called.

To explain the meaning using an example:

    public IEnumerable<int> SampleNumbers()
    {
        int counter = 0;
        yield return counter;

        counter = counter + 2;

        yield return counter;

        counter = counter + 3;

        yield return counter ;
    }

Values returned when this is iterated are: 0, 2, 5.

It’s important to note that counter variable in this example is a local variable. After the second iteration which returns the value of 2, third iteration starts from where it left before, while preserving the previous value of local variable named counter which was 2.

Bel

You didn't explain what yield break does – Slowly

I don't think yield return actually supports returning multiple values. Maybe that isn't what you actually meant, but that's how I read it. – Nombril

Sam -- the SampleNumbers method with multiple yield return statements does in fact work, the value of the iterator is returned immediately and execution is resumed when the next value is requested. I have seen people end a method like this with "yield break", but its unnecessary. Hitting the end of the method also ends the iterator – Halvorson

the reason this is a poor example for yield break is that it does not contain an language-level enumerator such as a foreach -- when using an enumerator the yield break provides real value. this example looks like an unrolled loop. you will almost never see this code in the real world (we can all think of some edge cases, sure) also, there is no "iterator" here. the "iterator block" cannot extend beyond the method as a matter of language specification. what is actually being returned is an "enumerable", see also: #742997 – Vaientina