Docs executáveis de C#: Laço foreach

Q: Como percorrer um Dictionary com foreach em C#?

Cada elemento é um KeyValuePair : foreach (var pair in prices) Console.WriteLine($"{pair.Key}: {pair.Value}");. No .NET Core 2.0 em diante você pode desconstruí-lo: foreach (var (name, price) in prices). Para percorrer só as chaves ou só os valores, use prices.Keys ou prices.Values.

Q: Como obter o índice em um laço foreach em C#?

O foreach não tem índice próprio. Mantenha um contador (int i = 0; antes do laço, i++ no fim do corpo), ou projete cada elemento com seu índice usando LINQ: foreach (var item in names.Select((name, index) => new { name, index })). Se você precisa do índice para escrever de volta ou comparar vizinhos, um laço for é a melhor escolha.

Q: O que significa "Collection was modified; enumeration operation may not execute"?

Você adicionou ou removeu itens de uma List, um Dictionary ou outra coleção enquanto um foreach a percorria. O enumerador detecta a mudança e lança InvalidOperationException no passo seguinte. Percorra uma cópia (foreach (var x in list.ToList())), junte as mudanças e aplique depois do laço, use list.RemoveAll(...), ou use um laço for de trás para frente.

Q: Por que não posso atribuir à variável do foreach em C#?

A variável de iteração é somente leitura: name = name.Trim(); dentro de foreach (string name in names) é o erro CS1656. Atribuir a ela também não mudaria a coleção. Para substituir elementos, use um laço for com índice, ou monte uma nova coleção com Select. Mudar uma propriedade de um objeto de classe (order.Status = ...) é permitido.

Q: Dá para sair de um laço foreach com break em C#?

Sim. break encerra o laço imediatamente e continue pula para o próximo elemento, exatamente como em for e while. return sai do método inteiro. O método List .ForEach é diferente: o corpo dele é uma lambda, então break e continue não estão disponíveis ali.

O foreach executa o corpo uma vez para cada elemento de uma coleção, em ordem, sem índice para administrar:

using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        string[] players = { "Ava", "Noah", "Mia" };
        foreach (string player in players)
        {
            Console.WriteLine($"Welcome, {player}");
        }

        var scores = new List<int> { 72, 88, 95 };
        int total = 0;
        foreach (int score in scores)
        {
            total += score;
        }
        Console.WriteLine($"Total: {total}");

        foreach (char c in "C#7")
        {
            Console.Write($"[{c}]");
        }
        Console.WriteLine();
    }
}

Saída:

Welcome, Ava
Welcome, Noah
Welcome, Mia
Total: 255
[C][#][7]

O laço funciona do mesmo jeito em um array, uma List<T>, uma string (tipo de elemento char), um HashSet<T>, uma consulta LINQ ou qualquer outra sequência. O tipo declarado pode ser var, o que é comum quando o tipo do elemento é longo: foreach (var order in pendingOrders).

O que o foreach faz por trás

O foreach pede um enumerador à coleção e o percorre. Para uma List<int>, o compilador transforma o laço mais ou menos nisto:

List<int>.Enumerator e = scores.GetEnumerator();
try
{
    while (e.MoveNext())
    {
        int score = e.Current;
        // loop body
    }
}
finally
{
    e.Dispose();
}

Daí vêm três consequências. Qualquer tipo com um método público GetEnumerator() funciona, e normalmente ele vem da implementação de IEnumerable<T>. O enumerador é descartado mesmo quando o corpo lança uma exceção ou executa break. E a variável do elemento é uma cópia nova de e.Current a cada passada, e é por isso que atribuir a ela não muda a coleção.

Um tipo sem GetEnumerator não pode ser usado:

error CS1579: foreach statement cannot operate on variables of type 'Order' because 'Order' does not contain a public instance or extension definition for 'GetEnumerator'

Implemente IEnumerable<T> no tipo, ou percorra a coleção que ele contém (order.Lines em vez de order). Você pode escrever suas próprias sequências com yield return, assunto da página de IEnumerable e yield.

Percorrendo um Dictionary

Os elementos de um dicionário são valores KeyValuePair<TKey, TValue> com as propriedades Key e Value:

using System;
using System.Collections.Generic;
using System.Linq;

class Program
{
    static void Main()
    {
        var stock = new Dictionary<string, int>
        {
            ["apples"] = 12,
            ["pears"] = 0,
            ["kiwis"] = 30,
        };

        foreach (KeyValuePair<string, int> item in stock)
        {
            Console.WriteLine($"{item.Key}: {item.Value}");
        }

        foreach (string fruit in stock.Keys)
        {
            Console.Write($"<{fruit}>");
        }
        Console.WriteLine();

        Console.WriteLine($"Units in stock: {stock.Values.Sum()}");

        foreach (var item in stock.OrderByDescending(p => p.Value))
        {
            Console.WriteLine($"{item.Value,3} {item.Key}");
        }
    }
}

Saída:

apples: 12
pears: 0
kiwis: 30
<apples><pears><kiwis>
Units in stock: 42
 30 kiwis
 12 apples
  0 pears

Um Dictionary não garante nenhuma ordem de enumeração. Na prática ele segue a ordem de inserção até você remover entradas, mas código que depende da ordem deve ordenar explicitamente, como o último laço faz com OrderByDescending, ou usar SortedDictionary.

No .NET Core 2.0 em diante (e em todo .NET moderno), KeyValuePair tem um método Deconstruct, então o par pode ser separado em duas variáveis direto no cabeçalho do laço:

// modern .NET: KeyValuePair deconstruction
foreach (var (fruit, count) in stock)
{
    Console.WriteLine($"{fruit}: {count}");
}

Essa é a forma mais curta e a que você vai ver no código atual. Ela não compila no .NET Framework, onde KeyValuePair não tem Deconstruct; lá, use item.Key e item.Value.

Obtendo o índice

O foreach não tem índice próprio. As duas formas usuais de obter um são um contador que você mantém, ou a sobrecarga de Select do LINQ que passa o índice junto com cada elemento:

using System;
using System.Linq;

class Program
{
    static void Main()
    {
        string[] podium = { "Kenji", "Sofia", "Omar" };

        int place = 1;
        foreach (string name in podium)
        {
            Console.WriteLine($"{place}. {name}");
            place++;
        }

        foreach (var entry in podium.Select((name, index) => new { name, index }))
        {
            Console.WriteLine($"index {entry.index}: {entry.name}");
        }
    }
}

Saída:

1. Kenji
2. Sofia
3. Omar
index 0: Kenji
index 1: Sofia
index 2: Omar

O contador é o mais barato e o mais claro. Se você perceber que está usando o índice para ler podium[i - 1] ou para escrever podium[i] = ..., troque para um laço for, que foi feito exatamente para isso.

A variável do laço é somente leitura

Você não pode atribuir à variável de iteração:

foreach (string name in names)
{
    name = name.Trim();
    // error CS1656: Cannot assign to 'name' because it is a 'foreach iteration variable'
}

Mesmo se fosse permitido, só mudaria uma cópia local. Para transformar cada elemento, monte uma nova sequência (names.Select(n => n.Trim()).ToArray()) ou use um laço for que escreve names[i] = names[i].Trim().

O que você pode fazer depende de o elemento ser uma classe ou uma struct. Para uma classe, a variável guarda uma referência, então mudar uma propriedade muda o objeto dentro da coleção:

using System;
using System.Collections.Generic;

class Order
{
    public int Id;
    public string Status;
}

class Program
{
    static void Main()
    {
        var orders = new List<Order>
        {
            new Order { Id = 1, Status = "paid" },
            new Order { Id = 2, Status = "paid" },
        };

        foreach (Order order in orders)
        {
            order.Status = "shipped";
        }

        foreach (Order order in orders)
        {
            Console.WriteLine($"Order {order.Id}: {order.Status}");
        }
    }
}

Saída:

Order 1: shipped
Order 2: shipped

Se Order fosse uma struct, a mesma atribuição falharia com CS1654 (Cannot modify members of 'order' because it is a 'foreach iteration variable'), porque a variável é uma cópia do valor, não uma referência a ele.

Modificando a coleção: InvalidOperationException

Adicionar ou remover elementos de uma List ou de um Dictionary enquanto um foreach a percorre quebra o enumerador. O próximo MoveNext lança InvalidOperationException com a mensagem "Collection was modified; enumeration operation may not execute.":

using System;
using System.Collections.Generic;
using System.Linq;

class Program
{
    static void Main()
    {
        var cart = new List<string> { "milk", "expired yogurt", "bread", "expired ham" };

        try
        {
            foreach (string item in cart)
            {
                if (item.StartsWith("expired"))
                    cart.Remove(item);
            }
        }
        catch (InvalidOperationException e)
        {
            Console.WriteLine($"{e.GetType().Name}: collection was modified");
        }

        cart = new List<string> { "milk", "expired yogurt", "bread", "expired ham" };

        // Fix 1: loop over a copy
        foreach (string item in cart.ToList())
        {
            if (item.StartsWith("expired"))
                cart.Remove(item);
        }
        Console.WriteLine(string.Join(", ", cart));

        // Fix 2: let the collection do it
        var cart2 = new List<string> { "milk", "expired yogurt", "bread" };
        cart2.RemoveAll(item => item.StartsWith("expired"));
        Console.WriteLine(string.Join(", ", cart2));
    }
}

Saída:

InvalidOperationException: collection was modified
milk, bread
milk, bread

As soluções, da mais simples para a mais flexível:

RemoveAll(predicate) em uma List<T> remove todas as correspondências de uma vez.
Percorrer uma cópia com ToList() ou ToArray(), e então modificar o original à vontade.
Juntar primeiro, aplicar depois: guarde as chaves a apagar em uma lista separada durante o laço e remova-as em seguida. É o padrão usual para um Dictionary.
Um laço for de trás para frente com RemoveAt(i).

O Dictionary tem uma exceção que vale conhecer. Desde o .NET Core 3.0, sobrescrever o valor de uma chave existente (stock[key] = 0) ou remover entradas durante um foreach sobre ele não lança mais exceção, mas adicionar uma chave nova ainda lança. No .NET Framework as três lançam, então juntar as chaves primeiro é a versão que funciona em qualquer lugar.

break, continue e coleções nulas

break e continue se comportam como em qualquer outro laço:

using System;
using System.Collections.Generic;
using System.Linq;

class Program
{
    static void Main()
    {
        int[] readings = { 21, -1, 23, 999, 22 };

        foreach (int r in readings)
        {
            if (r < 0) continue;          // skip sensor errors
            if (r == 999) break;          // end-of-data marker
            Console.WriteLine($"reading {r}");
        }

        List<string> tags = null;
        foreach (string tag in tags ?? Enumerable.Empty<string>())
        {
            Console.WriteLine(tag);
        }
        Console.WriteLine("no tags, no crash");
    }
}

Saída:

reading 21
reading 23
no tags, no crash

Percorrer uma coleção null lança NullReferenceException quando GetEnumerator é chamado. ?? Enumerable.Empty<T>() transforma uma sequência que pode ser nula em uma vazia; melhor ainda, retorne coleções vazias em vez de null nos seus próprios métodos.

foreach versus List.ForEach

List<T> tem um método ForEach(Action<T>): names.ForEach(n => Console.WriteLine(n));. Não é a mesma coisa que o laço. O corpo dele é uma lambda, então break, continue e yield não estão disponíveis e return só encerra a chamada do elemento atual. Ele só existe em List<T>, não em arrays nem em outras sequências. Prefira a instrução foreach; use ForEach só para uma ação de uma linha que você já tem como método.

Perguntas frequentes

Como percorrer um Dictionary com foreach em C#?

Cada elemento é um KeyValuePair<TKey, TValue>: foreach (var pair in prices) Console.WriteLine($"{pair.Key}: {pair.Value}");. No .NET Core 2.0 em diante você pode desconstruí-lo: foreach (var (name, price) in prices). Para percorrer só as chaves ou só os valores, use prices.Keys ou prices.Values.

Como obter o índice em um laço foreach em C#?

O foreach não tem índice próprio. Mantenha um contador (int i = 0; antes do laço, i++ no fim do corpo), ou projete cada elemento com seu índice usando LINQ: foreach (var item in names.Select((name, index) => new { name, index })). Se você precisa do índice para escrever de volta ou comparar vizinhos, um laço for é a melhor escolha.

O que significa "Collection was modified; enumeration operation may not execute"?

Você adicionou ou removeu itens de uma List, um Dictionary ou outra coleção enquanto um foreach a percorria. O enumerador detecta a mudança e lança InvalidOperationException no passo seguinte. Percorra uma cópia (foreach (var x in list.ToList())), junte as mudanças e aplique depois do laço, use list.RemoveAll(...), ou use um laço for de trás para frente.

Por que não posso atribuir à variável do foreach em C#?

A variável de iteração é somente leitura: name = name.Trim(); dentro de foreach (string name in names) é o erro CS1656. Atribuir a ela também não mudaria a coleção. Para substituir elementos, use um laço for com índice, ou monte uma nova coleção com Select. Mudar uma propriedade de um objeto de classe (order.Status = ...) é permitido.

Dá para sair de um laço foreach com break em C#?

Sim. break encerra o laço imediatamente e continue pula para o próximo elemento, exatamente como em for e while. return sai do método inteiro. O método List<T>.ForEach é diferente: o corpo dele é uma lambda, então break e continue não estão disponíveis ali.

Conceitos relacionados