Tipos comuns de coleções

Tip

Este artigo faz parte da secção Fundamentos para programadores que já conhecem pelo menos uma linguagem de programação e estão a aprender C#. Se és novo na programação, começa primeiro pelos tutoriais para começar . Para mais informações sobre coleções, consulte Coleções na referência da linguagem. Para mais informações sobre arrays, consulte O tipo de referência de array na referência da linguagem. Para mais informações sobre expressões de coleção, consulte Expressões de coleção (Literais de coleção) na referência da linguagem.

Vem de outra língua? Os arrays C# são coleções ordenadas de tamanho fixo, como arrays em Java ou C++. List<T> é a sequência extensível do dia a dia, como o ArrayList do Java, os arrays do JavaScript e as listas do Python. Dictionary<TKey,TValue> Armazena valores por chave, como mapas ou dicionários em muitas línguas.

Uma coleção é um objeto que armazena múltiplos valores relacionados. Cada valor numa coleção é um elemento. Escolha um array quando o conjunto estiver fixo, como os nomes de estado que o seu rastreador de itens de trabalho usa sempre. Escolhe uma List<T> quando os itens vão e vêm, como um backlog que ganha novo trabalho e remove itens concluídos. Escolhe a Dictionary<TKey,TValue> quando procurares valores por uma chave, como encontrar um item de trabalho por ID ou uma definição por nome. A secção seguinte transforma esses exemplos num modelo de decisão rápida.

Escolha uma forma de coleção

Escolha a coleção que corresponda à forma como o seu código usa os dados. Uma sequência armazena os elementos por ordem para que possas alcançá-los por posição. Use um array, que é representado por Array, quando souber o número de posições que a sequência precisa. O comprimento de um array não pode mudar depois de o criar, mas pode substituir o elemento armazenado numa posição existente. Usa List<T> quando precisares de uma sequência que possa adicionar ou remover elementos. Um dicionário armazena valores que alcanças por chave em vez de por posição. Utilize Dictionary<TKey,TValue> quando cada elemento tem uma chave de consulta, como um nome, ID ou código. Os exemplos usam uma expressão de coleção, que cria uma coleção a partir de expressões entre parênteses retos. A secção Criar coleções com expressões de coleções explica essa sintaxe com mais detalhe.

string[] sprintPlan = ["design", "code", "test"];
List<string> backlog = ["design", "code"];
Dictionary<string, int> priorities = new()
{
    ["docs"] = 2,
    ["tests"] = 1
};

backlog.Add("test");

Console.WriteLine($"Array: {string.Join(", ", sprintPlan)}");
Console.WriteLine($"List count: {backlog.Count}");
Console.WriteLine($"Priority for docs: {priorities["docs"]}");
// This example produces the following output:
//
//    Array: design, code, test
//    List count: 3
//    Priority for docs: 2
//

List<T> e Dictionary<TKey,TValue> são tipos genéricos. Um tipo genérico usa um argumento de tipo, como string ou int, para indicar que tipo de valores armazena. Os genéricos permitem reutilizar a mesma forma de coleção, como uma lista ou dicionário, com diferentes tipos de elementos, como string, int, ou um tipo personalizado. Também oferecem segurança de tipos: o compilador garante que cada elemento é o tipo declarado, por isso não precisas de casts nem podes armazenar acidentalmente o tipo errado. Para mais informações sobre tipos genéricos, consulte Tipos e métodos genéricos nos fundamentos.

Armazenar dados de tamanho fixo em arrays

Um array é uma coleção ordenada com comprimento fixo. Acede-se a um elemento do array pelo seu índice, que é a sua posição baseada em zero no array. Índice 0 é o primeiro elemento, índice 1 é o segundo elemento, e assim sucessivamente.

string[] stages = ["design", "code", "test", "review"];

Console.WriteLine($"First: {stages[0]}");
Console.WriteLine($"test index: {Array.IndexOf(stages, "test")}");
// This example produces the following output:
//
//    First: design
//    test index: 2
//

Usa foreach quando quiseres ler cada elemento por ordem. Use um índice quando a posição importa, como quando precisa do primeiro elemento, do último elemento ou da posição devolvida por Array.IndexOf.

O comprimento de um array é fixo, mas os elementos desse array podem mudar. Atribuir um novo valor a um índice existente quando a posição se mantém igual mas o valor armazenado precisa de ser atualizado:

string[] stages = ["design", "code", "test"];

stages[0] = "plan";

Console.WriteLine(string.Join(", ", stages));
Console.WriteLine($"Length: {stages.Length}");
// This example produces the following output:
//
//    plan, code, test
//    Length: 3
//

Fazer crescer e encolher uma sequência com List<T>

A List<T> armazena os elementos por ordem e pode crescer ou diminuir à medida que o programa corre. Use Add para adicionar um elemento, Remove remover um elemento correspondente, Contains testar se um elemento existe e IndexOf encontrar a posição de um elemento. Use o indexador de listas para substituir o valor numa posição existente.

List<string> workItems = ["design", "code", "test"];

workItems.Add("review");
workItems.Remove("code");
workItems[1] = "verify";

Console.WriteLine(string.Join(", ", workItems));
Console.WriteLine($"Has review: {workItems.Contains("review")}");
Console.WriteLine($"Index of verify: {workItems.IndexOf("verify")}");
// This example produces the following output:
//
//    design, verify, review
//    Has review: True
//    Index of verify: 1
//

A List<T> mantém os restantes elementos em ordem quando adicionas ou removes itens. Quando removes um elemento, os elementos posteriores passam para índices mais baixos.

Use-se Insert para adicionar um elemento numa posição específica, InsertRange para adicionar vários elementos numa posição, e RemoveAt para remover um elemento por índice:

List<string> workItems = ["design", "test"];

workItems.Insert(1, "code");
Console.WriteLine($"Insert middle: {string.Join(", ", workItems)}");

workItems.Insert(0, "plan");
Console.WriteLine($"Insert front: {string.Join(", ", workItems)}");

workItems.InsertRange(workItems.Count, ["review", "deploy"]);
Console.WriteLine($"Insert range at end: {string.Join(", ", workItems)}");

workItems.RemoveAt(workItems.Count - 1);
Console.WriteLine($"Remove end: {string.Join(", ", workItems)}");

workItems.RemoveAt(2);
Console.WriteLine($"Remove middle: {string.Join(", ", workItems)}");

workItems.RemoveAt(0);
Console.WriteLine($"Remove front: {string.Join(", ", workItems)}");
// This example produces the following output:
//
//    Insert middle: design, code, test
//    Insert front: plan, design, code, test
//    Insert range at end: plan, design, code, test, review, deploy
//    Remove end: plan, design, code, test, review
//    Remove middle: plan, design, test, review
//    Remove front: design, test, review
//

Adicionar ou remover no final de um List<T> é rápido. Somar com Add é uma operação O(1) em média, e remover o último elemento com RemoveAt é O(1). Inserir ou remover na frente ou no meio é O(n) porque cada elemento posterior muda para um novo índice. Se o seu código insere ou remove frequentemente no início, uma List<T> pode ser a estrutura de coleção errada.

Tip

A notação Big-O descreve como o trabalho cresce à medida que o tamanho da coleção, n, cresce. O(1), pronunciado "ordem um", significa que a operação exige aproximadamente a mesma quantidade de trabalho, independentemente do número de elementos que a coleção contenha. O(n), pronunciado "ordem n", significa que o trabalho aumenta aproximadamente em proporção ao número de elementos na coleção.

Associe um valor a uma chave com Dictionary<TKey,TValue>

A Dictionary<TKey,TValue> armazena pares chave/valor. Um par chave/valor é uma chave e o valor associado a essa chave; .NET representa um par com KeyValuePair<TKey,TValue>. Use o indexador do dicionário para adicionar ou atualizar um valor por chave, e use TryGetValue quando a chave possa não existir.

Dictionary<string, int> priorities = new()
{
    ["docs"] = 2,
    ["tests"] = 1
};

priorities["review"] = 3;
priorities.Remove("review");

if (priorities.TryGetValue("docs", out int docsPriority))
{
    Console.WriteLine($"docs priority: {docsPriority}");
}
else
{
    Console.WriteLine("docs missing");
}

if (priorities.TryGetValue("deploy", out int deployPriority))
{
    Console.WriteLine($"deploy priority: {deployPriority}");
}
else
{
    Console.WriteLine("deploy missing");
}

Console.WriteLine($"count: {priorities.Count}");
// This example produces the following output:
//
//    docs priority: 2
//    deploy missing
//    count: 2
//

Um indexador permite-lhe usar a sintaxe de parênteses retos para aceder a um valor de um objeto. O indexador de dicionário é útil quando a chave tem de existir ou quando está a atribuir um valor. TryGetValue verifica se uma chave existe e dá-te o valor quando existe. Para mais informações sobre o operador indexador, consulte Operadores de acesso membro na referência da linguagem.

Também pode alterar o valor associado a uma chave que já existe. Atribua através do indexador para adicionar uma chave ou substituir o valor de uma chave existente. Se a substituição depender do valor atual, leia primeiro o valor e depois atribua o novo valor:

Dictionary<string, int> priorities = new()
{
    ["docs"] = 2,
    ["tests"] = 1
};

priorities["docs"] = 1;

if (priorities.TryGetValue("tests", out int testsPriority))
{
    priorities["tests"] = testsPriority + 1;
}

priorities["deploy"] = 3;

Console.WriteLine($"docs priority: {priorities["docs"]}");
Console.WriteLine($"tests priority: {priorities["tests"]}");
Console.WriteLine($"deploy priority: {priorities["deploy"]}");
// This example produces the following output:
//
//    docs priority: 1
//    tests priority: 2
//    deploy priority: 3
//

Criar coleções com expressões de coleções

Uma expressão de coleção cria uma coleção a partir de expressões entre colchetes. As expressões de coleção podem criar arrays, listas e outros tipos de coleções. Um elemento spread copia os elementos de outra coleção para a nova coleção.

string[] planned = ["design", "code"];
// The spread element .. planned copies each element from planned.
string[] upcoming = [.. planned, "test"];
List<string> blocked = ["docs"];

Console.WriteLine($"Upcoming: {string.Join(", ", upcoming)}");
Console.WriteLine($"Blocked: {string.Join(", ", blocked)}");
// This example produces the following output:
//
//    Upcoming: design, code, test
//    Blocked: docs
//

As expressões de coleção mantêm a inicialização concisa. Uma expressão de coleção não tem um tipo próprio. O compilador converte a expressão na forma de coleção que o contexto exige. A variável ou parâmetro recetor pode transformá-lo num array, num List<T>, ou noutro tipo de coleção suportado.

Ler a partir de posições com índices e intervalos de índices

Os índices respondem "qual elemento individual?" Os intervalos respondem a "qual fatia contígua?" Use índices quando o seu código precisa de um elemento e intervalos quando a subseção faz parte dos dados com que está a trabalhar. Arrays e List<T> suportam tanto índices como intervalos.

Um Index pode contar desde o início ou desde o fim de uma sequência. Use o número diretamente para contar desde o início: phases[0] lê o primeiro elemento e phases[1] lê o segundo elemento. Use ^ para contar a partir do fim: phases[^1] lê o último elemento e phases[^2] lê o penúltimo elemento.

Um Range seleciona um segmento com .. (dois pontos finais). O operador de intervalo não é o mesmo que o elemento spread que viste anteriormente nas expressões de coleção, embora ambos usem pontos. Utilize um intervalo a..b quando quiser elementos do índice a até, mas não incluindo, ao índice b. A expressão phases[1..3] cria um novo array que contém os elementos no índice 1 e no índice 2.

Pode omitir um ou ambos os índices de intervalo. Omita o índice inicial quando a fatia começa no início, como em phases[..2] para os dois primeiros elementos. Omita o índice final quando a fatia continua até ao último elemento, como em phases[2..] para os elementos do índice 2 até ao fim. Omita ambos os índices quando quiseres uma cópia de todo o array, como em phases[..]. Um intervalo pode misturar tipos de índice. A expressão phases[1..^1] combina um índice de início e um índice de origem para devolver os elementos intermédios, code e test.

string[] phases = ["design", "code", "test", "deploy"];
List<string> checklist = ["design", "test", "review"];

Console.WriteLine($"Last: {phases[^1]}");
Console.WriteLine($"Middle: {string.Join(", ", phases[1..3])}");
Console.WriteLine($"Last two: {string.Join(", ", phases[^2..])}");
Console.WriteLine($"Without ends: {string.Join(", ", phases[1..^1])}");
Console.WriteLine($"First two: {string.Join(", ", phases[..2])}");
Console.WriteLine($"From third: {string.Join(", ", phases[2..])}");
Console.WriteLine($"All phases: {string.Join(", ", phases[..])}");
Console.WriteLine($"List last: {checklist[^1]}");
Console.WriteLine($"List first two: {string.Join(", ", checklist[0..2])}");
// This example produces the following output:
//
//    Last: deploy
//    Middle: code, test
//    Last two: test, deploy
//    Without ends: code, test
//    First two: design, code
//    From third: test, deploy
//    All phases: design, code, test, deploy
//    List last: review
//    List first two: design, test
//

Para mais informações sobre índices e intervalos, consulte Explorar intervalos de dados usando índices e intervalos nos tutoriais.

Ver também