Skip to content

5. Classes do .NET de uso frequente

Apresentamos aqui algumas classes frequentemente usadas da plataforma .NET: strings, arrays, coleções, arquivos e expressões regulares. Também trataremos do LINQ (Language Integrated Query), que o curso de 2008 omitia, embora já existisse desde o C# 3: ele é hoje a maneira mais comum de manipular coleções em C#. Antes disso, mostraremos como encontrar informações sobre as milhares de classes disponíveis. Este guia é indispensável a qualquer desenvolvedor C#, mesmo os experientes.

Os exemplos deste capítulo, com exceção da aplicação de exemplo no final, são aplicações de arquivo único executadas por [dotnet run file.cs]. Elas estão na pasta [05-classes-dotnet] do código do curso e são executadas na localidade francesa (fr-FR), exceto os exemplos de LINQ e de expressões regulares, que são executados na localidade do inglês americano (en-US).

5.1. Como encontrar ajuda sobre as classes do .NET

O curso de 2008 fornecia uma descrição detalhada, com capturas de tela, da ajuda MSDN instalada com o Visual Studio 2008. Essa ajuda local não está mais disponível: a documentação do .NET agora é online, gratuita e atualizada a cada nova versão.

5.1.1. Documentação online

O ponto de partida é o site learn.microsoft.com da Microsoft. Nele você encontra:

  • a documentação da linguagem C#: https://learn.microsoft.com/en-us/dotnet/csharp/. Ela inclui uma visão geral da linguagem, tutoriais, a referência da linguagem (palavras-chave, operadores, instruções) e uma seção “What’s New” que descreve cada versão do C#;
  • a referência da API do .NET: https://learn.microsoft.com/en-us/dotnet/api/. Ela descreve, namespace por namespace, todas as classes do .NET: seus construtores, propriedades e métodos, com exemplos;
  • o navegador de APIs, na mesma página: uma caixa de pesquisa na qual você pode digitar o nome de uma classe ou de um método ([StringBuilder], [Regex.Match]…). Uma lista suspensa permite selecionar a versão do .NET (aqui, o .NET 10).

A página de uma classe, como System.String, exibe:

  • o namespace da classe e o assembly que a contém;
  • sua declaração, sua classe pai e as interfaces que ela implementa;
  • a lista de seus construtores, propriedades e métodos, cada um com um link para uma página detalhada que mostra suas várias sobrecargas, parâmetros, valores de retorno, possíveis exceções e, muitas vezes, um exemplo;
  • observações sobre seu uso.

As páginas estão disponíveis em francês (tradução automática) e em inglês (texto original, às vezes mais preciso). Você pode alternar entre elas substituindo [en-us] por [fr-fr] na URL. Uma pesquisa em um mecanismo de busca com o nome completo da classe (“System.Text.StringBuilder”) geralmente leva direto à página correta.

5.1.2. Ajuda do editor

O editor de código (Visual Studio, Visual Studio Code com a extensão C# Dev Kit, Rider) fornece ajuda imediata sem precisar sair do código:

  • autocompletar (IntelliSense): depois de digitar [aString.], o editor sugere uma lista das propriedades e métodos do objeto, com um resumo de cada um;
  • Dicas de ferramenta: ao passar o mouse sobre o nome de uma classe, método ou variável, o editor exibe sua declaração e um resumo de sua documentação;
  • Ajuda de parâmetros: ao digitar o parêntese de abertura de uma chamada, o editor exibe as diferentes sobrecargas do método e o papel de cada parâmetro;
  • Ir para a definição (tecla F12): exibe a declaração da classe ou do método. Para uma classe do .NET, o editor exibe as declarações públicas reconstruídas a partir do assembly, junto com seus comentários de documentação;
  • No Visual Studio, pressionar a tecla F1 sobre o nome de uma classe ou método abre a página correspondente na documentação online.

Esses comentários de documentação, visíveis ao passar o mouse sobre um elemento, são os usados para gerar a referência online. Você pode escrever comentários semelhantes em seu próprio código com a sintaxe [/// <summary> ... </summary>] colocada acima de uma classe ou método: o editor os exibirá da mesma maneira.

5.2. Strings

5.2.1. A classe System.String

O tipo C# [string] é um alias da classe [System.String]. Ela tem numerosas propriedades e métodos. Eis alguns deles:

Membro
papel
[public int Length { get; }]
número de caracteres da string
[public char this[int index] { get; }]
Caractere nº [index]: [aString[i]]
[public bool StartsWith(string value)]
retorna [true] se a string começar com [value]
[public bool EndsWith(string value)]
retorna [true] se a string terminar com [value]
[public bool Contains(string value)]
retorna [true] se a string contiver [value]
[public bool Equals(string? value)]
retorna [true] se a string for igual a [value]; equivalente a [aString == value]
[public int IndexOf(string value)]
a primeira ocorrência de [value] na string, ou -1. Outra sobrecarga inicia a busca na posição [startIndex]
[public int IndexOf(char value)]
o mesmo vale para o caractere [value]
[public int LastIndexOf(char value)]
igual a [IndexOf] mas retorna a última posição em vez da primeira
[public string Insert(int startIndex, string value)]
insere a string [value] na string na posição [startIndex]
[public static string Join(string separator, params string[] value)]
método de classe: concatena os elementos de [value], separando-os com [separator]
[public string Replace(char oldChar, char newChar)]
retorna uma cópia da string em que o caractere [oldChar] foi substituído por [newChar]; um método sobrecarregado substitui uma string por outra
[public string[] Split(params char[] separator)]
a string é tratada como uma sequência de campos separados pelos caracteres de [separator]; o resultado é um array desses campos
[public string Substring(int startIndex, int length)]
uma substring de [length] caracteres a partir da posição [startIndex]
[public string ToLower()], [public string ToUpper()]
converte a string em minúsculas, maiúsculas
[public string Trim()]
remove os espaços no início e no fim da string ([TrimStart], [TrimEnd]: em um dos lados apenas)

É importante observar que uma string do tipo [string] é imutável; ela não pode ser modificada depois de criada. Quando um método retorna uma string, essa string é diferente daquela à qual o método foi aplicado. Assim, [s1.Trim()] retorna a string [s2], e [s1] e [s2] são duas strings diferentes: [s1] não mudou.

Uma string [c] pode ser considerada um array de caracteres somente leitura:

  • [c[i]] é o i-ésimo caractere de [c] (o primeiro caractere é o de número 0);
  • [c.Length] é o número de caracteres de [c].

O programa [strings-01.cs] é o seguinte:

// alguns métodos da classe String
string aString = "the bird flies above clouds";
Display("aString=" + aString);
Display("aString.Length=" + aString.Length);
Display("aString[10]=" + aString[10]);
Display("aString.IndexOf(\"flies\")=" + aString.IndexOf("flies"));
Display("aString.IndexOf(\"x\")=" + aString.IndexOf("x"));
Display("aString.LastIndexOf('a')=" + aString.LastIndexOf('a'));
Display("aString.LastIndexOf('x')=" + aString.LastIndexOf('x'));
Display("aString.Substring(4, 7)=" + aString.Substring(4, 7));
Display("aString.ToUpper()=" + aString.ToUpper());
Display("aString.ToLower()=" + aString.ToLower());
Display("aString.Replace('a', 'A')=" + aString.Replace('a', 'A'));
Display("aString.Insert(9, \"never \")=" + aString.Insert(9, "never "));
// divisão da string em palavras (separador: espaços)
string[] fields = aString.Split();
for (int i = 0; i < fields.Length; i++)
{
    Display("fields[" + i + "]=[" + fields[i] + "]");
}
Display("string.Join(\":\", fields)=" + string.Join(":", fields));
Display("\"  abc  \".Trim()=[" + "  abc  ".Trim() + "]");
// a string original não foi modificada
Display("aString=" + aString);

// um método local de exibição
static void Display(string msg)
{
    Console.WriteLine(msg);
}

Resultados:

> dotnet run strings-01.cs
aString=the bird flies above clouds
aString.Length=27
aString[10]=l
aString.IndexOf("flies")=9
aString.IndexOf("x")=-1
aString.LastIndexOf('a')=15
aString.LastIndexOf('x')=-1
aString.Substring(4, 7)=bird fl
aString.ToUpper()=THE BIRD FLIES ABOVE CLOUDS
aString.ToLower()=the bird flies above clouds
aString.Replace('a', 'A')=the bird flies Above clouds
aString.Insert(9, "never ")=the bird never flies above clouds
fields[0]=[the]
fields[1]=[bird]
fields[2]=[flies]
fields[3]=[above]
fields[4]=[clouds]
string.Join(":", fields)=the:bird:flies:above:clouds
"  abc  ".Trim()=[abc]
aString=the bird flies above clouds

Comentários:

  • linha 5: o caractere nº 10, ou seja, o 11º caractere da string;
  • Linhas 7 e 9: uma busca malsucedida retorna -1;
  • linha 10: os 7 caracteres a partir da posição 4;
  • linha 14: uma inserção na posição 9, antes da palavra “flies”;
  • linha 16: [Split] sem parâmetros divide a string nos caracteres de espaço em branco (espaço, tabulação, quebra de linha etc.). O curso de 2008 usava [Split(null)], o que dá no mesmo;
  • linha 21: o método estático [Join] faz o oposto de [Split];
  • Linha 23: todos os métodos anteriores retornavam novas strings: [aString] permaneceu inalterada (linha 21 dos resultados);
  • Linhas 27 a 29: uma função local, como no Capítulo 3.

5.2.2. Os métodos Split e Join

O programa [strings-02.cs] aprofunda a divisão de uma string em campos:

// Split e Join
string line = "one:two::three:";
// divisão com o separador ':'
string[] fields = line.Split(':');
for (int i = 0; i < fields.Length; i++)
{
    Console.WriteLine($"fields[{i}]=[{fields[i]}]");
}
// a operação inversa
Console.WriteLine($"join=[{string.Join(":", fields)}]");

// as opções de Split: remoção de campos vazios
fields = line.Split(':', StringSplitOptions.RemoveEmptyEntries);
Console.WriteLine($"RemoveEmptyEntries : {fields.Length} fields [{string.Join("|", fields)}]");

// vários separadores e remoção dos espaços ao redor dos campos
string person = " dupont , jean ;  45 ";
fields = person.Split([',', ';'], StringSplitOptions.TrimEntries);
Console.WriteLine($"TrimEntries : {fields.Length} fields [{string.Join("|", fields)}]");

// as duas opções combinadas
string list = "  red ,, green ,  , blue ";
fields = list.Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
Console.WriteLine($"both options: {fields.Length} fields [{string.Join("|", fields)}]");

// um separador que é uma string
string text = "apple -> pear -> apricot";
fields = text.Split(" -> ");
Console.WriteLine($"string separator: [{string.Join("|", fields)}]");

// Join aceita qualquer coleção, não apenas strings
int[] numbers = [1, 2, 3, 4];
Console.WriteLine($"Join on integers: {string.Join(" + ", numbers)}");

Resultados:

> dotnet run strings-02.cs
fields[0]=[one]
fields[1]=[two]
fields[2]=[]
fields[3]=[three]
fields[4]=[]
join=[one:two::three:]
RemoveEmptyEntries : 3 fields [one|two|three]
TrimEntries : 3 fields [dupont|jean|45]
both options: 3 fields [red|green|blue]
string separator: [apple|pear|apricot]
Join on integers: 1 + 2 + 3 + 4

Comentários:

  • Linha 4: os campos são separados pelo caractere [:]. Dois caracteres [:] consecutivos, ou um único [:] no final da string, delimitam um campo vazio: isso resulta em 5 campos, 2 dos quais vazios (linhas 4 e 6 dos resultados). [Join] reconstrói a string original;
  • o método [Split] tem numerosas sobrecargas. A versão de 2008, [Split(char[] separator)], agora é escrita como [Split(params char[] separator)]: a palavra-chave [params] permite informar os separadores um a um, [Split(':')] ou [Split(',', ';')], sem criar um array;
  • Linha 13: a enumeração [StringSplitOptions] modifica a divisão em campos. [RemoveEmptyEntries] remove os campos vazios;
  • linha 18: [TrimEntries] (.NET 5) remove os espaços ao redor de cada campo. Os separadores são passados aqui como uma expressão de coleção [',', ';'];
  • linha 23: as duas opções são combinadas por meio do operador [|]. Os espaços são removidos antes da verificação de campos vazios: o campo formado por dois espaços entre duas vírgulas é removido;
  • linha 28: o separador pode ser uma string composta por vários caracteres;
  • linha 33: [Join] aceita uma coleção de elementos de qualquer tipo; cada elemento é convertido em string por meio de seu método [ToString].

5.2.3. Pesquisa e comparação de strings

A comparação de strings é mais sutil do que parece: maiúsculas e minúsculas devem ser distinguidas? Como “éclair” deve ser classificado em relação a “essay”? O programa [strings-03.cs] apresenta os métodos de pesquisa e comparação:

// busca e comparação de strings
string title = "Learning the C# language with .NET";

// Contains, StartsWith, EndsWith: comparação exata por padrão
Console.WriteLine($"Contains(\"language\") : {title.Contains("language")}");
Console.WriteLine($"Contains(\"LANGUAGE\") : {title.Contains("LANGUAGE")}");
Console.WriteLine($"StartsWith(\"Learning\") : {title.StartsWith("Learning")}");
Console.WriteLine($"EndsWith('T') : {title.EndsWith('T')}");

// o modo de comparação é especificado com a enumeração StringComparison
Console.WriteLine($"Contains(\"LANGUAGE\", OrdinalIgnoreCase) : {title.Contains("LANGUAGE", StringComparison.OrdinalIgnoreCase)}");
Console.WriteLine($"StartsWith(\"learning\", OrdinalIgnoreCase) : {title.StartsWith("learning", StringComparison.OrdinalIgnoreCase)}");

// igualdade: o operador == compara o conteúdo das strings
string answer = "YES";
Console.WriteLine($"answer == \"yes\" : {answer == "yes"}");
Console.WriteLine($"string.Equals(answer, \"yes\", OrdinalIgnoreCase) : {string.Equals(answer, "yes", StringComparison.OrdinalIgnoreCase)}");

// ordem alfabética: comparação segundo a cultura ou segundo os códigos dos caracteres
string a = "éclair", b = "essay";
Console.WriteLine($"Compare(\"{a}\", \"{b}\", CurrentCulture) : {string.Compare(a, b, StringComparison.CurrentCulture)}");
Console.WriteLine($"Compare(\"{a}\", \"{b}\", Ordinal) : {string.Compare(a, b, StringComparison.Ordinal)}");

// strings vazias ou em branco
string? empty = null;
string blank = "   ";
Console.WriteLine($"IsNullOrEmpty(null) : {string.IsNullOrEmpty(empty)}");
Console.WriteLine($"IsNullOrEmpty(\"   \") : {string.IsNullOrEmpty(blank)}");
Console.WriteLine($"IsNullOrWhiteSpace(\"   \") : {string.IsNullOrWhiteSpace(blank)}");

// preenchimento (padding)
Console.WriteLine($"[{"abc".PadLeft(8)}] [{"abc".PadRight(8, '.')}] [{new string('-', 8)}]");

Resultados:

> dotnet run strings-03.cs
Contains("language") : True
Contains("LANGUAGE") : False
StartsWith("Learning") : True
EndsWith('T') : True
Contains("LANGUAGE", OrdinalIgnoreCase) : True
StartsWith("learning", OrdinalIgnoreCase) : True
answer == "yes" : False
string.Equals(answer, "yes", OrdinalIgnoreCase) : True
Compare("éclair", "essay", CurrentCulture) : -1
Compare("éclair", "essay", Ordinal) : 132
IsNullOrEmpty(null) : True
IsNullOrEmpty("   ") : False
IsNullOrWhiteSpace("   ") : True
[     abc] [abc.....] [--------]

Comentários:

  • linhas 5–8: [Contains], [StartsWith], e [EndsWith] realizam por padrão uma comparação exata, caractere por caractere: “LANGUAGE” não é encontrado;
  • Linhas 11–12: um parâmetro do tipo [StringComparison] especifica o modo de comparação. Os valores mais úteis são:
    • [Ordinal]: comparação dos códigos dos caracteres;
    • [OrdinalIgnoreCase]: igual à anterior, ignorando a diferença entre maiúsculas e minúsculas;
    • [CurrentCulture], [CurrentCultureIgnoreCase]: comparação de acordo com as regras do idioma da máquina;
    • [InvariantCulture]: comparação baseada em regras independentes da máquina;
  • linha 16: o operador [] compara o conteúdo das strings, assim como o método [Equals]. Essa é uma diferença importante em relação ao Java, em que [] compara referências;
  • linha 17: a forma estática de [Equals] também aceita um [StringComparison]. Essa é a maneira correta de testar uma resposta “yes” digitada no teclado em maiúsculas ou minúsculas;
  • Linhas 21–22: [string.Compare] retorna um inteiro negativo, zero ou positivo, conforme a primeira string venha antes da segunda, seja igual a ela ou venha depois. Em francês, “éclair” vem antes de “essay” (a letra “é” é classificada junto com “e”, linha 10 dos resultados). Na comparação ordinal, “éclair” vem depois de “essay”, porque o código do primeiro caractere, “é” (233), é maior que o do caractere “e” (101): a comparação ordinal retorna aqui a diferença entre os dois códigos, 132. Usaremos a ordem cultural para classificar palavras destinadas a um usuário e a ordem ordinal para comparar identificadores técnicos (nomes de arquivos, chaves etc.);
  • linhas 27–29: dois métodos estáticos para testar uma string ausente ([null]), vazia ou contendo apenas espaços;
  • Linha 32: [PadLeft] e [PadRight] preenchem uma string até um determinado comprimento; o construtor [new string('-', 8)] repete um caractere.

5.2.4. Interpolação e formatos

A interpolação de strings [$"..."] (C# 6) é usada desde o início deste curso. Assim como o método [string.Format], ela aceita uma largura e um formato para cada expressão: [{expression,width:format}]. O programa [strings-04.cs] traz exemplos disso, bem como das strings brutas do C# 11:

// interpolação, formatos e strings brutas
string name = "dupont";
int age = 45;
decimal salary = 2345.678m;
double rate = 0.0525;
DateTime date = new(2026, 10, 3, 14, 5, 9);

// interpolação simples
Console.WriteLine($"{name} is {age} years old");
// {expression,width:format}: width > 0 alinha à direita, < 0 alinha à esquerda
Console.WriteLine($"[{name,10}] [{name,-10}] [{age,5}]");
Console.WriteLine($"[{salary,12:F2}] [{salary,-12:F1}] [{salary:N2}] [{salary:C}]");
Console.WriteLine($"[{rate:P2}] [{age:D5}] [{age:X}] [{1234567:N0}]");
Console.WriteLine($"[{date:dd/MM/yyyy}] [{date:HH:mm:ss}] [{date:dddd d MMMM yyyy}]");
// qualquer expressão, aqui uma expressão condicional entre parênteses
Console.WriteLine($"{name} is {(age >= 18 ? "an adult" : "a minor")}");

// o método string.Format e a notação {n} das versões anteriores do C#
Console.WriteLine(string.Format("{0} is {1} years old and earns {2:F2} euros", name, age, salary));

// uma tabela alinhada
string[] products = ["apple", "pear", "apricot"];
decimal[] prices = [2.5m, 3.15m, 12m];
for (int i = 0; i < products.Length; i++)
{
    Console.WriteLine($"{products[i],-10}|{prices[i],8:F2} €");
}

// string verbatim: \ não é um caractere de escape
string path = @"C:\data\course\infos.txt";
Console.WriteLine(path);

// string bruta (C# 11): delimitada por pelo menos três aspas duplas, em várias linhas
string json = """
    {
      "name": "dupont",
      "path": "C:\data"
    }
    """;
Console.WriteLine(json);
// string bruta interpolada: com $$, as chaves simples permanecem literais
string json2 = $$"""{ "name": "{{name}}", "age": {{age}} }""";
Console.WriteLine(json2);

Resultados:

> dotnet run strings-04.cs
dupont is 45 years old
[    dupont] [dupont    ] [   45]
[     2345,68] [2345,7      ] [2 345,68] [2 345,68 €]
[5,25 %] [00045] [2D] [1 234 567]
[03/10/2026] [14:05:09] [samedi 3 octobre 2026]
dupont is an adult
dupont is 45 years old and earns 2345,68 euros
apple     |    2,50 €
pear      |    3,15 €
apricot   |   12,00 €
C:\data\course\infos.txt
{
  "name": "dupont",
  "path": "C:\data"
}
{ "name": "dupont", "age": 45 }

Comentários:

  • linha 11: uma largura positiva alinha o valor à direita em um campo de 10 caracteres; uma largura negativa o alinha à esquerda;
  • Linhas 12–14: os formatos mais comuns:
formato
Significado
exemplo (fr-FR)
[F2]
número de ponto fixo, 2 casas decimais
2345,68
[N2]
igual ao anterior, com separador de milhares
2 345,68
[C]
valor monetário para a cultura atual
2 345,68 €
[P2]
porcentagem (o valor é multiplicado por 100)
5,25 %
[D5]
inteiro de 5 dígitos ou mais, preenchido com zeros
00045
[X]
inteiro hexadecimal
2D
[dd/MM/yyyy], [HH:mm:ss]
data e hora (MM: mês, mm: minutos)
03/10/2026, 14:05:09
[dddd d MMMM yyyy]
dia e mês por extenso
samedi 3 octobre 2026
  • Os números e as datas são formatados de acordo com a localidade atual, neste caso fr-FR: vírgula decimal, espaço como separador de milhares, nomes de dias e meses em francês;
  • linha 16: uma expressão condicional colocada dentro de uma interpolação deve ser envolvida por parênteses, pois o caractere [:] introduziria ali um formato;
  • linha 19: a notação [{0}], [{1}]… para [string.Format] é a usada no curso de 2008 (e em [Console.WriteLine], que aceita os mesmos parâmetros). Ela ainda é encontrada com frequência; a interpolação é mais legível;
  • linhas 24–26: as larguras permitem exibir os dados em colunas;
  • linha 30: uma string literal [@"..."] não trata [\] como caractere de escape. Isso é útil para caminhos do Windows e expressões regulares;
  • linhas 34–39: uma string bruta (C# 11) é delimitada por pelo menos três aspas. Ela pode ocupar várias linhas e conter aspas e [\] sem escape. A indentação das aspas de fechamento é removida de cada linha: o texto JSON é exibido sem os 4 espaços da margem do código;
  • Linha 42: uma string bruta pode ser interpolada. Com [$$], uma expressão interpolada é escrita entre chaves duplas [{{name}}], e as chaves simples, comuns em um texto como JSON, continuam sendo caracteres comuns.

5.2.5. A classe System.Text.StringBuilder

Mencionamos que os métodos da classe [String] que operam sobre uma string [s1] retornam outra string [s2]. A classe [System.Text.StringBuilder] permite modificar uma string sem criar uma nova string a cada operação. Isso melhora o desempenho ao construir uma string por meio de muitas adições sucessivas, evitando a proliferação de strings de vida muito curta.

A classe oferece vários construtores:

construtor
função
[StringBuilder()]
construtor padrão
[StringBuilder(string value)]
Construção e inicialização com [value]
[StringBuilder(string value, int capacity)]
Construção e inicialização com [value], com uma capacidade inicial de [capacity] caracteres

Um objeto [StringBuilder] armazena seus caracteres em uma área de memória cujo tamanho, sua capacidade, é ajustado automaticamente à medida que o texto cresce. Por padrão, a capacidade inicial é de 16 caracteres. O terceiro construtor permite especificá-la. O programa [strings-05.cs] ilustra esse conceito de capacidade:

using System.Text;

// tamanho e capacidade de um StringBuilder
var str = new StringBuilder("test");
Console.WriteLine($"size={str.Length}, capacity={str.Capacity}");
for (int i = 0; i < 10; i++)
{
    str.Append("test");
    Console.WriteLine($"size={str.Length}, capacity={str.Capacity}");
}
// um StringBuilder com capacidade inicial 10
var str2 = new StringBuilder("test", 10);
Console.WriteLine($"size={str2.Length}, capacity={str2.Capacity}");
for (int i = 0; i < 10; i++)
{
    str2.Append("test");
    Console.WriteLine($"size={str2.Length}, capacity={str2.Capacity}");
}

Resultados:

> dotnet run strings-05.cs
size=4, capacity=16
size=8, capacity=16
size=12, capacity=16
size=16, capacity=16
size=20, capacity=32
size=24, capacity=32
size=28, capacity=32
size=32, capacity=32
size=36, capacity=64
size=40, capacity=64
size=44, capacity=64
size=4, capacity=10
size=8, capacity=10
size=12, capacity=20
size=16, capacity=20
size=20, capacity=20
size=24, capacity=40
size=28, capacity=40
size=32, capacity=40
size=36, capacity=40
size=40, capacity=40
size=44, capacity=80

Comentários:

  • linha 4: criação de um objeto [StringBuilder] com capacidade inicial de 16;
  • linha 5: [Length] é o número atual de caracteres; [Capacity] é o número de caracteres que o objeto pode conter antes de precisar ampliar sua área de memória;
  • linha 8: [Append] adiciona uma string ao final do texto;
  • linha 12: criação de um objeto [StringBuilder] com capacidade inicial de 10.

Os resultados mostram que a capacidade dobra quando é insuficiente: 16, 32, 64 (linhas 6 e 10 dos resultados) e 10, 20, 40, 80 para o segundo objeto. São os mesmos resultados de 2008. Se o tamanho aproximado do texto for conhecido de antemão, defini-lo no momento da construção evita ampliações sucessivas.

Eis alguns dos métodos da classe:

método
função
[StringBuilder Append(string value)]
Adiciona [value] ao final do texto. Sobrecarregado para aceitar os tipos [int], [double], [decimal], [char]… e uma string interpolada
[StringBuilder AppendLine()]
adiciona uma quebra de linha (uma sobrecarga adiciona uma string seguida de uma quebra de linha)
[StringBuilder AppendJoin(string separator, params string[] values)]
adiciona os elementos de [values] separados por [separator]
[StringBuilder Insert(int index, string value)]
insere [value] na posição [index]; sobrecarregado como [Append]
[StringBuilder Remove(int index, int length)]
exclui [length] caracteres a partir da posição [index]
[StringBuilder Replace(string oldValue, string newValue)]
substitui [oldValue] por [newValue]; uma sobrecarga substitui um caractere
[string ToString()]
converte o texto em uma string [string]

O programa [strings-06.cs] os utiliza:

using System.Text;

// os métodos de StringBuilder retornam o próprio objeto StringBuilder: podem ser encadeados
var str3 = new StringBuilder("test");
Console.WriteLine(str3.Append("abCD").Insert(2, "xyZT").Remove(0, 2).Replace("xy", "XY"));

// construção de uma string pedaço por pedaço
var lines = new StringBuilder();
for (int i = 1; i <= 3; i++)
{
    lines.Append("line ").Append(i).AppendLine();
}
// AppendJoin: o equivalente de string.Join
lines.AppendJoin(", ", "a", "b", "c").AppendLine();
// Append também aceita uma string interpolada
int total = 42;
lines.Append($"total={total,6:F1}");
// a string final
string result = lines.ToString();
Console.WriteLine(result);
Console.WriteLine($"{result.Length} characters");

Resultados:

1
2
3
4
5
6
7
8
> dotnet run strings-06.cs
XYZTstabCD
line 1
line 2
line 3
a, b, c
total=  42,0
41 characters

Comentários:

  • Linha 5: os métodos de modificação retornam o próprio objeto [StringBuilder], o que permite encadeá-los. Acompanhemos as etapas: “test” torna-se “testabCD” ([Append]), depois “texyZTstabCD” ([Insert] na posição 2), depois “xyZTstabCD” ([Remove] dos 2 primeiros caracteres) e, por fim, “XYZTstabCD” ([Replace]). [Console.WriteLine] exibe o objeto chamando seu método [ToString];
  • linhas 9–11: construção de um texto de várias linhas por meio de adições sucessivas: esse é o uso típico de [StringBuilder];
  • Linha 17: [Append] aceita uma string interpolada, incluindo largura e formato;
  • Linha 19: o texto final é obtido como uma string [string].

Para algumas poucas concatenações, o operador [+] ou a interpolação é suficiente: o compilador as otimiza. [StringBuilder] é necessário quando o número de adições é grande ou desconhecido, tipicamente em um laço.

5.2.6. Views sobre uma string: Span<char>

O .NET Core 2.1 (2018) introduziu os tipos [Span<T>] e [ReadOnlySpan<T>]. Um objeto [ReadOnlySpan<char>] é uma view sobre uma sequência de caracteres existente, como uma parte de uma string: ele não contém uma cópia dos caracteres, apenas uma forma de acessá-los. Extrair uma parte de uma string por meio de uma view, portanto, não cria uma nova string. O programa [strings-07.cs] compara as duas maneiras de analisar uma linha no formato “sobrenome:nome:idade”:

// ReadOnlySpan<char>: uma "visão" de uma parte de uma string, sem cópia
string line = "dupont:jean:45";

// com Substring: cada campo é uma nova string alocada na memória
int p1 = line.IndexOf(':');
int p2 = line.LastIndexOf(':');
string lastName = line.Substring(0, p1);
int age = int.Parse(line.Substring(p2 + 1));
Console.WriteLine($"Substring : last name={lastName}, age={age}");

// com uma visão: nenhuma string intermediária é criada
ReadOnlySpan<char> view = line.AsSpan();
ReadOnlySpan<char> lastNameView = view[..p1];     // caracteres de 0 a p1-1
ReadOnlySpan<char> ageView = view[(p2 + 1)..];    // de p2+1 até o fim
// int.Parse aceita uma visão
age = int.Parse(ageView);
Console.WriteLine($"Span : last name={lastNameView}, age={age}, length of the view={lastNameView.Length}");
// uma visão pode ser comparada a uma string sem copiá-la
Console.WriteLine($"the last name starts with \"du\": {lastNameView.StartsWith("du")}");
// uma string só é criada se for realmente necessária
string firstName = view[(p1 + 1)..p2].ToString();
Console.WriteLine($"first name={firstName}");

Resultados:

1
2
3
4
5
> dotnet run strings-07.cs
Substring : last name=dupont, age=45
Span : last name=dupont, age=45, length of the view=6
the last name starts with "du": True
first name=jean

Comentários:

  • linhas 7–8: cada chamada a [Substring] cria uma nova string na memória, mesmo que, como no caso da idade, ela seja usada apenas por um instante;
  • linha 12: [AsSpan] retorna uma view da string inteira;
  • Linhas 13–14: os intervalos [start..end] (C# 8), apresentados no Capítulo 3 para arrays, aplicam-se às views: obtêm-se duas novas views, sem cópia;
  • linha 16: muitos métodos do .NET aceitam uma view no lugar de uma string ([Parse], [TryParse], [StartsWith], [Contains], [Equals]…);
  • Linha 21: uma string só é criada a partir de uma view se for realmente necessária.

As views são uma ferramenta de otimização muito usada no próprio .NET: essa é uma das razões pelas quais as versões recentes são significativamente mais rápidas que o .NET Framework de 2008. Uma view só pode existir na pilha de execução: ela não pode, por exemplo, ser um campo de uma classe. Para um programa comum, [string] e [Substring] são perfeitamente adequados: as views só devem ser usadas em código identificado como crítico em termos de desempenho. Não iremos além disso.

5.3. Arrays

5.3.1. A classe Array

Os arrays derivam da classe [System.Array]. Essa classe fornece diversos métodos para ordenar um array, procurar um elemento nele, redimensioná-lo e assim por diante. Apresentaremos algumas de suas propriedades e métodos. Quase todos são sobrecarregados, ou seja, existem em diferentes variantes. Todo array os herda.

Propriedades:

propriedade
função
[public int Length { get; }]
número total de elementos do array, independentemente do número de dimensões
[public int Rank { get; }]
número de dimensões do array

Métodos:

Método
função
[public static int BinarySearch<T>(T[] array, T value)]
retorna a posição de [value] em [array], que deve estar ordenado; um número negativo se [value] estiver ausente
[public static void Clear(Array array, int index, int length)]
define os [length] elementos de [array] a partir do índice [index] com seus valores padrão: 0 para números, [false] para booleanos, [null] para referências
[public static void Copy(Array source, Array destination, int length)]
copia os primeiros [length] elementos de [source] para [destination]
[public static void Fill<T>(T[] array, T value)]
atribui [value] a todos os elementos de [array]
[public int GetLength(int dimension)]
número de elementos na dimensão de número [dimension] do array
[public static int IndexOf<T>(T[] array, T value)]
retorna a posição de [value] em [array], ou -1 se [value] não for encontrado; [LastIndexOf] retorna a última posição
[public static void Resize<T>(ref T[]? array, int newSize)]
redimensiona [array] para [newSize] elementos; os elementos já presentes são mantidos
[public static void Reverse(Array array)]
inverte a ordem dos elementos de [array]
[public static void Sort<T>(T[] array)]
ordena [array] de acordo com a ordem natural de seus elementos; um método sobrecarregado recebe um objeto [IComparer<T>] que define a ordem (Capítulo 4)

O programa [arrays-01.cs] ilustra o uso de alguns métodos da classe [Array]:

// a classe Array: redimensionamento, ordenação, busca

// leitura dos elementos de um array digitado no teclado
double[] elements = Input();
// exibição do array não ordenado
Display("Unsorted array", elements);
// busca linear no array não ordenado
Search(elements, SearchType.Linear);
// ordenação do array
Array.Sort(elements);
// exibição do array ordenado
Display("Sorted array", elements);
// busca binária no array ordenado
Search(elements, SearchType.Binary);

// entrada dos valores do array: retorna o array criado
static double[] Input()
{
    // no início, o array está vazio
    double[] elements = [];
    // laço de entrada dos elementos do array
    while (true)
    {
        Console.Write($"Element (real) {elements.Length} of the array (nothing to finish): ");
        string answer = (Console.ReadLine() ?? "").Trim();
        // fim da entrada se a string for vazia
        if (answer == "")
        {
            break;
        }
        // verificação da entrada
        if (!double.TryParse(answer, out double element))
        {
            Console.WriteLine("Incorrect input, try again");
            continue;
        }
        // mais um elemento: aumentamos o array em uma célula
        Array.Resize(ref elements, elements.Length + 1);
        // e armazenamos nela o novo elemento
        elements[^1] = element;
    }
    return elements;
}

// método genérico para exibir os elementos de um array
static void Display<T>(string text, T[] elements)
{
    Console.WriteLine(text.PadRight(50, '-'));
    foreach (T element in elements)
    {
        Console.WriteLine(element);
    }
}

// busca no array dos elementos digitados no teclado
static void Search(double[] elements, SearchType type)
{
    while (true)
    {
        Console.Write("Element searched for (nothing to stop): ");
        string answer = (Console.ReadLine() ?? "").Trim();
        // terminou?
        if (answer == "")
        {
            break;
        }
        // verificação
        if (!double.TryParse(answer, out double element))
        {
            Console.WriteLine("Error, try again...");
            continue;
        }
        // procuramos o elemento no array
        int i = type == SearchType.Binary
            ? Array.BinarySearch(elements, element)    // array ordenado
            : Array.IndexOf(elements, element);        // array qualquer
        // exibição da resposta
        Console.WriteLine(i >= 0 ? $"Found at position {i}" : $"Not in the array ({i})");
    }
}

// tipo de busca
enum SearchType { Linear, Binary }

Comentários:

  • Linhas 17–42: o método [Input] lê os elementos de um array digitados no teclado. Como o número de elementos não é conhecido de antemão, o programa começa com um array vazio (linha 20) e o amplia em um elemento a cada nova entrada (linha 38). [Resize] na verdade cria um novo array, copia para ele os elementos do antigo e armazena sua referência na variável passada por [ref]. Um algoritmo mais eficiente alocaria espaço em grupos de N elementos. Um array não foi concebido para ser redimensionado: esse cenário é mais bem tratado com uma lista [List<T>], como veremos em breve;
  • linha 40: [^1] refere-se ao último elemento do array (indexação a partir do final, C# 8);
  • No curso de 2008, [Input] era um método com um parâmetro [out]; a versão moderna retorna o array criado, o que é mais natural;
  • Linhas 56–78: o método [Search] procura no array os elementos digitados no teclado. Para um array não ordenado, é realizada uma busca linear com [IndexOf] (linha 76), que examina os elementos um a um. Para um array ordenado, é realizada uma busca binária com [BinarySearch] (linha 75), que divide o intervalo de busca ao meio a cada etapa: ela encontra um elemento entre um milhão em cerca de vinte comparações;
  • linha 10: o array é ordenado. Aqui, usamos uma variante de [Sort] que tem apenas um parâmetro: o array a ser ordenado. A relação de ordem usada para comparar os elementos do array é então a implícita desses elementos: neste caso, a ordem natural dos números;
  • linhas 46–51: um método genérico que exibe um array de elementos de qualquer tipo, [T].

Resultados:

> dotnet run arrays-01.cs
Element (real) 0 of the array (nothing to finish): 3,6
Element (real) 1 of the array (nothing to finish): 7,4
Element (real) 2 of the array (nothing to finish): -1,5
Element (real) 3 of the array (nothing to finish): x
Incorrect input, try again
Element (real) 3 of the array (nothing to finish): -7
Element (real) 4 of the array (nothing to finish): 
Unsorted array------------------------------------
3,6
7,4
-1,5
-7
Element searched for (nothing to stop): 7,4
Found at position 1
Element searched for (nothing to stop): 0
Not in the array (-1)
Element searched for (nothing to stop): 
Sorted array--------------------------------------
-7
-1,5
3,6
7,4
Element searched for (nothing to stop): 7,4
Found at position 3
Element searched for (nothing to stop): 0
Not in the array (-3)
Element searched for (nothing to stop): 

Quando o elemento procurado está ausente, [IndexOf] retorna -1 e [BinarySearch] retorna um número negativo (linha 27): é o complemento de um ([~i]) da posição em que o elemento deveria ser inserido para manter o array ordenado. Aqui, [~(-3)] é igual a 2: o número 0 deveria ser inserido na posição 2, entre -1,5 e 3,6. Observação: [BinarySearch] em um array não ordenado retorna um resultado sem sentido.

5.3.2. Outros métodos da classe Array

O programa [arrays-02.cs] demonstra outros métodos da classe [Array]:

// outros métodos da classe Array
int[] numbers = [40, 10, 30, 20, 50];
Display("numbers", numbers);

// Reverse: inverte a ordem dos elementos, no lugar
Array.Reverse(numbers);
Display("after Reverse", numbers);

// Sort em uma parte do array: 3 elementos a partir do índice 1
Array.Sort(numbers, 1, 3);
Display("after Sort(numbers, 1, 3)", numbers);

// Copy: cópia de 3 elementos para outro array
int[] copy = new int[5];
Array.Copy(numbers, copy, 3);
Display("copy", copy);

// Fill: preenche o array com um valor; Clear: redefine os elementos para o valor padrão
Array.Fill(copy, 7);
Display("after Fill(copy, 7)", copy);
Array.Clear(copy, 1, 2);
Display("after Clear(copy, 1, 2)", copy);

// IndexOf, LastIndexOf em um array de strings
string[] colors = ["red", "green", "blue", "green"];
Console.WriteLine($"IndexOf(green)={Array.IndexOf(colors, "green")}, LastIndexOf(green)={Array.LastIndexOf(colors, "green")}, IndexOf(black)={Array.IndexOf(colors, "black")}");

// ordenação de um array de strings: ordem alfabética da cultura atual
Array.Sort(colors);
Display("sorted colors", colors);

// um array bidimensional: Rank, Length, GetLength
int[,] matrix = new int[2, 3];
Console.WriteLine($"Rank={matrix.Rank}, Length={matrix.Length}, GetLength(0)={matrix.GetLength(0)}, GetLength(1)={matrix.GetLength(1)}");

// exibição de um array em uma linha
static void Display<T>(string text, T[] elements)
{
    Console.WriteLine($"{text,-28}: [{string.Join(", ", elements)}]");
}

Resultados:

> dotnet run arrays-02.cs
numbers                     : [40, 10, 30, 20, 50]
after Reverse               : [50, 20, 30, 10, 40]
after Sort(numbers, 1, 3)   : [50, 10, 20, 30, 40]
copy                        : [50, 10, 20, 0, 0]
after Fill(copy, 7)         : [7, 7, 7, 7, 7]
after Clear(copy, 1, 2)     : [7, 0, 0, 7, 7]
IndexOf(green)=1, LastIndexOf(green)=3, IndexOf(black)=-1
sorted colors               : [blue, green, green, red]
Rank=2, Length=6, GetLength(0)=2, GetLength(1)=3

Comentários:

  • linha 6: [Reverse] inverte a ordem dos elementos do próprio array;
  • linha 10: apenas 3 elementos são ordenados a partir da posição 1: 20, 30, 10 tornam-se 10, 20, 30;
  • linha 15: copia os 3 primeiros elementos de [numbers] para [copy], enquanto os demais elementos mantêm seu valor inicial 0;
  • Linhas 19–21: [Fill] preenche o array; [Clear] zera 2 elementos a partir da posição 1;
  • linha 29: as strings são ordenadas em ordem alfabética de acordo com a cultura atual;
  • Linha 34: para um array bidimensional, [Rank] é 2, [Length] é o número total de elementos e [GetLength(i)] é o número de elementos na dimensão i;
  • Linha 39: [string.Join] exibe um array em uma única linha.

O LINQ, que veremos mais adiante, oferece outras maneiras de pesquisar, ordenar ou transformar os elementos de um array.

5.4. Coleções genéricas

Além dos arrays, existem várias classes para armazenar coleções de elementos. As coleções genéricas, introduzidas com o .NET 2.0, ficam no namespace [System.Collections.Generic], que faz parte dos namespaces [using] implícitos. Apresentaremos primeiro duas coleções muito utilizadas, a lista e o dicionário, e depois trataremos brevemente de outras.

O namespace [System.Collections] contém as versões mais antigas, não genéricas, dessas coleções, que remontam ao .NET 1.0: [ArrayList] (uma lista), [Hashtable] (um dicionário)... O curso de 2008 ainda apresentava [ArrayList]. Essas classes agora são obsoletas: elas armazenam referências do tipo [object], o que exige converter os elementos lidos e fazer o boxing dos números em objetos, com os custos de memória e tempo associados. As coleções genéricas não têm nenhuma dessas desvantagens: uma *[List<int>] armazena seus inteiros diretamente em um array *[int[]] interno, e o compilador verifica o tipo dos elementos adicionados. [ArrayList] e [Hashtable] não devem mais ser usados em código novo.

5.4.1. A classe genérica List<T>

A classe [System.Collections.Generic.List<T>] permite implementar coleções de objetos [T] cujo tamanho varia durante a execução do programa. Um objeto do tipo [List<T>] é manipulado quase como um array. Assim, o elemento i de uma lista [l] é denotado por [l[i]].

Para uma lista do tipo [List<T>] em que [T] é uma classe, a lista armazena referências a objetos do tipo [T], como um array de objetos; se [T] for um tipo de valor ([int], [double], estrutura…), os próprios valores são armazenados na lista.

Eis algumas das propriedades e dos métodos das listas genéricas.

Propriedades:

propriedade
função
[public int Count { get; }]
número de elementos da lista
[public int Capacity { get; set; }]
número de elementos que a lista pode conter antes de ser ampliada. Essa ampliação ocorre automaticamente. Esse conceito de capacidade é análogo ao descrito para a classe [StringBuilder]

Métodos:

Método
função
[public void Add(T item)]
adiciona [item] ao final da lista
[public void AddRange(IEnumerable<T> collection)]
adiciona os elementos de [collection] ao final da lista
[public int BinarySearch(T item)]
retorna a posição de [item] na lista ordenada, se ele estiver presente; caso contrário, retorna um número negativo
[public void Clear()]
remove todos os elementos da lista
[public bool Contains(T item)]
retorna [true] se [item] estiver na lista; caso contrário, [false]
[public List<T> GetRange(int index, int count)]
retorna uma nova lista formada por [count] elementos a partir da posição [index]
[public int IndexOf(T item)]
retorna a posição de [item] na lista, ou -1 se [item] não for encontrado
[public void Insert(int index, T item)]
insere [item] na posição [index] da lista
[public bool Remove(T item)]
remove a primeira ocorrência de [item] da lista; retorna [true] se a operação for bem-sucedida e [false] caso contrário
[public void RemoveAt(int index)]
remove da lista o item de número [index]
[public void Reverse()]
inverte a ordem dos itens da lista
[public void Sort()]
ordena a lista em ordem natural; uma versão sobrecarregada recebe um [IComparer<T>]
[public T[] ToArray()]
retorna os elementos da lista na forma de um array

Vamos retomar o exemplo visto anteriormente com um array e processá-lo agora com um objeto do tipo [List<double>]. Como a lista se assemelha a um array, o código muda muito pouco. Este é o programa [collections-01.cs]:

// a classe List<T>: o programa arrays-01.cs reescrito com uma lista

// leitura dos elementos de uma lista digitada no teclado
List<double> elements = Input();
// número de elementos e capacidade
Console.WriteLine($"The list has {elements.Count} elements and a capacity of {elements.Capacity} elements");
// exibição da lista não ordenada
Display("Unsorted list", elements);
// busca linear na lista não ordenada
Search(elements, SearchType.Linear);
// ordenação da lista
elements.Sort();
// exibição da lista ordenada
Display("Sorted list", elements);
// busca binária na lista ordenada
Search(elements, SearchType.Binary);

// entrada dos valores da lista: retorna a lista criada
static List<double> Input()
{
    // no início, a lista está vazia
    List<double> elements = new();
    // laço de entrada dos elementos da lista
    while (true)
    {
        Console.Write($"Element (real) {elements.Count} of the list (nothing to finish): ");
        string answer = (Console.ReadLine() ?? "").Trim();
        // fim da entrada se a string for vazia
        if (answer == "")
        {
            break;
        }
        // verificação da entrada
        if (!double.TryParse(answer, out double element))
        {
            Console.WriteLine("Incorrect input, try again");
            continue;
        }
        // mais um elemento na lista: ela cresce sozinha
        elements.Add(element);
    }
    return elements;
}

// método genérico para exibir os elementos de qualquer sequência
static void Display<T>(string text, IEnumerable<T> elements)
{
    Console.WriteLine(text.PadRight(50, '-'));
    foreach (T element in elements)
    {
        Console.WriteLine(element);
    }
}

// busca na lista dos elementos digitados no teclado
static void Search(List<double> elements, SearchType type)
{
    while (true)
    {
        Console.Write("Element searched for (nothing to stop): ");
        string answer = (Console.ReadLine() ?? "").Trim();
        // terminou?
        if (answer == "")
        {
            break;
        }
        // verificação
        if (!double.TryParse(answer, out double element))
        {
            Console.WriteLine("Error, try again...");
            continue;
        }
        // procuramos o elemento na lista
        int i = type == SearchType.Binary
            ? elements.BinarySearch(element)    // lista ordenada
            : elements.IndexOf(element);        // lista qualquer
        // exibição da resposta
        Console.WriteLine(i >= 0 ? $"Found at position {i}" : $"Not in the list ({i})");
    }
}

// tipo de busca
enum SearchType { Linear, Binary }

Comentários:

  • linha 22: a lista é criada vazia. [new()] (C# 9) é uma forma abreviada de [new List<double>()]: o tipo é inferido a partir da declaração da variável;
  • linha 40: não há mais redimensionamento a tratar; a lista se amplia automaticamente;
  • linha 6: o número de elementos da lista e sua capacidade;
  • linhas 12, 75, 76: os métodos [Sort], [BinarySearch] e [IndexOf] agora são métodos de instância da lista, ao passo que os de [Array] são métodos estáticos;
  • linhas 46–51: o método genérico [Display<T>] recebe dois parâmetros:
    • o primeiro é um texto a ser escrito;
    • o segundo é um objeto que implementa a interface genérica [IEnumerable<T>]:
1
2
3
4
public interface IEnumerable<out T> : IEnumerable
{
    IEnumerator<T> GetEnumerator();
}

A estrutura [foreach (T element in elements)] é válida para qualquer objeto [elements] que implemente a interface [IEnumerable<T>]. Arrays e listas implementam essa interface. Portanto, o método [Display] serve tanto para exibir arrays quanto listas. Voltaremos a essa interface, que está no centro do LINQ.

Resultados:

> dotnet run collections-01.cs
Element (real) 0 of the list (nothing to finish): 3,6
Element (real) 1 of the list (nothing to finish): 7,4
Element (real) 2 of the list (nothing to finish): -1,5
Element (real) 3 of the list (nothing to finish): -7
Element (real) 4 of the list (nothing to finish): 
The list has 4 elements and a capacity of 4 elements
Unsorted list-------------------------------------
3,6
7,4
-1,5
-7
Element searched for (nothing to stop): 7,4
Found at position 1
Element searched for (nothing to stop): 0
Not in the list (-1)
Element searched for (nothing to stop): 
Sorted list---------------------------------------
-7
-1,5
3,6
7,4
Element searched for (nothing to stop): 7,4
Found at position 3
Element searched for (nothing to stop): 0
Not in the list (-3)
Element searched for (nothing to stop): 

Os resultados são os mesmos obtidos com o array. A capacidade da lista aqui é 4 (linha 7): partindo de 0, ela passou a 4 na primeira adição; passaria a 8 na quinta adição, dobrando como a de um [StringBuilder].

5.4.2. Métodos de List<T> e expressões de coleção

O programa [collections-02.cs] usa os demais métodos da lista e as expressões de coleção do C# 12, que já encontramos com arrays no Capítulo 3:

// os principais métodos de List<T> e expressões de coleção

// uma lista inicializada por uma expressão de coleção (C# 12)
List<string> cities = ["Paris", "Lyon", "Angers"];
Display("start", cities);

// adições
cities.Add("Nantes");                       // no fim
cities.Insert(1, "Brest");                  // na posição 1
cities.AddRange(["Lille", "Tours"]);        // vários elementos no fim
Display("after Add, Insert, AddRange", cities);

// acesso por índice, leitura e escrita
cities[0] = "Marseille";
Console.WriteLine($"cities[0]={cities[0]}, cities[^1]={cities[^1]}, Count={cities.Count}");

// busca
Console.WriteLine($"Contains(\"Lyon\")={cities.Contains("Lyon")}, IndexOf(\"Angers\")={cities.IndexOf("Angers")}, IndexOf(\"Nice\")={cities.IndexOf("Nice")}");

// remoções
bool removed = cities.Remove("Lyon");       // por valor
cities.RemoveAt(0);                         // por posição
Display($"after Remove ({removed}), RemoveAt(0)", cities);

// ordenação, inversão, intervalo de elementos
cities.Sort();
Display("after Sort", cities);
cities.Reverse();
Display("after Reverse", cities);
List<string> slice = cities.GetRange(1, 2);
Display("GetRange(1, 2)", slice);

// conversão para array e de volta
string[] array = cities.ToArray();
List<string> other = new(array);
Console.WriteLine($"array of {array.Length} elements, new list of {other.Count} elements");

// o operador .. (spread) insere os elementos de uma coleção em outra
int[] small = [1, 2, 3];
List<int> numbers = [0, .. small, 10, .. small];
Display("numbers", numbers);
// a mesma sintaxe cria um array, uma lista ou uma coleção vazia
int[] empty = [];
Console.WriteLine($"empty.Length={empty.Length}");

// Clear esvazia a lista
cities.Clear();
Console.WriteLine($"after Clear: Count={cities.Count}");

static void Display<T>(string text, List<T> list)
{
    Console.WriteLine($"{text,-34}: [{string.Join(", ", list)}]");
}

Resultados:

> dotnet run collections-02.cs
start                             : [Paris, Lyon, Angers]
after Add, Insert, AddRange       : [Paris, Brest, Lyon, Angers, Nantes, Lille, Tours]
cities[0]=Marseille, cities[^1]=Tours, Count=7
Contains("Lyon")=True, IndexOf("Angers")=3, IndexOf("Nice")=-1
after Remove (True), RemoveAt(0)  : [Brest, Angers, Nantes, Lille, Tours]
after Sort                        : [Angers, Brest, Lille, Nantes, Tours]
after Reverse                     : [Tours, Nantes, Lille, Brest, Angers]
GetRange(1, 2)                    : [Nantes, Lille]
array of 5 elements, new list of 5 elements
numbers                           : [0, 1, 2, 3, 10, 1, 2, 3]
empty.Length=0
after Clear: Count=0

Comentários:

  • linha 4: uma expressão de coleção [a, b, c] inicializa uma lista como se fosse um array;
  • linhas 8–10: três maneiras de adicionar elementos;
  • linha 14: o elemento de número 0 pode ser lido e escrito; [cities[^1]] é o último elemento, como em um array;
  • linha 21: [Remove] retorna [true] se o elemento foi encontrado e removido;
  • linha 30: uma nova lista formada por 2 elementos a partir da posição 1;
  • linhas 34–35: conversão de uma lista em array e de um array (ou qualquer sequência) em lista;
  • linha 40: em uma expressão de coleção, o operador [..] (spread) insere todos os elementos de outra coleção;
  • Linha 43: [] designa uma coleção vazia do tipo esperado.

5.4.3. A classe Dictionary<TKey,TValue>

A classe [System.Collections.Generic.Dictionary<TKey,TValue>] é usada para implementar um dicionário. Um dicionário pode ser visto como um array de duas colunas:

chave
valor
key1
value1
key2
value2
...
...

Na classe [Dictionary<TKey,TValue>], as chaves são do tipo [TKey] e os valores são do tipo [TValue]. As chaves são únicas: não pode haver duas chaves idênticas. Um dicionário desse tipo teria esta aparência se os tipos [TKey] e [TValue] se referissem a classes:

Image

O valor associado à chave [c] em um dicionário [d] é obtido com a notação [d[c]]. Esse valor pode ser lido e escrito. Assim, podemos escrever:

1
2
3
4
5
TValue v = ...;
TKey k = ...;
Dictionary<TKey, TValue> d = new();
d[k] = v;
v = d[k];

Na escrita, [d[c] = v] adiciona o par (c, v) se a chave [c] não existir e, caso contrário, substitui o valor associado a [c] . Na leitura, se a chave [c] não existir no dicionário [d], a notação [d[c]] lança uma exceção [KeyNotFoundException].

Os principais métodos e propriedades da classe [Dictionary<TKey,TValue>] são os seguintes.

Propriedades:

propriedade
função
[public int Count { get; }]
número de entradas (chave, valor) do dicionário
[public KeyCollection Keys { get; }]
coleção das chaves do dicionário
[public ValueCollection Values { get; }]
coleção dos valores do dicionário

Métodos:

Método
Função
[public void Add(TKey key, TValue value)]
Adiciona o par (chave, valor) ao dicionário; lança uma exceção se a chave já existir
[public bool TryAdd(TKey key, TValue value)]
Igual ao anterior, mas retorna [false] em vez de lançar uma exceção
[public void Clear()]
remove todos os pares do dicionário
[public bool ContainsKey(TKey key)]
Retorna [true] se [key] for uma chave do dicionário; caso contrário, retorna [false]
[public bool ContainsValue(TValue value)]
retorna [true] se [value] for um valor do dicionário e [false] caso contrário
[public bool Remove(TKey key)]
remove do dicionário o par chave-valor [key]; retorna [true] se a operação for bem-sucedida e [false] caso contrário
[public bool TryGetValue(TKey key, out TValue value)]
retorna [true] e atribui a [value] o valor associado à chave [key] se esta existir; retorna [false] caso contrário, e [value] recebe o valor padrão do tipo [TValue]

Consideremos o programa de exemplo [collections-03.cs]:

// a classe Dictionary<TKey,TValue>

// criação de um dicionário <string,int> a partir de um array de strings "name:age"
string[] list = ["jean:20", "paul:18", "mélanie:10", "violette:15"];
Dictionary<string, int> dico = new();
foreach (string element in list)
{
    string[] fields = element.Split(':');
    dico[fields[0]] = int.Parse(fields[1]);
}
// número de elementos do dicionário
Console.WriteLine($"The dictionary has {dico.Count} elements");
// lista de chaves
Display("[List of keys]", dico.Keys);
// lista de valores
Display("[List of values]", dico.Values);
// lista de chaves e valores
Console.WriteLine("[List of keys & values]");
foreach (string key in dico.Keys)
{
    Console.WriteLine($"key={key} value={dico[key]}");
}
// removemos a chave "paul"
Console.WriteLine("[Removal of a key]");
dico.Remove("paul");
// iteração sobre os pares (chave, valor) com desconstrução
Console.WriteLine("[List of keys & values]");
foreach (var (key, value) in dico)
{
    Console.WriteLine($"key={key} value={value}");
}
// Add rejeita uma chave existente, enquanto dico[key] = value a substitui
try
{
    dico.Add("jean", 21);
}
catch (ArgumentException e)
{
    Console.WriteLine($"{e.GetType().Name} : {e.Message}");
}
// TryAdd só adiciona se a chave estiver ausente
Console.WriteLine($"TryAdd(\"jean\", 21)={dico.TryAdd("jean", 21)}, TryAdd(\"zoé\", 12)={dico.TryAdd("zoé", 12)}");
// a notação dico[key] lança uma exceção se a chave estiver ausente
try
{
    Console.WriteLine(dico["x"]);
}
catch (KeyNotFoundException e)
{
    Console.WriteLine($"{e.GetType().Name} : {e.Message}");
}

// busca no dicionário
while (true)
{
    Console.Write("Name searched for (nothing to stop): ");
    string searchedName = (Console.ReadLine() ?? "").Trim();
    if (searchedName == "")
    {
        break;
    }
    // TryGetValue retorna true se a chave existir e coloca o valor associado em age
    if (dico.TryGetValue(searchedName, out int age))
    {
        Console.WriteLine($"{searchedName},{age}");
    }
    else
    {
        Console.WriteLine($"Name {searchedName} unknown");
    }
}

// método genérico para exibir os elementos de uma sequência
static void Display<T>(string text, IEnumerable<T> elements)
{
    Console.WriteLine(text.PadRight(50, '-'));
    foreach (T element in elements)
    {
        Console.WriteLine(element);
    }
}

Comentários:

  • linha 4: um array de strings que será usado para inicializar o dicionário <string,int>;
  • linha 5: o dicionário, que está vazio;
  • linhas 6–9: sua inicialização a partir do array de strings;
  • linha 12: o número de entradas do dicionário;
  • linhas 14–16: as chaves e os valores do dicionário. [dico.Keys] e [dico.Values] implementam [IEnumerable<T>]: o método [Display] que já encontramos é adequado;
  • linha 25: exclusão de uma entrada do dicionário;
  • linha 28: um dicionário é uma sequência de pares [KeyValuePair<TKey,TValue>], cada um com uma propriedade [Key] e uma propriedade [Value]. Desde o .NET Core 2.0, tal par pode ser decomposto em duas variáveis, como uma tupla (Capítulo 3);
  • linhas 35–42: [Add] rejeita uma chave existente lançando uma exceção; [TryAdd] retorna [false] nesse caso. As mensagens de exceção do .NET estão em inglês: o .NET 10 não fornece mensagens em francês;
  • linha 46: tentar ler uma chave ausente lança uma exceção [KeyNotFoundException];
  • linha 63: pesquisa de uma chave no dicionário. [TryGetValue] retorna [true] se a chave existir. O curso de 2008 ignorava esse resultado e verificava se o valor retornado era nulo, técnica que só funcionava porque o valor 0 não estava no dicionário. Verificar o valor booleano retornado é a abordagem correta.

Resultados:

> dotnet run collections-03.cs
The dictionary has 4 elements
[List of keys]------------------------------------
jean
paul
mélanie
violette
[List of values]----------------------------------
20
18
10
15
[List of keys & values]
key=jean value=20
key=paul value=18
key=mélanie value=10
key=violette value=15
[Removal of a key]
[List of keys & values]
key=jean value=20
key=mélanie value=10
key=violette value=15
ArgumentException : An item with the same key has already been added. Key: jean
TryAdd("jean", 21)=False, TryAdd("zoé", 12)=True
KeyNotFoundException : The given key 'x' was not present in the dictionary.
Name searched for (nothing to stop): violette
violette,15
Name searched for (nothing to stop): x
Name x unknown
Name searched for (nothing to stop): jean
jean,20
Name searched for (nothing to stop): 

As chaves são listadas aqui na ordem em que foram adicionadas, mas isso não é garantido: um *[Dictionary]* não preserva nenhuma ordem. Após exclusões, um novo elemento pode ocupar o lugar de um elemento excluído. Se a ordem das chaves for importante, use um *[SortedDictionary]*, apresentado a seguir.

5.4.4. Outras coleções genéricas

O namespace [System.Collections.Generic] contém outras coleções, cada uma adequada a um propósito específico:

classe
função
[HashSet<T>]
um conjunto: sem duplicatas, sem ordem, teste de pertinência muito rápido; operações de conjuntos (união, interseção, diferença)
[SortedSet<T>]
um conjunto cujos elementos são mantidos ordenados
[Queue<T>]
uma fila: os elementos saem na ordem em que foram inseridos (FIFO, first in, first out)
[Stack<T>]
uma pilha: o último elemento adicionado é o primeiro a ser removido (LIFO, last in, first out)
[SortedDictionary<TKey,TValue>]
um dicionário cujas chaves são mantidas ordenadas
[PriorityQueue<TElement,TPriority>]
uma fila de prioridade (.NET 6): o elemento removido é o de menor prioridade
[LinkedList<T>]
uma lista duplamente encadeada: inserções e exclusões rápidas no meio da lista

O programa [collections-04.cs] oferece uma visão geral rápida:

// uma visão geral de outras coleções genéricas

// HashSet<T>: um conjunto, sem duplicatas nem ordem
HashSet<string> languages = ["C#", "Java", "PHP"];
bool added1 = languages.Add("Python");
bool added2 = languages.Add("Java");             // já presente: rejeitado
Console.WriteLine($"HashSet : Add(Python)={added1}, Add(Java)={added2}, Count={languages.Count}, Contains(PHP)={languages.Contains("PHP")}");
HashSet<string> web = ["PHP", "JavaScript", "Python"];
HashSet<string> common = new(languages);
common.IntersectWith(web);                        // interseção
Console.WriteLine($"HashSet : intersection = {{{string.Join(", ", common)}}}");
common.UnionWith(["Go"]);                         // união
Console.WriteLine($"HashSet : after union = {{{string.Join(", ", common)}}}");

// Queue<T>: uma fila, primeiro a entrar, primeiro a sair
Queue<string> queue = new();
queue.Enqueue("client1");
queue.Enqueue("client2");
queue.Enqueue("client3");
Console.WriteLine($"Queue : Peek={queue.Peek()}, Dequeue={queue.Dequeue()}, Dequeue={queue.Dequeue()}, {queue.Count} left");

// Stack<T>: uma pilha, último a entrar, primeiro a sair
Stack<int> stack = new();
stack.Push(1);
stack.Push(2);
stack.Push(3);
Console.WriteLine($"Stack : Peek={stack.Peek()}, Pop={stack.Pop()}, Pop={stack.Pop()}, {stack.Count} left");
// TryPop evita a exceção em uma pilha vazia
stack.Pop();
Console.WriteLine($"Stack : TryPop on an empty stack = {stack.TryPop(out int top)}");

// SortedDictionary<TKey,TValue>: um dicionário cujas chaves são mantidas ordenadas
SortedDictionary<string, int> ages = new()
{
    ["violette"] = 15,
    ["jean"] = 20,
    ["mélanie"] = 10,
    ["paul"] = 18
};
Console.WriteLine($"SortedDictionary : {string.Join(", ", ages)}");

// PriorityQueue<TElement,TPriority>: o elemento de menor prioridade sempre sai primeiro
PriorityQueue<string, int> emergencies = new();
emergencies.Enqueue("sprain", 3);
emergencies.Enqueue("cardiac arrest", 1);
emergencies.Enqueue("cold", 5);
emergencies.Enqueue("fracture", 2);
Console.Write("PriorityQueue :");
while (emergencies.TryDequeue(out string? patient, out int priority))
{
    Console.Write($" {patient} ({priority})");
}
Console.WriteLine();

Resultados:

1
2
3
4
5
6
7
8
9
> dotnet run collections-04.cs
HashSet : Add(Python)=True, Add(Java)=False, Count=4, Contains(PHP)=True
HashSet : intersection = {PHP, Python}
HashSet : after union = {Go, PHP, Python}
Queue : Peek=client1, Dequeue=client1, Dequeue=client2, 1 left
Stack : Peek=3, Pop=3, Pop=2, 1 left
Stack : TryPop on an empty stack = False
SortedDictionary : [jean, 20], [mélanie, 10], [paul, 18], [violette, 15]
PriorityQueue : cardiac arrest (1) fracture (2) sprain (3) cold (5)

Comentários:

  • linha 4: as expressões de coleção também inicializam um conjunto;
  • linha 6: [Add] retorna [false] se o elemento já estiver no conjunto, que permanece inalterado;
  • Linhas 9–12: [IntersectWith] e [UnionWith] modificam o conjunto; por isso, trabalhamos sobre uma cópia de [languages]. A ordem em que os elementos de um conjunto são exibidos não tem significado (linha 4);
  • as chaves duplas [{{] e [}}] em uma string interpolada exibem uma única chave;
  • linhas 16–20: [Enqueue] coloca um elemento na fila, [Dequeue] retira o elemento mais antigo, [Peek] consulta o elemento sem retirá-lo da fila;
  • linhas 23–30: [Push] empilha um elemento, [Pop] desempilha o elemento mais recente. [Pop] em uma pilha vazia lança uma exceção; [TryPop] retorna [false];
  • linhas 33–40: um dicionário inicializado com a sintaxe [[key] = value]; seus pares chave-valor são enumerados na ordem das chaves;
  • linhas 43–49: cada elemento entra na fila com uma prioridade; os pacientes saem em ordem crescente de prioridade, independentemente da ordem de chegada.

5.4.5. Coleções somente leitura

Uma classe que gerencia uma coleção muitas vezes precisa expô-la externamente sem permitir que seja modificada. O .NET fornece interfaces somente leitura para essa finalidade: [IReadOnlyCollection<T>] (um [Count] e um [foreach]), [IReadOnlyList<T>] (mais o acesso por índice) e [IReadOnlyDictionary<TKey,TValue>]. As classes [List<T>], [T[]], e [Dictionary<TKey,TValue>] as implementam. O programa [collections-05.cs] as utiliza:

// coleções somente leitura

var classroom = new Classroom();
classroom.Enroll("dupont");
classroom.Enroll("martin");
// o código externo pode ler a lista de alunos...
IReadOnlyList<string> students = classroom.Students;
Console.WriteLine($"{students.Count} students: {string.Join(", ", students)}, students[0]={students[0]}");
// ... mas a interface IReadOnlyList<T> não tem Add nem Remove: students.Add("x") não compila

// um cast para List<string> permitiria contornar a proteção
if (students is List<string> list)
{
    Console.WriteLine("Students is actually a modifiable List<string>");
}
// AsReadOnly retorna um wrapper somente leitura que não pode ser contornado
IReadOnlyList<string> protectedList = classroom.ProtectedStudents;
Console.WriteLine($"ProtectedStudents is of type {protectedList.GetType().Name}");
try
{
    // ReadOnlyCollection<T> implementa IList<T>, mas seus métodos de modificação lançam uma exceção
    ((IList<string>)protectedList).Add("intruder");
}
catch (NotSupportedException e)
{
    Console.WriteLine($"{e.GetType().Name} : {e.Message}");
}
// o wrapper reflete as modificações feitas pela classe proprietária
classroom.Enroll("durand");
Console.WriteLine($"{protectedList.Count} students: {string.Join(", ", protectedList)}");

// um dicionário somente leitura
IReadOnlyDictionary<string, int> grades = new Dictionary<string, int> { ["dupont"] = 12, ["martin"] = 15 };
Console.WriteLine($"grades[martin]={grades["martin"]}, ContainsKey(durand)={grades.ContainsKey("durand")}");

// uma classe que mantém o controle de sua lista
class Classroom
{
    // a lista é privada: somente a classe pode modificá-la
    private readonly List<string> _students = [];

    // exposta como somente leitura por meio de uma interface
    public IReadOnlyList<string> Students => _students;
    // exposta por meio de um wrapper somente leitura
    public IReadOnlyList<string> ProtectedStudents => _students.AsReadOnly();

    public void Enroll(string name) => _students.Add(name);
}

Resultados:

1
2
3
4
5
6
7
> dotnet run collections-05.cs
2 students: dupont, martin, students[0]=dupont
Students is actually a modifiable List<string>
ProtectedStudents is of type ReadOnlyCollection`1
NotSupportedException : Collection is read-only.
3 students: dupont, martin, durand
grades[martin]=15, ContainsKey(durand)=False

Comentários:

  • linhas 37–47: a classe [Classroom] gerencia uma lista de alunos. A própria lista é privada; apenas o método [Enroll] permite modificá-la;
  • linha 43: a propriedade [Students] converte a lista para o tipo [IReadOnlyList<string>], que admite apenas operações de leitura: [students.Add("x")] causaria um erro de compilação;
  • linha 12: no entanto, essa proteção é apenas superficial: o objeto retornado é a própria lista, e uma conversão de tipo permite acessar seus métodos de modificação;
  • linha 45: [AsReadOnly] envolve a lista em um contêiner do tipo [ReadOnlyCollection<T>]. Desta vez, nenhuma modificação é possível: seus métodos de modificação, impostos pela interface [IList<T>], lançam uma exceção [NotSupportedException] (linha 5). O wrapper não copia a lista: ele enxerga as modificações feitas pela classe proprietária (linha 6);
  • linha 33: um dicionário visto por meio da interface [IReadOnlyDictionary<TKey,TValue>].

Para dados que nunca devem mudar após a criação, o namespace [System.Collections.Immutable] fornece coleções imutáveis ([ImmutableList<T>], [ImmutableDictionary<TKey,TValue>]…) e [System.Collections.Frozen] oferece coleções congeladas otimizadas para leitura ([FrozenDictionary<TKey,TValue>], .NET 8). Não entraremos em detalhes sobre elas.

5.5. LINQ

O curso de 2008 terminava pouco antes do LINQ, apresentando seus tipos anônimos sem realmente utilizá-los. O LINQ (Language Integrated Query, C# 3, 2007) é um conjunto de métodos que permitem consultar uma coleção assim como se consulta um banco de dados: filtrar, ordenar, agrupar, calcular totais e assim por diante. Ele se aplica a qualquer coleção que implemente a interface [IEnumerable<T>]: arrays, listas, dicionários, conjuntos, linhas de um arquivo, resultados de uma expressão regular e, com o Entity Framework Core (Capítulo 11), tabelas de banco de dados. O namespace [System.Linq] faz parte dos namespaces [using] implícitos.

5.5.1. As sequências IEnumerable<T> e os iteradores

Uma coleção que implementa [IEnumerable<T>] é chamada de sequência: ela pode ser percorrida com [foreach]. A interface contém apenas um método, [GetEnumerator], que retorna um enumerador [IEnumerator<T>]: um objeto que percorre a sequência ([MoveNext]) e retorna o elemento atual ([Current]).

Um método pode produzir uma sequência sem construir uma coleção: trata-se de um iterador. Ele retorna seus elementos um a um por meio da instrução [yield return]. O programa [linq-01.cs] traz dois exemplos:

// sequências IEnumerable<T> e iteradores (yield return)

// 1 - foreach sobre uma sequência produzida por um iterador
Console.WriteLine("[foreach on Evens(6)]");
foreach (int n in Evens(6))
{
    Console.WriteLine($"  received {n}");
}

// 2 - o que o foreach faz: ele pede um enumerador à sequência
Console.WriteLine("[enumeration by hand]");
IEnumerable<int> sequence = Evens(4);
using (IEnumerator<int> enumerator = sequence.GetEnumerator())
{
    while (enumerator.MoveNext())
    {
        Console.WriteLine($"  Current={enumerator.Current}");
    }
}

// 3 - uma sequência infinita: ela só é produzida à medida que é necessária
Console.WriteLine("[infinite sequence]");
foreach (long f in Fibonacci())
{
    if (f > 100)
    {
        break;
    }
    Console.Write($"{f} ");
}
Console.WriteLine();

// 4 - um array, uma lista, uma string também são IEnumerable<T>
IEnumerable<char> letters = "abc";
IEnumerable<string> words = new List<string> { "one", "two" };
Console.WriteLine($"[other sequences] {string.Join("-", letters)} {string.Join("-", words)}");

// os números pares de 0 a max
static IEnumerable<int> Evens(int max)
{
    Console.WriteLine("  (start of the iterator)");
    for (int i = 0; i <= max; i += 2)
    {
        Console.WriteLine($"  (production of {i})");
        // retornamos i ao código chamador; retomaremos aqui na próxima solicitação
        yield return i;
    }
    Console.WriteLine("  (end of the iterator)");
}

// a sequência de Fibonacci, sem fim
static IEnumerable<long> Fibonacci()
{
    long a = 0, b = 1;
    while (true)
    {
        yield return a;
        (a, b) = (b, a + b);
    }
}

Resultados:

> dotnet run linq-01.cs
[foreach on Evens(6)]
  (start of the iterator)
  (production of 0)
  received 0
  (production of 2)
  received 2
  (production of 4)
  received 4
  (production of 6)
  received 6
  (end of the iterator)
[enumeration by hand]
  (start of the iterator)
  (production of 0)
  Current=0
  (production of 2)
  Current=2
  (production of 4)
  Current=4
  (end of the iterator)
[infinite sequence]
0 1 1 2 3 5 8 13 21 34 55 89 
[other sequences] a-b-c one-two

Comentários:

  • Linhas 39–48: o método [Evens] é um iterador: seu tipo de retorno é *[IEnumerable<int>], e ele contém a instrução [yield return] (linha 46). Ele não constrói nenhuma lista: a cada [yield return], devolve um elemento ao código que o percorre e fica em pausa*; ele será retomado na instrução seguinte quando o próximo elemento for solicitado;
  • linhas 5–7: os resultados (linhas 3–12) mostram que a produção de um elemento pelo iterador e seu consumo pelo laço [foreach] se alternam;
  • linhas 12–17: o que o [foreach] realmente faz: ele solicita um enumerador à sequência, chama [MoveNext] enquanto esse método retornar [true] e lê o elemento atual em [Current]. O iterador é liberado no final pela instrução [using] (voltaremos a isso ao tratar de arquivos). Observe que a chamada a [Evens(4)] na linha 12 não faz nada: a mensagem “start of the iterator” só aparece na primeira chamada a [MoveNext];
  • linhas 52–58: um iterador pode produzir uma sequência infinita; ele calcula apenas os elementos solicitados. É o laço [foreach] que decide quando parar (linha 25). A linha 58 usa as tuplas do Capítulo 3 para trocar valores;
  • linhas 34–35: uma string é uma sequência de caracteres; uma lista é uma sequência de seus elementos. A lista é criada aqui com a sintaxe de [new List<string> { ... }] inicializador de coleção (C# 3), que é encontrada com frequência em código existente.

Esse mecanismo de geração sob demanda é usado por todos os métodos do LINQ.

5.5.2. Filtrar, projetar, ordenar

Os exemplos a seguir trabalham com uma pequena lista de pessoas. Uma pessoa é representada por um [record] (C# 9) record, apresentado no Capítulo 4: em uma única linha, obtemos uma classe com um construtor, propriedades somente leitura, um método [ToString] que exibe as propriedades e um operador de igualdade que compara os valores das propriedades.

O programa [linq-02.cs] demonstra os métodos básicos do LINQ:

// LINQ: filtragem (Where), projeção (Select), ordenação (OrderBy, ThenBy)

// os dados: uma lista de pessoas
List<Person> persons =
[
    new("dupont", "jean", 45, "Angers"),
    new("martin", "marie", 17, "Paris"),
    new("durand", "paul", 32, "Angers"),
    new("leroy", "sophie", 28, "Nantes"),
    new("moreau", "luc", 15, "Paris"),
    new("simon", "julie", 52, "Angers"),
    new("laurent", "marc", 32, "Lyon"),
];

// Where: os adultos; p => p.Age >= 18 é uma função anônima
IEnumerable<Person> adults = persons.Where(p => p.Age >= 18);
Display("[Where: the adults]", adults);

// Select: uma projeção, aqui cada pessoa se torna uma string
IEnumerable<string> names = persons.Select(p => $"{p.FirstName} {p.LastName.ToUpper()}");
Display("[Select: first name LAST NAME]", names);

// os operadores podem ser encadeados: os nomes das pessoas de Angers, em ordem alfabética
var angersPeople = persons
    .Where(p => p.City == "Angers")
    .OrderBy(p => p.LastName)
    .Select(p => p.LastName);
Display("[Where + OrderBy + Select: the people of Angers]", angersPeople);

// ordenação por vários critérios: idade decrescente, depois sobrenome crescente
var sorted = persons.OrderByDescending(p => p.Age).ThenBy(p => p.LastName);
Display("[OrderByDescending + ThenBy]", sorted);

// a mesma consulta que 'angersPeople' escrita com a sintaxe de consulta
var angersPeople2 = from p in persons
                    where p.City == "Angers"
                    orderby p.LastName
                    select p.LastName;
Display("[query syntax: the people of Angers]", angersPeople2);

// Select também pode fornecer a posição do elemento
var numbered = persons.Take(3).Select((p, i) => $"{i + 1}. {p.LastName}");
Display("[Select with index]", numbered);

// exibição de uma sequência
static void Display<T>(string title, IEnumerable<T> sequence)
{
    Console.WriteLine(title);
    foreach (T element in sequence)
    {
        Console.WriteLine($"  {element}");
    }
}

// uma pessoa
record Person(string LastName, string FirstName, int Age, string City);

Resultados:

> dotnet run linq-02.cs
[Where: the adults]
  Person { LastName = dupont, FirstName = jean, Age = 45, City = Angers }
  Person { LastName = durand, FirstName = paul, Age = 32, City = Angers }
  Person { LastName = leroy, FirstName = sophie, Age = 28, City = Nantes }
  Person { LastName = simon, FirstName = julie, Age = 52, City = Angers }
  Person { LastName = laurent, FirstName = marc, Age = 32, City = Lyon }
[Select: first name LAST NAME]
  jean DUPONT
  marie MARTIN
  paul DURAND
  sophie LEROY
  luc MOREAU
  julie SIMON
  marc LAURENT
[Where + OrderBy + Select: the people of Angers]
  dupont
  durand
  simon
[OrderByDescending + ThenBy]
  Person { LastName = simon, FirstName = julie, Age = 52, City = Angers }
  Person { LastName = dupont, FirstName = jean, Age = 45, City = Angers }
  Person { LastName = durand, FirstName = paul, Age = 32, City = Angers }
  Person { LastName = laurent, FirstName = marc, Age = 32, City = Lyon }
  Person { LastName = leroy, FirstName = sophie, Age = 28, City = Nantes }
  Person { LastName = martin, FirstName = marie, Age = 17, City = Paris }
  Person { LastName = moreau, FirstName = luc, Age = 15, City = Paris }
[query syntax: the people of Angers]
  dupont
  durand
  simon
[Select with index]
  1. dupont
  2. martin
  3. durand

Comentários:

  • linhas 4–13: a lista de pessoas, inicializada por uma expressão de coleção; [new(...)] cria um objeto do tipo esperado, neste caso [Person];
  • linha 56: o record [Person]. Uma aplicação de arquivo único coloca suas declarações de tipos após as instruções de nível superior;
  • linha 16: o método [Where] filtra a sequência: ele retém apenas os elementos que satisfazem uma condição. Essa condição lhe é passada na forma de uma função anônima [p => p.Age >= 18], que se lê “a função que, para uma pessoa p, associa o booleano p.Age >= 18”. Essa notação é chamada de expressão lambda. [Where] chama essa função para cada pessoa. As lambdas serão estudadas em detalhes no Capítulo 7 (“Delegates, lambdas e eventos”; por enquanto, basta saber lê-las);
  • O resultado de [Where] é uma nova sequência, [IEnumerable<Person>]: a lista [persons] permanece inalterada. Isso vale para todos os métodos do LINQ;
  • o método [Display] exibe cada pessoa por meio do método [ToString] gerado para o record: [Person { LastName = dupont, ... }];
  • Linha 20: o método [Select] mapeia cada elemento da sequência para um novo valor, neste caso uma string. O resultado é uma sequência [IEnumerable<string>];
  • linhas 24–27: os métodos do LINQ retornam sequências, às quais outros métodos do LINQ podem ser aplicados. Os métodos costumam ser escritos um por linha: essa cadeia de chamadas se lê de cima para baixo como uma receita;
  • linha 26: [OrderBy] ordena a sequência de acordo com a chave retornada pela lambda, neste caso o nome;
  • linha 31: [OrderByDescending] ordena em ordem decrescente; [ThenBy] (ou [ThenByDescending]) adiciona um critério secundário, usado para distinguir elementos iguais segundo o primeiro critério: Durand e Laurent, ambos com 32 anos, são ordenados por nome (linhas 23–24);
  • linhas 35–38: a mesma consulta que [angersPeople] escrita com a sintaxe de consulta, semelhante ao SQL. O compilador a traduz exatamente na cadeia de chamadas [Where(...).OrderBy(...).Select(...)]: as duas notações são equivalentes. A sintaxe de consulta é mais legível para junções e agrupamentos; a sintaxe de métodos é mais comum e é a única que dá acesso a todos os métodos do LINQ ([Take], [Count], [First]…);
  • Linha 42: uma variante de [Select] passa à lambda o elemento e sua posição na sequência.

5.5.3. Quantificadores, agregações, seleção de elementos

O programa [linq-03.cs] inclui métodos que retornam um único valor e métodos que selecionam uma parte da sequência:

// LINQ: quantificadores, agregados, escolha de elementos, partições

List<Person> persons =
[
    new("dupont", "jean", 45, "Angers"),
    new("martin", "marie", 17, "Paris"),
    new("durand", "paul", 32, "Angers"),
    new("leroy", "sophie", 28, "Nantes"),
    new("moreau", "luc", 15, "Paris"),
    new("simon", "julie", 52, "Angers"),
    new("laurent", "marc", 32, "Lyon"),
];

// quantificadores: Any (pelo menos um), All (todos)
Console.WriteLine($"Any(minor)={persons.Any(p => p.Age < 18)}, All(minor)={persons.All(p => p.Age < 18)}, Any()={persons.Any()}");

// agregados
Console.WriteLine($"Count()={persons.Count()}, Count(Angers)={persons.Count(p => p.City == "Angers")}");
Console.WriteLine($"Sum(age)={persons.Sum(p => p.Age)}, Average(age)={persons.Average(p => p.Age):F2}");
Console.WriteLine($"Min(age)={persons.Min(p => p.Age)}, Max(age)={persons.Max(p => p.Age)}");
// MinBy, MaxBy retornam o próprio elemento e não o valor mínimo ou máximo
Console.WriteLine($"MinBy(age)={persons.MinBy(p => p.Age)?.LastName}, MaxBy(age)={persons.MaxBy(p => p.Age)?.LastName}");

// escolha de um elemento
Console.WriteLine($"First()={persons.First().LastName}, First(Paris)={persons.First(p => p.City == "Paris").LastName}, Last()={persons.Last().LastName}");
Person? unknown = persons.FirstOrDefault(p => p.City == "Brest");
Console.WriteLine($"FirstOrDefault(Brest)={unknown?.LastName ?? "null"}");
Console.WriteLine($"Single(Lyon)={persons.Single(p => p.City == "Lyon").LastName}");
try
{
    // Single exige exatamente um elemento
    _ = persons.Single(p => p.City == "Angers");
}
catch (InvalidOperationException e)
{
    Console.WriteLine($"Single(Angers) : {e.GetType().Name} : {e.Message}");
}
try
{
    // First exige pelo menos um elemento
    _ = persons.First(p => p.City == "Brest");
}
catch (InvalidOperationException e)
{
    Console.WriteLine($"First(Brest) : {e.GetType().Name} : {e.Message}");
}

// Distinct: remove duplicatas
var cities = persons.Select(p => p.City).Distinct();
Console.WriteLine($"Distinct(cities)=[{string.Join(", ", cities)}]");
// DistinctBy: um elemento por valor de chave
var onePerCity = persons.DistinctBy(p => p.City).Select(p => p.LastName);
Console.WriteLine($"DistinctBy(city)=[{string.Join(", ", onePerCity)}]");

// partições: Take, Skip, TakeWhile
var names = persons.Select(p => p.LastName);
Console.WriteLine($"Take(2)=[{string.Join(", ", names.Take(2))}], Skip(5)=[{string.Join(", ", names.Skip(5))}]");
Console.WriteLine($"Skip(2).Take(2)=[{string.Join(", ", names.Skip(2).Take(2))}], TakeWhile(length 6)=[{string.Join(", ", names.TakeWhile(n => n.Length == 6))}]");

// Chunk: divisão em pacotes de tamanho fixo (paginação)
int page = 1;
foreach (Person[] packet in persons.Chunk(3))
{
    Console.WriteLine($"page {page++} : {string.Join(", ", packet.Select(p => p.LastName))}");
}

record Person(string LastName, string FirstName, int Age, string City);

Resultados:

> dotnet run linq-03.cs
Any(minor)=True, All(minor)=False, Any()=True
Count()=7, Count(Angers)=3
Sum(age)=221, Average(age)=31.57
Min(age)=15, Max(age)=52
MinBy(age)=moreau, MaxBy(age)=simon
First()=dupont, First(Paris)=martin, Last()=laurent
FirstOrDefault(Brest)=null
Single(Lyon)=laurent
Single(Angers) : InvalidOperationException : Sequence contains more than one matching element
First(Brest) : InvalidOperationException : Sequence contains no matching element
Distinct(cities)=[Angers, Paris, Nantes, Lyon]
DistinctBy(city)=[dupont, martin, leroy, laurent]
Take(2)=[dupont, martin], Skip(5)=[simon, laurent]
Skip(2).Take(2)=[durand, leroy], TakeWhile(length 6)=[dupont, martin, durand]
page 1 : dupont, martin, durand
page 2 : leroy, moreau, simon
page 3 : laurent

Comentários:

  • Linha 15: [Any] retorna [true] se pelo menos um elemento satisfizer a condição, e [All] se todos a satisfizerem. Sem parâmetros, [Any] indica se a sequência não está vazia;
  • Linhas 18–20: as agregações [Count], [Sum], [Average], [Min], [Max] calculam um valor com base na sequência inteira. [Count] aceita uma condição (uma lista também tem uma propriedade [Count], que é preferível ao método quando não há condição); [Sum], [Average], [Min] e [Max] aceitam uma lambda que especifica o valor a considerar para cada elemento;
  • Linha 22: [MinBy] e [MaxBy] (.NET 6) retornam o elemento (neste caso, a pessoa) cuja chave é mínima ou máxima, e não o valor da chave em si. Para uma sequência vazia de objetos (tipo de referência), retornam [null], daí o operador [?.];
  • linha 25: [First] retorna o primeiro elemento da sequência, ou o primeiro que satisfaz uma condição; [Last] retorna o último;
  • Linha 26: se nenhum elemento corresponder, [First] lança uma exceção (linha 11 dos resultados), ao passo que [FirstOrDefault] retorna o valor padrão do tipo, neste caso [null];
  • Linha 28: [Single] retorna o único elemento que satisfaz a condição e lança uma exceção se houver zero ou mais de um desses elementos (linha 10). Ele é usado quando a unicidade é uma regra dos dados, como na busca de um elemento por sua chave. [SingleOrDefault] retorna o valor padrão se não houver nenhum elemento;
  • linha 32: o resultado da chamada não é usado; ele é atribuído ao descarte [_] (C# 7) para sinalizá-lo;
  • linha 49: [Distinct] remove duplicatas; [DistinctBy] (.NET 6) mantém o primeiro elemento de cada valor de chave;
  • linhas 57–58: [Take(n)] mantém os n primeiros elementos, [Skip(n)] os ignora. Combinados, extraem uma “página” de resultados. [TakeWhile] mantém os elementos enquanto uma condição for satisfeita e para no primeiro elemento que não a satisfaz;
  • linha 62: [Chunk] (.NET 6) divide a sequência em arrays de 3 elementos, o último dos quais pode ser mais curto;
  • linha 64: a variável [page] é incrementada depois de ser usada na interpolação.

5.5.4. Tipos anônimos, agrupamentos, junções

O programa [linq-04.cs] apresenta os tipos anônimos e operações mais complexas:

// LINQ: tipos anônimos, agrupamentos, junções, conversões

List<Person> persons =
[
    new("dupont", "jean", 45, "Angers"),
    new("martin", "marie", 17, "Paris"),
    new("durand", "paul", 32, "Angers"),
    new("leroy", "sophie", 28, "Nantes"),
    new("moreau", "luc", 15, "Paris"),
    new("simon", "julie", 52, "Angers"),
    new("laurent", "marc", 32, "Lyon"),
];
List<City> cities =
[
    new("Angers", "Maine-et-Loire"),
    new("Nantes", "Loire-Atlantique"),
    new("Paris", "Paris"),
    new("Brest", "Finistère"),
];

// 1 - um tipo anônimo: um objeto cujo tipo, sem nome, é criado pelo compilador
var p1 = new { LastName = "dupont", Age = 45 };
Console.WriteLine($"[anonymous type] {p1}, p1.LastName={p1.LastName}");
// Select para um tipo anônimo: mantemos apenas as propriedades úteis
var summaries = persons.Where(p => p.Age > 40).Select(p => new { p.LastName, Decade = p.Age / 10 * 10 });
foreach (var r in summaries)
{
    Console.WriteLine($"  {r.LastName} is over {r.Decade} years old");
}

// 2 - GroupBy: agrupamento das pessoas por cidade
Console.WriteLine("[GroupBy]");
foreach (IGrouping<string, Person> group in persons.GroupBy(p => p.City))
{
    // um grupo tem uma chave (Key) e é ele próprio uma sequência de pessoas
    Console.WriteLine($"  {group.Key} : {group.Count()} person(s), average age {group.Average(p => p.Age):F1} ({string.Join(", ", group.Select(p => p.LastName))})");
}

// 3 - Join: associação de pessoas e cidades pelo nome da cidade
Console.WriteLine("[Join]");
var join = persons.Join(cities,
    p => p.City,                                     // chave do lado das pessoas
    c => c.Name,                                     // chave do lado das cidades
    (p, c) => new { p.LastName, c.Department });     // o que mantemos de um par
foreach (var j in join)
{
    Console.WriteLine($"  {j.LastName} lives in the department {j.Department}");
}
// a mesma junção na sintaxe de consulta: Lyon, ausente da lista de cidades, também desaparece
var join2 = from p in persons
            join c in cities on p.City equals c.Name
            where p.Age >= 18
            select $"{p.LastName}/{c.Department}";
Console.WriteLine($"[join in query syntax] {string.Join(", ", join2)}");

// 4 - conversões: ToList, ToArray, ToDictionary
List<string> adultNames = persons.Where(p => p.Age >= 18).Select(p => p.LastName).ToList();
Dictionary<string, int> agesByName = persons.ToDictionary(p => p.LastName, p => p.Age);
Console.WriteLine($"[ToList] {adultNames.Count} adults; [ToDictionary] agesByName[\"leroy\"]={agesByName["leroy"]}");

// 5 - .NET 9: CountBy, AggregateBy, Index
Console.WriteLine("[CountBy]");
foreach (KeyValuePair<string, int> pair in persons.CountBy(p => p.City))
{
    Console.WriteLine($"  {pair.Key}={pair.Value}");
}
Console.WriteLine("[AggregateBy: sum of the ages by city]");
foreach (var (city, total) in persons.AggregateBy(p => p.City, 0, (sum, p) => sum + p.Age))
{
    Console.WriteLine($"  {city}={total}");
}
Console.WriteLine("[Index]");
foreach (var (index, person) in persons.Where(p => p.Age < 30).Index())
{
    Console.WriteLine($"  {index} : {person.LastName}");
}

record Person(string LastName, string FirstName, int Age, string City);
record City(string Name, string Department);

Resultados:

> dotnet run linq-04.cs
[anonymous type] { LastName = dupont, Age = 45 }, p1.LastName=dupont
  dupont is over 40 years old
  simon is over 50 years old
[GroupBy]
  Angers : 3 person(s), average age 43.0 (dupont, durand, simon)
  Paris : 2 person(s), average age 16.0 (martin, moreau)
  Nantes : 1 person(s), average age 28.0 (leroy)
  Lyon : 1 person(s), average age 32.0 (laurent)
[Join]
  dupont lives in the department Maine-et-Loire
  martin lives in the department Paris
  durand lives in the department Maine-et-Loire
  leroy lives in the department Loire-Atlantique
  moreau lives in the department Paris
  simon lives in the department Maine-et-Loire
[join in query syntax] dupont/Maine-et-Loire, durand/Maine-et-Loire, leroy/Loire-Atlantique, simon/Maine-et-Loire
[ToList] 5 adults; [ToDictionary] agesByName["leroy"]=28
[CountBy]
  Angers=3
  Paris=2
  Nantes=1
  Lyon=1
[AggregateBy: sum of the ages by city]
  Angers=129
  Paris=32
  Nantes=28
  Lyon=32
[Index]
  0 : martin
  1 : leroy
  2 : moreau

Comentários:

  • Linha 22: um tipo anônimo (C# 3): a expressão [new { LastName = ..., Age = ... }] cria um objeto cuja classe sem nome é gerada pelo compilador com duas propriedades somente leitura, [LastName] e [Age]. Como esse tipo não tem nome, a variável deve ser declarada como [var]. O compilador, porém, conhece perfeitamente esse tipo: [p1.LastName] é validado em tempo de compilação, e o editor sugere as propriedades de [p1] no preenchimento automático;
  • linha 25: o principal uso dos tipos anônimos: em um [Select], manter apenas os dados úteis sem precisar declarar uma classe para eles. [p.LastName] é uma abreviação de [LastName = p.LastName];
  • Linha 33: [GroupBy] agrupa os elementos que têm a mesma chave. O resultado é uma sequência de grupos [IGrouping<TKey,TElement>]: cada grupo tem uma propriedade [Key], o valor comum da chave, e é ele próprio a sequência dos elementos do grupo, à qual podemos aplicar [Count], [Average], [Select]… (linha 36);
  • linhas 41–44: [Join] associa cada pessoa à cidade de mesmo nome. Seus parâmetros são a segunda sequência, a chave de junção de cada lado e uma lambda que constrói o resultado a partir de um par (pessoa, cidade). Como em uma junção SQL, [Join] retém apenas os pares que correspondem: Laurent, que mora em Lyon, ausente da lista de cidades, não aparece, nem Brest, que não tem nenhum morador;
  • linhas 50–53: a junção na sintaxe de consulta, que é mais legível: [join ... in ... on ... equals ...]. Um filtro, [where], é adicionado a ela. A sintaxe de consulta também inclui uma cláusula, [group ... by ...], para os agrupamentos;
  • linha 57: [ToList] (e [ToArray]) executa a consulta e armazena seus resultados em uma lista (um array);
  • linha 58: [ToDictionary] constrói um dicionário: a primeira lambda fornece a chave de cada elemento, a segunda, seu valor. Uma chave duplicada causa uma exceção;
  • Linha 63: [CountBy] (.NET 9) conta os elementos de cada valor de chave. Ele retorna uma sequência de pares [KeyValuePair<string,int>]. É um atalho para [GroupBy(p => p.City).Select(g => (g.Key, g.Count()))];
  • Linha 68: [AggregateBy] (.NET 9) acumula um valor para cada valor de chave: partindo de 0, para cada pessoa, sua idade é somada ao total de sua cidade. As tuplas retornadas são decompostas no laço [foreach];
  • linha 73: [Index] (.NET 9) associa cada elemento à sua posição na sequência, na forma de uma tupla (posição, elemento).

5.5.5. Execução adiada

Uma consulta LINQ não é executada quando é escrita, mas quando seu resultado é percorrido: é a execução adiada. O programa [linq-05.cs] demonstra isso por meio de lambdas que exibem o que estão fazendo:

// LINQ: execução adiada

List<int> numbers = [1, 2, 3, 4, 5, 6];

// 1 - definir uma consulta não a executa
Console.WriteLine("[definition of the query]");
IEnumerable<int> evenSquares = numbers
    .Where(n =>
    {
        Console.WriteLine($"  Where examines {n}");
        return n % 2 == 0;
    })
    .Select(n =>
    {
        Console.WriteLine($"  Select computes {n}*{n}");
        return n * n;
    });
Console.WriteLine("[the query is defined, nothing has been executed yet]");

// 2 - ela é executada quando é iterada, elemento por elemento
Console.WriteLine("[foreach]");
foreach (int c in evenSquares)
{
    Console.WriteLine($"  foreach receives {c}");
}

// 3 - a consulta é reavaliada a cada iteração: ela vê as modificações da fonte
IEnumerable<int> large = numbers.Where(n => n > 4);
Console.WriteLine($"[before adding] large=[{string.Join(", ", large)}]");
numbers.Add(10);
Console.WriteLine($"[after adding 10] large=[{string.Join(", ", large)}]");

// 4 - ToList executa a consulta imediatamente e armazena o resultado
List<int> snapshot = numbers.Where(n => n > 4).ToList();
numbers.Add(20);
Console.WriteLine($"[after adding 20] large=[{string.Join(", ", large)}], snapshot=[{string.Join(", ", snapshot)}]");

// 5 - os agregados (Count, Sum, First...) também são executados imediatamente
int howMany = numbers.Count(n => n > 4);
numbers.Add(30);
Console.WriteLine($"[after adding 30] howMany={howMany}, new Count={numbers.Count(n => n > 4)}");

// 6 - First interrompe a iteração assim que encontra um elemento
Console.WriteLine("[First on a query]");
int first = numbers.Where(n =>
{
    Console.WriteLine($"  Where examines {n}");
    return n > 2;
}).First();
Console.WriteLine($"  first={first}");

Resultados:

> dotnet run linq-05.cs
[definition of the query]
[the query is defined, nothing has been executed yet]
[foreach]
  Where examines 1
  Where examines 2
  Select computes 2*2
  foreach receives 4
  Where examines 3
  Where examines 4
  Select computes 4*4
  foreach receives 16
  Where examines 5
  Where examines 6
  Select computes 6*6
  foreach receives 36
[before adding] large=[5, 6]
[after adding 10] large=[5, 6, 10]
[after adding 20] large=[5, 6, 10, 20], snapshot=[5, 6, 10]
[after adding 30] howMany=4, new Count=5
[First on a query]
  Where examines 1
  Where examines 2
  Where examines 3
  first=3

Comentários:

  • Linhas 7–16: uma consulta que seleciona os números pares e depois calcula seus quadrados. As lambdas aqui são escritas com um corpo delimitado por chaves, que exibe uma mensagem antes de retornar seu valor com [return];
  • Linha 3 dos resultados: depois que a consulta foi definida, nada foi exibido: nem [Where] nem [Select] examinou ainda um único elemento. [evenSquares] não contém resultados, mas sim uma descrição de um cálculo;
  • Linhas 4–16: a consulta é executada durante o laço [foreach], elemento por elemento: cada número passa por [Where], depois por [Select] se for par e, em seguida, entra no laço antes que o próximo número seja examinado. São iteradores, como [Evens] em [linq-01.cs];
  • linhas 28–31: a consulta [large] é reavaliada a cada passagem: ela leva em conta o número 10 adicionado à lista após sua definição;
  • linha 34: [ToList] executa a consulta imediatamente e armazena seus resultados: [snapshot] é uma lista que não enxerga a adição do 20 (linha 19);
  • linha 39: os métodos que retornam um único valor ([Count], [Sum], [First], [Any]…) também percorrem a sequência imediatamente;
  • linhas 45–49: [First] para de percorrer assim que encontra um elemento: os números posteriores ao 3 nunca são examinados.

A execução adiada tem duas consequências práticas:

  • uma consulta percorrida várias vezes é executada várias vezes. Se seu cálculo for custoso, ou se for desejado um resultado fixo, ela é convertida de uma vez por todas com [ToList] ou [ToArray];
  • as consultas podem ser compostas sem custo: encadear [Where], [Select] e [Take] não cria nenhuma coleção intermediária, e apenas os elementos necessários são calculados.

Encontraremos o LINQ ao longo de todo o curso e veremos no Capítulo 7 como seus métodos são construídos.

5.6. Arquivos de texto

As classes de leitura e escrita de arquivos ficam no namespace [System.IO], que faz parte dos namespaces [using] implícitos.

5.6.1. A classe StreamReader

A classe [System.IO.StreamReader] permite ler o conteúdo de um arquivo de texto. Na verdade, ela é capaz de tratar streams que não são arquivos (uma conexão de rede, por exemplo). Eis algumas de suas propriedades e métodos.

Construtores:

construtor
função
[public StreamReader(string path)]
Cria um stream de leitura a partir do arquivo no caminho [path]. O conteúdo do arquivo pode ser codificado de várias maneiras; por padrão, é usada a codificação UTF-8. Outra sobrecarga permite especificar a codificação: [new StreamReader(path, Encoding.Latin1)]

Propriedades:

propriedade
função
[public bool EndOfStream { get; }]
[true] se o stream foi lido por inteiro

Métodos:

Método
Função
[public void Dispose()]
Fecha o stream e libera os recursos alocados para seu gerenciamento. Isso deve ser feito após o processamento do stream, o que é tratado pela instrução [using]. [Close] faz a mesma coisa
[public int Peek()]
retorna o próximo caractere do stream sem consumi-lo; -1 no final do stream
[public int Read()]
retorna o próximo caractere do stream e avança um caractere; -1 no final do stream
[public string? ReadLine()]
retorna a próxima linha do stream, sem o caractere de fim de linha, ou [null] se estiver no final do stream
[public string ReadToEnd()]
retorna o restante do stream, ou "" se estiver no final do stream

O programa [files-01.cs] é o seguinte:

// leitura de um arquivo de texto com StreamReader

// a pasta atual: é onde são procurados os arquivos designados por um nome relativo
Console.WriteLine($"Current folder: {Path.GetFileName(Environment.CurrentDirectory)}");
// o nome do arquivo pode ser passado como argumento; caso contrário, infos.txt
string fileName = args.Length > 0 ? args[0] : "infos.txt";
try
{
    // leitura 1: linha por linha
    Console.WriteLine("Reading 1----------------");
    using (var stream = new StreamReader(fileName))
    {
        string? line;
        // ReadLine retorna null no fim do arquivo
        while ((line = stream.ReadLine()) != null)
        {
            Console.WriteLine(line);
        }
    } // aqui o fluxo é fechado

    // leitura 2: o arquivo inteiro de uma vez, com uma declaração using
    Console.WriteLine("Reading 2----------------");
    using var stream2 = new StreamReader(fileName);
    Console.Write(stream2.ReadToEnd());
    // stream2 será fechado no fim do bloco que contém sua declaração, aqui o bloco try
}
catch (FileNotFoundException e)
{
    // e.FileName é o caminho completo do arquivo; exibimos apenas o nome
    Console.WriteLine($"{e.GetType().Name} : the file [{Path.GetFileName(e.FileName)}] does not exist");
}
catch (IOException e)
{
    // os outros erros de entrada/saída
    Console.WriteLine($"{e.GetType().Name} : {e.Message}");
}

Comentários:

  • linha 4: exibe o nome do diretório atual, aquele a partir do qual o comando [dotnet run] foi iniciado. Apenas o último elemento do caminho é exibido, com [Path.GetFileName], para não poluir os resultados com um caminho completo;
  • linha 6: o arquivo lido é [infos.txt] ou o passado como argumento. Por ser um caminho relativo, ele é procurado na pasta atual;
  • linha 11: a estrutura [using (stream = ...) { ... }] garante que o stream seja fechado no final do bloco, mesmo que ocorra uma exceção dentro dele. Isso elimina a necessidade de chamar explicitamente o método de fechamento. Ela se aplica a qualquer objeto que implemente a interface [IDisposable], isto é, qualquer objeto com um método [Dispose] que libere recursos (arquivo, conexão de rede, conexão com banco de dados etc.);
  • linhas 15–17: o arquivo é lido linha por linha. A atribuição [line = stream.ReadLine()] é uma expressão cujo valor é o de [line]: ele é comparado a [null], que indica o fim do arquivo. A variável [line] é do tipo [string?]: [ReadLine] pode receber o valor [null];
  • linha 23: uma declaração using (C# 8). Não há mais um bloco: a variável [stream2] será liberada no final do bloco que contém sua declaração, neste caso o bloco *[try]*. Essa sintaxe mais concisa é a mais comum hoje em dia;
  • linha 24: o arquivo é lido de uma só vez;
  • linhas 27–32: os erros de E/S são sinalizados por exceções derivadas de [IOException]*. *[FileNotFoundException]* é uma dessas exceções; por isso, ela é capturada primeiro. Sua propriedade *[FileName] contém o caminho completo do arquivo procurado.

O arquivo [infos.txt] é o seguinte:

1
2
3
12620:0:0
13190:0,05:631
15640:0,1:1290,5

Ele está localizado na pasta [05-classes-dotnet], a partir da qual o programa é executado:

> dotnet run files-01.cs
Current folder: 05-classes-dotnet
Reading 1----------------
12620:0:0
13190:0,05:631
15640:0,1:1290,5
Reading 2----------------
12620:0:0
13190:0,05:631
15640:0,1:1290,5

Com um arquivo inexistente:

1
2
3
4
> dotnet run files-01.cs -- xx.txt
Current folder: 05-classes-dotnet
Reading 1----------------
FileNotFoundException : the file [xx.txt] does not exist

Escolher a pasta atual para localizar os arquivos de dados é a abordagem natural para uma aplicação de arquivo único executada a partir de sua própria pasta. Em um projeto, o executável fica em uma subpasta [bin/Debug/net10.0] do projeto: veremos na aplicação de exemplo como copiar os arquivos de dados para lá e como localizá-los.

5.6.2. A classe StreamWriter

A classe [System.IO.StreamWriter] permite escrever em um arquivo de texto. Assim como a classe [StreamReader], ela é na verdade capaz de tratar streams que não são arquivos. Eis algumas de suas propriedades e métodos.

Construtores:

construtor
função
[public StreamWriter(string path)]
cria um stream de escrita para o arquivo no caminho [path]. O arquivo é criado ou sobrescrito, caso exista. Por padrão, o texto é codificado em UTF-8, sem BOM (veja abaixo)
[public StreamWriter(string path, bool append)]
se [append] for igual a [true], os dados são acrescentados ao final do arquivo existente

Propriedades:

propriedade
função
[public bool AutoFlush { get; set; }]
define o modo de escrita no arquivo. Se [AutoFlush] for igual a [false] (valor padrão), a escrita no stream não é imediata: o texto é escrito primeiro em um buffer e depois no arquivo, quando o buffer estiver cheio, quando for esvaziado explicitamente pelo método [Flush] ou quando o stream for fechado. Esse é o modo mais eficiente para arquivos, pois limita os acessos ao disco. Ele não é adequado a todos os streams, em particular aos streams de rede: em um diálogo entre dois parceiros, o que um escreve deve ser lido imediatamente pelo outro, e o stream de escrita deve estar no modo [AutoFlush=true]
[public string NewLine { get; set; }]
o caractere de fim de linha escrito por [WriteLine]. Por padrão, é o caractere de fim de linha do sistema: "\r\n" no Windows, "\n" no Linux e no macOS
[public Encoding Encoding { get; }]
a codificação utilizada

Métodos:

Método
função
[public void Dispose()]
Fecha o stream depois de gravar o conteúdo do buffer no arquivo. Deve ser feito após o processamento do stream; [Close] executa a mesma ação
[public void Flush()]
grava o conteúdo do buffer no arquivo sem esperar que ele esteja cheio
[public void Write(T value)]
escreve [value] no arquivo associado ao stream. Aqui, [T] não é um tipo genérico, mas simboliza o fato de que o método [Write] aceita diferentes tipos de parâmetros ([string], [int], [object]…)
[public void WriteLine(T value)]
igual a [Write] mas com o marcador de fim de linha ([NewLine]) acrescentado

O programa [files-02.cs] é o seguinte:

// escrita de um arquivo de texto com StreamWriter
const string fileName = "infos2.txt";
try
{
    // criação do arquivo de texto (se já existir, é sobrescrito)
    using (var stream = new StreamWriter(fileName))
    {
        Console.WriteLine($"AutoFlush mode: {stream.AutoFlush}, encoding: {stream.Encoding.WebName}");
        // laço enquanto a linha digitada não for vazia
        while (true)
        {
            Console.Write("line (nothing to stop): ");
            string line = (Console.ReadLine() ?? "").Trim();
            if (line == "")
            {
                break;
            }
            // escrita da linha no arquivo de texto
            stream.WriteLine(line);
        }
    } // fechamento do fluxo: o buffer é escrito no arquivo

    // verificação: lemos novamente o arquivo criado
    Console.WriteLine($"Content of {fileName} ({new FileInfo(fileName).Length} bytes):");
    using var reader = new StreamReader(fileName);
    Console.Write(reader.ReadToEnd());
}
catch (IOException e)
{
    Console.WriteLine($"The following error occurred: {e.Message}");
}

Resultados:

1
2
3
4
5
6
7
8
> dotnet run files-02.cs
AutoFlush mode: False, encoding: utf-8
line (nothing to stop): 1st line
line (nothing to stop): 2nd line
line (nothing to stop): 
Content of infos2.txt (18 bytes):
1st line
2nd line

Comentários:

  • linha 6: mais uma vez, usamos a instrução [using] para não precisar fechar o stream explicitamente. Esse fechamento ocorre automaticamente no final do bloco (chave de fechamento da linha 21). É esse fechamento que grava no arquivo o texto restante no buffer; sem ele, o arquivo poderia ficar incompleto;
  • linha 19: escreve uma linha no arquivo de texto;
  • linha 24: a classe [FileInfo] fornece informações sobre um arquivo, neste caso seu tamanho em bytes. Os 18 bytes se dividem assim: 16 caracteres, mais duas quebras de linha de um byte ("\n" no Linux, onde o código foi executado; no Windows, cada quebra de linha "\r\n" ocuparia 2 bytes);
  • linha 28: por que um [try / catch]? Poderíamos especificar um nome de arquivo na forma [dir1/dir2/file] com um diretório [dir1/dir2] que não existe, o que impossibilitaria a criação do arquivo. Seria então lançada uma exceção [DirectoryNotFoundException], derivada de [IOException]. Há outros casos possíveis de exceção (disco cheio, permissões insuficientes etc.).

5.6.3. As classes File, Path e Directory

Para operações comuns, a classe estática [File] elimina a necessidade de manipular streams: um único método abre o arquivo, lê ou escreve todo o seu conteúdo e depois o fecha. As classes estáticas [Path] e [Directory] tratam, respectivamente, de caminhos e de diretórios.

método
função
[File.ReadAllText(path)]
retorna o conteúdo do arquivo como uma string
[File.ReadAllLines(path)]
retorna as linhas do arquivo em um array [string[]]
[File.ReadLines(path)]
retorna as linhas do arquivo como uma sequência [IEnumerable<string>] lida sob demanda
[File.WriteAllText(path, contents)]
cria (ou sobrescreve) o arquivo e escreve nele [contents]; [WriteAllLines] escreve uma coleção de linhas
[File.AppendAllText(path, contents)], [File.AppendAllLines(path, lines)]
adiciona texto (linhas) ao final do arquivo (que é criado se não existir)
[File.ReadAllBytes(path)], [File.WriteAllBytes(path, bytes)]
lê e escreve o arquivo como um array de bytes
[File.Exists(path)], [File.Delete(path)], [File.Copy(source, dest)], [File.Move(source, dest)]
verifica se um arquivo existe, o exclui, o copia ou o move
[Path.Combine(p1, p2, ...)]
constrói um caminho a partir de seus elementos, usando o separador do sistema
[Path.GetFileName(path)], [Path.GetExtension(path)], [Path.GetDirectoryName(path)]
extrai de um caminho o nome do arquivo, a extensão do arquivo e a pasta
[Directory.CreateDirectory(path)]
cria a pasta e suas pastas ancestrais, se não existirem
[Directory.GetFiles(path, pattern)], [Directory.EnumerateFiles(path, pattern)]
arquivos da pasta cujos nomes correspondem ao padrão ([*.txt]…), em um array ou em uma sequência
[Directory.Exists(path)], [Directory.Delete(path, recursive)]
verifica a existência de uma pasta e a exclui (juntamente com seu conteúdo se [recursive] for igual a [true])

O programa [files-03.cs] os utiliza:

using System.Text;

// as classes estáticas File, Path e Directory

// Path.Combine constrói um caminho com o separador do sistema (\ no Windows, / no Linux)
string folder = "data";
string path = Path.Combine(folder, "cities.txt");
Console.WriteLine($"path={path}, name={Path.GetFileName(path)}, without extension={Path.GetFileNameWithoutExtension(path)}, extension={Path.GetExtension(path)}");

// Directory.CreateDirectory cria a pasta (e seus pais) se ela não existir
Directory.CreateDirectory(folder);

// File.WriteAllText: cria (ou sobrescreve) um arquivo com o texto dado, em UTF-8 sem BOM
File.WriteAllText(path, "Angers\nNantes\n");
// File.AppendAllLines: adiciona linhas no fim do arquivo
File.AppendAllLines(path, ["Paris", "Lyon"]);
// File.ReadAllLines: todas as linhas em um array
string[] lines = File.ReadAllLines(path);
Console.WriteLine($"ReadAllLines : {lines.Length} lines [{string.Join(", ", lines)}]");
// File.ReadAllText: o arquivo inteiro em uma string
Console.WriteLine($"ReadAllText : {File.ReadAllText(path).Length} characters");
// File.ReadLines: as linhas são lidas uma a uma, sob demanda (IEnumerable<string>)
foreach (string city in File.ReadLines(path).Where(l => l.StartsWith('N') || l.StartsWith('L')))
{
    Console.WriteLine($"ReadLines + Where : {city}");
}

// a codificação: UTF-8 sem BOM por padrão; outra pode ser imposta
string text = "café";
File.WriteAllText(Path.Combine(folder, "utf8.txt"), text);
File.WriteAllText(Path.Combine(folder, "utf8bom.txt"), text, new UTF8Encoding(true));
File.WriteAllText(Path.Combine(folder, "latin1.txt"), text, Encoding.Latin1);
foreach (string name in new[] { "utf8.txt", "utf8bom.txt", "latin1.txt" })
{
    byte[] bytes = File.ReadAllBytes(Path.Combine(folder, name));
    Console.WriteLine($"{name,-12}: {bytes.Length} bytes: {Convert.ToHexString(bytes)}");
}
// um arquivo Latin-1 relido como UTF-8: os caracteres acentuados são perdidos
Console.WriteLine($"latin1.txt read as UTF-8: {File.ReadAllText(Path.Combine(folder, "latin1.txt"))}");
Console.WriteLine($"latin1.txt read as Latin-1: {File.ReadAllText(Path.Combine(folder, "latin1.txt"), Encoding.Latin1)}");

// File.Exists, Directory.GetFiles
Console.WriteLine($"Exists(cities.txt)={File.Exists(path)}, Exists(xx.txt)={File.Exists(Path.Combine(folder, "xx.txt"))}");
foreach (string file in Directory.GetFiles(folder, "*.txt").Order())
{
    Console.WriteLine($"  {Path.GetFileName(file),-12} {new FileInfo(file).Length,3} bytes");
}

// limpeza: exclusão da pasta e de seu conteúdo
Directory.Delete(folder, recursive: true);
Console.WriteLine($"after Delete: Directory.Exists={Directory.Exists(folder)}");

Resultados:

> dotnet run files-03.cs
path=data/cities.txt, name=cities.txt, without extension=cities, extension=.txt
ReadAllLines : 4 lines [Angers, Nantes, Paris, Lyon]
ReadAllText : 25 characters
ReadLines + Where : Nantes
ReadLines + Where : Lyon
utf8.txt    : 5 bytes: 636166C3A9
utf8bom.txt : 8 bytes: EFBBBF636166C3A9
latin1.txt  : 4 bytes: 636166E9
latin1.txt read as UTF-8: caf�
latin1.txt read as Latin-1: café
Exists(cities.txt)=True, Exists(xx.txt)=False
  cities.txt    25 bytes
  latin1.txt     4 bytes
  utf8.txt       5 bytes
  utf8bom.txt    8 bytes
after Delete: Directory.Exists=False

Comentários:

  • Linha 7: [Path.Combine] usa o separador de caminhos do sistema. Os exercícios do curso foram executados no Linux: o caminho resultante é [data/cities.txt]; no Windows, seria [data\cities.txt]. Construir caminhos com [Path.Combine] em vez de concatenar strings torna o código portável;
  • linha 11: criar a pasta [data] não causa erro se ela já existir;
  • Linhas 14–18: escrita, acréscimo e leitura, cada uma em uma única instrução;
  • linha 23: [File.ReadLines] retorna uma sequência: as linhas são lidas uma a uma à medida que o laço avança, como os elementos de um iterador. É possível aplicar o LINQ a ela e, assim, processar um arquivo de vários gigabytes sem carregá-lo na memória, o que [ReadAllLines] faria. O arquivo é fechado no final da iteração;
  • linhas 29–36: o mesmo texto “café” é escrito usando três codificações, e depois os bytes dos arquivos são exibidos em hexadecimal:
    • em UTF-8, a codificação padrão do .NET, os caracteres acentuados ocupam 2 bytes (é = C3 A9) e os demais, 1 byte: 5 bytes para 4 caracteres;
    • em UTF-8 com BOM (Byte Order Mark), o arquivo começa com os 3 bytes EF BB BF, que indicam aos programas que o arquivo está codificado em UTF-8. [new UTF8Encoding(true)] instrui o sistema a escrever esse BOM;
    • em Latin-1 (ISO-8859-1), a codificação tradicional dos textos da Europa Ocidental, cada caractere ocupa um byte (é = E9);
  • Linha 39: ler um arquivo com uma codificação diferente da usada para escrevê-lo altera os caracteres acentuados: o byte E9, no final do arquivo, é inválido em UTF-8, e cada byte inválido é substituído pelo caractere �. Na leitura, [File.ReadAllText] e [StreamReader] reconhecem o BOM, se estiver presente; caso contrário, assumem UTF-8, a menos que outra codificação seja especificada (linha 40). Hoje, a regra é simples: os arquivos de texto são escritos e lidos em UTF-8;
  • linha 44: os nomes dos arquivos de texto da pasta. [GetFiles] não garante a ordem dos nomes; o método do LINQ [Order] (.NET 7) os ordena;
  • linha 50: exclui a pasta e seu conteúdo. O parâmetro é passado por nome, [recursive: true], o que torna a chamada mais legível que um simples [true] (argumentos nomeados, Capítulo 3).

Todos esses métodos têm versões assíncronas ([File.ReadAllTextAsync], [File.ReadAllLinesAsync]…): vamos utilizá-las no Capítulo 9, dedicado à programação assíncrona.

5.7. Arquivos binários

5.7.1. As classes BinaryWriter e BinaryReader

As classes [System.IO.BinaryWriter] e [System.IO.BinaryReader] são usadas para escrever e ler arquivos binários. Em um arquivo desse tipo, os dados não são escritos como texto, mas em sua forma interna: um [int] sempre ocupa 4 bytes, qualquer que seja seu valor.

Considere a seguinte aplicação:

1
2
3
4
// sintaxe: dotnet run files-04.cs -- text binary logs
// lemos um arquivo de texto (text) e armazenamos seu conteúdo em um arquivo binário (binary)
// o arquivo de texto tem linhas da forma name : age que escrevemos na forma (string, int)
// (logs) é um arquivo de log de texto

O arquivo de texto [persons1.txt] tem o seguinte conteúdo:

1
2
3
4
5
6
7
8
9
paul : 10
helene : 15

jacques : 11
sylvain : 12
xx : -1

xx: yy : zz
xx : yy

O programa [files-04.cs] é o seguinte:

// sintaxe: dotnet run files-04.cs -- text binary logs
// lemos um arquivo de texto (text) e armazenamos seu conteúdo em um arquivo binário (binary)
// o arquivo de texto tem linhas da forma name : age que escrevemos na forma (string, int)
// (logs) é um arquivo de log de texto

// são necessários 3 argumentos
if (args.Length != 3)
{
    Console.WriteLine("syntax: dotnet run files-04.cs -- text binary logs");
    return 1;
}
try
{
    // abertura do arquivo de texto para leitura
    using var input = new StreamReader(args[0]);
    // abertura do arquivo binário para escrita
    using var output = new BinaryWriter(new FileStream(args[1], FileMode.Create, FileAccess.Write));
    // abertura do arquivo de log para escrita
    using var logs = new StreamWriter(args[2]);
    // processamento do arquivo de texto
    string? line;
    int lineNumber = 0, nbPersons = 0;
    while ((line = input.ReadLine()) != null)
    {
        // mais uma linha
        lineNumber++;
        // linha vazia? a ignoramos
        if (line.Trim() == "")
        {
            continue;
        }
        // uma linha name : age
        string[] fields = line.Split(':', StringSplitOptions.TrimEntries);
        // precisamos de 2 campos
        if (fields.Length != 2)
        {
            logs.WriteLine($"Line no. [{lineNumber}] of the file [{args[0]}] has an incorrect number of fields");
            continue;
        }
        // o 1º campo não deve ser vazio
        bool error = false;
        string name = fields[0];
        if (name == "")
        {
            logs.WriteLine($"Line no. [{lineNumber}] of the file [{args[0]}] has an empty name");
            error = true;
        }
        // o segundo campo deve ser um inteiro >= 0
        if (!int.TryParse(fields[1], out int age) || age < 0)
        {
            logs.WriteLine($"Line no. [{lineNumber}] of the file [{args[0]}] has an incorrect age [{fields[1]}]");
            error = true;
        }
        // se não houver erro, escrevemos os dados no arquivo binário
        if (!error)
        {
            output.Write(name);
            output.Write(age);
            nbPersons++;
        }
    }
    Console.WriteLine($"{lineNumber} lines read, {nbPersons} persons written to [{args[1]}], errors in [{args[2]}]");
    // fim do bloco try: os três fluxos são fechados aqui, na ordem inversa de sua abertura
}
catch (FileNotFoundException e)
{
    // e.FileName é o caminho completo do arquivo; exibimos apenas o nome
    Console.WriteLine($"The file [{Path.GetFileName(e.FileName)}] does not exist");
    return 2;
}
catch (IOException e)
{
    Console.WriteLine($"The following error occurred: {e.GetType().Name} : {e.Message}");
    return 3;
}
return 0;

Vejamos mais de perto as operações que envolvem a classe [BinaryWriter]:

  • Linha 17: o objeto [BinaryWriter] é aberto pela operação [new BinaryWriter(new FileStream(args[1], FileMode.Create, FileAccess.Write))]. O argumento do construtor deve ser um stream ([Stream]). Aqui, é um stream criado a partir de um arquivo ([FileStream]), para o qual especificamos:
    • o nome;
    • a operação a ser realizada, neste caso [FileMode.Create] para criar o arquivo (ou sobrescrevê-lo, se existir);
    • o tipo de acesso, neste caso [FileAccess.Write] para acesso de escrita ao arquivo;
  • linhas 57–58: as operações de escrita. A classe [BinaryWriter] tem métodos [Write] sobrecarregados para escrever os diversos tipos de dados simples ([int], [double], [decimal], [bool], [string]...);
  • linhas 15–19: os três streams são abertos com declarações [using]. Eles serão fechados no final do bloco [try], na ordem inversa de sua abertura. O curso de 2008 os fechava em uma cláusula [finally] após verificar que não eram [null]: a declaração [using] faz o mesmo em uma única linha;
  • linha 10: as instruções de nível superior podem terminar com um [return n]; n é então o código de saída do programa, que um script pode verificar (0: sucesso);
  • linha 33: a opção [TrimEntries] remove os espaços ao redor do nome e da idade;
  • linha 49: a idade deve ser um inteiro positivo ou zero. Graças ao comportamento de curto-circuito do operador [||], a condição [age < 0] só é avaliada se a conversão tiver sido bem-sucedida.

Os três argumentos do programa são passados após [--] no [dotnet run] comando. Os resultados são os seguintes:

> dotnet run files-04.cs -- persons1.txt persons1.bin logs.txt
9 lines read, 4 persons written to [persons1.bin], errors in [logs.txt]

O arquivo de log [logs.txt] contém o seguinte:

1
2
3
4
> cat logs.txt
Line no. [6] of the file [persons1.txt] has an incorrect age [-1]
Line no. [8] of the file [persons1.txt] has an incorrect number of fields
Line no. [9] of the file [persons1.txt] has an incorrect age [yy]

O conteúdo do arquivo binário [persons1.bin] pode ser exibido em hexadecimal com o comando Linux [od] (no Windows, o comando PowerShell [Format-Hex] produz uma exibição semelhante):

1
2
3
4
5
> od -A d -t x1z persons1.bin
0000000 04 70 61 75 6c 0a 00 00 00 06 68 65 6c 65 6e 65  >.paul.....helene<
0000016 0f 00 00 00 07 6a 61 63 71 75 65 73 0b 00 00 00  >.....jacques....<
0000032 07 73 79 6c 76 61 69 6e 0c 00 00 00              >.sylvain....<
0000044

Isso mostra como [BinaryWriter] grava os dados:

  • uma string é gravada precedida de seu comprimento em bytes: o byte 04 seguido dos 4 bytes de “paul” (70 61 75 6c);
  • um inteiro [int] é gravado em 4 bytes, com o byte menos significativo primeiro: 10 é gravado como 0a 00 00 00;
  • os dados são gravados um após o outro, sem separadores nem quebras de linha: o arquivo tem 44 bytes (linha 5: com a opção [-A d], [od] exibe as posições em decimal).

Para ler esse arquivo, é preciso, portanto, conhecer a ordem e o tipo exatos dos dados gravados. É isso que o programa [files-05.cs] faz; ele realiza a operação inversa: lê o arquivo binário para criar um arquivo de texto. Se o arquivo de texto resultante contiver os dados corretos do arquivo original, saberemos que a conversão texto → binário → texto foi bem-sucedida.

// sintaxe: dotnet run files-05.cs -- binary text
// lemos um arquivo binário (binary) e armazenamos seu conteúdo em um arquivo de texto (text)
// o arquivo binário contém pares (string, int)
// o arquivo de texto terá linhas da forma name:age

// são necessários 2 argumentos
if (args.Length != 2)
{
    Console.WriteLine("syntax: dotnet run files-05.cs -- binary text");
    return 1;
}
try
{
    // abertura do arquivo binário para leitura
    using var input = new BinaryReader(new FileStream(args[0], FileMode.Open, FileAccess.Read));
    // abertura do arquivo de texto para escrita
    using var output = new StreamWriter(args[1]);
    // processamento do arquivo binário, enquanto não estivermos no fim do fluxo
    int nbPersons = 0;
    while (input.BaseStream.Position < input.BaseStream.Length)
    {
        // leitura de name, depois age: na ordem em que foram escritos
        string name = input.ReadString();
        int age = input.ReadInt32();
        // escrita no arquivo de texto
        output.WriteLine($"{name}:{age}");
        nbPersons++;
    }
    Console.WriteLine($"{nbPersons} persons read from [{args[0]}] and written to [{args[1]}]");
}
catch (EndOfStreamException)
{
    // o arquivo termina no meio de um registro
    Console.WriteLine($"The file [{args[0]}] is truncated");
    return 2;
}
catch (FileNotFoundException e)
{
    // e.FileName é o caminho completo do arquivo; exibimos apenas o nome
    Console.WriteLine($"The file [{Path.GetFileName(e.FileName)}] does not exist");
    return 3;
}
catch (IOException e)
{
    Console.WriteLine($"The following error occurred: {e.GetType().Name} : {e.Message}");
    return 4;
}
return 0;

Vamos examinar mais de perto as operações com a classe [BinaryReader]:

  • linha 15: o objeto [BinaryReader] é aberto sobre um fluxo [FileStream] usando o modo [FileMode.Open] (para abrir um arquivo existente) e o modo de acesso [FileAccess.Read] (acesso somente leitura);
  • Linhas 23–24: operações de leitura. A classe [BinaryReader] fornece os métodos [ReadXX] para ler diversos tipos de dados simples: [ReadString], [ReadInt32], [ReadDouble], [ReadDecimal], [ReadBoolean]... Eles devem ser chamados na ordem das gravações;
  • Linha 20: a propriedade [BaseStream] fornece o fluxo subjacente, neste caso [FileStream]. A leitura continua até que a posição atual no arquivo alcance o fim do arquivo. A versão de 2008 lia indefinidamente e detectava o fim do arquivo por meio da exceção [EndOfStreamException]: uma exceção deve permanecer excepcional, e o fim de um arquivo não é;
  • linha 31: essa exceção agora sinaliza uma anomalia verdadeira: um arquivo que termina no meio de um registro.

Vamos executar o programa sobre o arquivo [persons1.bin] gerado anteriormente:

> dotnet run files-05.cs -- persons1.bin persons2.txt
4 persons read from [persons1.bin] and written to [persons2.txt]

O conteúdo de [persons2.txt] é o seguinte:

1
2
3
4
5
> cat persons2.txt
paul:10
helene:15
jacques:11
sylvain:12

Encontramos as 4 pessoas válidas do arquivo [persons1.txt]. Com um arquivo [truncated.bin] formado pelos primeiros 30 bytes de [persons1.bin], a leitura da idade de Jacques falha:

> dotnet run files-05.cs -- truncated.bin truncated.txt
The file [truncated.bin] is truncated

5.7.2. A serialização JSON

Gravar e ler um arquivo binário byte a byte é trabalhoso, e a menor discrepância entre a gravação e a leitura produz resultados incorretos. Geralmente é preferível serializar os objetos: convertê-los automaticamente em uma sequência de bytes ou de caracteres e, depois, desserializá-los para reconstruí-los.

O .NET oferecia a classe [BinaryFormatter] para essa finalidade, que serializava objetos em um formato binário específico do .NET. Ela agora foi removida: foi declarada obsoleta no .NET 5 e sua implementação foi removida no .NET 9, porque a desserialização de dados de origem não confiável com [BinaryFormatter] permitia a execução de código arbitrário. A Microsoft recomenda substituí-la pela serialização JSON da biblioteca [System.Text.Json], integrada ao .NET desde o .NET Core 3.0.

JSON (JavaScript Object Notation) é um formato textual, legível por humanos e universal: é o formato de troca dos serviços web (Capítulo 13) e de numerosos arquivos de configuração. Um objeto é escrito entre chaves na forma de pares "propriedade":valor, e os arrays são delimitados por colchetes.

A classe estática [System.Text.Json.JsonSerializer] tem dois métodos principais:

método
função
[string Serialize<T>(T value, JsonSerializerOptions? options = null)]
retorna o texto JSON que representa o objeto [value]
[T? Deserialize<T>(string json, JsonSerializerOptions? options = null)]
reconstrói um objeto do tipo [T] a partir do texto JSON [json]; lança uma [JsonException] se o texto estiver incorreto

O programa [files-06.cs] os utiliza:

#:property PublishAot=false
using System.Text.Encodings.Web;
using System.Text.Json;
using System.Text.Json.Serialization;
using System.Text.Unicode;

// serialização JSON com System.Text.Json

List<Person> persons =
[
    new("paul", 10, ["football"]),
    new("hélène", 15, ["piano", "tennis"]),
    new("jacques", 11, []),
];

// 1 - serialização padrão: uma única linha, caracteres não ASCII com escape
string json = JsonSerializer.Serialize(persons[1]);
Console.WriteLine($"[default] {json}");

// 2 - opções: indentação, caracteres acentuados mantidos como estão
var options = new JsonSerializerOptions
{
    WriteIndented = true,
    Encoder = JavaScriptEncoder.Create(UnicodeRanges.All)
};
json = JsonSerializer.Serialize(persons, options);
// escrita em um arquivo de texto
File.WriteAllText("persons.json", json);
Console.WriteLine("[persons.json]");
Console.WriteLine(File.ReadAllText("persons.json"));

// 3 - desserialização: de texto JSON para objetos
string text = File.ReadAllText("persons.json");
List<Person>? readBack = JsonSerializer.Deserialize<List<Person>>(text);
Console.WriteLine($"[read back] {readBack?.Count} persons");
foreach (Person p in readBack ?? [])
{
    Console.WriteLine($"  {p.Name}, {p.Age} years old, hobbies: [{string.Join(", ", p.Hobbies)}]");
}

// 4 - sem atributos: as opções "Web" colocam os nomes das propriedades em camelCase
var web = new JsonSerializerOptions(JsonSerializerDefaults.Web);
string jsonArticle = JsonSerializer.Serialize(new Article("A12", 12.5m), web);
Console.WriteLine($"[Web options] {jsonArticle}");
// e ignoram maiúsculas e minúsculas na leitura
Article? article = JsonSerializer.Deserialize<Article>("""{ "CODE": "B7", "price": 3 }""", web);
Console.WriteLine($"[Web options] {article}");

// 5 - um documento JSON incorreto causa uma JsonException
try
{
    JsonSerializer.Deserialize<Person>("""{ "name": "x", "age": "twelve" }""");
}
catch (JsonException e)
{
    Console.WriteLine($"[error] {e.GetType().Name} : {e.Message}");
}

// uma pessoa; os atributos [JsonPropertyName] definem os nomes das propriedades JSON
record Person(
    [property: JsonPropertyName("name")] string Name,
    [property: JsonPropertyName("age")] int Age,
    [property: JsonPropertyName("hobbies")] List<string> Hobbies);

// um artigo, sem atributos
record Article(string Code, decimal Price);

Resultados:

> dotnet run files-06.cs
[default] {"name":"h\u00E9l\u00E8ne","age":15,"hobbies":["piano","tennis"]}
[persons.json]
[
  {
    "name": "paul",
    "age": 10,
    "hobbies": [
      "football"
    ]
  },
  {
    "name": "hélène",
    "age": 15,
    "hobbies": [
      "piano",
      "tennis"
    ]
  },
  {
    "name": "jacques",
    "age": 11,
    "hobbies": []
  }
]
[read back] 3 persons
  paul, 10 years old, hobbies: [football]
  hélène, 15 years old, hobbies: [piano, tennis]
  jacques, 11 years old, hobbies: []
[Web options] {"code":"A12","price":12.5}
[Web options] Article { Code = B7, Price = 3 }
[error] JsonException : The JSON value could not be converted to Person. Path: $.age | LineNumber: 0 | BytePositionInLine: 30.

Comentários:

  • Linha 1: uma diretiva para aplicativos de arquivo único. Por padrão, eles são configurados para compilação nativa (AOT, "ahead of time"), que produz um executável autônomo, mas desabilita os mecanismos que dependem da descoberta de tipos em tempo de execução (reflexão). Ora, [JsonSerializer] usa reflexão por padrão para descobrir as propriedades dos objetos a serem serializados: sem essa diretiva, a compilação produz avisos e a execução falha. Um projeto [.csproj] padrão, como o do aplicativo de exemplo, não tem essa restrição. Para um aplicativo compilado nativamente, [System.Text.Json] oferece um gerador de código-fonte (uma classe derivada de [JsonSerializerContext]) que gera o código de serialização em tempo de compilação: não o abordaremos aqui;
  • linhas 60–63: o record [Person] a ser serializado. Suas propriedades levam o atributo [JsonPropertyName], que define o nome da propriedade no texto JSON como [name] em vez de [Name]. Em um record posicional, [property: ...] indica que o atributo se aplica à propriedade gerada e não ao parâmetro do construtor;
  • linha 17: serialização de um objeto com as opções padrão: o texto é escrito em uma única linha e os caracteres não ASCII são escapados: [é] torna-se [\u00E9]. O texto continua correto, mas é difícil de ler;
  • Linhas 21–26: a opção [WriteIndented] produz um texto indentado em várias linhas; a opção [Encoder] especifica quais caracteres devem ser deixados como estão — neste caso, todos os caracteres Unicode. Uma lista é serializada em um array JSON;
  • linha 28: o texto JSON é salvo em um arquivo de texto: é assim que hoje se substitui a serialização binária;
  • linha 34: a desserialização reconstrói a lista. [Deserialize] cria os objetos [Person] chamando o construtor do record, cujos parâmetros são associados às propriedades JSON de mesmo nome. O resultado é do tipo [List<Person>?]: o texto JSON [null] é um documento válido que resulta em [null];
  • linha 42: as opções “Web” — usadas por padrão pelos serviços web do ASP.NET Core — gravam os nomes das propriedades em camelCase (primeira letra minúscula): [Code] torna-se [code], sem atributo. Na leitura, não diferenciam maiúsculas de minúsculas: [CODE] é aceito (linha 31);
  • linha 52: um documento JSON inválido — neste caso, uma string onde se espera um número — dispara uma exceção [JsonException], cuja mensagem indica o local do erro.

Usaremos JSON no próximo aplicativo de exemplo e ao longo do curso.

5.8. Expressões regulares

A classe [System.Text.RegularExpressions.Regex] permite o uso de expressões regulares. Elas permitem validar o formato de uma string. Por exemplo, é possível verificar se uma string que representa uma data está de fato no formato dd/mm/aa. Para isso, usa-se um padrão e compara-se a string com esse padrão. Neste exemplo, d, m e a devem ser dígitos. O padrão de um formato de data válido é, portanto, [\d\d/\d\d/\d\d], em que o símbolo [\d] representa um dígito. Os símbolos que podem ser usados em um padrão são os seguintes:

caractere
descrição
[\]
marca o caractere seguinte como caractere especial ou literal. Por exemplo, [n] corresponde ao caractere n, [\n] corresponde a um caractere de nova linha, [\\] corresponde a \ e [\(] corresponde a (
[^]
corresponde ao início da string
[$]
corresponde ao fim da string
[*]
corresponde ao elemento anterior zero ou mais vezes. Assim, [zo*] corresponde a z ou zoo
[+]
corresponde ao elemento anterior uma ou mais vezes. Assim, [zo+] corresponde a "zoo", mas não a "z"
[?]
corresponde ao elemento anterior zero ou uma vez. Por exemplo, [a?ve?] corresponde a “ve” em “lever”
[.]
corresponde a qualquer caractere isolado, exceto o caractere de nova linha
[(pattern)]
procura o padrão e armazena a correspondência (um grupo). A substring correspondente pode ser extraída da coleção [Groups] do resultado. Para encontrar correspondências com caracteres entre parênteses, use [\(] ou [\)]
[x|y]
corresponde a x ou y. Por exemplo, [z|foot] corresponde a z ou foot; [(z|f)oo] corresponde a zoo ou foo
[{n}]
n é um inteiro não negativo. Corresponde exatamente n vezes ao elemento anterior. Por exemplo, [o{2}] não corresponde ao o de Bob, mas aos dois primeiros o de fooooot
[{n,}]
corresponde ao elemento anterior pelo menos n vezes. Por exemplo, [o{2,}] não corresponde ao 'o' de 'Bob', mas corresponde a todos os 'o' de 'fooooot'. [o{1,}] equivale a [o+], e [o{0,}] equivale a [o*]
[{n,m}]
corresponde ao elemento anterior pelo menos n vezes e no máximo m vezes. Por exemplo, [o{1,3}] corresponde aos três primeiros “o” de “foooooot”; [o{0,1}] equivale a [o?]
[xyz]
conjunto de caracteres: corresponde a um dos caracteres especificados. Por exemplo, [abc] corresponde à letra “a” em “plat”
[^xyz]
conjunto negativo de caracteres: corresponde a qualquer caractere não listado. Por exemplo, [^abc] corresponde a "p" em "plat"
[a-z]
intervalo de caracteres: corresponde a qualquer caractere do intervalo especificado, neste caso uma letra minúscula sem acento
[^m-z]
intervalo negativo de caracteres: corresponde a qualquer caractere que não esteja entre 'm' e 'z'
[\b]
corresponde a um limite de palavra, isto é, à posição entre um caractere de palavra e um caractere que não é de palavra. Por exemplo, [er\b] corresponde a "er" em "lever", mas não a "er" em "verb"
[\B]
corresponde a uma posição que não é um limite de palavra. [en*t\B] corresponde a “ent” em “entertain”
[\d]
corresponde a um dígito; equivale a [0-9] (no .NET, também para dígitos de outros alfabetos Unicode)
[\D]
corresponde a um caractere que não é um dígito
[\f], [\n], [\r], [\t], [\v]
correspondem, respectivamente, aos caracteres de avanço de página, nova linha, retorno de carro, tabulação e tabulação vertical
[\s]
corresponde a qualquer espaço em branco: espaço, tabulação, avanço de página, quebra de linha… Equivale a [ \f\n\r\t\v], mais outros caracteres de espaço em branco Unicode (espaço não separável etc.)
[\S]
corresponde a qualquer caractere que não seja um espaço em branco
[\w]
corresponde a qualquer caractere de palavra: letra (com ou sem acento), dígito ou sublinhado
[\W]
corresponde a qualquer caractere que não seja um caractere de palavra
[\num]
num é um inteiro positivo: refere-se ao grupo de número num. Por exemplo, [(.)\1] corresponde a dois caracteres idênticos consecutivos
[\xnn], [\unnnn]
corresponde ao caractere hexadecimal nn (2 dígitos) ou nnnn (4 dígitos). Por exemplo, [\x41] corresponde a A

Um elemento em um padrão pode aparecer uma ou várias vezes. Vejamos alguns exemplos com o símbolo [\d], que representa um único dígito:

padrão
Significado
[\d]
um dígito
[\d?]
0 ou 1 dígito
[\d*]
0 ou mais dígitos
[\d+]
1 ou mais dígitos
[\d{2}]
2 dígitos
[\d{3,}]
No mínimo 3 dígitos
[\d{5,7}]
entre 5 e 7 dígitos

Imaginemos agora um padrão capaz de descrever o formato esperado para uma string:

string-alvo
padrão
uma data no formato dd/mm/aa
[\d{2}/\d{2}/\d{2}]
uma hora no formato hh:mm:ss
[\d{2}:\d{2}:\d{2}]
um inteiro sem sinal
[\d+]
uma sequência de espaços, que pode ser vazia
[\s*]
um inteiro sem sinal que pode ser precedido ou seguido de espaços
[\s*\d+\s*]
um inteiro que pode ter sinal e ser precedido ou seguido de espaços
[\s*[+-]?\s*\d+\s*]
um número real sem sinal que pode ser precedido ou seguido de espaços
[\s*\d+(\.\d*)?\s*]
um número real que pode ter sinal e ser precedido ou seguido de espaços
[\s*[+-]?\s*\d+(\.\d*)?\s*]
uma string que contém a palavra "just"
[\bjust\b]

O curso de 2008 usava [+|-] para o sinal: entre colchetes, o caractere [|] não tem significado específico, e esse formato aceitava também o sinal | antes de um número. Ele usava ainda [(.\d*)] para a parte decimal: o ponto sem escape ali representa qualquer caractere. Os padrões acima foram corrigidos.

Você pode especificar em que parte da string o padrão deve ser procurado:

padrão
significado
[^pattern]
o padrão inicia a string
[pattern$]
o padrão termina a string
[^pattern$]
o padrão inicia e termina a string
[pattern]
o padrão é procurado em qualquer lugar da string, a partir do início da string
string procurada
padrão
uma string que termina com um ponto de exclamação
[!$]
uma string que termina com um ponto final
[\.$]
uma string que começa com a sequência //
[^//]
uma string formada por uma única palavra, possivelmente precedida ou seguida de espaços
[^\s*\w+\s*$]
uma string formada por exatamente duas palavras, possivelmente precedidas ou seguidas de espaços
[^\s*\w+\s+\w+\s*$]
uma string que contém a palavra "secret"
[\bsecret\b]

É possível “extrair” subconjuntos de um padrão. Assim, não só podemos verificar se uma string corresponde a um determinado padrão, como também extrair dessa string os elementos correspondentes aos subconjuntos do padrão que foram colocados entre parênteses. Por exemplo, se você analisa uma string que contém uma data no formato dd/mm/aa e deseja também extrair os componentes dd, mm e aa dessa data, usaria o padrão [(\d\d)/(\d\d)/(\d\d)].

No código C#, é preferível escrever um padrão como uma string verbatim [@"..."]: assim, os numerosos caracteres [\] dos padrões não precisam ser duplicados. Com uma string comum, seria preciso escrever ***["\\\\d+"] em vez de ***[@"\\d+"].

5.8.1. Verificar se uma string corresponde a um padrão dado

Um objeto do tipo [Regex] é construído da seguinte forma:

construtor
função
[public Regex(string pattern)]
cria um objeto de “expressão regular” a partir de um padrão passado como parâmetro ([pattern]). Uma exceção [ArgumentException] é lançada se o padrão estiver incorreto
[public Regex(string pattern, RegexOptions options, TimeSpan matchTimeout)]
igual ao anterior, com opções e um tempo limite (veja abaixo)

Depois de construída a expressão regular, ela pode ser comparada com strings por meio do método [IsMatch]:

método
função
[public bool IsMatch(string input)]
true se a string [input] contiver uma substring que corresponda ao padrão da expressão regular

O programa [regex-01.cs] é o seguinte:

using System.Text.RegularExpressions;

// verificação de que uma string corresponde a um padrão
string pattern1 = @"^\s*\d+\s*$";
var regex1 = new Regex(pattern1);
// comparação de amostras com o padrão
foreach (string sample in new[] { "  123  ", "  123a  ", "4567" })
{
    if (regex1.IsMatch(sample))
    {
        Console.WriteLine($"[{sample}] matches the pattern [{pattern1}]");
    }
    else
    {
        Console.WriteLine($"[{sample}] does not match the pattern [{pattern1}]");
    }
}
// o método estático Regex.IsMatch evita criar você mesmo o objeto Regex
Console.WriteLine($"Regex.IsMatch(\"18/05/97\", date) : {Regex.IsMatch("18/05/97", @"^\d{2}/\d{2}/\d{2}$")}");
Console.WriteLine($"Regex.IsMatch(\"5/1/01\", date) : {Regex.IsMatch("5/1/01", @"^\d{2}/\d{2}/\d{2}$")}");

Resultados:

1
2
3
4
5
6
> dotnet run regex-01.cs
[  123  ] matches the pattern [^\s*\d+\s*$]
[  123a  ] does not match the pattern [^\s*\d+\s*$]
[4567] matches the pattern [^\s*\d+\s*$]
Regex.IsMatch("18/05/97", date) : True
Regex.IsMatch("5/1/01", date) : False

Comentários:

  • linha 4: o padrão de um inteiro sem sinal, opcionalmente cercado de espaços, que ocupa a string inteira (âncoras [^] e [$]);
  • linha 9: a string “123a”, cercada de espaços, não corresponde ao padrão: o caractere “a” não pode ser um dígito nem um espaço. Sem as âncoras [^] e [$], a string corresponderia, já que ela contém um número;
  • linha 19: a classe [Regex] também tem métodos estáticos que recebem o padrão como parâmetro. O .NET guarda na memória os padrões usados mais recentemente: eles podem ser usados em um laço sem receio de que o padrão seja analisado a cada chamada.

5.8.2. Encontrar todas as ocorrências de um padrão em uma string

O método [Matches] recupera os elementos de uma string que correspondem a um padrão:

método
função
[public MatchCollection Matches(string input)]
retorna a coleção de elementos da string [input] que correspondem ao padrão

A classe [MatchCollection] tem uma propriedade, [Count], que é o número de elementos da coleção. Se [results] for um objeto [MatchCollection], então [results[i]] é o i-ésimo elemento dessa coleção; ele é do tipo [Match]. A classe [Match] tem várias propriedades, entre elas as seguintes:

  • [Value]: o valor do objeto [Match], isto é, um elemento que corresponde ao padrão;
  • [Index]: a posição em que o elemento foi encontrado na string examinada.

O programa [regex-02.cs] é o seguinte:

using System.Text.RegularExpressions;

// busca de todas as ocorrências de um padrão em uma string
string pattern2 = @"\d+";
var regex2 = new Regex(pattern2);
string sample3 = "  123  456  789 ";
MatchCollection results = regex2.Matches(sample3);
Console.WriteLine($"Pattern=[{pattern2}], sample=[{sample3}]");
Console.WriteLine($"There are {results.Count} occurrences of the pattern in the sample");
foreach (Match m in results)
{
    Console.WriteLine($"[{m.Value}] found at position {m.Index}");
}
// uma MatchCollection é uma sequência: o LINQ se aplica a ela
int sum = results.Sum(m => int.Parse(m.Value));
Console.WriteLine($"sum of the numbers found: {sum}");
// Count conta as ocorrências sem construir a coleção
Console.WriteLine($"number of vowels of \"antidisestablishmentarianism\": {Regex.Count("antidisestablishmentarianism", "[aeiouy]")}");

Resultados:

1
2
3
4
5
6
7
8
> dotnet run regex-02.cs
Pattern=[\d+], sample=[  123  456  789 ]
There are 3 occurrences of the pattern in the sample
[123] found at position 2
[456] found at position 7
[789] found at position 12
sum of the numbers found: 1368
number of vowels of "antidisestablishmentarianism": 11

Comentários:

  • Linha 4: o padrão procurado é uma sequência de dígitos;
  • linha 6: a string em que esse padrão é procurado;
  • linha 7: todos os elementos de [sample3] que correspondem ao padrão [pattern2] são recuperados;
  • Linhas 10–12: eles são exibidos. Uma [MatchCollection] é percorrida com [foreach], como uma lista;
  • linha 15: [MatchCollection] implementa [IEnumerable<Match>]: aplica-se LINQ a ela. Aqui, somamos os números encontrados;
  • linha 18: o método [Count] (.NET 7) conta as ocorrências do padrão sem construir uma coleção. O padrão [aeiouy] denota uma vogal.

5.8.3. Recuperando partes de um padrão

Como mencionado anteriormente, as partes de um padrão colocadas entre parênteses são armazenadas: são os grupos. O programa [regex-03.cs] os utiliza:

using System.Text.RegularExpressions;

// recuperação de partes de um padrão: grupos
string pattern3 = @"(\d\d):(\d\d):(\d\d)";
var regex3 = new Regex(pattern3);
string sample4 = "It is 18:05:49";
// Match retorna a primeira ocorrência do padrão
Match result = regex3.Match(sample4);
if (result.Success)
{
    Console.WriteLine($"The sample [{sample4}] matches the pattern [{pattern3}]");
    // exibimos os grupos entre parênteses
    for (int i = 0; i < result.Groups.Count; i++)
    {
        Console.WriteLine($"groups[{i}]=[{result.Groups[i].Value}] found at position {result.Groups[i].Index}");
    }
}
else
{
    Console.WriteLine($"The sample [{sample4}] does not match the pattern [{pattern3}]");
}

// grupos nomeados: (?<name>...)
var regexDate = new Regex(@"(?<day>\d{1,2})/(?<month>\d{1,2})/(?<year>\d{4})");
string text = "Appointment on 3/10/2026, then on 15/11/2026.";
foreach (Match m in regexDate.Matches(text))
{
    // um grupo é designado pelo nome em vez do número
    int day = int.Parse(m.Groups["day"].Value);
    int month = int.Parse(m.Groups["month"].Value);
    int year = int.Parse(m.Groups["year"].Value);
    var date = new DateOnly(year, month, day);
    Console.WriteLine($"[{m.Value}] : day={day}, month={month}, year={year} -> {date:dddd d MMMM yyyy}");
}

// Replace: os grupos podem ser reutilizados na string de substituição
string reversed = regexDate.Replace(text, "${year}-${month}-${day}");
Console.WriteLine($"Replace : {reversed}");

Resultados:

1
2
3
4
5
6
7
8
9
> dotnet run regex-03.cs
The sample [It is 18:05:49] matches the pattern [(\d\d):(\d\d):(\d\d)]
groups[0]=[18:05:49] found at position 6
groups[1]=[18] found at position 6
groups[2]=[05] found at position 9
groups[3]=[49] found at position 12
[3/10/2026] : day=3, month=10, year=2026 -> Saturday 3 October 2026
[15/11/2026] : day=15, month=11, year=2026 -> Sunday 15 November 2026
Replace : Appointment on 2026-10-3, then on 2026-11-15.

Comentários:

  • Linha 8: a string [sample4] é comparada com o padrão [regex3] por meio do método [Match]. Esse método retorna a primeira ocorrência do padrão como um objeto [Match], já apresentado. Aqui, usamos duas novas propriedades dessa classe:
    • [Success] (linha 9): indica se foi encontrada uma correspondência;
    • [Groups] (linha 13): uma coleção em que [Groups[0]] corresponde à parte da string que representa o padrão e [Groups[i]] (i >= 1) corresponde ao i-ésimo par de parênteses;
  • se [result] for do tipo [Match], então [result.Groups] é do tipo [GroupCollection] e [result.Groups[i]] é do tipo [Group]. A classe [Group] tem, como a classe [Match], as propriedades [Value] (o texto capturado pelo grupo) e [Index] (sua posição na string analisada);
  • linha 24: um grupo pode ser nomeado com a sintaxe [(?<name>...)]. Aqui, o padrão reconhece uma data no formato d/m/aaaa, com dia e mês de um ou dois dígitos;
  • linhas 29–31: um grupo nomeado é referenciado pelo nome e não pelo número: o código fica mais legível e não depende da ordem dos parênteses;
  • linha 32: o tipo [DateOnly] (.NET 6) representa uma data sem hora. Ele é exibido no formato [dddd d MMMM yyyy]: o dia da semana aparece em inglês;
  • linha 37: o método [Replace] substitui cada ocorrência do padrão por uma string em que [${name}] (ou [$1], [$2]… para grupos numerados) denota o valor de um grupo. As datas são assim reformatadas no formato ano-mês-dia.

5.8.4. Um programa de aprendizado

Encontrar a expressão regular que verifica se uma string corresponde a um determinado padrão pode, às vezes, ser um verdadeiro desafio. O programa [regex-04.cs] permite praticar. Ele recebe como entrada um padrão e uma string e indica se a string corresponde ou não ao padrão.

using System.Text.RegularExpressions;

// um programa para aprender expressões regulares
while (true)
{
    // pedimos o padrão
    Console.Write("Type the pattern to test or nothing to stop: ");
    string pattern = Console.ReadLine() ?? "";
    // terminou?
    if (pattern.Trim() == "")
    {
        break;
    }
    // criamos a expressão regular; um padrão incorreto causa uma exceção
    Regex regex;
    try
    {
        regex = new Regex(pattern, RegexOptions.None, TimeSpan.FromSeconds(1));
    }
    catch (ArgumentException e)
    {
        Console.WriteLine($"Error: {e.Message}");
        continue;
    }
    // pedimos as amostras a comparar com o padrão
    while (true)
    {
        Console.Write($"Type the string to compare with the pattern [{pattern}] or nothing to stop: ");
        string input = Console.ReadLine() ?? "";
        // terminou?
        if (input.Trim() == "")
        {
            break;
        }
        try
        {
            // fazemos a comparação
            MatchCollection results = regex.Matches(input);
            if (results.Count == 0)
            {
                Console.WriteLine("I did not find any matches");
                continue;
            }
            // exibimos os elementos que correspondem ao padrão
            foreach (Match m in results)
            {
                Console.WriteLine($"I found the match [{m.Value}] at position [{m.Index}]");
                // e seus subelementos (grupos 1, 2, ...)
                for (int j = 1; j < m.Groups.Count; j++)
                {
                    Console.WriteLine($"\tsub-element [{m.Groups[j].Value}] at position [{m.Groups[j].Index}]");
                }
            }
        }
        catch (RegexMatchTimeoutException)
        {
            Console.WriteLine("The search was abandoned: it lasted more than one second");
        }
    }
}

Comentários:

  • linha 18: a expressão regular é construída com um tempo limite de um segundo: se uma busca demorar mais que isso, ela é abandonada e uma exceção [RegexMatchTimeoutException] é lançada (linha 55). Veremos adiante por que isso é útil;
  • linha 20: um padrão inválido causa uma exceção [ArgumentException] (mais especificamente, [RegexParseException], que deriva dela);
  • linhas 45–51: para cada correspondência, são exibidos os grupos de número 1 em diante, se houver.

Eis um exemplo da saída:

> dotnet run regex-04.cs
Type the pattern to test or nothing to stop: \d+
Type the string to compare with the pattern [\d+] or nothing to stop: 123 456 789
I found the match [123] at position [0]
I found the match [456] at position [4]
I found the match [789] at position [8]
Type the string to compare with the pattern [\d+] or nothing to stop: 
Type the pattern to test or nothing to stop: (\d{2}):(\d\d)
Type the string to compare with the pattern [(\d{2}):(\d\d)] or nothing to stop: 14:15 abcd 17:18 xyzt
I found the match [14:15] at position [0]
    sub-element [14] at position [0]
    sub-element [15] at position [3]
I found the match [17:18] at position [11]
    sub-element [17] at position [11]
    sub-element [18] at position [14]
Type the string to compare with the pattern [(\d{2}):(\d\d)] or nothing to stop: 
Type the pattern to test or nothing to stop: ^\s*\d+\s*$
Type the string to compare with the pattern [^\s*\d+\s*$] or nothing to stop:    1456
I found the match [   1456] at position [0]
Type the string to compare with the pattern [^\s*\d+\s*$] or nothing to stop: 
Type the pattern to test or nothing to stop: ^\s*(\d+)\s*$
Type the string to compare with the pattern [^\s*(\d+)\s*$] or nothing to stop: 1456
I found the match [1456] at position [0]
    sub-element [1456] at position [0]
Type the string to compare with the pattern [^\s*(\d+)\s*$] or nothing to stop: abcd 1456
I did not find any matches
Type the string to compare with the pattern [^\s*(\d+)\s*$] or nothing to stop: 
Type the pattern to test or nothing to stop: (a+)+$
Type the string to compare with the pattern [(a+)+$] or nothing to stop: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa!
The search was abandoned: it lasted more than one second
Type the string to compare with the pattern [(a+)+$] or nothing to stop: 
Type the pattern to test or nothing to stop: (\d+
Error: Invalid pattern '(\d+' at offset 4. Not enough )'s.
Type the pattern to test or nothing to stop: 

Os padrões [^\s*\d+\s*$] e [^\s*(\d+)\s*$] mostram a utilidade dos grupos: o primeiro reconhece a string “1456” precedida de três espaços, incluindo os espaços; o segundo extrai, além disso, o número sem os espaços. O padrão [(a+)+$] é examinado adiante.

5.8.5. O método Split

Já encontramos o método [Split] da classe [String]:

método
função
[public string[] Split(params char[] separator)]
A string é tratada como uma sequência de campos separados pelos caracteres listados no array [separator]. O resultado é um array desses campos

O método [Split] da classe [Regex] permite especificar o separador por meio de um padrão:

método
função
[public string[] Split(string input)]
A string [input] é dividida em campos, separados por um separador que corresponde ao padrão do objeto [Regex] atual

Suponha, por exemplo, que um arquivo de texto contenha linhas da forma campo1, campo2, ..., campon. Os campos são separados por vírgula, mas essa vírgula pode ser precedida ou seguida de espaços. O padrão [\s*,\s*] descreve esse separador exatamente, como mostra o programa [regex-05.cs]:

using System.Text.RegularExpressions;

// Regex.Split: o separador é definido por um padrão
string line = "abc  , def  ,ghi ,   jkl";
// uma vírgula precedida e seguida por qualquer número de espaços
var separator = new Regex(@"\s*,\s*");
string[] fields = separator.Split(line);
for (int i = 0; i < fields.Length; i++)
{
    Console.WriteLine($"fields[{i}]=[{fields[i]}]");
}
// vários separadores possíveis: ; ou | ou uma sequência de espaços
string[] words = Regex.Split("one;two|three   four", @"[;|]|\s+");
Console.WriteLine($"words=[{string.Join(", ", words)}]");

Resultados:

1
2
3
4
5
6
> dotnet run regex-05.cs
fields[0]=[abc]
fields[1]=[def]
fields[2]=[ghi]
fields[3]=[jkl]
words=[one, two, three, four]

Comentários:

  • linha 6: o separador: uma vírgula precedida e seguida de qualquer quantidade de espaços. Os espaços são removidos junto com o separador. Observe que a opção [TrimEntries] de [string.Split], apresentada anteriormente, agora permite obter o mesmo resultado sem expressão regular;
  • Linha 13: um separador que pode assumir várias formas: um ponto e vírgula ou uma barra vertical ([;|]), ou ([|]) uma sequência de espaços ([\s+]). Aqui, uma expressão regular é necessária.

5.8.6. Expressões regulares geradas, opções, tempo limite

Um objeto [Regex] analisa seu padrão em tempo de execução e depois o traduz para uma estrutura interna que ele interpreta, ou compila em código executável se a opção [RegexOptions.Compiled] lhe for passada. A partir do .NET 7, o atributo [GeneratedRegex] permite que esse trabalho seja feito em tempo de compilação: um gerador de código-fonte escreve o código C# da busca, que pode ser visualizado no editor (F12 sobre o método). O padrão é validado em tempo de compilação, não há mais custo de análise na inicialização e o código gerado executa o mais rápido possível. Essa é hoje a forma recomendada de usar um padrão conhecido de antemão. O programa [regex-06.cs] é o seguinte:

using System.Diagnostics;
using System.Text.RegularExpressions;

// 1 - expressões regulares geradas em tempo de compilação
Console.WriteLine($"Time(\"It is 18:05:49\") : {Patterns.Time().IsMatch("It is 18:05:49")}");
Match m = Patterns.Time().Match("departure at 07:45:00");
Console.WriteLine($"hours={m.Groups["h"].Value}, minutes={m.Groups["m"].Value}, seconds={m.Groups["s"].Value}");

// 2 - opções: aqui IgnoreCase, definida no atributo
foreach (string answer in new[] { "yes", "YES", "Yes", "no", "yesss" })
{
    Console.Write($"{answer}={Patterns.Yes().IsMatch(answer)} ");
}
Console.WriteLine();
// as opções são combinadas com |: Multiline faz ^ e $ corresponderem ao início e ao fim de cada linha
string text = "price: 10\nquantity: 3\ntotal: 30";
foreach (Match line in Regex.Matches(text, @"^(\w+): (\d+)$", RegexOptions.Multiline))
{
    Console.Write($"[{line.Groups[1].Value}={line.Groups[2].Value}] ");
}
Console.WriteLine();

// 3 - um timeout protege contra padrões com backtracking catastrófico
string input = new string('a', 30) + "!";
try
{
    Console.WriteLine(Patterns.Catastrophic().IsMatch(input));
}
catch (RegexMatchTimeoutException e)
{
    Console.WriteLine($"{e.GetType().Name} : search abandoned after {e.MatchTimeout.TotalMilliseconds} ms");
}
// o mesmo padrão com o mecanismo sem backtracking responde imediatamente
var stopwatch = Stopwatch.StartNew();
bool found = Regex.IsMatch(input, @"^(a+)+$", RegexOptions.NonBacktracking);
Console.WriteLine($"NonBacktracking : {found}, answer in less than one second: {stopwatch.ElapsedMilliseconds < 1000}");

// os padrões do programa
static partial class Patterns
{
    // uma hora hh:mm:ss com grupos nomeados
    [GeneratedRegex(@"(?<h>\d\d):(?<m>\d\d):(?<s>\d\d)")]
    public static partial Regex Time();

    // sim, independentemente de maiúsculas e minúsculas
    [GeneratedRegex(@"^\s*yes\s*$", RegexOptions.IgnoreCase)]
    public static partial Regex Yes();

    // um padrão patológico, com um timeout de 100 ms
    [GeneratedRegex(@"^(a+)+$", RegexOptions.None, matchTimeoutMilliseconds: 100)]
    public static partial Regex Catastrophic();
}

Resultados:

1
2
3
4
5
6
7
> dotnet run regex-06.cs
Time("It is 18:05:49") : True
hours=07, minutes=45, seconds=00
yes=True YES=True Yes=True no=False yesss=False 
[price=10] [quantity=3] [total=30] 
RegexMatchTimeoutException : search abandoned after 100 ms
NonBacktracking : False, answer in less than one second: True

Comentários:

  • Linhas 39–51: cada padrão é declarado por um método estático partial ([partial]) sem corpo, que gera um [Regex], e é precedido pelo atributo [GeneratedRegex]. O gerador de código-fonte escreve o corpo do método em outra parte da classe, também declarada como [partial]. A partir do C# 13 e do .NET 9, também é possível declarar uma propriedade parcial: [[GeneratedRegex(...)] private static partial Regex Time { get; }];
  • linha 5: o método é usado como um objeto [Regex] comum;
  • linha 46: o segundo parâmetro do atributo é uma combinação de opções [RegexOptions]. [IgnoreCase] ignora maiúsculas e minúsculas: “YES” e “Yes” correspondem ao padrão;
  • linha 17: as opções são usadas da mesma forma com os métodos de [Regex]. [Multiline] faz [^] e [$] corresponderem ao início e ao fim de cada linha da string, e não apenas ao início e ao fim da própria string. Outras opções são úteis: [Singleline] ([.] também corresponde a quebras de linha), [IgnorePatternWhitespace] (os espaços no padrão são ignorados, o que permite escrevê-lo em várias linhas, inclusive com comentários), [ExplicitCapture] (apenas os grupos nomeados são memorizados). Elas podem ser combinadas com o operador [|];
  • linha 50: o padrão [^(a+)+$] é patológico: quando aplicado a uma sequência de “a” terminada por outro caractere, o mecanismo de expressões regulares tenta todas as maneiras possíveis de distribuir os “a” entre as repetições do grupo antes de concluir que falhou. O número de possibilidades dobra a cada “a” adicional: com 30 “a”, há aproximadamente um bilhão de possibilidades. Isso é conhecido como um backtracking catastrófico. Um padrão desse tipo, aplicado a strings digitadas por usuários, é uma vulnerabilidade de segurança: poucas requisições bastam para derrubar um servidor. O parâmetro [matchTimeoutMilliseconds] define um tempo limite de 100 ms: depois disso, a busca é abandonada com uma exceção [RegexMatchTimeoutException] (linha 6);
  • linha 35: a opção [NonBacktracking] (.NET 7) usa um mecanismo diferente, que garante um tempo de busca proporcional ao comprimento da string. Ele não oferece suporte a certas construções (referências anteriores, como [\1], por exemplo), mas retorna um resultado imediatamente neste caso.

Observe que é preciso definir um tempo limite ou usar [NonBacktracking] sempre que o padrão ou a string pesquisada vier de fora do programa.

5.9. Aplicativo de exemplo - V3

Retomaremos o aplicativo estudado no Capítulo 3 (Versão 1) e no Capítulo 4 (Versão 2). Lembre-se de que se trata de um exercício: a tabela de imposto utilizada é a de 2004 (renda de 2003), que permanece inalterada desde o curso original.

5.9.1. Dados em um arquivo

Na versão 2, o cálculo do imposto era feito na classe abstrata [AbstractTax], que reproduzimos aqui sem alterações, exceto pelo namespace:

namespace TaxV3;

public abstract class AbstractTax : ITax
{
    // as faixas de imposto necessárias ao cálculo vêm de uma fonte externa
    // que somente as classes derivadas conhecem
    protected abstract TaxBracket[] TaxBrackets { get; }

    // cálculo do imposto
    public int Calculate(bool married, int nbChildren, int salary)
    {
        // cálculo do número de cotas
        decimal shares = (decimal)nbChildren / 2 + (married ? 2 : 1);
        if (nbChildren >= 3)
        {
            shares += 0.5m;
        }
        // cálculo da renda tributável e do quociente familiar
        decimal income = 0.72m * salary;
        decimal quotient = income / shares;
        // busca da faixa de imposto: a última é usada se nenhum limite servir
        TaxBracket[] brackets = TaxBrackets;
        TaxBracket bracket = brackets[^1];
        for (int i = 0; i < brackets.Length - 1; i++)
        {
            if (quotient <= brackets[i].Limit)
            {
                bracket = brackets[i];
                break;
            }
        }
        // cálculo do imposto
        return (int)(income * bracket.CoeffR - shares * bracket.CoeffN);
    }
}

O método [Calculate] usa as faixas de imposto retornadas pela propriedade abstrata [TaxBrackets] (linha 7). A classe [AbstractTax] não sabe de onde vêm essas faixas: cabe às classes derivadas fornecê-las. Na versão 2, a classe derivada [HardwiredTax] as fixava diretamente no código. Uma faixa de imposto é representada, como na versão 2, pela estrutura record [TaxBracket]:

1
2
3
4
namespace TaxV3;

// uma faixa da tabela do imposto
public readonly record struct TaxBracket(decimal Limit, decimal CoeffR, decimal CoeffN);

e o cálculo é descrito pela interface [ITax]:

1
2
3
4
5
6
7
namespace TaxV3;

public interface ITax
{
    // cálculo do imposto de um contribuinte
    int Calculate(bool married, int nbChildren, int salary);
}

A nova versão armazena os dados em um arquivo, o que permite alterar a tabela de faixas sem recompilar o programa. Escrevemos duas novas classes derivadas de [AbstractTax]:

  • [FileTax] lê as faixas de um arquivo de texto [TaxData.txt];
  • [JsonTax] as lê de um arquivo JSON chamado [TaxData.json].

O arquivo de texto [TaxData.txt] contém uma faixa de imposto por linha, no formato limite:coeffR:coeffN:

1
2
3
4
5
6
7
4962:0:0
8382:0.068:291.09
14753:0.191:1322.92
23888:0.283:2668.39
38868:0.374:4846.98
47932:0.426:6883.66
0:0.481:9505.54

O curso de 2008 escrevia os números com vírgula decimal (0,068) e os lia com [decimal.TryParse] na localidade da máquina: o mesmo arquivo, lido em uma máquina britânica ou americana, teria sido rejeitado ou, pior, interpretado incorretamente. Um arquivo de dados não deve depender do idioma da máquina que o lê: escrevemos os números com ponto decimal e os lemos na cultura invariável ([CultureInfo.InvariantCulture]), que também é a usada pelo JSON e pela maioria dos formatos de dados.

O arquivo [TaxData.json] contém os mesmos dados, na forma de um array JSON de objetos:

1
2
3
4
5
6
7
8
9
[
  { "limit": 4962, "coeffR": 0, "coeffN": 0 },
  { "limit": 8382, "coeffR": 0.068, "coeffN": 291.09 },
  { "limit": 14753, "coeffR": 0.191, "coeffN": 1322.92 },
  { "limit": 23888, "coeffR": 0.283, "coeffN": 2668.39 },
  { "limit": 38868, "coeffR": 0.374, "coeffN": 4846.98 },
  { "limit": 47932, "coeffR": 0.426, "coeffN": 6883.66 },
  { "limit": 0, "coeffR": 0.481, "coeffN": 9505.54 }
]

5.9.2. Erros

O processamento desses arquivos pode falhar: arquivo ausente, linha malformada, número incorreto etc. Como na versão de 2008, criamos uma classe de exceção específica para relatar esses erros. O curso de 2008 a chamava de [FileTaxException]; nós a chamamos de [TaxException], já que ela também será usada para outras fontes de dados (aqui o arquivo JSON e, mais adiante, um banco de dados). Ela carrega um código de erro:

namespace TaxV3;

// os códigos de erro: potências de 2, que podem ser combinadas
[Flags]
public enum ErrorCode
{
    Access = 1,     // o arquivo não pode ser lido
    Line = 2,       // uma linha não tem três campos
    Field1 = 4,     // o campo 1 (limit) está incorreto
    Field2 = 8,     // o campo 2 (coeffR) está incorreto
    Field3 = 16,    // o campo 3 (coeffN) está incorreto
    Json = 32       // o documento JSON está incorreto
}

// a exceção lançada pelas classes que leem as faixas de imposto
public class TaxException : Exception
{
    // o código de erro (uma combinação de valores de ErrorCode)
    public int Code { get; init; }

    public TaxException(string message) : base(message) { }
    public TaxException(string message, Exception inner) : base(message, inner) { }
}

Comentários:

  • linhas 16–22: a classe [TaxException] deriva da classe [Exception]. Ela será usada para relatar quaisquer erros que ocorram durante o processamento do arquivo de dados. Tem dois construtores: o primeiro recebe uma mensagem de erro e o segundo recebe também a exceção que causou o erro, que ficará disponível na propriedade [InnerException];
  • Linha 19: a propriedade [Code] armazena o código de erro. A palavra-chave [init] permite que ele seja definido apenas na criação do objeto, por meio de um inicializador de objeto: [new TaxException("...") { Code = 2 }]. É essa forma de exceção, com um código inteiro, que as versões seguintes do aplicativo usarão;
  • linhas 4–12: uma lista dos códigos de erro possíveis:
    • [Access]: erro de acesso ao arquivo de dados;
    • [Line]: linha sem os três campos esperados ou arquivo sem nenhuma faixa;
    • [Field1], [Field2], [Field3]: o campo 1, 2 ou 3 de uma linha está incorreto;
    • [Json]: o documento JSON está incorreto.

Alguns desses erros podem ocorrer em combinação: os três campos de uma linha podem estar incorretos. Por isso, a enumeração [ErrorCode] foi anotada com o atributo [Flags], e seus valores são potências de 2: cada um corresponde a um bit do inteiro. Um erro nos campos 2 e 3 resultará no código [Field2 | Field3], que vale 8 + 16 = 24. Graças ao atributo [Flags], o método [ToString] da enumeração exibe essa combinação na forma “Field2, Field3”.

5.9.3. A classe FileTax

A classe [FileTax] fornece as faixas lidas de um arquivo de texto:

using System.Globalization;
using System.Text.RegularExpressions;

namespace TaxV3;

// as faixas de imposto lidas de um arquivo de texto com linhas limit:coeffR:coeffN
public partial class FileTax : AbstractTax
{
    // o separador de campos: o caractere : cercado por espaços opcionais
    [GeneratedRegex(@"\s*:\s*")]
    private static partial Regex Separator();

    // as faixas de imposto lidas do arquivo
    private readonly TaxBracket[] taxBrackets;

    // implementação da propriedade abstrata da classe pai
    protected override TaxBracket[] TaxBrackets => taxBrackets;

    public FileTax(string fileName)
    {
        // o nome do arquivo, sem o caminho, para as mensagens de erro
        string name = Path.GetFileName(fileName);
        // as faixas lidas; não sabemos seu número de antemão
        List<TaxBracket> brackets = [];
        try
        {
            int lineNumber = 0;
            foreach (string lineRead in File.ReadLines(fileName))
            {
                lineNumber++;
                string line = lineRead.Trim();
                // as linhas vazias são ignoradas
                if (line == "")
                {
                    continue;
                }
                // a linha deve ter três campos
                string[] fields = Separator().Split(line);
                if (fields.Length != 3)
                {
                    throw new TaxException($"Line no. {lineNumber} is incorrect ({line})")
                    {
                        Code = (int)ErrorCode.Line
                    };
                }
                // três números decimais positivos ou nulos, escritos com ponto decimal
                ErrorCode code = 0;
                if (!Read(fields[0], out decimal limit)) code |= ErrorCode.Field1;
                if (!Read(fields[1], out decimal coeffR)) code |= ErrorCode.Field2;
                if (!Read(fields[2], out decimal coeffN)) code |= ErrorCode.Field3;
                if (code != 0)
                {
                    throw new TaxException($"Line no. {lineNumber} is incorrect ({line})")
                    {
                        Code = (int)code
                    };
                }
                // armazenamos a nova faixa de imposto
                brackets.Add(new TaxBracket(limit, coeffR, coeffN));
            }
        }
        catch (Exception e) when (e is IOException or UnauthorizedAccessException)
        {
            // erro de acesso ao arquivo: o encapsulamos em uma TaxException
            throw new TaxException($"Error while reading the file {name}", e)
            {
                Code = (int)ErrorCode.Access
            };
        }
        // é necessária pelo menos uma faixa
        if (brackets.Count == 0)
        {
            throw new TaxException($"The file {name} does not contain any bracket")
            {
                Code = (int)ErrorCode.Line
            };
        }
        // transferimos a lista para o array de faixas
        taxBrackets = brackets.ToArray();
    }

    // conversão de um campo em decimal >= 0, independentemente da cultura da máquina
    private static bool Read(string field, out decimal result) =>
        decimal.TryParse(field, NumberStyles.AllowDecimalPoint, CultureInfo.InvariantCulture, out result);
}

Comentários:

  • Linha 7: a classe [FileTax] deriva da classe [AbstractTax], assim como a classe [HardwiredTax] na versão 2. Ela é declarada como [partial] porque contém uma expressão regular gerada;
  • linhas 10–11: a expressão regular do separador de campos em uma linha limite:coeffR:coeffN: o caractere [:], precedido e seguido de qualquer quantidade de espaços;
  • linhas 14–17: as faixas lidas, retornadas pela propriedade [TaxBrackets], que redefine a propriedade abstrata de [AbstractTax];
  • linha 19: o construtor recebe o nome do arquivo de texto que contém os dados. Sua função é preencher o array [taxBrackets];
  • linha 22: o nome do arquivo sem o caminho, usado nas mensagens de erro. O construtor na verdade recebe um caminho completo, que não precisa ser exibido ao usuário;
  • linha 24: a leitura de um arquivo de texto é sequencial: o número de linhas só é conhecido depois de lido o arquivo inteiro. Por isso, o array não pode ser dimensionado antecipadamente; as faixas são armazenadas temporariamente em uma lista;
  • linha 28: o arquivo é lido linha a linha com [File.ReadLines], que abre e fecha o arquivo por conta própria. O curso de 2008 usava [StreamReader];
  • linhas 38–43: a linha é dividida em campos por meio de uma expressão regular; se não houver três campos, uma exceção [TaxException] com o código [Line] é lançada. O curso de 2008 armazenava o erro em uma variável, saía do laço e lançava a exceção depois de fechar o arquivo: lançá-la imediatamente é mais simples, e [File.ReadLines] fecha o arquivo em qualquer caso, pois o laço [foreach] libera seu enumerador mesmo quando uma exceção o interrompe;
  • linhas 47–55: conversão dos três campos em números decimais. Os erros são acumulados na variável [code] com o operador [|=] e depois relatados em conjunto;
  • linhas 83–84: conversão de um campo. [NumberStyles.AllowDecimalPoint] permite apenas dígitos e um ponto decimal: sem sinais, espaços ou separadores de milhar. Os números negativos são, portanto, rejeitados, o que valida os dados ao mesmo tempo em que são convertidos. [CultureInfo.InvariantCulture] impõe o ponto como separador decimal, independentemente da localidade da máquina;
  • linhas 62–67: os erros de acesso ao arquivo ([IOException] e suas variantes, como [FileNotFoundException], ou [UnauthorizedAccessException] para permissões insuficientes) são encapsulados em uma [TaxException] com o código [Access]. O [when (...)] filtro de exceção (C# 6) intercepta apenas essas exceções: [TaxException] lançadas dentro do laço não são interceptadas e saem do construtor inalteradas. O padrão [e is IOException or UnauthorizedAccessException] é um padrão combinado com [or] (C# 9);
  • linhas 71–79: um arquivo vazio é rejeitado; caso contrário, a lista é transferida para o array de faixas, que era a finalidade do construtor.

Encapsular exceções de baixo nível ([IOException]) em uma exceção específica do aplicativo ([TaxException]) permite que o código chamador trate um único tipo de exceção, qualquer que seja a fonte de dados: um arquivo de texto, um arquivo JSON e, mais adiante no curso, um banco de dados.

5.9.4. A classe JsonTax

A classe [JsonTax] fornece as faixas lidas de um arquivo JSON:

using System.Text.Json;

namespace TaxV3;

// as faixas de imposto lidas de um arquivo JSON
public class JsonTax : AbstractTax
{
    // opções "Web": nomes de propriedades em camelCase (limit, coeffR, coeffN)
    private static readonly JsonSerializerOptions options = new(JsonSerializerDefaults.Web);

    // as faixas de imposto lidas do arquivo
    private readonly TaxBracket[] taxBrackets;

    // implementação da propriedade abstrata da classe pai
    protected override TaxBracket[] TaxBrackets => taxBrackets;

    public JsonTax(string fileName)
    {
        // o nome do arquivo, sem o caminho, para as mensagens de erro
        string name = Path.GetFileName(fileName);
        string json;
        try
        {
            // leitura do arquivo
            json = File.ReadAllText(fileName);
        }
        catch (Exception e) when (e is IOException or UnauthorizedAccessException)
        {
            throw new TaxException($"Error while reading the file {name}", e)
            {
                Code = (int)ErrorCode.Access
            };
        }
        TaxBracket[]? brackets;
        try
        {
            // desserialização do array de faixas
            brackets = JsonSerializer.Deserialize<TaxBracket[]>(json, options);
        }
        catch (JsonException e)
        {
            throw new TaxException($"The file {name} is incorrect: {e.Message}", e)
            {
                Code = (int)ErrorCode.Json
            };
        }
        // é necessária pelo menos uma faixa, sem nenhum valor negativo
        if (brackets is null || brackets.Length == 0)
        {
            throw new TaxException($"The file {name} does not contain any bracket")
            {
                Code = (int)ErrorCode.Json
            };
        }
        if (brackets.Any(t => t.Limit < 0 || t.CoeffR < 0 || t.CoeffN < 0))
        {
            throw new TaxException($"The file {name} contains a negative value")
            {
                Code = (int)ErrorCode.Json
            };
        }
        taxBrackets = brackets;
    }
}

Comentários:

  • Linha 9: as opções “Web”: as propriedades JSON [limit], [coeffR] e [coeffN] correspondem às propriedades [Limit], [CoeffR] e [CoeffN] da estrutura [TaxBracket] sem necessidade de modificá-la com atributos. As opções são armazenadas em um campo estático: um objeto [JsonSerializerOptions] guarda informações sobre os tipos que processou, e é recomendável reutilizá-lo;
  • linhas 25–31: leitura do arquivo; um erro de acesso é tratado como em [FileTax];
  • Linha 38: uma única instrução converte o texto JSON em um array de faixas. [System.Text.Json] sabe construir uma estrutura record chamando seu construtor. Um documento inválido dispara uma [JsonException], encapsulada em uma [TaxException] de código [Json];
  • linhas 48–57: a desserialização verifica o formato do documento, não a validade dos dados: resta verificar que há pelo menos uma faixa (o documento [null] ou [] é um JSON válido) e que nenhum valor é negativo. O método LINQ [Any] faz essa última verificação em uma única linha.

Comparar as duas classes é instrutivo: com um formato de dados estruturado e uma biblioteca que o compreende, a análise do arquivo não exige mais nenhum código.

5.9.5. O programa principal

O projeto de console [TaxV3] tem a seguinte estrutura de diretórios:

05-classes-dotnet/
  05-classes-dotnet.slnx
  TaxV3/
    AbstractTax.cs
    FileTax.cs
    ITax.cs
    JsonTax.cs
    Program.cs
    TaxBracket.cs
    TaxData.json
    TaxData.txt
    TaxDataInvalid.json
    TaxDataInvalid.txt
    TaxException.cs
    TaxV3.csproj

O arquivo de projeto [TaxV3.csproj] é o criado por [dotnet new console], ao qual foi acrescentado um grupo de elementos:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <!-- os arquivos de dados são copiados ao lado do executável -->
  <ItemGroup>
    <None Update="TaxData*.txt;TaxData*.json" CopyToOutputDirectory="PreserveNewest" />
  </ItemGroup>

</Project>

O elemento [<None Update="..." CopyToOutputDirectory="PreserveNewest" />] (linha 12) especifica que os arquivos de dados devem ser copiados para a pasta do executável ([bin/Debug/net10.0]) durante a compilação, se forem mais recentes que a cópia existente. O caractere [*] permite especificar de uma só vez todos os arquivos [TaxData*.txt] e [TaxData*.json] . Isso equivale à propriedade “Copiar para o diretório de saída” que o curso de 2008 definia nas propriedades do arquivo no Visual Studio.

O programa [Program.cs] é o seguinte:

using TaxV3;

// cálculo do imposto, versão 3: as faixas de imposto são lidas de um arquivo
// sintaxe: dotnet run [-- file]; file: TaxData.txt por padrão, ou um arquivo .json

const string syntax = """
    syntax: Married NbChildren Salary
    Married: y for married, n for not married
    NbChildren: number of children
    Salary: annual salary in euros
    """;

// o arquivo de dados é procurado ao lado do executável
string fileName = args.Length > 0 ? args[0] : "TaxData.txt";
string path = Path.Combine(AppContext.BaseDirectory, fileName);
Console.WriteLine($"Tax brackets read from [{fileName}]");

// criação de um objeto ITax; a classe depende da extensão do arquivo
ITax tax;
try
{
    tax = Path.GetExtension(fileName).ToLower() switch
    {
        ".json" => new JsonTax(path),
        _ => new FileTax(path)
    };
}
catch (TaxException e)
{
    // exibição do erro; o código é exibido como uma combinação de ErrorCode
    string origin = e.InnerException is null ? "" : $", original exception: {e.InnerException.GetType().Name}";
    Console.WriteLine($"The following error occurred: [Code={(ErrorCode)e.Code}, Message={e.Message}{origin}]");
    // encerramento do programa
    return 1;
}

// laço de entrada
while (true)
{
    // pedimos os parâmetros do cálculo do imposto
    Console.Write("Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: ");
    string parameters = (Console.ReadLine() ?? "").Trim();
    // há algo a fazer?
    if (parameters == "")
    {
        break;
    }
    // verificação do número de campos da linha digitada
    string[] fields = parameters.Split(' ', StringSplitOptions.RemoveEmptyEntries);
    if (fields.Length != 3)
    {
        Console.WriteLine(syntax);
        continue;
    }
    // verificação da validade dos parâmetros
    // married
    string married = fields[0].ToLower();
    if (married != "y" && married != "n")
    {
        Console.WriteLine(syntax + "\nIncorrect married argument: type y or n");
        continue;
    }
    // nbChildren
    if (!int.TryParse(fields[1], out int nbChildren) || nbChildren < 0)
    {
        Console.WriteLine(syntax + "\nIncorrect NbChildren argument: type a positive or zero integer");
        continue;
    }
    // salary
    if (!int.TryParse(fields[2], out int salary) || salary < 0)
    {
        Console.WriteLine(syntax + "\nIncorrect salary argument: type a positive or zero integer");
        continue;
    }
    // os parâmetros estão corretos: calculamos o imposto
    Console.WriteLine($"Tax={tax.Calculate(married == "y", nbChildren, salary)} euros");
}
return 0;

Comentários:

  • linha 14: o nome do arquivo de dados é passado como argumento; por padrão, é [TaxData.txt];
  • linha 15: o arquivo é procurado na pasta do executável, [AppContext.BaseDirectory], onde foi copiado durante a compilação. Assim, o programa encontra seus dados independentemente da pasta a partir da qual é iniciado, o que não acontecia com os aplicativos de arquivo único deste capítulo;
  • Linhas 22–25: uma expressão [switch] (Capítulo 3) seleciona a classe a instanciar com base na extensão do arquivo. Os dois ramos retornam tipos diferentes, [JsonTax] e [FileTax]: o compilador infere o tipo da expressão a partir da variável de destino [tax], que é do tipo [ITax] (expressão [switch] com tipo de destino). O restante do programa conhece apenas a interface [ITax] e ignora de onde vêm os dados;
  • linhas 28–34: a criação do objeto pode disparar uma [TaxException], que é exibida antes de o programa terminar. O código é convertido em [ErrorCode] para ser exibido em texto legível; a exceção original, se houver, é identificada por seu tipo (sua mensagem contém o caminho completo do arquivo);
  • Linhas 37–76: o laço de diálogo é exatamente o mesmo da versão 2.

5.9.6. Execuções

Com o arquivo [TaxData.txt], usado por padrão:

> dotnet run
Tax brackets read from [TaxData.txt]
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 2 60000
Tax=4282 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 3 60000
Tax=2959 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: n 0 60000
Tax=11519 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: q s d
syntax: Married NbChildren Salary
Married: y for married, n for not married
NbChildren: number of children
Salary: annual salary in euros
Incorrect married argument: type y or n
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 2 d
syntax: Married NbChildren Salary
Married: y for married, n for not married
NbChildren: number of children
Salary: annual salary in euros
Incorrect salary argument: type a positive or zero integer
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 2
syntax: Married NbChildren Salary
Married: y for married, n for not married
NbChildren: number of children
Salary: annual salary in euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: 

Os valores das versões anteriores são reproduzidos: 4.282 euros para um casal com 2 filhos, 2.959 euros com 3 filhos e 11.519 euros para uma pessoa solteira sem filhos, com um salário anual de 60.000 euros. As entradas incorretas são sinalizadas como na Versão 2.

Com o arquivo [TaxData.json]:

1
2
3
4
5
6
7
8
9
> dotnet run -- TaxData.json
Tax brackets read from [TaxData.json]
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 2 60000
Tax=4282 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 3 60000
Tax=2959 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: n 0 60000
Tax=11519 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: 

Com um arquivo [xx.txt] inexistente:

1
2
3
> dotnet run -- xx.txt
Tax brackets read from [xx.txt]
The following error occurred: [Code=Access, Message=Error while reading the file xx.txt, original exception: FileNotFoundException]

Com o seguinte arquivo [TaxDataInvalid.txt], em que a terceira linha usa vírgula decimal:

1
2
3
4
4962:0:0
8382:0.068:291.09
14753:0,191:1322,92
23888:0.283:2668.39
1
2
3
> dotnet run -- TaxDataInvalid.txt
Tax brackets read from [TaxDataInvalid.txt]
The following error occurred: [Code=Field2, Field3, Message=Line no. 3 is incorrect (14753:0,191:1322,92)]

Os campos 2 e 3 da linha 3 são rejeitados: o código de erro é a combinação “Field2, Field3”. O campo 1 (14753), que não tem parte decimal, está correto.

Com o seguinte arquivo, [TaxDataInvalid.json], em que um coeficiente é escrito como string:

1
2
3
4
[
  { "limit": 4962, "coeffR": 0, "coeffN": 0 },
  { "limit": 8382, "coeffR": "0,068", "coeffN": 291.09 }
]
1
2
3
> dotnet run -- TaxDataInvalid.json
Tax brackets read from [TaxDataInvalid.json]
The following error occurred: [Code=Json, Message=The file TaxDataInvalid.json is incorrect: The JSON value could not be converted to System.Decimal. Path: $[1].coeffR | LineNumber: 2 | BytePositionInLine: 36., original exception: JsonException]

A mensagem de [JsonException] especifica o local exato do erro: a propriedade [coeffR] do segundo elemento do array ([$[1].coeffR]), [LineNumber: 2] — isto é, a terceira linha do documento, já que [System.Text.Json] numera as linhas a partir de 0.

5.10. Conclusão

Este capítulo apresentou as classes do .NET usadas em quase todos os programas:

  • as strings imutáveis ([string]) e as strings mutáveis ([StringBuilder]) para construí-las aos poucos; interpolação com larguras e formatos, strings brutas; visões ([ReadOnlySpan<char>]) para código crítico;
  • os arrays e a classe [Array];
  • as coleções genéricas [List<T>], [Dictionary<TKey,TValue>], [HashSet<T>], [Queue<T>], [Stack<T>], [PriorityQueue<TElement,TPriority>] e suas interfaces somente leitura; as coleções não genéricas [ArrayList] e [Hashtable] estão obsoletas;
  • o LINQ, suas sequências [IEnumerable<T>], seus iteradores e sua execução adiada;
  • os arquivos de texto ([StreamReader], [StreamWriter], [File]), os arquivos binários ([BinaryWriter], [BinaryReader]) e a serialização JSON, que substitui a serialização binária de [BinaryFormatter], removida do .NET;
  • as expressões regulares, de preferência geradas em tempo de compilação e sempre protegidas por um tempo limite ao processar dados externos.

O aplicativo de exemplo agora lê seus dados de um arquivo de texto ou JSON. O capítulo seguinte o reorganiza em camadas: a leitura dos dados, o cálculo do imposto e a interação com o usuário passarão a ser componentes independentes.